AI 工具 · 中文译文
funes 官方项目说明:为 AI 编程智能体提供持久记忆
为你的 AI 编程智能体提供持久记忆。 funes 为你在 Claude Code、Codex、pi 和 Hermes 中的历史会话建立索引,让任何智能体都能回忆过去的决策、理由和发现。你的记忆是一个可以发布到 Hugging Face Hub 的数据集——之后,任何机器、团队成员或智能体都可以从中检索回忆。
funes
为你的 AI 编程智能体提供持久记忆。 funes 为你在 Claude Code、Codex、pi 和 Hermes 中的历史会话建立索引,让任何智能体都能回忆过去的决策、理由和发现。你的记忆是一个可以发布到 Hugging Face Hub 的数据集——之后,任何机器、团队成员或智能体都可以从中检索回忆。

向一份记忆提出问题,并借用编程智能体来回答:funes 检索相关会话,将它们交给智能体,你会得到一个有依据、注明所用会话来源的答案——不安装任何东西。这里读取的是命令中直接指定的公开数据集 huggingface/funes-memory。
功能一览
- 你的智能体能回忆你过去的工作。 模型会在任务途中主动使用
funes,检索先前的决策、理由和发现。 - 多个智能体,共用一份记忆。 将 Claude Code、Codex、pi 和 Hermes 的会话索引到同一份记忆中;检索覆盖它们全部,每个命中结果都会显示来自哪个智能体。
- 你的记忆就是一个 Hugging Face 数据集。 将其发布到 Hugging Face Hub;团队成员、你的另一台机器——或任何人,如果你将其设为公开——只需一个参数就能从中检索。

