brainctl

Forgetful agents, fixed by a SQLite file.

One brain.db gives your agent durable memory across sessions — facts learned, decisions made, entities tracked, and state handed off. No server. No API keys. No LLM calls required.

Saturday May 17, 2026 — the agent memory marketplace opens at brainctl.org/marketplace. Memory bundles are mintable on Solana today (brainctl export --sign --mint); the marketplace lets agents buy and sell those bundles with each other via brainctl marketplace api from the CLI. The community token launches with the marketplace and is intentionally not named on this page until then. See the Mint section and Marketplace section below for the primitives, and the website for the full launch story.

from agentmemory import Brain

brain = Brain(agent_id="my-agent")
ctx = brain.orient(project="api-v2")           # session start: handoff + events + triggers + memories
brain.remember("rate-limit: 100/15s", category="integration")
brain.decide("use Retry-After for backoff", "server controls timing", project="api-v2")
brain.wrap_up("auth module complete", project="api-v2")  # session end: logs + handoff for next run

Install

pip install brainctl

Requires Python 3.11+. SQLite is built-in. No other mandatory dependencies.

pip install brainctl[mcp]     # MCP server — 100 visible tools for Claude Desktop, Cursor, VS Code
pip install brainctl[vec]     # vector similarity search (sqlite-vec + Ollama)
pip install brainctl[signing] # Ed25519-signed memory exports + optional Solana on-chain pinning
pip install brainctl[all]     # everything

5-line example

from agentmemory import Brain

brain = Brain(agent_id="research-bot")
brain.remember("OpenAI rate-limits at 500k TPM on tier 3", category="integration")
results = brain.search("rate limit")          # FTS5 full-text, stemming, ranked
brain.entity("OpenAI", "service", observations=["500k TPM tier 3", "REST API"])
brain.relate("OpenAI", "provides", "GPT-4o")

Feature checklist

Memory types

• convention, decision, environment, identity, integration, lesson, preference, project, user
• Category controls natural half-life: identity decays over ~1 year; integration details over ~1 month
• Hard cap: 10,000 memories per agent. Emergency compression retires lowest-confidence entries.

Retrieval modes

• FTS5 full-text search with stemming (default, zero dependencies)
• Vector similarity via sqlite-vec + Ollama nomic-embed-text (brainctl[vec])
• Hybrid: Reciprocal Rank Fusion over FTS5 + vector results
• Context profiles: named search presets scoped to task type (--profile ops, --profile research, etc.)
• --benchmark preset: flattens recency/salience for synthetic evaluation runs

Reranker chain

• Intent classifier (regex, 10 labels → 6 profiles) routes queries at cmd_search
• Post-FTS reranking by recency, salience, Q-value utility, and Bayesian recall confidence
• Cold-start: auto-detects available reranker backends (cross-encoder > sentence-transformers > fallback)
• Cross-encoder controls: --rerank-top-n and --rerank-budget-ms tune candidate window + strict latency budget
• Top-heavy staged rollout controls (I6): --rollout-mode, --rollout-canary-agents, --rollout-canary-percent, --rollback-top-heavy
• Env mirrors for rollout controls: BRAINCTL_TOPHEAVY_ROLLOUT_MODE, BRAINCTL_TOPHEAVY_CANARY_AGENTS, BRAINCTL_TOPHEAVY_CANARY_PERCENT, BRAINCTL_TOPHEAVY_ROLLBACK
• Retrieval regression-gated in CI: >2% drop on P@1/P@5/MRR/nDCG@5 fails the build

Knowledge graph

• Typed entity nodes: agent, concept, document, event, location, organization, person, project, service, tool
• Auto entity linking: memories mentioning a known entity create the edge automatically
• Compiled truth synthesis per entity (brainctl entity compile <name>)
• 3-level enrichment tier; canonical alias dedup (brainctl entity alias add)
• Spreading-activation recall across the graph (brain.think(query))

Brain-region subsystems (v2.8.0)

