# sankhya-ai/dhee architecture

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

- Interactive diagram: https://gitdiagram.com/sankhya-ai/dhee
- Repository: https://github.com/sankhya-ai/dhee

## Overview

1. **Overall shape**
   Dhee is a Python-first local memory platform for agents, with a few adjacent packages around it: a Rust acceleration crate (`dhee-accel`), a small pub/sub service (`engram-bus`), a web UI, MCP/server entrypoints, and optional plugins/hooks for agent runtimes. The central design is: capture agent activity locally, turn it into structured memory, store it durably, then compile the smallest useful context back into the next interaction.

2. **Primary control surfaces**
   The main ways into the system are the CLI (`dhee/cli*.py`), MCP server/tools (`dhee/mcp_server.py`, `dhee/mcp_slim.py`), HTTP/runtime servers (`dhee/runtime_daemon.py`, `dhee/ui/server.py`, `dhee/agent_runtime/server.py`), and provider-specific adapters. These are the boundaries where external agents, shells, or UIs enter the memory system.

3. **Context compilation core**
   The conceptual center is in `dhee/core`, `dhee/context_ir.py`, `dhee/context_kernel.py`, and `dhee/context_state.py`. This layer turns raw events, transcripts, files, and prior sessions into a compact context packet. It includes the story model the README describes: series/season/episode/scene/scene-card, plus intent, policy, belief, conflict, decay, retrieval, and handoff logic.

4. **Memory pipeline**
   The memory subsystem in `dhee/memory` is the main ingest/search/write path. It has admission, scoping, quality, reranking, episodic memory, search/write pipelines, and orchestration. The data flow is: incoming events and evidence are admitted, scored, possibly enriched or distilled, then written as durable items and later retrieved as scene cards or context packs.

5. **Persistence and storage**
   Durable state is backed primarily by SQLite through `dhee/db`, with separate modules for common tables, analytics, artifacts, and domain-specific storage. Vector search is abstracted through `dhee/vector_stores` with implementations such as SQLite vectors and `zvec`; the README’s production stack points to `dhee-accel` for accelerated vector/score operations. Secrets and repo-scoped state are isolated through `dhee/secret_store.py`, workspace helpers, and local `.dhee/...` storage.

6. **Agent runtime layer**
   `dhee/agent_runtime`, `dhee/runtime.py`, `dhee/runtime_io.py`, and `dhee/contract_runtime.py` form the runtime boundary that wraps an agent session. This layer handles before-run context injection, tool exposure, event capture, checkpointing, and policy/proof checks. It is where Dhee can behave as a sidecar memory runtime rather than a standalone app.

7. **Provider and harness integrations**
   Provider adapters live in `dhee/providers`, `dhee/llms`, `dhee/embeddings`, and `dhee/profiles`. The repo supports multiple external model vendors and embedding backends, including OpenAI, Gemini, Nvidia, Ollama, Qwen, Anthropic, and ElevenLabs. For execution environments, `dhee/harness` and `dhee/hooks` integrate with agent shells such as Claude Code and Codex, capturing transcripts and tool calls as memory events.

8. **MCP and tool surface**
   Dhee exposes a tool-oriented interface through MCP and related routers. The `dhee/router` package contains digests, policy, intent handling, pre-tool gating, and quality reporting, while `dhee/mcp_registry.py`, `dhee/mcp_server.py`, and `dhee/cli_mcp.py` publish the actual tool surface. This is the boundary that lets third-party MCP clients query or mutate memory without knowing the internal storage model.

9. **UI and operator views**
   The web UI under `dhee/ui/web` is a React/Vite frontend backed by `dhee/ui/server.py` and the Python backend APIs. Its views are organized around operational concepts like memory, router, tasks, workspace, conflict, evolution, and canvas. Architecturally, it is an निरीक्षण/control plane: it visualizes memory state, scene graphs, routing decisions, and workspace-level entities rather than serving as the primary execution engine.

