mnemosyneDeepSeek Harness plugin

Mnemosyne OS ☤

Mnemosyne OS | GitHub | 中文文档

Mnemosyne OS 7.0.0 — 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.

Zero-dependency core	Runs on the Python standard library alone. No numpy, no torch, no vector DB, no LLM required to store and recall memories.
Multi-tier memory	Hot / warm / cold tiers with economic forgetting — migrate low-value memories, never silently delete them.
Hash-chain ledger	SHA-256 chained ledger — verify_chain() detects tampering and locates the exact corrupted record.
Plugin SDK	VectorBackendPlugin / CryptoPlugin / RerankerPlugin + official plugins (numpy_vector, crypto, reranker, hrr, async, context-engine).
MCP server	13 tools over stdio JSON-RPC, with token auth and multi-tenant namespaces .
Web dashboard	Tech-aesthetic local dark dashboard , no external CDN — served from web_server.py.
Async API	AsyncMemoryBrain asyncio wrapper for high-throughput ingestion.
Chinese-optimized	Bigram tokenization + FTS5 + built-in synonym dictionary .
Security notary	Detects credentials, invisible Unicode, and HTML injection; field-level redaction before write.

---

Quick Install

From PyPI

bash
pip install mnemosyne-os

Zero-dependency core

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

Development install

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

---

Getting Started

CLI

bash
1# Initialize the memory database
2python mnemosyne.py --dir ./mem init
3
4# Store a memory
5python mnemosyne.py --dir ./mem retain --content "Apple Inc. was founded in 1976"
6
7# Search memories
8python mnemosyne.py --dir ./mem recall "Apple" --k 5
9
10# Consolidate similar memories (pre-check)
11python mnemosyne.py --dir ./mem consolidate --dry-run
12
13# View status / health check
14python mnemosyne.py --dir ./mem status --json
15python mnemosyne.py --dir ./mem doctor --json
16
17# Knowledge graph query
18python mnemosyne.py --dir ./mem graph-query "Steve Jobs" --depth 2 --json
19
20# Ledger integrity / audit
21python mnemosyne.py --dir ./mem verify-integrity --json
22python mnemosyne.py --dir ./mem ledger-audit <memory_id>
23
24# Export / import
25python mnemosyne.py --dir ./mem export --format json --out ./memories.json
26python mnemosyne.py --dir ./mem import ./memories.json
27
28# Migrate JSONL -> SQLite
29python mnemosyne.py --dir ./mem migrate --jsonl ./mem/index.jsonl
30
31# Start the web dashboard
32python -m mnemosyne.webui.web_server --port 9090

Python API

python
1from mnemosyne import MemoryBrain
2
3brain = MemoryBrain("./my_memories", enable_embeddings=False)
4brain.ensure_init()
5
6# Store
7brain.retain("Apple Inc. was founded in 1976", fast=True)
8
9# Recall
10results = brain.recall("Apple", k=5)
11for score, record, reasons in results:
12    print(f"Score: {score:.4f} | {record['content']}")
13
14# Token-budgeted recall
15results, cost_report = brain.recall("Apple", k=5, budget_tokens=100)
16
17# Conversation history
18brain.add_conversation_turn("session-1", "user", "Tell me about Apple")
19hits = brain.search_conversations("Apple", session_id="session-1")
20
21# Context snapshot
22snapshot = brain.build_context_prompt(query="Apple", max_chars=2000)

Async API

python
1import asyncio
2from plugins.async_wrapper import AsyncMemoryBrain
3
4async def main():
5    brain = AsyncMemoryBrain("./memories", enable_embeddings=False)
6    await brain.async_retain("Hello World", fast=True)
7    results = await brain.async_recall("Hello", k=5)
8    print(results)
9    brain.close()
10
11asyncio.run(main())

MCP Server

Run the MCP server over stdio JSON-RPC :

bash
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 **:

Tool	Description
retain	Write a memory
recall	Retrieve memories
retain_batch	Batch write, ~15× speedup
stats	Runtime statistics — writes / recalls / token savings
graph_query	Knowledge graph query
temporal_query	Temporal version-chain query
list_projects	List isolated projects
doctor	Health check — integrity, record count, disk
audit	Audit-trail query
confidence_history	Confidence trajectory query
memory/export-v1	Export via Memory Exchange Protocol
memory/import-v1	Import via Memory Exchange Protocol
memory/claim	Claim memories from an external export

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

HTTP API

bash
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

python
# 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

bash
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)
• 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).