1. 项目概述：为AI编程助手装上“持久记忆”

如果你和我一样，日常重度依赖Claude Code、Cursor这类AI编程助手来写代码，那你一定也经历过这种“似曾相识”的挫败感：昨天刚花十分钟跟它掰扯清楚“这个项目里我们统一用ESM的 import/export ，别用CommonJS的 require 了”，它当时改得好好的。结果今天新开一个会话，你让它写个新模块，它啪一下又给你整出一堆 require() 。或者，上周你刚在代码审查里发现并纠正了一个因为没做空值检查导致的隐蔽bug，这周在另一个功能模块里，同样的错误又原封不动地出现了。这种感觉，就像在教一个永远记不住事的“金鱼”学生，每次都得从头教起，效率大打折扣。

这正是 kōdo （发音同“代码”的日语“コード”）要解决的核心痛点。它不是什么新的AI模型，而是一个 AI编程助手的“持久记忆层” 。你可以把它理解为你所有AI编程助手的共享“外置大脑”或“项目知识库”。所有那些你反复强调的编码规范、踩过的坑、重要的架构决策、个人编码偏好，甚至是项目中反复出现的优秀模式，都可以被 kōdo 结构化地存储起来。之后，无论你切换回Claude Code、打开Cursor、还是试用新的Kiro， kōdo 都能确保这些宝贵的“记忆”被自动注入到每个助手的上下文中，让它们真正“记住”你的项目，实现跨会话、跨工具的“记忆继承”。

这个工具特别适合独立开发者、小团队技术负责人，或者任何希望将AI助手从“一次性对话工具”升级为“拥有项目长期记忆的智能伙伴”的人。它的设计哲学是“本地优先、零配置、多代理兼容”，所有数据都存在你本地的一个SQLite数据库里，不依赖任何云服务，确保了隐私和速度。

2. 核心设计思路：为什么我们需要结构化的记忆？

在深入安装和使用之前，我想先聊聊 kōdo 背后的设计思路，这能帮你更好地理解它解决的不是一个“有没有”的问题，而是一个“好不好用”的问题。市面上并非没有类似的“记忆”工具，比如Claude Code自带的 claude-mem ，或者一些通用的记忆MCP服务器。但 kōdo 的独特价值在于它的 结构化 和 多代理原生支持 。

2.1 从“记事本”到“分类知识库”

很多记忆工具就像一个单一的记事本，你把所有东西都往里扔。当AI需要回忆时，它面对的是一个杂乱无章的长文本，检索效率低，且容易引入无关噪音。 kōdo 引入了**记忆类型（Memory Types）**的概念，这就像给你的知识库建立了清晰的文件夹结构：

• 惯例（Convention） ：存储项目或团队的硬性规定。例如：“所有API响应必须包裹在 { data, code, message } 的标准结构里”、“React组件必须使用函数式组件和Hooks”。
• 错误（Mistake） ：记录那些导致过线上故障或调试了半天的典型错误。例如：“在Node.js库代码中，绝对不要使用 process.exit() ，应该抛出错误”、“使用 Array.map 时，回调函数里记得 return ”。
• 决策（Decision） ：保存重要的技术选型和架构决策背后的原因。例如：“本项目选择SQLite而非PostgreSQL，是因为它是一个本地优先、零外部依赖的桌面应用”、“选择Vite而非Webpack，是出于更快的冷启动速度和更简单的配置”。
• 偏好（Preference） ：记录个人或团队的编码风格偏好。例如：“优先使用早期返回（early return）来减少嵌套的 if-else ”、“字符串拼接使用模板字符串而非加号”。
• 模式（Pattern） ：提炼可复用的代码模式或解决方案。例如：“所有用户认证相关的中间件都遵循 验证Token -> 查询用户 -> 挂载到req.user -> next() 的流程”。
• 笔记（Note） ：存放一般的项目上下文信息。例如：“ payment-service 模块正在Q2重构，改动时需同步通知后端团队”。

