ai-memory — Chat History → AGENTS.md + Cursor Rules + MCP

ai-memory

将 AI 编辑器聊天记录转换为类型化 Markdown + AGENTS.md 规则 — 本地优先、可用 git 跟踪，无需调用 .remember()。

npx ai-memory-cli extract                     # read your editor's chat history → typed Markdown
npx ai-memory-cli rules --target agents-md    # → AGENTS.md (Cursor / Claude / Windsurf / Copilot / Codex all read it)
npx ai-memory-cli recall "OAuth"              # show the full git lineage of any decision
npx ai-memory-cli context --copy              # resume any session with full context

其他所有“AI 记忆”工具都从 remember() API 入手，并要求你在代码中添加埋点。ai-memory 直接读取编辑器的聊天记录 — Cursor、Claude Code、Windsurf、Copilot Chat、Codex CLI — 并将其转换为类型化、可用 git 跟踪的 Markdown，供每个 AI 编辑器通过 AGENTS.md 读取。无需学习新的 API，也无需在会话之间维持运行时记忆存储。

默认本地优先。 对话不会离开你的设备；唯一的网络请求是调用你为提取配置的大模型提供商。你也可以使用 Ollama / LM Studio 实现完全离线运行。

中文文档

---

只有 ai-memory 能做到的事

四项其他任何工具都无法兼得的能力。前三项是结构层面的优势；第四项是其他项目都没有投入的工程实践。

1. 无需编写 .remember() 样板代码。 我们读取你已经写下的内容 — 已保存在磁盘上的 Cursor / Claude Code / Windsurf / Copilot Chat / Codex CLI 记录。无需导入 SDK，也无需维持运行时记忆存储。与 mem0 / Letta / Zep / cortexmem 相比，它们要求你在应用代码中调用 client.add(...)。

2. 原生输出 AGENTS.md。 ai-memory rules --target agents-md 会写入跨工具的标准规则文件，供 Cursor、Claude Code、Windsurf、Copilot 和 OpenAI Codex CLI 使用。合并操作具有幂等性：只会修改 ... end --> 之间的部分；AGENTS.md 中任何手写内容都会逐字节保留。采用 AGENTS.md 的仓库已超过 60K，目前由 Linux Foundation 托管 — 大多数项目都从头手写规则文件；我们则根据你的对话记录生成它。

3. 将纯 Markdown 纳入 git — 无需数据库。 .ai-memory/ 是唯一可信来源：其中的 Markdown 文件可用 git diff 查看、进行代码审查、创建分支并回退。其他宣称记忆“可用 git 跟踪”的工具，提供的是内部存储的 git 跟踪快照；我们提供的是便于人类阅读的文件格式，让 git 管理一切。跨设备同步只需运行 git pull。

4. 通过 git 历史穿越时间回溯。 ai-memory recall <query> 会展示每条记忆逐次提交的完整沿革：4 月 1 日的决策内容、4 月 15 日的内容、哪些内容发生了变化以及是谁修改的。其他所有记忆工具都只会返回“最新内容” — 已被取代的版本会被悄然覆盖。无需引入新的运行时依赖：recall 会调用你已有的 git，并设置 10 秒超时。

我们如何衡量自身表现

CCEB — Cursor 对话提取基准，gpt-4o-mini，30 个人工精选样例（v1.1 扩展）：

指标	v1.1（2026-04-27，30 个样例）	v1.0 / v2.5-01（2026-04-26，9 个样例）	v2.4（2026-04-25，9 个样例）
总体 F1	64.1%（P 56.8% / R 73.5%）	76.2%（P 66.7% / R 88.9%）	56.0%（P 43.8% / R 77.8%）
decision / issue F1	78.3% / 100%	75.0% / 100%	66.7% / 66.7%
architecture F1	72.7%（召回率成为新的瓶颈）	100%	50%
噪声排除（闲聊 / 延后处理 / 假设性内容）	100% — 4 个噪声样例均未产生幻觉记忆	100%（2 个样例）	100%（2 个样例）
实际耗时	239.7 s	47.9 s	70.5 s
费用	≈ $0.02	≈ $0.006	≈ $0.005

v1.1 扩展（cceb-001 — cceb-030）特意加入了 v1.0 未覆盖的更难案例：单次对话包含多条记忆（架构 + 约定）、承诺类型存在歧义（流程事项还是技术待办）、CJK／混合语言对话，以及决策影响与后续待办之间的甄别。与上方 9 个样例那一行相比，F1 下降了 12 个百分点；这并非模型退化——仅用 v1.0 样例运行相同提示词，得分仍为 76%。在不那么经过挑选的样例分布上，64% 才是对同一提取器更诚实的衡量。剩下最大的改进空间是 todo 精确率（19 个假阳性中有 11 个是待办）；根据基准文档的分析，下一步是在提取后进行成对内容去重，此项已列入 v2.6 跟踪。

