BRAIN

Persistent memory MCP server for Codex sessions.

BRAIN stores structured decisions, outcomes, tasks, and preferences in SQLite, then exposes retrieval and synchronization tools through an MCP server.

Project Status

• Maturity: beta
• Runtime: production-capable for local/operator workflows
• Quality model: benchmark and done-state gated

Why BRAIN

Most memory systems stop at storage. BRAIN is built for operational follow-through:

• retrieve relevant policy and context at turn start,
• track decisions and close them with outcomes,
• enforce measurable memory quality gates,
• keep a human-readable MEMORY.md mirror synced from structured data.

Core Capabilities

Project memory tools:

• get_context
• prepare_turn
• recall
• cleanup_stale_decisions
• provider_health
• just_works_status
• record_event
• upsert_preference
• record_decision
• record_outcome
• sync_memory

Project continuity tools:

• upsert_project_profile
• record_task
• update_task
• list_tasks
• suggest_next

Repository Layout

• mcp/brain/: MCP runtime and evaluation modules
• bin/: install and quality-gate scripts
• docs/: evaluation, done-state, and release docs
• skills/brain/: skill instructions for memory workflow

Quick Start

1) Clone

git clone <repository-url> brain
cd brain

2) Install

bash ./bin/install.sh

Installer behavior:

• links the brain skill into ~/.codex/skills,
• writes or refreshes mcp_servers.brain in ~/.codex/config.toml,
• points MCP runtime at python3 -m brain with PYTHONPATH=<repo>/mcp,
• initializes ~/.codex/brain/brain.env with secure permissions (chmod 600).

3) Restart Codex

Restart is required so the MCP server is loaded in the current session.

Verify Installation

Deterministic fixture check:

bash ./bin/check_ci_fixture.sh

Expected outcome includes:

• just_works_status=healthy
• gate=pass
• done_state=pass

Optional real-dataset check:

bash ./bin/run_memory_eval.sh --report-done-state --enforce-gate --enforce-done-state

Local State And Privacy

BRAIN writes local operational state that should not be committed:

• MEMORY.md
• SQLite runtime files (brain.db, *.db-wal, *.db-shm)

MEMORY.example.md documents the expected shape for memory mirrors.

Uninstall

bash ./bin/uninstall.sh

By default, uninstall keeps local DB files. Set REMOVE_DB=1 to remove them.

Public Release Standard

Before shipping:

python3 -m compileall mcp
bash ./bin/check_ci_fixture.sh
bash ./bin/run_memory_eval.sh --report-done-state --enforce-gate --enforce-done-state

See docs/release-checklist.md for full checklist.

License

MIT. See LICENSE.