fimemory

FIMemory

一个本地存储空间，连接并授权后，AI 工具就能读取其中的内容。

FIMemory（FI Memory，由 Future Industries 开发）将笔记保存在你自己的 电脑上，并把 AI 工具连接到这些笔记，这样你就不用每次会话都重复解释 同一个项目。存储空间就是一个由你自己的文件组成的普通文件夹： 没有专有格式，没有服务，没有账户，也不会上传任何内容。 新建的存储空间默认采用静态加密。你可以选择一个密码短语，系统会 打印一次 24 个单词的恢复短语；无论这些文件存放在哪里：Git 托管平台、 云备份或 U 盘，它们都会保持私密。如果你更喜欢直接用文本编辑器打开 文件，设置时只需明确选择纯文本；加密存储空间随时都能导出为可读的 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 启用加密（最好在积累实际内容之前完成）。

以前，正常工作的安装和无法使用的安装看起来一模一样。现在，安装程序会告诉 你当前属于哪一种。

坦诚说明

• 已由真实用户在 Windows、macOS 和 Linux 上安装并使用。 这不是 CI 运行器上的声明：这些都是在真实机器上手动安装，之后确实投入使用；两种不同的 AI 工具连续数月每天读写同一个存储库。Windows 机器和 Mac 都运行 Claude Code 和 Grok 来访问它；Linux 机器则以无头模式运行。除此之外，每次推送时，CI 还会在 Linux 和 macOS 运行器上构建、进行类型检查和测试，并全局安装打包后的软件包。尚未覆盖的是各种宿主应用的长尾情况：运行器没有桌面会话，因此对于下文未提及的客户端，我们还没有亲眼确认 setup 写入的配置是否确实被加载。在 Linux 上，剪贴板命令需要 xclip，或在 Wayland 上使用 wl-clipboard；这两者默认都不会安装。如果遇到异常，请运行 fimemory doctor，并告知我们。
• 它并不比不记忆更省钱。 它只多花一小笔费用，但效果不错，也远比粘贴所有内容便宜。
• 连接并指示 Agent 后，Agent 才会读取记忆。 setup 会为你写入 MCP 配置、规则文本和检索钩子，但没有任何记忆产品能强制宿主在每一轮中都主动查阅记忆。
• 自动同步尚未发布。 多机器使用依靠你自己的 git 远程仓库和账户。目前没有同步服务，因此除非你自行配置远程仓库，否则你写入的任何内容都不会离开你的机器。
• 当前发布版本面向多台机器和多个 Agent。 将两台机器指向同一个私有 git 远程仓库：在第二台机器上运行 fimemory join <url>，然后在会话前后运行 fimemory pull。对同一条笔记的修改绝不会静默合并；落败一方会成为待处理提案，供你审核。除此之外，不包含超出个人远程仓库范围的团队功能。

setup 实际运行的内容

按以下顺序执行五个步骤：

1. 仅当 ~/.fimemory 中没有存储库时才运行 init（会检测并保留之前安装遗留的 ~/.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。

各工具对应的配置

工具	MCP 配置	规则块	检索钩子
Claude Code	打印命令，不写入文件	~/.claude/CLAUDE.md	有，~/.claude/settings.json
Codex CLI	~/.codex/config.toml	~/.codex/AGENTS.md	无，见下文
Gemini CLI	~/.gemini/settings.json	~/.gemini/GEMINI.md	无，见下文
Grok CLI	~/.grok/config.toml	~/.grok/AGENTS.md	无，见下文
Windsurf	~/.codeium/windsurf/mcp_config.json *	~/.codeium/windsurf/memories/global_rules.md *	无，见下文
Cursor	~/.cursor/mcp.json *	不写入，见下文	无，见下文
Claude Desktop	claude_desktop_config.json *	不写入，见下文	无，见下文

* 供应商文档有记录，但未经磁盘验证。 我们检查过的机器上都没有安装 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。 这些组合已安装并用于日常实际工作，且连接到共享存储。表中的其他宿主会写入配置和规则；真实的逐宿主矩阵会在完成测量后发布，而不是提前发布。

如果宿主安装在不寻常的位置：只要设置了 CODEX_HOME、GEMINI_CLI_HOME 和 GROK_HOME，install-rules、install-mcp 和 doctor 都会遵循这些变量，因此三者对宿主位置的判断一致。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 查找钩子（[compat.claude] hooks = true，记录于 ~/.grok/docs/user-guide/05-configuration.md；10-hooks.md 中的 Hook Locations 表也将该文件列为全局始终受信任的来源）。它确实会加载我们的两个处理程序，但无法注入内容，原因有两个，且相互独立：