样例漏检、样例假阳性、逐样例详情、v1.0 → v1.1 差异分析和方法说明均见基准文档。相比追逐一个上游模型一更新就会变化的排行榜分数，我们更愿意公布经得起质询的数据。

LongMemEval-50（跨语料库合理性检查，bench/longmemeval/）：在 LongMemEval-S-cleaned 的一个确定性 50 题子集中，按我们的字面令牌证据保留评分标准，使用 gpt-4o-mini 得分为 0 / 50 完全保留 + 2 / 50 部分保留（约 12 分钟，约 $0.40）。这是一个刻意严格的代理指标（“上游答案中的每个关键令牌是否都保留在提取出的记忆中？”，而非 LongMemEval 原生问答正确率——评分标准见实验文档 §4.3）；0/50 表明 ai-memory 并非面向从 500 轮对话中进行开放域问答，而基准文档中的逐题匹配数／总数显示了部分信号出现的位置（单会话偏好：17-43 个令牌中，有 3-6 个能稳定保留）。LongMemEval、LoCoMo 等衡量的是运行时的回忆（Agent 是否记住某个事实）；我们衡量的是提取（是否从聊天中提取出了正确的结构化产物）。这是不同的层面，也是在回答不同的问题——另见类别定位 ADR。

它还能处理的其他事项

• 节省令牌 — context 可将数千轮对话压缩成聚焦的提示词（通常比粘贴原始历史记录减少 90% 以上）。
• 支持团队协作 — 在 .ai-memory/{author}/ 下按作者建立子目录，两人从同一项目提交记忆时不会产生合并冲突。
• 跨设备便携 — export / import 可将整个存储以带版本号的 JSON 包进行往返导入导出。
• 零配置、无需 API 密钥 — npx ai-memory-cli extract 使用内置免费模型即可立即运行；设置自己的密钥即可移除 2 个对话的限制。

---

常见问题解答

“100 万令牌的上下文不会让你变得多余吗？”

简短回答：长上下文和 ai-memory 解决的是同一问题的不同方面。100 万令牌的上下文窗口让模型能在一次查询中看到一段很长的对话；ai-memory 则让这段对话中的决策能够跨会话、机器和团队成员持久保存、供人审阅和分享。下面我们会认真回答这个问题，因为它是 HN 上针对任何结构化记忆工具被引用最多的异议。

每次查询都重新发送历史记录，成本会不断累积。 截至 2026-04，前沿模型的输入定价约为每 100 万令牌 $1–$3（Anthropic / OpenAI / Google AI）。一次为期两周的 Cursor 会话，算上工具调用负载和文件差异，通常会达到 100–300K 令牌；每轮都粘贴这段历史记录，在你提出任何问题之前，每次查询就要花费 $0.20–$0.60。从同一段对话生成的 AGENTS.md 大约只有 1–5K 令牌，而且每个会话只加载一次。再乘以团队规模和每日查询次数，成本差距就会达到两个数量级。

长上下文检索对非重点信息的处理仍会退化。 “迷失在中间”（Liu 等人，2023）以及 100 万规模的“大海捞针”（BABILong，Kuratov 等人，2024）都表明，在超过约 128–256K 令牌后，多跳检索的召回率会出现可测量的下降，即便模型宣称支持 100 万令牌的上下文窗口也是如此。长上下文对最近和最醒目的对话轮次效果很好；但对于日常的问题——“等等，我们三周前关于 X 做了什么决定？”——效果就会退化，而这正是记忆工具旨在解决的问题。提取过程不会丢失唯一重要的信号（经过类型标注的决策 / 约定 / 架构）。

长上下文针对单台机器；AGENTS.md 针对单个代码仓库。 笔记本电脑上的聊天记录帮不了团队成员度过入职第一天。提交到 git 的 .ai-memory/ 目录则可以——它能在 PR 中接受审查、创建分支、还原，并能被每台机器上克隆该代码仓库的每个编辑器重新读取。请参阅只有 ai-memory 能做到的事——第 3 点和第 4 点有更详细的说明。

如果 (a) 前沿模型的价格降至每百万令牌低于 $0.50，(b) 长上下文基准测试显示超过 500K 令牌后的检索退化低于 5%，或 (c) 编辑器开始原生支持跨会话对话压缩，我们就会重新评估这个常见问题。触发条件列表和完整理由见 docs/1m-context-faq-spike-2026-04-27.md。

---

快速开始

# Initialise project (optionally register ai-memory as an MCP server)
npx ai-memory-cli init --with-mcp

# Extract — works out of the box with the built-in free model (no API key needed)
# Limited to 2 conversations per run on the built-in key.
npx ai-memory-cli extract

