The old article had a useful subject and a bad shape. It made persistent memory sound like a general collaboration upgrade, then leaned on token-saving numbers without enough source context. That is the part to cut.
The better article asks an operational question: when Claude Code agents start new sessions or new teammates, what context should they inherit, who approved it, where is it stored, and how does the team remove stale rules? claude-teams-brain has enough source material to answer that question. It is a local memory layer built from hooks, SQLite, FTS5 search, MCP tools, command-output filtering, and explicit memory commands.
Why this seed is worth saving
The idea is useful because Agent Teams have a real continuity problem. A backend agent can learn the auth layout today, then a fresh backend agent can start tomorrow without that history. Teams try to patch this with longer prompts, copied transcripts, or a growing CLAUDE.md. Those fixes work until they become noisy.
claude-teams-brain is interesting because it does not treat memory as one blob. The source separates runs, tasks, decisions, files touched, knowledge-base chunks, role-specific queries, manual memories, and command output. That structure gives reviewers handles. A team can ask what the backend role will receive, which decisions are being injected, which files that role touched, and which memories are still pending.
The architecture claim
The core architecture is local and inspectable. The brain engine creates ~/.claude-teams-brain/projects/<project-hash>/brain.db, unless CLAUDE_BRAIN_HOME overrides the base directory. Inside the SQLite database, it defines tables for runs, tasks, decisions, file indexes, and knowledge-base chunks. It also creates FTS5 indexes for task and KB search, with trigram fallbacks when the SQLite build supports them.
That matters more than the product claim. A team can inspect a local database, export conventions, clear a project, or ask why a role received a given memory. This is the difference between “the agent remembers” and “the team can audit the memory substrate.”
Hooks turn sessions into records
The hook config is the first source-backed mechanism. It wires Claude Code lifecycle events into hook_runner.py: SessionStart, SubagentStart, TaskCompleted, SubagentStop, TeammateIdle, PreToolUse, and SessionEnd. The runner then calls brain_engine.py commands to index session starts, task completion, subagent stops, and pre-tool context.
This is also the first adoption boundary. Hooks are powerful because they collect context without asking the user to paste summaries. Hooks are risky because they can collect the wrong context at the wrong time. Before a team enables this for a repo, it should know which events are installed, where the DB is, and how to clear or export the memory.
Role injection is a query, not magic
The strongest implementation detail is query-role. When a teammate starts, the engine looks for prior work by role or agent name, ranks tasks against the new task description, pulls manual project rules, deduplicates team decisions, searches KB chunks, includes recent team work when role history is thin, and caps the final injected text with CLAUDE_BRAIN_CONTEXT_BUDGET. The default is 6000 characters.
That cap is important. Memory should compete for context like any other input. For Claude Code, this means a backend agent should not receive every frontend discussion ever stored. For Codex-style workflows, the same lesson applies: role memory is useful only when it is scoped, ranked, and small enough to leave room for the current diff.
Approval is the safety feature
The old article mentioned memory but did not make approval central. It should. The engine assigns manual remember entries a PENDING confidence, and the /brain-approve skill exposes the review path: list pending items, approve one item, or approve all pending items.
That is the right workflow. A developer might store “all endpoints need auth,” “prefer PaymentIntents,” or “never touch generated clients by hand.” Those rules can be valuable, but stale rules are worse than no memory. A team should approve explicit rules, reject outdated ones, and use /brain-query <role> before major work to see what would actually be injected.
Command output belongs in a KB
The MCP side is the other half of the project. The README lists five tools: batch_execute, execute, search, index, and stats. The server indexes raw command output into the local KB, then returns filtered output to the model. That split is sensible: keep the evidence searchable, but avoid dumping every passing test line into active context.
The output filter strips ANSI/progress noise, deduplicates logs, extracts failure blocks from pytest, JavaScript tests, cargo test, and go test, and has filters for git, build, Docker, process, and shell commands. The repo's percentage savings should be read as project claims, not independent benchmarks. The architectural point is stronger anyway: raw output should be retained as searchable evidence, while the agent sees the smallest useful summary.
A practical rollout path
A careful rollout should start small:
npx claude-teams-brain
# restart Claude Code
/brain-learn
/brain-status
/brain-query backend
/brain-remember all API endpoints require auth
/brain-approveFor an existing repo, /brain-learn extracts conventions from git history. For a new repo, /brain-seed nextjs-prisma or another profile can seed expected stack conventions. After a few sessions, use /brain-stats to inspect memory and KB state, /brain-search to find prior decisions, and /brain-export when you want a human-readable CONVENTIONS.md artifact.
Where it can go wrong
Persistent memory has a failure mode that short prompts do not: old context can become policy. If a project migrates from REST to tRPC, changes auth providers, renames modules, or deletes a service, stale memory can steer every future teammate in the wrong direction. The project has confidence levels, pending approvals, access-based promotion, stale demotion, reject and flag commands, and clear/export paths because memory needs maintenance.
Security is another boundary. The security policy says memory stays local and no data is sent to an external server, which is good. It also says shell commands executed through batch_execute or execute run with the same permissions as Claude Code. This is not a sandbox. Teams should not treat the MCP tools as safer than the underlying shell.
The Codex lesson
Even if a team does not use Claude Code Agent Teams, the pattern is useful for Codex and other agent stacks. Do not design memory as a magical transcript. Design it as a local system with schema, source labels, confidence, freshness, role filters, search, explicit approval, and a way to delete bad entries.
That is why this article should be saved. claude-teams-brain is not just a memory pitch. It is a concrete case study in turning agent memory into something operators can review before it becomes prompt context.
Save claude-teams-brain as an architecture deep dive, not a hype article. It is valuable when memory is local, queryable, scoped by role, and approved before injection; it is risky when teams let stale context become invisible policy.
Practical takeaway
If you adopt claude-teams-brain, start with one repo, run /brain-learn, inspect /brain-query <role> before trusting injected context, require /brain-approve for manual rules, use /brain-stats and /brain-search to audit what the system remembers, and keep /brain-clear or /brain-forget in the operating checklist for stale decisions.