brainctl models 27 brain regions / nuclei as first-class subsystems, each with its own schema, state, and event log. They cover the modulatory, attentional, motivational, mnemonic, and sensorimotor layers that real cognition runs on:

• Modulatory nuclei: locus coeruleus (NE / phasic surprise gain), nucleus basalis (ACh / phasic attention), VTA-SNc (dopamine pathways), raphe (serotonin / horizon)
• Arousal / state: ARAS (wake-sleep transitions), sleep architecture (REM/NREM cycles)
• Motivational gates: habenula (negative-prediction "no-go"), septum (theta pacing)
• Memory mechanics: hippocampus CA1+subiculum (mismatch detection / output), memory aging (synaptic tagging-and-capture, Frey & Morris), mammillary (Papez circuit transit)
• Workspace: workspace bandwidth (global-workspace throttling), connectome (inter-region graph)
• Sensorimotor: colliculi (orienting), olfactory (single-trial valence imprinting), claustrum (multimodal binding)
• Pre-existing (2.x): basal ganglia, cerebellum, thalamus, amygdala, hippocampal subfields, ACC, DMN, drives, insula, PFC, entorhinal grid cells

Every subsystem speaks the same dispatcher protocol (subsystem_status, subsystem_emit, subsystem_register, subsystem_history, subsystem_configure), so an agent that learned the shape for LC already knows how to drive raphe or claustrum. Schemas live in db/migrations/067-082 (this release) plus the earlier brain-region migrations.

Belief revision (AGM)

• Belief set per agent with confidence weights
• Conflict detection and resolution via brainctl belief conflicts and brainctl belief merge
• Collapse mechanics: decoherent beliefs quarantined, recovery candidates surfaced
• PII recency gate (Proactive Interference Index) on supersedes operations

Signed exports

• brainctl export --sign produces a portable Ed25519-signed JSON bundle
• brainctl verify <bundle.json> checks the signature offline — no brainctl required for verification
• Optional: --pin-onchain writes the SHA-256 hash as a Solana memo transaction (~$0.001 per pin)
• Managed wallet: brainctl wallet new creates a local keypair at ~/.brainctl/wallet.json for users without an existing Solana setup
• Memories never leave the machine; only the hash goes on-chain (opt-in)

Mint (v1, optional [mint] extra)

