memex：为 AI 编程 Agent 打造的长效记忆系统

你是否曾遇到过这样的场景：花了两小时和 AI 编程助手完成了一个复杂重构，下一次新会话时，它完全忘记了你们讨论过的所有设计决策、踩过的坑、以及为什么选择了方案A而非方案B——然后你又得从头解释一遍。这种"每次从零开始"的割裂感，正是 memex 试图解决的核心痛点。

背景：Luhmann 方法如何走进 AI 时代

memex 的设计灵感来自社会学家 Niklas Luhmann——这位德国学者用 90,000 张手写卡片写出了 70 本书。他的"卡片盒笔记法"（Zettelkasten）有三个核心原则：原子性（一张卡片只讲一个想法）、用自己的话写（强制理解，而非复制粘贴）、以及双向链接（"这条笔记和 [[那条笔记]] 相关，因为……"）。这些原则在过去二十年间深刻影响了个人知识管理工具的设计，从 Roam Research 到 Obsidian 都沿用了这套方法论。

memex 将这套经过数十年验证的方法，移植到了 AI 编程 Agent 的工作流中。它不依赖任何向量数据库、不需要 embedding 计算——所有记忆就是普通的 Markdown 文件，存在 ~/.memex/cards/ 目录里，任何时候你都可以直接打开查看或编辑。

图1：memex 时间线视图，展示了 Agent 生成的知识卡片时间轴。

核心机制：recall 与 retro

memex 的工作流围绕两个关键动作展开：recall（回顾）和 retro（反思）。

当你启动一个新编程会话时，memex 会自动触发 recall 流程——它读取 ~/.memex/cards/ 目录中的所有卡片，通过关键词匹配找到与当前任务相关的知识片段，在 Agent 开始工作前就把"上下文记忆"注入进来。Agent 不再是从空白状态开始，而是带着上一轮的经验和洞察进入工作。

当一个任务完成后，memex 的 retro 机制接管。Agent 被引导对本次工作进行反思，提取出值得沉淀的知识——可能是踩过的 bug、发现的最佳实践、或者某个架构决策背后的权衡——然后将它们写成带有 [[双向链接]] 的原子知识卡片，存入本地 Markdown 文件。

这个过程不需要任何向量检索或机器学习推理。memex 的本质是一个结构化的文件管理系统 + 一套让 Agent 遵守的反思工作流。双向链接通过正则匹配实现，而非图数据库——这种朴素的设计反而带来了极高的可靠性和可移植性。

广泛的平台支持

memex 最有价值的设计决策之一，是它选择了 MCP（Model Context Protocol） 作为跨平台整合的核心协议。MCP 是 Anthropic 主导推出的 Agent 上下文标准，而 memex 提供了完整的 MCP Server 实现，包含 10 个工具函数，覆盖搜索、读取、写入、归档等核心操作。

这意味着 memex 可以无缝接入几乎所有主流 AI 编程工具：

平台	集成方式	体验评分
Claude Code	原生 Plugin（hooks + skills）	⭐⭐⭐⭐⭐ 最佳——SessionStart 自动 recall、斜杠命令、深度 hook
VS Code / Copilot	VS Code 扩展（MCP Server 内置）	⭐⭐⭐⭐ 一键安装，零配置
Cursor	MCP Server	⭐⭐⭐⭐ 10 个 MCP 工具，Cursor 官方支持一键配置
Codex	MCP Server	⭐⭐⭐⭐ OpenAI 官方集成
Windsurf	MCP Server	⭐⭐⭐⭐ Codeium 官方支持
Pi	专属 Extension	⭐⭐⭐⭐ 8 个专属工具 + 自动 recall hook

所有平台共享同一个 ~/.memex/cards/ 目录。这意味着在 Claude Code 中沉淀的卡片，Cursor 立刻可见——记忆是真正的跨平台共享资产，而非某个工具的专属数据。

Git 同步：记忆的持久化与多设备同步

memex 还提供了 memex sync 命令，可以将本地的 cards 目录通过 Git 同步到 GitHub 私有仓库。这解决了两个问题：其一，记忆的备份与版本控制；其二，多设备间的记忆同步。

初始化同步只需一条命令：memex sync --init，memex 会自动通过 GitHub CLI 创建私有仓库并完成初始提交。GitLab 用户则可以手动指定仓库 URL。同步可以设置为每次写入后自动触发（memex sync on），也可以手动控制频率。

更值得一提的是同步后带来的协作可能性：如果你将仓库设为私有，memex cards 可以作为团队共享的知识库——每个成员在不同项目中积累的洞察，最终汇聚成一份持续增长的集体记忆。

视觉探索：Graph View 与 Timeline

memex 自带一个本地 Web UI，通过 memex serve 启动，在 localhost:3939 上提供可视化界面。Timeline 视图按时间顺序展示所有知识卡片，Graph View 则将卡片之间的双向链接关系渲染成一张网络图。

如果你配置了 git 同步，memex serve 会自动重定向到 memra.vercel.app（一个第三方托管的 Web UI），提供更丰富的交互体验。在离线环境或不愿使用第三方服务时，可通过 --local 参数强制使用本地 UI。

图2：Graph View 可视化展示卡片间的双向链接网络，帮助发现知识盲区和潜在的连接机会。

