frugal-memory

frugal-memory

一个为 AI 助手打造的持久化记忆，只需一个 SQLite 文件——成本约为读取 Markdown 笔记的五分之一。

无需向量存储、嵌入、外部服务或 API 密钥。Python、带有 FTS5 的 SQLite、stdio——唯一的依赖项是官方 mcp SDK。除非你明确开启可选的事实核查，否则不会有任何数据离开你的设备。

在来自 89 个工作会话的 275 个真实问题中进行测量：每个已回答问题平均 2,359 个 token，而常见做法为 11,319 个——每条事实存入一个 Markdown 文件，通过 grep 找到后再读取整个文件。特意选用这个基准作为朴素做法：它模拟的是用 Read 打开文件的情况，而这会加载整个文件。更谨慎的做法是使用 grep -C，并提供三行上下文；结果发现，它反而更贵，而不是更省：在真实搜索顺序下，中位数的字符数多出 28 倍（运行后补充；按运行前固定的规则则多出 65 倍），因为在 1,756 个文件中进行宽泛搜索会返回数百行匹配内容（详情）。这两种做法都是与 Markdown 笔记比较，并非与其他记忆服务比较。随着记忆增多，差距也会扩大，因为这里每次回答都有上限，而 grep 没有。所有数据都来自一次安装，文档也说明了哪些结论并不适用。

为什么

助手的记忆通常会以两种方式失效：要么是一堆必须完整读取才能搜索的 Markdown 文件，要么是一个向量数据库，只会回答匹配到了什么，却从不说明为什么。

这是一个针对短条目的排序全文索引，并附加了两项功能，让一堆笔记真正成为记忆：条目按两个维度归档——归属何处（项目）和知识类型（陷阱、决策、测量结果，……）；当你记下某件事时，工具会告诉你它与哪些现有条目重叠，从而让矛盾浮出水面，而不是悄悄越积越多。

功能

• 有上限、可预估的回答 — 搜索会返回 8 行预览，总计约 1.2 KB，而不是 4.2 KB 的全文；随后，zeige 会获取你选中的条目，除非你要求获取全部内容，否则每次调用约返回 6,000 个字符。最坏情况下的返回量在你发起请求前就已知。
• 从自身的失败中学习 — 搜索后若接着获取某个条目，系统就会记住这对操作。再次提出相同的问题时，上次给出答案的条目会排在最前。仅对逐字重复的问题生效，且标题会说明何时触发。
• 两条归档维度 — 自由文本项目标签，以及封闭且强制执行的知识类别词表。编年条目默认不参与搜索，但标题总会说明有多少条目被排除。
• 重复与矛盾提示 — remember 会报告相似的现有条目以及发生变化的编号，让你可以替换旧条目，而不是不断累积。
• 永不删除任何内容 — 被替换的条目会从默认视图中隐藏，但仍可搜索，并附有说明，标明替换原因和替换它的条目。若这是个错误，只需切换一个选项即可恢复显示。
• 不只是搜索，还能浏览 — themen() 会列出项目及项目中最新条目的标题行，方便你在忘记搜索词时查找。和其他内容一样设有上限：只显示一页，并附上一行说明如何获取其余内容。
• 使用时绑定项目，搜索时不绑定 — 通常会在一个项目内通过 marke= 提问。该筛选条件是硬性限制，因此如果最佳匹配位于项目之外，recall 会指出它，而不会给你一份看似合理、实际却包含错误条目的列表。
• 基于同一引擎的两个可选扩展 — 所有项目共享的文献档案，以及用于测量序列的实验记录簿。每个扩展都有独立文件和独立的服务器条目；不启用它们，一切照常运行（下文）。
• 可选的第二意见 — 可向任意兼容 OpenAI 的模型询问两个条目是相互矛盾，还是其中一个替代了另一个。
• 默认使用德语，也可按需切换为英语 — 工具名称、消息和类别均为德语；设置 MEMORY_LANG=en 即可切换全部内容。搜索也会匹配词形变化和复合词组成部分（搜索 “Rangliste” 可找到 “Ranglisten”）。实测发现，这很少改变结果：搜索的普通“任意词”阶段已经能找到词干扩展带来的结果（详情）。

