MnemosyneOS/mnemosyne

mnemosyne OS

PyPI ·
GitHub ·
中文

Mnemosyne OS 8.0.0 — 一个零依赖、本地优先的 AI 记忆系统。图记忆、多模态摄取、重排序、时间推理、哈希链式审计账本、无损压缩，以及 31 个 MCP 工具。

唯一一个核心真正零第三方依赖的 AI 记忆引擎——无需向量数据库、无需 LLM 运行时、无需云账户。
install_requires 是一个空列表。它同样可以运行在笔记本电脑、服务器或无服务器基础设施上。

你可以将其用作 Python 库、CLI、HTTP API 或 MCP 服务器。

🚀 快速开始

安装

pip install mnemosyne-os          # 核心：零第三方依赖

无需任何配置即可记忆和回忆

from mnemosyne import Memory
m = Memory()                       # 内置嵌入器 + 基于规则的提取器
m.add("I prefer dark mode and use vim keybindings. My name is Alice.",
user_id="alice")

for hit in m.search("what does alice prefer", filters={"user_id": "alice"})["results"]:
print(f"{hit['score']:.3f}  {hit['memory']}")

离线运行，无需 API 密钥，无需下载模型，无需安装数据库——这正是下一节得以实现的原因。

仅在召回需要更强时才接入真实模型
python
from mnemosyne import Memory

m = Memory.from_config({
"llm":          {"provider": "openai", "config": {"model": "gpt-4o-mini"}},
"embedder":     {"provider": "openai", "config": {"model": "text-embedding-3-small"}},
"vector_store": {"provider": "qdrant", "config": {"url": "http://localhost:6333"}},
"reranker":     {"provider": "cohere", "config": {"api_key": "..."}},
"graph_store":  {"provider": "builtin"},
})

每个组件都是独立可选的。当某个提供者无法构建时，它会回退到内置的等效实现，并且会明确说明——不会有任何静默降级：
python
m.describe()["degraded"]
{'llm': {'requested': 'openai', 'used': 'rules', 'reason': 'no API key configured',
'hint': 'Set MNEMOSYNE_LLM_OPENAI_API_KEY ...'}}

或者从命令行驱动它
bash
mnemosyne init
mnemosyne add "I prefer dark mode and vim keybindings" --user-id alice
mnemosyne search "what does alice prefer" --user-id alice
mnemosyne list  --user-id alice
mnemosyne event --limit 10
mnemosyne --agent search "preferences" --user-id alice   # JSON envelope for tool loops

或者通过 MCP 暴露它
json
{
"mcpServers": {
"mnemosyne": {
"command": "python",
"args": ["-m", "mnemosyne.webui.mcp_server",
"--brain-dir", "./mem", "--namespace", "default"],
"env": { "MNEMOSYNE_MCP_TOKEN": "" }
}
}
}

或者通过 HTTP 提供服务
bash
mnemosyne-web --port 9090          # console and REST share one port
curl -X POST http://127.0.0.1:8788/v3/memories/add/ \
-H "Authorization: Bearer $MNEMOSYNE_API_KEY" -H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"I moved to Berlin in 2023."}],"user_id":"alice"}'

📊 基准测试

使用本仓库附带的测试工具进行测量。可通过
scripts/verify_recall_quality.py 和 scripts/verify_precision_recall.py 复现。

| 基准测试 | 得分 | 衡量内容 |
| --- | --- | --- |
| LongMemEval | 96.2 | 长时程对话召回 |
| LoCoMo | 94.8 | 多会话对话记忆 |
| BEAM (1M) | 68.5 | 1M token 上下文预算下的召回 |
| BEAM (10M) | 53.9 | 10M token 上下文预算下的召回 |

得分满分均为 100。

🧩 能力

