Brain

Your team already wrote the missing manual. It is sitting in agent chats.

Brain turns Claude Code, Codex, Cursor, and Amp sessions into a shared, searchable memory. A new teammate can ask why a system works this way. An agent can find the old investigation instead of repeating it. The useful context can span the whole history of a Git organization, including decisions that never made it into a document.

Deploy Brain once. Put it on your Tailnet. Point any stateless MCP client at /mcp. Search needs no Brain package, token, browser login, or custom client. It works well from Code Mode because the MCP tools are small data operations and the agent can combine them in a REPL.

Brain is open source and cloud-neutral. AWS, another cloud, or one machine all work.

What feels different

• Tailscale is the default front door. People use the identity they already have on the private network.

• Search and reading are remote, stateless MCP calls. There is nothing to install on each reader's machine.

• Sharing stays deliberate. The local exporter shows the repository, source, dates, and session count before upload.

• Repository scope comes from the saved session directory's Git origin, not its folder name. Amp threads carry their own Git remote, so threads from orbs keep their repository.

• Claude Code, Codex, Cursor, Amp, subagents, archived Codex sessions, and recorded Codex Desktop side chats are supported.

• Repeated text is stored once with SHA-256 content-addressed storage. Uploads send only missing sessions and bodies.

• Admins can audit bounded request records, including the first 2,000 characters of each search. Upload bodies and responses are never stored.

Related MCP server: Trapic Core

Run it

uv is the default way to build, test, and run Brain.

git clone https://github.com/sdrshn-nmbr/brain
cd brain
cp .env.example .env
# Edit the repository, Tailnet host, admin login, and app-capability domain.
docker compose up -d
tailscale serve --accept-app-caps=example.com/cap/brain 8788

Then point a remote MCP client at:

https://brain.your-tailnet.ts.net/mcp

Tailscale Serve adds the caller identity and strips spoofed identity headers. Keep Brain's published port on host loopback and do not expose its plain HTTP port. See authentication and deployment.

Search without a client install

The server exposes search, browse, read_session, and stats as normal MCP tools. Add the URL to Claude Code, Codex, Cursor, OpenCode, or another remote MCP client. Code Mode can call those tools from its own REPL; it does not need the Brain Python package.

Publishing is the one local step. The server cannot read ~/.claude, ~/.codex, or Cursor's local databases. Run the publisher once through uv without installing it:

uvx --from git+https://github.com/sdrshn-nmbr/brain@v1.1.0 brain-sync \
  --endpoint https://brain.your-tailnet.ts.net/mcp \
  --repository github.com/example/widget \
  --visibility "Example engineering" \
  --dry-run

The dry run writes a local archive but sends no transcript data. Read the printed scope, then publish that exact archive:

uvx --from git+https://github.com/sdrshn-nmbr/brain@v1.1.0 brain-sync \
  --endpoint https://brain.your-tailnet.ts.net/mcp \
  --archive "$HOME/Downloads/agent-chats-export-<timestamp>.zip"

Brain asks before upload. Use --yes only after a person or approved automation has accepted that exact scope.

Codex Desktop side chats

