agentbrain MCP server
Commit Nov 15, 2026Provides local-first long-term memory for AI agents using a plain Markdown vault and CJK-aware BM25 retrieval.
Also known as 2672243194/agentbrain
- Stars
- 6
- Tools
- 10
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- —
What is agentbrain MCP?
agentbrain provides local-first long-term memory for AI agents using a plain Markdown vault and CJK-aware BM25 retrieval. It exposes 10 tools, such as lesson_id, lesson_version, outcome.
Summary generated from the project's README
About agentbrain MCP server
Providing long-term memory for AI agents through a local Markdown vault is what agentbrain enables. It allows developers to store lessons, preferences, and case studies in a plain text format that remains accessible even without the server, making it compatible with tools like Obsidian or Git. The system uses CJK-aware BM25 retrieval and an index-first approach to ensure token efficiency during searches.
Users set up the server locally by installing the mnemosyne-lite package and running the serve command. It integrates with various clients including Claude Code, Cursor, and Open WebUI via standard MCP configurations. The server includes built-in security to prevent secrets from entering the vault by scanning for credential-shaped content during ingestion. It also supports an append-only workflow where agents create lessons and humans approve consolidations through a proposal system.
What you can do with it
- 1Retrieve past technical lessonsAsk the agent to search for specific deployment or operational experiences using the query tool.
- 2Automate agent onboardingDirect a new agent to read the onboarding documentation to configure its own access mode.
- 3Securely store environment preferencesUse placeholders for sensitive variables so that agents can reference environment settings without storing actual keys.
Written from the project's README. Every use case is checked against a quote from it.
agentbrain MCP tools 10
Detected from the READMElesson_idlesson_versionoutcomeenvironmentevidencehelpfulpartialineffectivenot_applicableunverified
Configuration
AGENTBRAIN_VAULT
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachable2672243194/agentbrain is public and reachablegithub.com/2672243194/agentbrain ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-10-29github.com/2672243194/agentbrain ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model10 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubagentbrain
Local-first long-term memory for AI agents — a plain Markdown vault + a thin MCP server. 给 AI Agent 用的本地长期记忆:纯 Markdown 知识库 + 薄 MCP server。
三步上手 / Quick start (3 steps)
pip install mnemosyne-lite # Python >= 3.10(PyPI 包名;命令仍是 agentbrain)
agentbrain init ~/agentbrain # 建立记忆库(幂等,可重复执行)
agentbrain doctor # 自检:一切正常会显示 "Everything looks healthy."
{
"mcpServers": {
"agentbrain": {
"command": "agentbrain",
"args": ["serve"],
"env": { "AGENTBRAIN_VAULT": "~/agentbrain" }
}
}
}
AGENTBRAIN_VAULT 可省略(默认 ~/agentbrain);vault 在别处时才需要写,路径按你的实际情况改。将 command、args、env 填入客户端的 MCP 配置入口;支持 mcpServers 导入的客户端可直接使用上面的 JSON。不同客户端的配置格式可能不同,DSH 桌面版请见下方专节。重启客户端后即可访问共享记忆库。
以后接入新的 agent 不用你教:对它说一句「读 AGENTS.md 照做」即可——文件开头会把新来者引导到 ONBOARDING.md,它自己就能判断接入状态(已接 MCP / 只有 shell / 只能读文件)并完成配置或降级。
Use that JSON in clients accepting mcpServers, or enter its command, arguments and environment in your client's MCP settings. Restart the client to connect to the shared vault. See the DSH desktop section below for its profile format.
Why agentbrain / 设计理念
- Plain Markdown, no lock-in — your memory is a folder of
.mdfiles. Open it in Obsidian, grep it, version it with Git. Remove agentbrain and the memory stays. - Token-efficient by design — index-first retrieval:
Index.mdis the cheap first layer, BM25 (CJK-aware) only ranks candidates, and query output is compact by default (mode='index'); full text only on demand. - Append-only for agents — agents may create lessons, never edit or delete them.
Consolidation happens through proposals in
_consolidations/that a human approves, which keeps multi-agent writes conflict-free. - Plug-and-play via MCP — one server, every client: Claude Code, Codex CLI, OpenCode, Cursor, DSH, Open WebUI, ...
- Secrets never enter the vault — credentials live in env/keyring; lessons reference
${ENV:VAR_NAME}placeholders only, resolved at runtime via shell. Since 0.4.1 this is enforced, not just a rule:memory_ingestscans for credential-shaped content (sk-/ghp_/AKIA/xox-/AIza keys, bearer tokens, private-key blocks,password=assignments) and refuses the write, telling the agent to use a placeholder instead. Placeholders and teaching examples (sk-xxx,YOUR_KEY) ingest fine.lintalso scans existing lessons and reportsSECRETfindings — read-only, never rewrites files. Hand-written files are never touched.
Vault layout
agentbrain/ # vault root (git-friendly, Obsidian-friendly)
├─ AGENTS.md # rules every agent reads at session start
├─ ONBOARDING.md # one-shot access setup for new agents
├─ Case-Learnings/
│ ├─ Index.md # auto-generated lesson index (retrieval layer 1)
│ ├─ log.md # append-only audit log
│ ├─ Learnings/ # one lesson per file, YAML frontmatter
│ │ └─ case-001-lesson-01.md # 文件名 = {case_id}-lesson-{NN},自动生成
│ ├─ _consolidations/ # merge/promotion proposals (human approval)
│ └─ _feedback/ # reported outcomes, created on first feedback
└─ Agent-Profile/
├─ Immutable/ # owner preferences & environment (agent read-only)
├─ Mutable-Hints/ # soft preferences (agent read-only)
└─ _suggestions/ # agent-suggested profile changes
中文快速上手
pip install mnemosyne-lite # Python >= 3.10
agentbrain init ~/agentbrain # 生成 vault 脚手架(幂等),自动开启 Git 快照
agentbrain doctor # 体检:vault/索引/锁/快照/log 一览
agentbrain ingest --case demo --lesson "部署前必须先跑迁移脚本" --tags 部署,运维
agentbrain query "部署 迁移"
agentbrain read demo-lesson-01 # 读取确认相关的记忆,并记录实际使用
agentbrain stats # 查看利用率统计
agentbrain profile # 查看个人偏好(Immutable + Mutable-Hints)
agentbrain suggest --title "回复用中文" --change "偏好简洁的中文回复" # 提交偏好建议
agentbrain lint # 体检:重复/过时/无标签/低置信度 → 生成整合提案
agentbrain apply lint-20260820-172206.md # 人工审核后执行提案(自动归档)
agentbrain verify my-case-lesson-01 # 重新确认某条经验仍然有效(消除 lint 的 STALE)
agentbrain distill # 分析 log 中重复出现的模式 → 生成提升提案
agentbrain snapshot -m "手动备份" # 手动提交快照(如用 Obsidian 手改文件后)
agentbrain rules --agent trae --write # 把记忆纪律写进客户端规则文件(项目根目录运行)
agentbrain rules --agent agentsmd --write # agents.md 开放标准,覆盖 OpenCode/Gemini CLI 等
agentbrain rules --agent claude --write --global # 写进用户级全局规则,所有项目生效
agentbrain install --agent codex --global # Codex:MCP + 全局纪律一键接入
升级到新版本后(pip install --upgrade mnemosyne-lite):
agentbrain upgrade # 刷新 vault 里的 AGENTS.md / ONBOARDING.md 模板
agentbrain rules --agent trae --write # 刷新各项目规则文件里的纪律块(旧版会原地更新)
# 然后重启你的 agent 客户端 —— MCP server 是进程启动时加载代码的
说明:PyPI 包名为
mnemosyne-lite(agentbrain在 PyPI 上与已有项目过于相似,无法注册)。 安装后的 CLI 命令与 Python 包名仍是agentbrain,GitHub 仓库地址不变。
日常你只需要做三件事(频率都很低):
| 事 | 命令 | 频率 |
|---|---|---|
| 想看库健不健康 | agentbrain doctor |
随意 |
| 记忆整理(清重复/过时) | agentbrain lint → 审核 → agentbrain apply <提案> |
约一周一次 |
| 手改文件后备份 | agentbrain snapshot |
改完就跑 |
支持服务器 instructions 的客户端会获得默认引导:首次实质任务读偏好,任务前检索并选读相关经验,核对适用条件后使用;任务或子任务有结果后按需批量反馈;新经验须经过验证、查重并符合宿主授权规则后入库。客户端是否实际调用工具取决于其实现和规则,服务端不能保证自动执行。
在 MCP 客户端里接入(以 Claude Code 为例):
claude mcp add agentbrain -- agentbrain serve
通用 MCP JSON 配置(Cursor / Open WebUI 等):
{
"mcpServers": {
"agentbrain": {
"command": "agentbrain",
"args": ["serve"],
"env": { "AGENTBRAIN_VAULT": "~/agentbrain" }
}
}
}
AGENTBRAIN_VAULT 可省略(默认 ~/agentbrain);vault 在别处时才需要写。
Vault 路径解析顺序:--vault 参数 > AGENTBRAIN_VAULT 环境变量 > ~/agentbrain。
注册 MCP 后,支持 instructions 的客户端可获得按需记忆工作流。对于忽略 instructions 的客户端,或需要显式配置工作流时,可把纪律写进客户端规则文件(在项目根目录运行,幂等可重复):
agentbrain rules --agent claude --write # 支持 claude / codex / trae / cursor / agentsmd(项目级)
agentbrain rules --agent agentsmd --write # agents.md 开放标准:OpenCode、Gemini CLI、Amp 等都遵守
agentbrain rules --agent claude --write --global # 用户级全局(~/.claude/CLAUDE.md),一次配置所有项目生效
该命令写入「任务前检索并选读、同主题复用、遇到未覆盖问题再查、有结果后批量反馈、经验证且授权后查重入库、密钥不入库」到 CLAUDE.md / AGENTS.md / .trae/rules/ / .cursor/rules/。TRAE 和 Cursor 的全局规则在各自设置界面里,不走文件;claude / codex 支持 --global。
Onboarding a new agent later needs no instructions from you: just tell it
"read AGENTS.md" — the file routes first-timers to ONBOARDING.md, where they
detect their own access mode (MCP tools / shell / file-only) and wire themselves
up or fall back accordingly.
DSH 桌面版 / DSH desktop
以下配置按 DSH 桌面版 0.2.0-rc.2 的 MCP 插件核对。桌面版使用独立的 desktop profile,不能用全局 dsh CLI 的版本或配置代表桌面版,也不要把上面的 mcpServers JSON 直接写入 YAML 文件。
在安装 agentbrain 的 Python 环境中运行 agentbrain doctor,获取当前解释器的绝对路径、参数和 Vault 路径。将对应字段合并到 ~/.dsh/profiles/desktop/cordis.patch.yml 的顶层列表中;若已有 id: mcp-agentbrain,更新该条目即可,保留其他插件和用户配置。
- insert:
- id: mcp-agentbrain
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: agentbrain
transport: stdio
command: 'C:\agentbrain-env\python.exe'
args: ['-I', '-m', 'agentbrain', 'serve']
env:
AGENTBRAIN_VAULT: 'C:\Users\<用户名>\agentbrain'
示例路径需要替换成实际安装位置。使用绝对解释器路径可避免桌面程序选中另一个 PATH 中的 Python。doctor 仅在自身以 -I 启动时保留隔离模式;如果使用 pip install --user,不要额外添加 -I,否则 Python 会忽略用户安装目录。
完整退出并重新打开 DSH 桌面版后,新建会话并请求调用 mcp__agentbrain__memory_stats 验证连接,再用实际任务检查 memory_profile → memory_query → 相关 memory_read 的使用。工具列表可能在断线期间保留,仅看到工具名称不能证明连接正常。
该版 DSH 会把服务器 instructions 加入系统提示,但是否主动调用仍取决于模型和会话规则。工具拒绝操作会以 MCP isError 标记失败;成功的无命中查询仍是正常结果,部分 ID 缺失的读取会保留已找到的正文并列出缺失项。
English quickstart
pip install mnemosyne-lite # Python >= 3.10
agentbrain init ~/agentbrain # scaffold the vault (idempotent), enables git snapshots
agentbrain doctor # health check: vault, index, lock, snapshots, log
agentbrain ingest --case demo --lesson "Always run migrations before deploy" --tags deploy,ops
agentbrain query "deploy migrations"
agentbrain profile # print the owner profile
agentbrain suggest --title "Short replies" --change "Keep answers under 3 sentences."
agentbrain lint # health check → consolidation proposals
agentbrain apply lint-20260820-172206.md # execute an approved proposal (archives it)
agentbrain verify my-case-lesson-01 # re-confirm a lesson is still valid (clears STALE)
agentbrain distill # recurring-pattern analysis → promotion proposals
agentbrain snapshot -m "manual backup" # commit a snapshot (e.g. after hand-edits)
agentbrain rules --agent claude --write # install memory discipline into the client's rule file
agentbrain serve # start the MCP server on stdio
After upgrading the package (pip install --upgrade mnemosyne-lite):
agentbrain upgrade # refresh AGENTS.md / ONBOARDING.md templates in the vault
agentbrain rules --agent claude --write # refresh the discipline block in project rule files
# then restart your agent clients — MCP servers load code at process start
Note: the PyPI distribution name is
mnemosyne-lite(agentbrainwas rejected as too similar to an existing PyPI project); the installed CLI command and the Python import name remainagentbrain.
Codex CLI (~/.codex/config.toml):
[mcp_servers.agentbrain]
command = "agentbrain"
args = ["serve"]
Registering MCP also supplies server instructions to supporting clients. Clients may ignore them; server configuration cannot guarantee tool calls. For explicit client guidance, write the discipline block into the project's rule file (run in the project root, idempotent):
agentbrain rules --agent codex --write # per-project AGENTS.md
agentbrain rules --agent codex --write --global # user-level ~/.codex/AGENTS.md
Or configure both MCP and the discipline block in one step:
agentbrain install --agent codex --global
It installs a short "agentbrain memory discipline" section into CLAUDE.md,
AGENTS.md, .trae/rules/ or .cursor/rules/: query and selectively read before
work, check applicability, reuse previously read lessons, and re-query for
uncovered subtasks/errors. Batch feedback after task/subtask evidence is available.
Ingest only verified, reusable findings after
duplicate checks and under host authorization rules; never store secrets.
The agentsmd target writes the agents.md open standard file,
followed by OpenCode, Gemini CLI, Amp and other standard-compliant tools.
TRAE and Cursor keep their global rules in their settings UIs;
claude and codex support --global.
MCP tools
| Tool | Purpose |
|---|---|
memory_query(query, top_k=5, mode="index", tag=None) |
Search lessons. mode='index' returns compact hits (id, summary, tags, path, gist); mode='full' adds full text; tag narrows results to one tag. |
memory_read(lesson_ids) |
Read up to 10 unique IDs and record full-text reads. Includes a content version for later feedback. Superseded IDs point to replacements; expired lessons are historical context and do not increase counts. |
memory_feedback(task_id, entries) |
Record up to 10 lesson outcomes with versions, environment and evidence. Same task/lesson/version retries are idempotent; conflicting reports are refused. |
memory_stats() |
Show active (not superseded, including expired), retired, read, unread and most-read lesson counts, plus separately reported feedback outcomes. Reads do not establish adoption; feedback is reported evidence, not automatic verification. |
memory_ingest(case_id, lesson, tags, confidence=0.8, source_summary=None) |
Save a new lesson (facts + scenario + fix, ≤ 30 lines). Creates a file, updates Index.md and log.md. |
memory_lint(scope="all") |
Health check: duplicates, stale, expired, untagged, low-confidence. Writes a merge proposal to _consolidations/. |
memory_distill(window_days=30, min_repeat=3) |
Finds cases/tags ingested ≥ N times in the window and writes a promotion proposal. |
memory_profile() |
Returns the owner profile (hard rules + soft preferences). Read-only; agents call it once per session to tailor behavior. |
memory_suggest(title, change) |
Proposes a profile change into Agent-Profile/_suggestions/ for the owner to review — agents never edit the profile itself. |
memory_stats reports cumulative read counters and separate feedback totals, not
complete recent activity or automatically verified task success. Read timestamps
are not recorded; task outcomes exist only when explicitly reported through
memory_feedback. Read-count changes are saved
with the next content snapshot, so a snapshot date is not the read date. Older
Vaults may also include counts from index queries recorded by earlier versions.
For scripted CLI use, rejected query, ingest, suggest and read requests
exit with code 2. read returns 1 when only some requested IDs exist, and 0 when
all IDs are handled. A successful query with no matches still returns 0.
经验效果反馈 / Outcome feedback
在任务或子任务有可核对的结果后,遵守宿主授权规则,一次批量提交相关经验的反馈;不要每读一次就调用,也不要要求用户逐条打分。use_count 继续只表示读取次数。没有反馈不代表经验无用,整个任务成功也不能证明每条读过的经验都发挥了作用。
memory_feedback 接受一个稳定且不包含敏感信息的 task_id,以及最多 10 条 entries。不同任务使用不同标识;同一任务的重试沿用原标识。每条包含:
| 字段 | 含义 |
|---|---|
lesson_id |
实际评估的经验 ID |
lesson_version |
从当时的 memory_read 或 memory_query(mode="full") 输出复制的内容版本;不能猜测或用新版本替代旧证据 |
outcome |
下表中的一种结果 |
environment |
简短说明实际环境、版本或适用条件 |
evidence |
一句话说明该条经验的具体作用或失败证据;结果不明时说明尚未验证的原因 |
outcome |
使用条件 |
|---|---|
helpful |
实际采用,并有证据说明它带来了帮助 |
partial |
部分步骤有帮助,还需要补充条件或措施 |
ineffective |
条件匹配且正确执行后仍无效,或发现了经验错误 |
not_applicable |
环境、版本或前提不匹配;不视为经验错误 |
unverified |
尚无足够证据判断效果;不计为好评或差评 |
反馈单独保存为 Case-Learnings/_feedback/*.md,不修改原经验、Immutable、置信度或检索排序。相同任务、经验和内容版本的相同请求不会重复计数;冲突反馈会被拒绝,不覆盖历史。反馈受密钥检查和长度限制,不保存猜测、聊天流水账、未经测量的 token 节省量。通过 memory_stats / agentbrain stats 查看分类总数,或直接阅读反馈 Markdown 查看上下文。
Feedback is a separate, version-bound report of observed contribution. Submit a batch when evidence is available, retain the task ID on retries, and distinguish failed advice from an inapplicable environment or an unverified result. Reports are not independent ground truth and do not automatically change lesson ranking, confidence or content. Feedback is available through MCP; there is no feedback CLI command. Older clients need a server restart to discover the new tool; actual use still depends on the client, model and host authorization rules.
MCP resources
| URI | Content |
|---|---|
agentbrain://rules |
AGENTS.md — vault rules for every agent |
agentbrain://index |
Case-Learnings/Index.md — retrieval layer 1 |
agentbrain://profile |
merged owner profile (read-only) |
Agents are expected to follow AGENTS.md in the vault root: read the profile once
for substantive work, query and selectively read before applying lessons, and
save verified findings after duplicate checks and under host authorization.
Never edit existing lessons or write secrets into the vault. Consolidation proposals carry
machine-readable directive blocks (```agentbrain); only the owner
executes them via agentbrain apply.
Design notes
- Retrieval scoring: BM25 over summary (×3), tags (×2), case id and body, with a
CJK bigram tokenizer so Chinese queries work out of the box; results are boosted by
verified,use_countand recentlast_verified_at, demoted when stale (> 1 year). - Self-maintenance signals: compact query hits do not increment
use_count. Explicitmemory_readand full-mode queries count non-expired, non-superseded reads once per ID per call; counts do not measure adoption or task success. Version-bound feedback records reported outcomes separately and does not alter these counters or ranking. No feedback is not evidence of failure.log.mdfeedsmemory_distillpattern analysis;lintrefreshes nothing silently — every mutation of history goes through human-approved proposals. - Single-user, local-first: no daemon, no ports; concurrent writes from several
agents are serialized by an OS-level byte-range lock (
.vault.lock, msvcrt/fcntl — released instantly if the holder crashes), and all file writes are atomic (temp + rename) so readers never see torn files. - Point-in-time recovery: every vault is its own git repo (created by
init, repo-local identity only). Each content write — ingest, apply, lint/distill proposal, suggestion, index rebuild — is auto-committed, so any bad edit can be rolled back with plain git. Query-drivenuse_countbumps ride along with the next content commit instead of polluting history. Works fully without git; if git is missing, snapshots are silently disabled. Individual file replacements are atomic; a disk failure can still interrupt a multi-file operation.
agentbrain MCP questions
What tools does agentbrain MCP provide?
It exposes 10 tools, including lesson_id, lesson_version, outcome, environment, evidence.
Is my data locked into this tool?
No, your memory is stored as a folder of plain Markdown files that can be opened in Obsidian, versioned with Git, or searched with grep.
How does the server handle sensitive information like API keys?
The server prevents secrets from entering the vault by scanning for credential-shaped content and refusing the write, requiring agents to use environment variable placeholders instead.
Can I use this with Claude Code or Cursor?
Yes, it supports various clients including Claude Code, Cursor, OpenCode, and DSH via MCP configuration.