这种结构化带来了几个巨大优势：第一， 精准检索 。你可以让AI只搜索“与错误处理相关的惯例”，避免其他类型的记忆干扰。第二， 语义清晰 。AI能更准确地理解这条记忆的意图和适用场景。第三， 便于管理 。你可以批量查看或导出某一类记忆，比如把所有“错误”类记忆整理成团队的“避坑指南”。

2.2 从“单点适配”到“通用接口”

另一个关键设计是 多代理兼容性 。 kōdo 没有把自己绑定在任何一个特定的AI编程工具上。它同时提供了两种方式来为助手提供记忆：

1. MCP服务器（实时、双向） ：通过Model Context Protocol（MCP）标准， kōdo 可以作为一个服务器运行。AI助手在会话中能实时地调用 kodo_remember 来存储新学到的知识，也能通过 kodo_recall 主动查询相关记忆。这是最动态、最强大的集成方式。
2. 配置文件导出（静态、广泛兼容） ：通过 kodo export 命令， kōdo 能将所有记忆转换成各个AI助手原生的配置文件格式（如Claude Code的 .claude/settings/memory.md ，Cursor的 .cursor/rules/kodo-memory.md ）。这样，即使某个助手暂时不支持MCP，或者你在一个没有运行MCP服务器的环境里，记忆依然能通过配置文件生效。这实现了最大程度的工具覆盖。

这种设计意味着，无论未来出现什么新的、好用的AI编程工具，只要它支持MCP或可以读取某种格式的配置文件， kōdo 就能大概率与之兼容，保护了你的“记忆资产”不因工具切换而贬值。

2.3 本地优先与自动化学习

所有数据默认存储在你项目根目录下的 .kodo/memory.db （一个SQLite数据库文件）中。SQLite本身轻量、快速，并且 kōdo 启用了WAL模式和FTS5全文搜索扩展，使得记忆的存储和检索非常高效。你可以选择将 .kodo/ 目录加入 .gitignore 来保存私人记忆，也可以将其提交到仓库，作为团队共享的编码规范库。

此外， kodo learn 命令体现了“自动化”的思想。它能分析项目的Git提交历史，自动提取出一些潜在的惯例（比如检测到你们在使用Conventional Commits）和代码“热点”（某个文件被频繁修复，可能需要更多关注）。这相当于让工具帮你完成了记忆的“冷启动”。

3. 从零开始：安装、配置与基础使用

理解了设计思路，我们来看看如何把它用起来。整个过程非常轻量，几乎不会给你的开发流程增加负担。

3.1 安装与初始化

最快捷的方式是通过npm全局安装：

npm install -g kodo-memory

安装完成后，进入你的项目根目录，执行初始化命令：

cd /path/to/your/project
kodo init

这个命令会在当前目录下创建 .kodo/ 文件夹和其中的 memory.db 数据库文件。同时，它通常也会提示你是否要将 .kodo/ 加入 .gitignore ，根据你的需要选择即可。

如果你想直接从源码运行或参与贡献，也可以克隆仓库：

git clone https://github.com/Xuan-1998/kodo.git
cd kodo
npm install
# 然后使用 node bin/kodo.js 来代替 kodo 命令
node bin/kodo.js init

3.2 添加你的第一条记忆

初始化后，你的记忆库是空的。让我们从添加几条最基本的记忆开始，体验一下。

假设你的项目是一个Node.js后端服务，并且你决定全面采用ES Modules。

# 添加一条关于模块导入的惯例
kodo add -t convention -c "本项目全部使用ESM语法（import/export），禁止使用CommonJS的require()。所有.js文件需在package.json中声明 `\"type\": \"module\"`，或使用.mjs扩展名。" --tags "javascript,esm,module"

# 添加一条关于错误处理的错误记忆（曾经踩过的坑）
kodo add -t mistake -c "在作为库发布的代码中，绝对不要使用 `process.exit(code)` 来终止进程，这会导致使用该库的应用程序意外退出。正确的做法是抛出（throw）一个清晰的Error，由上游调用者处理。" --tags "nodejs,library,error-handling,process"

# 添加一条技术选型决策
kodo add -t decision -c "数据库层选择SQLite而非PostgreSQL，因为本项目是面向单用户的桌面端应用，SQLite提供了零配置、单文件存储的优势，且完全满足当前的数据复杂度和并发需求。" --tags "database,sqlite,architecture"