Memory APIMemory / AsyncMemory / MemoryClient，拥有完整的方法接口：add get get_all search update delete delete_all history reset close from_config。
四维作用域user_id / agent_id / run_id / app_id —— 通过物理隔离强制执行：每个作用域一个 SQLite 文件，而不是共享行再施加过滤条件。
过滤语言eq ne gt gte lt lte in nin contains icontains wildcard，支持任意嵌套的 AND/OR/NOT。
单遍仅追加提取每次写入仅调用一次模型；记忆不断累积，从不被覆盖。由于不会重写任何内容，糟糕的提取只会引入噪声——它永远无法破坏真实的事实。
图记忆，始终开启实体链接与多跳遍历都存放在同一个 SQLite 文件中。无需外部图数据库。
多模态摄取接受 OpenAI、Anthropic 和 Gemini 的图像内容格式（以及音频）。配置了视觉模型时，它会存储描述；未配置时，它会存储引用——不会丢弃任何内容。
多信号检索语义 + BM25 关键词 + 实体图 + 时间 + 标签，通过校准的相关性下限和词汇回退进行融合。
时间推理观察日期、相对时间解析、过期语义，以及按实体的版本链。
分层记忆热 / 温 / 冷层级，配合遗忘经济学：低价值记忆会被降级和压缩，绝不会被静默删除。
无损压缩（AIC）将记忆压缩为指针 + 结构化事实 + 内容原子。数字、日期、金额和型号在每个层级都能保留；expand() 可逐字节恢复原始文本并校验其哈希。
哈希链式审计账本一条 SHA-256 链；verify_integrity() 可检测篡改并指出发生更改的确切条目。
异步 API 与事件AsyncMemory 用于高吞吐写入，外加持久化的操作日志，使已接受的写入在跨进程时仍然可见。
中文优化二元分词 + FTS5 + 内置同义词词典，并完全支持拉丁字母文字。
安全公证器在写入落地前检测凭据、不可见 Unicode 和 HTML 注入，并在字段级别进行脱敏。

🔌 集成

每个适配器都是可选的。stdlib 适配器完全不需要第三方包
——它们直接通过 urllib 使用 HTTP。sdk 适配器会延迟导入其 SDK，
并明确告诉你缺少哪个包。

LLM 提供商（20）

| 传输方式 | 提供商 |
| --- | --- |
| stdlib HTTP | openai openai_structured azure_openai azure_openai_structured ollama anthropic gemini groq together deepseek minimax xai sarvam openrouter litellm lmstudio vllm |
| sdk | langchain aws_bedrock |
| 内置 | rules —— 一个确定性的离线提取器，这就是为什么在完全没有配置模型的情况下 add() 也能工作 |

嵌入器（13）

| 传输方式 | 提供商 |
| --- | --- |
| stdlib HTTP | openai azure_openai ollama gemini vertexai together lmstudio huggingface |
| sdk | fastembed langchain aws_bedrock |
| 内置 | builtin（128 维、零依赖、确定性）· hashing（任意维度、离线） |

向量存储（28）

| 传输方式 | 存储 |
| --- | --- |
| 嵌入式 | builtin（一个 SQLite 文件同时保存记忆和向量）· memory · generic（声明式 REST） |
| stdlib HTTP | qdrant pinecone elasticsearch opensearch weaviate upstash_vector turbopuffer |
| sdk | chroma pgvector milvus mongodb redis valkey azure_ai_search azure_mysql baidu cassandra databricks faiss langchain neptune oracledb s3_vectors supabase vertex_ai_vector_search |

图存储（6）

builtin（原生 SQLite 三元组）· neo4j · memgraph · neptune · kuzu · sparql（任意 SPARQL 1.1 端点）

重排序器（5）

llm · cohere · zero_entropy · huggingface · sentence_transformer

框架适配器

LangChain · LlamaIndex · CrewAI · Dify · n8n · Vercel AI SDK · Ollama · MCP（stdio + Streamable HTTP）

🛠 MCP 服务器

通过 stdio JSON-RPC 运行：
bash
export MNEMOSYNE_MCP_TOKEN="your-secret-token"   # optional, but recommended
python -m mnemosyne.webui.mcp_server --brain-dir ./mem --namespace default

31 个工具 —— 二十个原生工具，加上十一个复用常规
agent-memory 工具名称的工具，因此现有的 MCP 客户端可以指向 Mnemosyne，
而无需重写其工具定义。

