CerebroCortex-RS

A brain-analogous memory system for AI agents — pure Rust, one binary, one SQLite file.

Memories that decay, dreams that consolidate, skills that compete to survive.

Your agent calls remember and recall over MCP. Underneath, nine engines named after the brain regions they imitate run the content through a salience gate, tag it with emotion, link it into an association graph, and embed it for semantic search. Memories strengthen when retrieved and fade when ignored — real ACT-R and FSRS math, not a vector-store metaphor. At night, a dream cycle replays, abstracts, prunes, and recombines. Procedures that keep failing lose their standing to rivals that win.

All of it compiles to a single binary that idles at 23 MB:

Bare binary (no model):   23 MB RSS,  6 threads,  26 ms recall  (FTS5 + spreading activation)
With BGE-small-en-v1.5:  275 MB RSS,  9 threads,  26 ms recall  (cosine ANN, 384-dim)
Binary size:              29 MB stripped arm64 ELF
Cold start:              ~4.4 s  (graph rebuild + model load from cache)

Hot-swapped into a live ApexOS Pi 5 by changing one line in plugins.toml. agentd counted 67 tools and moved on.

✨ What's inside

🚀 Quick start

git clone https://github.com/buckster123/CerebroCortex-RS
cd CerebroCortex-RS
cargo build --release -p cerebro-mcp     # ~2 min on a Pi 5

Wire it into any MCP client (Claude Code shown):

{
  "mcpServers": {
    "cerebro-cortex": {
      "command": "/path/to/target/release/cerebro-mcp",
      "env": { "CEREBRO_DATA_DIR": "/path/to/brain" }
    }
  }
}

First remember downloads the ~128 MB embedding model to the cache; set CEREBRO_EMBED_MODEL="" to skip it and run keyword-only in 23 MB. Then:

remember("The deploy hot-swap needs systemctl stop before cp — text file busy otherwise")
recall("how do I deploy?")   → ranked, activation-weighted, and now slightly stronger

[!TIP]
Migrating from the Python original? Point CEREBRO_DATA_DIR at your existing cerebro.db and start the binary. The Python schema is detected and migrated in one transaction — 504 memories and 9.4k links took under 50 ms in production. The old tables are kept as a fallback through the migration boot, then reaped on the next start.

🗺 Architecture

Four crates, one brain:

crates/
  cerebro/        # the library — engines, activation math, storage, vision, ingestion
  cerebro-mcp/    # MCP-over-stdio binary — the agent-facing drop-in (67 tools)
  cerebro-api/    # axum REST API + the Lucida observatory (127.0.0.1:8765, token auth)
  cerebro-cli/    # clap CLI (cerebro remember / recall / stats / dream ...)
ui-slint/         # cerebro-ui — Lucida's native mirror (Slint; dashboard + Atlas + Thought)

graph TB
    subgraph Frontends
        MCP[cerebro-mcp<br/>67 MCP tools]
        API[cerebro-api<br/>REST + Lucida observatory]
        CLI[cerebro<br/>CLI]
    end

    subgraph Library["cerebro (lib)"]
        Cortex[Cortex<br/>coordinator]
        subgraph Engines["9 engines"]
            TH[Thalamus<br/>gating]
            AM[Amygdala<br/>emotion]
            TE[Temporal<br/>concepts]
            HI[Hippocampus<br/>episodic]
            AS[Association<br/>links]
            CB[Cerebellum<br/>procedural]
            PF[Prefrontal<br/>ranking]
            NC[Neocortex<br/>schemas]
            DR[Dream<br/>8 phases]
        end
        VI[Vision<br/>VLM + CLIP]
        IN[Ingest<br/>7 formats]
        subgraph Storage
            SQ[(SQLite<br/>source of truth)]
            VE[sqlite-vec ANN<br/>+ FTS5 fallback]
            GR[petgraph<br/>in-memory graph]
        end
    end

    MCP --> Cortex
    API --> Cortex
    CLI --> Cortex
    Cortex --> Engines
    Cortex --> VI
    Cortex --> IN
    Cortex --> Storage
    VE --> SQ
    GR --> SQ

SQLite is the single source of truth — the graph and vector index are derived caches, rebuilt on startup and kept fresh across processes via PRAGMA data_version (the MCP daemon and the REST API can share one DB without seeing stale graphs).

🔬 How memory works

Storing

flowchart LR
    Input([content]) --> TH[Thalamus<br/>salience gate<br/>10 B – 64 KiB]
    TH --> AM[Amygdala<br/>valence + arousal]
    AM --> TE[Temporal<br/>concepts + bigrams]
    TE --> SQ[(SQLite)]
    SQ --> GR[graph node]
    SQ --> VE[384-dim embed<br/>vec0 index]

