feat(dream): sleep-time LLM consolidation episodic->semantic (mimir_dream, #364) (#369)

New mimir_dream tool: batches clusters of related cold/episodic memories
per category (trigram neighborhoods, cold-first), reflects over each
cluster via the configured --llm-endpoint, and writes back durable
semantic insights (category=insight, working/semantic layer) with full
evidence_for provenance to every source and derivation="dream".

- Never fabricates: insights need >=2 cited sources; LLM output is
  untrusted data, parsed strictly (unknown types / empty summaries /
  out-of-range evidence indices are dropped, never repaired).
- Idempotent: insight keys are a stable FNV-1a hash of the evidence set,
  so re-dreaming an unchanged cluster dedupes instead of duplicating.
- Contradiction-aware: disagreeing sources become a flagged
  "contradiction" insight (sources always stay live), not a silent merge.
- Bounded: max_entities caps the scan, max_clusters caps LLM calls.
- Same archive safety rules as consolidate/#350: opt-in archive_sources
  never touches verified or importance-floored sources.
- Local-first: clean error without --llm-endpoint (works offline), or
  opt-in fallback_consolidate to degrade to the non-LLM consolidate
  pass. Prompt fields sanitized via sanitize_prompt_field (#337);
  memories demoted to data-not-instructions in the prompt.
- LLM boundary injected via dream_with_llm for deterministic, zero-
  network tests (9 db-level + 1 MCP-level; JSON-RPC smoke verified
  against the compiled binary). No schema change; no new dependencies
  (reuses ureq, Ollama /api/generate shape with OpenAI-compat fallback).
- Docs: retention.md "Dreaming" section, README/CHANGELOG, tool count
  49 -> 50 across README badge/tables, server.json, manifest.json,
  glama.json, CLAIMS-AUDIT.md.

Closes #364

Co-authored-by: tcconnally <hermes@perseus.observer>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

CHANGELOG.md

@@ -24,6 +24,12 @@ All notable changes to Perseus Vault (formerly Mimir/Mneme) are documented here.
   entities across clusters instead of only the nearest one). Communities are
   persisted in a new `communities` table (schema v8); `mimir_stats` now
   reports `total_communities` and `graph_modularity`.
+- `mimir_dream` — sleep-time LLM consolidation of episodic → semantic memory:
+  clusters related cold memories per category, reflects over each cluster via
+  the configured `--llm-endpoint`, and writes back provenance-linked semantic
+  insights (`evidence_for` to every source, `derivation: "dream"`, idempotent
+  by evidence-set hash, contradiction-aware, bounded budgets, dry-run;
+  verified/importance-floored sources never archived). 53rd MCP tool (#364)
 
 ### Fixed
 - Context injection relevance gating (#356): `context`/`prepare` no longer

CLAIMS-AUDIT.md

@@ -8,10 +8,10 @@
 
 Claims verified against `src/`:
 
-- **49 MCP tools** — exactly 49 distinct `mimir_*` tool names registered in
+- **50 MCP tools** — exactly 50 distinct `mimir_*` tool names registered in
   source (`src/mcp.rs` TOOLS schema); each is additionally exposed under
   `mneme_*` and `perseus_vault_*` aliases (same handler, not counted).
-  README badge, comparison table, and the "49 MCP Tools" section all agree. ✓
+  README badge, comparison table, and the "50 MCP Tools" section all agree. ✓
 
   Verify the count against source (this is the authoritative command — re-run
   it and update README/manifest.json/glama.json whenever a tool is added):

README.md

@@ -10,7 +10,7 @@
 [![LangGraph](https://img.shields.io/badge/integrations-LangGraph-blue)](integrations/langgraph/)
 [![CrewAI](https://img.shields.io/badge/integrations-CrewAI-orange)](integrations/crewai/)
 [![AutoGen](https://img.shields.io/badge/integrations-AutoGen-purple)](integrations/autogen/)
-[![MCP Tools](https://img.shields.io/badge/MCP%20tools-52-brightgreen)]()
+[![MCP Tools](https://img.shields.io/badge/MCP%20tools-53-brightgreen)]()
 
 Perseus Vault is a single Rust binary that gives AI agents durable memory across sessions.
 **One binary. One file. No Docker. No Postgres. No cloud.** Just persistent memory
@@ -93,15 +93,15 @@ local-first, zero-dependency, AND agent-first.
 |---|---|---|---|---|
 | **Deployment** | Single binary (~8MB) | Cloud + self-host | Docker/Postgres | Docker/Postgres |
 | **Dependencies** | None (SQLite embedded) | Python + vector DB | Postgres + Python | Postgres + Go |
-| **MCP-Native** | ✅ 52 tools | ❌ Not MCP-native | ❌ Not MCP-native | ❌ Not MCP-native |
+| **MCP-Native** | ✅ 53 tools | ❌ Not MCP-native | ❌ Not MCP-native | ❌ Not MCP-native |
 | **Offline/Local** | ✅ Fully local | Cloud-dependent | Docker needed | Docker needed |
 | **Encryption** | AES-256-GCM ✅ | ❌ | ❌ | ❌ |
 | **Hybrid Search** | BM25 + Dense + RRF | Vector only | Vector only | Vector + Graph |
 | **Entity Lifecycle** | Decay + Promote + Archive | ❌ | ❌ | ❌ |
 | **Entity Graph** | Link + Traverse | ❌ | ❌ | ✅ |
 | **Journal Audit Trail** | ✅ Immutable | ❌ | ❌ | ❌ |
 | **State Management** | ✅ Key-value + TTL | ❌ | ❌ | ❌ |
-| **MCP Tools** | 52 | 5 | 8 | 0 |
+| **MCP Tools** | 53 | 5 | 8 | 0 |
 | **GitHub Stars** | ~20 | ~55K | ~15K | ~3K |
 | **License** | MIT | Apache 2.0 | Apache 2.0 | Apache 2.0 |
 
@@ -143,7 +143,7 @@ Each adapter:
 Any MCP-compatible framework works with Perseus Vault directly. See
 [Awesome Mimir](awesome-mimir.md) for the full list.
 
-## 52 MCP Tools
+## 53 MCP Tools
 
 ### Entity CRUD
 | Tool | Description |
@@ -204,6 +204,7 @@ Any MCP-compatible framework works with Perseus Vault directly. See
 | `mimir_compact` | Archive entities below decay threshold. |
 | `mimir_reindex` | Rebuild FTS5 search index from entities table. |
 | `mimir_consolidate` | Merge overlapping/duplicative entities in a category into durable, evidence-tracked observations (mirror image of `mimir_conflicts`). |
+| `mimir_dream` | Sleep-time LLM consolidation: reflect over clusters of related episodic memories via the configured LLM and write back durable semantic insights, provenance-linked to every source. Idempotent (evidence-set hash), contradiction-aware, bounded; requires `--llm-endpoint`. |
 
 ### Quality
 | Tool | Description |

docs/retention.md

@@ -149,6 +149,38 @@ The legacy unconditional top-N dump remains available as an explicit opt-in
 (`mode: "always_inject"` on `mimir_context`, `--legacy-context` on
 `prepare`) and is unclamped unless a budget is passed. The gRPC `context`
 RPC keeps the legacy semantics for wire compatibility.
+## Dreaming (LLM consolidation, episodic → semantic)
+
+Consolidation compresses *duplicates*; `mimir_dream` goes one step further and
+**reasons** over clusters of merely *related* memories. It batches the coldest
+entities per category (cold-first by default — consolidate fading memories
+before decay claims them), sends each trigram-neighborhood cluster to the
+configured LLM ("given these N memories, what stable pattern / preference /
+fact do they collectively imply?"), and writes the answer back as a durable
+**semantic insight** (category `insight`, `working` layer — the canonical
+storage layer for the `semantic` biomimetic alias). Properties:
+
+- **Full provenance** — every insight links `evidence_for` to each source
+  entity, and its body carries `derived: true`, `derivation: "dream"`, and the
+  source ids, so it is auditable and reversible.
+- **Never fabricates** — insights need at least two cited sources; clusters
+  that support no durable generalization are a no-op. LLM output is parsed
+  strictly (unknown types, empty summaries, out-of-range evidence indices are
+  dropped, never repaired into a write).
+- **Idempotent** — insights are keyed by a hash of their evidence set, so
+  re-dreaming an unchanged cluster dedupes instead of duplicating.
+- **Contradiction-aware** — disagreeing sources become a flagged
+  `contradiction` insight (sources always stay live), never a silent merge.
+- **Bounded** — `max_entities` caps the scan, `max_clusters` caps LLM calls.
+- **Same archive safety rules** — opt-in `archive_sources` retires dreamed
+  sources (`archive_reason` names the insight), but **verified or
+  importance-floored sources are never archived**.
+
+Dreaming requires `--llm-endpoint` (fully local via Ollama). Without one it
+returns a clean error — or, with `fallback_consolidate: true`, degrades to the
+mechanical `mimir_consolidate` cold-first pass. `dry_run: true` previews the
+candidate insights and their evidence sets without writing anything (not even
+a journal entry).
 
 ## Semantic recall and reinforcement
 

glama.json

@@ -3,7 +3,7 @@
   "maintainers": [
     "tcconnally"
   ],
-  "tools": 52,
+  "tools": 53,
   "transport": {
     "stdio": true,
     "sse": true,

manifest.json

@@ -3,8 +3,8 @@
   "name": "perseus-vault",
   "version": "2.13.0",
   "display_name": "Perseus Vault — Persistent Memory for Claude (formerly Mimir/Mneme)",
-  "description": "Persistent cross-session memory for Claude. 52 MCP tools: remember, recall, search, link entities, journal audit trail, state management, AES-256-GCM encryption. Local-first, single Rust binary, zero cloud dependencies.",
-  "long_description": "Perseus Vault (formerly \"Mimir\", then \"Mneme\") gives Claude durable memory across sessions. It is a single Rust binary (~8MB) with an embedded SQLite database — no Docker, no Postgres, no cloud. Features include:\n\n- **52 MCP tools** for entity storage, hybrid search (FTS5 + dense vector), knowledge-graph traversal, journal audit trail, and state management\n- **AES-256-GCM encryption at rest** (optional, transparent)\n- **Fully local** — never phones home, no telemetry, air-gapped by default\n- **Agent-first design** — entity lifecycle with Ebbinghaus decay, auto-promotion, archiving\n- **Works with any MCP host** — Claude Desktop, Claude Code, Cursor, Hermes Agent, Perseus, and more\n\nInstall in one line: `curl -sSf https://raw.githubusercontent.com/Perseus-Computing-LLC/perseus-vault/main/scripts/install.sh | sh`",
+  "description": "Persistent cross-session memory for Claude. 53 MCP tools: remember, recall, search, link entities, journal audit trail, state management, AES-256-GCM encryption. Local-first, single Rust binary, zero cloud dependencies.",
+  "long_description": "Perseus Vault (formerly \"Mimir\", then \"Mneme\") gives Claude durable memory across sessions. It is a single Rust binary (~8MB) with an embedded SQLite database — no Docker, no Postgres, no cloud. Features include:\n\n- **53 MCP tools** for entity storage, hybrid search (FTS5 + dense vector), knowledge-graph traversal, journal audit trail, and state management\n- **AES-256-GCM encryption at rest** (optional, transparent)\n- **Fully local** — never phones home, no telemetry, air-gapped by default\n- **Agent-first design** — entity lifecycle with Ebbinghaus decay, auto-promotion, archiving\n- **Works with any MCP host** — Claude Desktop, Claude Code, Cursor, Hermes Agent, Perseus, and more\n\nInstall in one line: `curl -sSf https://raw.githubusercontent.com/Perseus-Computing-LLC/perseus-vault/main/scripts/install.sh | sh`",
   "author": {
     "name": "Perseus Computing LLC",
     "email": "privacy@perseus.observer",

server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.Perseus-Computing-LLC/mimir",
   "title": "Perseus Vault (formerly Mimir/Mneme), persistent memory engine for AI agents",
-  "description": "Local-first MCP memory server: SQLite, FTS5 and vector search, AES-256-GCM. 52 tools, no cloud.",
+  "description": "Local-first MCP memory server: SQLite, FTS5 and vector search, AES-256-GCM. 53 tools, no cloud.",
   "version": "2.13.0",
   "packages": [{
     "registryType": "oci",