创网头像创网独立产品工程师
菜单

其他 / 设置

返回博客

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 采用只追加方式;funes 检索相关会话,编程智能体据此回答并标明来源

向一份记忆提出问题,并借用编程智能体来回答:funes 检索相关会话,将它们交给智能体,你会得到一个有依据、注明所用会话来源的答案——不安装任何东西。这里读取的是命令中直接指定的公开数据集 huggingface/funes-memory。

功能一览

  • 你的智能体能回忆你过去的工作。 模型会在任务途中主动使用 funes,检索先前的决策、理由和发现。
  • 多个智能体,共用一份记忆。 将 Claude Code、Codex、pi 和 Hermes 的会话索引到同一份记忆中;检索覆盖它们全部,每个命中结果都会显示来自哪个智能体。
  • 你的记忆就是一个 Hugging Face 数据集。 将其发布到 Hugging Face Hub;团队成员、你的另一台机器——或任何人,如果你将其设为公开——只需一个参数就能从中检索。

编程智能体在任务途中主动调用 funes,检索公开的 huggingface/funes-memory 数据集,然后基于检索内容回答,并标明所用会话

这一过程还会自动发生:接入 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.