# Unlock unlimited extractions — set your own key (any OpenAI-compatible provider)
export AI_REVIEW_API_KEY=sk-...    # or OPENAI_API_KEY

# One-shot health check — verifies editors, API key, store, MCP config
npx ai-memory-cli doctor

# Search your knowledge base
npx ai-memory-cli search "authentication"

# Generate Cursor Rules from conventions
npx ai-memory-cli rules

# Generate a context prompt and copy to clipboard
npx ai-memory-cli context --copy

# Commit to git
git add .ai-memory/ && git commit -m "chore: add ai-memory knowledge base"

---

命令

try — 无需 API 密钥的演示（30 秒，零凭证）

在临时目录中初始化一个包含 3 条精心整理的记忆的存储库，在其中运行真实的 rules --target agents-md 流程，并以内联方式打印生成的 AGENTS.md。不会调用大模型，不需要 API 密钥，也不会更改你的工作目录——在着手配置之前，让你具体了解“这个工具究竟会生成什么？”

npx ai-memory-cli try                     # full demo, tmp dir cleaned up afterwards
npx ai-memory-cli try --keep              # leave the tmp scenario on disk for inspection
npx ai-memory-cli try --json              # structured output (counts, AGENTS.md content, paths)

附带的场景包含 1 条决策（PKCE 身份验证流程）、1 条架构记录（事件溯源式计费审计日志）和 1 条约定（Relay 风格的游标分页），涉及两位作者。只有约定和决策会写入 AGENTS.md——这与真实的 rules 命令筛选你自己的记忆时使用的规则相同。

doctor — 一次性健康检查

如果你决定让 ai-memory 处理真实的聊天记录，请在运行 try 后运行此命令。它会诊断 6 种最常见的配置问题，并准确说明如何逐一修复。

npx ai-memory-cli doctor                 # human-readable report
npx ai-memory-cli doctor --no-llm-check  # skip live API call (offline / CI)
npx ai-memory-cli doctor --json          # structured output for automation / bug reports

检查内容包括：Node.js 版本、检测到的编辑器（Cursor / Claude Code / Windsurf / Copilot / Codex CLI 及对话数量）、大模型提供商及实时连通性探测、记忆存储库及作者解析、嵌入的新鲜度，以及 MCP 配置注册。如果全部检查通过，退出代码为 0；如果任一检查失败，则为 1。未配置 API 密钥时，doctor 现在会推荐将 try 作为无密钥的快速路径。

list — 显示可用的对话

npx ai-memory-cli list                            # show all conversations
npx ai-memory-cli list --source cursor             # only Cursor conversations
npx ai-memory-cli list --json                      # JSON output

extract — 从对话中提取记忆

npx ai-memory-cli extract                          # extract all conversations
npx ai-memory-cli extract --incremental             # only new conversations
npx ai-memory-cli extract --pick 3                  # only conversation #3
npx ai-memory-cli extract --pick 1,4,7              # multiple conversations
npx ai-memory-cli extract --id b5677be8             # match by ID prefix
npx ai-memory-cli extract --since "3 days ago"      # only recent conversations
npx ai-memory-cli extract --type decision,todo      # only specific types
npx ai-memory-cli extract --dry-run                 # preview without writing
npx ai-memory-cli extract --force                   # overwrite existing files
npx ai-memory-cli extract --author "alice"          # override author name
npx ai-memory-cli extract --redact                  # scrub secrets / PII before LLM call (v2.5+)
npx ai-memory-cli extract --verbose                 # show LLM request details
npx ai-memory-cli extract --json                    # JSON output (CI friendly)

没有 API 密钥？ extract 会自动回退到内置的免费模型（通过 SiliconFlow 提供的 DeepSeek-V4-Flash），每次运行最多处理 2 个对话，每个对话最多处理 20 个片段（均匀采样——覆盖整个对话的内容，而不只是开头几轮）。设置 AI_REVIEW_API_KEY 或 OPENAI_API_KEY 即可解除这两项限制。

--redact — 发送给大模型前清除机密信息／个人身份信息／内部主机名（v2.5+）

extract、summary 和 context --summarize 会将对话摘录发送给你配置的大模型提供商。“本地优先”适用于存储层——.ai-memory/ 是纯 Markdown，我们绝不会上传它——但提取调用必须通过 HTTPS 向外发送请求。如果聊天记录中意外粘贴了 API 密钥、堆栈跟踪中的内部主机名，或日志中的客户电子邮件地址，--redact 会在请求离开你的设备前将其清除。

$ ai-memory extract --redact
   ...
Redaction: 5 items scrubbed before LLM (118 chars) — 3 openai-key, 2 email

