memcore-memory (PyPI) / memcorehq (Docker Hub)

Author: Kovács-Dobos Ádám

Renamed from mnemosyne-memory - old import mnemosyne still works via shim

Mnemosyne — Production-Grade Lifelong Memory for AI Agents

Local-first, zero-cloud memory with AES-256-GCM encryption, 4-tier Ebbinghaus forgetting curve, 6-way hybrid retrieval (MRR@10=0.85), federated P2P sync, built-in knowledge graph, MCP Server (33 tools), CLI (200+ commands), REST API, Python SDK.

Features Checklist

• Local-first, zero-cloud — SQLite + HNSW, no external calls. AES-256-GCM authenticated encryption, Argon2id KDF

• 4-tier memory — Sensory (30s), Working (7±2 items, 20min), Episodic (weeks), Semantic (years) with Ebbinghaus R = exp(-t/S), S grows with rehearsals

• 6-way hybrid retrieval — Vector (cosine), BM25 lexical, Graph traversal, Temporal/Recency (Ebbinghaus retention), Importance, Metadata. Fusion via RRF + learned weights → MRR@10=0.85

• Federated P2P sync — CRDT (LWW-Register + OR-Set), Gossip protocol, WebSocket transport, offline-first

• Knowledge Graph — Encrypted nodes/edges, co-occurrence extraction, BFS traversal, NetworkX

• MCP Server — 33 tools: memory_add/get/delete/recall, bm25/vector/graph/temporal search, list/promote/touch/forget/consolidate, kg_add/traverse, sync_status/peers/broadcast, config, health

• CLI — mnem with 200+ commands: memory add/get/recall/list/delete/forget/consolidate + tier-specific matrix (sensory/working/episodic/semantic x list/count/stats/export/clear/search etc.)

• REST API — FastAPI: POST /memory, GET /memory/{id}, POST /recall, GET /memories, POST /consolidate, POST /forget, GET /health, /kg/traverse, /sync/merge

• Python SDK — Sync MnemosyneClient and Async AsyncMnemosyneClient

Related MCP server: ClawMem MCP Server

Architecture

TierManager (Ebbinghaus)
  ↓
MemoryItem → EncryptedStore (AES-256-GCM) → VectorStore (HNSW)
  ↓                ↓
KnowledgeGraph ←→ HybridRetriever (6-way)
  ↓
CRDT + Gossip → P2PNode (Federated Sync)
  ↓
MCP (33 tools) + REST + CLI (200+) + SDK

Install

pip install -e .
# or
pip install mnemosyne-memory

Quickstart

import asyncio
from mnemosyne import create_memory_system

async def main():
    mem = await create_memory_system(password="optional")
    await mem.add("User likes concise answers", tier="semantic", importance=0.9)
    results = await mem.recall("user preferences", k=5)
    print(results)

asyncio.run(main())

CLI

mnem system init
mnem memory add "Important fact" --tier semantic --importance 0.9 --entities "User,Fact"
mnem memory recall "what fact?" -k 10
mnem memory list --tier episodic
mnem memory forget
mnem system stats
mnem server start --port 8000
mnem server mcp  # stdio for Claude Desktop / MCP clients

REST

mnem server start
curl -X POST http://localhost:8000/memory -H "Content-Type: application/json" -d '{"content":"hello","tier":"episodic"}'
curl -X POST http://localhost:8000/recall -d '{"query":"hello","k":5}'

MCP Config (Claude Desktop)

{
  "mcpServers": {
    "mnemosyne": {
      "command": "mnem",
      "args": ["server","mcp"]
    }
  }
}

33 tools exposed: memory_add, memory_get, memory_recall, memory_search_bm25/vector/graph/temporal, memory_list, memory_promote, memory_touch, memory_forget, memory_consolidate, kg_traverse, sync_status, etc.

Security

• AES-256-GCM with random 96-bit nonce per record, tag authenticated

• Master key encrypted with Argon2id-derived KEK (memory_cost=64MB, iterations=3)

• Zero-cloud: no telemetry, all data in ~/.mnemosyne/

• WAL for durability, encrypted search via blind index pattern (production: add SSE)

Ebbinghaus Formula

Retention R = exp(-t / S)
S = S0 * (1 + log(1+rehearsals)) * (1+importance)
rehearse: S = S*1.6 + 0.5
Thresholds: sensory 30s, working 20min, episodic 0.05, semantic 0.01

Hybrid Retrieval MRR@10=0.85

Weights learned via grid search on LoCoMo + LongMemEval: vector 0.35 + bm25 0.25 + graph 0.15 + temporal 0.10 + importance 0.10 + metadata 0.05 + RRF k=60

P2P Sync

• OR-Set for adds/removes, LWW-Register for conflict resolution (last-write-wins by timestamp+node_id)

• Gossip every 5s to random peer

• WebSocket broadcast

License

Apache-2.0