这里有几个实操要点：

• -t 或 --type ：指定记忆类型，就是前面提到的六种之一。
• -c 或 --content ：记忆的具体内容。建议描述清晰、具体，最好包含“要做什么”和“为什么”。
• --tags ：为记忆打上标签（可选，但强烈建议）。标签是空格或逗号分隔的关键词，能极大提升后续搜索的准确性。比如给“ESM”这条记忆打上 javascript, esm, module 标签。

执行后，你会看到类似 ✓ Remembered #1 [convention] ... 的成功提示。每条记忆都会被分配一个唯一的ID。

3.3 检索与查看记忆

随着记忆增多，你需要能快速找到它们。 kodo search 命令提供了灵活的检索方式。

# 1. 全文搜索：在所有记忆内容中查找关键词
kodo search "import"
# 这会返回所有内容中包含“import”的记忆，比如我们刚加的ESM惯例。

# 2. 按类型过滤
kodo search --type mistake
# 这会列出所有类型为“错误”的记忆，帮你快速回顾有哪些坑不能再踩。

# 3. 结合搜索词和类型
kodo search "sqlite" --type decision
# 这会找到关于SQLite的技术决策记忆。

# 4. 查看所有记忆（不加任何参数）
kodo search

搜索结果是实时从SQLite的FTS5全文搜索索引中返回的，速度很快。你还可以使用 kodo stats 来查看记忆库的统计数据，比如各类记忆的数量、最早/最晚添加时间等，对管理记忆库很有帮助。

注意： 在内容（ -c ）和标签（ --tags ）中使用的关键词都会影响全文搜索。因此，为记忆添加丰富、准确的标签，相当于手动构建了一个高质量的索引，能让你在几个月后依然能快速定位到那条模糊的记忆。

4. 核心环节实现：让记忆融入AI助手的工作流

仅仅在命令行里管理记忆还不够，关键是要让AI助手在编码时能“看到”并“利用”这些记忆。 kōdo 通过两种无缝的方式实现了这一点。

4.1 方式一：导出为原生配置文件（最通用）

这是最简单、兼容性最广的方式。运行一个命令， kōdo 就会把你的所有记忆，转换成各个AI助手能直接识别的配置文件格式。

kodo export

执行后，你会看到输出提示，表明文件已生成：

✓ claude → .claude/settings/memory.md (6 memories)
✓ cursor → .cursor/rules/kodo-memory.md (6 memories)
✓ kiro   → .kiro/steering/kodo-memory.md (6 memories)
✓ codex  → .codex/memory.md (6 memories)

现在，让我们看看这些文件里有什么。以生成的 .cursor/rules/kodo-memory.md 为例，它的内容结构非常清晰：

# kōdo Memory

_Automatically generated by kodo export_

## Convention
*   **#1**：本项目全部使用ESM语法（import/export），禁止使用CommonJS的require()。所有.js文件需在package.json中声明 `"type": "module"`，或使用.mjs扩展名。 [javascript, esm, module]

## Mistake
*   **#2**：在作为库发布的代码中，绝对不要使用 `process.exit(code)` 来终止进程，这会导致使用该库的应用程序意外退出。正确的做法是抛出（throw）一个清晰的Error，由上游调用者处理。 [nodejs, library, error-handling, process]

## Decision
*   **#3**：数据库层选择SQLite而非PostgreSQL，因为本项目是面向单用户的桌面端应用，SQLite提供了零配置、单文件存储的优势，且完全满足当前的数据复杂度和并发需求。 [database, sqlite, architecture]

...（其他记忆）

对于Claude Code、Cursor等工具来说，这个文件就是一条普通的规则（Rule）或记忆文件。AI助手在分析你的项目时，会自动将这些内容纳入其上下文考虑。这意味着， 即使 kōdo 的CLI或MCP服务器没有运行 ，只要这些配置文件存在，AI助手就能遵守这些规范。

你可以有选择地导出，比如只同步给Claude Code和Kiro：

kodo export --agents claude,kiro