Codex does not always put complete Desktop side chats in its normal session files. Brain includes a small opt-in proxy that records future side-chat prompts, assistant replies, and tool events under ~/.codex/attachments/sidechats/*.jsonl:

uvx --from git+https://github.com/sdrshn-nmbr/brain@v1.1.0 brain-sidechat-recorder --install-hook
export CODEX_CLI_PATH="$HOME/.codex/bin/brain-sidechat-recorder"

Start Codex Desktop from an environment containing that variable. The hook is local and contains only Python standard library code. Recording failure never blocks Codex. These files can contain sensitive tool data. Brain uploads a recorded side chat only when its saved working directory resolves to an allowed repository and the user confirms the archive. Arbitrary files from ~/.codex/attachments are never uploaded.

On a remote Linux host that Codex Desktop reaches over SSH, the Desktop runs codex app-server proxy with ~/.local/bin first on PATH. Link the recorder there instead. It finds the real codex further down PATH and passes every other command, including the app-server --listen daemon, straight through:

uvx --from git+https://github.com/sdrshn-nmbr/brain brain-sidechat-recorder --install-hook
ln -sfn "$HOME/.codex/bin/brain-sidechat-recorder" "$HOME/.local/bin/codex"

Recording starts with the next Desktop connection. Set CODEX_SIDECHAT_DISABLE=1 or remove the link to turn it off.

Scope and access

Scope is checked by the exporter, upload server, and ingester. Repository IDs include the Git host, such as github.com/acme/api or gitlab.example.com/platform/models/recommender.

Tailnet users get append access by default. Named admins get observability tools. Tagged workloads need a Tailscale app capability and receive the access it grants. The included policy templates show read, append, and admin grants for fine-grained access. Bearer tokens and trusted proxy headers remain explicit alternatives.

Personal mode

One person can run Brain over every agent session on every machine they use. Set BRAIN_MODE=personal and leave BRAIN_ALLOWED_REPOSITORIES unset. The server then accepts sessions from any folder and files each session under the machine that uploaded it, so search can narrow with person=mac or person=devbox. Folders without a Git origin are kept as local:<cwd>.

Each machine publishes on a timer:

uvx --from git+https://github.com/sdrshn-nmbr/brain brain-sync \
  --endpoint https://brain.your-tailnet.ts.net/mcp --machine mac

--machine is the standing consent for that machine: it publishes without a prompt and only re-reads session files changed since its last successful run. Keep personal mode behind an identity that only you hold, such as BRAIN_TAILSCALE_ALLOWED_USERS set to your own login.

Why SQLite

The current bottlenecks were query shape, archive packaging, and connection reuse. After those fixes, local SQLite FTS search is fast and the single-writer design stays easy to operate. Brain keeps reads online during atomic ingestion and uses a separate append-only object database for deduplicated bodies.

Possible future directions:

• A Turbopuffer backend for lexical search, vector search, and other indexes, with S3 for session bodies.

• Postgres or Turso when a deployment needs several writers or a managed database.

• Go, Rust, async pipelines, or SIMD JSON parsing if profiles show CPU parsing is the next real limit.

These are options, not required complexity.

How search ranks

Search combines two candidate lists. Full-text search ranks bodies that contain every query term by BM25. A vector index ranks user and assistant messages by meaning, so a question can find an answer that uses different words. Reciprocal rank fusion merges the lists. A session scores by its best message plus smaller shares of its next two, so one strong match outranks several weak ones. Quoted phrases stay keyword-only.

Agent harnesses store some of their own text under the user role. Search gives injected instructions, such as AGENTS.md blocks, skill bodies, and environment context, 30% weight so they can still find a session that loaded a skill without crowding out what people wrote. A Codex auto-review session copies the transcript it reviews, including tool output that default search skips, so its matches count toward the reviewed session and the copy itself is not returned. App-generated suggestion requests are left out. This classification is rebuilt in memory at startup and after each upload.

The vectors live in vectors.sqlite beside the index, through sqlite-vec, and searches score a normalized copy held in memory: about 5 ms for 260,000 vectors and 0.5 GB of RAM. Search takes the 2,000 nearest messages and keeps the 200 best that match the filters, so a repository-scoped search still gets semantic results. A small static embedding model, minishlab/potion-retrieval-32M by default, runs on the server CPU, so no text leaves the machine. New messages are embedded after each upload. Changing BRAIN_EMBEDDING_MODEL rebuilds the vectors on the next start; none turns semantic search off.

A personal Brain also learns from use. It records each search, and a read credits the most recent search within 15 minutes that returned that session. Sessions that keep proving useful rank higher. A team Brain records neither queries nor reads.

brain-eval measures a ranking or model change before it is kept. It replays logged searches that led to a read, using only the usage learned before each search, and builds known-item queries from sampled sessions: three uncommon words from one message, and a session's three most characteristic words drawn from different messages. It reports recall@10, MRR, empty results, timeouts, the share of results that are review copies or generated sessions, and latency. Query generation stays on the server, so no conversation text leaves the machine. --relabel rebuilds the read credits from the request log; --usage-dir points it at a copy first.

--judge-model MODEL also grades the top results of sampled logged queries with a model at OPENAI_BASE_URL, which sends their excerpts to that endpoint, and reports nDCG@10 and precision. Grades are cached by query and session in judgments.json, without excerpt text, so scoring a second ranking reuses them and both are compared against the pooled best ordering.

Develop

uv sync --frozen
just check

just check runs Ruff, ty, the full test suite, and package build. Brain uses Pydantic models at its MCP boundary and checks them with ty's Pydantic-aware type analysis.

The service uses one writable process and one persistent data directory. See architecture for the storage and consistency rules.

Apache-2.0. See LICENSE.