原生（20）：

| 工具 | 用途 |
| --- | --- |
| retain | 存储一条记忆 |
| recall | 检索记忆 |
| retain_batch | 批量写入，大约快 15 倍 |
| forget | 遗忘一条记忆 —— 按 id，或通过自然语言查询定位它 |
| capsule | 将一条记忆压缩为指针 + 事实 + 原子 |
| expand | 逐字节恢复胶囊的原始文本 |
| recall_health | 只读的召回质量指标 |
| consolidate | 将近重复的记忆合并为一个代表 |
| reflect | 统计信息、频繁实体、冲突检测、认知模式 |
| dedup | 检测重复项和近似重复项 |
| graph_query | 知识图谱遍历 |
| temporal_query | 版本链查询 |
| list_projects | 列出隔离的项目 |
| doctor | 健康检查——完整性、计数、磁盘、后端状态 |
| stats | 运行时统计信息 |
| audit | 审计链查询 |
| confidence_history | 置信度轨迹 |
| memory/export-v1 | 通过 Memory Exchange Protocol 导出 |
| memory/import-v1 | 通过 Memory Exchange Protocol 导入 |
| memory/claim | 从外部导出中接管记忆 |

客户端兼容（11 个）：

| 工具 | 用途 |
| --- | --- |
| add_memory | 为用户/代理保存文本或对话历史 |
| search_memories | 带过滤条件的语义搜索 |
| get_memories | 结构化过滤 + 分页列表 |
| get_memory | 按 id 获取单条记录 |
| update_memory | 覆盖文本和/或元数据 |
| delete_memory | 删除单条记录 |
| delete_all_memories | 清空某个作用域 |
| delete_entities | 删除实体并级联删除 |
| list_entities | 列出用户/代理/应用/运行实例 |
| list_events | 列出记忆操作 |
| get_event_status | 轮询异步操作 |

🌐 自托管 REST API

单进程、单端口，接受 X-API-Key、Bearer 和 Token 认证头。
控制台和 API 共享同一个监听器。

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | /v1/status/ | 存活探测 + 实时配置报告 |
| GET | /v1/providers/ | 每个提供者及其当前可用性 |
| POST | /v3/memories/add/ | 提取并存储（异步，返回事件 id） |
| POST | /v3/memories/search/ | 语义搜索 |
| POST | /v3/memories/get-all/ | 过滤列表 |
| GET / PUT / DELETE | /v3/memories/{id}/ | 获取 / 更新 / 删除单条记录 |
| DELETE | /v3/memories/ | 清空某个作用域 |
| GET | /v3/memories/{id}/history/ | 变更历史 |
| GET | /v1/event/{id}/ · /v1/events/ | 轮询 / 列出操作 |
| GET / DELETE | /v2/entities/ | 列出 / 删除作用域 |
| POST | /v3/graph/{add,search,get-all,delete-all}/ | 图谱记忆 |
| POST | /v1/capsule/ · /v1/expand/ | 无损压缩 |
| GET | /v1/integrity/ | 账本验证 |
| GET / POST / DELETE | /v1/keys/ | API 密钥管理 |

🧠 Python API
python
from mnemosyne import Memory, AsyncMemory, MemoryClient

--- extraction / scope / filters ---------------------------------------------
m = Memory()
m.add([{"role": "user", "content": "I moved to Berlin in 2023."}],
user_id="alice", metadata={"source": "onboarding"},
observation_date="2023-06-01")
m.add("The invoice number is INV-2024-001.", user_id="alice", immutable=True)

hits = m.search("where does the user live",
filters={"user_id": "alice",
"AND": [{"source": {"eq": "onboarding"}}]},
top_k=5, threshold=0.1, rerank=False, explain=True)

--- 多模态 ---------------------------------------------------------------
m.add([{"role": "user", "content": [
{"type": "text", "text": "My new desk."},
{"type": "image_url", "image_url": {"url": "https://example.com/desk.jpg"}},
]}], user_id="alice")

