ai-memory
三更灯火五更鸡，正是男儿读书时，黑发不知勤学早，白首方悔读书迟。——颜真卿
ai-memory：让 AI 编程助手真正记住项目的长期记忆
项目地址：https://github.com/akitaonrails/ai-memory
AI 编程助手最擅长的事情之一，是快速进入代码、阅读上下文、提出修改并执行任务。
但它们也有一个非常现实的限制：会话会结束，窗口会关闭，工具会切换，机器会更换，协作者会加入。昨天刚刚讨论过的架构决策，今天可能又要重新解释；刚刚尝试失败的方案，换一个助手后又可能被重复尝试；一个任务做到一半从 Claude Code 切换到 Codex，新的助手甚至未必知道前一个助手已经走到了哪里。
ai-memory 想解决的，就是这种持续性缺失。
它是一套面向 AI 编程助手的长期记忆方案，能够帮助不同工具之间交接任务，也能够让项目知识跨越会话、机器与人员继续存在。它将 AI 助手工作过程中产生的关键信息沉淀为可阅读的 Markdown 页面，并以 Git 支持的 Wiki 作为事实来源。
它不是让某个助手单独记住一点偏好。
它希望让一个项目拥有真正可延续的记忆。
当编程任务不该随着会话结束而失忆
一个真实的软件开发任务，很少能在一次会话中结束。
开发者可能先让 Claude Code 阅读架构，再交给 Codex 修改实现。某个问题可能在桌面设备上被定位，又在笔记本上继续排查。团队中的不同成员也可能分别与自己的 AI 助手协作，却需要面对同一个仓库、同一组规则与同一批尚未解决的问题。
如果每一次切换都需要重新讲述背景，AI 助手带来的效率就会被不断重复的上下文传递消耗掉。
ai-memory 的核心想法很直接：让记忆跟着工作走，而不是跟着某一个助手、某一台机器或某一次会话消失。
它可以记录当前任务进行到哪里，记录哪些方案已经失败，记录哪些问题仍然开放，也记录项目中已经形成的决定。当下一个助手进入同一目录时，它不必从零开始猜测，而可以从已有交接中接过工作。
这是一种更接近真实团队协作的方式。
工作不属于某一个窗口。
记忆也不应该只停留在某一个窗口里。
一个共享记忆，连接二十多种 AI 编程工具
ai-memory 支持二十多种工具与运行环境。
README 中列出的支持范围包括 Claude Code、Codex、Cursor、Gemini CLI、OpenCode、Grok、Devin、Kimi、Kiro、GitHub Copilot CLI、Factory Droid、Meta Muse Code、IBM Bob、Hermes Agent、GrizzyBot 等。
不同工具各自有不同的交互方式、扩展机制与生命周期，但 ai-memory 希望让它们汇聚到同一份共享记忆中。
这意味着，开发者可以在一个任务中使用不同的助手。
可以先在 Claude Code 中进行探索。
可以在 Codex 中继续实现。
可以在 Cursor 中查看与编辑。
也可以在其他受支持的工具中接过前一个助手留下的上下文。
当一个任务从一个助手交给另一个助手时，ai-memory 会提供交接信息，说明当前工作停在何处、已经发生过什么、哪些尝试没有成功，以及还有哪些问题等待处理。
这种交接并不是一段随意的文本。
README 将 handoff 描述为具有类型的协议。每一次交接都有所有者，并且只能被领取一次。于是，交接不只是“有人留下了一句话”，而是一根明确传递的接力棒。
不只传递摘要，也能延续会话细节
项目摘要很有价值，但摘要不可能包含所有细节。
有时，真正重要的信息藏在一次工具调用的输出中，藏在某个失败命令的报错里，藏在一段被截断的分析过程中。为了处理这种情况，ai-memory 提供 ai-memory run 方式来启动助手。
例如，可以先退出当前的 Claude Code 会话，再通过以下方式启动 Codex：
1 | ai-memory run codex |
在这种跨工具切换中，新的助手可以获得共享工作流信息，也可以获得一个私有、临时的本地投影，用于访问前一个助手可见的原生历史细节。
这种临时投影只保留在本地启动机器上。
远程服务器只会收到工具类型与会话身份，不会接收本地会话记录的路径或正文内容。临时文件会在受管理的子进程退出后消失。
这让跨助手延续不只依赖有限的启动摘要。
当简短交接中遗漏了具体细节时，后续助手仍然能够在本地范围内追溯前一段工作的上下文。
让个人工作习惯跨越不同项目
每个开发者都有自己的工作方式。
有人固定使用某种包管理器，有人习惯特定的测试布局，有人偏好某种架构组织方式。每次进入新仓库时，反复向 AI 助手解释这些习惯，同样是一种隐形的上下文成本。
ai-memory 提供跨项目个人档案。
这个档案可以记录开发者通常的工作偏好，并在每个新仓库的会话开始时提供默认信息。它位于每个仓库自身规则文件之下，作为更通用的默认层存在。
对于单个用户，跨项目档案默认开启。
在共享服务器中，它需要主动启用，并且会按个人保持私有。
这让记忆不只停留在项目层面。
项目有项目的架构、规则与历史。
开发者也有开发者自己的习惯、偏好与常用方式。
ai-memory 将这两种层次区分开来，让 AI 助手既能理解当前仓库，也能减少重复认识当前使用者的过程。
记忆可以跟随项目跨越机器
开发工作很少只发生在一台设备上。
桌面环境中留下的进度，可能需要在笔记本上继续。办公室中的任务，也可能需要在家庭实验室或局域网服务器中延续。若记忆只保存在当前机器上，切换设备时，AI 助手又会回到不知道历史的状态。
ai-memory 将记忆存放在由使用者运行的服务器中。
这个服务器可以位于同一台笔记本上，也可以部署在家庭实验室设备或其他位置。只要不同机器连接到同一个服务器，项目中的知识与待解决问题就可以继续存在。
于是，开发者在桌面设备上暂停的项目，可以在笔记本上继续。
新的会话不必从空白开始。
同一个项目的历史、页面、交接与待办问题，能够继续陪伴下一次工作。
团队记忆不等于公开所有私人交接
团队协作中的知识共享，需要同时处理公开与私人的边界。
ai-memory 支持多人使用同一个服务器。一个人的会话学到的项目知识，其他人的 AI 助手可以在同一项目范围内检索。与此同时，个人交接仍然保持为个人内容。
项目知识可以共享。
个人 handoff 可以保留私有。
README 中还提到，ai-memory 内置多用户认证、按人归属记录与审计日志，并且这些能力不是付费层级中的附加项目。
这使它不仅适合单人开发者，也面向需要共享项目知识的团队。
当多人共同处理同一个代码库时，很多信息原本会散落在不同对话、不同终端、不同问题单与不同人的记忆中。ai-memory 试图将其中与项目有关的知识汇集起来，让后续的 AI 助手能够检索到已经发生的工作，而不是一次又一次重复探索。
Markdown 才是记忆的事实来源
ai-memory 的一个重要选择，是使用 Git 支持的 Markdown Wiki 作为记忆的事实来源。
项目中的知识以普通 .md 文件保存。
它们可以被 grep 搜索，可以在 Obsidian 中打开，可以被手动编辑，也可以通过 rsync 同步。数据库只是从这些文件构建出来的派生索引，即使需要重建，也可以从 Markdown 文件重新生成。
这让记忆不会被锁进不透明的二进制格式中。
也不要求维护一个向量数据库作为唯一事实来源。
开发者能够直接查看记忆。
能够理解记忆写了什么。
能够编辑记忆。
能够通过版本控制追踪记忆的变化。
对于长期使用的项目而言，这种透明性尤其重要。AI 助手的记忆不再是一块无法查看的黑箱，而是能被人打开、阅读、修订和保留的项目资产。
自动捕捉工作，但不要求手动提醒
很多记忆工具需要用户主动说一句“请记住”。
ai-memory 的方向不同。
它通过生命周期钩子记录工作过程中发生的事件，包括提示词、工具调用与会话边界。记录进入存储流程之前，会经过具有类型的隐私边界清理。之后，服务器会将这些观察信息整合成更容易阅读的页面。
使用者不必不断提醒系统记住某件事。
在默认路径中，捕捉、搜索与交接都不需要 API 密钥，也不需要调用大语言模型。
这意味着，即使完全不配置 LLM 提供方，ai-memory 仍然能够完成自动捕捉、检索与交接。
它让长期记忆的基础能力不依赖于额外的模型调用。
工作发生时，信息被记录。
会话结束时，信息被整理。
下一次会话开始时，信息重新被带回。
从捕捉到交接，一条持续运行的记忆链路
ai-memory 将自身的基本工作过程概括为四个阶段：
1 | capture ──▶ consolidate ──▶ recall ──▶ handoff |
捕捉阶段由生命周期钩子安静地观察工作过程。
整合阶段会在会话结束后，将观察结果转化为项目 Wiki 中连贯的 Markdown 页面。
回忆阶段让下一次会话能够通过搜索与简报重新获得项目上下文。
交接阶段则把任务明确地传递给下一个助手，无论它使用的是哪一种受支持工具。
这条链路并不要求所有内容都被压缩为一句简单摘要。
搜索可以覆盖全文、实体、链接，并可选地结合向量检索。不同结果会被融合到同一个排序中。
因此，下一次会话获得的不是一个孤立标签，而是一套能够继续搜索、继续阅读、继续追踪的项目记忆体系。
不用 LLM，也能让记忆逐渐变得有秩序
长期记忆如果只会增加，最终也会变得难以使用。
ai-memory 因此提供了无需 LLM 的记忆老化机制。
记忆可以按照不同层级配置衰减计划。
被使用过的记忆会衰减得更慢。打开页面、搜索页面，或通过链接访问页面，都会被视为使用行为。
当情节型笔记逐渐变冷时，它们可以被压缩为更持久的事实，例如文件路径、错误代码与已经形成的决策，而不是直接被丢弃。
近似重复的内容可以收敛为一份。
可能互相矛盾的内容可以被标记。
这些过程默认不需要 API 调用。
项目还强调，原始内容不会被硬删除。原始版本仍然保留在 Git 中，版本链也能够通过 restore-page 恢复。
访问加权保留始终开启，因为它只会让记忆保留得更久。
而会改写或丢弃内容的部分，包括压缩、去重与分层衰减曲线，则默认关闭，直到使用者主动启用。
这种设计体现出一种克制的记忆管理方式。
记忆可以变化，但不会轻易失去来源。
记忆可以被压缩，但不会直接失踪。
可选的梦境整理，让冷记忆重新汇聚
ai-memory 还提供一个可选能力，被称为 dream。
当配置了 LLM 后，系统可以在空闲时对成组的冷记忆进行后台整理，将多个页面重写为一份更连贯的页面。当使用者重新开始工作时，这个过程会取消。
这种能力默认关闭。
它不会删除源页面，合并之前的版本仍然可以访问。项目还要求这一能力在可能成为默认行为之前，先通过回忆评估。
这使 dream 更像一项主动选择的增强能力，而不是强制发生的自动改写。
不配置 LLM 时，ai-memory 仍然可以正常工作。
配置 LLM 后，记忆则可以获得额外的整合能力。
两条路径共同存在，但默认仍然站在零 LLM 调用的一侧。
一个二进制文件，承载服务器与数据目录
ai-memory 以单个 Rust 二进制文件的形式提供。
这个二进制文件运行 MCP 与 HTTP 服务，并管理一个数据目录。目录结构中包含 Wiki、原始观察记录、SQLite 索引、预留的本地嵌入模型位置与日志。
1 | <data_dir>/ |
其中，wiki/ 保存作为事实来源的 Git 版本化 Markdown 内容。
raw/ 保存不可变的、经过清理的受管理工作流会话片段。
db/ 保存 SQLite 索引，其中包括 FTS5、实体与嵌入相关内容。
models/ 为本地嵌入模型保留。
logs/ 则保存滚动追踪输出。
服务器会通过单个 SQLite 写入者序列化写入操作，并将会话观察信息编译为 Markdown 页面。检索过程会结合 FTS5、实体匹配、图邻居相关排序、可选向量排序、观察证据流与其他受限调整机制。
这让 ai-memory 的结构具备两层含义。
一层是使用者可以直接阅读和控制的 Markdown Wiki。
另一层是用于高效搜索与索引的数据库结构。
前者保证透明与可拥有。
后者保证检索与服务能力。
两条命令开始安装
在 Linux 与 macOS 上，README 提供了两条命令的安装方式：
1 | curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh |
安装脚本会下载适用于当前操作系统与 CPU 的发行版本，并使用已发布的 SHA-256 校验和进行检查。校验不匹配时，脚本会拒绝安装。
之后，ai-memory setup 会创建数据目录，在仅所有者可访问的文件中创建 Bearer Token，并启动每用户服务。
在 Linux 上，它会使用 systemd 用户服务。
在 macOS 上，它会使用 launchd LaunchAgent。
安装流程还会查找已安装的 AI 助手，并为检测到的工具配置 MCP、生命周期钩子与 Agent Skills。它会先展示计划，说明找到了哪些工具，并等待确认。
如果只想查看计划而不修改任何内容，可以使用：
1 | ai-memory setup --plan |
如果希望在浏览器中查看计划并选择需要配置的工具，可以使用：
1 | ai-memory setup --web |
如果希望跳过确认，可以使用：
1 | ai-memory setup --yes |
安装完成后，重启对应的 AI 助手，再询问它“你还记得这个项目什么”，便可以通过 ai-memory 获取项目记忆。
Windows 也可以无管理员权限开始
在 Windows PowerShell 中，可以执行：
1 | irm https://github.com/akitaonrails/ai-memory/releases/latest/download/install.ps1 | iex |
安装脚本会校验发行包的 SHA-256，然后将内容解压到用户本地应用程序目录，并将对应路径加入当前用户的 PATH。
之后，ai-memory setup 会创建数据目录、Token 与工具配置，并使用登录项启动服务。服务会在用户登录时启动，不显示控制台窗口，并在失败时尝试重启。
README 也说明了 Windows via WSL2 属于受支持范围，而原生 Windows 目前属于实验性支持。
从 Arch Linux 到 Fedora 的安装路径
对于 Arch Linux，项目提供 AUR 包。
预构建二进制包可以通过以下命令安装：
1 | yay -S ai-memory-bin |
如果希望从源代码构建，可以使用：
1 | yay -S ai-memory |
安装后，再执行：
1 | ai-memory setup |
对于 Fedora，README 提供 RPM 安装路径。下载对应架构的 RPM 后，可以使用：
1 | sudo dnf install ./ai-memory-*.rpm |
随后继续执行：
1 | ai-memory setup |
不同系统的安装方式不同，但后续目标一致：准备数据目录，启动服务，为已使用的 AI 工具建立捕捉、检索与交接能力。
使用插件连接 Claude Code 与 Codex
Claude Code 与 Codex 用户还可以通过插件市场连接 ai-memory。
Claude Code 的安装方式为：
1 | claude plugin marketplace add akitaonrails/ai-memory |
Codex 的安装方式为：
1 | codex plugin marketplace add akitaonrails/ai-memory |
Codex 会要求使用者信任 /hooks 中的钩子。
这些插件不携带二进制文件，不需要单独构建，也不会在首次运行时下载二进制内容。插件中包含清单、路由技能、状态技能、MCP 入口和一个 POSIX Shell 脚本。
生命周期事件最终由已安装的本地 ai-memory hook 命令处理。
这个本地命令会在事件进入队列或网络之前，应用捕捉策略，包括忽略路径、允许列表模式与服务器配置。插件脚本本身不会直接发送任何内容。
插件文件中没有遥测内容，也不保存凭据。钩子与 MCP 桥接使用的是 ai-memory CLI 已经保存的凭据。
ai-memory run，让启动助手时自动带上记忆
README 特别推荐通过 ai-memory run 启动工具。
第一次使用它启动某个助手时，系统会自动检查并安装该助手所需的钩子与 MCP 配置。它会按照构造好的方式连接正确的项目范围，并在共享记忆之上增加跨工具的会话连续性。
例如：
1 | ai-memory run claude |
也可以通过以下命令启动 Codex 并传递参数：
1 | ai-memory run codex --yolo |
如果希望使用可复用的配置预设，可以这样执行：
1 | ai-memory run --profile work claude |
对于最近的受管理工作流，可以使用：
1 | ai-memory continue |
也可以恢复当前仓库中的工作流：
1 | ai-memory resume |
如果希望通过名称搜索工作流，可以使用：
1 | ai-memory resume --search auth |
如果希望跨越所有关联工作目录进行选择，可以使用：
1 | ai-memory resume --all |
当之前的启动器已经终止，但活动租约仍然存在时，可以使用：
1 | ai-memory run --force-unlock codex |
这一选项会立即使所选工作流的活动租约过期，但不会终止原生进程，也不能驱逐另一位已认证操作者正在进行的工作。
这些命令让记忆不只停留在后台服务中，也真正进入日常的 AI 助手启动动作。
离线时继续工作，服务恢复后再补回
网络或服务并不总是稳定。
当 ai-memory 服务不可达时，ai-memory run 会给出提示，但仍然启动助手，并在本地保存捕捉内容。服务恢复后，可以使用 ai-memory recover 进行恢复。
如果希望在服务不可用时直接停止启动，而不是允许降级运行，可以添加：
1 | --require-server |
这种设计让记忆服务不会成为开发工作无法继续的单点阻塞。
服务可用时，内容正常进入共享记忆。
服务暂时不可用时，工作仍然可以继续。
之后再进行恢复，让记录重新回到长期记忆中。
Docker 部署，让记忆服务运行在容器里
ai-memory 也提供 Docker 或 Podman 使用方式。
发布的镜像同时包含 linux/amd64 与 linux/arm64 变体，因此 Apple Silicon Mac 与 ARM64 Linux 主机可以直接拉取对应镜像，而不需要额外指定 x86_64 仿真平台。
README 中的 Docker 快速开始默认不启用认证，容器也只绑定到回环地址。这样，外部网络无法直接访问服务，但本机进程与浏览器页面可以访问。
以下命令展示了服务容器启动方式：
1 | docker run -d --name ai-memory \ |
如果不使用 LLM 与嵌入提供方，依然可以运行零 LLM 模式，FTS5 搜索也可以继续工作。
在容器化环境中，使用者还可以通过 CLI 包装器为不同工具安装 MCP 与钩子，从而让容器服务与本地 AI 助手连接起来。
从日常使用中逐步形成记忆
ai-memory 的目标不是让使用者每天花时间维护一套复杂知识库。
README 对日常使用的描述十分朴素：大多数时候，不需要特别想到 ai-memory 的存在。
钩子会捕捉提示词、工具调用与会话边界。
会话结束后，内容会变成可阅读的 Wiki 页面。
下一次会话开始时，助手会从交接中获得上下文。
开发者可以直接对助手说：
- 我们上次做到哪里了
- 我们讨论过某个问题吗
- 搜索关于某个主题的记忆
- 帮我回顾近期项目活动
对于已经存在很久的项目，还可以执行：
1 | ai-memory bootstrap |
这项命令用于在采用 ai-memory 时，为已有项目建立初始记忆基础。
项目也提供只读浏览器视图与 JSON API。通过启用 Web 功能，可以在浏览器中阅读 Wiki，并通过 API 获取相关内容。
多机器与团队共享，但仍保留归属与审计
当 ai-memory 服务器部署在局域网主机、家庭实验室设备或其他可访问位置时，多台机器与多个团队成员可以连接到同一份项目记忆。
项目知识按项目共享。
个人 handoff 保持个人属性。
每一次写入都可以归属到具体人员，并被记录在审计日志中。
项目提供多用户认证，包括密码与 API 凭据。也提供可选的会话管理与自助 API Key 能力。
会话管理允许已登录用户查看会话，并删除属于自己的会话。
自助 API Key 功能则允许用户签发与撤销自己的 aim_ API Key。
这些 HTTP 能力默认关闭，需要主动启用。
这让 ai-memory 的团队使用方式保持谨慎：共享能力存在，但不会在默认情况下把所有管理功能暴露出来。
默认绑定本机，安全从本地开始
ai-memory 默认只绑定到回环地址。
新的 ai-memory init 会在数据目录中生成根 Bearer Token，钩子、CLI 与 ai-memory mcp-bridge 都从该位置读取 Token，而不会将它写入 AI 工具配置文件中。
对于较早安装的实例以及 Docker 快速开始环境，可能默认未启用认证。项目提供 ai-memory auth enable 来启用认证，ai-memory status 也会显示当前认证状态。
README 描述了一条渐进式加固路线。
可以先从局域网 Bearer Token 开始。
然后使用按用户划分的账号。
再到用于钩子的 OIDC 设备认证。
最后可在反向代理前配置 TLS。
在捕捉侧，内容会先经过具有类型的隐私边界清理。每个仓库也可以通过 [capture] 规则排除路径，或切换到允许列表模式。仓库还能够将捕捉路由到与默认钩子服务器不同的服务器。
这使安全并不是一个只有开启或关闭的选项，而是一条可逐步建立的路径。
LLM 是可选增强，不是默认前提
ai-memory 支持可选的 LLM 提供方。
配置 LLM 后，可以提升会话摘要能力，并启用语义搜索。项目支持 Anthropic、OpenAI、OpenAI OAuth、Codex CLI 凭据复用、GitHub Copilot、Gemini、OpenCode 相关提供方，以及兼容 OpenAI API 的端点，例如 Ollama、LM Studio 与 vLLM。
嵌入能力则支持 OpenAI、Voyage、Gemini 与无需密钥的 OpenAI 兼容端点。
但这些都不是 ai-memory 基础运行的必要条件。
没有 API Key 时，自动捕捉、全文搜索、交接、记忆老化、提取式压缩、去重、矛盾标记与访问加权保留仍然可以工作。
这种设计让使用者可以先从本地、零 LLM、零 API 调用的方式开始。
之后，如果需要更丰富的整合与语义检索，再主动引入模型能力。
记忆质量，也需要被认真评估
ai-memory 仓库中包含评估工具。
这些工具不是发布版本的一部分，而是用于比较不同模型、不同提供方或不同提示词调整下的整合效果与检索表现。
评估程序可以并排运行两个 LLM 提供方，保存双方输出，并对文本忠实度进行评分。也可以在不使用任何模型的情况下，测试观察投影是否将应保留的事实送入了整合请求。
项目还提供 LongMemEval 检索基准评估。
这一评估通过真实的 ai-memory serve 子进程运行，使用实际服务的检索链路，并报告命中情况、延迟以及代理可能接收的上下文 token 估计。
这种评估体系说明，ai-memory 不只关注“看起来记住了什么”。
它也尝试追问：关键事实是否真的被保留，检索是否能找到相关会话，性能与上下文成本处于怎样的状态。
对于长期记忆系统而言，这种追问很重要。
记忆不是写下来就结束了。
它还必须在需要时被找回来。
让 AI 助手从临时对话者变成持续协作者
ai-memory 的意义，不在于为 AI 助手增加一段更长的上下文。
它所尝试构建的，是一种更持续的协作关系。
今天的助手可以留下工作痕迹。
明天的助手可以接手。
不同工具可以共享项目知识。
不同机器可以继续同一条工作线。
团队成员可以让自己的助手检索共同积累的项目记忆。
而所有这些内容，最终都落在可以查看、编辑、搜索、同步与版本控制的 Markdown Wiki 中。
它让 AI 编程助手不再只是一场会话中的临时参与者。
它们可以开始拥有共同的过去。
也可以在同一个项目里，继续走向下一步。