内容
="center">
<img src="assets/ferris_is_big.png" alt="Ferris — matte gold crab on white sand under a galaxy sky" width="720"/>
</p>
<h1 align="center">mnemex</h1>
<p align="center">
<strong>个人AI记忆层 — 向量存储 + 会话合并 + 连接到 GitHub Copilot 的 MCP 服务器</strong>
</p>
<p align="center">
<img alt="Rust" src="https://img.shields.io/badge/Rust-1.96+-f74c00?style=flat-square&logo=rust&logoColor=white"/>
<img alt="MCP" src="https://img.shields.io/badge/MCP-rmcp%202.1-6366f1?style=flat-square"/>
<img alt="Embeddings" src="https://img.shields.io/badge/embeddings-nomic--embed--text--v1.5-10b981?style=flat-square"/>
<img alt="Local" src="https://img.shields.io/badge/100%25%20local-no%20API%20key-0ea5e9?style=flat-square"/>
<img alt="License" src="https://img.shields.io/badge/license-MIT-gray?style=flat-square"/>
</p>
---
## 为什么
每次与 AI 助手的对话都从零开始。
上下文、决策、模式、代码 — 所有这些都在会话结束时消失。
Mnemex 解决了这个问题。它为 GitHub Copilot 提供了一个**持久的、语义化的记忆**，该记忆在会话、工作区和时间中存续。当我开始一个新的对话时，Copilot 可以回忆起我们上周一起构建的内容 — 架构决策、经验教训、代码模式、未解决的问题。
无需云服务。无需 API 密钥。无需依赖他人的废弃计划。所有操作都在本地运行。
---
## 架构
```
mnemex/
├── crates/
│ ├── mnemex-core/ # 核心逻辑 — 嵌入 + 存储 + 合并
│ │ └── src/
│ │ ├── error.rs # MnemexError (thiserror, no anyhow)
│ │ ├── embedder.rs # fastembed 包装器 + 金丝雀哈希锁定
│ │ ├── store.rs # 平面 JSON 存储 + 余弦相似性搜索
│ │ └── consolidate.rs# 贪婪近重复移除
│ └── mnemex-mcp/ # MCP 服务器 (rmcp, stdio)
│ └── src/main.rs # 工具 + SIGTERM 合并钩子
└── .vscode/mcp.json # VS Code 连接
```
## MCP 工具
| 工具 | 功能 |
|------|-------------|
| `remember(text, tags?)` | 嵌入并持久化记忆 |
| `recall(query, top_k?)` | 对所有记忆进行语义搜索 |
| `forget(id)` | 按 ID 删除记忆 |
| `list_memories(limit?)` | 列出最近的记忆 |
| `consolidate(session_id?, dedup_threshold?)` | 去除会话重复（自动关闭时） |
| `session_id()` | 获取当前会话 UUID |
---
## 模型一致性保证
嵌入器（`nomic-ai/nomic-embed-text-v1.5` via fastembed）通过存储在 `~/.local/share/mnemex/model_lock.json` 中的 SHA-256 金丝雀哈希锁定。
如果 fastembed 包版本曾经悄悄更改模型权重，服务器将拒绝启动。这确保插入、查询和合并始终使用完全相同的嵌入空间。
## 会话合并
当 VS Code 关闭 → **SIGTERM** → 服务器在退出前为当前会话运行 `consolidate_session`（贪婪余弦去重，阈值 0.92）。
手动触发：
```bash
# 通过 MCP 工具
consolidate(dedup_threshold=0.92)
# 或直接
kill -SIGTERM $(pgrep mnemex-mcp)
```
---
## 安装
**系统依赖（Fedora/RHEL）：**
```bash
sudo dnf install -y gcc gcc-c++ openssl-devel
```
**构建：**
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
cargo build --release
```
首次运行时，下载 ONNX 模型（约 522 MB）到 `~/.cache/fastembed/`。
**VS Code：** `.vscode/mcp.json` 已经配置好。重新加载窗口，`mnemex` MCP 服务器将出现在 Copilot 的工具列表中。
---
## 数据
```
~/.local/share/mnemex/
├── memories.json # 平面向量存储（原子写入）
└── model_lock.json # 金丝雀哈希 — 请勿手动编辑
```
---
## 技术栈
- **[rmcp](https://crates.io/crates/rmcp)** — 官方 Rust MCP SDK（stdio 传输）
- **[fastembed](https://crates.io/crates/fastembed)** — 本地 ONNX 嵌入，nomic-embed-text-v1.5
- **[thiserror](https://crates.io/crates/thiserror)** — 显式类型错误，无 anyhow
- **tokio** — 异步运行时
- 余弦相似性搜索 — O(n)，10k 条目下 < 1ms
