FIMemory

一个本地存储，你的 AI 工具在连接并被告知后即可读取。

FIMemory（FI Memory，由 Future Industries 开发）将你的笔记保存在你自己的计算机上，并将你的 AI 工具连接到这些笔记，这样你就不必在每次会话中重复解释同一个项目。这个存储就是一个普通的文件夹，里面是你自己的文件：没有专有格式，没有服务器，没有账户，不会上传任何内容到任何地方。新存储默认在静态时加密。你选择一个口令，24 个单词的恢复短语只打印一次，文件无论走到哪里都保持私密：git 主机、云备份、USB 驱动器。更喜欢可以直接在文本编辑器中打开的文件？明文在设置时只需一个明确的选择即可，加密存储随时可以导出回可读的 Markdown，只需你的密钥即可解锁。

从这里开始

两个命令。

npm i -g fimemory
fimemory setup

如果第一个命令失败并出现 EACCES: permission denied（在 macOS 上很常见，npm 的默认全局文件夹归 root 所有），请给 npm 一个你拥有的文件夹，然后重试。不需要 sudo：

npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
npm i -g fimemory

然后关闭并重新打开任何已经运行的 AI 工具，因为它们会在启动时读取自己的设置。

这就是整个安装过程。setup 会在你没有存储时创建存储，连接它在这台机器上找到的每个 AI 工具，然后检查自己的工作并打印哪些已落地、哪些没有。再次运行它是安全且无聊的：已经就位的所有内容都会报告 unchanged，并且不会重写任何内容。当你不确定它是否成功时，再次运行它。

在终端上创建存储时，setup 会引导你完成加密：你选择一个口令（或按一个键用 --plaintext 选择退出），它会打印你的 24 个单词恢复短语一次，并要求你证明你已将其写下来，然后让存储在这台机器上保持解锁约 8 小时。在脚本或 CI 中没有提示：传递 --passphrase "..."，设置 GESTALT_PASSPHRASE，或说 --plaintext。如果这些都没有，它会干净地拒绝，而不是猜测。丢失口令和 24 个单词短语，数据就没了，这是设计使然；这就是“你的密钥，不是我们的服务器”的代价，而引导运行不会让它无声地发生。

setup 无法为你完成的一步是 Claude Code，它管理自己的配置文件。setup 会检查 claude 命令是否存在于这台机器上：如果存在，它会打印一行 claude mcp add 供你粘贴。如果不存在（VSCode 扩展和桌面应用不安装命令行），它会打印确切的 JSON 块以及要放入的文件。无论哪种方式，它都会落在“后续步骤”下，而不是滚动过去。

如果某一步失败，运行会继续，失败会得到自己的行。修复该行，再次运行 fimemory setup，已经成功的步骤会保持不变。

你以后会需要的三个命令：

• fimemory onboard 是 setup 之后的引导式第一步：它引导你批准第一个建议的编辑，问你三个关于你工作方式的问题，并将答案写入存储，然后显示一个用你自己的事实回答的搜索。一个已连接但没有任何关于你的信息的存储即使没有出问题也感觉坏了；这是绕过这种感觉的最短路径。

• fimemory doctor 会读取整个设置并告诉你缺少什么以及该怎么做。半途而废的安装是这种情况最常见的出错方式。

• fimemory setup --plaintext 使用未加密的存储执行相同的安装：每个文件都可以在文本编辑器中读取，你可以读取，任何有权访问该文件夹的人或程序也可以读取。这是一个真实的选择，明确说明，而不是隐藏的降级。以纯文本开始的存储以后可以用 fimemory encrypt 采用加密（在真实内容积累之前最便宜）。

以前，一个有效的安装和一个无效的安装看起来一模一样。现在安装会告诉你你拥有的是哪一种。

Related MCP server: Munin Memory

诚实的期望

• 由人在 Windows、macOS 和 Linux 上安装和使用。 这不是跑者的说法：这些是在真实机器上手工安装的，然后完成了真实的工作，两个不同的 AI 工具每天读取和写入一个存储，持续数月。Windows 机器和 Mac 都运行 Claude Code 和 Grok 来访问它；Linux 机器无头运行它。CI 另外在每次推送时在 Linux 和 macOS 运行器上构建、类型检查、测试并全局安装打包的包。这仍然没有覆盖的是宿主应用的长尾：运行器没有桌面会话，因此对于下面命名的客户端以外的任何客户端，我们都没有看到 setup 写入的配置实际被加载。在 Linux 上，剪贴板命令需要 xclip，或者在 Wayland 上需要 wl-clipboard，而两者都不是默认安装的。如果看起来有问题，请运行 fimemory doctor，并请报告。

