mnema

# 🧠 Mnema — 人工智能长期记忆 > 为您的AI代理提供持久、可搜索的记忆。使用 **MCP × 向量数据库** 解决上下文窗口问题。 [](#-快速开始) [](https://www.python.org/downloads/) [](LICENSE) [](https://modelcontextprotocol.io/) [](#状态) **Mnema**（μνῆμα — 希腊语意为 *"记忆"*）是一个开源的 [模型上下文协议](https://modelcontextprotocol.io) 服务器，为语言模型代理提供长期记忆层。不要将所有相关事实都塞进一次对话中（并为此付出代币、延迟和丢失上下文的代价）；而是将持久的事实存储一次，通过意义而不是关键词来回忆。 --- ## ✨ 功能 - **🔌 MCP原生** — 直接集成到Claude Desktop、ZCode、Cursor或任何MCP兼容的客户端。 - **🗄️ 可插拔的向量后端** — ChromaDB（嵌入式，默认）、Qdrant（本地或远程）或sqlite-vec（纯SQLite，零依赖）。 - **🧠 混合搜索** — 将 **语义相似度** + **标签重叠** + **衰减评分** 结合成单个排名分数。 - **⏳ 记忆衰减** — 一个遗忘曲线（`近期 × 频率 × 重要性`），让存储器专注于重要的事情。 - **📝 总结** — 计划如何将许多记忆浓缩成几个高级别的记忆；调用AI执行计划（Mnema不会自己调用LLM）。 - **👥 多用户/多会话** — 基于作用域的命名空间隔离（`user:alice`、`session:abc`、`agent:bot-1`）。 - **🔧 默认离线** — 本地句子转换器嵌入；无需API密钥即可启动。 - **📦 编程SDK** — 从Python使用Mnema，无需启动MCP服务器。 - **💻 CLI** — `mnema add`、`mnema recall`、`mnema stats`… 适用于终端优先的工作流。 - **🧪 经过充分测试** — 纯函数单元测试 +针对每个支持的存储器的后端矩阵。 --- ## 🚀 快速开始 ### 一行安装（推荐） ```bash curl -fsSL https://raw.githubusercontent.com/mienetic/mnema/main/scripts/install.sh | bash ``` 安装程序： 1. 安装 [`uv`](https://docs.astral.sh/uv/) （无需pip/虚拟环境管理）。 2. 从GitHub克隆Mnema。 3. 使用所有依赖项创建隔离的Python 3.11环境。 4. 安装 `mnema` 和 `mnema-update` 命令。 5. 运行 `mnema --doctor` 进行验证。 > 🇹🇭 **新手？** 请参阅 [GETTING_STARTED.md](GETTING_STARTED.md) — 逐步指南（泰语）。 ### 验证和更新 ```bash mnema --doctor # 检查后端 + 嵌入加载 mnema # 运行MCP服务器（标准输入输出，用于客户端） mnema-update # git pull + 重新安装 + 验证（运行此命令进行升级） ``` ### 选择不同的后端/嵌入（可选） 默认安装提供 **Chroma + 本地嵌入** — 足够满足大多数用户需求。要使用其他后端，请使用匹配的额外功能重新安装： ```bash # Qdrant（本地或远程） curl -fsSL https://raw.githubusercontent.com/mienetic/mnema/main/scripts/install.sh \ | MNEMA_EXTRAS="qdrant,local" bash # sqlite-vec（最小占用空间） curl -fsSL https://raw.githubusercontent.com/mienetic/mnema/main/scripts/install.sh \ | MNEMA_EXTRAS="sqlite_vec,local" bash # 所有功能（所有后端 + OpenAI嵌入） curl -fsSL https://raw.githubusercontent.com/mienetic/mnema/main/scripts/install.sh \ | MNEMA_EXTRAS=all bash ``` 可用额外功能：`chroma`、`qdrant`、`sqlite_vec`、`local`、`openai`、`default`（= `chroma,local`）、`all`。请参阅 [docs/backends.md](docs/backends.md) 和 [docs/embedding-providers.md](docs/embedding-providers.md)。 ### 手动/从源码 ```bash git clone https://github.com/mienetic/mnema cd mnema/packages/mnema-python uv venv --python 3.11 .venv VIRTUAL_ENV=.venv uv pip install -e '.[default]' .venv/bin/mnema --doctor ``` ### 连接到您的AI客户端 从下面的客户端中选择一个。**每个示例都假定Mnema已经安装**（`mnema`在您的`PATH`中）。 <details> <summary><b>Claude Desktop</b> （Anthropic的桌面应用）</summary> 1. 查找或创建配置文件： - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` *(在Finder中，按`Cmd+Shift+G`并粘贴路径)* - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` 2. 将以下内容粘贴到文件中（如果已存在，请与现有的`mcpServers`合并）： ```json { "mcpServers": { "mnema": { "command": "mnema", "env": { "MNEMA_BACKEND": "chroma", "MNEMA_BACKEND_PATH": "~/.mnema-data", "MNEMA_DEFAULT_SCOPE": "user:me" } } } } ``` 3. **完全退出Claude Desktop** （菜单 → 退出，而不仅仅是关闭窗口）并重新打开。 4. 验证：点击聊天中的 **🔌 插件图标** — `mnema` 应该出现在列表中。 5. 尝试： *"记住我更喜欢深色模式。"* 然后，在新的聊天中， *"你知道我的偏好是什么？"* </details> <details> <summary><b>Claude Code</b> （<code>claude</code> CLI）</summary> 1. 从项目根目录添加服务器： ```bash claude mcp add mnema mnema ``` 或直接添加到 `~/.claude.json` （用户范围）： ```json { "mcpServers": { "mnema": { "command": "mnema", "env": { "MNEMA_DEFAULT_SCOPE": "user:me" } } } } ``` 2. 启动 `claude` 并运行 `/mcp` 以确认 `mnema` 已连接。 3. 工具会自动可用 — 尝试 *"记住这个项目使用Postgres"*。 </details> <details> <summary><b>Cursor</b> （AI代码编辑器）</summary> 1. 创建 `~/.cursor/mcp.json` （全局）或 `.cursor/mcp.json` （项目级）： ```json { "mcpServers": { "mnema": { "command": "mnema", "env": { "MNEMA_BACKEND": "chroma", "MNEMA_BACKEND_PATH": "~/.mnema-data", "MNEMA_DEFAULT_SCOPE": "project:current" } } } } ``` 2. 打开Cursor → **设置 → MCP** （或重新加载窗口：`Cmd+Shift+P` → "Reload Window"）。 3. `mnema` 应该显示一个绿色点。如果是红色，请使用 `which mnema` 检查路径。 4. 在聊天中使用： *"搜索我的记忆中的过去决策关于auth模块。"* </details> <details> <summary><b>Zed</b> （编辑器）</summary> 1. 打开 `~/.config/zed/settings.json` （macOS）并在 `context_servers` 下添加： ```json { "context_servers": { "mnema": { "command": { "path": "mnema" }, "env": { "MNEMA_DEFAULT_SCOPE": "user:me" } } } } ``` 2. 重新启动Zed，然后在Assistant面板设置中启用服务器。 3. 在Assistant中，标签 `@mnema` 以拉取记忆上下文到对话中。 </details> <details> <summary><b>Cline</b> （VS Code扩展）</summary> 1. 打开Cline侧边栏 → **MCP图标** → **"编辑MCP设置"**。 2. 将条目添加到 `cline_mcp_settings.json`： ```json { "mcpServers": { "mnema": { "command": "mnema", "env": { "MNEMA_DEFAULT_SCOPE": "workspace" }, "disabled": false, "alwaysAllow": [] } } } ``` 3. Cline自动检测更改 — 无需重启。 4. 询问Cline： *"搜索我对测试策略的记忆。* </details> <details> <summary><b>Continue.dev</b> （VS Code / JetBrains）</summary> 1. 打开 `~/.continue/config.json` 并在 `experimental.modelContextProtocolServers` 下添加： ```json { "experimental": { "modelContextProtocolServers": [ { "transport": { "type": "stdio", "command": "mnema" } } ] } } ``` 2. 重新加载窗口（`Cmd+Shift+P` → "Reload Window"）。 3. 在Continue聊天中使用 `@mnema` 以作用域记忆工具。 </details> <details> <summary><b>Windsurf</b> （Codeium的编辑器）</summary> 1. 打开 **设置 → MCP服务器** → **"添加服务器"** （或编辑 `~/.codeium/windsurf/mcp_config.json`）： ```json { "mcpServers": { "mnema": { "command": "mnema" } } } ``` 2. 点击 **刷新** 在MCP面板 — `mnema` 应该激活。 3. 使用Cascade与 `@mnema` 回忆项目上下文。 </details> <details> <summary><b>任意其他MCP客户端</b> （通用）</summary> Mnema是一个标准的 **stdio** MCP服务器。任何支持 [模型上下文协议](https://modelcontextprotocol.io) 的客户端都可以启动它： ```json { "mcpServers": { "mnema": { "command": "mnema" } } } ``` 对于 **远程/多客户端** 设置，请通过可流式HTTP运行Mnema： ```bash mnema --transport http --host 127.0.0.1 --port 8000 # 然后将客户端指向 http://127.0.0.1:8000/mcp ``` </details> 所有客户端的即复制配置都在 [`examples/`](examples/) 中。 --- ## 🛠️ 工具 | 工具 | 描述 | 只读？ | |---|---|---| | `mnema_remember` | 存储新记忆 | ✏️ | | `mnema_recall` | 纯语义向量搜索 | 🔍 | | `mnema_search` | 混合：向量 + 标签 + 衰减 | 🔍 | | `mnema_get_memory` | 通过id获取记忆 | 🔍 | | `mnema_update_memory` | 修补文本/标签/重要性/元数据 | ✏️ | | `mnema_forget` | 删除一个记忆 | 🗑️ | | `mnema_forget_scope` | 删除作用域中的所有记忆 | 🗑️ | | `mnema_list_scopes` | 枚举作用域 + 计数 | 🔍 | | `mnema_summarize` | 计划如何压缩作用域 | 🔍 | | `mnema_apply_decay` | 查找/忘记低值记忆 | 🗑️ | | `mnema_stats` | 聚合存储统计数据 | 🔍 | 还有 **资源** (`mnema://memory/{id}`、`mnema://scope/{s}/summary`、`mnema://stats`) 和 **提示模板** (`summarize_scope`, `recall_for`)。 请参阅 **[SKILL.md](SKILL.md)** 以获取完整的Agent端使用指南。 --- ## 💻 CLI 您不需要AI客户端即可使用Mnema — `mnema` 命令也是终端工具（与安装程序免费附带）。 ```bash # 存储记忆 mnema add "Alice prefers Earl Grey tea" --tags pref,tea --scope user:alice # 按含义回忆 mnema recall "what does alice drink?" --scope user:alice # 混合搜索（向量 + 标签 + 衰减） mnema search "preferences" --tag pref --scope user:alice # 检查 mnema get <id> mnema list-scopes mnema stats # 维护 mnema decay --threshold 0.1 # 干运行：列出低值记忆 mnema decay --threshold 0.1 --apply # 实际忘记它们 mnema summarize session:abc # 计划如何压缩作用域 # 备份/迁移 mnema export -o memories.json mnema import -i memories.json ``` 在任何读取命令中添加 `--json` 以获取机器可读的输出。运行 `mnema <command> --help` 以获取完整选项。 --- ## 🧑‍💻 编程SDK 从Python使用Mnema无需MCP — 相同的引擎，无需IPC： ```python import asyncio from mnema.sdk import MemoryClient async def main(): async with MemoryClient() as client: await client.remember( "Alice's deployment target is fly.io (region sin).", scope="project:web", tags=["deploy", "infra"], importance=8, ) hits = await client.search("where do we deploy?", scope="project:web") print(hits.results[0].memory.text) asyncio.run(main()) ``` 同步辅助脚本： ```python from mnema.sdk import sync_client with sync_client() as client: client.remember("a durable fact", tags=["x"]) print(client.recall("durable").results) ``` --- ## ⚙️ 配置 所有设置均由环境驱动（或 `.env`）： | 变量 | 默认值 | 描述 | |---|---|---| | `MNEMA_BACKEND` | `chroma` | `chroma` \| `qdrant` \| `sqlite_vec` | | `MNEMA_BACKEND_PATH` | `.mnema/data` | 本地路径或远程URL (`http://…`) | | `MNEMA_BACKEND_COLLECTION` | `memories` | 集合/表名 | | `MNEMA_EMBEDDING` | `local` | `local` (离线) \| `openai` | | `MNEMA_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | 模型名称 | | `MNEMA_EMBEDDING_DIM` | _auto_ | 重写向量维度 | | `MNEMA_OPENAI_API_KEY` | — | 当 `embedding=openai` 时需要 | | `MNEMA_DEFAULT_SCOPE` | `global` | 工具省略作用域时的作用域 | | `MNEMA_DECAY_HALF_LIFE_DAYS` | `30` | 衰减半衰期 | | `MNEMA_DECAY_FLOOR` | `0.05` | 最小衰减分数 | | `MNEMA_VECTOR_WEIGHT` | `0.7` | 混合分数权重（必须加起来为1） | | `MNEMA_KEYWORD_WEIGHT` | `0.2` | 混合分数权重 | | `MNEMA_DECAY_WEIGHT` | `0.1` | 混合分数权重 | | `MNEMA_TRANSPORT` | `stdio` | `stdio` \| `http` | | `MNEMA_HTTP_HOST` | `127.0.0.1` | HTTP绑定主机 | | `MNEMA_HTTP_PORT` | `8000` | HTTP绑定端口 | --- ## 🗄️ 选择后端 | 后端 | 安装额外功能 | 嵌入式？ | 最适合 | |---|---|---|---| | **Chroma** (默认) | `chroma` | ✅ 进程内 + 持久化 | 快速启动，单用户，开发 | | **Qdrant** | `qdrant` | ✅ 本地路径 / `:memory:` / 远程 | 生产，高规模，元数据过滤 | | **sqlite-vec** | `sqlite_vec` | ✅ 纯SQLite | 最小占用空间，约束环境 | 通过使用正确的额外功能重新安装并设置环境变量来切换后端： ```bash curl -fsSL https://raw.githubusercontent.com/mienetic/mnema/main/scripts/install.sh \ | MNEMA_EXTRAS="qdrant,local" bash export MNEMA_BACKEND=qdrant mnema --doctor ``` 参阅 [docs/backends.md](docs/backends.md) 以获取详细内容。 --- ## 🧠 嵌入提供商 | 提供商 | 安装额外功能 | 模式 | 维度 | |---|---|---|---| | **sentence-transformers** (默认) | `local` | 离线（CPU/GPU） | 384 (`all-MiniLM-L6-v2`) | | **OpenAI** | `openai` | API（需要密钥） | 1536 (`text-embedding-3-small`) | ```bash curl -fsSL https://raw.githubusercontent.com/mienetic/mnema/main/scripts/install.sh \ | MNEMA_EXTRAS="chroma,openai" bash export MNEMA_EMBEDDING=openai export MNEMA_OPENAI_API_KEY=sk-... mnema --doctor ``` 参阅 [docs/embedding-providers.md](docs/embedding-providers.md) 获取模型选项。 --- ## 🧪 开发 ```bash git clone https://github.com/mienetic/mnema.git cd mnema/packages/mnema-python # 使用开发依赖项 + 所有后端安装 uv venv --python 3.11 .venv VIRTUAL_ENV=.venv uv pip install -e '.[all,dev]' # 运行测试（跳过依赖项缺失的后端） pytest # 运行特定后端的测试，安装其额外功能后 pytest -m chroma # lint + 类型检查 ruff check . mypy src/mnema ``` ### 交互式测试服务器 ```bash npx @modelcontextprotocol/inspector uv run mnema ``` 这将打开MCP Inspector Web UI，您可以在其中调用每个工具。 --- ## 🐳 Docker ```bash docker compose -f docker/docker-compose.yml up mnema # 流式HTTP位于 http://localhost:8000/mcp ``` 参阅 [`docker/`](docker/) 获取Dockerfile和compose设置。 --- ## 📦 项目布局 ``` mnema/ ├── packages/ │ ├── mnema-python/ # ⭐ MCP服务器 + SDK（Python） │ │ ├── src/mnema/ │ │ │ ├── backends/ # chroma, qdrant, sqlite_vec │ │ │ ├── embeddings/ # sentence_transformers, openai │ │ │ ├── tools/ # 10个MCP工具 │ │ │ ├── service.py # 协调 │ │ │ ├── decay.py # 遗忘曲线 │ │ │ ├── summarize.py # 总结计划器 │ │ │ ├── sdk.py # 编程SDK │ │ │ └── server.py # FastMCP启动 │ │ └── tests/ │ ├── mnema-ts/ # TypeScript MCP服务器（计划中） │ └── mnema-cli/ # Node CLI（计划中） ├── docker/ # Dockerfile + compose ├── docs/ # 架构，后端，部署 ├── examples/ # 客户端配置示例 ├── SKILL.md # 面向代理的用法指南 └── README.md ``` --- ## 🤝 工作原理 ``` ┌──────────────┐ MCP ┌──────────────────┐ │ AI 客户端 │◄──────────►│ Mnema 服务器 │ └──────────────┘ (stdio/ │ ┌────────────┐ │ HTTP) │ │ 10 个工具 │ │ │ └──────┬─────┘ │ │ ┌──────▼─────┐ │ │ │ 服务 │ │ │ └──┬─────┬───┘ │ │ ┌────▼─┐ ┌─▼────┐ │ │ │ 嵌入 │ │ 向量 │ │ │ └──┬───┘ └──┬───┘ │ └────┼─────────┼────┘ │ │ 句子转换器 │ Chroma/Qdrant/ （本地） │ sqlite-vec │ 矢量 + 元数据 ``` 每个记忆都会嵌入，存储在作用域/标签/重要性旁边，并通过以下方式在检索时排名： ``` score = 0.7·vector + 0.2·keyword + 0.1·decay ``` 其中 `decay = recency(half-life) × frequency × importance`. --- ## 🗺️ 路线图 - [x] Python MCP服务器（FastMCP） - [x] Chroma / Qdrant / sqlite-vec 后端 - [x] 本地 + OpenAI 嵌入 - [x] 带有衰减的混合搜索 - [x] 总结计划器 - [x] 编程Python SDK - [ ] TypeScript MCP服务器（原生Node运行时） - [ ] CLI (`mnema add`, `mnema recall`, …) - [ ] 内存浏览网页仪表盘 - [ ] 评估框架 (`docs/evaluations.xml`) --- ## 📄 许可证 [MIT](LICENSE) © Mnema Contributors. ## 🙏 致谢 - [模型上下文协议](https://modelcontextprotocol.io) — 使本项目成为可能的协议。 - [ChromaDB](https://www.trychroma.com/)，[Qdrant](https://qdrant.tech/)，[sqlite-vec](https://github.com/asg017/sqlite-vec) — 优秀的开源向量存储。 - [sentence-transformers](https://www.sbert.net/) — 为每个人提供离线嵌入。