Recalling

flowchart LR
    Query([query]) --> VEC[sqlite-vec<br/>cosine ANN]
    Query -. fallback .-> FTS[FTS5 · BM25]
    VEC --> ACT[Spreading activation<br/>2 hops · 0.6 decay<br/>scope-bounded frontier]
    FTS --> ACT
    ACT --> PF[Prefrontal ranking]
    PF --> R([ranked memories])
    R --> REINF[ACT-R access +<br/>FSRS review recorded]

score = 0.35·vector_sim + 0.30·ACT-R activation + 0.20·FSRS retrievability + 0.15·salience

Every recall is also a rehearsal: the ACT-R access history grows and the FSRS stability rises, so frequently-used memories genuinely resist forgetting while untouched ones drift toward the activation_at_risk list.

ACT-R base-level activation — recency + frequency:

$$B(t) = \ln\left(\sum_k t_k^{-d}\right) + \varepsilon \qquad d = 0.5,\ \varepsilon \sim U(\pm 0.4)$$

Access timestamps are capped at the 50 most recent per memory.

FSRS retrievability — the spaced-repetition forgetting curve:

$$R(t, S) = \left(1 + \frac{t}{9S}\right)^{-1}$$

t = days since last review, S = stability in days. A successful recall grows S and eases difficulty; a lapse halves it.

Spreading activation — Collins & Loftus over the link graph: BFS from the vector-search seeds, max 2 hops, 0.6 decay per hop, 50-node cap. Edge conductance is link_type_weight × effective_weight(now) with a 30-day link half-life. The visibility map is computed only over the reachable frontier (never the whole store), and a node missing from the map is treated as not visible — fail-closed by construction.

All three are verified against the Python reference implementation to within 1e-4 by fixture tests.

Memory types & layers

MemoryType:  Episodic · Semantic · Procedural · Affective · Prospective · Schematic
MemoryLayer: Sensory (minutes) → Working (days) → LongTerm (months) → Cortex (permanent)
Visibility:  Private (agent-only) · Shared (all agents) · Thread (cross-agent dialogue)

🌙 The dream cycle

dream_run executes eight phases; three use an LLM (ANTHROPIC_API_KEY) and skip gracefully without one — the algorithmic phases always run. Pre-phases close stale episodes and sweep retention caps on the lifecycle tables.

flowchart LR
    P1[1 · SWS replay] --> P2[2 · Pattern extraction 🤖]
    P2 --> P3[3 · Schema formation 🤖]
    P3 --> P4[4 · Emotional reprocessing]
    P4 --> P5[5 · Pruning]
    P5 --> P6[6 · REM recombination 🤖]
    P6 --> P7[7 · Variation 🤖]
    P7 --> P8[8 · Skill competition]

🧬 The evolutionary layer

The part where the memory system stops being a filing cabinet. Procedures aren't just stored — they compete:

flowchart LR
    USE[record_procedure_outcome<br/>wins & losses] --> LED[fitness ledger<br/>Wilson lower bound]
    LED --> COMP[skill_competition<br/>same-niche rivals ranked]
    COMP -->|fittest| CH[👑 skill_champion]
    COMP -->|dominated| DK[salience decay<br/>→ prune floor]
    DK --> VAR[variation phase<br/>refine / merge]
    VAR -->|dream_mutated · dream_merged| LED
    CH --> RET[champion-aware retrieval<br/>find_relevant_procedures · cognitive_bootstrap]

• Grading a procedure's outcome is asymmetric: one failure bites harder than one success rewards, so bad habits can't coast on age.
• The competition uses the Wilson lower bound on the win rate — a 2/2 newcomer doesn't dethrone a 40/45 veteran, and novel procedures are exempt until they've been graded.
• Dominated rivals decay toward a prune floor instead of being deleted — they can fight their way back.
• Mutated and merged variants inherit their niche tags but start un-graded: trust is re-earned, never copied.

👁 The vision loop

flowchart LR
    IMG([image]) --> DI[describe_image<br/>Ollama local/LAN → Anthropic fallback]
    DI -->|caption| M[(memory · tagged vision)]
    DI -->|CLIP 512-dim| VX[(vision_embeddings)]
    TQ([text query]) --> SV[search_vision]
    IQ([example image]) --> SV
    SV --> VX --> M

The backend is tiered so a node with no local compute still gets eyes: point CEREBRO_VISION_URL at any Ollama (a Pi running moondream, or a beefy box across the LAN), or let it fall back to the Anthropic API. CLIP's image and text towers share one embedding space, so "a red bicycle by a door" finds the photo, and the photo finds its siblings. Nodes with embeddings disabled fall back to caption keyword search — degraded, never broken.