• 它并不比不记忆便宜。 它对于小溢价是正确的，并且比粘贴所有内容便宜得多。

• 代理在连接并被告知时读取它。 setup 为你写入 MCP 配置、规则文本和检索钩子，但没有任何记忆产品可以强制宿主在每一轮都主动咨询它。

• 自动同步未发布。 多机器通过你自己的 git 远程工作，在你自己的账户下。目前还没有同步服务，因此除非你自己配置远程，否则你写的任何内容都不会离开你的机器。

• 发布的范围是你的机器，几个代理。 将两台机器指向一个私有 git 远程：在第二台机器上 fimemory join <url>，然后在会话前后 fimemory pull。对同一笔记的编辑永远不会静默合并；失败的一方会成为待你审查的待定提案。超出你自己远程的团队功能不在其中。

setup 实际运行什么

五个步骤，按此顺序：

1. init，仅当 ~/.fimemory 没有存储时（检测到早期安装的现有 ~/.gestalt 并保留）。当已经存在时，跳过，绝不覆盖。

2. install-mcp，将 MCP 服务器条目写入它找到的每个宿主配置文件。这就是让助手能够读取存储的方式。

3. install-hooks，将 Claude Code 的检索钩子写入 ~/.claude/settings.json。当 ~/.claude 不存在时跳过。

4. install-rules，将记忆规则块写入每个宿主的规则文件。这就是让助手实际使用存储的方式。

5. doctor，读取所有内容并报告。

钩子在规则之前运行是有意为之。shim 规则文本告诉模型，相关笔记可能已经在轮次中，由检索钩子注入。这句话只有在钩子安装后才为真，因此钩子先运行，其结果决定措辞：钩子已安装意味着 Claude Code 获得 shim 措辞，钩子跳过意味着每个宿主获得搜索优先措辞，后者是无条件为真的。在没有钩子的情况下写入 shim 措辞会告诉模型停止搜索，以换取永远不会到达的注入，这比什么都不做更糟糕。

每一步都被包装，因此失败会成为该步骤的行，并且运行继续。无法写入的规则文件绝不能让你失去 MCP 注册，两者都不能让你失去 doctor 的裁决，该裁决会告诉你哪些已落地。setup 也可以在锁定的加密存储上运行，这是第二台机器上的正常情况，并让 doctor 报告锁定。

各个动词仍然存在，并且仍然可以独立工作：init、install-mcp、install-hooks、install-rules、doctor。

哪个工具获得什么

* 供应商文档，未在磁盘上验证。 Windsurf、Cursor 和 Claude Desktop 没有安装在我们检查过的任何机器上，因此我们从未见过这些路径存在。如果其中一个在 setup 说 installed 后忽略了存储，那是最值得怀疑的地方：检查应用自己的设置，看看它真正把规则放在哪里，然后重新运行 fimemory install-rules --file <path>。表中的每一行都已在磁盘上看到。

• Claude Code 是 install-mcp 不写入的唯一宿主。Claude Code CLI 拥有 ~/.claude.json 的模式，因此我们打印 claude mcp add fimemory -s user -- ... 而不是写入。它的规则块和钩子为你写入。

• Cursor：我们不写入 Cursor 规则文件。Cursor 在哪里保存用户级规则，以及它是否加载 ~/.cursor/rules，未验证。Cursor 没有安装在我们检查过的任何机器上，并且此磁盘上没有 Cursor 文档。此页面的早期版本将这些限制陈述为事实；它们从未从来源读取过，这与下面的 ~/.grok/GROK.md 错误相同，因此它们已删除。第三方证据指向另一个方向：Grok 自己的 12-project-rules.md 将 ~/.cursor/rules/ 列为它扫描的规则目录。如果你知道 Cursor 读取的文件，install-rules --file <path> 会将相同的块写入那里。