实操心得： 我习惯将 kodo export 命令加入到我的项目启动脚本或 package.json 的 postinstall 钩子中。这样，每次我（或队友）克隆项目、安装依赖后，最新的记忆规则就会自动生成。也可以把它加到Git的 post-checkout 或 post-merge 钩子里，确保切换分支或拉取代码后记忆总是最新的。

4.2 方式二：集成MCP服务器（最强大）

MCP（Model Context Protocol）是一种让AI模型安全、结构化地访问外部数据和工具的协议。通过运行 kōdo 的MCP服务器，AI助手能在对话过程中 实时、主动 地与你的记忆库交互。

配置步骤：

1. 首先，确保你的AI助手支持MCP 。目前Claude Code、Cursor、Kiro的新版本都支持。

2. 配置MCP服务器 。你需要告诉你的AI助手去哪里找到 kōdo 的MCP服务器。

   • 对于Claude Code ，在终端执行：

     claude mcp add kodo -- node /path/to/kodo/src/mcp-server.js
     

     （请将 /path/to/kodo 替换为你实际的 kodo 项目克隆路径或全局安装的路径，通常全局安装后可以直接用 kodo-mcp 命令，具体请查看项目文档）。

   • 对于Cursor ，需要在项目或全局的 .cursor/mcp.json 文件中添加配置。如果文件不存在就创建它：

     {
       "mcpServers": {
         "kodo": {
           "command": "node",
           "args": ["/path/to/kodo/src/mcp-server.js"],
           "env": {}
         }
       }
     }
     

   • 对于Kiro ，配置在 .kiro/settings/mcp.json 中，格式类似。

3. 重启你的AI助手 ，让它加载新的MCP配置。

MCP工具实战：

配置成功后，在你的AI助手会话中，你就可以使用 kōdo 提供的工具了。例如，在Cursor中：

• 场景： AI助手刚刚帮你修复了一个因为忘记处理异步错误导致的Bug。
• 操作： 你可以对AI说：“记住这个，以后写异步函数要记得用 .catch 或 try-catch 处理错误。”
  • AI助手会调用 kodo_remember 工具，弹出一个表单让你确认。
  • 类型（Type）选择 mistake 。
  • 内容（Content）填入：“在Promise链或async函数中，必须显式处理错误。使用 .catch() 或在async函数外用 try...catch 包裹，避免未处理的Promise拒绝（Unhandled Promise Rejection）。”
  • 标签（Tags）可以填 javascript, async, error-handling, promise 。
• 结果： 这条新记忆立刻被存入数据库。当下次你或AI助手在处理类似异步代码时，可以通过 kodo_recall 工具搜索“async error”来快速回忆起这条教训。

MCP工具列表：

• kodo_remember : 存储新记忆。
• kodo_recall : 根据查询词和/或类型搜索记忆。
• kodo_forget : 根据ID删除一条记忆（比如发现某条记忆过时或不准确）。
• kodo_stats : 获取记忆库的统计信息。

重要提示： MCP模式是双向的，能力最强，但需要助手支持并正确配置。配置文件导出模式是单向的（只读），但兼容性极广，甚至能用于一些不支持MCP的编辑器插件。 我个人的最佳实践是两者结合使用 ：通过MCP进行动态的、会话中的记忆读写；同时定期运行 kodo export ，确保那些最核心的、稳定的惯例和决策，能以配置文件的形式被所有开发环境和工具（包括CI/CD中可能使用的静态分析工具）感知到。

5. 高级技巧与自动化：让记忆管理更智能

基础使用已经能带来巨大提升，但 kōdo 还有一些“进阶玩法”，能进一步解放你的生产力。

5.1 利用 kodo learn 自动挖掘项目历史

对于一个已有一定历史的项目，手动添加所有惯例和错误记忆是项繁重的工作。 kodo learn 命令可以帮你自动分析Git历史，提取潜在的模式。

# 在项目根目录执行
kodo learn

这个命令会做以下几件事：