默认启用的规则（10 项）：OpenAI／Anthropic／AWS／GitHub／Slack／GCP／Stripe API 密钥、RFC5322 电子邮件地址，以及 *.internal／*.corp／*.local／*.lan／*.intra 主机名。另有两项默认关闭的可选规则（jwt、aws-secret-key），因为它们对长 Base64 字符串的误报率较高；可通过 .ai-memory/.config.json 启用：

{
  "redact": {
    "enabled": true,
    "enableOptional": ["jwt"],
    "rules": [{ "name": "internal-jira", "pattern": "JIRA-[0-9]{4,}" }]
  }
}

命令行选项会覆盖配置：--no-redact 始终禁用，--redact 始终启用。启用清除功能时，审计记录（每条规则的命中次数）始终开启，且会同时显示在普通输出和 --json 输出中。绝不会记录匹配到的值——否则就失去了清除的意义。

威胁模型。 这是纵深防御，不能替代恰当的机密信息管理。完整的策略文档——包括不在适用范围内的项目（图像附件、对既有记忆进行追溯清除、结构化个人身份信息保险库检查）以及威胁模型边界——见 docs/redaction-policy-2026-04-26.md。

search — 搜索已提取的记忆

npx ai-memory-cli search "OAuth"                   # keyword search across all memories
npx ai-memory-cli search "payment" --type decision  # filter by type
npx ai-memory-cli search "auth" --author alice      # filter by author
npx ai-memory-cli search "API" --include-resolved   # include resolved memories
npx ai-memory-cli search "config" --json            # JSON output

结果按相关性排序（标题匹配 > 内容 > 上下文），并突出显示关键词。

recall — 通过 git 历史回溯记忆

其他所有“记忆”工具都会将存储内容压平为“最新”版本——所有被取代的版本都会被静默覆盖。由于 .ai-memory/ 是 git 仓库中的纯 Markdown，每条事实的完整沿革早已保存在磁盘上；recall 将其作为一等命令呈现。

npx ai-memory-cli recall "OAuth"                   # show how the OAuth decision evolved
npx ai-memory-cli recall "OAuth" --include-resolved # include superseded / resolved memories
npx ai-memory-cli recall "API" --type decision      # filter by type
npx ai-memory-cli recall "auth" --all-authors       # search across the whole team
npx ai-memory-cli recall "OAuth" --json             # structured output (one entry per memory + its commit list)

输出如下：

Recall: "OAuth" — 1 memory, 4 commits of lineage

[+] CURRENT  Use OAuth 2.0 PKCE for SPA  @conor (2026-04-20)
    .ai-memory/conor/decisions/2026-04-20-use-oauth-pkce.md
    History (4 commits):
      a1b2c3d  2026-04-20  conor   ~ Tighten OAuth PKCE: require HTTPS-only token endpoint
      e4f5g6h  2026-04-15  conor   ~ Switch from implicit flow to PKCE
      i7j8k9l  2026-03-20  conor   + Add OAuth library notes
    > git log --follow .ai-memory/conor/decisions/2026-04-20-use-oauth-pkce.md  for full diffs

• 使用 git log --follow，因此可以透明地跟踪 .ai-memory/ 内的重命名。
• 每行显示短 SHA、ISO 日期、作者、状态代码（+ 新增，~ 修改，- 删除，R 重命名）和提交主题。
• 软回退——在 git 仓库之外，或在 .ai-memory/ 首次提交之前，recall 仍会返回匹配的记忆，并附上说明缺少什么的提示。任何情况下，recall 的表现都不会差于 search。
• 不新增运行时依赖——仅使用 node:child_process.execFile 调用你现有的 git，并设有最长 10 秒的超时。

rules — 将约定导出为 Cursor Rules、AGENTS.md 和 Anthropic Skills

生成每个 AI 工具都能原生读取的编辑器规则：

npx ai-memory-cli rules                            # default: .cursor/rules/ai-memory-conventions.mdc
npx ai-memory-cli rules --target agents-md         # AGENTS.md (Codex / Cursor / Windsurf / Copilot / Amp)
npx ai-memory-cli rules --target skills            # Anthropic Skills (Claude Code) — v2.5+
npx ai-memory-cli rules --target both              # write Cursor Rules + AGENTS.md at default paths
npx ai-memory-cli rules --output my-rules.mdc      # custom output (single-target only)
npx ai-memory-cli rules --all-authors              # include team conventions

--target agents-md 会执行幂等合并：仅修改 ... end --> 之间的部分，因此 AGENTS.md 中任何手动编写的内容都会逐字节保留。若没有新增记忆而再次运行，则不会执行任何操作（already-up-to-date）；如果标记因编辑中断而格式错误，系统会报告冲突，并保持文件不变。

--target skills 会在 .claude/skills/ 下写入 Anthropic Skills。系统会针对每种长期记忆类型生成一个技能，共三个：