• Claude Desktop：我们不写入 Claude Desktop 规则文件。它是否在磁盘上有规则文件未验证。它没有安装在我们检查过的任何机器上。它的 MCP 配置已写入。

• Gemini CLI 允许你使用 ~/.gemini/settings.json 中的 contextFileName 重命名其上下文文件。install-rules 会读取并尊重它，因此规则块会落在 Gemini 实际读取的文件中。

• 其他任何东西，包括我们从未听说过的宿主：install-mcp 会打印一个通用的 JSON 片段，供你粘贴到该客户端的配置中。

由人端到端验证：Claude Code 和 Grok，在 Windows 11 和 macOS 上。 这些是已安装并用于实际工作、每天针对共享存储的组合。表中的每个其他宿主都会写入其配置和规则；诚实的按宿主矩阵在测量时发布，而不是提前发布。

如果宿主位于不寻常的位置：install-rules、install-mcp 和 doctor 都会遵循 CODEX_HOME、GEMINI_CLI_HOME 和 GROK_HOME（如果已设置），因此三者对宿主所在位置的看法一致。Claude Desktop 的配置路径取决于你的平台（在 Windows 上还取决于 APPDATA）。其余路径，Cursor 和 Windsurf 的路径，是固定的。

钩子，精确地说

install-hooks 只写入一个文件：Claude Code 的 ~/.claude/settings.json。这是关于此软件的一个陈述。这不是声称其他工具没有钩子，而做出该声称的此句子的版本已于 2026-07-31 检查，并且是假的。

Grok CLI，于 2026-07-31 在磁盘上实际安装的 grok 0.2.117 上做了一手验证。Grok 默认会扫描 ~/.claude/settings.json 中的 hooks（[compat.claude] hooks = true，见 ~/.grok/docs/user-guide/05-configuration.md；而 10-hooks.md 中的 Hook Locations 表将该文件列为全局始终可信来源）。它确实会加载我们的两个 handler。但它无法传入注入内容，原因有二，彼此独立：

1. Grok 会丢弃 hook 的 stdout。 这是关键的一条，因为无法绕过。我们实测过：四种输出形态（Claude 的 hookSpecificOutput、顶层 additionalContext、纯文本、systemMessage），每种都已通过它写入的标记文件确认真正触发过，每种都没有产生被注入的上下文；同时还有阳性对照，证明测试装置完全能够呈现被注入的上下文。实测是在无头 -p 模式下进行的；交互式 TUI 未测。Grok 自己的文档并未对此下结论。10-hooks.md 只说 PreToolUse 和停止类事件可以决定，且“其他所有事件都是被动的”；其 Passive Hooks 一节又说 stdout 对“像 SessionStart 或 PostToolUse 这类事件”会被忽略，只举了例子而没有提及 UserPromptSubmit——所以这里的权威是实验而不是文档。

2. 其 handler 格式没有 args 字段。 10-hooks.md 中的 Key Fields 表列出了 type、command、url、timeout 和 env，而我们的整个调用都放在 args 中。Grok 启动解释器时不带任何参数，那个进程随即立即退出。这点看起来可以修复，因为 command 接受内联 shell 命令；但修好也只是让 hook 运行起来，依然不会注入任何内容，原因见 (1)。

无论哪种情况，什么都不会被拦截：Grok 都是失败开放。但“失败开放”不等于“静默”。10-hooks.md 说每次 hook 失败都会记录到 UI 回滚缓冲区，因此你每次向 Grok 提问时都会看到一行 hook 失败记录。想让它消失，请在 ~/.grok/config.toml 中设置 [compat.claude] hooks = false。不要把 handler 从 ~/.claude/settings.json 中删除。那是 Claude Code 实际使用的文件；从那里删除，会关掉 hook 唯一能正常工作的那个宿主。

Grok 也会读取 ~/.claude/CLAUDE.md。 规则文件并不是所在目录那个宿主的专有文件。Grok 的 12-project-rules.md 提到，在启用 Claude 兼容性时（默认开启），它会扫描用户主目录下 ~/.claude/，寻找 CLAUDE.md 等文件；在真实机器上运行 grok inspect --json 也列出了正是那个文件。因此在 Claude Code + Grok 共存的机器上，写给“Claude Code”的 shim 措辞也会到达 Grok。现在不再如此了：只要检测到一个无法运行该 hook 的宿主也会读取某个规则文件，那个文件就会使用 search-first（先搜索）措辞，无论其名义上的所有者是谁。fimemory doctor 会报告每个规则文件携带的是哪一种正文，而不只是说明是否存在一个块。

