mnemo

Claude Code、Codex、Cursor、OpenCode 和 Pi 共用同一可信数据源。

English · Español · 简体中文

快速开始 · 为什么选择 mnemo？ · 工作原理 · Agent · 文档 · 社区 · 路线图

---

为什么选择 mnemo？

Agent 会遗忘。Markdown 记忆会偏离。钩子会发生竞争。设置可能悄无声息地失败。

不使用 mnemo	使用 mnemo
决策在不同会话之间消失	将项目记忆持久保存在本地 SQLite 中
MEMORY.md、编辑器记忆和聊天笔记各不相同	所有受支持 Agent 共用一个项目级可信数据源
全局钩子要么到处运行，要么毫无用处	通过 .mnemo 选择启用；未标记的项目会被忽略
配置错误不易察觉	mnemo doctor 会准确说明接入情况；mnemo doctor --fix 会修复问题

mnemo 并不声称支持所有 harness。它提供稳定的记忆契约，任何 harness 都可以实现并验证。

快速开始

# 1. Install the latest stable release
curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash

# 2. Activate in a project
cd your-project
mnemo init --agent=all

# 3. Verify
mnemo doctor --agent=all --path=.

然后在你的 Agent 中使用 mem_save 保存决策，结束会话并开启另一个会话——mem_search / mem_context 就能找到它。

mnemo search "SQLite" --project "$(mnemo json id < .mnemo)"

安装程序和 mnemo update 会跟随最新发布的稳定版本（v1.0.0）。只有在选择使用预发布版本时，才使用 mnemo update --prerelease。有关更新和 Agent 专属设置，请参阅安装指南。

工作原理

1. Agent 通过 MCP 工具、钩子和可移植的 Agent 技能与 mnemo 交互。
2. 本地事件控制器 是唯一常规的 SQLite 写入者——发布者绝不会打开数据库。
3. 记忆 保留在你的设备上：SQLite + FTS5 中的结构化观察记录、标签、主题键和会话摘要。

project/
├── .mnemo      # project ID + activated agents (gitignored)
├── AGENTS.md   # shared memory authority
├── CLAUDE.md   # Claude rules when selected
├── .cursor/    # Cursor rules when selected
└── .pi/        # Pi prompt extensions when selected

关于传递和故障语义，请参阅持久事件。

亮点

• 项目范围的激活 — 没有有效的 .mnemo 时，全局钩子保持不活动
• MCP + 原生工具 — mem_save、mem_search、mem_context、mem_doctor 等
• 持久事件控制器 — 每位用户使用 JetStream；采用幂等 SQLite 事务
• 控制器管理的会话 — Agent 原生执行 ID 绑定到一个规范会话
• 可移植技能 — 教会 Agent 使用 mnemo，而不是退回到原生记忆
• 被动捕获 — 从 Agent 提供的输出中提取经验
• 来源信息 — 可通过 SQL 查询的 Agent、工具、模型和 MCP 客户端元数据
• 诊断与修复 — mnemo doctor / mnemo doctor --fix、项目合并/重命名、mnemo memories review
• 安全迁移与自我更新 — 打开时升级架构；通过 mnemo update 获取版本更新

支持的 Agent

Agent	MCP	钩子 / 运行时	全局指令	技能	状态
Claude Code	是	会话钩子	是	是	支持
Codex	是	会话钩子	是	是	支持
Cursor	是	提示词钩子	是	是	支持
OpenCode	是	插件事件	是	是	支持
Pi	原生工具	原生扩展	是	是	支持

安装后，Codex 需要交互式钩子信任审核——详情请参阅 Agent 集成。

Claude Code 在设置了 CLAUDE_CONFIG_DIR 时会使用它作为配置目录，否则默认为 ~/.claude。设置了 CLAUDE_CONFIG_DIR 时，其 MCP 配置文件 .claude.json 位于该目录中；否则位于 $HOME 中。

相关模块

模块	用途
mnemo-adapters	CLI、控制器和 MCP 的 Agent 适配器接口与映射
mnemo-events	发布者、控制器和存储共用的持久事件与命令契约

安装选项

方式	命令
固定稳定版（v1.0.0）	curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | MNEMO_VERSION=v1.0.0 bash
最新稳定版	curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash
安装到一个 Agent	bash -s -- --agent=codex
安装到所有 Agent	bash -s -- --agent=all
从源代码构建	go build -o ~/.local/bin/mnemo ./cmd/mnemo/

安装程序会为每个 Agent 配置指令、MCP 服务、钩子和技能。mnemo 不附带 Agent 插件。如果你在早期版本中安装了 mnemo Claude Code 或 Codex 插件，mnemo doctor 会报告该插件，而 mnemo doctor --fix 会将其移除并恢复安装程序的配置。

完整的更新标志和卸载步骤请参阅：安装。

文档

指南	内容
Wiki 首页	用户文档与导航
安装	二进制文件、控制器、激活、更新
Agent 集成	原生 ID、钩子、工具、Codex 信任
持久事件	控制器架构与故障行为
CLI 参考	命令、MCP 工具、搜索模式
故障排查	诊断与控制器恢复
存储	SQLite、迁移、sqlc
路线图	计划中的产品与维护工作

设计原则

• 本地优先 — 记忆保存在你设备上的 SQLite 中
• 与 Agent 无关 — 在受支持的编码 Agent 之间共用一个记忆权威
• 按项目选择启用 — 没有 .mnemo 时，全局集成不会生效
• 便于诊断 — 无需更改即可检查每个设置界面，且 mnemo doctor --fix 可修复问题
• 可修复 — 重复项目和记忆冲突均清晰可见，并可通过 CLI 修复

社区

如果 mnemo 对你的 Agent 工作流有所帮助，请为仓库点 Star——这能表明值得构建本地且与 Agent 无关的记忆功能。

• 参与贡献 — 构建、测试并提交 PR
• 行为准则 — 社区规范
• 安全 — 私下报告漏洞
• 网站 · Wiki · 路线图

许可证

Apache 2.0：可自由使用、修改和分发；请保留版权声明，并在所有分发版本中附上 NOTICE。