内容
# 记忆女神
[](https://github.com/Furinelle/Mnemosyne/actions/workflows/ci.yml)
> 希腊记忆女神，九位缪斯之母。
**记忆女神是一款本地优先、代理无关的记忆内核。** 长期记忆以纯 Markdown 文件存储在磁盘上，通过 SQLite FTS5 混合检索索引，由所有使用的代理共享 — Claude Code、Codex CLI、Cursor、Hermes 或任何可以支持 MCP、运行 shell 命令或读取文件。
[中文文档 → README.zh.md](README.zh.md)
## 为什么选择记忆女神
大多数代理记忆系统要求您在以下三者之间做出选择：繁重的基础设施（Postgres + 向量数据库 + Docker）、每次写入都需要 LLM 密钥，或单一厂商的生态系统。记忆女神拒绝了这三者：
- **文件是真相的来源。** 每个记忆都是 Markdown + YAML 前置信息。可以读取、grep、git 差异、手动编辑。您的记忆将永远可读，无论是否使用记忆女神。
- **零重依赖。** Python 3.11+ 和 `portalocker`。检索是 SQLite FTS5（支持中文、日文、韩文混合搜索，可选向量通道和重排序器）；如果 FTS5 不可用，则降级为纯标准库 BM25。
- **默认情况下不涉及 LLM。** 自动蒸馏是启发式优先的；LLM 引擎是可选的，永远不需要。
- **代理中立的核心，边缘适配器。** 一个内核，一个存储，多个门户：MCP 工具、CLI、生命周期注入事件和直接文件访问。
## 快速开始
```bash
git clone https://github.com/Furinelle/Mnemosyne && cd Mnemosyne
pip install -e .
cd /path/to/your/project
python3 -m mnemosyne init # 创建 .mnemosyne/ + 一个通用的 AGENTS.md
python3 -m mnemosyne write --type pitfall --importance 70 \
--title "示例" --content "身份验证令牌在 15 分钟后过期。"
python3 -m mnemosyne search "身份验证令牌"
```
全局偏好存储在 `~/.mnemosyne/` 中，项目知识存储在存储库的 `.mnemosyne/` 中。
## 集成任意代理
三种访问路径，请根据代理的能力选择：所有路径共享相同的存储和检索内核。
### 1. MCP（适用于 Claude Code、Codex CLI、Cursor、Cline、Windsurf、Gemini CLI 等）
```bash
python3 -m mnemosyne mcp serve # 标准输入/输出，纯标准库，无需额外安装
```
工具：`mnemosyne_search`、`mnemosyne_write`、`mnemosyne_read_core`、`mnemosyne_show`、`mnemosyne_link`、`mnemosyne_graph`、`mnemosyne_maintain`、`mnemosyne_prep_context`。Cursor / Cline / Continue / Windsurf 的客户端配置片段位于 `mnemosyne/templates/mcp_clients/` 中。
纯 MCP 客户端通过两次调用获得完整的工作流程：`mnemosyne_read_core` 在会话开始时，`mnemosyne_search` 在需要上下文时。
### 2. CLI + 注入事件（任意具有 shell 或钩子的代理）
每个功能都是一个子命令（`write`、`search`、`show`、`link`、`graph`、`distill`、`prep`、`ingest` 等），在需要时输出 JSON 格式。通过以下方式提供四个代理中立的生命周期事件：
| 事件 | 何时 | 有效载荷（stdin JSON） |
|---|---|---|
| `session_start` | 会话打开 | `{}` → 核心内存块 |
| `turn_start` | 用户提交提示 | `{"prompt": "..."}` → 相关记忆 |
| `file_touch` | 代理即将编辑文件 | `{"files": ["a.py"]}` → 文件相关记忆 |
| `session_end` | 会话关闭 | `{"text": ...}` 或 `{"transcript": {"path": ...}}` → 自动蒸馏 |
```bash
echo '{"prompt": "为什么 portalocker 会死锁"}' | \
python3 -m mnemosyne inject --event turn_start --session my-session --format json
```
`--fail-safe` 使得在任何错误时退出并返回 0 且输出为空，因此钩子永远不会阻塞主机。有关完整的适配器合约，请参见 [docs/adapters.md](docs/adapters.md)。
### 3. 文件（任意可以读取文件的代理）
`.mnemosyne/core.md` 是始终相关的摘要；每个记忆的文件位于 `.mnemosyne/working/` 下。前置信息架构和 `search --format json` 输出架构在 [docs/interface.md](docs/interface.md) 中指定。查找交换（代理 → 记忆）在 [docs/handoff-format.md](docs/handoff-format.md) 中指定，具有 Markdown 和 JSON 变体。
## 官方适配器
| 代理 | 集成 | 安装 |
|---|---|---|
| Claude Code | 生命周期钩子（SessionStart / UserPromptSubmit / PreToolUse / Stop）带有确定性注入 + 自动蒸馏 | `python3 -m mnemosyne install claude-code`（打印合并步骤） |
| Codex CLI | `AGENTS.md` 协议 + `prep` / `ingest` 切换块 | `python3 -m mnemosyne init --agent codex` |
| Hermes | 原生 MemoryProvider 插件（inject、recall、tool、distill） | `python3 -m mnemosyne install hermes` |
适配器是同一中立事件上的对等方；编写另一个代理适配器是一个薄映射层；请参见 [docs/adapters.md](docs/adapters.md)。
## 功能亮点
- **混合检索**：SQLite FTS5 支持中文、日文、韩文混合搜索，可选嵌入通道通过 RRF 融合，可选交叉编码器重排序，类型链接图扩展。
- **记忆生命周期**：强度衰减、存档、回忆奖励、过期、核心推广候选、近重复合并。
- **类型化关系和图**：`caused_by` / `refines` / `supersedes` / `contradicts` / `related`，使用 Mermaid / ASCII / JSON 渲染。
- **时间有效性**：过时的记忆被标记为无效但保留；默认检索过滤它们，`--include-superseded` 回顾过去。
- **自动记忆形成**：可选的 `distill` 从转录（`claude-jsonl`，中立 `role-jsonl`，纯文本）中提取持久记忆，具有重复和取代处理后写入。
- **可重复评估**：`eval run` 报告在固定语料库上的召回率/MRR；`eval convert longmemeval` + `eval run --longmemeval` 与 LongMemEval 基准测试；CI 强制实施召回率@5 回归门控。
- **设计并发安全**：原子写入、`portalocker` 锁排序、SQLite WAL — 多个代理可以共享一个存储。
## 稳定性承诺
- 记忆文件保持可读：存储格式稳定且版本控制更改仅追加。
- `mnemosyne.api` 模块是公共 Python API。
- 旧版接口（`codex-prep` / `codex-ingest` / `install-hermes` 命令、`mnemosyne.codex` / `mnemosyne.hooks.*` 导入、`mnemosyne_codex_prep` MCP 工具）保留为别名。
## 更新日志
当前版本：0.7.0 — “通用记忆内核”版本：稳定的 `mnemosyne.api`、中立注入事件（`mnemosyne inject`）、JSON 查找变体、转录解析器注册表、每个代理适配器和模板、英文优先文档。存储格式不变；所有旧版命令、导入路径和 MCP 工具名称通过别名继续工作。请参见 [CHANGELOG.md](CHANGELOG.md)。
## 开发
```bash
python3 -m pytest tests/ -q
python3 -m mnemosyne doctor
```
许可证：MIT。欢迎贡献 — 运行测试套件并保持标准库核心约束。