技能	来源	告诉 Claude 的内容
.claude/skills/ai-memory-coding-conventions/SKILL.md	convention 记忆	编写新代码、命名事物或设计 API 时
.claude/skills/ai-memory-decision-log/SKILL.md	decision 记忆（状态 ≠ resolved）	提议架构变更或被问及为何做出某项选择时
.claude/skills/ai-memory-system-architecture/SKILL.md	architecture 记忆	实现跨组件功能或调试集成时

Claude Code 会根据 YAML frontmatter 中的 description 与你的请求是否匹配，动态加载技能；与 AGENTS.md（始终生效的上下文）不同，技能正文仅在相关时才会进入上下文。我们所采用的架构（于 2026-04-26 冻结）见 docs/skills-schema-snapshot-2026-04-26.md。技能名称中的 ai-memory- 前缀用于标识归属：.claude/skills/ai-memory-*/ 中的所有内容都会在每次运行时完全重新生成；其他目录名下由用户编写的技能则会原样保留。

这是从对话到规则的流水线——从聊天记录中提取约定，并自动生成每个 AI 编辑器都会读取的规则文件。没有其他工具能从单份聊天记录输入中同时生成 Cursor Rules、AGENTS.md 和 Anthropic Skills。

resolve — 将记忆标记为已解决

决策可能被推翻，待办事项也会完成。保持知识库内容最新：

npx ai-memory-cli resolve "OAuth"                  # mark matching memories as resolved
npx ai-memory-cli resolve "OAuth" --undo           # reactivate resolved memories

已解决的记忆会自动从 context、summary 和 search 结果中排除。使用 --include-resolved 可强制包含。

summary — 生成项目级摘要

npx ai-memory-cli summary                          # write/update SUMMARY.md
npx ai-memory-cli summary --output MEMORY.md       # custom output path
npx ai-memory-cli summary --focus "payment module"  # focus on a topic
npx ai-memory-cli summary --all-authors             # include all team members
npx ai-memory-cli summary --include-resolved        # include resolved memories

# Scope summary to a single conversation (no LLM cost for the wrong chats)
npx ai-memory-cli summary --list-sources           # list conversations first
npx ai-memory-cli summary --source-id b5677be8     # summarize ONE chat
npx ai-memory-cli summary --convo "payment refactor"

context — 生成续接提示词

无缝地在新对话或另一台机器上继续工作：

npx ai-memory-cli context                          # generate context block (instant, no LLM)
npx ai-memory-cli context --copy                   # generate and copy to clipboard
npx ai-memory-cli context --topic "coupon system"  # focus on a specific topic
npx ai-memory-cli context --recent 7               # only last 7 days of memories
npx ai-memory-cli context --output CONTEXT.md      # write to file
npx ai-memory-cli context --summarize              # use LLM for condensed prose summary
npx ai-memory-cli context --all-authors            # include all team members
npx ai-memory-cli context --include-resolved       # include resolved memories

将上下文限定在单次对话中——因为现实中，你通常只想继续一段聊天，而不是把所有内容都倾倒出来：

# 1. See which conversations produced memories
npx ai-memory-cli context --list-sources
#  #  Date        Source        ID        Count  Types              Title
#  ------------------------------------------------------------------------------
#   1  2026-04-01  cursor        b5677be8    12  D:4 A:3 C:5        resume tool
#   2  2026-03-28  claude-code   ff12abc3     7  A:4 T:3            ai-lab

# 2. Copy context from ONE conversation (ID prefix, like git short hash)
npx ai-memory-cli context --source-id b5677be8 --copy

# 3. Or match by conversation title — picks the most recent if multiple match
npx ai-memory-cli context --convo "resume tool" --copy
npx ai-memory-cli context --convo "resume" --all-matching --copy   # include every "resume*" chat

link — 将记忆关联到实现它们的提交（v2.6）

npx ai-memory-cli link                             # scan last 30 days of commits
npx ai-memory-cli link --since "7 days ago"        # custom time window
npx ai-memory-cli link --dry-run                   # preview links without writing
npx ai-memory-cli link --clear-auto                # remove all auto-generated links

扫描你的 git 日志，并使用加权 token 重叠对每个（记忆、提交）组合进行评分：记忆标题 × 3、类型 × 2、内容 × 1，与提交主题 × 3、变更路径 × 2、正文 × 1 进行比较。高置信度匹配（score ≥ 0.70）会以不可见的 HTML 注释块写入记忆文件，供仪表板显示。默认阈值较为保守——错误的自动关联比不关联更糟。请先在真实仓库中使用 --dry-run 进行校准。

init — 初始化配置

npx ai-memory-cli init                             # detect editors, create config
npx ai-memory-cli init --with-mcp                  # also register ai-memory as MCP server
npx ai-memory-cli init --schedule                  # register a daily extract --incremental cron job
npx ai-memory-cli init --unschedule                # remove the scheduled task