1. Grok 会丢弃钩子的 stdout。 这是关键问题，因为无法绕过。我们对此进行了测试：四种输出形式（Claude 的 hookSpecificOutput、顶层 additionalContext、纯文本、systemMessage），每种都通过其写入的标记文件确认确实已触发，但都没有注入上下文；与此同时，正向对照证明了该测试框架确实能够显示注入的上下文。测试是在无头 -p 模式下进行的；交互式 TUI 未测试。Grok 自己的文档无法定论。10-hooks.md 仅说明 PreToolUse 和停止事件可以作出决定，“所有其他事件均为被动事件”；其 Passive Hooks 部分则称，对于“例如 SessionStart 或 PostToolUse 这样的事件”，stdout 会被忽略。文档列出的是示例，而非 UserPromptSubmit，因此此处应以实验结果为准，而非文档。
2. 其处理程序格式没有 args 字段。 10-hooks.md 的 Key Fields 表列出了 type、command、url、timeout 和 env，而我们的整个调用都写在 args 中。Grok 启动解释器时不会传入任何参数，因此进程会立即退出。这一点看起来可以修复，因为 command 接受内联 shell 命令；但修复后只能让钩子运行。由于原因（1），它仍然不会注入任何内容。

无论哪种情况都不会阻断运行：Grok 会在失败时继续执行。但“失败时继续执行”不等于“毫无提示”。10-hooks.md 说明，每次钩子失败都会记录在 UI 滚动记录中，所以每次在 Grok 中输入提示词时，都会看到一条钩子失败信息。若要隐藏它，请在 ~/.grok/config.toml 中设置 [compat.claude] hooks = false。不要从 ~/.claude/settings.json 中删除这些处理程序。Claude Code 实际使用的就是该文件；在此处删除它们，就会关闭钩子唯一能正常工作的宿主。

Grok 也会读取 ~/.claude/CLAUDE.md。 规则文件并非只对其所在目录对应的宿主可见。Grok 的 12-project-rules.md 说明，在启用 Claude 兼容模式（默认设置）时，它会扫描用户主目录级别的 ~/.claude/，查找 CLAUDE.md 等文件；在一台真实机器上运行 grok inspect --json，也列出了这个确切的文件。因此，在同时运行 Claude Code 和 Grok 的机器上，原本“写给 Claude Code”的垫片措辞也会被 Grok 读取。现在不会了：当检测到的宿主无法运行该钩子，且与其他宿主共用规则文件时，无论该文件名义上归谁所有，都会采用优先搜索的措辞。fimemory doctor 会报告每个规则文件采用的正文内容，而不只是报告其中存在一个区块。

Codex CLI 支持钩子。我们于 2026-08-01 通过其随附的二进制文件 @openai/codex 0.145.0 读取并确认：事件集包括 user_prompt_submit、session_start、pre_tool_use 和 stop；二进制文件中包含 hooks/src/events/ 源路径以及 hooks/hooks.json 加载器。我们没有编写任何 Codex 钩子配置，因此我们的钩子不会在那里运行。我们的处理程序是否能在 Codex 下正常工作，也就是其处理程序架构是否兼容，以及 user_prompt_submit 钩子的 stdout 是否会被注入，尚未验证；我们对此不作任何方向的断言。 Gemini CLI 支持钩子，并且自带对我们编写的文件的原生导入功能。在 @google/gemini-cli 0.52.0（2026-08-01）中，UserPromptSubmit 会映射到 Gemini 的 BeforeAgent 事件，而 gemini hooks migrate 会读取 <cwd>/.claude/settings.json 并导入其中的钩子。使用该命令时有一点需要注意：它的导入器只会复制 command、type 和 timeout，丢弃 args，与 Grok 完全一样。在包含我们处理程序的 .claude/settings.json 所在目录中运行该命令，会导致 Node 进程在每次提示词提交时都失败。我们不会编写 Gemini 钩子配置，所以只有你自己运行迁移时才会发生这种情况。

Windsurf 和 Claude Desktop：它们是否支持钩子尚未验证。我们检查过的机器上都没有安装这两者。我们不会为它们编写钩子配置，除此之外也不声称有任何限制。

Cursor：Grok 的文档记载了 Cursor 钩子文件（~/.cursor/hooks.json）。我们不会编写该文件，也没有测试过我们的处理程序是否适用于它。

