brain

A personal memory engine and MCP server for coding agents. Durable facts, session digests, and recorded sessions are searchable through hybrid recall (full-text plus vector search) from any MCP client.

Replace OWNER in the badge with the GitHub account that hosts the fork.

Contents

• Overview

• Choosing an install path

• Path 1: Local

• Path 2: Supabase store, local server

• Path 3: Self-hosted server

• Connecting clients

• Configuration reference

• Commands

• Memory file format

• Repository layout

• Scope and limitations

• License

Related MCP server: Agentic Memory

Overview

An agent's context ends with the session. brain keeps what matters across sessions and makes it recallable through three MCP tools on every deployment: recall, get_episode, and remember.

It stores three kinds of documents:

• Memories: curated, durable facts (preferences, decisions, runbooks, per-project state notes).

• Summaries: per-session digests written by the consolidation pass.

• Episodes: recorded Claude Code transcript turns.

Each query runs a lexical leg (BM25 or Postgres full-text) and a vector leg. The two rankings are fused with reciprocal-rank fusion, then weighted by kind (a curated memory outranks a raw episode at equal evidence) and by recency. Every hit carries a score in (0, 1].

Two storage backends share one code base:

Choosing an install path

Pick path 1 to try the project or for a single machine. Pick path 3 to share one brain across several machines or agents without handing out database credentials. Path 2 sits between them: one shared database, no server to run.

Path 1: Local

Everything runs on one machine. Markdown under memories/ and summaries/ is the source of truth, and cache/brain.db is a derived index that can be deleted and rebuilt at any time.

Prerequisites

• Python 3.12+ and uv.

• Git.

• About 600 MB of disk for the embedding model, downloaded on first run.

Steps

1. Clone and install.

   git clone https://github.com/OWNER/brain-mcp.git ~/src/brain-mcp
   cd ~/src/brain-mcp
   uv sync

2. Try recall against the synthetic store in examples/. Pointing BRAIN_CLAUDE_PROJECTS at an empty directory keeps real transcripts out.

   BRAIN_DIR=$PWD/examples BRAIN_CLAUDE_PROJECTS=$(mktemp -d) \
     uv run brain-ingest --full
   BRAIN_DIR=$PWD/examples uv run brain-recall "postgres backup"

3. Index real data. With BRAIN_DIR unset, the store is the checkout itself and brain-ingest reads Claude Code transcripts from ~/.claude/projects (and ~/.claude-work/projects when it exists).

   uv run brain-ingest

4. Register the stdio server with Claude Code.

   claude mcp add brain -- uv run --directory ~/src/brain-mcp brain-server

   For a client that must only see read tools, register brain-server-readonly instead (recall and get_episode only).

5. Optional: add the local hooks to ~/.claude/settings.json.

   {
     "hooks": {
       "SessionStart": [{ "hooks": [{ "type": "command", "timeout": 10,
         "command": "uv run --no-sync --directory ~/src/brain-mcp brain-session-start" }] }],
       "UserPromptSubmit": [{ "hooks": [{ "type": "command", "timeout": 5,
         "command": "uv run --no-sync --directory ~/src/brain-mcp brain-hook" }] }]
     }
   }

   brain-session-start injects the project's state note with a freshness banner. brain-hook runs a fast read-only search on each prompt and injects the strongest matches.

6. Optional: consolidation. Link skills/reflect-local into ~/.claude/skills/ and set BRAIN_REFLECT_SKILL=/reflect-local so the debt-triggered brain-autoreflect runs the local pass. The other skills in skills/ target the hosted MCP tools (paths 2 and 3).

7. Optional: multi-machine sync. Add any private git remote as origin. Memory writes auto-commit, and brain-sync pulls and pushes. The index never leaves the machine. BRAIN_SYNC=0 disables sync. An always-on Linux box can index the committed episodes/ tree and run maintenance timers; see deploy/vm/ and specs/episodes-in-git.md.

Environment

None is required. Common settings: BRAIN_DIR, BRAIN_CLAUDE_PROJECTS, BRAIN_SYNC, BRAIN_REFLECT_SKILL, FASTEMBED_CACHE_PATH. Set BRAIN_BACKEND=sqlite if DATABASE_URL is exported in the same shell for another reason.

Path 2: Supabase store, local server

Postgres holds every document and the search index. Each machine runs the stdio server against the same database. Supabase is the documented host; any Postgres 17 with the vector extension works (CI uses pgvector/pgvector:pg17).

Prerequisites

• Everything from path 1.

• A Supabase project (or another Postgres 17 with pgvector).

• An OpenAI API key if OpenAI embeddings are used.

Steps

1. Create the Supabase project. Leave schema brain off the Data API's exposed schemas. Details: docs/supabase.md, section 1.

