brainctl

Your AI agent forgets everything between sessions. brainctl fixes that.

One SQLite file gives your agent persistent memory — what it learned, who it talked to, what decisions were made, and why. No server. No API keys. No LLM calls.

from agentmemory import Brain

brain = Brain(agent_id="my-agent")

# Start of session — get full context in one call
context = brain.orient(project="api-v2")
# → {'handoff': {...}, 'recent_events': [...], 'triggers': [...], 'memories': [...]}

# During work
brain.remember("API rate-limits at 100 req/15s", category="integration")
brain.decide("Use Retry-After for backoff", "Server controls timing", project="api-v2")
brain.entity("RateLimitAPI", "service", observations=["100 req/15s", "Retry-After header"])

# End of session — preserve state for next agent
brain.wrap_up("Documented rate limiting, auth module complete", project="api-v2")

Next session, a different agent (or the same one) picks up exactly where you left off.

Install

pip install brainctl

That's it. No dependencies beyond Python 3.11+ and SQLite (built-in). Optional extras:

pip install brainctl[mcp]         # MCP server for Claude Desktop / VS Code
pip install brainctl[vec]         # vector similarity search (sqlite-vec + Ollama)
pip install brainctl[all]         # everything

Upgrading

Fresh installs: nothing to do. pip install brainctl and your first Brain() call creates a brain.db with the full current schema.

Upgrading an existing brain.db: brainctl tracks schema migrations in a schema_versions table. After upgrading:

cp $BRAIN_DB $BRAIN_DB.pre-upgrade     # always back up first
brainctl doctor                         # diagnose migration state
brainctl migrate                        # apply anything pending

If brainctl doctor reports everything green, you're done.

Predating the tracker — "virgin tracker + schema drift"

If your brain.db existed before the migration tracking framework was introduced, schema_versions will be empty but your schema already has the effects of many migrations. Running brainctl migrate blindly in that state will crash on the first ALTER TABLE ADD COLUMN that collides with an existing column — SQLite has no IF NOT EXISTS for column adds.

brainctl doctor detects this state and prints:

  migrations: virgin tracker + 5 ad-hoc schema hits — DANGEROUS to run `brainctl migrate` directly
    1. brainctl migrate --status-verbose   (see which migrations are truly pending)
    2. apply truly-pending ones manually via sqlite3
    3. brainctl migrate --mark-applied-up-to N (backfill the rest)
    4. brainctl migrate   (run anything above N)

Full recovery workflow:

# 1. Back up. Always.
cp $BRAIN_DB $BRAIN_DB.pre-migrate

# 2. Get a per-migration heuristic report.
#    Each migration is classified as:
#      likely-applied → all expected columns/tables exist
#      partial        → some DDL applied, some missing (actual drift)
#      pending        → none of its DDL exists (genuinely needs to run)
#      unknown        → no introspectable DDL (UPDATE-only or DROP-only)
brainctl migrate --status-verbose

# 3. For each migration in 'pending' or 'partial', apply it manually.
#    This is the safe path because you see exactly what each statement does.
sqlite3 $BRAIN_DB < db/migrations/024_confidence_alpha_beta_wiring.sql
sqlite3 $BRAIN_DB < db/migrations/028_memory_quarantine.sql
# ... etc

# 4. Backfill the tracker so future `brainctl migrate` runs skip
#    what's already applied. Pick N = highest version you've verified.
brainctl migrate --mark-applied-up-to 31

# 5. Run anything above N (e.g. migration 032 drops dead tables)
brainctl migrate

--mark-applied-up-to N writes rows to schema_versions with a (backfilled) suffix on the name so you can tell them apart from "really ran" rows. It refuses to go below the current high-water mark (guards against rewritin

... View full README on GitHub