FrankHu-HK/mnemosyne

Mnemosyne OS ☤

Mnemosyne OS | GitHub | 中文文档

Mnemosyne OS 7.0.2 — 一个零依赖、本地优先的 AI 记忆系统，具备多层遗忘机制、哈希链账本、插件 SDK、本地 Web 仪表盘以及 MCP 支持。

唯一一款核心需要零第三方依赖的 AI 记忆引擎——无需向量数据库、无需 LLM 运行时、无云锁定。可在笔记本电脑、服务器或无服务器基础设施上运行。
将其用作 Python 库、CLI、HTTP API、MCP 服务器，或通过 MCP stdio 传输将其嵌入。

零依赖核心仅依赖 Python 标准库运行。无需 numpy、torch、向量数据库或 LLM 即可存储和召回记忆。
多层记忆热 / 温 / 冷分层，配合经济型遗忘——迁移低价值记忆，绝不静默删除。
哈希链账本SHA-256 链式账本——verify_chain() 可检测篡改并定位到确切的损坏记录。
插件 SDKVectorBackendPlugin / CryptoPlugin / RerankerPlugin + 官方插件（numpy_vector、crypto、reranker、hrr、async、context-engine）。
MCP 服务器通过 stdio JSON-RPC 提供 20 个工具，支持令牌认证和多租户命名空间。
Web 仪表盘科技美学的本地深色仪表盘，无外部 CDN——由 web_server.py 提供服务。
异步 APIAsyncMemoryBrain asyncio 封装，用于高吞吐量摄取。
中文优化双字分词 + FTS5 + 内置同义词词典。
安全公证检测凭据、不可见 Unicode 和 HTML 注入；写入前进行字段级脱敏。

快速安装

从 PyPI 安装

pip install mnemosyne-os

零依赖核心

Core runs on the Python standard library alone
python -c "from mnemosyne import MemoryBrain; print('Ready!')"

开发安装

git clone https://github.com/FrankHu-HK/mnemosyne.git
cd mnemosyne
pip install -e .

快速上手

CLI

Initialize the memory database
python mnemosyne.py --dir ./mem init

Store a memory
python mnemosyne.py --dir ./mem retain --content "Apple Inc. was founded in 1976"

Search memories
python mnemosyne.py --dir ./mem recall "Apple" --k 5

Consolidate similar memories (pre-check)
python mnemosyne.py --dir ./mem consolidate --dry-run

View status / health check
python mnemosyne.py --dir ./mem status --json
python mnemosyne.py --dir ./mem doctor --json

Knowledge graph query
python mnemosyne.py --dir ./mem graph-query "Steve Jobs" --depth 2 --json

Ledger integrity / audit
python mnemosyne.py --dir ./mem verify-integrity --json
python mnemosyne.py --dir ./mem ledger-audit

Export / import
python mnemosyne.py --dir ./mem export --format json --out ./memories.json
python mnemosyne.py --dir ./mem import ./memories.json

Migrate JSONL -> SQLite
python mnemosyne.py --dir ./mem migrate --jsonl ./mem/index.jsonl

Start the web dashboard
python -m mnemosyne.webui.web_server --port 9090

Python API

from mnemosyne import MemoryBrain

brain = MemoryBrain("./my_memories", enable_embeddings=False)
brain.ensure_init()

存储
brain.retain("Apple Inc. was founded in 1976", fast=True)

召回
results = brain.recall("Apple", k=5)
for score, record, reasons in results:
print(f"Score: {score:.4f} | {record['content']}")

按 token 预算的召回
results, cost_report = brain.recall("Apple", k=5, budget_tokens=100)

对话历史
brain.add_conversation_turn("session-1", "user", "Tell me about Apple")
hits = brain.search_conversations("Apple", session_id="session-1")

上下文快照
snapshot = brain.build_context_prompt(query="Apple", max_chars=2000)

异步 API

import asyncio
from plugins.async_wrapper import AsyncMemoryBrain

async def main():
brain = AsyncMemoryBrain("./memories", enable_embeddings=False)
await brain.async_retain("Hello World", fast=True)
results = await brain.async_recall("Hello", k=5)
print(results)
brain.close()

asyncio.run(main())

MCP 服务器

通过 stdio JSON-RPC 运行 MCP 服务器：

export MNEMOSYNE_MCP_TOKEN="your-secret-token"   # 可选的 token 认证
python -m mnemosyne.webui.mcp_server --brain-dir ./mem --namespace default

MCP 服务器暴露 20 个工具：

