# p0luz/ombre-brain architecture

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

- Interactive diagram: https://gitdiagram.com/p0luz/ombre-brain
- Repository: https://github.com/p0luz/ombre-brain

## Overview

Ombre Brain is a persistent emotional-memory service for Claude and other MCP clients. Its main loop accepts memory-tool requests, stores and updates Obsidian-compatible Markdown buckets, then retrieves and surfaces memories through keyword/BM25 and vector search. Separate stages handle decay, archiving, and explicit memory maintenance. The Dashboard adds administration, import/export, and remote access; optional You/them profiles and Letters provide distinct relationship-oriented capabilities. Some subsystem links below are documented in the README rather than verified from sampled implementation, so unsampled details are omitted.

Main entry points: [`src/bucket_manager.py`](https://github.com/p0luz/ombre-brain/blob/main/src/bucket_manager.py) (Bucket manager), [`src/server.py`](https://github.com/p0luz/ombre-brain/blob/main/src/server.py) (MCP tools), [`src/tools/_common.py`](https://github.com/p0luz/ombre-brain/blob/main/src/tools/_common.py) (Shared tool logic), [`src/web/dashboard.py`](https://github.com/p0luz/ombre-brain/blob/main/src/web/dashboard.py) (Web dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_mcp_tools["MCP tools<br/>[server.py]"]
  node_web_dashboard["Web dashboard<br/>[dashboard.py]"]
  node_tool_runtime["Tool runtime<br/>[_runtime.py]"]
  node_tool_shared["Shared tool logic<br/>[_common.py]"]
  node_oauth_tunnel["Remote access<br/>[oauth.py]"]
end

subgraph group_memory["Memory lifecycle"]
  node_bucket_manager["Bucket manager<br/>[bucket_manager.py]"]
  node_decay["Decay engine<br/>[decay_engine.py]"]
  node_memory_tools["Memory operations<br/>[core.py]"]
  node_trace_tools["Trace operations<br/>[core.py]"]
  node_dream_tools["Dream digestion<br/>[output.py]"]
end

subgraph group_retrieval["Recall and indexing"]
  node_recall_tools["Breath and search<br/>[search.py]"]
  node_retrieval_engine["Retrieval engine<br/>[engine.py]"]
  node_bm25["BM25 index<br/>[bm25_index.py]"]
  node_embedding["Embedding engine"]
end

subgraph group_state["Persistence and recovery"]
  node_markdown_vault[("Markdown vault<br/>[bucket_manager.py]")]
  node_source_evidence[("Source evidence<br/>[source_store.py]")]
  node_backup_import["Backup and import<br/>[migrate_engine.py]"]
  node_embedding_outbox["Embedding outbox"]
  node_github_sync["GitHub sync<br/>[github_sync.py]"]
end

subgraph group_extensions["Optional capabilities"]
  node_you_them["You and them<br/>[service.py]"]
  node_letters_plans["Letters and plans<br/>[core.py]"]
end

node_mcp_client(("MCP client"))
node_dashboard_user(("Dashboard user"))
node_external_embedding(("Embedding provider"))

node_mcp_client -->|"calls tools"| node_mcp_tools
node_dashboard_user -->|"manages memory"| node_web_dashboard
node_mcp_tools -->|"dispatches"| node_tool_runtime
node_tool_runtime -->|"uses helpers"| node_tool_shared
node_tool_shared -->|"reads and writes"| node_bucket_manager
node_memory_tools -->|"uses helpers"| node_tool_shared
node_trace_tools -->|"uses helpers"| node_tool_shared
node_memory_tools -.->|"creates memories"| node_bucket_manager
node_trace_tools -.->|"updates memories"| node_bucket_manager
node_dream_tools -.->|"digests memories"| node_decay
node_recall_tools -->|"retrieves memories"| node_retrieval_engine
node_retrieval_engine -.->|"combines keyword scores"| node_bm25
node_retrieval_engine -.->|"requests vectors"| node_embedding
node_recall_tools -.->|"reads buckets"| node_bucket_manager
node_bucket_manager -->|"reads and writes"| node_markdown_vault
node_bucket_manager -.->|"stores evidence"| node_source_evidence
node_embedding -.->|"requests embeddings"| node_external_embedding
node_bucket_manager -.->|"queues indexing"| node_embedding_outbox
node_embedding_outbox -.->|"generates vectors"| node_embedding
node_web_dashboard -.->|"imports backups"| node_backup_import
node_backup_import -->|"merges buckets"| node_bucket_manager
node_web_dashboard -.->|"configures remote access"| node_oauth_tunnel
node_bucket_manager -.->|"syncs vault"| node_github_sync
node_mcp_tools -.->|"exposes when enabled"| node_you_them
node_mcp_tools -->|"provides tools"| node_letters_plans

click node_mcp_tools "https://github.com/p0luz/ombre-brain/blob/main/src/server.py"
click node_web_dashboard "https://github.com/p0luz/ombre-brain/blob/main/src/web/dashboard.py"
click node_tool_runtime "https://github.com/p0luz/ombre-brain/blob/main/src/tools/_runtime.py"
click node_tool_shared "https://github.com/p0luz/ombre-brain/blob/main/src/tools/_common.py"
click node_bucket_manager "https://github.com/p0luz/ombre-brain/blob/main/src/bucket_manager.py"
click node_decay "https://github.com/p0luz/ombre-brain/blob/main/src/decay_engine.py"
click node_memory_tools "https://github.com/p0luz/ombre-brain/blob/main/src/tools/hold/core.py"
click node_trace_tools "https://github.com/p0luz/ombre-brain/blob/main/src/tools/trace/core.py"
click node_dream_tools "https://github.com/p0luz/ombre-brain/blob/main/src/tools/dream/output.py"
click node_recall_tools "https://github.com/p0luz/ombre-brain/blob/main/src/tools/breath/search.py"
click node_retrieval_engine "https://github.com/p0luz/ombre-brain/blob/main/src/ombrebrain/retrieval/engine.py"
click node_bm25 "https://github.com/p0luz/ombre-brain/blob/main/src/bm25_index.py"
click node_embedding "https://github.com/p0luz/ombre-brain/blob/main/src/embedding_engine.py"
click node_markdown_vault "https://github.com/p0luz/ombre-brain/blob/main/src/bucket_manager.py"
click node_source_evidence "https://github.com/p0luz/ombre-brain/blob/main/src/ombrebrain/storage/source_store.py"
click node_backup_import "https://github.com/p0luz/ombre-brain/blob/main/src/migrate_engine.py"
click node_embedding_outbox "https://github.com/p0luz/ombre-brain/blob/main/src/ombrebrain/storage/embedding_outbox.py"
click node_oauth_tunnel "https://github.com/p0luz/ombre-brain/blob/main/src/web/oauth.py"
click node_github_sync "https://github.com/p0luz/ombre-brain/blob/main/src/github_sync.py"
click node_you_them "https://github.com/p0luz/ombre-brain/blob/main/src/ombrebrain/them/service.py"
click node_letters_plans "https://github.com/p0luz/ombre-brain/blob/main/src/tools/plan/core.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_mcp_tools,node_web_dashboard,node_tool_runtime,node_tool_shared,node_oauth_tunnel,node_mcp_client,node_dashboard_user toneBlue
class node_bucket_manager,node_decay,node_memory_tools,node_trace_tools,node_dream_tools toneAmber
class node_recall_tools,node_retrieval_engine,node_bm25,node_embedding toneMint
class node_markdown_vault,node_source_evidence,node_backup_import,node_embedding_outbox,node_github_sync toneRose
class node_you_them,node_letters_plans,node_external_embedding toneIndigo
```

## Components

### Interfaces

- [MCP tools](https://github.com/p0luz/ombre-brain/blob/main/src/server.py): `src/server.py`
- [Web dashboard](https://github.com/p0luz/ombre-brain/blob/main/src/web/dashboard.py): `src/web/dashboard.py`
- [Tool runtime](https://github.com/p0luz/ombre-brain/blob/main/src/tools/_runtime.py): `src/tools/_runtime.py`
- [Shared tool logic](https://github.com/p0luz/ombre-brain/blob/main/src/tools/_common.py): `src/tools/_common.py`
- [Remote access](https://github.com/p0luz/ombre-brain/blob/main/src/web/oauth.py): `src/web/oauth.py`

### Memory lifecycle

- [Bucket manager](https://github.com/p0luz/ombre-brain/blob/main/src/bucket_manager.py): `src/bucket_manager.py`
- [Decay engine](https://github.com/p0luz/ombre-brain/blob/main/src/decay_engine.py): `src/decay_engine.py`
- [Memory operations](https://github.com/p0luz/ombre-brain/blob/main/src/tools/hold/core.py): `src/tools/hold/core.py`
- [Trace operations](https://github.com/p0luz/ombre-brain/blob/main/src/tools/trace/core.py): `src/tools/trace/core.py`
- [Dream digestion](https://github.com/p0luz/ombre-brain/blob/main/src/tools/dream/output.py): `src/tools/dream/output.py`

### Recall and indexing

- [Breath and search](https://github.com/p0luz/ombre-brain/blob/main/src/tools/breath/search.py): `src/tools/breath/search.py`
- [Retrieval engine](https://github.com/p0luz/ombre-brain/blob/main/src/ombrebrain/retrieval/engine.py): `src/ombrebrain/retrieval/engine.py`
- [BM25 index](https://github.com/p0luz/ombre-brain/blob/main/src/bm25_index.py): `src/bm25_index.py`
- [Embedding engine](https://github.com/p0luz/ombre-brain/blob/main/src/embedding_engine.py): `src/embedding_engine.py`

### Persistence and recovery

- [Markdown vault](https://github.com/p0luz/ombre-brain/blob/main/src/bucket_manager.py): `src/bucket_manager.py`
- [Source evidence](https://github.com/p0luz/ombre-brain/blob/main/src/ombrebrain/storage/source_store.py): `src/ombrebrain/storage/source_store.py`
- [Backup and import](https://github.com/p0luz/ombre-brain/blob/main/src/migrate_engine.py): `src/migrate_engine.py`
- [Embedding outbox](https://github.com/p0luz/ombre-brain/blob/main/src/ombrebrain/storage/embedding_outbox.py): `src/ombrebrain/storage/embedding_outbox.py`
- [GitHub sync](https://github.com/p0luz/ombre-brain/blob/main/src/github_sync.py): `src/github_sync.py`

### Optional capabilities

- [You and them](https://github.com/p0luz/ombre-brain/blob/main/src/ombrebrain/them/service.py): `src/ombrebrain/them/service.py`
- [Letters and plans](https://github.com/p0luz/ombre-brain/blob/main/src/tools/plan/core.py): `src/tools/plan/core.py`

### Other components

- **MCP client**
- **Dashboard user**
- **Embedding provider**

## Connections

- MCP client → MCP tools: calls tools (evidence: `README.md`)
- Dashboard user → Web dashboard: manages memory (evidence: `README.md`)
- MCP tools → Tool runtime: dispatches (evidence: `src/tools/_runtime.py`)
- Tool runtime → Shared tool logic: uses helpers (evidence: `src/tools/_runtime.py`)
- Shared tool logic → Bucket manager: reads and writes (evidence: `src/tools/_common.py`)
- Memory operations → Shared tool logic: uses helpers (evidence: `src/tools/_common.py`)
- Trace operations → Shared tool logic: uses helpers (evidence: `src/tools/trace/core.py`)
- Memory operations → Bucket manager: creates memories
- Trace operations → Bucket manager: updates memories
- Dream digestion → Decay engine: digests memories
- Breath and search → Retrieval engine: retrieves memories (evidence: `README.md`)
- Retrieval engine → BM25 index: combines keyword scores
- Retrieval engine → Embedding engine: requests vectors
- Breath and search → Bucket manager: reads buckets
- Bucket manager → Markdown vault: reads and writes (evidence: `src/bucket_manager.py`)
- Bucket manager → Source evidence: stores evidence (evidence: `src/bucket_manager.py`)
- Embedding engine → Embedding provider: requests embeddings
- Bucket manager → Embedding outbox: queues indexing
- Embedding outbox → Embedding engine: generates vectors
- Web dashboard → Backup and import: imports backups
- Backup and import → Bucket manager: merges buckets (evidence: `src/migrate_engine.py`)
- Web dashboard → Remote access: configures remote access
- Bucket manager → GitHub sync: syncs vault
- MCP tools → You and them: exposes when enabled (evidence: `README.md`)
- MCP tools → Letters and plans: provides tools (evidence: `README.md`)
