Mnemosyne 7.0.0 — Zero-Dependency AI Memory System

Mnemosyne (慧记) — 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.

Quick Start

# Zero-dependency core — no pip install required
python -c "from mnemosyne import MemoryBrain; print('Ready!')"

# Or install in development mode
pip install -e .

Core Features

Usage

CLI

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

# Store a memory
python mnemosyne.py --dir ./mem retain --content "苹果公司成立于1976年"

# Search memories
python mnemosyne.py --dir ./mem recall "苹果" --k 5

# Consolidate similar memories
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 "张三" --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 -c "from web_server import run_server; run_server(port=9090)"

Python API

from mnemosyne import MemoryBrain

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

# Store
brain.retain("苹果公司成立于1976年", fast=True)

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

# Token-budgeted recall
results, cost_report = brain.recall("苹果", 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())

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 (36 lines) 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)
├── mcp_server.py             # MCP server (13 tools + auth + multi-tenant)
├── web_server.py             # Local web dashboard
├── tests/                    # unittest suite
├── benchmarks/               # Performance benchmarks
├── quality_eval/             # Retrieval quality evaluation
├── examples/                 # Runnable examples (Ollama / LangChain / MCP / CLI / embedded)
└── docs/                     # Full Chinese docs (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 documentation: architecture, data model, 15 module docs, 7 plugin docs, API/CLI/MCP reference, deployment, integration, commercialization
• 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 the LICENSE file.