Codex CLI 有 hooks。在其随附的二进制版本 @openai/codex 0.145.0（2026-08-01）中看到：事件集合包含 user_prompt_submit、session_start、pre_tool_use 和 stop；二进制中带有 hooks/src/events/ 源码路径以及一个 hooks/hooks.json 加载器。我们没有写任何 Codex hook 配置，因此我们的 hook 不会在那里运行。至于我们的 handler 在 Codex 下是否能够工作——即它的 handler schema 是否能被接受，以及 user_prompt_submit hook 的 stdout 是否会被注入——这一点未验证，我们也不作任何方向的断言。

Gemini CLI 有 hooks，并且自带一个官方导入器，专门导入我们写入的那个文件。在 @google/gemini-cli 0.52.0（2026-08-01）中看到：UserPromptSubmit 映射到 Gemini 的 BeforeAgent 事件，而 gemini hooks migrate 会读取 <cwd>/.claude/settings.json 并导入其中的 hooks。如果你使用该命令，有一个警告：它的导入器只复制 command、type 和 timeout，并会丢弃 args，与 Grok 如出一辙。在一个 .claude/settings.json 中含有我们 handler 的目录里运行它，你会得到一个 node 进程在每次 prompt 时都失败。我们不写任何 Gemini hook 配置，所以这只会发生在你自己执行迁移时。

Windsurf 和 Claude Desktop：它们到底是否支持 hooks，未验证。在我们检查过的任何机器上，这两个都没有安装。我们也不为它们编写任何 hook 配置，除此之外不做更多声明。

Cursor：Grok 的文档记录了一个 Cursor hooks 文件（~/.cursor/hooks.json）。我们不写它，也没有把我们的 handler 放在它之上进行测试。

fimemory install-rules --list-hosts 会在你的机器上打印出以上全部信息：检测到哪些宿主、每个宿主把规则文件放在哪里，以及每个宿主对应的 hook 原因及来源。

为什么规则块才是关键部分

install-mcp 给你的助手提供读取存储的能力。install-rules --mode shim 才是让助手无需被要求就读存储的东西，它会在你的 prompt 之前注入相关笔记。按照我们自己的测量，其代价只是让助手通过工具调用去搜索存储所需很小一部分代价的一部分。没有它，工具虽然在那里，但大部分时间处于空闲状态。

shim 措辞只写入那些唯一由真正运行检索 hook 的宿主读取的文件；目前这就意味着在没有安装 Grok CLI 的机器上的 Claude Code。其他所有文件都会得到 search-first（先搜索）块，这种措辞告诉那些助手自己调用 fimemory_search，因为对它们不会注入任何内容。安装 Grok CLI 之后，~/.claude/CLAUDE.md 会在下一次 setup 时退化回 search-first（先搜索）措辞，因为 Grok 也会读取该文件。

当某些东西看起来不对时

fimemory doctor 会检查存储模式、密钥来源、每个宿主配置中的 MCP 注册、规则块、检索 hook、目录索引，以及存储最后一次被读取的时间。它会指出缺失了什么以及该怎么办，并在确实有故障时以非零状态退出。如果一个存储的索引缺失，或没有列出磁盘上确实存在的笔记，那属于故障，而不是警告：搜索读取的是索引，所以一个“盲”索引意味着助手会静悄悄什么都找不到。

静态加密（默认）

新存储会在 Argon2id 口令的守护下用 XChaCha20-Poly1305 密封，并在创建时打印一次 24 词恢复短语（fimemory encrypt 会把较旧的或 --plaintext 存储带到同一状态）。如果 passphrase 和短语都丢失，数据就会消失——这是设计使然。没有账号，也没有重置功能，这正是那句短语重要的原因。

工具使用 GESTALT_PASSPHRASE 打开存储。请按你的 shell 需要的方式来设置：

$env:GESTALT_PASSPHRASE = 'your passphrase here'          # PowerShell
set "GESTALT_PASSPHRASE=your passphrase here"             # cmd.exe
GESTALT_PASSPHRASE='your passphrase here' fimemory list   # macOS, Linux