fimemory install-rules --list-hosts 会为你的机器打印以上所有信息：检测到的宿主、各宿主存放规则文件的位置，以及每个宿主的钩子说明和来源。

为什么规则块才是关键所在

install-mcp 让你的助手能够读取存储库。install-rules --mode shim 则会在提示词前注入相关笔记，让助手无需你要求就能读取存储库。根据我们自己的测量，这种方式的成本只是让助手通过工具调用搜索存储库的零头。如果没有它，工具虽然可用，却大多处于闲置状态。

shim 文案只会写入由检索钩子实际运行的宿主专门读取的文件。目前，这意味着在未安装 Grok CLI 的机器上使用 Claude Code。其他所有文件都会使用优先搜索的规则块，其文案会告知这些助手自行调用 fimemory_search，因为不会为它们注入任何内容。安装 Grok CLI 后，在下一次 setup 时，~/.claude/CLAUDE.md 会恢复为优先搜索的文案，因为 Grok 也会读取该文件。

遇到问题时

fimemory doctor 会检查存储库模式、密钥来源、各宿主配置中的 MCP 注册、规则块、检索钩子、目录索引，以及上次读取存储库的时间。它会指出缺少的内容以及相应的处理方法；实际发生故障时会以非零状态码退出。如果存储库索引缺失，或未列出磁盘上已有的笔记，就属于故障而非警告：搜索会读取索引，因此索引空白会导致助手悄无声息地找不到任何内容。

静态加密（默认设置）

新建的存储会使用 XChaCha20-Poly1305 加密，并通过 Argon2id 口令保护；创建时会显示一次 24 词恢复短语（fimemory encrypt 可将旧存储或 --plaintext 存储转换为相同状态）。如果口令和恢复短语都丢失，数据就会消失，这是有意为之。这里没有账户，也无法重置，因此恢复短语至关重要。

工具使用 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 可提前结束解锁状态。

关于第二天的实际情况，先说明清楚，免得你措手不及：解锁窗口到期且环境中没有口令时，CLI 命令会再次询问；MCP 工具每次调用都会返回清晰的“存储已锁定”错误，并说明如何解决（在工具运行的环境中设置 GESTALT_PASSPHRASE，或在任意终端运行 fimemory unlock；运行中的服务会在下一次调用时获取解锁状态，无需重启）；每次提示词触发的检索钩子则会保持静默，不会阻塞提示词。fimemory doctor 会明确报告这一状态。GUI 应用（Claude Desktop 等）读取的是操作系统用户环境，而不是你的 shell 配置文件，因此请在桌面会话可见的位置设置变量。

坦诚说明边界：存储解锁后，已连接的 MCP 客户端拥有与文件系统工具同等的读取权限。所有记忆 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，加密存储的口令就以明文形式保存在这些主机配置文件中。删除我们的条目时也会一并删除口令；对某些人来说，该配置文件可能是唯一的口令副本。因此，无论如何处理，顺序都很重要：

• **保留存储：**在删除任何内容之前，确保仍能打开存储：你可以使用记得的口令，也可以使用 24 词恢复短语。先运行 fimemory uninstall-mcp --dry-run。它会列出将要删除的环境变量，但绝不会显示变量值，也不会写入任何内容。
• **放弃存储：**先删除配置，再删除存储目录。这个顺序才是正确的，也能避免口令留在配置文件中。
• Claude Code 自身的二进制文件明确说明，claude mcp remove 会永久删除服务器配置，包括环境变量和标头，因此打印出的命令也会一并删除这些值。

存储位于你自己的目录中，因此删除存储就是删除一个目录：~/.fimemory（更名之前安装的版本则是 ~/.gestalt），或者你通过 --home 指定的位置。如果想保留笔记，请先导出。

你的文件，由你决定何时离开

fimemory export --plaintext <dir> 会将每条笔记、日志和建议的编辑内容导出为纯 Markdown，放在存储目录之外。这个退出途径确实存在，而且从第一天起就能使用。

命名说明

所有面向用户的名称均为 fimemory：命令、MCP 服务键和工具 ID（fimemory_search、fimemory_get……）。更名之前安装的版本仍可正常使用：位于 ~/.gestalt 的存储、GESTALT_* 环境变量以及旧的 gestalt MCP 条目都会继续被检测并受支持。

许可证

源代码可用，采用 FSL-1.1-ALv2 许可（参见 LICENSE.md）。 可免费使用和修改。不得出售或将其作为竞争性服务运行。每个版本在发布两年后转为 Apache-2.0。