# oceanbase/powercontext architecture

> Architecture diagram of the GitHub repository oceanbase/powercontext, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oceanbase/powercontext
- Repository: https://github.com/oceanbase/powercontext

## Overview

PowerContext is a durable context service for AI work: agents and people store evidence and revisioned artifacts in Scopes, then prepare bounded context or hand work to another session or person. The principal path runs through a client or host integration to the HTTP server and builtin runtime, which operates on scoped artifacts and persistence; results return as prepared context or inspectable history. Other documented capabilities include candidate review, skill export/publication, dashboard access, and desktop management. Some internal links below are documented or indexed but not visible in the sampled implementation excerpts.

Main entry points: [`src/powercontext/builtin/runtime/application.py`](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/runtime/application.py) (Builtin runtime), [`src/powercontext/builtin/artifacts/skill/distribution.py`](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/artifacts/skill/distribution.py) (Skill distribution), [`src/powercontext/builtin/artifacts/skill/models.py`](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/artifacts/skill/models.py) (Skill lifecycle), [`src/powercontext/server/app.py`](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/server/app.py) (HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_client["Python client<br/>[ingestion.py]"]
  node_server["HTTP server<br/>[app.py]"]
  node_dashboard["Dashboard<br/>[routes.py]"]
  node_desktop["Desktop manager<br/>[App.tsx]"]
end

subgraph group_service["Service runtime"]
  node_runtime["Builtin runtime<br/>[application.py]"]
  node_scope["Scoped services<br/>[application.py]"]
  node_code["Code context<br/>[service.py]"]
end

subgraph group_artifacts["Artifact lifecycle"]
  node_memory["Memory lifecycle<br/>[models.py]"]
  node_artifact_search["Artifact search<br/>[search.py]"]
  node_handoff["Handoff records"]
  node_experience["Experience review"]
  node_skill["Skill lifecycle<br/>[models.py]"]
  node_skill_package["Skill packages<br/>[package.py]"]
  node_skill_projection["Skill projection<br/>[projection.py]"]
  node_skill_publication["Skill publication<br/>[publication.py]"]
  node_skill_distribution["Skill distribution<br/>[distribution.py]"]
end

subgraph group_storage["Persistence"]
  node_artifact_store[("Artifact repository<br/>[artifacts.py]")]
  node_database[("Database<br/>[database.py]")]
  node_skill_governance[("Skill governance")]
  node_skill_targets[("Skill targets")]
  node_skill_publications[("Publication records")]
end

subgraph group_extensions["Integrations"]
  node_hermes["Hermes integration<br/>[client.py]"]
end

node_agent(("Agent or person"))

node_agent -->|"uses"| node_client
node_client -->|"requests"| node_server
node_server -->|"dispatches"| node_runtime
node_runtime -->|"selects scope"| node_scope
node_runtime -->|"queries"| node_code
node_runtime -->|"prepares recall"| node_memory
node_runtime -->|"searches"| node_artifact_search
node_runtime -->|"records work"| node_handoff
node_runtime -->|"generates candidates"| node_experience
node_runtime -->|"manages"| node_skill
node_skill -->|"packages"| node_skill_package
node_skill -->|"projects"| node_skill_projection
node_skill -->|"publishes"| node_skill_publication
node_skill_publication -->|"distributes"| node_skill_distribution
node_skill_distribution -->|"reads targets"| node_skill_targets
node_skill_distribution -->|"checks lifecycle"| node_skill_governance
node_skill_distribution -->|"records publication"| node_skill_publications
node_skill_distribution -->|"loads artifacts"| node_artifact_store
node_runtime -.->|"persists artifacts"| node_artifact_store
node_artifact_store -.->|"stores in"| node_database
node_agent -->|"inspects history"| node_dashboard
node_agent -.->|"manages service"| node_desktop
node_hermes -->|"calls HTTP"| node_server

click node_client "https://github.com/oceanbase/powercontext/blob/master/src/powercontext/client/ingestion.py"
click node_server "https://github.com/oceanbase/powercontext/blob/master/src/powercontext/server/app.py"
click node_dashboard "https://github.com/oceanbase/powercontext/blob/master/src/powercontext/server/dashboard/routes.py"
click node_desktop "https://github.com/oceanbase/powercontext/blob/master/desktop/ui/src/app/App.tsx"
click node_runtime "https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/runtime/application.py"
click node_scope "https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/scope/application.py"
click node_code "https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/code/service.py"
click node_memory "https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/artifacts/atomic_memory/models.py"
click node_artifact_search "https://github.com/oceanbase/powercontext/blob/master/src/powercontext/artifacts/search.py"
click node_handoff "https://github.com/oceanbase/powercontext/tree/master/src/powercontext/builtin/artifacts/handoff"
click node_experience "https://github.com/oceanbase/powercontext/tree/master/src/powercontext/builtin/artifacts/experience"
click node_skill "https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/artifacts/skill/models.py"
click node_skill_package "https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/artifacts/skill/package.py"
click node_skill_projection "https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/artifacts/skill/projection.py"
click node_skill_publication "https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/artifacts/skill/publication.py"
click node_skill_distribution "https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/artifacts/skill/distribution.py"
click node_artifact_store "https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/persistence/artifacts.py"
click node_database "https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/persistence/database.py"
click node_skill_governance "https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/persistence/artifact_governance.py"
click node_skill_targets "https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/persistence/agent_skill_targets.py"
click node_skill_publications "https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/persistence/skill_publications.py"
click node_hermes "https://github.com/oceanbase/powercontext/blob/master/integrations/hermes/plugins/powercontext/client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_server,node_dashboard,node_desktop toneBlue
class node_runtime,node_scope,node_code toneAmber
class node_memory,node_artifact_search,node_handoff,node_experience,node_skill,node_skill_package,node_skill_projection,node_skill_publication,node_skill_distribution toneMint
class node_artifact_store,node_database,node_skill_governance,node_skill_targets,node_skill_publications toneRose
class node_hermes,node_agent toneIndigo
```

## Components

### User interfaces

- [Python client](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/client/ingestion.py): `src/powercontext/client/ingestion.py`
- [HTTP server](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/server/app.py): `src/powercontext/server/app.py`
- [Dashboard](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/server/dashboard/routes.py): `src/powercontext/server/dashboard/routes.py`
- [Desktop manager](https://github.com/oceanbase/powercontext/blob/master/desktop/ui/src/app/App.tsx): `desktop/ui/src/app/App.tsx`

### Service runtime

- [Builtin runtime](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/runtime/application.py): `src/powercontext/builtin/runtime/application.py`
- [Scoped services](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/scope/application.py): `src/powercontext/builtin/scope/application.py`
- [Code context](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/code/service.py): `src/powercontext/builtin/code/service.py`

### Artifact lifecycle

- [Memory lifecycle](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/artifacts/atomic_memory/models.py): `src/powercontext/builtin/artifacts/atomic_memory/models.py`
- [Artifact search](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/artifacts/search.py): `src/powercontext/artifacts/search.py`
- [Handoff records](https://github.com/oceanbase/powercontext/tree/master/src/powercontext/builtin/artifacts/handoff): `src/powercontext/builtin/artifacts/handoff`
- [Experience review](https://github.com/oceanbase/powercontext/tree/master/src/powercontext/builtin/artifacts/experience): `src/powercontext/builtin/artifacts/experience`
- [Skill lifecycle](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/artifacts/skill/models.py): `src/powercontext/builtin/artifacts/skill/models.py`
- [Skill packages](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/artifacts/skill/package.py): `src/powercontext/builtin/artifacts/skill/package.py`
- [Skill projection](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/artifacts/skill/projection.py): `src/powercontext/builtin/artifacts/skill/projection.py`
- [Skill publication](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/artifacts/skill/publication.py): `src/powercontext/builtin/artifacts/skill/publication.py`
- [Skill distribution](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/artifacts/skill/distribution.py): `src/powercontext/builtin/artifacts/skill/distribution.py`

### Persistence

- [Artifact repository](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/persistence/artifacts.py): `src/powercontext/builtin/persistence/artifacts.py`
- [Database](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/persistence/database.py): `src/powercontext/builtin/persistence/database.py`
- [Skill governance](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/persistence/artifact_governance.py): `src/powercontext/builtin/persistence/artifact_governance.py`
- [Skill targets](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/persistence/agent_skill_targets.py): `src/powercontext/builtin/persistence/agent_skill_targets.py`
- [Publication records](https://github.com/oceanbase/powercontext/blob/master/src/powercontext/builtin/persistence/skill_publications.py): `src/powercontext/builtin/persistence/skill_publications.py`

### Integrations

- [Hermes integration](https://github.com/oceanbase/powercontext/blob/master/integrations/hermes/plugins/powercontext/client.py): `integrations/hermes/plugins/powercontext/client.py`

### Other components

- **Agent or person**

## Connections

- Agent or person → Python client: uses (evidence: `README.md`)
- Python client → HTTP server: requests (evidence: `README.md`)
- HTTP server → Builtin runtime: dispatches (evidence: `src/powercontext/server/app.py`)
- Builtin runtime → Scoped services: selects scope (evidence: `src/powercontext/builtin/runtime/application.py`)
- Builtin runtime → Code context: queries (evidence: `src/powercontext/builtin/runtime/application.py`)
- Builtin runtime → Memory lifecycle: prepares recall (evidence: `src/powercontext/builtin/runtime/application.py`)
- Builtin runtime → Artifact search: searches (evidence: `src/powercontext/builtin/runtime/application.py`)
- Builtin runtime → Handoff records: records work (evidence: `README.md`)
- Builtin runtime → Experience review: generates candidates (evidence: `README.md`)
- Builtin runtime → Skill lifecycle: manages (evidence: `src/powercontext/builtin/runtime/application.py`)
- Skill lifecycle → Skill packages: packages (evidence: `src/powercontext/builtin/artifacts/skill/__init__.py`)
- Skill lifecycle → Skill projection: projects
- Skill lifecycle → Skill publication: publishes (evidence: `src/powercontext/builtin/artifacts/skill/publication.py`)
- Skill publication → Skill distribution: distributes (evidence: `src/powercontext/builtin/artifacts/skill/distribution.py`)
- Skill distribution → Skill targets: reads targets (evidence: `src/powercontext/builtin/artifacts/skill/distribution.py`)
- Skill distribution → Skill governance: checks lifecycle (evidence: `src/powercontext/builtin/artifacts/skill/distribution.py`)
- Skill distribution → Publication records: records publication (evidence: `src/powercontext/builtin/artifacts/skill/distribution.py`)
- Skill distribution → Artifact repository: loads artifacts (evidence: `src/powercontext/builtin/artifacts/skill/distribution.py`)
- Builtin runtime → Artifact repository: persists artifacts
- Artifact repository → Database: stores in
- Agent or person → Dashboard: inspects history (evidence: `README.md`)
- Agent or person → Desktop manager: manages service
- Hermes integration → HTTP server: calls HTTP (evidence: `integrations/hermes/plugins/powercontext/client.py`)