要求

• Python 3.11+
• mcp SDK（requirements.txt，依赖列表仅此一项）
• 支持 FTS5 的 SQLite — 标准 CPython 构建中已包含
• 已在 Linux、macOS 和 Windows 上使用 Python 3.11 和 3.14 测试：每次推送都会运行完整测试套件，并测试已安装的软件包。目前日常使用仅限 Linux — 非常欢迎 macOS 和 Windows 用户通过 issue 提交反馈。
• 可选，仅用于事实核查：任意兼容 OpenAI 的端点

设置

从 PyPI 安装，并在独立环境中作为命令运行：

pipx install frugal-memory        # or: uv tool install frugal-memory

claude mcp add memory -s user -- frugal-memory

使用 uv 时，也可以无需预先安装即可运行；uvx 会在首次启动时获取软件包：

claude mcp add memory -s user -- uvx frugal-memory

数据库会在首次使用时创建于 ~/.local/share/frugal-memory/memory.db（如果设置了 $XDG_DATA_HOME，则使用该目录）。 frugal-memory-nachziehen 是 DESIGN.md 中介绍的维护脚本。 如果你有一文件夹的 Markdown 笔记，frugal-memory-import <folder> 会逐段将其导入 （IMPORT.md）。 frugal-memory-skill 会安装 Claude Code 的工作规则（见下文）。 使用 uvx 时，这些命令都可以通过 uvx --from frugal-memory frugal-memory-import … 运行。

也可以从本仓库的检出版本运行：

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

claude mcp add memory -s user -- \
    /path/to/frugal-memory/.venv/bin/python \
    /path/to/frugal-memory/memory_server.py

此时，数据库会创建为脚本旁边的 memory.db。无论采用哪种方式， 都可以通过 MEMORY_DB=/some/path.db 将数据库放到其他位置。

-s user 会让所有项目都能使用该服务；配置项会写入 ~/.claude.json。之后重启 Claude Code——MCP 服务只会在启动时 加载。随后可调用的工具名称为 mcp__memory__recall 和 mcp__memory__remember。

对于 Claude Desktop，请改用 ~/.config/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "memory": {
      "command": "/path/to/frugal-memory/.venv/bin/python",
      "args": ["/path/to/frugal-memory/memory_server.py"]
    }
  }
}

有一条规则比任何设置都重要：每次调用只存一个事实，而不是一份文档。 recall 会返回完整条目——如果把一个 180 KB 的文件作为单个条目存储，取回时它也只会作为一个结果返回，毫无收益。

教会 Agent 如何使用它

仅有工具并不能让 Agent 知道工作规则：先搜索再读文件，recall → zeige，每个条目只包含一种类型，用新内容替代旧内容而不是不断累积，并尝试使用另一种语言重试。以下两层会提供这些规则：

• 简短版本随服务附带。 连接时，它会发送约 600 个字符的说明（德语，或设置 MEMORY_LANG=en 时使用英语），Claude Code 会将其添加到所有启用了该服务的会话中。访客模式（--gast）不会发送说明，因为它无法存储任何内容。
• 完整规则以 skill 形式提供。 它随仓库和 PyPI 软件包一起发布；运行一条命令即可安装：

uvx --from frugal-memory frugal-memory-skill   # or frugal-memory-skill after pip install
cp -r skills/frugal-memory ~/.claude/skills/    # or from a clone

只有在需要使用记忆时，Claude Code 才会加载 skill 的完整文本；在此之前，上下文中只有一行描述。如果现有的 SKILL.md 内容不同，除非添加 --force，否则不会改动。

第三层由你决定：在 CLAUDE.md 中添加几行，说明前两层都无法涵盖的内容——主要是知识应存入该服务，而不是 Claude Code 自身的记忆文件。可选的文本块见 docs/CLAUDE-MD.md。

读取另一台机器的记忆

每台机器都有自己的记忆，条目编号都从 1 开始。机器 A 上的会话可以通过 SSH 读取机器 B 的记忆——服务在 B 上运行，与记忆文件放在一起；数据库本身不会通过网络传输：