• brainctl export --sign --mint mints one Light Protocol compressed token per signed bundle, owned by your brainctl wallet
• Bundle content is AES-256-GCM encrypted before anything touches a public storage layer (Arweave) — the chain stores ownership, never plaintext
• Each mint creates a Memory NFT-style token: scannable in any Solana wallet, transferable via Tensor / Magic Eden out of the box, ~$0.0001 per mint (Light Protocol's compressed-token program)
• Devnet by default; mainnet-beta requires --cluster mainnet-beta and a Helius API key
• Setup: pip install 'brainctl[mint]' then cd tools && npm install (the actual mint runs in a Node helper because Light Protocol's SDK is TypeScript-only as of v0.23)
• Foundation for the agent-to-agent memory marketplace; see CLAUDE.md § "Mint" for the full agent flow

Marketplace (v1.5, optional [marketplace] extra)

• brainctl marketplace api ... drives the chain-canonical memory marketplace at brainctl.org/marketplace
• Sellers list signed proofs (not pre-minted tokens); the cNFT is forged just-in-time at settlement, one fresh mint per buyer
• Negotiation chain on Solana memos + Arweave manifests — every state change is a signed memo so anyone can reproduce the marketplace state from chain alone
• Buyer flow: browse → show → settle --submit → status --wait --auto-decrypt --ingest (full end-to-end in four commands)
• Negotiated buyer flow: offer <listing> --price-usd N → poll offers <listing> → settle the accepted offer_id
• Seller flow: list (publishes the proof) → listen (daemon mints cNFT + releases bundle key when payment lands)
• Negotiation: offers <listing>, offer, counter, accept, reject, withdraw — every move is a signed memo + Arweave manifest, fully agent-callable
• Decrypt your own minted bundle locally: brainctl bundle decrypt <mint> --ciphertext-uri ar://...

Import from other providers (v2.6.0)

• brainctl import mem0 <export.json> — onboard from mem0
• brainctl import json <records.json> — generic JSON ingest (list or {"memories":[...]} shape, also .jsonl)
• Quarantine-by-default: imports land in scope imported:<provider>; promote into your primary scope after review
• More providers (zep, cognee, letta, langchain) coming next
• 2.5% protocol fee at settlement, USD-pegged pricing capped at $10,000, SOL-native pre-launch (community token post-launch). Flat $0.10 fee on each list/offer/counter/accept/reject/withdraw, $0.50 on mint, $0.10 on --pin-onchain. Devnet is free.
• Auth is wallet-signature based — no API keys, your Solana wallet is your agent identity
• Setup: pip install 'brainctl[marketplace]' (adds pynacl on top of [mint])

Plugins (16 first-party)

Agent frameworks:

Trading bots:

MCP server (100 visible tools, v2 surface)

{
  "mcpServers": {
    "brainctl": {
      "command": "brainctl-mcp"
    }
  }
}

Add to ~/.claude/claude_desktop_config.json, ~/.cursor/mcp.json, or equivalent. Full tool list and decision tree: MCP_SERVER.md. v1→v2 name migration map: docs/TOOL_MIGRATION_V2.md.

As of 2.8.0, the public MCP surface is 100 visible tools (370 registered internally). Tier-1 tools — memory_add, memory_search, event_add, entity_*, agent_orient, agent_wrap_up, decision_add, handoff_add, trigger_* — are called directly by name. Brain-region operations route through action-discriminated dispatchers:

// Discover what's available
subsystem_list()                                  // 27 brain subsystems
subsystem_list_actions(name="lc")                 // valid actions for LC

// Then act
subsystem_status(name="lc", agent_id="me")
subsystem_emit(name="lc", action="fire",
               payload={"trigger_name":"x", "surprise_magnitude":0.7})
belief(action="collapse", payload={...})
trust(action="show", payload={"agent_id":"me"})

The shape of the surface fits the ~100-tool cap that several MCP clients enforce (Google Antigravity, etc.) and cuts the system-prompt token cost from ~50k → ~12k. v1 tool names remain callable internally for backwards compatibility; only their visibility in tools/list changes.

CLI reference

brainctl memory add "content" -c convention   # store a memory
brainctl search "query"                       # FTS5 search
brainctl vsearch "semantic query"             # vector search (requires [vec])
brainctl entity create "Alice" -t person      # create entity
brainctl entity relate Alice works_at Acme    # link entities
brainctl event add "deployed v3" -t result    # log an event
brainctl decide "title" -r "rationale"        # record a decision
brainctl export --sign -o bundle.json         # signed export
brainctl verify bundle.json                   # verify a bundle
brainctl wallet new                           # create managed signing wallet
brainctl wallet export-key                    # base58 private key for Phantom/Backpack/Solflare/Glow import
brainctl stats                                # DB overview
brainctl doctor                               # health check
brainctl lint                                 # quality issues
brainctl gaps scan                            # coverage + orphan + broken-edge scans
brainctl consolidate cycle                    # full consolidation pass

Python API (22 methods)

Memory lifecycle

• Write gate (W(m)): surprise scoring rejects redundant writes. Bypass with force=True.
• Three-tier routing: high-value memories get full indexing; low-value get lightweight storage.
• Duplicate suppression: near-duplicates reinforce existing memories instead of creating new rows.
• Half-life decay: unused memories fade at a rate set by category. Recalled memories are reinforced.
• Consolidation: Hebbian learning, temporal promotion, compression — runs on a cron schedule.

Retrieval benchmarks

Tested with default settings, no tuning for benchmark data. Two harnesses ship in the tree:

• tests/bench/ — single-system retrieval baselines for Brain.search and cmd_search, gated against regression in CI.
• tests/bench/competitor_runs/ — same-fixture head-to-head harness with adapters for Mem0, Letta, Zep, Cognee, MemPalace, OpenAI Memory. Skip-not-fabricate contract: missing SDK / API key raises CompetitorUnavailable instead of returning a fake 0. Each result row carries a provenance block recording retrieval_mode, vector_enabled, embedding_model, rerankers_active, and the full search_args so the JSON is self-describing.

brainctl-only baselines (Brain.search, FTS5)

LongMemEval (289-question retrieval-friendly subset of longmemeval_s):

LongMemEval lock snapshot (old FTS-only baseline vs final locked, n=289):

LOCOMO (1,982 questions, 5 categories, 10 conversations):

LOCOMO latest retrieval operating points (n=1,982, no-LLM retrieval):

Interpretation: hybrid leads session on hit@1, hit@5, MRR, and multi-hop hit@5, ties temporal hit@5, and slightly trails on single-hop hit@5.

The Brain.search baseline remains weaker on hop-heavy categories (single-hop/multi-hop hit@1 0.167 / 0.174). Root cause: recency and salience rerankers bias toward recent memories; LOCOMO uses uniform synthetic timestamps with gold evidence concentrated in early sessions, so reranking can fight lexical evidence. A --benchmark preset that flattens recency/salience is available for evaluation runs.

Top-heavy rollout and provenance (I2/I3/I4/I6)

• Rollout policy is staged and canary-first: start with --rollout-mode canary, then move to on after guardrails hold.
• Emergency rollback is explicit: --rollback-top-heavy or BRAINCTL_TOPHEAVY_ROLLBACK=1.
• Cross-encoder top-heaviness knobs are explicit: --rerank-top-n N, --rerank-budget-ms MS.
• Canary targeting supports both allowlist and percent sampling: --rollout-canary-agents / BRAINCTL_TOPHEAVY_CANARY_AGENTS, --rollout-canary-percent / BRAINCTL_TOPHEAVY_CANARY_PERCENT.
• Provenance is emitted in search output via _debug (always with --debug; opportunistically otherwise). Inspect: topheavy.rollout_mode, topheavy.rollout_reason, topheavy.enabled, <bucket>.cross_encoder_applied, <bucket>.cross_encoder_skipped, <bucket>.cross_encoder_latency_ms, <bucket>.cross_encoder_p95_ms, <bucket>.cross_encoder_top_n, and gate keys such as <bucket>.recency_skipped, <bucket>.salience_skipped, <bucket>.qvalue_skipped, <bucket>.trust_skipped, <bucket>.fetch_narrowed.

Head-to-head vs MemPalace (measured 2026-04-18)

Same machine (Intel Core Ultra 7 258V / 33.9 GB RAM / Windows 10), same datasets, same scoring. Repro: python benchmarks/compare_memory_engines.py --label full_compare.

Honesty caveat (verbatim from the artifact bundle): the vector-on/off flag for the cmd_search run was not persisted in that specific bundle. Subsequent runs through tests/bench/competitor_runs/ record retrieval_mode + vector_enabled automatically (commit 40c1ed2), so the gap is closed for any future re-run. We will not cite the cmd_search numbers above as a clean vector-vs-FTS statement without rerunning that exact variant with the flag captured.

Upgrading

cp $BRAIN_DB $BRAIN_DB.pre-upgrade
brainctl doctor      # diagnose migration state
brainctl migrate     # apply pending migrations

For databases predating the migration tracker, see the full recovery workflow in the README's Upgrading section (below the install block in the full docs).

Multi-agent

researcher = Brain(agent_id="researcher")
writer     = Brain(agent_id="writer")

researcher.remember("API uses OAuth 2.0 PKCE", category="integration")
writer.search("OAuth")   # finds researcher's memory — same brain.db, shared graph

Every operation accepts agent_id for attribution. Agents share one brain.db. The knowledge graph connects insights across agents automatically.

Documentation

License

MIT