1. 分析提交信息 ：识别是否使用了类似Conventional Commits（ feat: ， fix: ， chore: ）的规范，并生成一条“惯例”记忆。
2. 识别热点文件 ：分析哪些文件或路径被 fix 类型的提交频繁修改。这些地方往往是代码脆弱或逻辑复杂的区域， kodo learn 会生成一条“错误”或“笔记”记忆，提醒你和AI助手在这些区域修改时需要格外小心。
3. 扫描项目配置文件 ：如 package.json ， dockerfile 等，来推断项目的主要语言、框架、工具，并添加相关“笔记”记忆。

执行后，用 kodo search 看看它学到了什么。你可能会发现一些你自己都没意识到的团队习惯。这些自动生成的记忆可以作为基础，你可以对其进行审核、编辑（需要手动修改， kodo 目前不提供CLI编辑功能，但可以直接操作数据库或先删除再添加）或补充。

5.2 记忆的维护与更新

记忆库不是只增不减的。随着项目演进，一些决策可能过时，一些惯例可能改变。

• 删除记忆 ：使用 kodo forget <id> 命令。你可以先用 kodo search 找到那条记忆的ID。

• 更新记忆 ： kodo CLI目前没有直接的 edit 命令。更新一条记忆的常用方法是：

  1. kodo search 找到目标记忆及其ID。
  2. kodo forget <old_id> 删除旧的。
  3. kodo add -t <type> -c "<new_content>" 添加一条新的、修正后的记忆。 这虽然多了一步，但保持了操作的简单性和原子性。你也可以直接使用SQLite工具打开 .kodo/memory.db 文件进行修改，但这需要一些数据库知识。

• 团队共享 ：如果你希望团队共用一套记忆，可以将 .kodo/memory.db 文件纳入版本控制（前提是里面没有敏感的私人记忆）。更优雅的方式可能是定期将 kodo export 生成的配置文件（如 .cursor/rules/kodo-memory.md ）纳入版本控制，这样团队成员拉取代码后，他们的AI助手就能自动获得这些规则。 kōdo 的路线图中也有 kodo sync （通过Git同步记忆）的功能规划。

5.3 与其他工具组合使用

kōdo 可以和你已有的开发工具链结合，产生1+1>2的效果。

• 与 claude-mem 结合 ： claude-mem 擅长捕获和总结冗长的会话。你可以让它总结出本次会话中达成的关键共识或学到的教训，然后手动或通过脚本将其作为一条条清晰的“记忆”添加到 kōdo 中，完成从“会话记录”到“结构化知识”的提炼。
• 与代码质量工具结合 ：在CI/CD流水线中，你可以运行 kodo export 生成当前记忆的Markdown文件，然后使用 markdownlint 或其他文档检查工具来确保这些规则的表述清晰、格式统一。你甚至可以写一个简单的脚本，将ESLint或TypeScript编译器中某些高频出现的错误模式，自动转化为 kodo 的“错误”类记忆。
• 作为新成员 onboarding 材料 ：让新同事在配置好AI助手后，首先运行 kodo export 。这样，AI助手在帮助他们编写代码时，就已经内置了项目的所有“潜规则”和“历史经验”，能极大降低他们犯重复错误、违反团队规范的概率，加速上手过程。

6. 常见问题与排查实录

在实际使用中，你可能会遇到一些小问题。这里记录了一些常见情况和解决方法。

6.1 安装与初始化问题

• 问题： 执行 kodo init 时提示“数据库文件已存在”或权限错误。
  • 排查： 检查当前目录下是否已存在 .kodo 文件夹。如果这是你第一次初始化，可以尝试手动删除该文件夹再重新运行 init 。如果是权限问题，在Linux/macOS上尝试用 sudo （不推荐，最好修复目录权限），或在Windows上以管理员身份运行终端。
• 问题： kodo export 命令没有在对应位置生成配置文件。
  • 排查：
    1. 首先确认 kodo search 是否能正常显示记忆，确保数据库中有数据。
    2. 检查目标目录是否存在。例如，Cursor的规则目录是 .cursor/rules/ ，如果 .cursor 文件夹不存在， kodo 可能无法创建。你可以手动创建这些目录，或者检查 kodo 的日志输出。
    3. 运行 kodo export --agents claude 只导出一个代理，看是否成功，以排除是某个特定代理的路径配置问题。