claude mcp add memory-b -s project -- \
    ssh b /path/to/frugal-memory/.venv/bin/python \
          /path/to/frugal-memory/memory_server.py --gast

--gast（访客）有三层含义：

• 只读。 文件以 mode=ro 模式打开，且只提供 recall、 zeige 和 themen。写入工具会被移除，verdichten 和 pruefe 也一样：维护工作属于所有者，只有所有者才能执行。访客的搜索 不会影响所有者的搜索反馈，访客也不会迁移数据库架构。
• 每个 ID 都带有记忆名称： b#72，而不是 #72。名称是 小写的主机名；可通过 MEMORY_NAME 覆盖。
• 无论哪种模式，都会检查带名称的 ID。 如果对 b 以外的任何记忆调用 zeige("b#72")，请求都会被拒绝，而不会悄悄返回该记忆自身的 #72。裸 ID（72、#72）表示当前被查询的记忆。

-s project 会让额外的三个工具定义不出现在不需要它们的会话中。 此时可调用的工具名称为 mcp__memory-b__recall 等。

两个可选扩展

同一服务还可以以两种模式启动。每种模式都有自己的文件、工具和 Claude Code 条目；它们不会打开记忆本身。这两种模式都像记忆一样遵循 MEMORY_LANG=en。它们源于同时使用多个项目的日常实践，尚未像记忆那样经过测量评估——之所以提供它们，是因为它们让这项工作明显更轻松，而不是因为某个数字能证明这一点。

文献档案（--archiv）

供所有项目共享的论文、数据集和先前工作。记忆记录的是 你 的发现；档案记录的是 他人 发表的内容，它的价值在于能找到其他项目已有的发现。

claude mcp add archive -s user -- uvx frugal-memory --archiv

• 同样的八种工具，但用于其他类型：befund（发现）、methode（方法）、ueberblick（综述）、werkzeug（代码、数据集）、luecke（已搜索但无处测量）、spur（尚未核实的线索）和 verworfen（已核查并否定——例如语言模型捏造的引用）。线索和已否定条目不会出现在搜索结果中，就像记忆中的编年记录一样。
• 通过 id 而非措辞识别同一来源。 当 remember 遇到档案中已有的 arXiv 编号、DOI 或链接时，会提示这一点——两个项目很少会用相同的措辞描述一篇论文。如果来源和证据级别（全文、摘要、未经确认）缺失，它也会要求补充。
• 每个 id 都带有名称 archiv#12（英语模式下为 archive#12），因此绝不会被误认为记忆 id。
• 文件：与记忆文件放在一起的 archive.db，或通过 ARCHIVE_DB 指定。多台机器可以共享一个档案：在存放该文件的机器上通过 SSH 启动服务即可（不带 --gast，这样所有机器都能写入）。

实验记录本（--messbuch）

将测量系列作为结构化记录，而不是零散条目：问题、判据、配方、数值、结论，以及各项内容之间的承继关系。把一组测量分散在十几条记忆记录中，恰好会丢失最重要的信息——哪项仍在进行且尚未评估，以及判据是否在结果出来前就已确定。

claude mcp add messbuch -s user -- uvx frugal-memory --messbuch

• reihen() / series() 会列出未结束的系列及需要检查的事项： N 天没有新条目——流程还在运行吗？、有测量但没有结果、没有判据。要查看某个主题下所有系列的表格，可使用 reihen(kennung="vision/lr-*", tabelle=True)。
• 在首次运行之前调用 reihe_anlegen / new_series。判据会附带时间戳；首次测量后，只有说明理由才能更改，且更改记录会保留。没有判据时，唯一可能的结论是 beobachtung（观察）。
• rezept / recipe 记录命令、代码版本、随机种子和机器；messwerte / measurements 每行记录一个数值；ergebnis / result 记录依据判据得出的结论及其后续影响。内容不会删除；错误数值会被后续记录取代。
• 在开始第一个系列之前就启用它。 事后录入旧系列也可行（nachtrag=、begonnen= 会保留真实日期），但从零散笔记中整理它们所消耗的令牌，远多于在事情发生时逐项记录。
• 文件：messbuch.db，或通过 MESSBUCH_DB 指定。写入记录本的记忆 id 必须带上记忆名称（laptop#452）：记录本可能由多台机器共享，而这些机器的记忆 id 都从 1 开始。