代码架构：TypeScript + MCP SDK

memex 采用了 TypeScript 作为主力开发语言，这并非随意选择。TypeScript 的类型系统为代码质量提供了保障，同时它能直接编译为 Node.js 可执行的 CommonJS 模块，天然适合 CLI 和 MCP Server 这类工具类项目。

从 package.json 可以看出核心依赖：

• @modelcontextprotocol/sdk：Anthropic 官方的 MCP 协议 SDK，处理所有 MCP 通信细节
• commander：成熟的 Node.js CLI 参数解析库
• gray-matter：解析 Markdown 文件头部元数据的标准工具
• zod：运行时类型验证，确保数据结构的可靠性

构建系统使用 esbuild，以单文件 bundle 形式输出到 dist/ 目录，最终通过 npm 全局安装的 CLI 入口 memex 分发。测试框架选用 vitest（Vite 原生的测试运行器），与项目整体现代化的工具链一致。

源代码组织清晰：src/cli.ts 作为入口文件，src/commands/ 包含各个子命令（search/read/write/archive/sync 等），src/mcp/ 实现了 MCP Server 的工具函数，src/lib/ 放置核心业务逻辑，src/importers/ 支持从其他工具（Roam、Obsidian）导入卡片。

隐私设计：主动防御

memex 在隐私保护上做了主动设计。它会检测并拒绝高置信度的原始密钥内容，要求用户使用抽象描述代替真实凭证。即使有人在卡片中不慎写入了包含 token 的 URL，memex 也会在保存前进行去敏感化处理。

不过 memex 明确指出，它无法隐藏 AI 客户端已经在对话 transcript 中展示过的工具调用参数——这意味着如果你的 Copilot 已经显示了某个 API key，那部分信息就已经泄露了。因此最佳实践是：在向 memex 提问或写卡片前，先完成敏感信息的去标识化。

实验性功能：Agentic Memory

在 ~/.memex/.memexrc 中启用 experimental.agenticMemory: true 后，memex 会激活一套更结构化的 Agent 记忆工作流：观察 → 起草原子卡片 → 丰富元数据 → 检索候选 → 决策（创建/更新/跳过）→ 预览 → 写入 → 验证。这套流程借鉴了 A-MEM 思想，生成的卡片质量更高——尤其是双向链接，是通过检索后的 Agent 主动提议，而非简单的关键词匹配。

该功能默认关闭，不影响现有行为，用户可以放心尝鲜。

局限与争议

尽管设计精巧，memex 也存在明显的局限性：

检索能力的上限：memex 完全依赖关键词匹配（grep 风格的搜索），没有任何语义检索能力。当你的记忆库积累到数百张卡片时，通过关键词找到相关卡片变得越来越困难。相比之下，依赖 embedding 的方案（如 Continue.dev 的记忆功能）在语义相关性上更有优势。这是 memex 作者在"简洁性"与"能力上限"之间有意的取舍。

上下文窗口的隐性成本：recall 机制本质上是将相关卡片内容注入 Agent 的上下文窗口。如果卡片数量多、篇幅长，会显著消耗宝贵的上下文额度，影响对话质量。memex 本身没有做摘要或优先级排序——这部分取决于用户的使用纪律和 Agent 的自我约束能力。

VS Code 扩展与 Claude Code Plugin 的选择困惑：文档中特别强调了"不要在 VS Code 里同时用两个集成"——如果你在 VS Code 中使用 Claude Code，应该装 Claude Code Plugin 而非 VS Code 扩展。但很多用户可能不清楚自己用的是哪个，这个边界在实践中容易混淆。

跨平台同步的一致性问题：虽然所有平台读写同一个 cards 目录，但如果两个客户端同时写入（比如同时开着 Claude Code 和 Cursor），文件系统层面的并发写入可能产生冲突。memex 没有内置冲突解决机制，依赖 Git 来兜底。

行业意义：工具记忆的范式转变

memex 出现的大背景，是 AI 编程工具正从"单次对话执行者"向"持续工作伙伴"进化。Claude Code、Cursor、Windsurf 这些工具的核心卖点，已经从"帮你写代码"延伸到"理解你的项目、记住你的偏好、积累你的经验"。

在这一趋势下，Agent 记忆系统的重要性日益凸显。memex 的方案——用文件系统和 Git 替代向量数据库、用双向链接替代 embedding 相似度——代表了"轻量化优先"的设计哲学。对于追求简单、透明、可控的开发者来说，这是一个值得认真考虑的选择。

它可能不是功能最强大的 Agent 记忆方案，但它的极简主义哲学——Markdown 就是数据库、Git 就是备份、grep 就是检索——让它成为最容易部署、最不容易出错的方案。而在这个 AI 工具快速迭代的时代，"不出错"本身就是一种竞争优势。

快速上手

安装（Node.js >= 18）：

npm install -g @touchskyer/memex

Claude Code 用户：

/plugin marketplace add iamtouchskyer/memex
/plugin install memex@memex

VS Code / Copilot 用户： 在 VS Code 扩展商店搜索 "memex"，一键安装，无需任何额外配置。

Cursor / Codex / Windsurf 用户： 安装后添加 MCP server：命令填 memex，参数填 ["mcp"]。

启动可视化界面： memex serve

初始化 Git 同步： memex sync --init