📥 File ingestion

ingest_file routes by extension, chunks to memory-sized pieces, and stamps everything with a source:<filename> tag:

The provenance tag makes every import a first-class, reversible operation: find_by_tags(["source:notes.md"]) lists it, bulk_delete removes it.

🤝 Multi-agent memory

Multiple agents share one brain without reading each other's diaries. Every query carries a VisibilityScope compiled into the SQL:

-- FORGE's view:
WHERE (visibility='shared' OR (visibility='private' AND agent_id='FORGE'))
      AND deleted_at IS NULL

• Scope-enforced writes — deletes, purges, restores, and tag rewrites are scope-checked at the storage layer, atomically, not in the handler above it.
• Federation scope — recall(visibility: "shared") restricts to shared memories only, and private nodes don't even influence the spreading activation. This is the scope a mesh peer's query runs under: private never crosses the wire.
• Ownership rules — share_memory is the deliberate publish act; privatizing an owner-less memory is refused (it would be visible to no one).
• Self-history — every successful mutating call writes one attributed row to the audit log. query_audit reads back the agent's own verbs, newest first, filterable by action and time.

🧰 The tool surface (67)

All 67 advertised tools are implemented — no stubs. Wire format: newline-delimited JSON-RPC 2.0 over stdio, protocol 2024-11-05; stdout is exclusively the MCP stream, logs go to stderr. Malformed and oversized frames are answered per-frame (the daemon never dies on bad input), handler panics are isolated, and content is bounded at both gates (64 KiB per memory, 32 MiB per frame).

cognitive_bootstrap deserves a mention: one call assembles a token-budgeted priming block — open intentions, relevant session notes, distilled skills, champion procedures, relevant memories — replacing a four-tool orient at session start.

memories           — the nodes; access_times JSON for ACT-R, embedding BLOB for vec0
links              — typed, weighted edges with traversal stats and decay
memories_fts       — FTS5 mirror, trigger-synced, soft-delete aware
memory_vectors     — vec0 virtual table (sqlite-vec), rowid-joined
vision_embeddings  — CLIP 512-dim image vectors + source paths
memory_versions    — content snapshots for undo/audit (retention-capped)
episodes / steps   — episodic sequences
dream_reports      — persisted dream cycle output (retention-capped)
audit_log          — the agent's own action timeline (retention-capped)
agents             — registry with display metadata
schema_version     — migration marker (100 = migrated from Python)

A retention sweep rides the dream cycle and bounds the three forever-growing tables (CEREBRO_RETAIN_* env knobs; 0 = keep forever). When it prunes, it writes one audit row saying exactly what it did — the timeline may shorten, but never silently.

🚢 Deployment

The tier ladder

Same binary everywhere — tiers are just environment variables.

† GPU ONNX execution providers are planned; CPU works everywhere today. An unrecognized model name falls back to bge-small with a loud warning — embeddings never silently disable.

The real target is the hardware sitting in drawers — last-gen mini-PCs, retired Mac Minis, Pi 4s from the before-times. A complete cognitive memory system in 23 MB leaves the rest of the board for the agent itself.

ApexOS drop-in

# /etc/agentd/plugins.toml
[[plugin]]
id      = "cerebro"
cmd     = "/usr/local/bin/cerebro-mcp"
restart = "always"
[plugin.env]
CEREBRO_DATA_DIR    = "/var/lib/agentd/cerebro"
FASTEMBED_CACHE_DIR = "/var/lib/agentd/cerebro/models"
RUST_LOG            = "warn"

Build natively on the target (arm64 ≠ x86 — never cross-compile), stop the service before copying the binary (text file busy), and pre-warm the model cache on first deploy.

sudo mkdir -p /var/lib/agentd/cerebro/models
sudo chown agentd:agentd /var/lib/agentd/cerebro/models

# Run once as the service user — downloads ~128 MB to the cache
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"prewarm","version":"0.1"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"remember","arguments":{"content":"prewarm memory for model download"}}}\n' | \
  sudo -u agentd env \
    CEREBRO_DATA_DIR=/var/lib/agentd/cerebro \
    FASTEMBED_CACHE_DIR=/var/lib/agentd/cerebro/models \
  /usr/local/bin/cerebro-mcp

🔨 Building from source

cargo build --release        # all four crates
cargo test                   # 250 tests, no network, no model download

🔗 Related

• CerebroCortex — the Python original: reference implementation and the source of the activation-math fixtures
• ApexOS — the Pi-native agent runtime this plugs into, where the multi-node colony features (mesh recall, procedure replication) live

📄 License

MIT