八个工具

remember(text, tags, art, ersetzt)	存储一条记录；报告相似的现有记录，以及它会取代哪些记录
recall(query, limit, art, marke, …)	按相关性排序的全文搜索，默认显示预览；使用 marke= 时，会指出项目之外更匹配的记录
zeige(ids, voll)	查看指定记录的全文，每次调用约 6000 个字符；未能放入的内容会列在获取它的调用中
themen(marke, limit, seite, alle)	浏览：查看有哪些项目，或查看一个项目的标题行，按最新顺序排列，每次显示一页
vergessen(ids, grund, rueckgaengig)	将记录标记为过时——绝不删除；rueckgaengig=True 会恢复记录
einordnen(ids, art)	为现有记录指定知识类型
verdichten(marke, art, …)	查找内容大致相同的记录组
pruefe(ids)	可选择启用：让语言模型判断记录之间是相互矛盾，还是反映了更新后的状态

包含参数和行为的完整参考：docs/TOOLS.md。 设置 MEMORY_LANG=en 后，同样的工具会使用英文名称和参数， 详见语言说明。

部分数据

在一个实际数据集上进行测量，该数据集从约 900 条记录增长到约 1,900 条——这是来自一次安装的证据，并非基准测试：

• 比读取 Markdown 文件便宜 4.8 倍，以实际 token 数计算，涵盖 275 个真实问题（每个问题 2,359 个，对比 11,319 个）。数据集和文件越大，差距越大，因为读取文件是全有或全无：针对一个 188 KB 项目文件提问一次就要耗费 94,152 个 token。
• 在公开的 LoCoMo 数据集上，按会话为单位计算，未经调优的 Recall@10 为 89.8 %（2026-10-19；9 月的首次运行结果为 82.3 %，若以单个对话轮次为单位则为 45.1 %）。
• 预览使返回内容减少 73 %，且最坏情况可计算。
• 反馈循环使每个问题的预期字符数减少 −23 %，首轮命中率从 73 % 提升到 84 %；测量基于按时间顺序回放的 30 个真实会话中的 164 个问题——一组问答只会帮助之后的问题，永远不会帮助自身。19 个问题受益，没有问题受损。
• 一项单行排序修复使 47 个真实改写链中的命中率从 53 % → 64 %——这是通过测量真实搜索会话的失败位置发现的，而非凭空猜测。在当前数据集上，同一修复也会让原本已能成功的 117 个问题中的 3 个受损，因此 164 个问题的净增幅为 2 个。
• 数据集中 93 % 的内容属于某个项目（1,907 条记录中有 1,777 条），工具的使用方式也正是如此。搜索本身并不在意：通用知识和项目知识都能找到（92 % 对比 96 %，按 10 % 规则视为持平）。项目筛选器带来的好处是提高简短问题的精度——约三个词的问题，找到率为 97 % 对比 85 %。代价是无法找到项目之外的内容：在 22 个项目标签下提出的 40 个通用知识问题中，880 条记录里找到了 0 条。现在，recall 会在其中 82 % 的情况下指出标签之外更匹配的记录；在 70 % 的情况下，该记录本身就是所求内容；对于真实项目问题，这种提示会在 7–16 % 的情况下出现。
• 将 themen 和 zeige 的返回上限设为固定值后，项目标题索引减少 −83 %，获取八条全文减少 −34 %。在 110 个项目问题中，设置上限没有让任何答案受损。

对于未能在更大样本中得到验证的测量，文中会注明： docs/MEASUREMENTS.md，原始报告见 messung/。上面的排序数据曾修正两次—— 详见排序修复：两次修正。

文档