6.2 MCP服务器连接失败

• 问题： 在AI助手中无法调用 kodo_remember 等MCP工具，提示服务器连接错误。
  • 排查步骤：
    1. 确认服务器运行 ：在终端直接运行MCP服务器命令（如 node src/mcp-server.js ），看是否有错误输出。确保Node.js版本符合要求。
    2. 检查路径 ：在Cursor或Claude Code的MCP配置中， command 和 args 里的路径必须是绝对路径，并且指向正确的 mcp-server.js 文件。全局安装和源码运行的路径不同。
    3. 检查环境 ：某些情况下需要配置 env 字段，尤其是如果 kodo 依赖某些环境变量来找到它的数据库。在MCP配置的 env 对象中，可以设置 KODO_DB_PATH 等变量。
    4. 查看助手日志 ：Claude Code和Cursor通常有开发者控制台或日志文件，里面会有更详细的MCP连接错误信息。
    5. 简化测试 ：尝试使用一个最简单的MCP服务器配置进行测试，以确认是否是 kodo 的MCP实现问题，还是配置问题。

6.3 记忆检索不准确或遗漏

• 问题： 用 kodo search 搜索某个关键词，感觉应该匹配到的记忆没有出现。
  • 排查与技巧：
    1. 理解FTS5 ： kōdo 使用SQLite的FTS5进行全文搜索。它会对文本进行分词。像“error-handling”这样的连词，可能会被分词成“error”和“handling”。搜索“error-handling”可能不如搜索“error handling”有效。
    2. 善用标签 ：这是最重要的技巧！在添加记忆时，务必用 --tags 参数添加多个相关的关键词。搜索时，系统会同时搜索内容和标签。标签相当于你为记忆建立的精准索引。例如，给所有关于React Hooks的惯例都打上 react, hooks 标签，以后搜索 react 就能一网打尽。
    3. 尝试模糊搜索 ：FTS5支持前缀搜索。例如，搜索 databa* 可能会匹配到“database”、“databases”等词。具体语法可查阅SQLite FTS5文档。
    4. 检查记忆内容 ：确保你要搜索的关键词确实以同样的形式出现在记忆内容或标签中。比如，你记忆里写的是“ES6模块”，但搜索的是“ESM”，就可能搜不到。

6.4 性能与数据管理

• 问题： 记忆条目非常多（比如上千条）后，搜索会变慢吗？

  • 解答： SQLite FTS5对于几千甚至几万条文本记录的搜索性能依然非常好，通常在毫秒级。真正的瓶颈可能在于AI助手的上下文长度。当你通过 kodo export 生成Markdown文件，或通过MCP的 kodo_recall 返回大量记忆时，可能会耗尽AI模型的上下文窗口。因此， 质量优于数量 。定期回顾和清理过时、冗余的记忆，保持记忆库的精炼和相关性，比一味堆砌更重要。 kodo recall 工具也支持按类型和相关性排序，可以帮助返回最相关的几条，而不是全部。

• 问题： 如何备份或迁移我的 kōdo 记忆？

  • 解答： 所有数据都在 .kodo/memory.db 这个SQLite数据库文件中。最简单的备份方式就是复制这个文件。迁移到新机器或新项目时，把这个文件放到新项目的 .kodo/ 目录下，然后运行 kodo export 即可。你也可以使用 kodo search --json 命令（如果支持）将记忆导出为JSON格式，然后在别处导入。

最后，一个我亲身踩过的坑：早期我贪图方便，添加了很多非常具体、场景极其狭窄的记忆（比如“在 src/utils/dateFormatter.js 这个文件里，月份要格式化成两位数字”）。后来这类记忆越来越多，反而在搜索更通用的“日期格式化”惯例时造成了干扰。我的建议是，尽量提炼 通用原则 ，而非记录具体案例。把“日期格式化要统一使用 YYYY-MM-DD 格式，并集中使用 src/utils/dateFormatter.js 中的 formatDate 函数”作为一条“惯例”记忆，远比记录一堆在哪个文件用了什么格式要有效得多。记忆库的价值在于其普适性和指导性，而不是成为一份琐碎的代码变更日志。