mnemosyne-mcp

AI Agent 记忆管理 MCP Server — 分层记忆 · 时间衰减 · 关键词检索 · 知识图谱

为 Claude Desktop / Cursor / Windsurf 等 MCP 客户端提供结构化记忆能力。基于 Mnemosyne 架构设计，走本地优先、SQLite + 知识图谱路线。

记忆层级: session (会话级) → global (全局共享)，经 sleep() 归档
检索:     hybrid 评分 (BM25 词频 + 重要性 + 可选时间衰减)
图谱:     subject-predicate-object 三元组 + 多跳 BFS
归档:     sleep() 把低重要性 session 记忆提升为 global/episodic

说明：当前实现是两级 scope（session / global），不是三���记忆。 检索是纯 BM25 + 加权，未接入向量嵌入（embeddings 附加依赖为 规划中能力）。详见 ROADMAP.md。

---

与 mem0 的差异

特性	mem0	mnemosyne-mcp
存储	需 Qdrant / PGVector	纯 SQLite，零外部服务
检索	embedding API	纯 BM25 + 重要性 + 时间衰减（无向量库依赖）
知识图谱	实体链接	三元组 + 时序 + 多跳 BFS
部署	需 Docker / 服务端	单文件 pip install 即用
数据所有权	云端可选	本地 SQLite 文件，100% 可控

---

快速开始

# 安装
pip install mnemosyne-mcp

# 初始化记忆库
mnemosyne-mcp init --path ~/.mnemosyne/data

# 启动 MCP Server (stdio)
mnemosyne-mcp serve

# 或 SSE 模式（本地回环）
mnemosyne-mcp serve --transport sse --port 8080

Claude Desktop 配置

{
  "mcpServers": {
    "mnemosyne": {
      "command": "mnemosyne-mcp",
      "args": ["serve"]
    }
  }
}

---

核心 API

记忆操作

工具	说明
mnemosyne_remember	写入记忆（user/feedback/project/reference，支持 importance / temporal_halflife）
mnemosyne_recall	关键词检索（BM25 + 重要性 + 可选时间衰减加权）
mnemosyne_get	按 ID 精确读取
mnemosyne_update	更新已有记忆
mnemosyne_forget	按 ID 删除
mnemosyne_invalidate	标记过期/被取代
mnemosyne_validate	多方验证（attest / update / invalidate / delete）

知识图谱

工具	说明
mnemosyne_triple_add	写入三元组 (subject, predicate, object)
mnemosyne_triple_query	图谱查询（支持 as_of 历史回溯）
mnemosyne_triple_end	过期三元组（不删除，保留审计链路）
mnemosyne_graph_link	显式声明记忆间的语义边
mnemosyne_graph_query	多跳 BFS 遍历（max_hops / min_weight）

记忆管理

工具	说明
mnemosyne_sleep	运行 consolidate 周期（旧 working → episodic 摘要）
mnemosyne_scratchpad_write	临时便签（进程级，不持久化）
mnemosyne_scratchpad_read	读取临时便签
mnemosyne_scratchpad_clear	清空临时便签
mnemosyne_hygiene_audit	审计噪声（terminal spam / secret / stack trace）
mnemosyne_hygiene_clean	清理噪声（delete / archive / flag）
mnemosyne_stats	记忆库统计（working / episodic / triples / graph_edges）
mnemosyne_sync_pull	从远程同步服务器拉取记忆 ⚠️ 占位实现
mnemosyne_sync_push	推送本地记忆到远程 ⚠️ 占位实现

工具总数 21。其中 mnemosyne_sync_pull / mnemosyne_sync_push 目前是占位实现（直接返回提示信息，不做实际同步）—— 远程同步服务端尚未提供，见 ROADMAP.md。

批量操作

from mnemosyne_mcp import MnemosyneClient

client = MnemosyneClient(path="~/.mnemosyne/data/mnemosyne.db")

# 批量写入 —— 单个事务，全有或全无
results = client.batch([
    {"action": "remember", "content": "用户偏好 Python", "scope": "global", "importance": 0.9},
    {"action": "triple_add", "subject": "user", "predicate": "prefers", "object": "Python"},
    {"action": "graph_link", "source_id": "...", "target_id": "...", "relationship": "references"},
])

支持的 action：remember / triple_add / graph_link / update / forget。

原子性：任一条操作失败，整批回滚并抛出异常，不会留下半截数据。 半截导入比完全失败更难收拾 —— 这正是批量场景下最需要的行为。

---

Python 直接使用（无需 MCP）

from mnemosyne_mcp import MnemosyneClient

client = MnemosyneClient(path="./my_memory.db")

# 写入
mem_id = client.remember(
    content="用户喜欢简洁的代码风格",
    memory_type="user",
    scope="global",
    importance=0.8,
)

# 检索
results = client.recall("代码风格偏好", limit=5)

# 知识图谱
client.triple_add("user", "prefers", "Python", confidence=1.0)
graph = client.graph_query(seed_id=mem_id, max_hops=2)

# 记忆归档
client.sleep(force=True)

💡 mnemosyne_mcp.client 保留为兼容别名（0.2.0 起实现合并进 mnemosyne_mcp.core），旧代码 from mnemosyne_mcp.client import MnemosyneClient 仍可正常工作。新代码请直接 from mnemosyne_mcp import MnemosyneClient。

---

架构

mnemosyne-mcp/
├── src/mnemosyne_mcp/
│   ├── __init__.py      # 公共 API 导出
│   ├── core.py          # 客户端 + MCP Server + 工具路由（0.2.0 起合并）
│   └── client.py        # 兼容别名模块（转发到 core）
├── tests/
│   ├── conftest.py
│   ├── test_client.py
│   └── test_tools.py
├── examples/
│   ├── basic_usage.py
│   └── knowledge_graph.py
└── .github/
    ├── workflows/ci.yml
    └── ISSUE_TEMPLATE/

依赖: mcp >= 1.0.0（协议层）+ Python 标准库 sqlite3

全部存储与检索基于 Python 标准库 sqlite3，不依赖任何向量数据库。 可选的 embeddings / sse / sqlite-vec 附加依赖按需安装： pip install "mnemosyne-mcp[sse]"

---

数据安全

• 所有记忆存储在本地 SQLite 文件，不上传任何云端
• 支持 MNEMOSYNE_DATA_DIR 环境变量自定义存储路径
• SSE 模式默认绑定 loopback，LAN 暴露必须设置 MNEMOSYNE_MCP_TOKEN
• mnemosyne_hygiene_clean 默认是 dry-run，必须显式 confirm=True 才会真删

⚠️ 记忆库是明文 SQLite 文件，不含加密。存放敏感信息前请自行 使用加密卷或文件系统权限保护，详见 SECURITY.md。

---

License

Apache-2.0