1. 项目概述为AI编程助手构建持久记忆系统如果你和我一样每天都在和各种AI编程助手比如Claude Code、Cursor、GitHub Copilot打交道那你肯定遇到过这个烦人的问题每次开启一个新的会话它都像一张白纸完全不记得我们之前讨论过的项目细节、代码规范或者踩过的坑。你不得不一遍又一遍地重复解释项目结构、业务逻辑甚至同一个函数的最佳实践。这种“金鱼记忆”极大地限制了AI助手作为长期协作伙伴的潜力。Memex这个项目就是为了彻底解决这个问题而生的。它本质上是一个为AI编程助手设计的持久化记忆系统。你可以把它想象成给AI助手配备了一个永不丢失的“第二大脑”。每次你和助手完成一项任务比如重构了一个复杂的模块或者解决了一个棘手的BugMemex会引导助手将这次任务的核心洞察、学到的知识以一种结构化的方式保存下来形成一张张“知识卡片”。下次当你或者助手自己在相关上下文中工作时它能自动“回忆”起这些卡片基于已有的知识继续构建而不是每次都从零开始。最让我欣赏的是它的设计哲学极简与开放。它没有引入复杂的向量数据库也不需要做Embedding计算所有记忆都以纯Markdown文件的形式存储在本地一个简单的文件夹里~/.memex/cards/。这意味着你的记忆资产是完全透明、可读、可编辑的你可以用任何文本编辑器打开也可以用Git进行版本管理和多设备同步。这种“不锁死”的设计对于开发者来说意味着完全的掌控权和安全感。2. 核心设计理念为什么是Zettelkasten与原子化卡片Memex的灵感来源于德国社会学家尼克拉斯·卢曼Niklas Luhmann创造的“卡片盒笔记法”Zettelkasten。卢曼用这套方法一生积累了约9万张卡片并以此为基础出版了70多本著作其生产力令人惊叹。Memex将这套历经考验的知识管理方法论巧妙地应用到了AI协作的领域。理解其背后的四个核心原则你就能明白Memex为何有效。2.1 原子化Atomicity一卡一事聚焦核心这是Zettelkasten的第一要义也是Memex卡片设计的基石。所谓“原子化”就是一张卡片只记录一个核心概念、一个解决方案或一个关键洞察。比如不是笼统地记“关于用户认证模块的笔记”而是拆分成“使用JWT进行无状态认证的密钥轮换策略”“OAuth 2.0授权码模式下防止CSRF攻击的最佳实践”“在Next.js API路由中集成Clerk鉴权的代码片段”这样做的好处是显而易见的。对于AI助手而言原子化的知识颗粒度更细更容易被精确地检索和调用。当你在处理“密钥轮换”相关问题时AI能直接定位到那张具体的卡片而不是在一篇冗长的综合笔记里大海捞针。对于开发者来说这也迫使我们在保存知识时进行深度思考提炼出真正有价值的“知识单元”而不是简单地堆砌信息。2.2 双向链接Bidirectional Links构建知识网络单纯的原子化卡片是孤岛。Memex通过[[双向链接]]语法类似于Roam Research或Obsidian将卡片连接起来形成一张动态的知识网络。例如在“JWT密钥轮换”卡片的末尾你可能会写上“此策略是为了解决[[2024-03-15-发现JWT密钥泄露风险]]中提到的安全问题并与[[系统架构-微服务间认证]]方案协同工作。”这种链接不是简单的标签Tag而是在上下文中阐述关系。当AI或你通过图形视图浏览“JWT密钥轮换”卡片时它能清晰地看到这张卡片为何存在它与哪些问题、哪些方案相关联。这种关联性记忆模拟了人类大脑的联想思维使得知识不再是线性的列表而是一个有机的、可探索的网络。AI在回忆时不仅能找到直接相关的卡片还能通过链接发现相关的上下文和背景信息给出更全面的建议。2.3 用自己的话复述Own Words费曼学习法的实践Memex鼓励或者说通过其工作流设计引导AI助手在保存卡片时用“自己的话”重新组织学到的知识。这本质上是费曼学习法的体现要真正理解一个东西你必须能把它清晰地解释出来。当AI助手尝试将一段复杂的代码逻辑或解决方案总结成一张卡片时这个过程本身就是一个深度处理和内化的过程。它不能只是复制粘贴代码片段而需要理解其原理、目的和边界条件。例如它可能会将一段配置Webpack的复杂代码总结为“本项目使用splitChunks插件将node_modules打包为独立vendor块目的是利用浏览器缓存提升非首屏路由的加载速度。注意需与runtimeChunk: single配合使用以避免哈希不一致问题。”这种经过消化再输出的知识其可用性和可理解性远高于原始的、未经处理的代码块。它存储的是“理解”而不仅仅是“信息”。2.4 无锁的纯文本Plain Text保障主权与灵活性这是Memex区别于许多“黑盒”AI工具的关键。所有卡片都以Markdown格式明文存储在~/.memex/cards/目录下。这意味着工具无关你可以用VS Code、Vim、Obsidian甚至cat命令来查看和编辑你的记忆。未来无忧即使Memex项目停止维护你的所有知识资产都完好无损地躺在那里格式是通用的Markdown。无缝集成你可以用grep、find命令行搜索可以用Git进行版本控制和同步可以写脚本进行批量处理。跨平台共享因为所有客户端Claude Code, Cursor, VS Code等都读写同一个目录在一个平台上创建的记忆在其他平台上立即可用。这种设计将选择权和控制权完全交给了用户避免了被单一工具或封闭格式绑架的风险。3. 平台集成深度解析MCP协议如何打通AI工具链Memex能覆盖如此多的主流AI编程工具Claude Code, Cursor, VS Code Copilot等其核心技术倚仗是Model Context Protocol。MCP是Anthropic提出的一种开放协议旨在标准化AI应用与外部数据源、工具之间的通信方式。你可以把MCP Server想象成一个“翻译官”或“适配器”它让不同的AI客户端都能以统一的方式调用Memex的功能。3.1 MCP Server通用的记忆接入层对于大多数平台VS Code/Copilot, Cursor, Codex, WindsurfMemex通过启动一个MCP Server来集成。安装全局CLI工具npm install -g touchskyer/memex后memex mcp命令就会启动这个服务。它向AI客户端暴露了约10个标准化的工具Tools例如memex_recall根据当前对话或代码上下文搜索并召回相关的知识卡片。memex_retro在对话或任务结束时总结并保存本次会话的收获为新卡片。memex_search按关键词搜索卡片。memex_write直接创建或编辑一张卡片。这些工具的描述Description经过精心设计会“告诉”AI助手应该在什么场景下使用它们。比如memex_recall的描述可能会是“在用户开始描述一个新任务或打开一个新文件时自动搜索与此上下文相关的记忆卡片为用户提供背景信息。” 这样AI助手在会话开始时就会智能地主动去回忆相关记忆。实操心得理解“零配置”的含义这里的“零配置”指的是Memex本身。你仍需在各自的编辑器里完成一次性的MCP Server配置。例如在Cursor中你需要通过其MCP设置界面添加一个Server命令填memex参数填[“mcp”]。这个过程通常只需一次之后就会自动连接。Memex的“零配置”优势在于它不需要你在服务器端搭建数据库或处理复杂的API密钥本地安装即用。3.2 Claude Code Plugin深度集成的典范Claude CodeClaude桌面应用的集成度是最高的因为它支持更丰富的插件机制Hooks Skills。除了MCP工具外它还提供了SessionStart Hook每次启动新会话时自动触发memex_recall将相关记忆直接注入到对话开场白中实现真正的“无缝记忆”。Slash Commands你可以直接输入/memex recall或/memex retro来手动触发功能交互更快捷。更优的上下文管理Plugin能更深度地整合到Claude的上下文窗口管理记忆的输入和输出。这解释了为什么在支持平台表格中Claude Code的体验被标记为“Best”。它不仅仅是提供了工具而是将记忆功能深度编织到了AI协作的工作流核心。3.3 VS Code / Copilot扩展开箱即用的便利对于VS Code和GitHub Copilot用户最方便的安装方式是通过VS Code扩展市场。搜索安装“memex-mcp”扩展后一切都准备好了。这个扩展实际上内置了Memex的CLI和MCP Server你连npm install的步骤都省了真正做到了点击即用。这对于不想折腾命令行、追求极致便捷的用户来说是最佳选择。3.4 平台选择建议根据你的主要工作流我的建议是主力使用Claude Code毫无疑问选择其Plugin版本享受最自动、最深入的集成体验。主力使用VS Code/Copilot或Cursor如果你主要在这两个编辑器内工作使用对应的集成方式VS Code扩展或Cursor MCP。它们的体验非常接近都能在编码时提供强大的上下文记忆。多编辑器混用者安装全局CLInpm install -g touchskyer/memex然后在各个编辑器中配置MCP Server。由于所有平台都读写~/.memex/cards/你的记忆库是统一且实时同步的在任何地方都能接上之前的思路。4. 完整工作流实操从安装到构建个人知识库理论说得再多不如动手实践。下面我将以macOS/Linux系统、VS Code和Claude Code为主要环境带你走通一个完整的Memex使用流程。4.1 环境准备与安装首先确保你有一个可用的Node.js环境18及以上版本。这是运行Memex CLI的基础。# 检查Node.js版本 node --version # 全局安装Memex命令行工具 npm install -g touchskyer/memex安装完成后CLI工具memex就可以在终端中使用了。你可以通过memex --help查看所有可用命令。接下来根据你的编辑器进行配置对于VS Code / GitHub Copilot打开VS Code进入扩展市场CtrlShiftX。搜索“memex-mcp”找到由“touchskyer”发布的扩展。点击“安装”。安装完成后通常无需任何配置扩展会自动启动Memex的MCP Server。对于Claude Code打开Claude Code应用。在对话输入框中输入命令/plugin marketplace add iamtouchskyer/memex。这会将Memex添加到你的插件市场。添加成功后再输入/plugin install memexmemex。等待安装完成。安装后你可能需要在新会话中启用它。Claude Code的插件管理通常比较直观。对于Cursor确保已全局安装touchskyer/memex如上所述。打开Cursor进入设置Settings。找到“MCP Servers”或“AI模型配置”相关部分不同版本位置可能略有不同。添加一个新的MCP Server配置如下Name:memex(可自定义)Command:memexArgs:[mcp]保存并重启Cursor。4.2 初体验你的第一次“记忆”与“回忆”安装配置好后我们来进行一次最简单的测试感受Memex如何工作。步骤一在Claude Code中创建记忆打开Claude Code开启一个新会话。由于安装了Plugin你可能会在Claude的开场白中看到它提到了Memex已就绪。你可以直接和Claude开始工作。例如让它帮你写一个Python函数用于安全地解析JSON并处理特定错误。任务完成后手动触发保存记忆。输入斜杠命令/memex retro。Claude会开始与你交互询问这次会话的要点。你可以引导它比如“总结一下我们刚才写的安全解析JSON函数重点记录json.decoder.JSONDecodeError异常的处理以及使用try-except结构的最佳实践。”Claude会生成一张卡片的草稿并询问你卡片的唯一标识Slug例如python-json-safe-parse。确认后这张卡片就被保存到了~/.memex/cards/python-json-safe-parse.md。步骤二在VS Code中验证回忆打开VS Code并打开一个Python项目或文件。调用GitHub Copilot例如输入注释# 这里需要解析用户输入的JSON。观察Copilot的补全或聊天建议。由于Memex MCP Server在运行Copilot获得了调用memex_recall工具的能力。在它生成代码建议时可能会自动关联到你刚才保存的python-json-safe-parse卡片从而直接给出一个包含完善错误处理的try-except代码块。你也可以直接打开终端使用CLI查看这张卡片memex read python-json-safe-parse。这个过程直观地展示了跨会话、跨平台记忆的核心价值在一个地方学到的知识在另一个地方被自动应用。4.3 卡片写作规范与高级技巧要让记忆系统高效运转卡片的写作质量至关重要。遵循一些规范能让AI和你自己在未来更好地利用它们。1. 优秀的卡片标题SlugSlug是卡片的唯一标识和文件名。好的Slug应该具有描述性react-context-performance-optimization比react-notes-1好得多。使用连字符这是URL和文件名友好格式。包含关键概念让搜索变得更简单。2. 卡片正文结构一张好的卡片通常包含# 卡片标题与Slug对应或更友好 **核心摘要**用一两句话说明这张卡片解决了什么问题或记录了何种知识。 ## 内容 这里是知识的主体。可以是代码片段、配置示例、问题分析步骤等。 - 对于代码给出**完整、可运行**的示例。 - 解释**为什么**这么做而不仅仅是“怎么做”。 - 注明适用的**前提条件**或**边界情况**。 ## 关联与上下文 - **参考**链接到相关的官方文档 [链接文字](URL)。 - **链接**使用 [[another-card-slug]] 链接到其他相关记忆卡片。 - **起因**记录是解决哪个具体问题催生了这张卡片例如源于[[2024-04-01-生产环境JSON解析失败]]。 ## 关键词 #python #json #error-handling #best-practice 标签有助于快速分类但双向链接更能体现深度关系3. 主动建立链接不要事后才想起来链接。在写作卡片时就养成思考的习惯“这个概念和我知道的哪个知识点有关” 立刻用[[ ]]把它链接起来。这种即时的关联是构建知识网络的关键。4. 定期回顾与整理使用memex serve启动本地Web界面localhost:3939在“图形视图”中浏览你的知识网络。你会发现哪些卡片是孤立的“死胡同”哪些是连接丰富的“枢纽”。你可以有意识地创建一些“索引卡片”Index Card例如一张名为索引- Python错误处理的卡片里面不写具体内容只罗列链接到所有相关错误处理卡片如[[python-json-safe-parse]],[[python-requests-timeout-handling]]等。这为你和AI提供了一个强大的入口点。4.4 跨设备同步用Git管理你的“第二大脑”记忆库只存在一台电脑上是不够的。Memex利用Git实现了优雅的同步方案。# 1. 初始化同步首次设置 # 确保已安装GitHub CLI (gh) 并登录 (gh auth login) memex sync --init # 这条命令会自动在GitHub上为你创建一个名为memex-cards的私有仓库并将本地卡片目录关联上去。 # 或者使用已有的Git仓库 memex sync --init https://github.com/yourname/your-memex-repo.git # 2. 开启自动同步推荐 memex sync on # 此后每次卡片创建或修改Memex都会自动执行git add, commit, push。 # 3. 在其他设备上恢复 # 在新电脑上安装好Memex后克隆你的仓库到~/.memex/cards/目录即可。 # 或者使用CLI假设自动同步已设置 memex sync # 这会执行pull操作获取最新记忆。 # 4. 手动同步或关闭 memex sync # 手动触发同步拉取推送 memex sync off # 关闭自动同步重要注意事项隐私与安全自动创建的仓库是私有的这很好。但你需要意识到你的所有记忆卡片都将存储在这个Git仓库中。切勿将密码、API密钥、敏感令牌等机密信息写入卡片。Memex是知识管理系统不是密码管理器。如果卡片中不可避免地涉及服务器地址、数据库名等非机密但敏感的信息确保你的私有仓库访问权限是严格控制的。5. 核心CLI工具与MCP工具详解Memex的强大一半在于其设计理念另一半在于这套精心设计的工具集。它们为你从命令行或AI内部管理记忆提供了全方位的接口。5.1 命令行界面CLI工具安装全局包后你可以在终端使用memex命令。以下是核心子命令的深度用法memex search [query]- 智能搜索这是最常用的命令之一。不加参数时它会列出所有卡片的标题和摘要。# 列出所有卡片 memex search # 关键词搜索支持模糊匹配 memex search python json # 这会搜索卡片标题、正文、标签中包含“python”或“json”的卡片。 # 搜索并显示更多细节 memex search --detail api design搜索结果是按相关性排序的Memex会优先匹配标题和标签中的关键词。memex write slug- 快速捕获灵感有时你不想通过AI而是想自己快速记下一点东西。# 交互式写入命令会打开你的默认编辑器如Vim/VSCode memex write my-new-idea # 通过管道直接写入内容 echo 这是一个通过CLI快速测试创建的卡片。\n\n关联[[some-existing-card]] | memex write cli-testmemex read slug- 查阅卡片# 读取特定卡片内容到终端 memex read python-json-safe-parse # 以原始Markdown格式输出便于用其他工具处理 memex read --raw some-card card_content.mdmemex links [slug]- 分析知识图谱这个命令能让你洞察卡片间的联系强度。# 查看所有卡片的链接统计 memex links # 输出示例 # Total cards: 142 # Total links: 387 # Avg links per card: 2.73 # Top hubs: # system-architecture (links: 24) # python-error-handling (links: 18) # Orphaned cards: 12 (考虑为它们建立链接) # 查看特定卡片的链接详情 memex links python-json-safe-parse # 会显示哪些卡片链接了它以及它链接了哪些卡片。memex archive slug- 归档旧卡片知识会过时。对于不再相关但想留作记录的卡片不要删除而是归档。memex archive outdated-legacy-api-notes归档操作会将卡片移动到~/.memex/cards/_archived/目录下它不会出现在常规搜索中但依然被版本控制系统管理必要时可以找回。memex serve- 可视化浏览启动本地Web服务器默认端口3939在浏览器中打开一个时间线视图和图形视图。这是回顾和整理知识网络的最佳方式。图形视图能让你直观地看到卡片集群和关键枢纽对发现知识盲点和建立新连接非常有帮助。5.2 MCP工具AI助手的“记忆”API这些工具通过MCP协议暴露给AI客户端是AI主动与记忆交互的渠道。理解它们能帮助你更好地预测和引导AI的行为。工具名触发场景与用途AI客户端典型使用方式memex_recall会话开始时或用户提到一个新概念/文件时。AI自动调用此工具搜索与当前对话上下文如打开的文件路径、语言、提到的技术名词相关的卡片并将内容作为背景信息注入。“用户打开了api/auth.js文件。让我调用memex_recall搜索与‘auth’、‘JWT’、‘Node.js’相关的卡片。”memex_retro会话结束时或用户明确要求总结时。AI总结本次对话的收获生成一张新卡片的草稿与用户确认标题和内容后保存。“我们刚刚完成了OAuth2.0的配置。调用memex_retro生成一张关于‘Express.js中Google OAuth2.0集成步骤与坑点’的卡片。”memex_search用户明确询问已知信息时。例如用户问“我们之前是怎么处理X问题的” AI调用此工具进行精准搜索。用户“我记得我们优化过数据库查询具体方案是什么” AI“我来调用memex_search关键词是‘数据库查询优化’。”memex_write用户要求直接记录某事时。AI将用户提供的内容直接格式化为卡片并保存。用户“把‘项目部署服务器的SSH连接信息’记下来。” AI“调用memex_writeslug设为deploy-server-ssh-info。”memex_read用户要求查看特定卡片时。AI获取卡片完整内容并展示给用户。用户“给我看看‘python-json-safe-parse’那张卡。” AI“调用memex_read。”实操心得如何训练你的AI助手更好地使用Memex起初AI可能不会总是完美地自动触发recall或retro。你可以通过显式提示来引导它。例如在Claude Code中开始一个新任务时你可以先说“在开始之前先回忆一下我们之前关于这个模块的所有讨论。” 这相当于手动激活了memex_recall。任务完成后你可以说“好了我们来总结一下这次学到的东西保存到Memex里。” 多次这样的引导后AI会逐渐学习你的工作模式变得更自动。6. 常见问题与故障排查实录在实际使用中你可能会遇到一些典型问题。以下是我和社区用户遇到的一些情况及解决方法。6.1 安装与连接问题问题在Cursor/VSCode中配置了MCP Server但AI助手似乎无法调用Memex工具。检查Server是否运行在终端运行memex mcp看是否能正常启动并保持运行不退出。如果立即退出可能是Node.js版本或全局安装有问题。尝试重新安装npm uninstall -g touchskyer/memex npm install -g touchskyer/memex。检查编辑器配置确保MCP Server的命令Command和参数Args完全正确。命令应为memex假设其在系统PATH中参数应为[mcp]包括方括号。在Cursor中有时需要重启整个编辑器才能使MCP配置生效。查看编辑器日志VS Code/Copilot和Cursor通常有输出面板Output Panel或日志文件里面会有MCP连接的错误信息。搜索“MCP”或“memex”关键词。问题memex命令在终端中找不到。确认全局安装运行npm list -g touchskyer/memex查看是否安装成功。检查PATHNode.js的全局包安装路径如/usr/local/bin或%APPDATA%\npm是否已添加到系统的PATH环境变量中。你可以通过which memex(macOS/Linux) 或where memex(Windows) 来检查。6.2 卡片管理与同步问题问题卡片太多搜索变得不够精准。优化卡片标题和标签确保Slug包含核心关键词。在卡片正文中使用## 关键词部分并添加相关标签如#docker,#auth。使用索引卡片创建一些高层次的“目录”或“索引”卡片例如索引-后端架构决策里面只包含指向各个具体决策卡片的链接。让AI先回忆这些索引卡片。利用双向链接通过memex links找出那些链接稀少的“孤儿卡片”思考它们是否能与现有知识网络建立联系。强关联的网络比一堆关键词更能提升回忆精度。问题自动同步memex sync on失败报Git错误。首次运行需初始化确保你已经运行过memex sync --init成功初始化了Git仓库。检查Git配置Memex使用系统Git。确保你的Git用户信息user.name,user.email已配置并且你有权限推送到关联的远程仓库如果是私有仓库需配置好SSH密钥或Personal Access Token。手动排查可以进入~/.memex/cards/目录手动执行git status,git pull,git push等命令查看具体的错误信息。6.3 与AI协作的效能问题问题AI在retro回顾时生成的卡片内容质量不高过于笼统。提供更具体的指引不要只说“总结一下”。在触发retro时给出明确的指令“请将我们刚才讨论的‘使用Redis缓存用户会话以减少数据库查询’的方案总结成卡片重点包括1) Redis连接配置要点2) 缓存失效策略TTL设置3) 雪崩预防的伪代码示例。”事后编辑卡片保存后你可以直接用文本编辑器打开对应的Markdown文件进行润色和补充。记忆库是为你服务的AI生成的初稿只是一个起点。示范优质卡片你可以手动创建几张结构清晰、内容深入的卡片作为范例。AI在学习和生成新卡片时会参考现有卡片的风格和质量。问题AI在会话开始时recall回忆的内容不相关干扰了对话。检查卡片相关性去~/.memex/cards/目录下查看AI召回的那些卡片。是不是它们的标题或内容包含了过于宽泛的词汇考虑修改这些卡片使其更具体。调整会话上下文AI的recall基于当前对话的初始信息如文件路径、语言。如果你在一个全新的项目中开始会话而Memex里充满了另一个项目的卡片可能会产生干扰。可以考虑使用memex archive暂时归档旧项目的大量卡片或者为不同项目建立不同的记忆库通过修改MEMEX_HOME环境变量指向不同目录但这属于高级用法需要手动管理。6.4 性能与存储问题卡片数量增长后memex serve图形视图加载变慢或卡顿。这是本地Web应用的正常现象当卡片超过上千张且链接非常复杂时图形渲染会有压力。替代方案更多时候使用memex search和memex links进行命令行查询。图形视图主要用于偶尔的高层梳理和探索。归档旧卡片定期使用memex archive清理不再活跃使用的卡片保持核心工作集的轻量。Memex不是一个“设置完就忘”的魔法工具。它更像一个需要你稍加照料和互动的伙伴。初期投入一点时间规范卡片写作、建立有效链接后期它回报给你的是一个随着时间推移越来越聪明、越来越懂你的AI协作环境。它解决的不仅是“忘记”的问题更是如何将碎片化的编程知识沉淀为可复用、可演进、真正属于你的数字资产的问题。