AxDSan/mnemosyne

## 目录 - [适用于一切](#works-with-everything) - [快速开始](#quick-start) - [添加到您的代理](#add-to-your-agent) - [基准测试](#benchmark) - [CLI 使用](#cli-usage) - [Python API](#python-api) - [BEAM 直接访问](#advanced-beam-direct-access) - [架构](#architecture) - [为什么选择 Mnemosyne？](#why-mnemosyne) - [配置](#configuration) - [环境变量](#environment-variables) - [Hermes 插件（23个工具）](#hermes-plugin-23-tools) - [贡献](#contributing) - [支持](#support) - [许可](#license) ## 适用于一切 | 平台 | 方法 | 设置 | |----------|--------|-------| | **Cursor** | MCP | 添加到 `.cursor/mcp.json` | | **Claude Code** | MCP | 添加到 `claude.json` | | **OpenAI Codex CLI** | MCP | 添加到 `.codex/mcp.json` | | **Windsurf** | MCP | 添加到 `.windsurf/mcp_config.json` | | **OpenWebUI** | 本地 @tool | 将桥接文件放入 `data/tools/` | | **OpenClaw** | 本地提供者 | `pip install mnemosyne-memory[openclaw]` | | **Hermes 代理** | MCP + 插件 | 本地 — 随附启用 | | **任何 MCP 客户端** | MCP (stdio/SSE) | 一行配置 | | **任何 Python 代理** | 直接 SDK | `import mnemosyne` | 有关每个平台的完整设置指南，请参阅 [docs/integrations/](docs/integrations/README.md.) ## 快速开始 ``` pip install mnemosyne-memory # With all features (vector search + MCP server) pip install "mnemosyne-memory[all]" # Upgrade pip install --upgrade mnemosyne-memory ``` ### 添加到您的代理 **基于 MCP**（Cursor、Claude Code、Codex、Windsurf）： ``` { "mcpServers": { "mnemosyne": { "command": "mnemosyne", "args": ["mcp"], "env": {} } } } ``` **Python SDK**（任何代理）： ``` from mnemosyne import remember, recall remember("User prefers dark mode interfaces") results = recall("user preferences") ``` **OpenWebUI**：将一行桥接文件放入 `data/tools/`。 **OpenClaw**：将 `provider: mnemosyne.integrations.openclaw:create_provider` 添加到配置中。 ## 基准测试 Mnemosyne 在两个主要的记忆基准测试中均取得了顶级成绩，**LongMemEval**（ICLR 2025）和 **BEAM**（ICLR 2026），都在一个 SQLite 文件中，零云依赖。 ### LongMemEval（检索） | 系统 | 分数 | 备注 | |--------|-------|-------| | **Mnemosyne（密集型）** | **98.9% Recall@All@5** | 2026年4月，bge-small-en-v1.5，100个实例 | | Mempalace | 96.6% Recall@5 | AAAK + Palace 架构 | | Backboard | 93.4% | 独立评估 | | Hindsight | 91.4% | Vectorize.io | ### BEAM（端到端 QA） | 规模 | Mnemosyne v3 | Honcho | Hindsight | LIGHT | RAG | |-------|-------------|--------|-----------|-------|-----| | **100K** | **65.2%** | 63.0% | 73.4% | 35.8% | 32.3% | 每项能力（100K）：IE 91.5% · MR 87.5% · TR 75.0% · ABS 100.0% · CR 50.0% · KU 50.0% · EO 25.0% · IF 62.5% · PF 54.5% · SUM 55.6% ### BEAM 检索（纯召回） | 规模 | Recall@10 | 延迟 | 存储 | 消息 | |-------|-----------|---------|---------|----------| | 100K | 20% | 372ms | 1.8 MB | 200 | | 500K | 20% | 412ms | 3.2 MB | 1,000 | | 1M | 20% | 493ms | 4.8 MB | 2,000 | | **10M** | **20%** | **35ms** | **7.2 MB** | **20,000** | 召回在所有规模上保持平坦。**100% 拒绝准确率**，从不对未知事物进行幻觉。事件压缩提供 9.4 倍的存储节省。 完整报告：[docs/beam-benchmark.md](docs/beam-benchmark.md) ## CLI 使用 ``` # MCP server (works with any MCP client) mnemosyne mcp # stdio (default) mnemosyne mcp --transport sse --port 8080 # SSE (web clients) # Direct memory ops mnemosyne remember "User likes dark mode" mnemosyne recall "preferences" mnemosyne stats mnemosyne sleep # Run consolidation # Export / import mnemosyne export --output backup.json mnemosyne import --input backup.json ``` ## Python API ``` from mnemosyne import remember, recall # Store a fact remember("User prefers dark mode interfaces", importance=0.9, source="preference") # Store globally (visible across all sessions) remember("User email is user@example.com", importance=0.95, scope="global") # Store with expiry remember("Temp token: abc123", importance=0.8, valid_until="2026-12-31") # Search results = recall("interface preferences", top_k=3) # Temporal recall (recency boost) results = recall("deployments", temporal_weight=0.5, temporal_halflife=48.0) # Entity extraction remember("Met with Abdias about the v2 release", extract_entities=True) # LLM-driven fact extraction remember("User said they prefer Python for backend work", extract=True) # Temporal triples (knowledge graph) from mnemosyne.core.triples import TripleStore kg = TripleStore() kg.add("Maya", "assigned_to", "auth-migration", valid_from="2026-01-15") kg.query("Maya", as_of="2026-02-01") # Memory banks (per-domain isolation) from mnemosyne.core.banks import BankManager BankManager().create_bank("work") work_mem = Mnemosyne(bank="work") work_mem.remember("Sprint review on Friday") ``` ## 高级：BEAM 直接访问 ``` from mnemosyne.core.beam import BeamMemory beam = BeamMemory(session_id="my_session") beam.remember("Important context", importance=0.9) beam.consolidate_to_episodic( summary="User likes Neovim", source_wm_ids=["wm1"] ) results = beam.recall("editor preferences", top_k=5) ``` ## 架构 ``` ┌────────────────────────────────────────────────────────────┐ │ Any AI Agent │ │ (Hermes · Claude Code · Cursor · Codex · OpenWebUI · MCP) │ └────────────────────────┬───────────────────────────────────┘ │ MCP / SDK / Plugin ┌────────────────────────▼───────────────────────────────────┐ │ Mnemosyne BEAM │ │ ┌────────────┐ ┌──────────────┐ ┌────────────────────┐ │ │ │ Working │ │ Episodic │ │ TripleStore │ │ │ │ Memory │──▶│ Memory │ │ (Temporal KG) │ │ │ │ (hot ctx) │ │ (long-term) │ └────────────────────┘ │ │ └────────────┘ └──────┬───────┘ │ │ │ │ │ ┌──────────▼──────────┐ │ │ │ SQLite DB │ │ │ │ (single file) │ │ │ │ sqlite-vec + FTS5 │ │ │ │ MIB binary vectors │ │ │ └─────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` **BEAM**（双级事件关联记忆）： - **工作记忆** — 热上下文，在 LLM 调用之前自动注入，基于 TTL 清除 - **事件记忆** — 长期存储，使用 sqlite-vec + FTS5 混合搜索 - **三元组存储** — 带版本链的时间知识图 **混合评分**：50% 向量相似度 + 30% FTS5 排名 + 20% 重要性，全部在 SQLite 内部。 **二进制向量**：信息论二值化（MIB）将 384 维 float32 嵌入压缩到 48 字节 — 32 倍减少。汉明距离完全在 SQLite 内部。没有 ANN 索引，没有外部向量数据库。 ## 为什么选择 Mnemosyne？ | 特性 | Mnemosyne | mem0 | Letta | Honcho | SuperMemory | Hindsight | ChromaDB | |---------|-----------|------|-------|--------|-------------|-----------|----------| | **本地优先** | ✅ SQLite | ⚠️ 混合 | ❌ Docker+PG | ⚠️ PG+worker | ❌ SaaS | ✅ SQLite | ✅ 嵌入式 | | **零依赖** | ✅ pip only | ❌ Qdrant/PG | ❌ PG+vector | ❌ PG+3 LLMs | ❌ SaaS 基础设施 | ✅ pip only | ✅ pip only | | **MCP 服务器** | ✅ 内置 | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | | **Python SDK** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **多平台** | ✅ 8+ 目标 | ⚠️ 3 适配器 | ❌ 代理仅限 | ⚠️ 4 适配器 | ✅ MCP | ❌ 代理仅限 | ❌ 库仅限 | | **开源** | ✅ MIT | ✅ Apache 2.0 | ✅ OSS | ⚠️ AGPL | ❌ 商业软件 | ✅ MIT | ✅ Apache 2.0 | | **基准测试** | **65.2% BEAM / 98.9% LongMem** | 49% LongMem | 83.2% LoCoMo | **90.4% LongMem** | 85.2% MemoryBench | 73.4% BEAM | N/A（向量数据库）| | **自托管** | ✅ 是 | ✅ 可选 | ✅ 可选 | ✅ 是 | ❌ 企业 | ✅ 是 | ✅ 是 | | **集成模板** | ✅ 已发布 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | **记忆架构** | BEAM（3层） | 会话 + 事实 | OS 虚拟上下文 | 对等 + 推理 | 5 层堆栈 | 事件 + 语义 | 仅向量存储 | | **目的** | 完整记忆系统 | 记忆 API | 代理运行时 | 管理内存 | 消费者 + 代理 | 研究记忆 | 向量数据库 | ## 配置 ### 环境变量 | 变量 | 默认 | 描述 | |----------|---------|-------------| | `MNEMOSYNE_DATA_DIR` | `~/.hermes/mnemosyne/data` | 数据库目录 | | `MNEMOSYNE_VEC_TYPE` | `int8` | 向量压缩：`float32`、`int8` 或 `bit` | | `MNEMOSYNE_VEC_WEIGHT` | `0.5` | 向量相似度权重 | | `MNEMOSYNE_FTS_WEIGHT` | `0.3` | FTS5 关键字权重 | | `MNEMOSYNE_IMPORTANCE_WEIGHT` | `0.2` | 重要性权重 | | `MNEMOSYNE_WM_MAX_ITEMS` | `10000` | 工作记忆限制 | | `MNEMOSYNE_RECENCY_HALFLIFE` | `168` | 衰减半衰期（小时）| | `MNEMOSYNE_EMBEDDING_API_URL` | `${OPENROUTER_BASE_URL:-https://openrouter.ai/api/v1}` | 自定义嵌入 API 端点的首选名称（与 OpenAI 兼容）。回退到 `OPENROUTER_BASE_URL`。 | | `MNEMOSYNE_EMBEDDING_API_KEY` | `${OPENROUTER_API_KEY:-${OPENAI_API_KEY:-}}` | 嵌入 API 密钥的首选名称。回退到 `OPENROUTER_API_KEY`，然后 `OPENAI_API_KEY`。 | | `MNEMOSYNE_EMBEDDING_MODEL` | `BAAI/bge-small-en-v1.5` | 嵌入模型。低资源多语言：`sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`；更大的选项：`intfloat/multilingual-e5-base`、`BAAI/bge-m3`。 | 完整参考：[docs/configuration.md](docs/configuration.md) ### 语言支持 默认嵌入是针对英语优化的（`bge-small-en-v1.5`）。对于 **非英语或多语言** 检索，请更换模型： ``` # Low-resource local multilingual embeddings export MNEMOSYNE_EMBEDDING_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 # Larger multilingual embeddings export MNEMOSYNE_EMBEDDING_MODEL=intfloat/multilingual-e5-base # Or Chinese-specific embeddings export MNEMOSYNE_EMBEDDING_MODEL=BAAI/bge-small-zh-v1.5 ``` 有关权衡（RAM、速度、维度变化）的详细信息，请参阅 [docs/configuration.md#custom-embedding-models](docs/configuration.md#custom-embedding-models.) ## Hermes 插件（23个工具） 当与 Hermes 代理一起使用时，Mnemosyne 提供了 **23个工具** 用于完整的记忆生命周期管理 — 3 个生命周期钩子（`pre_llm_call`、`on_session_start`、`post_tool_call`）用于自动上下文注入，以及 MCP 支持。 **安装（Hermes 用户）：** ``` pip install mnemosyne-hermes hermes config set memory.provider mnemosyne hermes memory setup ``` 然后禁用 Hermes 内置的文件内存以避免重复： ``` hermes tools disable memory ``` 有关完整设置指南，请参阅 [docs/hermes-integration.md](docs/hermes-integration.md). ### 工具类别 | 类别 | 工具 | |---|---| | **核心记忆**（9个） | `remember`、`recall`、`sleep`、`stats`、`get`、`update`、`forget`、`invalidate`、`validate` | | **知识图谱**（4个） | `triple_add`、`triple_query`、`graph_query`、`graph_link` | | **多代理界面**（4个） | `shared_remember`、`shared_recall`、`shared_forget`、`shared_stats` | | **工作笔记**（3个） | `scratchpad_write`、`scratchpad_read`、`scratchpad_clear` | | **操作**（3个） | `export`、`import`、`diagnose` | 所有 23 个工具都通过 `mnemosyne-hermes` 包公开，该包封装了 `mnemosyne-memory` 核心库。`integrations/hermes/` 中的插件清单也可由 Hermes 的插件系统发现。 **更新**：`pip install --upgrade mnemosyne-hermes && hermes gateway restart` 或 `git pull && pip install --upgrade integrations/hermes && hermes gateway restart`（源）。 ## 贡献 有关指南，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md). 完整文档：[`docs/`](docs/README.md) · 更新日志：[`CHANGELOG.md`](CHANGELOG.md) · 发布：[GitHub 发布](https://github.com/AxDSan/mnemosyne/releases) · 集成：[docs/integrations/](docs/integrations/README.md) ## 许可 MIT 许可证 — 查看 [LICENSE](LICENSE) 版权所有 (c) 2026 Abdias J

"最淡的墨水也比最强的记忆更有力量。" — 赫耳墨斯·特里梅吉斯托斯

标签：AI 记忆, API, BEAM 基准, CLI, Discord 社区, Hermes 代理, MCP 协议, MIT 许可, OpenClaw, OpenWebUI, ProductHunt, PyPI, Python, SQLite, WiFi技术, 人工智能, 内存管理, 内存系统, 开源框架, 快速启动, 持续集成, 无后门, 架构设计, 模型上下文协议, 用户模式Hook绕过, 逆向工具, 零依赖