| 工具 | 描述 |
| --- | --- |
| retain | 写入一条记忆 |
| recall | 检索记忆 |
| retain_batch | 批量写入，约 15 倍加速 |
| stats | 运行时统计——写入 / 召回 / token 节省 |
| graph_query | 知识图谱查询 |
| temporal_query | 时序版本链查询 |
| list_projects | 列出隔离的项目 |
| doctor | 健康检查——完整性、记录数、磁盘 |
| audit | 审计追踪查询 |
| confidence_history | 置信度轨迹查询 |
| memory/export-v1 | 通过 Memory Exchange Protocol 导出 |
| memory/import-v1 | 通过 Memory Exchange Protocol 导入 |
| memory/claim | 从外部导出中认领记忆 |
| forget | 遗忘一条记忆——将置信度设为 0 并软删除（接受 memory_id，或自然语言 query） |
| consolidate | 压缩 · 记忆合并——将高度相似 / 同义的记忆合并为一条代表性记忆；原始记忆标记为 consolidated（min_similarity、max_group、generate_summary、dry_run） |
| reflect | 压缩 · 增强反思——按类型 / 层 / 事实类型 / 置信度统计总数、热门实体、事实冲突检测、时序密度；deep=true 会增加认知模式发现 |
| dedup | 压缩 · 去重——通过内容指纹 + 向量 / 词频相似度检测重复项和近似重复项；dry_run=true 仅报告 |

将任何 MCP 主机（Claude Desktop、Hermes Agent 等）指向上述 stdio 命令即可连接。

HTTP API

python -m mnemosyne.webui.web_server --port 9090
然后打开 http://127.0.0.1:9090 —— 一个本地深色仪表盘，具有记忆浏览、图谱视图、统计信息以及一个 REST 端点。默认账户 admin / mnemosyne 在首次运行时创建；登录后请修改密码。

插件

加密插件（需要 cryptography；否则会优雅降级）
brain = MemoryBrain("./memories", plugins=["crypto"])

Numpy 向量后端（需要 numpy；可选的 sentence-transformers 模型）
brain = MemoryBrain("./memories", plugins=["numpy_vector"])

重排序插件
brain = MemoryBrain("./memories", plugins=["reranker"])

项目结构

Mnemosyne7.0.2/
├── mnemosyne.py              # 薄门面，重新导出 mnemosyne 包
├── mnemosyne/                # 核心引擎包（brain / storage / retrieval / cognitive / notary）
├── storage/                  # 存储后端（sqlite_backend / ledger / session_store / plugin_sdk）
├── context/                  # 上下文快照（snapshot_builder）
├── context_engine/           # 上下文压缩引擎（引擎无关核心 + Hermes 适配器）
├── lexical/                  # 内置同义词词典
├── profiles/                 # 用户画像管理
├── providers/                # 外部提供方适配器 + 多源路由器
├── security/                 # 矛盾检测 + 安全报告
├── session/                  # 对话导入器
├── visualization/            # 知识树生成器
├── plugins/                  # 额外插件（HRR / Async）
├── mnemosyne_plugins/        # 官方插件（numpy_vector / crypto / reranker / qdrant_backend）
├── examples/                 # 可运行示例（Ollama / LangChain / MCP / CLI / 嵌入式）
└── docs/                     # 文档（架构、模块、插件、API、部署）

测试

python -m unittest discover -s tests -v
python -m unittest tests.test_plugins -v

文档

- docs/DEPLOY_DEEPSEEK_HARNESS.md —— 使用 DeepSeek Harness 部署（通过 MCP）
- docs/KNOWN_DEFECTS.md —— 7.0.2 记忆栈中已确认的缺陷，附证据与修复方案
- docs/RECALL_STRATEGY.md —— 召回机制与逐轮注入策略评估
- docs/ACCEPTANCE_GUIDE.md —— 验收指南（附 scripts/verify_memory_lifecycle.py）
- README_CN.md —— 中文说明（中文 README）
- docs/ —— 完整文档：架构、数据模型、模块文档、插件文档、API / CLI / MCP 参考、部署、集成
- COMPLIANCE.md —— HIPAA / 等保 / GDPR / PIPL 合规映射
- comparison.md —— 与替代方案的功能对比
- CHANGELOG.md —— 版本历史
- 报告：quality_report.md（检索质量）、benchmark_report.md（性能）、security_report.md（安全）

许可证

MIT 许可证 —— 参见 LICENSE。

由 胡景堃（Jingkun Hu）构建。