10. **Repo intelligence and graph analysis**
   `dhee/repo_intelligence.py`, `dhee/repo_link.py`, `dhee/graph_proof_bundle.py`, `dhee/graph_projection_hardening.py`, and related `dhee/core/graph.py` modules form the “repo brain.” This subsystem maps files, symbols, routes, tests, and failure evidence into a graph-backed impact model so the agent can answer “if I touch this, what breaks?” It is a separate analysis boundary from generic memory: it is git/repo-scoped and optimized for change impact and proof.

11. **Scene, temporal, and world-memory subsystems**
   Several packages model time and narrative state: `dhee/temporal_*`, `dhee/world_memory`, `dhee/core/scene.py`, `episode.py`, `session_tracker.py`, and `handoff_snapshot.py`. These components preserve continuity across sessions by tracking scenes, causal graphs, session graphs, and checkpoint/handoff artifacts. They are the bridge between short-lived agent runs and long-lived memory.

12. **Shared task and multi-agent coordination**
   `dhee/engram-bus`, `dhee/core/workspace_line_bus.py`, `dhee/core/shared_tasks.py`, and `dhee/core/task_state.py` provide coordination primitives for shared workspace state and task progress. This is the cross-agent boundary: memory is not only per-session, but can be published, replayed, or synchronized across workers and tools.

13. **Evaluation, training, and quality gates**
   The `dhee/training`, `dhee/mini`, `dhee/benchmarks`, `benchmarks/longmemeval`, and the extensive test suite act as the quality subsystem. They validate retrieval quality, memory admission, routing, runtime behavior, and provider integrations. This matters architecturally because Dhee treats memory quality as an enforced contract, not just a best-effort cache.

14. **Packaging and deployment model**
   The repo is built as a distributable Python package with optional extras, a Docker image, and CLI install flows. The Rust crate is an internal performance boundary; the UI is prebuilt and served alongside Python services; and the optional plugin/package directories show that Dhee can be embedded into existing agent ecosystems rather than requiring a single monolithic deployment.