一次解锁会让命令在大约 8 小时内保持快速（sessionKeyCacheTtlHours，设为 0 则禁用）。fimemory lock 可以提前结束。

这里还有“第二天”的实际情况，好让你不吃惊：当那个窗口过期且环境变量中没有 passphrase 时，CLI 命令会再次询问；MCP 工具会对每次调用回答一个明确的“存储已锁定”错误，并指明修复方式（在工具运行的地方设置 GESTALT_PASSPHRASE，或任意终端中运行 fimemory unlock；正在运行的服务器会在下一次调用时使用新解锁状态，无需重启）。而每个 prompt 的检索 hook 会保持沉默，不会阻断你的 prompt。fimemory doctor 就是把这种状态大声说出来的工具。GUI 应用（Claude Desktop 等）读取的会是操作系统用户环境，而不是你的 shell profile，所以请把变量放在桌面能读取的桌面的地方。

关于边界的坦诚说明：一旦存储解锁，已连接 MCP 客户端就拥有等同于文件系统工具的读取权限。这对每一个 memory MCP 都是如此；我们已明说。

卸载

每个层面对应一个命令，每个命令只清理自己的安装卸载器写的东西：

fimemory uninstall-mcp      # remove the MCP entry from every host config
fimemory uninstall-rules    # remove the memory rule block, nothing else in the file
fimemory uninstall-hooks    # remove our two handlers from Claude Code's settings

还没有一个单独销毁命令，所以 uninstall-mcp 会打印另外两个命令，整个回滚过程在一屏内完成。

uninstall-mcp 的运行逻辑和 install-mcp 相同，只不过替换为一组空内容：相同的宿主、相同的文件、相同的规则——宿主配置文件决定了是否“已安装”。它只删除自己的配置条目，不触碰其他任何东西。无法解析的配置文件不会被改动，且被拒绝，拒绝时返回退出码 1，所以 fimemory uninstall-mcp && rm -rf ~/.fimemory 会因命令失败而停止而不是继续。如果某个宿主配置中没有我们的任何内容，那么这次执行也算成功，退出码为 0。

Claude Code 的处理与安装完全对称：我们会打印 claude mcp remove fimemory -s user，并只读地读取 ~/.claude.json，纯粹是为了告诉你那里是否注册了条目。

删除任何东西之前的口令顺序

如果你以前运行过 install-mcp --env-passthrough GESTALT_PASSPHRASE，那么加密存储的 passphrase 就会以明文形式保存在这些宿主配置文件中，配置文件里。删除我们的条目会同时删除它；对某些人来说，那个配置文件可能就是唯一的副本。因此，无论哪个方向，顺序都很重要：

• 想保留存储： 请先确保你仍能用某个记得的口令或你的 24 词恢复短语打开它，然后再删除任何东西。先运行 fimemory uninstall-mcp --dry-run。它会列出将删除的环境变量名，但绝不显示环境变量的值，并且不会写入任何内容。

• 想丢弃存储： 先删除配置，再删除存储文件夹。这个顺序是对的，也不会把口令留在某个配置文件中。

• 关于本身 Claude Code 的 cli 官方文档说明 claude mcp remove 会永久删除服务器配置，包括服务器环境和相关的 Header，所以这个命令也会一并带走那些变量值。

存储本身是一个你的文件夹，所以删除它就是删除一个目录：~/.fimemory（如果是改名之前的安装，则是 ~/.gestalt），或任何你用 --home 指定过的地方。如果你想保留笔记，先导出。

你的文件，你可以随时退出

fimemory export --plaintext <dir> 会把每条笔记、日志和建议修改都以纯文本 Markdown 形式写到存储之外。这条逃生通道是真实存在的，而且从第一天起就能用。

命名说明

所有需要你看到的名字都叫 fimemory：命令、MCP 服务器 key，以及工具 id（fimemory_search、fimemory_get，……）。更名之前安装旧版本也仍然有效：位于 ~/.gestalt 的存储、GESTALT_* 环境变量，以及旧的 gestalt MCP 条目，都依然会被检测并继续生效。

许可证

源代码在 FSL-1.1-ALv2 下可用（见 LICENSE.md）。可以自由使用和修改，但不得销售它，也不得作为竞争性服务来运行。每个版本在发布两年后转为 Apache-2.0。