2. Apply the migrations over the direct connection or the session pooler (port 5432), never the transaction pooler.

   export DATABASE_URL='postgresql://postgres:PASSWORD@db.PROJECT_REF.supabase.co:5432/postgres'
   uv run brain-pg-migrate

   Re-running is safe. For a least-privilege login, create brain_app and grant it brain_server (see docs/supabase.md, section 2).

3. Optional: import an existing path 1 store. Only git-tracked files are read.

   uv run brain-pg-load --repo /path/to/store --sqlite /path/to/store/cache/brain.db

4. Choose one embedding space and keep it. Either leave BRAIN_EMBED_PROVIDER unset (local model) or set BRAIN_EMBED_PROVIDER=openai with OPENAI_API_KEY, then fill vectors:

   uv run brain-pg-reembed --estimate
   uv run brain-pg-reembed
   uv run brain-pg-reembed --swap --require-complete

   Recall only uses vectors whose stored space matches the running process.

5. Register the server with Claude Code.

   claude mcp add brain \
     -e DATABASE_URL='postgresql://...' -e BRAIN_EMBED_PROVIDER=openai -e OPENAI_API_KEY=sk-... \
     -- uv run --directory ~/src/brain-mcp brain-server

   In this mode remember writes to Postgres and does not commit to git, and the server does not run brain-ingest.

Environment

DATABASE_URL (or SUPABASE_DB_URL), BRAIN_EMBED_PROVIDER, OPENAI_API_KEY for OpenAI embeddings, and optionally BRAIN_PG_POOL_MAX.

Notes

New sessions are not recorded automatically in this path. brain-push and the remote hooks post to the HTTP server's device routes, which only path 3 provides, and local brain-ingest writes only the SQLite index. Memories written with remember and data imported with brain-pg-load are the contents of the store.

Path 3: Self-hosted server

One HTTP MCP server fronts the Postgres store. MCP clients sign in with Google OAuth. Hooks and the session recorder on each device authenticate with a per-device token, so no device holds database credentials.

Routes: /mcp (all tools), /mcp-ro (recall and get_episode only), /health (open, does not touch the database), and the device routes /ingest/episodes, /hook/state, /hook/recall.

Prerequisites

• A Postgres store set up as in path 2, steps 1 and 2 (migrations through 0007 applied).

• A container host. Cloud Run is documented; the Dockerfile runs on any host that serves HTTPS in front of port 8080.

• A Google OAuth client of type Web application (Google Cloud Console, APIs and Services, Credentials).

• An OpenAI API key. The image omits the local embedding model to keep cold starts fast; BRAIN_EMBED_PROVIDER=off runs full-text only.

Steps

1. Decide the public origin, for example https://brain.example.com or the Cloud Run service URL. This is BRAIN_PUBLIC_URL.

2. In the OAuth client, add the redirect URI ${BRAIN_PUBLIC_URL}/auth/callback.

3. Configure the service environment. Every variable is listed in deploy/cloudrun/env.example. Store secrets in a secret manager, not in plain env flags. At runtime DATABASE_URL should be the Supavisor transaction pooler (port 6543).

4. Deploy. On Cloud Run:

   gcloud run deploy brain --source . --region REGION \
     --max-instances=1 --memory=1Gi --port=8080

   On another host, build with docker build -t brain-mcp . and run the image with the same environment. The server refuses to start without BRAIN_PUBLIC_URL, the Google client id and secret, and at least one of BRAIN_AUTH_DOMAIN or BRAIN_AUTH_ALLOWED_EMAILS. IAM notes for organizations with domain-restricted sharing are in deploy/cloudrun/README.md.

5. Check health.

   curl -fsS "$BRAIN_PUBLIC_URL/health"

   Use /health for probes. Cloud Run's frontend does not route paths that end in z, so /healthz is not reachable from outside.

6. Optional: nightly job. brain-nightly dumps schema brain to a Cloud Storage bucket and drains the git export outbox into one commit on a GitHub repo. Setup: deploy/cloudrun/nightly.md. Helper scripts for Cloud Run deploys and a full git resync are in ops/.

7. Connect each device as described in Connecting clients.

Environment

Required: DATABASE_URL, BRAIN_PUBLIC_URL, BRAIN_GOOGLE_CLIENT_ID, BRAIN_GOOGLE_CLIENT_SECRET, and BRAIN_AUTH_DOMAIN and/or BRAIN_AUTH_ALLOWED_EMAILS. Usually set: BRAIN_BACKEND=postgres, BRAIN_EMBED_PROVIDER=openai, OPENAI_API_KEY, BRAIN_JWT_SIGNING_KEY. The image sets the backend, embedding, host, and port defaults.