使用 --with-mcp 时，ai-memory 会写入或合并 .cursor/mcp.json 和 .windsurf/mcp.json，让编辑器自动加载 MCP 服务。使用 --schedule 时，系统会通过操作系统原生调度器注册每日提取任务（macOS 上使用 launchd，Linux 上使用 crontab，Windows 上使用 Task Scheduler），让你的知识库无需手动运行也能保持最新。这两个标志均为幂等且安全。

export / import — 在不同机器间迁移记忆（新增）

Cursor / Claude Code 的对话保存在各台机器的本地状态中，因此换一台新笔记本就没有任何历史记录。export 和 import 会创建可移植的 JSON 捆绑包，可顺畅地导出再导入——目标机器上的文件、对话分组以及 context --source-id 行为都保持一致。

# On the old machine — export everything (or scope with --source-id / --convo / --type)
npx ai-memory-cli export --output backup.ai-memory.json
npx ai-memory-cli export --source-id b5677be8 --output resume-tool.json  # one chat only
npx ai-memory-cli export --convo "coupon" --output coupons.json          # match by title

# Copy / commit / share the bundle (it's a plain JSON file)

# On the new machine — preview first, then apply
npx ai-memory-cli import backup.ai-memory.json --dry-run
npx ai-memory-cli import backup.ai-memory.json               # default: skip duplicates
npx ai-memory-cli import teammate-bundle.json --author me    # remap teammate's memories
npx ai-memory-cli import stale.json --overwrite              # replace local copies

# Rebuild embeddings so semantic search/MCP work on the imported memories
npx ai-memory-cli reindex

捆绑包格式带有版本号（version: 1），且导入操作具有幂等性——重复导入同一捆绑包不会产生任何变化（根据作者 + 类型 + 日期 + 标题进行去重）。

---

MCP 服务（新增）

ai-memory 可作为 MCP 服务运行，让 AI 编辑器（Cursor、Claude Code）直接访问你的知识库——无需手动运行命令。

设置

添加到你的 Cursor MCP 配置（.cursor/mcp.json）：

{
  "mcpServers": {
    "ai-memory": {
      "command": "npx",
      "args": ["ai-memory-cli", "serve"]
    }
  }
}

或者用于 Claude Code（.claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "ai-memory": {
      "command": "npx",
      "args": ["ai-memory-cli", "serve"]
    }
  }
}

AI 能力

MCP 能力	功能
remember 工具	AI 在对话期间保存决策/约定/待办事项（自动建立索引）
recall 工具	AI 使用语义 + 关键词混合搜索来检索相关记忆
search_memories 工具	完整搜索，支持按类型/作者/已解决状态筛选，并感知语义
project-context 资源	开始对话时自动提供项目上下文

配置完成后，AI 可以自动记住重要决策，并在未来的会话中回忆这些决策——无需你运行任何命令。

语义搜索

ai-memory 使用结合语义相似度（通过嵌入实现）、关键词匹配和时间衰减的混合搜索。这意味着你可以按含义搜索，而不仅仅依赖完全匹配的关键词。

# Build search index (uses your existing LLM API for embeddings)
npx ai-memory-cli reindex

# Now search works semantically — "database choice" finds "PostgreSQL decision"
npx ai-memory-cli search "database choice"

MCP 的 recall 和 search_memories 工具会自动使用混合搜索。嵌入存储在本地的 .ai-memory/.embeddings.json 中，并会在使用 remember 工具时自动建立索引。

手动启动（用于测试）

npx ai-memory-cli serve           # start MCP server
npx ai-memory-cli serve --debug   # with debug logging

---

监视模式（新增）

当对话发生变化时自动提取知识——无需手动操作：

npx ai-memory-cli watch

监视模式会监控所有检测到的来源，查看是否有新的对话活动，并自动运行提取。它使用文件系统事件（用于 Cursor/Claude Code）和定期轮询（用于所有来源）来检测变化。

ai-memory watch — auto-extract on conversation changes

   Author: conor
   Output: .ai-memory/
   [+] Watching: Cursor
   [+] Watching: Claude Code

Initial scan complete — watching for changes...

10:15:32 [Cursor] "OAuth refactor discussion" (+8 turns) — extracting...
10:15:37 [+] 2 decision, 1 convention

按 Ctrl+C 停止。

---

仪表板（新增）

通过本地 Web 界面浏览、搜索和可视化你的知识库：

npx ai-memory-cli dashboard

打开 http://localhost:3141，其中包含：

