Baron Munchausen

Baron Munchausen — 能跨越聊天会话的本地记忆

_{以上内容均为在全新克隆项目上实际运行的结果。rpc 是在 docs/demo/baron-demo.sh 中定义的两行 curl 封装；运行 cd docs/demo && ./record.sh 即可重新录制全过程。}

公开 Alpha 版（0.6.1）。 该引擎数月来一直在作者自己的工作中每日运行；这个代码仓库才刚创建一天。代码已完整，并采用 Apache-2.0 许可证——“Alpha”指的是打包、文档和安装流程。遇到任何问题，欢迎反馈。

会话结束了，项目还在继续。 只需一次调用，就能找回项目停下的位置、已做出的决定和接下来的工作——无论是关闭了标签页、用完了额度，还是更换了模型。每个基于这些记忆给出的回答都会附带判定结果：grounded、partial 或 ungrounded，并逐一列出没有依据的句子。

一个使用 Python 3.12 编写、没有第三方运行时依赖的记忆服务。通过 stdio 使用 MCP 与客户端通信，其他所有场景则通过 127.0.0.1:8765 上的 JSON-RPC 通信。这里没有任何内容会调用模型，也没有任何数据会离开你的设备。全新安装会从空图谱开始：我们提供工具，绝不提供数据。

为什么

三个数字，每一个都经过测量，而且都在旁边说明了它不能说明什么。

1. 单次上下文回填：7 146 个 token → 2 388 个 token。 7 146 是从会话记录中得到的一份真实压缩摘要，2 388 则是实时 memory_ground_prepare 针对同一项目的同一时刻返回的片段。两者均于 2026-09-10 使用 tiktoken/cl100k_base 计算。它不能说明的是： 这只是单组样本，并非一个分布——同一语料的另一份摘要有 5 913 个 token，因此同样的片段会使 token 数减少 60%，而不是 67%。

2. Claude Opus 5：输入 token 减少 69.6%，实测。 这不是根据上面的数字计算得出的，而是模型在 2026-09-10 对相同任务进行实际运行后，其自身 usage 报告的结果。相同运行中，Sonnet 5 减少了 61.7%，Haiku 4.5 减少了 66.3%。它不能说明的是： 这些数据来自作者的图谱和作者的任务。你的比率取决于上下文中有多少内容能从图谱中找回，而且目前还没有人在公开基准测试中运行过它。

3. 三十个工具，零个运行时依赖。 在全新克隆项目上运行 curl -s 127.0.0.1:8765/health，会返回 "tools": 30——通过 MCP stdio 和 JSON-RPC 都是相同的 30 个工具，且 requirements.txt 中没有第三方运行时包。它不能说明的是： 质量如何。这只是一个数量。

这些百分比能为你省下多少钱，取决于你使用的模型和调用量：**shinegang.click 上的费用计算器**会根据当前标价计算费用，并说明哪些数字是实测的，哪些是计算得出的。

两分钟完成安装

git clone https://github.com/shinegang/baron.git && cd baron

# 1. start the memory server — standard library only, nothing to install
bin/baron --host 127.0.0.1 --port 8765 --store blank

# 2. in a second terminal: it is up, the graph is empty, 30 tools are loaded
curl -s http://127.0.0.1:8765/health | jq '{product, version, nodes, tools}'

# 3. check the stdio bridge against the live server
python3.12 bridge/mnemos_bridge.py --selftest

# 4. register it with your MCP client (Claude Code shown; the rest are below)
bash integrations/baron_add.sh

第 2 步会输出 {"product": "Baron Munchausen", "version": "0.6.1", "nodes": 0, "tools": 30}。如果没有 jq，去掉管道并直接查看原始 JSON。

无需任何客户端，也能写入一条事实并获取判定结果——这与上方演示运行的是同一个 JSON-RPC：

curl -sX POST 127.0.0.1:8765/rpc -H content-type:application/json -d '{
  "jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"memory_add",
  "arguments":{"items":[{"claim":"The release build is pinned to Python 3.12.",
  "source":"team decision","kind":"rule"}],"session_id":"demo"}}}'

安装软件包（pip install .）后，同一服务会以 baron 的名称加入 PATH；在代码检出目录中运行 python3.12 -m baron 也可以启动服务。

客户端

任何支持标准 mcpServers JSON 配置块的客户端都可以使用 Baron。以下客户端已在 integrations/ 中准备好对应文件：

客户端	方法	文件
Claude Code	bash integrations/baron_add.sh	baron_add.sh
Codex	bash integrations/codex/register.sh	codex/
Cursor	复制到 ~/.cursor/mcp.json	baron_cursor_mcp.json
llama.cpp	复制到服务器配置文件旁边	baron_llama_cpp_mcp_servers.json
LangChain	一个可运行的 HTTP 端点调用示例	langchain_example.py
Claude Desktop	复制到 claude_desktop_config.json	baron_claude_desktop.json
其他客户端	stdio 使用 python3.12 bridge/mnemos_bridge.py，JSON-RPC 使用 http://127.0.0.1:8765	—

Claude Code 不仅可以完成注册：tools/hooks/claude/ 中的 PreCompact 和 SessionStart 钩子会在上下文窗口压缩时重新注入图谱的一部分，因此即使窗口丢弃了内容，图谱仍会保留。

功能说明、对应数字及其测量位置

