内容
<div align="center">
# 米密尔
**您的人工智能代理的记忆是一个 Markdown 文件夹。**
在 Obsidian 中打开它。手动编辑一个事实。代理在下一次思考时看到您的编辑 — 无需同步步骤，因为没有什么需要同步。
[](https://github.com/hasil7677/mimir/actions/workflows/ci.yml)
[](LICENSE)
[](docs/CLIENTS.md)
</div>
<!-- 📸 REPLACE ME: a GIF or screenshot of the Obsidian graph view showing
scenes → entities linked by [[wikilinks]], grown from a real conversation.
This is the single highest-leverage thing in this README — the whole
pitch is "your agent's brain is a vault you can see," so show it. -->
---
每个代理框架都有相同的问题：**对话从零开始。** 全上下文填充会烧掉您的 token 预算，朴素的摘要会永远丢弃事实，而扁平向量 RAG 无法区分昨天的记忆和六个月前的记忆。
米密尔是一种记忆引擎，它在**无需您运行任何操作的情况下**解决了这个问题。无需云账户，无需 Docker，无需 API 密钥。指向它，它就开始工作 — 一个本地文件成为转录文件，另一个文件成为可搜索的事实，而一个 Markdown 文件夹成为您可以实际阅读、理解和纠正的部分。稍后添加本地模型（或云模型），每个层都会自动变得更加清晰。您构建的任何内容都不需要更改。
## 为什么选择知识库，而不是数据库
其他记忆系统将代理的知识存储为不透明的行，您需要脚本才能检查。米密尔将其编写为 **OKF** （开放知识格式）— YAML 前面信息、Markdown 散文、`[[wikilinks]]` 链接事实和它们提到的实体。这意味着：
- **您可以打开它。** `~/.mimir/vault` 是一个真正的 Obsidian 知识库。图视图、反向链接、搜索 — 所有功能都是免费的，原生支持。
- **您可以修复它。** 代理得到了错误的信息？编辑笔记。修复将在下一次读取时生效。无需重新摄入，无需缓存失效操作。
- **它属于您。** 如果您想要历史记录，请对您的知识库执行 `git init`。将文件夹复制到新机器上，您的代理将记住所有内容，无论在哪里。
- **数据库只是索引。** DuckDB 和 Qdrant 存在是为了使搜索速度更快 — 知识库始终是事实的来源。
## 背景下发生了什么
四个存储库，每个存储库都是可选的，除了第一个存储库，每个存储库在缺失时都会独立降级：
| 存储库 | 持有 | 没有它 |
|---|---|---|
| **DuckDB** (`~/.mimir/memories.db`) | 原始转录、提取的事实、审计日志 | 没有它就不行 — 这是唯一必须存在的文件 |
| **知识库** (`~/.mimir/vault/`) | 人类可读的 Markdown：场景、实体、角色 | 没有图信号，没有链接笔记增强 — 事实仍然返回 |
| **Qdrant** (`~/.mimir/qdrant/`, 嵌入式) | 语义搜索的事实向量 | 仅限关键词召回 — 仍然真实，只是字面匹配 |
| **Redis** (可选服务器) | 热门近期对话 + 查询缓存 | 没有近期对话上下文，每次缓存未命中 — 仍然捕获 |
对话流程如下：**捕获**（原始对话回合进入 DuckDB，尽力推送到 Redis）→ **刷新** 在会话结束时（LLM 或确定性离线摘要将会话转换为 Obsidian 场景笔记，提取原子事实，与已知事实进行重复数据删除，标记矛盾而不是沉默地选择赢家，每 N 个事实刷新一次正在运行的角色文档）。**回忆** 运行相反：语义缓存检查 → BM25 + 向量混合搜索 → 互惠排名融合 → 四信号评分（语义相关性、时间衰减、访问频率、通过知识库自己的 wikilinks 的图接近度）→ 一个上下文字符串准备好注入到您的代理的提示中。
完整的图表和模块化演练： **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**。
## 快速开始
```bash
git clone https://github.com/hasil7677/mimir.git
cd mimir/engine
pip install -e ".[dev]"
uvicorn app.main:app --port 8080
```
就是这样 — `GET /health` 在零配置的情况下有效。无需 `mimir.yaml`、Redis 或 API 密钥。复制 `mimir.yaml.example` 到 `mimir.yaml` 时，您可以指向本地 Ollama 模型、云 LLM 或 Redis 实例；每个设置都有一个合理的默认值，直到那时。
## 立即从 Claude Code（或任何 MCP 客户端）使用它
```bash
claude mcp add mimir --scope user -e MIMIR_USER_ID=you -- python /path/to/mimir/engine/adapters/mcp_embedded.py
```
无需运行网关 — 嵌入式适配器直接导入引擎，因此在您的代理会话打开时，进程才存在。显示了三个工具：`mimir_recall`、`mimir_remember`、`mimir_flush`。指向您的 `CLAUDE.md`，您的代理开始为您构建记忆，一次对话一个。
还记录了：OpenCode（原生 MCP）、Pi（通过社区 `pi-mcp-adapter`）和用于其他任何事物的纯 HTTP 合同 — 请参阅 **[docs/CLIENTS.md](docs/CLIENTS.md)**。
## 状态
这是早期版本 — 构建迅速，测试严格，但至今只有我测试过，还没有经过实战测试。以下是诚实的划分：
**稳固且经过测试（83 个测试 — 80 个测试在零服务运行时通过，3 个测试需要 Redis — 真实的 HTTP 层、真实的文件系统、真实的重复数据删除逻辑）：**
混合召回与 4 信号评分公式 · 语义缓存与测量的缓存命中 · L1.5 事实合并（精确重复检测需要零 LLM 调用；存在 LLM 时，您会获得存储/跳过/替换/矛盾标记决策，幻觉目标 ID 被拒绝）· GDPR 样式的删除和导出，跨每个存储 · 孤立会话的自我修复恢复路径（实时发现，实时修复 — 请查看提交日志）· MCP 支持在真实 Claude Code 会话中验证端到端。
**已知但未隐藏的空白：**
- 尚无真正的图数据库 — [KuZu](https://kuzudb.com) 没有 Python 3.11+ 轮，因此实体关系作为知识库 `[[wikilinks]]` 存在，具有跳跃距离评分，而不是 Cypher 可遍历的图。评分接口已经基于跳跃，因此 KuZu 可以在无需重写的情况下安装。
- 实体提取是正则表达式启发式（大写运行检测），不是真正的 NER 模型。它有效，但也偶尔会将不应 wikilink 的专有名词链接起来。spaCy 是计划中的修复。
- 暂无基准测试数字 — 暂无 PersonaMem 运行，暂无测量的召回准确率。所有设计声明都是架构推理，而不是已发布的分数。
- LangChain / OpenAI Agents 适配器尚未构建。它们需要的 HTTP 合同已经存在。
如果您正在寻找具有支持合同的经过生产验证的产品，这不是它。但如果您想看看当数据库被视为缓存，文件系统被视为真相时，记忆系统是什么样子，请打开知识库。
## 开发
```bash
pip install -e ".[dev]"
pytest # 83 个测试；Redis 支持的测试在没有服务器的情况下自动跳过
```
CI 在 Python 3.11–3.13 上运行测试套件，在 Ubuntu 和 Windows 上均运行 — Windows 测试环境不是装饰品，它在开发过程中捕获了一个真正的时区错误。
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。建立在核心内存引擎始终免费和开放的理念之上；任何类似托管/托管产品的产品都是另一天的单独对话。
