brainctl 0.1.0

A cognitive memory system for AI agents — episodic, semantic, and procedural memory with FTS5 search, vector embeddings, neuromodulation, and MCP server integration.

brainctl

A cognitive memory system for AI agents. Single SQLite file. No server required.

from brainctl import Brain

brain = Brain()
brain.remember("User prefers dark mode")
brain.search("dark mode")
brain.entity("Alice", "person", observations=["Engineer", "Likes Python"])
brain.relate("Alice", "works_at", "Acme")
brain.log("Deployed v2.0")

MCP Server (Claude Desktop / VS Code)

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

12 tools: memory_add, memory_search, event_add, event_search, entity_create, entity_get, entity_search, entity_observe, entity_relate, decision_add, search, stats

Install

pip install brainctl              # core
pip install brainctl[mcp]         # with MCP server
pip install brainctl[vec]         # with vector search (sqlite-vec)
pip install brainctl[all]         # everything

CLI

# Memories
brainctl memory add "Python 3.12 is the minimum version" -c convention
brainctl memory search "python version"

# Entities (typed knowledge graph)
brainctl entity create "Alice" -t person -o "Engineer; Likes Python; Based in NYC"
brainctl entity get Alice
brainctl entity relate Alice works_at Acme
brainctl entity search "engineer"

# Events
brainctl event add "Deployed v2.0 to production" -t result -p myproject
brainctl event search -q "deploy"

# Cross-table search (memories + events + entities)
brainctl search "deployment"

# Prospective memory (triggers that fire on future queries)
brainctl trigger create "Alice mentions vacation" -k vacation,alice -a "Remind about project deadline"
brainctl trigger check "alice is going on vacation"

# Stats
brainctl stats

What Makes It Different

Feature	brainctl	mem0	Zep	MemGPT
Single file (SQLite)	✓	✗	✗	✗
No server required	✓	✓	✗	✗
MCP server included	✓	✗	✗	✗
Full-text search (FTS5)	✓	✗	✗	✗
Vector search	✓	✓	✓	✓
Entity registry	✓	✗	✓	✗
Knowledge graph	✓	✗	✓	✗
Consolidation engine	✓	✗	✗	✗
Confidence decay	✓	✗	✗	✗
Bayesian scoring	✓	✗	✗	✗
Prospective memory	✓	✗	✗	✗
Write gate (surprise scoring)	✓	✗	✗	✗
Multi-agent support	✓	✗	✓	✗
No LLM calls for memory ops	✓	✗	✓	✗

Architecture

brain.db (single SQLite file)
├── memories        FTS5 full-text + optional vec search
├── events          timestamped logs with importance scoring
├── entities        typed nodes (person, project, tool, concept...)
├── knowledge_edges directed relations between any table rows
├── decisions       recorded with rationale
├── memory_triggers prospective memory (fire on future conditions)
└── 20+ more tables (consolidation, beliefs, policies, epochs...)

Consolidation Engine (hippocampus.py)
├── Confidence decay    — unused memories fade
├── Temporal promotion  — frequently-accessed memories strengthen
├── Dream synthesis     — discover non-obvious connections
├── Hebbian learning    — co-retrieved memories form edges
├── Contradiction detection
└── Compression         — merge redundant memories

Write Gate (W(m))
├── Surprise scoring    — reject redundant memories at the door
├── Worthiness check    — surprise × importance × (1 - redundancy)
└── Force flag          — bypass for explicit writes

Vector Search (Optional)

brainctl works without embeddings. For vector search, install Ollama and sqlite-vec:

pip install brainctl[vec]
# Install Ollama: https://ollama.ai
ollama pull nomic-embed-text
brainctl-embed                    # backfill embeddings
brainctl vsearch "semantic query" # vector similarity search

Docker

docker build -t brainctl .
docker run -v ./data:/data brainctl              # MCP server
docker run -v ./data:/data brainctl brainctl stats  # CLI

Multi-Agent

Every operation accepts --agent / agent_id for attribution:

brainctl -a agent-alpha memory add "learned something" -c lesson
brainctl -a agent-beta entity observe "Alice" "Now leads the team"

Agents share one brain.db. Each write is attributed. Search sees everything.

Contributing

PRs welcome. The codebase is one big Python file (bin/brainctl) — intentionally. Single-file means no import hell, easy to read, easy to deploy.

License

MIT