• 概览 — 统计卡片、月度时间线图表、作者细分和近期活动
• 记忆浏览器 — 实时搜索，可按类型/作者/状态筛选，并提供详情弹窗
• 对话 — 每个产生过记忆的聊天窗口各有一张卡片，并提供一键复制 context --source-id，让你可以从“我在哪个聊天里做了这个决定？”直接跳转到“在新会话中继续那个聊天”
• 知识图谱 — 交互式 D3.js 力导向图（节点按类型着色，边表示共享对话或关键词）
• 质量 — 具体性直方图、模糊内容列表、重复/被包含的条目对（由 v2.2 算法栈提供支持）
• 导出 — 下载为 JSON、Obsidian 知识库（含 YAML 前置元数据），或复制到剪贴板

npx ai-memory-cli dashboard --port 8080   # custom port

使用新算法清理现有记忆

如果你从旧版本升级，并希望追溯应用 v2.2 质量算法，以移除之前积累的模糊/重复记忆：

npx ai-memory-cli reindex --dedup --dry-run   # preview what would be deleted
npx ai-memory-cli reindex --dedup             # actually delete + update index

对于包含 200 条以上记忆的存储，通常可清理掉 20–30% 的模糊/重复/被包含内容。

---

本地 LLM 支持（新增）

使用 Ollama 或 LM Studio 替代云 API——无需 API 密钥：

Ollama

# Install Ollama: https://ollama.ai
ollama pull llama3.2              # download a model
ollama pull nomic-embed-text      # (optional) for semantic search

export OLLAMA_HOST=http://localhost:11434
export OLLAMA_MODEL=llama3.2      # extraction model
npx ai-memory-cli extract

LM Studio

# Start LM Studio and load a model
export LM_STUDIO_BASE_URL=http://localhost:1234/v1
export LM_STUDIO_MODEL=your-model-name
npx ai-memory-cli extract

云端 API 密钥始终优先于本地 LLM。如果设置了 OPENAI_API_KEY 或 AI_REVIEW_API_KEY，则会使用这些密钥。

变量	描述
OLLAMA_HOST	Ollama 服务 URL（默认：http://localhost:11434）
OLLAMA_MODEL	用于提取的模型（默认：llama3.2）
OLLAMA_EMBEDDING_MODEL	用于语义搜索的模型（默认：nomic-embed-text）
LM_STUDIO_BASE_URL	LM Studio 服务 URL（默认：http://localhost:1234/v1）
LM_STUDIO_MODEL	模型名称

---

支持的数据源