docs/TOOLS.md	详细介绍全部八种工具
docs/DESIGN.md	两个维度、形态学、数据库架构，以及有意省略的内容
docs/MEASUREMENTS.md	测量内容及已知局限
docs/FACTCHECK.md	可选事实核查：设置方法及其能力与局限
docs/IMPORT.md	导入现有笔记文件夹，以及导入造成的损坏
docs/CLAUDE-MD.md	可复制到 CLAUDE.md 中的可选内容块
messung/	八份底层测量报告（大多为德语）

关于语言的说明

默认语言为德语：工具名称、状态消息和类别词汇 （schnittstelle、fallstrick、entscheidung、messwert、arbeitsweise、 verlauf、gemischt）均为德语，搜索会提取德语词干并拆分 德语复合词。

英文模式： 使用 MEMORY_LANG=en 启动服务。此时：

• 工具为 remember(text, tags, kind, supersedes)、 recall(query, limit, kind, tag, full, include_superseded)、show(ids, full)、 topics(tag, limit, page, all)、forget(ids, reason, undo)、classify(ids, kind)、 consolidate(tag, kind, threshold, groups) 和 check(ids)，
• 类别为 interface、pitfall、decision、measurement、 workflow、history、unsorted，
• 所有消息均为英文，
• 搜索使用一个小型英文后缀词干提取器（搜索 "configured" 可以找到 "configuring"），而不是德语词干提取器，也不会拆分复合词。

数据库本身不会改变：类别始终以德语名称存储，并在边界处翻译；两种模式下都接受德语类别名称。变化的是词干索引，因此文件会记录其构建时所用的语言，服务也会拒绝用另一种语言打开该文件。要切换现有记忆库，请先备份，然后运行一次 MEMORY_LANG=en frugal-memory-nachziehen（从代码检出目录运行：MEMORY_LANG=en python3 nachziehen.py）。

两个扩展也遵循相同的切换方式：在英文模式下，档案类别为 finding、method、survey、resource、gap、lead 和 rejected；笔记本工具为 series、new_series、edit_series、recipe、measurements 和 result，并使用英文状态和结论。与记忆库一样，它们的文件中存储的是德语名称。

切换不涵盖的内容：事实核查提示词仍为德语（它经过逐字校准，曾经只增加一句话，准确率就减半；只有结论会以英文显示），导入脚本和测量报告也仍为德语。英文词干提取器是新开发的，尚未像德语搜索那样，在真实问题上进行过测量。

文件

memory_server.py	MCP 服务，包含八个工具、搜索级联、架构和迁移
morphologie.py	词干提取器和复合词拆分器（德语；MEMORY_LANG=en 时使用小型英语词干提取器）
werkzeuge_en.py	MEMORY_LANG=en 时使用的英文工具界面
messbuch.py	实验记录本（--messbuch）
messbuch_en.py	实验记录本的英文工具和消息
texte_en.py	英文消息，以德语文本为键
nachziehen.py	重新计算派生列、词语和标签目录以及链标记（pip install 后使用 frugal-memory-nachziehen）
faktencheck.py	通过任意 OpenAI 兼容模型获取可选的第二意见（除非配置，否则关闭）
pruefstand_fc.py	根据数据集中的黄金标签评估事实核查
pruefpaare_gebaut.json	手动构建和手动发现的矛盾对
import_memos.py	导入一个 Markdown 笔记文件夹（pip install 后使用 frugal-memory-import；参见 docs/IMPORT.md）
test_memory.py	回归测试网，每个陷阱对应一个用例（不使用 pytest）
test_archiv.py、test_messbuch.py	两个扩展的测试
skills/frugal-memory/SKILL.md	面向 Agent 的工作规则，作为 Claude Code 技能（也包含在软件包中）
skill_installieren.py	将技能复制到 ~/.claude/skills/（pip install 后使用 frugal-memory-skill）
requirements.txt	仅包含 mcp>=2.2.0
pyproject.toml	PyPI 软件包定义（frugal-memory）
server.json	官方 MCP 注册表中的条目
memory.db	数据库——首次使用时创建，不会提交

messung/ 保存八份测量报告。生成这些报告的脚本及其原始数据不包含在内：它们仅适用于作者自己的数据集，而原始数据是实际工作会话的逐字记录。

许可证

MIT——参见 LICENSE。