--- 图记忆 -------------------------------------------------------------
m.graph_add("Jobs founded Apple in Cupertino.", user_id="alice")
m.graph_search("Apple", filters={"user_id": "alice"})

--- 异步与事件 ---------------------------------------------------------
async def ingest():
am = AsyncMemory()
await am.add_many([{"messages": t, "options": {"user_id": "alice"}}
for t in transcripts])

Memory、AsyncMemory 和 MemoryClient 也接受其他记忆库所使用的
传统智能体记忆调用形式，因此已按该形式编写的代码只需更改导入即可切换。参见
docs/COMPATIBILITY.md。

引擎自身的能力也挂载在同一对象上：
python
from mnemosyne import MemoryBrain

brain = MemoryBrain("./memories", enable_embeddings=True)
brain.ensure_init()
brain.retain("His laptop is an ASUS VivoBook Pro 14", fast=True)

results = brain.recall("what are that machine's specs", k=5)
results, cost = brain.recall("that machine's specs", k=5, budget_tokens=100)

cap = brain.capsule("", budget_tokens=60)   # pointer + facts + atoms
brain.expand(cap["ref"])                                # byte-exact recovery
brain.verify_integrity()                                # SHA-256 ledger check

📂 目录结构

mnemosyne/
├── api/                 # 记忆 API：Memory / AsyncMemory / MemoryClient
│   ├── memory.py        #   由引擎支持的客户端
│   ├── config.py        #   MemoryConfig + 维度一致性检查
│   ├── filters.py       #   过滤语言 -> 谓词
│   ├── extract.py       #   单遍仅 ADD 的提取
│   ├── multimodal.py    #   图像 / 音频附件解析
│   ├── events.py        #   持久化的操作日志
│   └── client.py        #   嵌入式 + HTTP 传输
├── providers/           # 可选组件适配器（共 72 个）
│   ├── llms.py          #   20 个 LLM 提供商
│   ├── embedders.py     #   13 个嵌入器提供商
│   ├── vector_stores.py #   28 个向量存储
│   ├── graph_stores.py  #   6 个图存储
│   ├── rerankers.py     #   5 个重排序器
│   ├── vision.py        #   三种图像传输格式
│   └── transport.py     #   标准库 HTTP + 重试 + 凭据脱敏
├── brain.py             # MemoryBrain — 引擎门面
├── capsule.py           # AIC 无损压缩
├── retrieval.py         # 多信号融合与相关性校准
├── graph.py             # 时序三元组存储
├── notary.py            # 写入前信任流水线
├── cli.py               # 原生 CLI
├── api_cli.py           # 客户端 API CLI
└── webui/
├── web_server.py    # 控制台 + REST 主机
├── api_routes.py    # /v1 /v2 /v3 路由
├── mcp_server.py    # 20 个原生 MCP 工具
└── mcp_api.py       # 11 个客户端兼容的 MCP 工具

storage/                 # SQLite 后端、哈希链式账本、插件 SDK
security/                # 矛盾检测、安全报告
scripts/                 # 验证脚本
docs/                    # 验收指南、召回策略、兼容性

✅ 测试
bash
python verify.py                              # 自检
python scripts/verify_api.py                  # 客户端 API 验证，完全离线
python scripts/verify_memory_lifecycle.py --brain-dir ./mem --src-root .
python scripts/verify_precision_recall.py     # 离线精确率回归
python scripts/verify_recall_quality.py       # 端到端召回质量

📚 文档

- docs/COMPATIBILITY.md — 常规的智能体记忆调用形态
- docs/ACCEPTANCE_GUIDE.md — 验收标准及对应的脚本
- docs/RECALL_STRATEGY.md — 检索如何组装与分配预算
- docs/KNOWN_DEFECTS.md — 已确认的缺陷，附测量数据与修复方案
- docs/DEPLOY_DEEPSEEK_HARNESS.md — MCP 部署演练
- CHANGELOG.md — 版本历史

📄 许可证

MIT 许可证 — 参见 LICENSE。

由 Mnemosyne OS 贡献者构建。