brain-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@brain-mcp what did we decide about Firestore regions?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
brain-blueprint
Long-term memory for coding agents, done with files you can read.
Agents forget everything between sessions. Most memory layers fix that with a vector database you can't open, edit or review. This repo takes the other road, the one Claude Code's auto memory, Letta's MemFS and Basic Memory have converged on in 2025-2026: memory is a folder of Markdown notes, and the database is only an index you can delete.
It contains two things:
The blueprint. How to structure an agent's long-term memory: the note schema, the lifecycle (recall, encode, link, supersede, validate), ranking, the protocol you give the agent, and how to evaluate it.
A reference implementation. A small MCP server in Python (SQLite FTS5, under 400 lines, tested) that plugs into Claude Code, Claude Desktop, Cursor or any MCP client.
The design in six rules
One note, one idea. A Markdown file with typed YAML frontmatter. The
descriptionline is written so an agent can decide to open the note without opening it.Files are the truth, the index is disposable. Humans can edit notes by hand; the index catches up on the next call.
Recall before acting. The agent searches memory before any non-trivial step, then reads only the 1-3 best hits.
Rank on more than relevance. Score = BM25 relevance × confidence × freshness. Every factor is a number you can inspect when recall goes wrong.
Supersede, never overwrite. A contradicted note is marked
superseded, linked to its replacement and hidden from search, but its history stays. This mirrors how Graphiti invalidates facts instead of deleting them.Link across themes. Notes live in cortices (one folder per theme). Links between cortices are where the value is.
Related MCP server: akasha-mcp
Quickstart
git clone https://github.com/2soum/brain-blueprint && cd brain-blueprint
uv sync
BRAIN_DIR=./examples/brain uv run brain-mcp # stdio MCP serverAdd it to Claude Code:
claude mcp add brain -e BRAIN_DIR=$HOME/brain -- uv --directory $PWD run brain-mcpThen paste templates/AGENTS.md into your CLAUDE.md or AGENTS.md, so the agent knows when to recall and when to write.
Tools
Tool | What it does |
| Ranked recall. Returns id, title, description and score. |
| Full note, frontmatter included. |
| Cortices with counts, or the notes of one cortex. |
| Store a new note. Never overwrites: a clashing id gets a suffix. |
| Link two notes both ways. |
| Retire a note in favour of a newer one. |
| Record that a note was re-checked today. |
What a note looks like
---
id: firestore-region-europe-west1-for-eu-prospect-data
title: Firestore region europe-west1 for EU prospect data
type: decision
cortex: infra
description: EU prospect data stays in the EU; a Firestore region cannot change after creation.
tags: [firestore, region, gdpr]
confidence: 0.95
created: 2026-10-27
last_validated: 2026-10-27
status: active
links:
- to: firestore-region-us-central1
rel: supersedes
---
> For the next agent: create every new Firestore database in eur3 or europe-west1.
> Moving later means a migration.Browse examples/brain for a small brain with links and a superseded decision.
How it compares
Storage | Recall | Contradictions | |
brain-blueprint | Markdown + SQLite FTS5 | BM25 × confidence × freshness | Supersede with history |
Claude Code auto memory | Markdown + | Index always loaded, files on demand | Manual edits |
Basic Memory | Markdown + SQLite/Postgres | Full-text + vectors + graph | Manual edits |
Letta | Memory blocks + archive; git-backed MemFS (2026) | Blocks in context + search tools | Rewrite, git history |
mem0 | Vector facts, optional graph | Vectors (+ BM25 with extras) | LLM picks ADD / UPDATE / DELETE |
Graphiti / Zep | Bi-temporal knowledge graph | Vectors + BM25 + graph traversal | Facts invalidated with a timestamp |
MCP reference | JSONL entities and relations | String matching | Manual deletes |
Details, sources and caveats on published benchmark numbers are in docs/landscape.md.
Roadmap
Optional embeddings and Reciprocal Rank Fusion for paraphrase recall.
Graph expansion: return the neighbours of the top hits.
A background
consolidatepass to merge duplicates and flag stale notes.An evaluation harness on LongMemEval-style questions (updates, abstention).
Development
uv run pytest -q
uv run ruff check src testsMIT licensed. Built by Dayssam Bakaar.
Available Tools
7 toolsbrain_encodeA
Store one durable learning: a fix that worked, a constraint, a preference, a decision.
Start the body with a 2-3 sentence blockquote addressed to the next agent.
Pick an existing cortex when one fits (see brain_list); create a new one only for a new theme.
Inputs: body (required), title (required), cortex (required), tags, +3 more.
brain_linkC
Link two notes both ways. Links across cortices are the most valuable.
Inputs: a (required), b (required), rel. Returns: result
brain_listB
List cortices with their note counts, or the notes of one cortex.
Inputs: cortex.
brain_readB
Return the full Markdown of one note, frontmatter included.
Inputs: id (required). Returns: result
brain_searchA
Recall notes relevant to a task. Call this before any non-trivial step.
Returns id, title, description and score; open the promising ones with brain_read.
Inputs: query (required), k, cortex, include_superseded. Returns: result
brain_supersedeB
Retire an outdated note in favour of a newer one. Never edit history in place.
Inputs: new (required), old (required), reason (required). Returns: result
brain_validateB
Mark a note as re-checked today, optionally with a new confidence.
Inputs: id (required), confidence. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool maps to a distinct action on notes: browse (list), create (encode), relate (link), retire (supersede), re-check (validate), find (search), open (read). The only mild overlap is between brain_list and brain_search, both retrieval paths, but descriptions differentiate enumeration from query-based recall.
Every tool follows a uniform brain_<verb> pattern (brain_list, brain_encode, brain_link, brain_supersede, brain_validate, brain_search, brain_read). Fully predictable and consistent.
Seven tools is well-scoped for a note-memory system, covering browse/search/read/create/link/supersede/validate without redundancy. Each tool earns its place.
The lifecycle is well covered: create, retrieve, relate, retire, and confidence-update, with intentional design that history is never edited in place. Minor gap is no explicit cortex management or bulk cleanup, though cortex creation is folded into encode.
Related MCP Connectors
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Notes and memory assistant: one Markdown vault that Claude, ChatGPT and any MCP client can share.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables coding agents to store, search, and retrieve long-term memory as plain Markdown files with a disposable SQLite index, including note management, decision/bug tracking, and codebase symbol lookup via MCP.8MIT
- AlicenseNot gradedqualityBmaintenanceGives coding agents a persistent memory by searching a local, read-only index of existing markdown and letting them write findings back as notes that the next session can retrieve. It serves ranked, context-sized results over MCP, injects standing conventions at session start, and keeps data on your machine with secret redaction and archive-only deletion.111 PyPIMIT
- FlicenseNot gradedqualityAmaintenanceEnables Claude and other MCP-compatible clients to create atomic notes, link them with semantic relationship types, tag and search them, and traverse the resulting knowledge graph for exploration and synthesis. Notes are stored as human-readable Markdown files that remain the source of truth, with a rebuildable SQLite index for fast querying.-
- FlicenseNot gradedqualityAmaintenanceEnables users to create, link, search, explore, and synthesize atomic notes through Claude and other MCP-compatible clients, using Markdown files backed by a SQLite index.-