这一过程还会自动发生:接入 funes 后,智能体会在对话途中主动调用 recall——你无需运行命令。这里,它通过检索来回答关于 funes 自身设计的问题,回答有依据,并注明所用会话。
获取 funes
安装程序会识别你的平台,下载相应的预构建二进制文件,核验带标签发布版的校验和与版本,并将它放入你的 PATH,默认位置为 ~/.local/bin:
curl -fsSL https://huggingface.co/buckets/huggingface/funes/resolve/install.sh | sh
然后将它添加到你的智能体:
funes add claude # or codex, pi, hermes
使用其他智能体?其作者维护的集成列在 funes-integrations/COMMUNITY.md 中,funes add <id> --from … 可以从其发布位置安装集成。要构建并分享你自己的集成,请从编写集成开始。
一条命令即可完成接入:你的智能体会获得 recall 和 get 工具;对 Claude、Codex 和 Hermes,funes 还会建立首个索引,安装一个在每轮对话保持索引最新的 hook,并在绑定了记忆时,于每个会话边界发布。之后你只管工作即可。有关智能体、记忆绑定,以及一次运行会做什么,请参见 docs/add.md;funes status 会告诉你,检索是否已经在读取你自己的记忆。
带标签的二进制文件及其 SHA256SUMS 清单,也可从发布存储桶获取:
| 平台 | 二进制文件 |
|---|---|
| Linux x86_64 | funes-x86_64-linux |
| Linux aarch64 | funes-aarch64-linux |
| macOS Apple Silicon | funes-arm64-apple-darwin |
校验和能检测损坏、截断或版本不匹配的发布下载。由于二进制文件与校验和位于同一存储桶中,它并不能验证该存储桶本身的真实性。
已经安装?funes update 会在原位置将二进制文件替换为适合你平台的最新构建;--force 会重新安装当前版本。funes status 会告诉你是否有新版本发布。要自行构建,请参见从源码构建。
跨智能体与模型使用
你的记忆不绑定某一个工具。由于 Claude Code、Codex、pi 和 Hermes 都将内容索引到同一份记忆,你可以切换智能体而不丢失任何内容:在 Claude Code 中开始一个任务,下周在 Codex 中继续,每个智能体都能检索全部历史,而不仅仅是自己的会话;每个命中结果会显示它来自哪个智能体。其他智能体也可以通过将会话写成 funes JSONL 格式的轮次文件,或者使用兼容的 .parquet 轨迹导出加入其中,详见导入约定。
模型也是如此。funes 运行固定版本的本地嵌入模型与重排序模型,但自身没有生成模型:你使用智能体所采用的模型进行推理;通过 pi,可以使用任何本地模型,或通过 Hugging Face 路由器提供的模型。在不同会话间切换模型,记忆不需要迁移。
Hub 上的记忆
你的本地记忆是一个数据集,也像数据集一样分享:将它发布到你拥有的 Hugging Face dataset 仓库,它就会像任何模型或数据集一样成为 Hub 上的产物——归你的账户或组织所有,由你的 token 控制权限,允许你指定的人读取。不仅是项目代码,背后的过程——决策、走过的死胡同与理由——也成为智能体可以检索的内容。
funes 创建的数据集仓库默认私有。已有仓库会保留当前可见性;将 funes 创建的记忆公开,需要在 Hub 上有意作出更改。
在为智能体添加 funes 时绑定一份记忆,它会从那里检索,并自动保持更新;你也可以直接运行这两条命令:
funes push <user|org>/funes-memory # publish your local memory's new chunks
funes recall "..." --memory <user|org>/funes-memory # read any remote memory for one call
第二种形式让你能够读取别人已经发布的某个主题的记忆,而不改动自己的设置。发布过程有保护措施:funes 在建立索引时会清除凭据,另一个独立且始终开启的门禁会拒绝推送仍包含秘密的分块。由于发布的记忆只是一个数据集,你可以现在就尝试检索,而不用先给自己的任何内容建立索引:
funes recall "why is funes append-only" --memory huggingface/funes-memory
要获得一个答案而不只是排序后的段落,可以借用智能体回答一个问题,无需安装任何东西:
funes ask claude "why is funes append-only" --memory huggingface/funes-memory # or: funes ask codex
有关发布、秘密门禁、选择发布内容和检查记忆,请参见 docs/push.md;有依据的回答参见 docs/ask.md;远程检索如何通过缓存达到本地速度,参见 docs/hub-caching.md。
命令
funes add 将所有这些接入你的智能体;每个命令也可独立使用。完整指南请浏览以工作流程组织的文档索引。
| 命令 | 文档 |
|---|---|
funes add <agent> [memory] / funes remove <agent> / funes mcp [memory] |
docs/add.md——支持的智能体、集成生命周期、通用 MCP 客户端、hooks 和记忆绑定 |
funes index [path] |
docs/index.md——建立或更新记忆;来源、增量处理、参数 |
funes recall "…" / funes get … |
docs/recall.md——检索段落并深入查看 |
funes sessions / funes sketch … / funes scan … |
docs/sessions.md——列出会话、概览某个会话、在某个会话中查找字面文本 |
funes ask <agent> "…" |
docs/ask.md——借用智能体获得有依据的答案 |
funes push <memory>(以及 scrub、status) |
docs/push.md——发布并分享记忆 |
funes update |
安装与更新——用经过验证的发布版替换已安装的二进制文件 |
hooks 执行的逐轮索引和会话边界发布,详见 docs/automation.md。
工作原理
funes add 运行一个循环:为你已完成的工作建立索引,在有用的时候检索回忆它——并给你刚完成的工作建立索引,让下次也能检索到。两部分使用同一条确定性的流水线:将每个来源解析为通用的轮次/区块结构,分块,用固定版本的本地模型生成嵌入,并写入本地 Lance 数据集;检索融合向量搜索与 BM25 搜索,重新排序,并按近期程度重新加权。集成将各智能体的对话记录转换为共享的轮次格式。添加一个智能体,意味着发布你自己的集成;索引与查询流水线已经能够读取该格式。
funes 的输出面向智能体而非人。因此,如果你自己想向一份记忆提问,可以借用一个智能体:funes ask 从记忆中检索,并根据找到的内容回答,不安装任何东西。funes recall 打印答案背后的原始排序段落,funes get 则将任何被引用的轮次完整重组出来。
- docs/index.md——索引流水线、层级和增量行为。
- docs/recall.md——检索、使用
get深入查看,以及读取共享记忆。 - docs/sessions.md——按会话浏览记忆:
sessions、sketch、scan。 - docs/ask.md——借用智能体获得有依据的答案,无需安装任何东西。
- docs/automation.md——保持内容最新的逐轮 hooks。
从源码构建
需要 Rust 工具链和 protoc——lance 的构建脚本会在构建时编译 protobuf,完成的二进制文件不需要它。可用以下两种方式之一安装:
# System-wide:
sudo apt-get install -y protobuf-compiler # Debian/Ubuntu
brew install protobuf # macOS
然后运行 cargo build --release,二进制文件位于 target/release/funes;cargo test 运行测试套件。集成测试会在首次运行时下载嵌入模型和重排序模型的权重。
推理,即嵌入与重排序,在内置后端上运行:macOS 使用 Accelerate,Linux 使用纯 Rust。因此,默认构建没有 ML 运行时依赖,可以在任何 glibc ≥ 2.35 的系统上运行,例如 Ubuntu 22.04。也可以选择使用 ONNX Runtime 后端的变体:
cargo build --release --no-default-features --features onnx # ONNX backend instead
cargo run --release --features onnx --example bench_backends # A/B both backends
说明
- 嵌入模型采用固定版本,并记录在记忆中;用不同的嵌入模型查询会被拒绝。要更换它,需要从对话记录重新构建;记忆是可以丢弃的派生产物,每一行都保留了原始文本。这与用于推理的模型不同,后者可以自由更换。
- 子智能体对话记录(
.../subagents/agent-*.jsonl)也会建立索引。
为什么选择 funes
“思考,就是忘却差异、进行概括、作出抽象。” —— Jorge Luis Borges,《博闻强记的富内斯》(Funes the Memorious)
关于 funes 为什么采用这样的设计,以及它与其他记忆工具如何比较,见 docs/RATIONALE.md。
许可证
funes 使用 Apache License 2.0 许可证。
转载与翻译许可
原文及对应版本许可:funes README · 原仓库 LICENSE。本页将原 README 翻译为中文,保留全部正文、代码和两处项目 GIF 引用;相对链接已改为历史版本的绝对地址。以下保留原版权及 Apache License 2.0 完整许可文本。
查看原版权与完整 Apache License 2.0
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright 2026 The HuggingFace Team
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.