Main entry points: [`dhee/memory/main.py`](https://github.com/sankhya-ai/dhee/blob/main/dhee/memory/main.py) (Memory core), [`dhee/context_kernel.py`](https://github.com/sankhya-ai/dhee/blob/main/dhee/context_kernel.py) (Kernel), [`dhee/db/sqlite.py`](https://github.com/sankhya-ai/dhee/blob/main/dhee/db/sqlite.py) (SQLite DB), [`dhee/memory/search_pipeline.py`](https://github.com/sankhya-ai/dhee/blob/main/dhee/memory/search_pipeline.py) (Search/write)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_entry["Entry points"]
  node_cli["CLI<br/>command entry<br/>[cli.py]"]
  node_mcp["MCP tools<br/>tool server<br/>[mcp_server.py]"]
  node_runtime_daemon["Runtime daemon<br/>service entry<br/>[runtime_daemon.py]"]
end

subgraph group_group_context["Context core"]
  node_context_ir["Context IR<br/>context model<br/>[context_ir.py]"]
  node_context_kernel{{"Kernel<br/>context compiler<br/>[context_kernel.py]"}}
  node_context_state["State<br/>[context_state.py]"]
end

subgraph group_group_memory["Memory system"]
  node_memory_main["Memory core<br/>memory pipeline<br/>[main.py]"]
  node_admission{{"Admission<br/>memory gate<br/>[admission.py]"}}
  node_search_write["Search/write<br/>pipeline<br/>[search_pipeline.py]"]
  node_quality_rerank{{"Quality<br/>scoring layer<br/>[quality.py]"}}
end

subgraph group_group_storage["Storage layer"]
  node_db[("SQLite DB<br/>persistence<br/>[sqlite.py]")]
  node_vector_store[("Vector store<br/>similarity index<br/>[base.py]")]
  node_accel{{"Rust accel<br/>native backend<br/>[lib.rs]"}}
end

subgraph group_group_runtime["Runtime boundary"]
  node_runtime_boundary["Agent runtime<br/>session wrapper<br/>[runtime.py]"]
  node_agent_runtime["Agent server<br/>runtime service<br/>[server.py]"]
  node_providers["Providers<br/>llm/embedding adapters<br/>[base.py]"]
end

subgraph group_group_ops["Ops and analysis"]
  node_ui_server["UI server<br/>web backend<br/>[server.py]"]
  node_ui_web["Web UI<br/>operator console<br/>[App.tsx]"]
  node_repo_intel{{"Repo brain<br/>repo analysis"}}
  node_world_memory["World memory<br/>temporal model<br/>[service.py]"]
  node_bus["Engram bus<br/>pubsub service<br/>[server.py]"]
  node_training["Quality loop<br/>evaluation/training<br/>[train.py]"]
  node_plugins["Plugins<br/>integration pack<br/>[README.md]"]
end

node_cli -->|"operate"| node_memory_main
node_cli -->|"expose tools"| node_mcp
node_runtime_daemon -->|"host"| node_runtime_boundary
node_runtime_boundary -->|"compile"| node_context_kernel
node_runtime_boundary -->|"serve"| node_agent_runtime
node_context_kernel -->|"shape"| node_context_ir
node_context_kernel -->|"update"| node_context_state
node_memory_main -->|"ingest"| node_admission
node_memory_main -->|"score"| node_quality_rerank
node_memory_main -->|"retrieve/write"| node_search_write
node_search_write -->|"persist"| node_db
node_search_write -->|"index"| node_vector_store
node_vector_store -->|"accelerate"| node_accel
node_db -.->|"support"| node_vector_store
node_agent_runtime -->|"invoke"| node_providers
node_providers -->|"feed events"| node_memory_main
node_ui_server -->|"serve"| node_ui_web
node_ui_web -->|"inspect"| node_memory_main
node_ui_web -.->|"display"| node_context_state
node_repo_intel -.->|"analyze"| node_context_kernel
node_repo_intel -->|"record"| node_db
node_world_memory -->|"continuity"| node_context_state
node_world_memory -->|"store"| node_db
node_bus -.->|"publish"| node_memory_main
node_plugins -.->|"extend"| node_cli
node_training -->|"evaluate"| node_memory_main
node_training -.->|"verify"| node_repo_intel

click node_cli "https://github.com/sankhya-ai/dhee/blob/main/dhee/cli.py"
click node_mcp "https://github.com/sankhya-ai/dhee/blob/main/dhee/mcp_server.py"
click node_runtime_daemon "https://github.com/sankhya-ai/dhee/blob/main/dhee/runtime_daemon.py"
click node_context_ir "https://github.com/sankhya-ai/dhee/blob/main/dhee/context_ir.py"
click node_context_kernel "https://github.com/sankhya-ai/dhee/blob/main/dhee/context_kernel.py"
click node_context_state "https://github.com/sankhya-ai/dhee/blob/main/dhee/context_state.py"
click node_memory_main "https://github.com/sankhya-ai/dhee/blob/main/dhee/memory/main.py"
click node_admission "https://github.com/sankhya-ai/dhee/blob/main/dhee/memory/admission.py"
click node_search_write "https://github.com/sankhya-ai/dhee/blob/main/dhee/memory/search_pipeline.py"
click node_quality_rerank "https://github.com/sankhya-ai/dhee/blob/main/dhee/memory/quality.py"
click node_db "https://github.com/sankhya-ai/dhee/blob/main/dhee/db/sqlite.py"
click node_vector_store "https://github.com/sankhya-ai/dhee/blob/main/dhee/vector_stores/base.py"
click node_accel "https://github.com/sankhya-ai/dhee/blob/main/dhee-accel/src/lib.rs"
click node_runtime_boundary "https://github.com/sankhya-ai/dhee/blob/main/dhee/runtime.py"
click node_agent_runtime "https://github.com/sankhya-ai/dhee/blob/main/dhee/agent_runtime/server.py"
click node_providers "https://github.com/sankhya-ai/dhee/blob/main/dhee/providers/base.py"
click node_ui_server "https://github.com/sankhya-ai/dhee/blob/main/dhee/ui/server.py"
click node_ui_web "https://github.com/sankhya-ai/dhee/blob/main/dhee/ui/web/src/App.tsx"
click node_repo_intel "https://github.com/sankhya-ai/dhee/blob/main/dhee/repo_intelligence.py"
click node_world_memory "https://github.com/sankhya-ai/dhee/blob/main/dhee/world_memory/service.py"
click node_bus "https://github.com/sankhya-ai/dhee/blob/main/engram-bus/engram_bus/server.py"
click node_training "https://github.com/sankhya-ai/dhee/blob/main/dhee/training/train.py"
click node_plugins "https://github.com/sankhya-ai/dhee/blob/main/plugins/engram-memory/README.md"

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_cli,node_mcp,node_runtime_daemon toneBlue
class node_context_ir,node_context_kernel,node_context_state toneAmber
class node_memory_main,node_admission,node_search_write,node_quality_rerank toneMint
class node_db,node_vector_store,node_accel toneRose
class node_runtime_boundary,node_agent_runtime,node_providers toneIndigo
class node_ui_server,node_ui_web,node_repo_intel,node_world_memory,node_bus,node_training,node_plugins toneTeal
```

## Components

### Entry points

User and machine entry surfaces into the memory system

- [CLI](https://github.com/sankhya-ai/dhee/blob/main/dhee/cli.py): command entry · Primary shell entry for setup, updates, and memory operations · `dhee/cli.py`
- [MCP tools](https://github.com/sankhya-ai/dhee/blob/main/dhee/mcp_server.py): tool server · MCP server and registry for external clients · `dhee/mcp_server.py`
- [Runtime daemon](https://github.com/sankhya-ai/dhee/blob/main/dhee/runtime_daemon.py): service entry · Long-running service entry for local runtime orchestration · `dhee/runtime_daemon.py`

### Context core

Context compilation and session-state machinery

- [Context IR](https://github.com/sankhya-ai/dhee/blob/main/dhee/context_ir.py): context model · Intermediate representation for compact context packets · `dhee/context_ir.py`
- [Kernel](https://github.com/sankhya-ai/dhee/blob/main/dhee/context_kernel.py): context compiler · Core logic that compiles events and evidence into usable context · `dhee/context_kernel.py`
- [State](https://github.com/sankhya-ai/dhee/blob/main/dhee/context_state.py): session state · Mutable context and session state tracked across runs · `dhee/context_state.py`

### Memory system

Ingest, retrieve, score, and write durable memory

- [Memory core](https://github.com/sankhya-ai/dhee/blob/main/dhee/memory/main.py): memory pipeline · Main orchestration for ingest, search, and write flows · `dhee/memory/main.py`
- [Admission](https://github.com/sankhya-ai/dhee/blob/main/dhee/memory/admission.py): memory gate · Filters and scopes incoming evidence before persistence · `dhee/memory/admission.py`
- [Search/write](https://github.com/sankhya-ai/dhee/blob/main/dhee/memory/search_pipeline.py): pipeline · Retrieval and durable write pipelines for memory items · `dhee/memory/search_pipeline.py`
- [Quality](https://github.com/sankhya-ai/dhee/blob/main/dhee/memory/quality.py): scoring layer · Quality checks, reranking, and relevance shaping · `dhee/memory/quality.py`

### Storage layer

Persistence, vector search, and acceleration backends

- [SQLite DB](https://github.com/sankhya-ai/dhee/blob/main/dhee/db/sqlite.py): persistence · Durable relational storage for common, analytics, artifact, and domain data · `dhee/db/sqlite.py`
- [Vector store](https://github.com/sankhya-ai/dhee/blob/main/dhee/vector_stores/base.py): similarity index · Abstracted vector search layer with SQLite and zvec backends · `dhee/vector_stores/base.py`
- [Rust accel](https://github.com/sankhya-ai/dhee/blob/main/dhee-accel/src/lib.rs): native backend · Rust acceleration for scoring, decay, and vector operations · `dhee-accel/src/lib.rs`

### Runtime boundary

Agent session wrapping, tool exposure, and provider integration

- [Agent runtime](https://github.com/sankhya-ai/dhee/blob/main/dhee/runtime.py): session wrapper · Wraps agent sessions with context injection, event capture, and policy checks · `dhee/runtime.py`
- [Agent server](https://github.com/sankhya-ai/dhee/blob/main/dhee/agent_runtime/server.py): runtime service · HTTP/server boundary for agent-runtime workflows and tools · `dhee/agent_runtime/server.py`
- [Providers](https://github.com/sankhya-ai/dhee/blob/main/dhee/providers/base.py): llm/embedding adapters · Model and embedding adapters for multiple external vendors · `dhee/providers/base.py`

### Ops and analysis

UI, repo intelligence, coordination, and evaluation

- [UI server](https://github.com/sankhya-ai/dhee/blob/main/dhee/ui/server.py): web backend · Backend for the operator UI and local web app · `dhee/ui/server.py`
- [Web UI](https://github.com/sankhya-ai/dhee/blob/main/dhee/ui/web/src/App.tsx): operator console · React/Vite frontend for memory, router, workspace, and canvas views · `dhee/ui/web/src/App.tsx`
- [Repo brain](https://github.com/sankhya-ai/dhee/blob/main/dhee/repo_intelligence.py): repo analysis · Repo-scoped impact, graph, and proof analysis for change reasoning · `dhee/repo_intelligence.py`
- [World memory](https://github.com/sankhya-ai/dhee/blob/main/dhee/world_memory/service.py): temporal model · Session graphs, causal graphs, and world-state capture across runs · `dhee/world_memory/service.py`
- [Engram bus](https://github.com/sankhya-ai/dhee/blob/main/engram-bus/engram_bus/server.py): pubsub service · Small pub/sub coordination service for workspace and task signals · `engram-bus/engram_bus/server.py`
- [Quality loop](https://github.com/sankhya-ai/dhee/blob/main/dhee/training/train.py): evaluation/training · Benchmarks, replay gates, and trainer loops that enforce memory quality · `dhee/training/train.py`
- [Plugins](https://github.com/sankhya-ai/dhee/blob/main/plugins/engram-memory/README.md): integration pack · Optional shell/runtime integrations and command packs · `plugins/engram-memory/README.md`

## Connections

- CLI → Memory core: operate · CLI drives memory operations and maintenance
- CLI → MCP tools: expose tools · CLI publishes or reuses MCP-oriented tool entrypoints
- Runtime daemon → Agent runtime: host · Daemon hosts runtime wrapping and session services
- Agent runtime → Kernel: compile · Runtime injects compiled context into sessions
- Agent runtime → Agent server: serve · Runtime boundary is surfaced through the agent server
- Kernel → Context IR: shape · Kernel shapes the intermediate context representation
- Kernel → State: update · Kernel updates session and context state
- Memory core → Admission: ingest · Memory core admits and scopes incoming evidence
- Memory core → Quality: score · Memory core ranks and quality-controls candidates
- Memory core → Search/write: retrieve/write · Memory core routes work into search and write pipelines
- Search/write → SQLite DB: persist · Memory writes durable items into SQLite-backed storage
- Search/write → Vector store: index · Memory indexes and retrieves similarity data through vector stores
- Vector store → Rust accel: accelerate · Vector operations can use native Rust acceleration
- SQLite DB → Vector store: support · Relational state supports vector-backed retrieval and metadata
- Agent server → Providers: invoke · Agent runtime relies on provider adapters for model calls
- Providers → Memory core: feed events · Provider interactions become memory events and transcripts
- UI server → Web UI: serve · Python backend serves the web frontend
- Web UI → Memory core: inspect · UI reads and visualizes memory state and routing outputs
- Web UI → State: display · UI surfaces current context and session state
- Repo brain → Kernel: analyze · Repo intelligence consumes graph-like context and proof artifacts
- Repo brain → SQLite DB: record · Repo intelligence stores scoped analysis and evidence
- World memory → State: continuity · World memory preserves continuity across sessions
- World memory → SQLite DB: store · Temporal graphs and session artifacts are persisted durably
- Engram bus → Memory core: publish · Bus broadcasts workspace and task signals into memory flows
- Plugins → CLI: extend · Plugin packs extend the CLI and shell workflows
- Quality loop → Memory core: evaluate · Benchmarks and replay gates evaluate memory behavior
- Quality loop → Repo brain: verify · Quality loops validate repo-impact and proof workflows