Mnemosyne OS ☤

Mnemosyne OS | GitHub | 中文文档

Mnemosyne OS 7.0.2 — a zero-dependency , local-first AI memory system with multi-tier forgetting , a hash-chain ledger , a plugin SDK , a local web dashboard , and MCP support.

The only AI memory engine whose core requires zero third-party dependencies — no vector database , no LLM runtime, no cloud lock-in. Runs on a laptop, a server, or serverless infra .

Use it as a Python library, a **CLI **, an **HTTP API **, an **MCP server **, or embed it via the **MCP ** stdio transport.

---

Quick Install

From PyPI

pip install mnemosyne-os

Zero-dependency core

# 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 

# 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()

# 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

Run the MCP server over stdio 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 **20 tools **:

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

HTTP API

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.2/
├── 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 / qdrant_backend)
├── 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

• docs/DEPLOY_DEEPSEEK_HARNESS.md — Deploy with DeepSeek Harness (via MCP)
• docs/KNOWN_DEFECTS.md — Confirmed defects in the 7.0.2 memory stack, with evidence and fixes
• docs/RECALL_STRATEGY.md — Recall mechanics and per-turn injection strategy assessment
• docs/ACCEPTANCE_GUIDE.md — Acceptance guide (with scripts/verify_memory_lifecycle.py)
• 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).