How p0luz/ombre-brain works
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: bucket_manager.py Bucket manager · server.py MCP tools · _common.py Shared tool logic · dashboard.py Web dashboard
Components 24
Interfaces
- MCP tools
src/server.py - Web dashboard
src/web/dashboard.py - Tool runtime
src/tools/_runtime.py - Shared tool logic
src/tools/_common.py - Remote access
src/web/oauth.py
Memory lifecycle
- Bucket manager
src/bucket_manager.py - Decay engine
src/decay_engine.py - Memory operations
src/tools/hold/core.py - Trace operations
src/tools/trace/core.py - Dream digestion
src/tools/dream/output.py
Recall and indexing
- Breath and search
src/tools/breath/search.py - Retrieval engine
src/ombrebrain/retrieval/engine.py - BM25 index
src/bm25_index.py - Embedding engine
src/embedding_engine.py
Persistence and recovery
- Markdown vault
src/bucket_manager.py - Source evidence
src/ombrebrain/storage/source_store.py - Backup and import
src/migrate_engine.py - Embedding outbox
src/ombrebrain/storage/embedding_outbox.py - GitHub sync
src/github_sync.py
Optional capabilities
- You and them
src/ombrebrain/them/service.py - Letters and plans
src/tools/plan/core.py
Other components
- MCP client
- Dashboard user
- Embedding provider
Connections 25
- MCP client → MCP tools: calls tools
README.md - Dashboard user → Web dashboard: manages memory
README.md - MCP tools → Tool runtime: dispatches
src/tools/_runtime.py - Tool runtime → Shared tool logic: uses helpers
src/tools/_runtime.py - Shared tool logic → Bucket manager: reads and writes
src/tools/_common.py - Memory operations → Shared tool logic: uses helpers
src/tools/_common.py - Trace operations → Shared tool logic: uses helpers
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
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
src/bucket_manager.py - Bucket manager → Source evidence: stores 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
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
README.md - MCP tools → Letters and plans: provides tools
README.md