LabscoMCP early access ↗
TSchonleberMCP SERVER

BrainCTL

Durable local memory for agents in a single SQLite file — facts, decisions, entities and session handoffs — with full-text and optional vector recall and a knowledge graph.

by TSchonleber ↗Agent MemoryCommunity

LABSCO SUMMARY

Agent memory that is just a file.

The core promise is small and appealing: one SQLite file gives an agent memory across sessions, with no server to run and no keys to hold, and full-text recall works out of the box before you add anything. Two design choices are worth knowing. First, memory categories decay on their own timelines, so stale integration notes fade while identity facts persist. Second, brain-region operations are folded behind dispatchers so the visible tool surface fits the ~100-tool cap some clients enforce — that is what keeps it usable in clients that limit tool count. The Solana mint and marketplace pieces sit off to the side as opt-in extras, not something the memory layer requires.

What it is

An agent-memory library and MCP server backed by one brain.db SQLite file. It stores categorised memories, decisions, tracked entities and session state, retrieves them through FTS5 full-text search (optionally hybrid vector search), links entities into a knowledge graph, and needs no server, API keys or LLM calls to run.

What you get

  • Memories added and searched, with categories that decay at natural rates — identity over about a year, integration details over about a month, capped at 10,000 per agent — memory_add, memory_search
  • Session start and end helpers that assemble a handoff plus events and triggers, then log the session for the next run — agent_orient, agent_wrap_up
  • Decisions, events, entities and handoffs recorded as first-class types — decision_add, event_add, entity_*, handoff_add, trigger_*
  • FTS5 search by default, optional vector similarity via sqlite-vec and Ollama, and hybrid Reciprocal Rank Fusion over both
  • A typed knowledge graph with automatic entity linking and spreading-activation recall
  • Signed, portable memory exports verifiable offline — brainctl export --sign, brainctl verify
  • Brain-region subsystems reached through action-discriminated dispatchers — subsystem_list, subsystem_status, subsystem_emit
  • 16 first-party plugins for agent frameworks and trading bots

Requirements

No account, no API keys and no mandatory dependencies beyond built-in SQLite. Python 3.11+. pip install brainctl for the core; brainctl[mcp] adds the MCP server, brainctl[vec] adds vector search via sqlite-vec and Ollama, brainctl[signing] adds Ed25519-signed exports, brainctl[all] installs everything. The MCP entry launches brainctl-mcp; the pyproject names the package brainctl at 2.8.0. As of 2.8.0 the README puts the public MCP surface at 100 visible tools (370 registered internally), sized to fit the ~100-tool cap some clients enforce, which it says cuts the system-prompt token cost from roughly 50k to about 12k. The optional Solana mint and marketplace features are separate opt-in extras.

Setup effort

One command — pip install 'brainctl[mcp]'

See installation options