Mnemosyne OS ☤

Mnemosyne OS | GitHub | 中文文档

Mnemosyne OS 7.0.0 — a zero-dependency (零依赖), local-first (本地优先) AI memory system (AI 记忆系统) with multi-tier forgetting (多层次遗忘), a hash-chain ledger (哈希链账本), a plugin SDK (插件 SDK), a local web dashboard (本地 Web 管理界面), and MCP (Model Context Protocol / 模型上下文协议) support.

The only AI memory engine whose core requires zero third-party dependencies (仅依赖 Python 标准库 3.8+) — no vector database (向量库), no LLM (大语言模型) runtime, no cloud lock-in. Runs on a laptop, a server, or serverless infra (无服务器架构).

Use it as a Python (Python 库) library, a CLI (命令行), an HTTP API (API 接口), an MCP server (MCP 服务器), or embed it via the MCP (模型上下文协议) stdio transport.

Quick Install (快速安装)

From PyPI (PyPI 安装)

pip install mnemosyne-os

Zero-dependency core (零依赖核心 — no pip install required)

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

Development install (开发模式安装)

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

Getting Started (快速开始)

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 <memory_id>

# 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 (Python 接口)

from mnemosyne import MemoryBrain

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

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

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

# Token-budgeted recall
results, cost_report = brain.recall("Apple", k=5, budget_tokens=100)

# Conversation history
brain.add_conversation_turn("session-1", "user", "Tell me about Apple")
hits = brain.search_conversations("Apple", session_id="session-1")

# Context snapshot
snapshot = brain.build_context_prompt(query="Apple", max_chars=2000)

Async 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 Server (MCP 服务器)

Run the MCP server over stdio JSON-RPC (标准 JSON-RPC 传输):

export MNEMOSYNE_MCP_TOKEN="your-secret-token"   # optional token auth
python -m mnemosyne.webui.mcp_server --brain-dir ./mem --namespace default

The MCP server exposes 13 tools (13 个工具):

Connect any MCP host (Claude Desktop, Hermes Agent, etc.) by pointing it at the stdio command above.

HTTP API (API 接口 / Web 管理界面)

python -m mnemosyne.webui.web_server --port 9090

Then open http://127.0.0.1:9090 — a local dark dashboard (本地暗色面板) with memory browsing, graph view, stats, and a REST (表述性状态传递) endpoint. The default account admin / mnemosyne is created on first run; change the password after login.

Plugins (插件)

# Crypto plugin (requires cryptography; degrades gracefully otherwise)
brain = MemoryBrain("./memories", plugins=["crypto"])

# Numpy vector backend (requires numpy; optional sentence-transformers model)
brain = MemoryBrain("./memories", plugins=["numpy_vector"])

# Reranker plugin
brain = MemoryBrain("./memories", plugins=["reranker"])

Project Structure (项目结构)

Mnemosyne7.0.0/
├── mnemosyne.py              # Thin facade re-exporting the mnemosyne package
├── mnemosyne/                # Core engine package (brain / storage / retrieval / cognitive / notary)
├── storage/                  # Storage backends (sqlite_backend / ledger / session_store / plugin_sdk)
├── context/                  # Context snapshots (snapshot_builder)
├── context_engine/           # Context compression engine (engine-agnostic core + Hermes adapter)
├── lexical/                  # Built-in synonym dictionary
├── profiles/                 # User profile management
├── providers/                # External provider adapter + multi-source router
├── security/                 # Contradiction detection + security report
├── session/                  # Conversation importer
├── visualization/            # Knowledge tree generator
├── plugins/                  # Extra plugins (HRR / Async)
├── mnemosyne_plugins/        # Official plugins (numpy_vector / crypto / reranker)
├── examples/                 # Runnable examples (Ollama / LangChain / MCP / CLI / embedded)
└── docs/                     # Documentation (architecture, modules, plugins, API, deployment)

Testing (测试)

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

Documentation (文档)

• README_CN.md — 中文说明 (Chinese README)
• docs/ — Full docs: architecture, data model, module docs, plugin docs, API / CLI / MCP references, deployment, integration
• COMPLIANCE.md — HIPAA / 等保 / GDPR / PIPL compliance mapping
• comparison.md — Feature comparison with alternatives
• CHANGELOG.md — Version history
• Reports: quality_report.md (retrieval quality), benchmark_report.md (performance), security_report.md (security)

License (许可证)

MIT License — see LICENSE.

Built by 胡景堃 (Jingkun Hu).