xy-claude/brain-core

How xy-claude/brain-core works

brain-core is a local, persistent memory system for Claude Code agents. The workflow starts with scaffolding an agent folder, then Claude Code invokes a five-tool MCP server: sessions load and close context, memories are written to the markdown vault and indexed for recall, and distillation captures source material for later curation. SQLite provides the local index and event state; Hindsight is an optional vector-memory integration. Scheduled daily and weekly jobs maintain briefs, archives, and mental models. The graph emphasizes README-described capabilities; some implementation links are omitted where excerpts do not establish calls.

Main entry points: agent.py Agent API · main.py CLI · vault.py Markdown vault · remember.py Memory writes

Components 20

Agent interfaces

CLI src/brain_core/cli/main.py
Agent scaffolding src/brain_core/cli/init.py
MCP tools src/brain_core/mcp/server.py
Agent API src/brain_core/agent.py

Memory workflow

Session lifecycle src/brain_core/session.py
Memory writes src/brain_core/remember.py
Memory recall src/brain_core/recall.py
Source distillation src/brain_core/distill.py
Transcript capture src/brain_core/capture.py

Memory stores

Markdown vault src/brain_core/stores/vault.py
FTS search index src/brain_core/stores/index.py
Transcript store src/brain_core/stores/transcripts.py
SQLite database src/brain_core/storage/db.py
Relations store src/brain_core/stores/graph.py

Maintenance and insight

Scheduled jobs src/brain_core/cron.py
Health status src/brain_core/status.py
Trait evidence src/brain_core/traits.py

Other components

Agent owner
Claude Code
Hindsight service

Connections 28

Agent owner → CLI: initializes agent README.md
CLI → Agent scaffolding: scaffolds folder src/brain_core/cli/main.py
Claude Code → MCP tools: invokes tools README.md
MCP tools → Agent API: dispatches tools src/brain_core/mcp/server.py
Agent API → Session lifecycle: delegates session src/brain_core/agent.py
Agent API → Memory writes: delegates writes src/brain_core/agent.py
Agent API → Memory recall: delegates search src/brain_core/agent.py
Agent API → Source distillation: delegates capture src/brain_core/agent.py
Agent API → Health status: delegates health src/brain_core/agent.py
Memory writes → Markdown vault: writes first README.md
Memory writes → Relations store: writes relations src/brain_core/remember.py
Memory writes → Hindsight service: retains memory README.md
Memory recall → FTS search index: searches records src/brain_core/recall.py
Memory recall → Hindsight service: searches optionally README.md
Markdown vault → FTS search index: indexes records README.md
FTS search index → SQLite database: stores FTS rows src/brain_core/stores/index.py
Transcript store → SQLite database: indexes transcripts src/brain_core/stores/transcripts.py
Transcript capture → Agent API: records transcript src/brain_core/capture.py
Source distillation → Markdown vault: saves raw source src/brain_core/distill.py
Session lifecycle → Markdown vault: reads and writes context src/brain_core/session.py
Session lifecycle → Hindsight service: drains queue src/brain_core/session.py
Scheduled jobs → Markdown vault: updates briefs and archives src/brain_core/cron.py
Scheduled jobs → Hindsight service: backs up and refreshes src/brain_core/cron.py
Health status → Trait evidence: computes evidence src/brain_core/status.py
Scheduled jobs → Trait evidence: reports traits src/brain_core/cron.py
CLI → Scheduled jobs: runs jobs src/brain_core/cli/main.py
CLI → Transcript capture: runs capture hook src/brain_core/cli/main.py
CLI → Health status: reports health src/brain_core/cli/main.py

More Python diagrams: rightnow-ai/autokernel · vimalloc/flask-jwt-extended · bayramannakov/claude-reflect · realpython/flask-boilerplate · twilio/stashboard

Drawn by GitDiagram on November 12, 2026 from the repository's file tree, README and source files. Read as Markdown ·