The memory engine

Consolidation

Clusters similar memories and merges them into a consolidated insight, archiving the originals. Models the biological trace → memory → schema maturation.

memorius consolidate --dry-run            # preview clusters
memorius consolidate --threshold 0.80     # merge at 80% similarity
memorius consolidate --vault main          # scope to one vault

Uses O(N²) pairwise comparison for clustering. Runs automatically when consolidation.enabled is on (config) and can also be triggered by a hook action. Related MCP tool: memorius_consolidate.

Temporal decay

The Ebbinghaus forgetting curve ranks memories by relevance over time. Two scores drive it:

• Decay score (0–1) = age decay (40%) + recency boost (40%) + access reinforcement (20%).
• Search ranking = semantic similarity (60%) + temporal decay (25%) + access frequency (15%).

Reading a memory reinforces it via touch(). Stale memories surface through the decay threshold or explicit TTL expiry — set with memorius store "..." --ttl 30.

Pruning

Find and archive (or hard-delete) stale memories by decay score.

memorius prune --threshold 0.1 --dry-run   # preview stale memories
memorius prune --threshold 0.1             # soft-archive stale memories
memorius prune --threshold 0.1 --delete    # hard-delete

Soft-archived memories stay queryable but stop counting toward active retrieval; --delete removes them from both stores. Accepts --json.

Knowledge graph

Memories auto-link on every store() by content proximity. Edge types:

Inspect with memorius graph stats, memorius graph view (interactive browser), or memorius graph export-html (standalone file).

Fact-checking

Verify a claim against stored memories. Verdicts: verified / contradicted / uncertain / no_match.

memorius factcheck "Rust 1.80 was released in July 2024"
memorius factcheck "..." --web     # cross-check uncertain claims with the web

Contradictions are persisted as bidirectional contradicts graph edges and are queryable via memorius_contradictions (MCP) and /contradictions/{id} (REST).

Cross-encoder reranking

Optional precision pass over top-k vector hits.

memorius search "query" --rerank

Uses cross-encoder/ms-marco-MiniLM-L-6-v2 (included out of the box). Adds __rerank_score__ to metadata for transparent ranking. Hybrid retrieval (vector + BM25/FTS5) is on by default so keyword blind-spots don't drop results.

Web fallback

Local-first and opt-in — the vault is searched first; web is only consulted when local recall is thin or you ask for it.

memorius web "python 3.13 changelog"                 # keyless DuckDuckGo
memorius web "..." --provider tavily                 # keyed, higher signal
memorius search "latest rust release" --web          # augment a local search
memorius factcheck "..." --web                        # cross-check a claim

memorius doctor — health checks

Runs 6 checks and returns a structured ok / warn / fail / skip report.

1. Config is parseable.
2. Storage directory is writable.
3. ONNX model is present.
4. Vector/meta count drift (points at repair when it fires).
5. Collection name length (Chroma limit).
6. Graph health.

memorius doctor

memorius repair — fix vector/meta drift

New in v0.8.6. Reconciles the Chroma vector store with the authoritative memory_meta table. Remove orphaned vectors, optionally re-embed missing ones.

memorius repair --dry-run          # preview what would change
memorius repair                    # remove orphaned vectors
memorius repair --reindex          # also re-embed metadata rows missing a vector
memorius repair --vault main       # scope to a single vault
memorius repair --json             # machine-readable report