Mnemosyne AI Memory

Mnemosyne

Give your AI a brain that remembers across sessions, retrieves with GraphRAG, predicts with precondition, dreams to consolidate, and grows governed skills.

Bionic Experience & Memory System — Agent memory, GraphRAG, vector search, predictive memory, dream consolidation, Skill Memory, MCP, REST API, and dashboard.

[](https://www.python.org/) [](LICENSE) [](https://modelcontextprotocol.io/) [](CHANGELOG.md) [](https://github.com/nianpangzhi233/Mnemosyne-AI-Memory/actions/workflows/ci.yml) [](https://github.com/nianpangzhi233/Mnemosyne-AI-Memory/actions/workflows/pages.yml) [](#knowledge-graph--multi-dimensional-retrieval) [](#predictive-memory)

[中文文档](docs/READMECN.md) · [Architecture](docs/architecture.md) · [Cold-start demo](demo/demoscript.md) · Project Site · [FAQ](docs/faq.md) · [Benchmarks](docs/benchmarks.md) · [Why it matters](docs/why-it-matters.md) · Releases

For AI agents that should remember what matters, dream what connects, and grow skills that survive the next session.

Live demo / project page · Quick start · Skill evolution

---

What It Is

Mnemosyne is a local-first AI memory system for developers who keep teaching an agent the same lesson and want it to actually remember. It combines GraphRAG, vector search, predictive memory, dream consolidation, and governed Skill Memory behind MCP, REST API, CLI, and a dashboard.

The Problem

AI assistants have a fatal flaw: they can't remember.

You spent 30 minutes explaining your project architecture — next day, it's gone. You corrected it 3 times to use const instead of var — 4th time, still writing var. You said "I prefer concise replies" — next session, it's writing essays again.

This isn't a bug, it's by design — every conversation starts from a blank slate.

Mnemosyne fixes this. Not a file store, not a diary, not keyword matching. It's a living knowledge graph — like a human brain that associates, forgets, and dreams.

Use Cases

• Remember team preferences, architecture decisions, and recurring fixes.
• Recall project-specific lessons without re-explaining them every session.
• Surface known pitfalls before the agent repeats them.
• Convert reliable experience clusters into reusable, governed skills.

Why it is different

• Memory is not append-only. It can verify, contradict, decay, and evolve.
• Retrieval is not one-dimensional. It combines vector search, keyword search, graph traversal, and tag filtering.
• Skills are not just prompts. They are tested, governed artifacts with evidence, feedback, and promotion rules.
• It ships with a dashboard, REST API, MCP server, and a one-command installer.

Visual overview

---

Quick Start

git clone https://github.com/nianpangzhi233/Mnemosyne-AI-Memory.git
cd Mnemosyne-AI-Memory
python setup.py

On Windows, start the local V8 API and dashboard with the bundled shortcuts:

start-v8-api.cmd
start-dashboard.cmd

start-api.cmd remains as a legacy launcher for the combined API surface.

Manual startup works the same way:

python scripts/api/start_api.py --port 8979
streamlit run scripts/dashboard/app.py --server.port 8501 --server.headless=true --browser.gatherUsageStats=false

Run the legacy V7 dream manually when you want consolidation now:

python scripts/graph_dream.py --full

Run the safe cold-start demo first if you want to see the whole user story without touching your real databases:

python demo/run_v8_demo.py
python demo/run_demo.py
python demo/run_demo.py --keep --out %TEMP%\mnemosyne-demo-kept

demo/run_v8_demo.py is the V8-only demo path. demo/run_demo.py is the legacy V7-heavy story demo.

The legacy demo imports safe seed conversations, creates typed graph evidence, writes a reviewable EvolutionReport, creates a low-risk trial skill, demonstrates skill injection, and records a telemetry run. A successful run prints status: PASS with explicit checks.

If you only want the legacy V7 graph flow, run python setup.py first and then use graph_write.py, graph_query.py, and graph_dream.py.

# Write an experience
memory_write(content="Gzip request body must be decompressed before JSON.parse()",
             principle="Always check Content-Encoding header before parsing")

# Search memories
memory_search(query="request body parse failure", layer="L0")
# → Returns: "Always check Content-Encoding header" (~100 tokens only)

# Auto-inject relevant memories on startup (memories find you)
memory_inject(context="API proxy project")

# Predictive memory: remember when an experience applies
memory_write(
    content="torch 2.11.0 crashes on this Windows setup; use torch 2.6.0 instead",
    precondition="installing torch on Windows",
    predicted_outcome="torch 2.6.0 is the stable choice"
)

---

Core Features

Three-Layer Memory (L0/L1/L2)

Inspired by ByteDance's OpenViking. Don't dump 50K tokens of context into every prompt:

| Layer | Size | Purpose | |-------|------|---------| | L0 Abstract | ~100 tokens | Quick relevance check, injected at startup | | L1 Overview | ~500 tokens | Enough for most queries | | L2 Full Content | Unlimited | When you actually need the details |

Result: 83% token cost reduction with no loss in retrieval quality.

Knowledge Graph + Multi-Dimensional Retrieval

Memories are connected by relation types, then routed through orthogonal graph dimensions (semantic, causal, temporal, entity) for more precise retrieval:

| Relation | Meaning | Example | |----------|---------|---------| | is_a | Categorize into abstract principle | "gzip decompress fail" → is_a → "check encoding first" | | similar_to | Semantically similar (vector ≥ 0.85) | "response garbled" ≈ "JSON parse error" | | caused | Causal chain | "no input validation" → caused → "production 500" | | solves | Solution link | "added retry logic" → solves → "API timeout" | | contradicts | New experience overrides old | "use approach A" ✗ "actually use B" | | transfers_to | Cross-domain transfer | "Node.js error handling" → transfers to → "Python project" | | evolved_from | Strategy distilled from cluster | Abstract strategy from multiple experiences |

v6.1 adds SYNAPSE-style spreading activation with 5 search modes:

| Mode | Use case | |------|----------| | hybrid | Default vector + keyword + graph retrieval | | precise | Conservative traversal through strong edges | | creative | Wider association through weak edges and is_a concept jumps | | vector | Pure semantic similarity search | | keyword | FTS5 keyword search |

Predictive Memory

Mnemosyne is no longer append-only. Experiences can declare:

| Field | Meaning | |-------|---------| | precondition | When this memory applies | | predicted_outcome | What should happen under that condition | | confidence | Reliability score, increased by verification and reduced by contradiction |

When a new memory matches an old precondition, Mnemosyne validates the old prediction automatically. Confirming evidence strengthens the memory; conflicting evidence creates a contradicts edge and lowers stale confidence.

Dream (Legacy Automatic Consolidation)

The human brain consolidates memories during sleep. The legacy V7 runtime does the same with a Fast/Slow dream pipeline:

| Stream | Purpose | |--------|---------| | Fast Path | Deterministic maintenance: decay, sync, incremental association, index-safe cleanup | | Slow Path | Deeper consolidation: contradiction discovery, causal links, strategy distillation, optional LLM review |

V6.1 legacy Dream is organized around a three-layer biomimetic architecture:

| Layer | Mnemosyne component | |-------|--------------------| | Hippocampus | Write-time predictive validation and auto-association | | REM sleep | Incremental similar_to and contradicts discovery | | Prefrontal cortex | Optional LLM-assisted contradiction judgment and review |

Legacy V7 dream runs automatically at 3 AM, noon, and 5 PM daily. Or trigger manually:

python scripts/graph_dream.py --full

The legacy background skill daemon extends this with a post-dream skill loop:

• scan new embryo and needs_revision skills after each full dream run
• run up to 2 bilateral evolution rounds per candidate
• record trial feedback automatically
• auto-promote only low-risk skills after 3 consecutive successful trials
• keep medium/high-risk skills out of default injection unless an explicit policy allows them

skill-daemon.cmd

Legacy dream output is reviewable, not just logged. Each run writes an EvolutionReport with structured sections such as new memories, concepts, skill candidates, skill changes, contradictions, recommended actions, target IDs, and evidence IDs. Daemon jobs also write persistent telemetry_runs rows with status, duration, summary, and errors so historical background work remains observable.

Skill Memory System

v7.1 lets mature experience clusters grow into reusable, governed skills through bilateral evolution:

experience cluster -> embryo -> draft -> tested -> evolved -> approved -> injected skill

Key rules:

| State | Meaning | Default injection | |-------|---------|-------------------| | embryo | Graph-discovered skill candidate | No | | draft | LLM-developed operational draft | No | | tested | Baseline and with-skill runs recorded with judge output | No | | evolved | Darwin live tests improved behavior and Mnemosyne graph governance passed | No, except explicit trial/experimental modes | | approved | Verified skill allowed in normal context | Yes | | deprecated | Soft-retired skill with evidence preserved | No |

Dry-run scoring cannot produce evolved. Approval is gated: a skill must have passing bilateral evidence, a synced SKILL.md hash, and at least one verified_by edge before it can become approved.

Bilateral evolution means:

Darwin side: baseline vs with-skill live tests prove behavior improved.
Mnemosyne side: graph evidence, feedback, trigger precision, and safety prove the skill is trustworthy.

Generated skill mirrors live in:

skills//SKILL.md

Skill test prompts live beside the skill:

skills//test-prompts.json

Automatic Conversation Learning

Scans opencode conversation logs, filters noise (chitchat, boilerplate, system warnings), and uses LLM to distill principles and summaries from valuable fragments — writing them into the memory graph.

You use AI normally, memories accumulate automatically. No manual recording needed.

Privacy Guard

All auto-discovered relations go through a safety audit. Edges involving passwords, keys, ID numbers, or other sensitive information are automatically rejected.

---

Integration

MCP (Recommended)

Any AI tool that supports MCP (Model Context Protocol) can use Mnemosyne:

{
  "mcpServers": {
    "mnemosyne": {
      "command": "python",
      "args": ["scripts/mcp_server/start_mcp.py"]
    }
  }
}

Core memory tools: memory_write, memory_search, memory_inject, memory_detail, memory_update, memory_delete.

Skill Memory tools: memory_crystallize, memory_skill_search, memory_skill_inject, memory_skill_approve, memory_skill_feedback, memory_skill_deprecate.

V8 evidence-governed kernel tools are available with the v8_ prefix, including v8_event_add, v8_candidate_add, v8_evidence_add, v8_lifecycle_promote, and v8_context_build. See v8/README.md for the stable V8 contract.

memory_search supports hybrid, precise, creative, vector, and keyword modes, plus graph dimension and tag filters.

REST API

python scripts/api/start_api.py --port 8979
# Windows shortcut: start-v8-api.cmd
# Legacy shortcut: start-api.cmd
# Swagger docs: http://localhost:8979/docs

curl http://localhost:8979/api/health
# → {"status":"ok","nodes":0,"edges":0}

curl "http://localhost:8979/api/search?q=gzip&layer=L0&top=5"

Operational endpoints expose learning reports and background observability:

GET /api/evolution-reports/latest
GET /api/evolution-reports
GET /api/telemetry/latest
GET /api/telemetry/summary
GET /api/telemetry/runs
GET /api/telemetry/runs/summary

V8 is the new evidence-governed runtime. Its REST endpoints live under /api/v8, including POST /api/v8/events, POST /api/v8/candidates, POST /api/v8/evidence, POST /api/v8/lifecycle/promote, and POST /api/v8/context-packs. V7 is being preserved as a legacy archive; see V7_ARCHIVE_POLICY.md and V7_TO_V8_MIGRATION.md.

CLI

# Write
python scripts/graph_write.py --content "experience content" --principle "abstract principle"

# Search (semantic / keyword / hybrid)
python scripts/graph_query.py --vector-search "keyword" --layer L0 --top 5

# Health check
python scripts/graph_audit.py

# Evaluate a skill with an OpenAI-compatible runner/judge
python scripts/evaluate_skill.py \
  --skill-id  \
  --config configs/skill-eval.local-gateway.example.json

# Run the skill evidence-flow daemon
skill-daemon.cmd

evaluate_skill.py is a thin adapter. The reusable flow lives in core.skill_evolution.SkillEvolutionRunner, and provider-specific execution lives in core.runners. Do not put real API keys in example configs; use environment variables such as MNEMOSYNE_LLM_API_KEY for private endpoints.

---

Dashboard

streamlit run scripts/dashboard/app.py --server.port 8501 --server.headless=true --browser.gatherUsageStats=false
# Windows shortcut: start-dashboard.cmd

| Page | Features | |------|----------| | Dashboard | Control console, quick search, health metrics, latest learning report, daemon run history, audit signals | | Skills | Skill catalog, evidence flow, governance decisions, injection status, trial feedback, audit flags | | Search | Search + L0→L1→L2 progressive expand | | Graph | D3.js force-directed graph (zoom, drag, type coloring) | | Dream Log | Fast/Slow dream runs, phase timing, reviewable EvolutionReport sections, evidence IDs, recommended actions |

---

Project Structure

scripts/
├── core/                # Abstraction layer (swappable components)
│   ├── graph_store.py   # Graph store interface
│   ├── sqlite_store.py  # SQLite impl (vectors + FTS5 + graph traversal)
│   ├── embedder.py      # Embedding interface (Harrier/BGE-M3/Qwen)
│   ├── dream_pipeline.py # Fast/Slow dream pipeline + EvolutionReport
│   └── telemetry.py     # Local telemetry_runs persistence
├── api/                 # FastAPI REST API + Swagger
├── mcp_server/          # MCP Server (memory + skill tools, stdio)
├── dashboard/           # Streamlit visualization dashboard
├── log_scanner/         # Conversation log scanner + filter + distill
├── graph_write.py       # Write CLI
├── graph_query.py       # Query CLI
├── graph_dream.py       # Dream CLI
└── graph_audit.py       # Health report + cleanup
demo/
├── seed_conversations/  # Safe public demo data
├── expected/            # Expected demo check shape
└── run_demo.py          # Cold-start user-story demo

Every component is swappable through abstract interfaces:

• Storage (GraphStore) → SQLite / FAISS / Neo4j
• Embedding (Embedder) → Harrier / BGE-M3 / Qwen
• Scheduler (TaskRunner) → APScheduler / Celery

---

Design Philosophy

Mnemosyne simulates three memory mechanisms of the human brain:

Prediction — You enter the same situation again, and the brain expects what should happen. Predictive memory does this with precondition + predicted_outcome.

Intuition — Walk into a kitchen, automatically think "food." The environment triggers memory. Startup injection does exactly this.

Recall — Someone asks "how did we make that dish?" and you actively search your memory

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nianpangzhi233
• Source: nianpangzhi233/Mnemosyne-AI-Memory
• License: MIT
• Homepage: https://nianpangzhi233.github.io/Mnemosyne-AI-Memory/

Install and usage instructions live in the source repository linked above.