数据源	数据位置	状态
Cursor	~/.cursor/projects/{name}/agent-transcripts/	稳定
Claude Code	~/.claude/projects/{path}/*.jsonl	稳定
Windsurf	~/AppData/Windsurf/User/workspaceStorage/*/state.vscdb	Beta
VS Code Copilot	~/AppData/Code/User/workspaceStorage/*/chatSessions/*.json	Beta
Codex CLI	~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl	Beta — v2.5+

---

典型工作流

首次提取

npx ai-memory-cli list                    # see what conversations are available
npx ai-memory-cli extract                 # extract everything (few minutes on first run)
npx ai-memory-cli rules                   # generate Cursor Rules
git add .ai-memory/ .cursor/rules/
git commit -m "chore: add ai-memory knowledge base"

日常使用（增量）

npx ai-memory-cli extract --incremental   # after a productive coding session
npx ai-memory-cli rules                   # refresh Cursor Rules
git add .ai-memory/ && git commit -m "chore: update memories"

开始新的对话

npx ai-memory-cli context --copy          # copy context to clipboard
# Paste into new Cursor/Claude Code session

输出如下所示：

## Project Context

### Key Decisions (follow without re-discussion)
- **Use OAuth Bridge pattern**: WebView cannot receive redirect directly...

### Conventions (always follow)
- **Never call getServerSideProps in this project**: ...

### Active TODOs
- [ ] Add retry logic to payment webhook handler

查找特定知识

npx ai-memory-cli search "payment"        # find all payment-related memories
npx ai-memory-cli search "auth" --type decision  # only decisions about auth

---

团队工作流

多人在同一个 git 仓库中使用 ai-memory 时，每个人的记忆都会自动存储在各自的子目录中。

工作原理

系统会自动检测作者身份（优先级：--author CLI 标志 > config.author > git config user.name > OS 用户名）。无需手动设置。

.ai-memory/
├── conor/
│   ├── decisions/
│   │   └── 2026-04-15-oauth-bridge.md
│   └── todos/
│       └── 2026-04-15-add-retry.md
├── alice/
│   ├── decisions/
│   │   └── 2026-04-16-payment-design.md
│   └── architecture/
│       └── 2026-04-16-module-split.md
└── .config.json

使用方法

# Everyone extracts normally — writes to their own directory
npx ai-memory-cli extract --incremental

# Generate your own context (default: only your memories)
npx ai-memory-cli context --copy

# Include the whole team's memories
npx ai-memory-cli summary --all-authors
npx ai-memory-cli context --all-authors --copy

# Override author name
npx ai-memory-cli extract --author "alice"

升级现有项目

v1.3 之前创建的记忆存储在扁平目录（.ai-memory/decisions/）中。升级后：

• 旧文件仍可正常读取（向后兼容），author 为空
• 新提取的内容会存入 .ai-memory/{author}/decisions/ 等目录
• 无需手动迁移

---

跨设备工作流

Work machine                                   Home machine
────────────                                   ────────────
Cursor / Claude Code dev work
        -> npx ai-memory-cli extract --incremental
        -> git add .ai-memory/
git commit && git push
                                               git pull
                                               -> npx ai-memory-cli context --topic "today's work"
                                               -> Paste context into new conversation
                                               -> Seamlessly resume

---

配置

ai-memory 无需任何配置即可使用。要自定义配置，请运行 npx ai-memory-cli init 或手动创建 .ai-memory/.config.json：

{
  "sources": {
    "cursor": { "enabled": true, "projectName": "my-project" },
    "claudeCode": { "enabled": true },
    "windsurf": { "enabled": true },
    "copilot": { "enabled": true }
  },
  "extract": {
    "types": ["decision", "architecture", "convention", "todo", "issue"],
    "ignoreConversations": [],    // conversation UUIDs to skip
    "minConversationLength": 5   // skip very short conversations
  },
  "output": {
    "dir": ".ai-memory",
    "summaryFile": "SUMMARY.md",
    "language": "zh"             // "zh" or "en" — output language for summaries
  },
  "model": "",                   // leave empty for auto-selection
  "author": ""                   // leave empty to auto-detect from git config user.name
}

环境变量

变量	描述
AI_REVIEW_API_KEY	API 密钥（优先使用，与 ai-review-pipeline 共享）
OPENAI_API_KEY	OpenAI API 密钥
OPENAI_BASE_URL	自定义的 OpenAI 兼容 API 基础 URL
OPENAI_MODEL	OpenAI 的模型覆盖值
ANTHROPIC_API_KEY	Anthropic API 密钥（需要兼容的代理）
ANTHROPIC_BASE_URL	Anthropic 代理基础 URL
AI_REVIEW_BASE_URL	自定义 API 基础 URL
AI_REVIEW_MODEL	要使用的模型（默认：gpt-4o-mini）
OLLAMA_HOST	Ollama 服务 URL（默认：http://localhost:11434）
OLLAMA_MODEL	用于提取的 Ollama 模型
OLLAMA_EMBEDDING_MODEL	用于语义搜索嵌入的 Ollama 模型
LM_STUDIO_BASE_URL	LM Studio API URL
LM_STUDIO_MODEL	LM Studio 模型名称

---

输出结构

每条记忆都是一个独立文件，按作者和类型分类：

.ai-memory/
├── SUMMARY.md                              # Project summary (from `summary` command)
├── conor/                                  # Per-author subdirectory
│   ├── decisions/
│   │   ├── 2026-04-12-oauth-bridge-pattern.md
│   │   └── 2026-04-13-async-job-queue-design.md
│   ├── architecture/
│   │   └── 2026-04-10-payment-module-design.md
│   ├── conventions/
│   │   └── 2026-04-08-coding-conventions.md
│   ├── todos/
│   │   └── 2026-04-12-add-retry-logic.md
│   └── issues/
│       └── 2026-04-11-sqlite-locking-fix.md
├── .index/                                 # Extraction index (auto-managed)
├── .config.json                            # Configuration (commit this)
└── .state.json                             # Extraction state (add to .gitignore)

将 .ai-memory/.state.json 添加到 .gitignore 中——它会记录已处理的对话，并且与机器有关。

---

CI 集成

# .github/workflows/memory.yml
- name: Extract AI memories
  run: npx ai-memory-cli extract --incremental --json
  env:
    AI_REVIEW_API_KEY: ${{ secrets.AI_REVIEW_API_KEY }}

---

要求

• Node.js >= 18
• 入门无需 API 密钥——未配置密钥时，会自动使用内置的免费模型（通过 SiliconFlow 提供的 DeepSeek-V4-Flash），每次运行最多处理 2 条对话。
• 如需无限量提取：设置 AI_REVIEW_API_KEY（或 OPENAI_API_KEY），使用任意 OpenAI 兼容服务商，或使用本地 LLM（Ollama / LM Studio）。

**提示：**Node.js 22+ 可读取 Cursor/Windsurf 的数据库，从而生成更丰富的对话标题。在 Node 18-20 上，标题取自第一条消息（仍可正常使用）。

社区

• Linux DO 讨论 — 中文开发者社区讨论帖

许可证

MIT — Conor Liu