以下每个数字均于 2026-09-10 在作者自己的图谱和机器上测得，且都可以从本仓库重新测量。如果某个数字尚不存在，本页会如实说明。

	功能说明	测量位置
1. 会话不会中断	一次 memory_checkpoint 会返回线程的概要、最近 3 个会话、所有未解决事项以及最近 5 项决策。	docs/QUICKSTART.md
2. 每个回答都有判定	grounded / partial / ungrounded，并逐一指出不受支持的句子。阈值：支持度 0.60 为有依据，0.30 为部分有依据，grounded 要求 0.80 的句子有依据。	mnemos/grounding.py，tests/test_grounding.py
3. 切片有预算限制	对一个包含 11 342 个节点的图谱执行了 30 次真实查询：提示词中位数为 1 070 个令牌，最大 1 166 个，上限 1 200 个，超出预算 0 次；切片中的节点中位数为 5 个。	mnemos/slice.py，mnemos/context_engine.py
4. 足够快，可纳入工作循环	同样的 30 次查询，在本地构建切片的中位耗时为 115 ms，p90 为 221 ms，最大 394 ms。	mnemos/context_engine.py
5. 适用于任何模型、任何客户端	通过 MCP stdio 和 JSON-RPC 提供 30 个工具，地址为 127.0.0.1:8765。Claude Code、Codex、Cursor、llama.cpp、LangChain 和一行 curl 命令都是同等的客户端。	integrations/
6. 无需模型即可自检	pulse 会持续遍历整个图谱：在一个 3 300 个节点的图谱上用时 571.7 s，占单核 0.72 %；在一个 3 455 个节点的图谱上，首次遍历记录了 52 个事件。	mnemos/pulse.py
7. 记忆可以按规则遗忘	memory_retract 会关闭事实的有效期，并将其从搜索、切片和依据核验中移除；磁盘上的内容不会被删除，且 undo=true 可以恢复。	mnemos/store.py，tests/test_memory_retract.py
8. 上下文压缩后依然有效	Claude Code 钩子会在 PreCompact 和 SessionStart 时重新注入图谱切片，因此即使窗口丢弃了内容，图谱仍会保留。	tools/hooks/claude/

本项目尚无的数据。 尚无 LongMemEval 或 LoCoMo 的分数：这里还没有运行过这些测试框架，在运行之前，诚实的说法就是“尚未测量”。在 14 天的实际使用中，作者自己的日志共经过 142 次核验：81 次判为无依据、41 次判为部分有依据、20 次判为有依据——这衡量的是 Agent 有多少次未先查询图谱就作答，而不是质量分数。我们公布这一数据，因为隐瞒它恰恰是这个工具旨在揭露的行为。

依据核验的实际工作方式

步骤	工具	功能说明
1 — 回答之前	memory_ground_prepare(query, session_id)	搜索图谱，根据找到的节点构建提示词，并登记预核验记录。返回 graph_first：如果答案已在记忆中，就直接采用并跳过模型。
2 — 回答	（你的模型）	根据该摘录生成回答——也可以完全不生成。
3 — 回答之后	memory_ground(answer_text, session_id)	将回答拆分成主张，逐条对照图谱核验，并返回判定和 unsupported_claims。
一次调用	memory_checkpoint(query, session_id, agent)	结合项目线程，一并执行步骤 1 和搜索。
写入	memory_add(items=[{claim, source}, …])	每次调用最多处理 50 条事实，每条都需通过核验。
撤回	memory_retract(node_id, reason)	该事实已不再成立。可撤销。
审计	memory_ground_log	记录每次核验的只追加日志。

没有预核验，就不算数。 如果没有匹配的 memory_ground_prepare 就调用 memory_ground，判定会是 ungrounded（notes: no_pre_pass），无论文本中有多少主张实际上有依据。

完整说明：docs/GROUNDING.md。

你的图谱从空白开始

baron --store blank                       # ./nodes.json, empty
baron --store blank:/var/lib/baron.json   # explicit path

blank 不会覆盖现有文件，而你得到的图谱确实是空的。两者冲突时，服务会拒绝启动并告知你该怎么做。配置： docs/CONFIGURATION.md。

从目录安装

Baron 已发布到 official MCP Registry，标识为 io.github.shinegang/baron：

curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.shinegang/baron"

镜像官方索引的注册表（Glama，以及直接读取官方索引的客户端）会从那里获取该条目。本仓库包含这些目录读取的元数据：

文件	目录	内容
server.json	official MCP Registry	反向 DNS 名称、版本、仓库、网站
smithery.yaml	Smithery	用于 bridge/mnemos_bridge.py 的 stdio 启动命令及其配置架构
glama.json	Glama	维护者信息，用于所有权认领

目前 PyPI 或 npm 上还没有相应的软件包，因此注册表条目指向源代码仓库，而不是可安装的制品：使用两分钟内安装中的 git clone 命令安装，或在检出目录中运行 pip install .。baron-munchausen 发布到 PyPI 后，会在 server.json 中加入 packages 区块，这些目录也会提供一键安装。

参与贡献

欢迎提交问题和拉取请求。这里有两条规则，软件本身也会遵守：

1. 提出主张时须附上来源。 附带复现问题的命令的错误报告，比没有命令的报告有价值十倍。
2. “我无法确认”是有效的回答，而且比猜测更好。在这里，unknown 是一种状态，不是失败。

提交拉取请求前，请运行 python3.12 -m pytest tests -q。

许可证

Apache-2.0 — LICENSE。