funes：给编程代理加本地持久记忆

原文要点

funes是Hugging Face开源的本地持久记忆工具（github.com/huggingface/funes，2026-09-03发布博客），面向Claude Code、Codex、pi、Hermes四种编程代理。单二进制安装，嵌入与重排在本机用固定模型完成，无ML运行时依赖；解析各代理历史会话为统一的turn-and-block结构，分块写入本地Lance数据集；查询融合向量与BM25，cross-encoder重排并按时间衰减加权，recall返回原文而非摘要并标注代理、时间戳、会话、轮次。funes add一条命令完成建索引、装recall/get工具与自动化钩子；funes ask是只读单问模式，可用--memory读共享记忆；可绑定私有Hugging Face数据集跨机同步，发布前做密钥脱敏扫描。

这次做成什么

在一台装有Claude Code的机器上安装funes，完成首次索引并让代理在会话中自主recall历史决策，再用funes ask验证检索质量，最后可选绑定私有HF数据集实现跨机同步。

准备什么

• 一台macOS或Linux机器，可执行shell命令并联网下载安装脚本
• 已安装Claude Code、Codex、pi或Hermes中至少一个，且已有若干历史会话可供索引
• 如要跨机同步：Hugging Face账号及有写权限的token，用于创建私有数据集
• 磁盘留有足够空间存放本地Lance数据集与嵌入模型（原文未给具体大小）

具体怎么做

1. 安装funes单二进制

   在终端执行 curl -fsSL https://huggingface.co/buckets/huggingface/funes/resolve/install.sh | sh 。安装前可先下载该脚本通读一遍再执行。装完运行 funes --help 确认可用。

2. 接入你正在用的代理

   执行 funes add claude （代理是Codex、pi或Hermes时替换参数）。这一条命令会：构建首个索引、给代理装上recall和get两个工具、安装每轮结束后自动增量的索引钩子。原文称首次过程较快，但评论区实测在1.9万个会话的机器上完整索引约2小时、且默认只先索引一小部分，历史多的机器应预期后台逐步回填，'约一分钟'仅为作者说法。

3. 让代理在真实任务中自主recall

   正常用代理干活，当任务涉及过往决策时代理会自己调用recall。recall返回的是原文片段而非摘要，每条注明来源代理、时间戳、会话和轮次，并附get命令可展开完整轮次上下文。你不需要手动粘贴旧会话。

4. 用funes ask直接提问验证

   执行 funes ask claude "我们为什么放弃流式解析器" 。它会检索相关片段交给代理给出注明来源的回答；检索不到支持材料时代理会明说找不到，而不是编造。也可以不建自己的记忆，直接问官方公开的样例记忆：funes ask claude "why is funes append-only" --memory huggingface/funes-memory 。

5. 可选：绑定私有数据集跨机同步

   执行 funes add codex 你的用户名/funes-memory 绑定一个你名下的HF数据集（默认私有）。此后每轮在本地索引并在会话边界发布；另一台机器执行同样命令即可共享记忆。索引阶段会脱敏凭据，发布前还会逐块扫描并拦下疑似密钥的内容，扫描规则见仓库SECURITY.md。

可直接复制的材料

# 1. 安装（建议先 curl 下载脚本阅读后再管道执行）
curl -fsSL https://huggingface.co/buckets/huggingface/funes/resolve/install.sh | sh

# 2. 接入代理：claude / codex / pi / hermes 四选一
funes add claude

# 3. 只读提问，不改动代理配置
funes ask claude "我们为什么放弃流式解析器"

# 4. 读官方公开的样例记忆，无需自己建索引
funes ask claude "why is funes append-only" --memory huggingface/funes-memory

# 5. 绑定私有HF数据集，跨机器共享（替换为你自己的用户名）
funes add codex 你的用户名/funes-memory

[
  {"question": "我们为什么放弃流式解析器", "purpose": "验证对单一历史决策的召回与出处标注"},
  {"question": "上次处理登录超时bug时试过哪些方案、哪个失败了", "purpose": "验证对失败路径的召回，这类信息通常不在代码里"},
  {"question": "数据库迁移方案最终选了哪个、理由是什么", "purpose": "验证跨会话、跨代理的recall（先在Claude中讨论再用Codex提问）"},
  {"question": "项目里从未讨论过的某个名词", "purpose": "验证检索落空时是否如实回答找不到而非编造"}
]

输入与输出示例

以上输出为本站虚构演示格式，非实跑结果；真实输出取决于你机器上的会话内容与代理模型。

输入

在已接入Claude Code、历史会话中有过解析器讨论的机器上执行：funes ask claude "我们为什么放弃流式解析器"

对应输出

示意回答（本站虚构）：'根据2026年8月18日Claude Code会话（turn 34-37），团队放弃流式解析器是因为它在嵌套注释场景下状态机复杂度失控，曾两次引入回归bug；改为逐行解析加后处理。来源：session a1b2c3，agent: claude，2026-08-18T14:22Z；可继续使用该结果附带的get命令展开完整轮次上下文。' 若历史中没有相关内容，预期回答为'在记忆中找不到支持该问题的记录'。

做完检查这些

• funes --help 正常输出，且 funes add 执行后代理工具列表中出现recall和get两个工具
• recall结果包含原文片段且每条带来源（代理名、时间戳、会话ID、轮次），不是改写后的摘要
• 对记忆中不存在的话题提问时，回答明确说找不到而不是编造内容
• 绑定HF数据集后在另一台机器执行同样的add命令，能recall到第一台机器产生的会话

容易卡住的地方

• 评论区实测：默认30天recency半衰期会把超过一个月的历史排名砍半，老历史为主的机器可用--half-life 0关闭时间衰减再对比召回
• 评论区实测：在约1.9万个会话的语料上完整索引约2小时，首分钟只索引一小部分，大历史量不要预期立刻可全量检索
• 作者博客的基准对比（recall比手写交接便宜4-8倍）仅两个任务，样本很小，不宜直接外推到你的工作负载
• 绑定共享记忆前务必阅读SECURITY.md确认脱敏扫描的覆盖范围，会话里出现过的密钥可能未被完全拦截
• funes ask只读单问，不做迭代检索；复杂排查应改用funes add让代理在工作中多轮recall