Access control

• BRAIN_AUTH_DOMAIN admits a Google Workspace domain. Google's hd claim must match; an address that merely ends in the domain is refused.

• BRAIN_AUTH_ALLOWED_EMAILS admits individual accounts.

• BRAIN_AUTH_EMAIL_PROFILES limits an account to the personal or work profile, for example you@example.com=personal|work.

• OAuth client registrations and token mappings are stored encrypted in brain.oauth_kv. Keep BRAIN_JWT_SIGNING_KEY stable across deploys; changing it invalidates every stored sign-in.

Connecting clients

Claude Code, stdio (paths 1 and 2)

claude mcp add brain -- uv run --directory ~/src/brain-mcp brain-server

Claude Code, HTTP (path 3)

claude mcp add --transport http brain "$BRAIN_PUBLIC_URL/mcp"
# read-only alternative
claude mcp add --transport http brain-ro "$BRAIN_PUBLIC_URL/mcp-ro"

Run /mcp in a session to complete the Google sign-in.

Other clients take the same URL. Cursor mcp.json:

{ "mcpServers": { "brain": { "url": "https://brain.example.com/mcp" } } }

Codex: point the brain entry in ~/.codex/config.toml at the URL, then run codex mcp login brain. More detail: docs/connecting-agents.md.

Device tokens and session recording (path 3)

Hooks cannot complete a browser sign-in, so each device gets its own token. The CLI signs in through the browser and writes the token to ~/.config/brain/device-token, so the token never appears in a transcript.

export BRAIN_URL="$BRAIN_PUBLIC_URL"
uv run --directory ~/src/brain-mcp brain-device-token create --device laptop
uv run --directory ~/src/brain-mcp brain-device-token list
uv run --directory ~/src/brain-mcp brain-device-token revoke <id>

BRAIN_URL must point at the server on every device; the default is http://localhost:8080. The client needs no database credentials, no embedder, and no SQLite file. Installing the console scripts with uv tool install --from ~/src/brain-mcp brain puts them on PATH.

Hooks for ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "timeout": 10,
      "command": "uv run --no-sync --directory ~/src/brain-mcp brain-remote-session-start" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "timeout": 5,
      "command": "uv run --no-sync --directory ~/src/brain-mcp brain-remote-recall-hook" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "timeout": 10,
      "command": "uv run --no-sync --directory ~/src/brain-mcp brain-push --hook" }] }],
    "SessionEnd": [{ "hooks": [{ "type": "command", "timeout": 10,
      "command": "uv run --no-sync --directory ~/src/brain-mcp brain-push --hook" }] }]
  }
}

brain-push --hook detaches and returns immediately. A periodic catch-up covers sessions a hook missed:

*/30 * * * * cd ~/src/brain-mcp && uv run --no-sync brain-push >/dev/null 2>&1

On Windows, schedule the same command with Task Scheduler. To record history from before the hooks were installed, run brain-push --backfill --dry-run, then brain-push --backfill.

Skills

The skills/ directory holds Claude Code skills that drive the hosted tools: /checkpoint (save a project's state note before /clear), /handoff, /catchup (deep resume), /reflect (starts a headless consolidation pass) and /reflect-run (the pass itself). skills/codex/ has the Codex variant, and skills/reflect-local/ is the path 1 pass. Link or copy them into ~/.claude/skills/.

Configuration reference

All configuration is environment variables. Defaults live in src/brain/config.py, src/brain/embedconf.py, and src/brain/authz.py.

Store and backend

Embeddings and ranking

HTTP server and access control (path 3)

Devices, hooks, and push

Privacy, consolidation, and nightly job

Commands

Every entry point is a console script, run with uv run <name>.

Memory file format

A memory is YAML frontmatter plus a markdown body:

---
name: postgres-nightly-backup
description: How the demo acme-webapp Postgres database is backed up each night.
metadata:
  type: reference
date: 2026-01-12
---
The `acme-webapp` database is dumped nightly at 02:00 UTC ...

Types are user, feedback, project, and reference. See examples/ for one of each kind and the session-digest format. The Postgres backend stores the same fields, and the git export renders rows back into this format.

Repository layout

Scope and limitations

• Built as a single-user personal system. Profiles (personal, work) separate one person's contexts; the server is not a hardened multi-tenant service.

• Google is the only OAuth provider the HTTP server supports.

• The container image has no local embedding model. A hosted server uses OpenAI embeddings or runs full-text only.

• CI runs the SQLite suite without the embedding model and runs the Postgres suite against pgvector/pgvector:pg17. Postgres tests skip locally unless DATABASE_URL is set.

License

MIT. See LICENSE.