Perseus Vault
Mimir is a local-first, MCP-native persistent memory engine for AI agents, offering 43 tools across entity storage, search, knowledge graphing, journaling, state management, and lifecycle management — running as a single zero-dependency Rust binary with optional AES-256-GCM encryption, bearer token auth, and multi-transport support (stdio, SSE, HTTP).
Entity CRUD & Storage
Store/update entities (
mimir_remember) — idempotent key-value memory with categories, tags, importance, encryption, and workspace scopingSearch memories (
mimir_recall) — FTS5 keyword, dense vector, or hybrid (RRF) search with filters, query expansion, and recency-aware rankingProactive recall (
mimir_recall_when) — surface memories whose triggers match the current task contextFetch by ID (
mimir_get_entity), time-travel queries (mimir_as_of), and soft-delete (mimir_forget)
Search & RAG
Natural language Q&A (
mimir_ask) — RAG-style question answering over stored memories via a configured LLMGenerate/store dense vector embeddings (
mimir_embed) via Ollama or OpenAI-compatible endpointsSession context injection (
mimir_context) — pre-formatted markdown block of top entities for agent contextIngest external connectors (
mimir_ingest— GitHub issues, file watcher), local documents (mimir_ingest_file— text, markdown, DOCX, PDF), and extract structured knowledge (mimir_extract) via rule-based heuristics
Knowledge Graph
Create typed relationships (
mimir_link), remove them (mimir_unlink), and traverse the graph to configurable depth (mimir_traverse)
Journal & Audit Trail
Append structured events (
mimir_journal) — decisions, observations, actions, errors with actor attributionQuery by time range, event type, or category (
mimir_timeline)
State Management
Key-value store with optional TTL expiration (
mimir_state_set,mimir_state_get,mimir_state_delete,mimir_state_list)
Memory Lifecycle
Ebbinghaus decay scoring (
mimir_decay), bulk pruning (mimir_prune), compaction (mimir_compact), permanent purge with VACUUM (mimir_purge), and autonomous grooming (mimir_cohere,mimir_autocohere)
Quality & Conflict Management
Assign quality scores (
mimir_score), detect contradicting entities (mimir_conflicts), capture corrections for agent learning (mimir_correct), and mark superseded facts (mimir_supersede)
Vault & Federation
Export to Obsidian-compatible markdown (
mimir_vault_export), import back (mimir_vault_import), federate entities between workspaces (mimir_federate), share individual entities (mimir_share), and discover workspaces (mimir_workspace_list)
Metrics, Ops & Learning
Health check (
mimir_health), database statistics (mimir_stats), performance benchmarking (mimir_bench), LLM session synthesis for agent self-improvement (mimir_synthesize), database maintenance — dedup, orphan detection, VACUUM, FTS5 reindex (mimir_maintenance,mimir_reindex), and schema migration (mimir_migrate)
Perseus Vault
Persistent, encrypted memory for AI agents. One Rust binary, one file, no cloud.
Published on Official MCP Registry · Glama · mcpservers.org · Docker (GHCR)
Give your agents memory that survives the session, so they stop re-deriving what they
already learned and stop repeating past mistakes. Hybrid recall (BM25 + dense + RRF),
bi-temporal history, and AES-256-GCM at rest are exposed through a canonical MCP
surface that works with any host. The exact v2.23.2 --no-default-features snapshot
published in the versioned API reference
contains 175 unique canonical tools; counts are release/profile-specific and are
also recorded in the published metadata.json.
The source-checked LongMemEval claim is the fully offline session-level recall
measurement in benchmark/longmemeval/: on the public
_s split (500 questions, 23,867 sessions), the committed hybrid path reaches
83.2% recall@1, 98.8% recall@5, 99.8% recall@10, and 0.8949 MRR against
answer_session_ids. It is judge-free and uses the real binary with bundled local
embeddings; it is a retrieval metric, not end-to-end QA accuracy. The exact
report, harness, and reproduction command are documented in that directory.
Perseus Context Engine resolves the present; Perseus Ledger records the evidence. Vault is the durable-memory layer between them.
One binary. One file. No Docker. No Postgres. No cloud. Local-first, air-gap ready, MIT.
One-Line Install
curl -sSf https://raw.githubusercontent.com/Perseus-Computing-LLC/perseus-vault/main/scripts/install.sh | shThat's it. Perseus Vault is installed to ~/.local/bin/perseus-vault. Start it:
perseus-vault serve --db ~/.perseus-vault/data/perseus-vault.dbEncryption is enabled automatically for the default installation. The first run creates
~/.perseus-vault/secret.keywith owner-only permissions and an encrypted database canary. Back up that key: it cannot be recovered. Explicit--encryption-keypaths remain supported, and existing plaintext databases are preserved for migration withperseus-vault init --rekey. Usedoctorto inspect the actual on-disk state.
macOS note (Apple Silicon). A freshly built or copied binary is SIGKILLed on first run (
Killed: 9, no other output) by the OS binary policy — even with no quarantine attribute. The one-line installer and thebootstrap.shbuild-from-source installer ad-hoc code-sign Perseus Vault for you. If you build the binary yourself, sign it once after each rebuild:cargo build --release cp target/release/perseus-vault ~/.local/bin/perseus-vault codesign --force --sign - ~/.local/bin/perseus-vault # required on Apple Silicon; fixes "Killed: 9"
--forcere-signs an already-signed binary (needed after every rebuild); the step is harmless on Intel macOS and unnecessary on Linux/Windows.
Then wire your MCP client(s) — and the full recall/capture loop — in one command:
perseus-vault install-client --hooks --rulesThis autodetects Claude Code / Codex / Cursor (pass --client <name> for
claude-desktop, hermes, windsurf, vscode, zed, or generic; --all-detected
wires every detected client), merges the MCP server registration into the
client's config without clobbering anything (a .bak-perseus backup is
written first), points every client at one shared memory database,
registers the session lifecycle hooks (recall injection on SessionStart,
hygiene on session end — the docs/lifecycle-hooks.md contract), and appends
the memory usage rules to CLAUDE.md/AGENTS.md. Re-running is a no-op; add
--dry-run to preview every file it would touch.
Or connect any MCP host by hand (Claude Desktop, Cursor, Hermes Agent, Perseus, etc.):
{
"mcpServers": {
"perseus-vault": {
"command": "perseus-vault",
"args": ["serve", "--db", "~/.perseus-vault/data/perseus-vault.db"]
}
}
}Related MCP server: GroundMemory
For Agents: Connect Over MCP
When the primary consumer is an agent, the interface is MCP — the agent adopts the Vault through its MCP client, and no per-machine CLI install is needed beyond running the server itself:
# 1. Run the server (one line)
perseus-vault serve --db ~/.perseus-vault/data/perseus-vault.db &
# 2. Register it in the agent's MCP client config
# { "mcpServers": { "perseus-vault": {
# "command": "perseus-vault",
# "args": ["serve", "--db", "~/.perseus-vault/data/perseus-vault.db"] } } }
# 3. Verify the agent-facing surface
perseus-vault doctorperseus-vault install-client --hooks --rules wires the whole
recall/capture loop for Claude Code / Codex / Cursor / Hermes in one command.
For the agent-facing capability map — which tool does which job, and the
planning-boundary pattern — see
docs/integration/agent-adoption.md.
For the cross-tier architecture and evaluator boundary, see the
Evaluator Guide.
30-Second Quickstart
# Start Perseus Vault
perseus-vault serve --db memory.db &
sleep 1
# Remember a fact (via MCP JSON-RPC on stdio)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"perseus_vault_remember","arguments":{"category":"demo","key":"hello","body_json":"{\"text\":\"Hello from Perseus Vault!\"}"}}}' | perseus-vault serve --db memory.db
# Search for it
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"perseus_vault_recall","arguments":{"query":"Hello"}}}' | perseus-vault serve --db memory.dbMemory model and operational boundaries
Perseus Vault keeps three planes distinct:
Implicit working context is the host's current prompt, transcript, and any context block a client chooses to inject. It is ephemeral and host-owned; it is not persisted merely because Vault returned it.
Explicit durable memory is written by an explicit
perseus_vault_remember,perseus_vault_capture,write, orcaptureoperation. The Vault server owns the SQLite record, history, journal, decay, archive, and purge lifecycle.Derived projections include consolidated or synthesized records and exported Markdown. They carry provenance, but they are not a replacement for the durable source records and may need separate cleanup.
perseus-vault prepare and perseus_vault_context read durable records to
produce a bounded, task-relevant active working context. This is a rolling
snapshot, not a background write or a promise that the client will retain it:
refresh it when the task changes, and do not treat prompt text as durable memory
unless an explicit capture/write operation succeeds. Recall-first output is
budgeted (1500 characters by default, 6000 for large-window hosts, or an
explicit max_context_chars); the always_on set is capped at five. See
retention and context semantics.
Lifecycle hooks and client installers are optional orchestration. They request server-owned recall, capture, maintenance, and refresh work; they do not become a second store or change retention policy. If the server or a hook is unavailable, continue the task without injected memory and surface the degraded state. A host integration may have an explicitly configured local fallback, but that fallback must be labeled local-only and must not be presented as durable Vault recall; a failed explicit write must never be reported as persisted. For upgrade/recovery steps, use the upgrade and migration playbook.
Works With Every MCP Client
Perseus Vault is a standard MCP stdio server — the same perseus-vault serve command works
everywhere. Run perseus-vault doctor to validate your install and print this matrix locally.
Client | Status | Config |
Claude Desktop | ✅ |
|
Claude Code / Hermes | ✅ |
|
Cursor | ✅ |
|
Windsurf | ✅ |
|
VS Code + Continue.dev | ✅ |
|
Zed | ✅ |
|
Codex CLI | ✅ |
|
Copy-paste config snippets for each: docs/clients/.
Then wire the recall → work → capture → consolidate loop to your client's session events (SessionStart/Stop hooks for Claude Code, Codex, and Cursor, plus a portable AGENTS.md fallback): docs/lifecycle-hooks.md.
Composing with a memory washer (CoalWash) and a runtime output compactor (Noisegate) for end-to-end context-budget control: docs/integration/context-budget-stack.md.
Auditing what the Vault remembers, from where, and under which authority: docs/evidence-chain-guidance.md — evidence chains, write-time provenance tags, and continuous attestation for durable memory.
Memory banks (per-client isolation, one profile)
Agency running 50 clients with the same playbook? Don't duplicate profiles — designate the memory bank per project and keep one Hermes profile, one Vault, and one shared skill library:
# .hermes.md
memory_bank: acme-seo # name → deterministic workspace hash
memory_bank_workspace: <64-hex> # optional explicit workspace overrideThe Hermes memory provider
(hermes plugins install Perseus-Computing-LLC/hermes-plugin-perseus-vault)
resolves the bank once per session and scopes every Vault read and write —
prefetch recall, perseus_recall / perseus_remember / perseus_forget,
session-end capture — to a dedicated workspace. Bank names map
deterministically (sha256("memory-bank:" + name)), so every instance
pointing at the same name addresses the same workspace with no registry to
maintain. Workspaces are first-class on the server: scoped maintenance, dedup
isolation between banks, and per-workspace authority manifests. Discovery
mirrors Hermes project-context rules (nearest .hermes.md wins, bounded at
the git root); a context file without a directive means no bank — the
configured workspace stays in effect.
Why Perseus Vault
Perseus Vault is designed to be MCP-native, local-first, zero-dependency, and agent-first.
LongMemEval retrieval (offline, judge-free)
The current public measurement is the reproducible retrieval lane in
benchmark/longmemeval/, not the deprecated
LLM-answer-and-judge experiment. It drives the real binary over MCP stdio and
checks whether a gold evidence session appears in the requested rank window,
using LongMemEval's answer_session_ids on the public _s split.
The committed report covers 500 questions and 23,867 ingested sessions:
path | recall@1 | recall@3 | recall@5 | recall@10 | MRR |
keyword only ( | 4.2% | 12.2% | 19.2% | 33.6% | 0.1069 |
dense | 75.8% | 88.0% | 91.8% | 96.0% | 0.8296 |
hybrid (RRF) | 83.2% | 96.6% | 98.8% | 99.8% | 0.8949 |
These are session-level retrieval metrics: offline, judge-free, and not
end-to-end QA accuracy. Reproduce the exact source-checked report with the
commands in the benchmark README; the committed artifact is
report-currentmain-2026-08-16.json.
The deprecated benchmarks/LONG_MEM_EVAL.md
explains why the earlier model/judge numbers are not used as public claims.
LOCOMO (mem0's own harness)
Measured on mem0's own LOCOMO harness (our fork), not ours — cats 1–4, 1,540q, top-200, gpt-5 answerer + judge:
Engine | Overall | Single | Temporal | Multi | Open-domain |
Perseus Vault 2.20.2 | 87.9% | 89.1 | 92.2 | 85.1 | 70.8 |
Mem0 Platform Starter | 82.2% | 85.0 | 82.9 | 78.0 | 67.7 |
Zep Cloud Flex | 33.8% | 36.9 | 6.9 | 50.0 | 49.0 |
Cat-5 adversarial (446q): Perseus 63.5, Mem0 55.6, Zep 49.8. Our Mem0 measurement is 9.4pts below their published file (judge/platform drift — disclosed). Full leaderboard →
Bi-temporal time-travel (three-axis)
Our strongest structural differentiator — full SQL:2011 bi-temporal history (transaction-time and valid-time) — measured against a reproducible, fully offline gauntlet. It drives the real shipped binary over MCP stdio through the hard cases single-axis competitors get wrong (retroactive corrections, proactive future-dated facts, out-of-order arrival, belief-vs-truth divergence, closed periods):
Axis | Question it answers | Checks | Pass |
valid-time ( | "what was true in the world at T" | 10 | 10 |
transaction-time ( | "what did we believe at T" | 1 | 1 |
bi-temporal ( | "as of belief at T, what was true at V" | 2 | 2 |
Total | 13 | 13 (100%) |
Reproduce with a single command (no API key, no network, no LLM):
cargo build --release
python benchmark/temporal/gauntlet.py --bin target/release/perseus-vaultThe PASS/FAIL verdicts are deterministic (wall-clock timestamps vary, verdicts
do not), so a correct build re-runs to an identical signature_sha256. The
committed gauntlet_report.json is
the reference. Methodology & dataset →
Comparison Matrix
Perseus Vault | Mem0 | Letta | Zep | |
Deployment | Single binary | Cloud + self-host | Docker/Postgres | Docker/Neo4j |
Dependencies | None (SQLite embedded) | Python + vector DB | Postgres + Python | Neo4j + Go (Graphiti) |
MCP-Native | ✅ Versioned canonical MCP surface | ❌ 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 | Versioned; public API reference | 5 | 8 | 0 |
License | MIT | Apache 2.0 | Apache 2.0 | Apache 2.0 |
Full comparison: Perseus Vault vs Mem0 → vs Letta → vs Zep →
Stress Test: 100K Entities
Perseus Vault handles sustained test workloads on modest hardware. The numbers
below are from the committed artifact
benchmark/scale/report.json: the real release
binary driven over MCP stdio (one persistent process per corpus size), AMD64
16-core, Windows 11, every write durable before the next is sent.
Metric | 10K | 100K |
Write throughput, sustained (MCP stdio) | 479 docs/s | 40 docs/s |
Hybrid recall p50 | 19.03 ms | 79.73 ms |
FTS5 recall p50 | 3.14 ms | 15.67 ms |
Full percentiles, as_of point lookups, temporal recall, and cold-start
numbers are in benchmark/scale/.
Run it yourself: python benchmark/scale/run.py
Recall Accuracy at Scale: Keyword Collapses, Hybrid Holds
Speed is table stakes — the question that matters for agent memory is does the
right memory actually surface? Measured on distinct-content corpora (first-party,
reproducible; see benchmark/lambda/), recall@k by mode:
100,000 entities (1×H100, nomic-embed-text on Ollama):
recall@k | keyword (BM25/FTS5) | dense | hybrid (RRF) |
@1 | 0.003 | 0.680 | 0.785 |
@5 | 0.015 | 0.859 | 1.000 |
@10 | 0.029 | 0.899 | 1.000 |
At 100K entities, hybrid recall is perfect @5 while keyword search lands ~1.5% of the time — a ~66× gap. And it widens with scale: at 10K entities keyword recall@5 was 0.008 while hybrid was already 1.000; keyword-only memory silently degrades as an agent accumulates history, hybrid (BM25 + dense + reciprocal-rank fusion) does not. This is the core argument for Perseus Vault's hybrid retrieval.
Head-to-head, same box, same corpus, all fully local (1×H100, Ollama — identical fact set, queries, and substring judge for every system):
System | Recall accuracy | p50 latency | Notes |
Perseus Vault (hybrid) | 1.00 | 35.6 ms | single self-contained binary, in-process |
Letta (archival / pgvector) | 1.00 | 135.5 ms | server + Postgres/pgvector |
Mem0 (vector) | 0.60 | 37.9 ms | Python + vector DB |
Zep (Graphiti temporal KG) | 0.20 | 49.7 ms | server + Neo4j; graph extracted by local model |
Every competitor was stood up and run live on the same box against the same
local Ollama (qwen2.5:14b-instruct + nomic-embed-text) — no cloud, no fabricated
numbers. Letta ran as the letta/letta server (bundled Postgres/pgvector) and matched
Perseus Vault at 1.00. Zep's self-hosted Community Edition server is deprecated and its
zep_python memory API is now Zep Cloud-only, so we measured Zep's actual OSS engine —
Graphiti temporal KG on Neo4j — with entity/edge extraction and embeddings on the same
local Ollama. Its 0.20 reflects the honest cost of building a knowledge graph with a
local model (structured extraction is lossy: 5 entities / 2 edges from 6 facts) — not
Zep Cloud, which uses frontier models. Full artifact + methodology:
benchmark/lambda/results/competitors.json.
Cold-start: a bare GPU box reaches its first grounded RAG answer in 3.3s (models staged on disk).
Reproduce: benchmark/lambda/scale_bench.py and
competitors_bench.py.
Deploying beside a model server on a GPU host (vLLM on MI300X/H100)? See the
AMD MI300X deployment reference — measured
co-residency numbers plus the /dev/shm, PID-1, and version-pinning gotchas
that break these stacks in practice.
Framework Integrations
Ready-to-use adapters that make Perseus Vault the default memory backend for popular AI agent frameworks:
Framework | Integration | Type |
|
| |
| Agent tool | |
|
|
Each adapter:
Connects via MCP stdio subprocess (persistent session)
Maps the framework's memory interface to Perseus Vault tools
Comes with a README quickstart (5 minutes to working)
Has passing tests with mocked MCP transport
Any MCP-compatible framework works with Perseus Vault directly. See MCP client and framework integrations for the full list.
Versioned Canonical MCP Tools
The count is release/profile-specific. The v2.23.2
--no-default-featuressnapshot in the public API reference publishes 175 canonical MCP tools. The reference'smetadata.jsonrecords the source commit, feature profile, generator versions, and raw snapshot digest. New integrations should use the canonicalperseus_vault_*namespace and verify the installed server withperseus-vault doctoror the published snapshot. Historical migration material is isolated indocs/migration/legacy-tool-prefixes.md.
Tool advertisement profiles
The recommended configuration for an LLM agent host is the explicit lean profile:
perseus-vault serve --profile lean --db ~/.perseus-vault/data/perseus-vault.db--profile lean reduces the advertised tools/list response to the core memory
surface: perseus_vault_remember, perseus_vault_recall,
perseus_vault_forget, perseus_vault_correct, perseus_vault_context,
perseus_vault_workspace_status, and perseus_vault_health. In lean mode,
perseus_vault_workspace_status is caller-scoped to the transport-stamped
MCP clientInfo.name and does not disclose other profile/workspace bindings.
The profile is an advertisement reduction, not an authorization boundary; hidden
canonical tools stay available to explicitly governed tools/call requests.
default (the default) and all are equivalent and advertise the complete
canonical registry. The existing PERSEUS_VAULT_TOOL_SCOPE setting can further
reduce the full view for deployments that use the older agent/ops tiers; counts
remain release/profile-specific and must be derived from the checked-in registry.
Tool scopes (advertisement tiers, #1051)
By default tools/list advertises every canonical tool. Set
PERSEUS_VAULT_TOOL_SCOPE to narrow the advertised surface for token- and
attention-constrained agent clients:
Setting | Advertised surface | Count |
| everything | 175 |
| agent surface + operational grooming, maintenance, governance, export | 168 |
| everyday memory + coordination surface (recall / remember / context / handoffs / state, plus the agent-side AAR calls) | 55 |
Scopes are advertisement-only: a hidden tool remains fully callable via
tools/call, and authorization stays with workspace binding and authority
manifests. The tier classification is a 1:1 side table (TOOL_SCOPES in
src/mcp.rs), CI-enforced by scripts/registry_metadata_check.py — every
new tool must be classified. admin-tier tools (migrate, purge,
erase, vault_import, authority_set / authority_revoke /
authority_set_signed) never appear in a scoped list.
For multi-agent or HTTP deployments, set PERSEUS_VAULT_STRICT_SCOPE=1.
Strict scope mode requires every scoped read or mutation to carry a
transport-stamped MCP clientInfo.name, a non-empty workspace_hash, and an
active exact workspace binding. Unbound legacy sessions remain available only
when this deployment gate is explicitly off; they are not a substitute for
authority manifests in a shared deployment.
Entity CRUD
Tool | Description |
| Store/update entity. Idempotent by (category, key); a content change snapshots the prior version into history. |
| Search with FTS5/dense/hybrid modes, filters, stemming expansion. Query contract (#562): |
| Deterministic paginated enumeration of a category or the whole store (#562): immutable |
| Read-only startup-memory hygiene report (#675): scores active memories by "actionability" (concrete anchors — issue keys, #refs, paths, URLs, decisions — vs vague/date-only/short) and lists the worst offenders with reasons, for archive/consolidate curation. |
| Recall from a specific biomimetic layer (world, episodic, semantic). |
| Proactive just-in-time recall: surface entities whose |
| Fetch one entity by ID with full |
| Transaction-time time-travel: the version of a fact (category + key) that was believed at a past instant. |
| Valid-time lookup: the version that was actually true in the world at an instant, per current knowledge (SQL:2011 APPLICATION_TIME). |
| Full 2-axis bi-temporal query: "as of transaction time T, what did we believe was true at valid time V" — the exact rectangle cell. |
| List superseded versions of a fact (category + key), newest first — paginated ( |
| Soft-delete (archived=1). |
Search & RAG
Tool | Description |
| RAG: recall context, query LLM, return grounded answer with sources. |
| Generate dense vectors via the bundled model, Ollama, or OpenAI-compatible endpoint. |
| Dense-only semantic search shortcut — find entities by meaning, ranked purely by embedding similarity (no keyword fallback). |
| Pre-formatted markdown block for session injection. Recall-first by default: pass |
| Trigger connector syncs (GitHub, file watcher); unchanged content is skipped via containment replay (#1050). |
| Extraction-loss net (#1048): retain sentences the extractor missed as residual spans, verbatim with provenance. |
| Extraction-loss net (#1048): refusal-as-signal — re-score spans vs the query, return a retry payload, flag lossy units. |
| Extraction-loss net (#1048): confirm a retry — attach a provisional query key so the identical repeat query serves first-pass. |
| Locally extract a document's text (plaintext/markdown always; DOCX/PDF with the |
| Local, deterministic, rule-based knowledge extraction (facts / preferences / temporal events / episodes) from text or a stored entity. Read-only. |
| Opt-in in-session capture (#520): distill a transcript/insight payload (text, markdown, or JSONL) into durable entities (root-cause / pitfall / decision / pattern / takeaway) the moment a problem is solved. Local rule-based distiller by default, optional |
| Anthropic memory-tool compatible file interface ( |
📖 docs/retrieval-modes.md — one enumerated reference for every retrieval mode (keyword · dense · hybrid · graph · GraphRAG · proactive
recall_when· temporalas_of): mechanism, when to use, invocation, and examples.
Graph
Tool | Description |
| Create typed relationship links between entities. |
| Remove entity links. |
| Walk entity link graph up to configurable depth. |
| GraphRAG community detection over the link graph (deterministic label propagation or greedy-modularity "louvain"; pure Rust, offline). |
| Extractive (optionally LLM-polished) summary of one community, materialized as an entity with |
| GraphRAG global search: breadth over community summaries, then depth into the best communities' members — holistic answers across clusters. |
| Read-only graph/entities/indexes/receipts drift report (#869): unattested, dangling, archived/expired-target, and cross-workspace edges, stale community memberships, FTS drift, journal refs to missing entities. |
| Stamp the from-side entity id as the evidence anchor on legacy edges so they become serveable by the graph recall arms (#869); dry-run preview, journaled. |
Journal
Tool | Description |
| Append structured event with actor attribution. |
| Deja-vu guard: check an action against previously recorded failures (journal + failure/pitfall entities) before retrying it. Read-only. |
| Query journal by time range with filters. |
State
Tool | Description |
| Set key-value state with optional TTL. |
| Get state value. Returns null if expired. |
| Delete state entry. |
| List state keys, optionally filtered by prefix. |
Lifecycle
Tool | Description |
| Recalculate Ebbinghaus decay scores (batched 1000-entity transactions). |
| Bulk archive by category, decay threshold, or age. |
| Permanently delete archived entities + VACUUM. Destructive. |
| Time-based lifecycle sweep: entities past their body |
| Content redaction: scrub a workspace-scoped entity's body to a hash-only marker, delete history + FTS text, keep metadata (re-ingest allowed). Requires explicit |
| Physical erasure of a workspace-scoped entity across ALL derived layers (FTS, history, communities, links, journal) + permanent re-ingest suppression. Requires explicit |
| Autonomous coherence grooming pass — promote, decay, link, archive. |
| Full atomic grooming: cohere → decay → compact in one pass (supports dry-run). |
| Archive entities below decay threshold. |
| Rebuild FTS5 search index from entities table. |
| Merge overlapping/duplicative entities in a category into durable, evidence-tracked observations (mirror image of |
| 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 |
Quality
Tool | Description |
| Assign quality score (0.0-1.0). |
| Detect conflicting entities via trigram similarity; opt-in |
| Structured correction capture for learning from errors. |
| Mark a new fact as superseding an old one (sets the old entity to |
| Record whether an entity was actually FOLLOWED or MISSED — follow-rate efficacy signal that feeds both decay scoring and outcome-weighted recall ranking (#681). |
Keystones (policy rules)
Tool | Description |
| Author a Keystone — a mandatory policy rule that survives context compaction (#683). Scoped (tenant/fleet/agent), weight-ranked, crypto-chained on every mutation; authoring is trust-tier-gated. |
| Fetch the merged Keystones for a scope, ordered by weight (highest first) then scope specificity — the deterministic session-start counterpart to recall. A renderer injects these ahead of all other context. |
| Register/update or look up an agent in the multi-agent registry (#684): identity + trust tier (0-3) + fleet. Trust tier gates sensitive ops (e.g. authoring keystones needs tier ≥ 2) and drives visibility enforcement on recall. |
Vault Transfer (peer federation disabled)
Tool | Description |
| Export entities to .md files with YAML frontmatter. |
| Import from .md vault directory (idempotent). |
| Share one entity (by category + key) into another workspace, preserving content. |
| List all distinct entity categories. |
perseus_vault_federate is intentionally not advertised or executable. Peer
transfer remains disabled until authenticated authority, rollback-capable
custody, conflict handling, and tombstone/erasure propagation are implemented.
Use the explicit vault_export / vault_import tools for reviewed file-based
transfers.
Metrics & Ops
Tool | Description |
| Full DB statistics across all tables. |
| Server and DB health check. |
| Performance benchmark tracking. |
| DB maintenance: dedup, orphan detection, VACUUM, FTS5 reindex (supports dry-run). |
| LLM session synthesis — extract lessons from transcripts. |
| Migrate v0.1.x DB to current schema. |
Tools by job (agent cheat sheet)
Not a category listing — a job listing. Pick the row for what the agent is trying to do:
Job | Tools |
Remember a durable fact / decision / correction |
|
Recall before planning |
|
Reconstruct the development narrative (intent trail, next work) |
|
Decisions: supersession and authority |
|
Ask "what did we believe then?" |
|
Correct the record / surface contradictions |
|
Policy that survives compaction |
|
Ops, trust, and scope |
|
CLI
# Server
perseus-vault serve --db /data/perseus-vault.db
perseus-vault serve --web --port 8767 --encryption-key ~/.perseus-vault/secret.key
perseus-vault serve --llm-endpoint http://localhost:11434/api/generate --llm-model llama3
perseus-vault serve --transport sse --port 8787 --mcp-token my-secret-token
# Maintenance (operate directly on DB, no server needed)
perseus-vault stats --db /data/perseus-vault.db
perseus-vault forget --db /data/perseus-vault.db --category decision --key stale-choice --reason "superseded"
perseus-vault prune --db /data/perseus-vault.db --category junk --min-decay 0.1 --dry-run
perseus-vault purge --db /data/perseus-vault.db --dry-run
perseus-vault decay --db /data/perseus-vault.db
perseus-vault reindex --db /data/perseus-vault.db
perseus-vault vault-export --db /data/perseus-vault.db --vault-dir ./export/
perseus-vault vault-import --db /data/perseus-vault.db --vault-dir ./export/
perseus-vault obsidian-sync ~/obsidian-vault/Perseus Vault/ # one-shot export to an Obsidian vault
perseus-vault obsidian-sync ~/obsidian-vault/Perseus Vault/ --watch # continuous sync on every memory change
# Key management
perseus-vault keygen --key-file ~/.perseus-vault/secret.key
# #918: read-only TUI inspector (retrieval telemetry, claim cards, entity
# state, decay, bi-temporal history). Never writes; repairs go through the
# governed MCP tools. Requires the default `tui` feature.
perseus-vault inspect --db /data/perseus-vault.db --key-file ~/.perseus-vault/secret.keyLive updates without restarting the session
perseus-vault serve detects when its own binary is replaced on disk
mid-session (the normal cargo build / reinstall flow) and refuses to serve
results from the stale process image — every tool answers a loud, explicit
error instead of degrading into empty results (#858, #1045). Two recovery
paths, both on the same stdio connection (no client restart):
Explicit: call
perseus_vault_handoff_restart {"confirm": true}— the process hot-swaps to the new binary and the session continues seamlessly, with the MCP session state (initialization + agent identity) preserved.Automatic (opt-in): launch the server with
PERSEUS_VAULT_AUTO_HANDOFF=1and the swap happens transparently on the next tool call, which the new binary answers directly.
On macOS/Linux the swap is a true exec (same PID, same pipes). Windows
locks a running executable, so mid-session replacement is not possible there;
update across a session boundary. Full contract and the local dev workflow:
docs/specs/live-update-handoff.md.
Manual DB edits. The maintenance verbs above and the normal MCP write path keep the FTS5 index in sync automatically. Editing the
entitiestable directly withsqlite3(a manualDELETE/UPDATE) bypasses that sync and can leave orphaned index rows — "ghost" recall hits for content that is already gone. After any direct SQL edit, runperseus-vault maintain --db <path>(orperseus-vault reindex) to reconcile the FTS index.
Flags
Flag | Description |
| SQLite database path (default: |
| MCP advertisement profile: |
| Start web dashboard |
| Dashboard port (default: 8767) |
| Dashboard bind address (default: 127.0.0.1) |
| MCP transport: |
| Bearer token for SSE/HTTP transport auth |
| AES-256-GCM key file path |
| LLM API endpoint for |
| LLM model name (default: llama3) |
| API key for LLM endpoints (OpenAI, Azure, etc.) |
| OpenAI-compatible embedding endpoint |
| Path to connectors.yaml |
Database location
The canonical database path is:
~/.perseus-vault/data/perseus-vault.dbAlways pass --db (or set $PERSEUS_VAULT_DB_PATH) in scripts, MCP host configs, and
cron/harvest jobs so every invocation targets the same file. When neither is
set, Perseus Vault resolves the default in this order and uses the first that
already exists (so upgraders and legacy single-user installs are picked up
instead of silently starting empty):
~/.perseus-vault/data/perseus-vault.db— canonical (current name)~/.perseus-vault/data/perseus-vault.db— pre-rename~/.perseus-vault/data/perseus-vault.db— pre-rename~/perseus-vault.db— legacy single-user install location
If none exist, it creates ~/.perseus-vault/data/perseus-vault.db. If more than one
of these exists and you did not pass --db/$PERSEUS_VAULT_DB_PATH, Perseus Vault
prints a stderr warning naming the chosen file and the others it ignored, so an
ambiguous multi-database state is visible rather than silent. Setting --db or
$PERSEUS_VAULT_DB_PATH explicitly always wins and suppresses the warning.
Your AI Memory in Obsidian
Perseus Vault is your AI agent's long-term memory — and it doubles as your second brain. Every entity your agent remembers exports to a plain Markdown note with YAML frontmatter, so your AI's memory becomes a navigable personal knowledge base inside the tools you already use: Obsidian, Logseq, or Notion.
# Export your entire memory to an Obsidian vault as linked Markdown notes
perseus-vault obsidian-sync ~/obsidian-vault/Perseus Vault/
# Keep it live — re-export automatically on every memory change
perseus-vault obsidian-sync ~/obsidian-vault/Perseus Vault/ --watchOpen the vault in Obsidian and you get a graph of your agent's knowledge.
WikiLink backlinks. When one entity links to another (via perseus_vault_link or a
depends_on / implements / references relationship), the exported note gets
a ## Links section with [[WikiLink]] backlinks that resolve natively in
Obsidian's graph view:
---
id: cli-de8dfb8364b6
category: architecture
key: api
type: insight
decay_score: 0.5000
---
{"content":"axum service"}
## Links
- [[cli-99756b494c7d|database]] (depends_on)Links resolve by entity id (notes are written as <id>.md) so they never
break, and Obsidian shows the human-readable key as the link label. Open the
graph view and your agent's architecture, decisions, and insights become a
clickable knowledge map.
--watch polls Perseus Vault's cheap, deterministic state digest on an interval and
re-exports only when memory actually changes. It naturally catches every
perseus_vault_remember write with no filesystem-watcher dependency and no coupling to
the server. Tune the interval with PERSEUS_VAULT_SYNC_INTERVAL_SECS (default: 2s).
Other PKM tools
Tool | How |
Obsidian |
|
Logseq | Point |
Notion | Run |
Unlike cloud-only "second brain" tools, Perseus Vault runs 100% local, is written in Rust, encrypts at rest with AES-256-GCM, and applies decay scoring so stale memories fade — your knowledge base stays yours and stays fresh.
Features
Semantic Search (on by default)
Bundled, in-process embeddings — a quantized all-MiniLM-L6-v2 model (384-dim) is compiled into the binary, so dense/semantic search works with zero config and zero network: no Ollama, no API key, no model download. This is the default build (
bundled-embeddingsfeature).Auto-embed on write (#271) —
perseus_vault_rememberembeds each new (or content-changed) entity synchronously as it is written, using the bundled model. Single-entity embedding is deterministic and LRU-cached, so it is cheap and adds no background tasks. Embedding failures are non-fatal (logged to stderr); the write always succeeds.Hybrid is the default recall mode (#271) —
perseus_vault_recall(query=...)with nomodeflag automatically selects hybrid (dense + keyword fused via RRF) whenever embeddings exist, and transparently falls back to fts5 keyword search when none do. No manualperseus_vault_embedstep, no flags to remember.perseus_vault_semantic_search(query, limit)— a one-tool shortcut for pure dense, meaning-based search (no keyword fallback) when you just want "find things like this".Optional alternate embedder — to use Ollama or any OpenAI-compatible
/v1/embeddingsendpoint instead of the bundled model, set--llm-endpoint(and--embedding-endpoint/--llm-api-keyas needed). This is entirely optional; the bundled model is used by default.Build a lean binary without bundled embeddings via
cargo build --no-default-features— recall then defaults to keyword search unless a remote embedder is configured.
Hybrid Search internals
FTS5 keyword search with LIKE fallback and Porter stemming expansion
Dense vector search via cosine similarity on stored embeddings
Reciprocal Rank Fusion (RRF) — combine keyword + vector results
Query expansion — automatic stemming variants for broader recall
Memory Lifecycle
Perseus Vault models memory using three biomimetic layers, inspired by human memory pathways:
World (Core): Slow-decaying, global facts about the environment.
Episodic (Buffer): Fast-decaying, session-specific interaction history.
Semantic (Working): Medium-decaying, general knowledge and learned concepts.
You can interact with these layers directly using the perseus_vault_recall_layer tool or by specifying the layer parameter in perseus_vault_remember.
Ebbinghaus decay — memories naturally fade unless retrieved (refresh on access)
Layer promotion — buffer → working → core based on access frequency
Automatic archival — stale entities archive; purge to permanently delete + VACUUM
Always-on entities — pin identity-critical memories for session injection (hard-capped under recall-first; prefer
recall_whentriggers)Prospective query hints (#919) — optional 1–3 natural-language phrasings per entity (
hintsonperseus_vault_remember) that are indexed into FTS5 alongside the body, bridging vocabulary gaps between plain-language queries and stored wording. Default-off (PERSEUS_VAULT_HINTS_ENABLED=1); rejected while disabled. See docs/specs/prospective-query-hints.md.
Recall-First Context Injection
The vault is the query layer — it retrieves the few facts a turn needs instead of
handing the host a standing blob to staple into every system prompt.
perseus_vault_context and perseus-vault prepare are recall-first by default:
Relevance gating — pass
query(the current task/message) and only entities whoserecall_whentriggers or indexed content match it are injected. No query, no topical injection: the block is a compact retrieval pointer, byte-stable across unrelated vault writes (prefix-cache friendly).Per-model recall budget — output is clamped to a character budget resolved from the host model: default/lean profile 1500 chars; large-window ("opus") profile 6000 chars;
max_context_charsoverrides both.Capped always-on —
always_on: truestill works for identity-critical facts, but the recall-first set is hard-capped (top 5) and overflow emits a warning steering you torecall_whentriggers.Legacy opt-in — the old unconditional top-N dump is still available with
mode: "always_inject"(--legacy-contextforprepare), unclamped unless you pass a budget.
perseus-vault prepare --task "deploying the payments service" --model claude-sonnet-4-6
perseus-vault prepare --task "..." --max-context-chars 800 # explicit budget
perseus-vault prepare --task "..." --legacy-context # old dump, opt-inRAG & Embeddings
perseus_vault_ask— natural language Q&A over stored memories via any LLM (Ollama, OpenAI, etc.)perseus_vault_embed— generate and store dense vectors via Ollama or OpenAI-compatible/v1/embeddingsSupports single-entity and batch-category embedding
Encryption
AES-256-GCM transparent encryption for live/history
body_jsonand query hintsEnabled by default for fresh installs — the standard key is auto-generated at
~/.perseus-vault/secret.keyon first write--encryption-keyflag for explicit keys;perseus-vault keygenfor custom key generationExisting plaintext databases fail closed with an
init --rekeymigration path (or explicitPERSEUS_VAULT_ALLOW_PLAINTEXT=1)Protected FTS5 search uses keyed
hmac-sha256-blind-token-v1tokens for live and historical rows; it does not store body plaintext, but leaks deterministic token relationships
Web Dashboard
Built-in Axum HTTP server (
perseus-vault serve --web --port 8767)Dark-themed dashboard with search, entity table, vis.js graph, timeline
Default bind:
127.0.0.1(use--web-bind 0.0.0.0to expose)Separate SQLite connection in WAL mode for concurrent reads
External Connectors
GitHub issues connector — ingest issues/PRs by repo, rate-limit aware
File watcher — scan directories for
.md/.txt/.jsonfiles with content-hash dedupYAML-based connector config via
--connectors-config
Multi-Transport
stdio (default) — zero-config, works with any MCP host
SSE — Server-Sent Events for HTTP-based MCP clients
HTTP — REST-style MCP endpoint
Bearer token auth — for SSE/HTTP transports
Perseus Integration
Perseus Vault is the default memory backend for Perseus:
perseus_vault:
enabled: true
transport: "stdio"
command: ["perseus-vault", "serve", "--db", "~/.perseus-vault/data/perseus-vault.db"]
timeout_s: 30.0
merge_strategy: "local_first"
fallback_to_local: true
context_categories: ["decision", "architecture", "convention"]
context_limit: 10Government & Federal Procurement
Perseus Vault is built for government deployment from the ground up.
Capability | Status |
License | MIT — no copyleft, no GPL/AGPL |
SBOM | Published — NTIA minimum elements |
Air-gapped | Fully offline — no telemetry, no API calls, no network by default |
Encryption at rest | AES-256-GCM on bodies, enabled by default for fresh installs |
Audit trail | Immutable journal with chain-of-custody |
Supply chain | SLSA attestation in progress |
For federal buyers: See docs/federal-buyers.md for procurement information, compliance status, and deployment models (air-gapped, on-premises, classified environments).
Perseus Computing LLC is a US-owned small business. Current procurement identifiers and owner-published readiness claims are maintained in the public capability statement. Those claims are dated and scoped; they do not constitute CMMC certification, an ATO, or a cATO authorization. NAICS: 541715, 541511, 541512.
Privacy Policy
Perseus Vault is a local-first MCP server — it runs entirely on your machine.
Data Collection
No data collection. Perseus Vault does not collect, transmit, or phone home any user data, usage statistics, or telemetry.
All data remains in your local SQLite database file.
Data Usage & Storage
All memory entities, journal entries, and state are stored locally in a SQLite database at the path you specify via
--db.Optional AES-256-GCM encryption at rest is available — when enabled, entity bodies are encrypted before storage.
No data is shared with Perseus Computing LLC or any third party.
Third-Party Sharing
None. Perseus Vault is fully air-gapped by default. No API calls, no cloud services, no external network requests.
The optional dense vector embeddings feature uses a locally-compiled model — no external embedding API is called.
Data Retention
You control retention with four distinct lifecycle operations (see
docs/specs/data-boundaries-retention-lifecycle.md): soft-delete (perseus_vault_forget, content recoverable), expiry (perseus_vault_expire, time-basedstatus='expired'with content retained), redaction (perseus_vault_redact, content scrubbed to hash-only, metadata kept), and physical erasure (perseus_vault_erase, removal across all derived layers with permanent re-ingest suppression).perseus_vault_purgereclaims space from archived rows.No automatic off-machine backup is performed.
Contact
Email: privacy@perseus.observer
Release Verification
Release binaries are built from tagged commits via GitHub Actions. Every release ships:
Artifact | Description | Verification |
| Full build (bundled embeddings, glibc) | SHA-256 checksum in |
| Lean build ( | SHA-256 checksum in |
SLSA provenance attestation | Sigstore-signed build provenance |
|
Verify a release binary
# 1. Verify SHA-256 checksum
sha256sum -c perseus-vault-lite-x86_64-unknown-linux-musl.tar.gz.sha256
# 2. Verify SLSA build provenance (requires gh CLI + OIDC session)
gh attestation verify perseus-vault-lite-x86_64-unknown-linux-musl.tar.gz \
--repo Perseus-Computing-LLC/perseus-vault
# 3. Confirm the binary identity
./perseus-vault --version
# Should show both the release version AND the git commit hash, e.g.:
# perseus-vault 2.23.2 (v2.23.2-0-gabcdef1)
# 4. Confirm the doctor reports the same identity
./perseus-vault doctor --db /tmp/test.db | head -1
# perseus-vault doctor — v2.23.2 (v2.23.2-0-gabcdef1)Build reproducibly from source
# The exact same binary (bit-for-bit) requires matching:
# - Rust toolchain version (see rust-toolchain.toml)
# - Locked dependencies: `cargo build --locked`
# - Build flags: `--release` for release builds
cargo build --locked --release
./target/release/perseus-vault --versionLicense
MIT — see LICENSE.
Available Tools
43 toolsmimir_askARead-only
Ask a natural language question and get a grounded answer from stored memories via RAG. Internally recalls top-k entities, assembles context, and queries the configured LLM (Ollama) for an answer with cited sources. Requires --llm-endpoint to be set.
Inputs: query (required), top_k. Returns: answer, sources
mimir_as_ofARead-only
Bi-temporal time-travel: return the version of a fact (category + key) that Mimir believed at a given past instant. When a fact is overwritten, the prior version is kept in history; this returns whichever version was live at as_of_unix_ms. Use to answer 'what did we believe about X back then?' or to audit how a fact changed. Returns found=false if the fact had not been recorded yet at that time.
Inputs: key (required), category (required), as_of_unix_ms (required). Returns: id, key, found, status, +4 more
mimir_autocohereADestructive
Run a full atomic grooming pass: cohere (promote, link, archive), then decay (recalculate Ebbinghaus decay), then compact (archive below threshold). Returns a summary report. Use dry_run=true to preview without changes.
Inputs: dry_run. Returns: dry_run, decay_updates, links_created, archived_entities, +3 more
mimir_benchADestructive
Record a performance benchmark data point. Tracks task metrics (turns taken, tokens used, success) alongside whether memory recall was used — enabling measurement of Mimir's impact on agent performance. Aggregate with mimir_recall to analyze trends.
Inputs: tokens_used (required), turns_taken (required), task_description (required), memory_recall_used (required), +4 more. Returns: entity_id, created_at_unix_ms
mimir_cohereADestructive
Run an autonomous coherence grooming pass over the memory. Promotes buffer entities to working layer, applies decay, auto-links related entities, and archives stale ones below the decay threshold. Use dry_run=true to preview without making changes.
Inputs: dry_run, max_links, archive_threshold, promote_threshold. Returns: linked, decayed, dry_run, archived, +3 more
mimir_compactADestructive
Archive entities whose decay score has fallen below a threshold. Supports dry-run mode to preview without making changes. Run periodically or threshold-triggered to keep the database focused on active, high-value memories.
Inputs: dry_run, min_decay. Returns: dry_run, entities_archived, entities_examined, completed_at_unix_ms
mimir_conflictsA
Detect conflicting entities in the same category — pairs with low trigram similarity in their body_json. Flags potential contradictions, duplicate-but-divergent entries, and stale-overwritten facts. Read-only by default. Opt in with resolve=true to actively invalidate the lower-certainty side of clear conflicts (superseding it into history, reversible + time-travelable via mimir_as_of); that path defaults to dry_run=true so you preview first, and never resolves pairs whose certainties are within certainty_margin.
Inputs: category (required), limit, offset, dry_run, +3 more. Returns: conflicts, invalidations
mimir_contextARead-only
Return a pre-formatted markdown context block of the most important entities for session injection. The downstream system (Perseus) uses this to pre-load AI agent context with relevant memories before work begins.
Inputs: limit, categories. Returns: markdown, total_chars
mimir_correctADestructive
Capture a user correction to the agent. Stores what went wrong, what the user said, and the lesson learned — as both a 'correction' entity and a journal entry. Use this every time the user corrects your approach. Enables the self-improving feedback loop: the agent learns from mistakes across sessions.
Inputs: task_context (required), wrong_approach (required), user_correction (required), tags, +3 more. Returns: key, category, entity_id, journal_id, +1 more
mimir_decayADestructive
Recalculate Ebbinghaus decay scores for all entities based on time since last access. Auto-archives entities that have fully decayed (score < 0.05). Run periodically to keep memory fresh — decayed entities surface less often in recall results.
Inputs: no named parameters. Returns: auto_archived, entities_checked, entities_updated, completed_at_unix_ms
mimir_embedADestructive
Generate and store dense vector embeddings for entities via Ollama /api/embed. Supports single entity (category+key) or batch mode (batch_category). Requires --llm-endpoint to be set.
Inputs: key, text, category, batch_limit, +1 more. Returns: embedded, dimensions
mimir_extractARead-only
Extract structured knowledge — facts, preferences, temporal events, episodes — from raw text or a stored entity, using a fully local, deterministic rule-based extractor (no cloud LLM, no embedding/API call, no network). Read-only: never writes to the store. Provide text, or category + key to extract from a stored entity.
Inputs: key, text, category, strategy. Returns: items, total, strategy
mimir_federateADestructive
Federate entities from one workspace to another. Exports entities scoped to from_workspace, remaps their workspace_hash to to_workspace, and imports them — effectively copying or moving knowledge between workspaces. Use this for cross-agent or cross-project knowledge sharing without manual file transfer.
Inputs: to_workspace (required), from_workspace (required), vault_dir. Returns: exported, imported, remapped, import_errors
mimir_forgetADestructive
Soft-delete an entity by setting archived=1. The entity is hidden from queries but recoverable. Use this to clean up stale or incorrect facts without permanent data loss.
Inputs: key (required), category (required), reason. Returns: key, found, category
mimir_get_entityARead-only
Get an entity by ID with its full body_json content. Use after mimir_recall with preview_cap to read the complete body of a truncated result. The drill-down footer embedded in preview-capped results references this tool with the entity ID to use.
Inputs: id (required). Returns: id, key, layer, status, +7 more
mimir_healthARead-only
Check whether the Mimir server and its SQLite database are healthy. Returns a simple healthy/unhealthy status. Use this for health checks and monitoring, not for detailed stats (use mimir_stats).
Inputs: no named parameters. Returns: status
mimir_ingestADestructive
Sync external data connectors (GitHub issues, file watcher) into Mimir. Call with no arguments to run all enabled connectors, or specify a connector name to run only that one. Use dry_run=true to preview without storing.
Inputs: dry_run, connector. Returns: errors, dry_run, ingested
mimir_ingest_fileADestructive
Ingest a document file into memory by extracting its text LOCALLY (no cloud, no network). Plaintext/markdown/structured-text work in any build; DOCX and PDF require a binary built with --features multimodal (otherwise a clear error is returned). The extracted text is stored as a normal entity (recallable via mimir_recall). category defaults to 'document', key defaults to the file name.
Inputs: path (required), key, tags, category. Returns: id, key, chars, action, +1 more
mimir_journalADestructive
Append a structured decision/observation log entry. Uses evaluated/acted/forward pattern: what was considered, what was done, and what happens next. Essential for audit trails and timeline reconstruction.
Inputs: key, acted, forward, agent_id, +4 more. Returns: id, event_type, created_at_unix_ms
mimir_linkADestructive
Create a relationship link from one entity to another. Builds a knowledge graph that mimir_traverse can walk. Use 'depends_on', 'implements', 'extends', 'references', or custom relationships.
Inputs: to_id (required), from_key (required), from_category (required), relationship. Returns: to, from, success, relationship
mimir_maintenanceADestructive
Database maintenance operations: deduplicate entities with identical (category, key), detect orphan journal entries and links, vacuum (reclaim disk space), reindex FTS5. Set dry_run=true to preview. Use 'all' to run everything.
Inputs: all, dedup, vacuum, dry_run, +2 more. Returns: errors, dry_run, dedup_archived, orphan_links_found, +3 more
mimir_migrateADestructive
Migrate a v0.1.x Mimir database to the current v0.5.0 schema. Reads the old database, converts memories to the entity model, and merges into the current database. Use this once per legacy database during upgrade.
Inputs: from_path (required). Returns: errors, entities_created, entities_updated, total_old_memories, +1 more
mimir_pruneADestructive
Bulk archive entities by category, decay threshold, or age. Use dry_run=true to preview without archiving. Useful for cleaning stale or low-quality memories.
Inputs: limit, dry_run, category, min_decay, +1 more. Returns: reason, dry_run, archived, examined
mimir_purgeADestructive
Permanently delete all archived entities and run VACUUM to reclaim disk space. This is the only operation that actually removes entities — prune/forget only soft-archive. Archived entities are DELETED and NOT RECOVERABLE. Supports dry_run=true to preview first.
Inputs: dry_run. Returns: dry_run, bytes_freed, entities_deleted, completed_at_unix_ms
mimir_recallARead-only
Search entities with FTS5 keyword search. Words are OR'd together. Returns entities sorted by relevance with expanded content/summary fields at top level. Use this to find previously stored facts, decisions, or architecture notes. When encryption is enabled, body_json is decrypted transparently.
Inputs: query (required), mode, type, limit, +13 more. Returns: items, total, variants
mimir_recall_whenARead-only
Search entities whose recall_when triggers match a given context. Use this for proactive just-in-time memory injection — before writing code, before plans, at session start. Pass the current task description as context and get back memories that declared they should be recalled in similar situations.
Inputs: context (required), limit. Returns: items, total, context
mimir_reindexADestructive
Rebuild the FTS5 search index from the entities table. Repairs index drift — e.g. after a direct SQLite write, an interrupted archive, or a legacy database written before the atomic prune/forget fixes — so archived entities stop surfacing in recall/search. Returns the number of entities reindexed.
Inputs: no named parameters. Returns: reindexed
mimir_rememberADestructive
Store or update an entity by (category, key). Idempotent — call as often as you want, same key returns an update. Optional always_on=true injects entity into every mimir_context. Optional certainty (0.0-1.0) is used by mimir_conflicts for typed-entity conflict detection. Use this for saving facts, decisions, architecture notes, and conventions. When encryption is enabled, body_json is encrypted at rest with AES-256-GCM.
Inputs: key (required), category (required), body_json (required), tags, +6 more. Returns: id, key, action, category
mimir_scoreADestructive
Assign a quality score (0.0–1.0) to an entity. Verified entities with high scores resist decay and rank higher in recall results. Use this to mark entities as accurate, verified, or deprecated.
Inputs: key (required), score (required), category (required). Returns: key, found, score, category
mimir_state_deleteADestructive
Delete a state entry by key. Permanent removal — unlike mimir_forget which is a soft-delete. Use this to clean up expired or unused state entries.
Inputs: key (required). Returns: key, found
mimir_state_getARead-only
Get a state value by key. Returns null if the key has expired or doesn't exist. Use this instead of mimir_recall for transient session state that doesn't need FTS5 search.
Inputs: key (required). Returns: key, found, value, created_at_unix_ms, +1 more
mimir_state_listARead-only
List all state keys, optionally filtered by a key prefix. Use this to discover what state entries exist without knowing exact keys ahead of time.
Inputs: prefix. Returns: keys, total
mimir_state_setADestructive
Set a key-value state entry with optional TTL for auto-expiration. Use this for session state, temporary flags, or configuration values that should expire after a set time.
Inputs: key (required), value_json (required), ttl_seconds. Returns: key, ttl_seconds, expires_at_unix_ms
mimir_statsARead-only
Return comprehensive database statistics: entity counts by category, type, and decay layer; journal event count; state entry count; database file size; and date range of stored data.
Inputs: no named parameters. Returns: by_type, by_layer, by_category, newest_unix_ms, +5 more
mimir_supersedeADestructive
Create a 'supersedes' relationship from a new fact to an old one, setting the old entity's status to 'deprecated'. Use this when a newer entity makes an older one obsolete.
Inputs: to_key (required), from_key (required), to_category (required), from_category (required), +2 more. Returns: relationship, to_entity_id, to_entity_key, from_entity_id, +4 more
mimir_synthesizeADestructive
LLM-driven session synthesis. Reviews a session transcript and extracts structured lessons: what worked (success), what failed (failure), what was corrected (correction), what was abandoned (dead_end), and key decisions made (decision). Each lesson becomes an entity linked to a synthesis journal entry. Requires --llm-endpoint to be configured. This is the Perplexity-Brain-style overnight synthesis loop for agent self-improvement.
Inputs: session_content (required), tags, session_id, visibility. Returns: dry_run, lessons, journal_id, entities_created, +1 more
mimir_timelineARead-only
Query journal events by time range with optional filters for event type, category, or entity. Use this to reconstruct the decision history and understand what happened when.
Inputs: limit, to_ms, offset, from_ms, +3 more. Returns: items, total
mimir_traverseARead-only
Walk the entity link graph starting from a given entity up to a configurable depth. Returns a chain of linked entities — useful for exploring dependencies, decision trees, and relationship graphs built via mimir_link.
Inputs: key (required), category (required), max_depth, max_nodes. Returns: entity, traversed
mimir_unlinkADestructive
Remove a relationship link from one entity to another. Use this to correct outdated or incorrect links in the knowledge graph.
Inputs: to_id (required), from_key (required), from_category (required). Returns: to, from, success
mimir_vault_exportADestructive
Export all non-archived entities to .md files with YAML frontmatter in a vault directory. Files are human-readable, git-trackable, and Obsidian-compatible. Use this for backup, transfer between workspaces, or offline review.
Inputs: vault_dir. Returns: errors, vault_dir, files_created, files_updated, +1 more
mimir_vault_importADestructive
Import .md files from a vault directory into the database. Reads YAML frontmatter for metadata and markdown body for content. Idempotent — re-running on the same vault won't duplicate entities. Pair with mimir_vault_export for transfer.
Inputs: vault_dir. Returns: errors, vault_dir, files_created, files_updated, +1 more
mimir_workspace_listARead-only
List all distinct entity categories present in the database. Use this to discover what knowledge domains exist before querying with mimir_recall or mimir_context.
Inputs: no named parameters. Returns: total, categories
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 43 tools
Many tools have clearly distinct purposes (e.g., mimir_remember vs mimir_state_set), but there are clustered groups with fuzzy boundaries: prune/compact/decay/cohere/autocohere all perform overlapping maintenance, share/federate both transfer between workspaces, and recall/ask/recall_when all retrieve memories. The detailed descriptions help, but an agent could easily misselect among these sets.
All tools share the mimir_ prefix and use snake_case, which creates a strong sense of predictability. Most are verb-first (remember, recall, ingest, traverse) or verb_noun (state_get, vault_export, workspace_list), with only a few noun-only names (context, stats, health) as minor deviations. Overall naming is consistent and readable.
43 tools is well above the 25+ threshold and feels bloated for a memory server, even one that spans storage, retrieval, graph, state, maintenance, import/export, and LLM features. The scope is broad, but many tools could be consolidated (e.g., compaction/grooming operations, sharing/federation), so the count is excessive for the apparent domain.
The tool set covers the full memory lifecycle: create/update (remember, state_set, journal), read/search (recall, get_entity, ask, timeline), soft-delete (forget, prune), hard-delete (purge), graph relations (link, unlink, traverse, supersede), import/export (vault_import/export), sync (ingest), maintenance, health, and even feedback loops (correct, synthesize, bench). No obvious dead ends or missing operations for the stated purpose.
Maintenance
Related MCP Connectors
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
Persistent, portable memory for AI assistants — your private memory graph, from any MCP client.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Related MCP Servers
AlicenseAqualityCmaintenanceSelf-hosted MCP-native agent memory server. Gives AI agents persistent, decay-weighted memory via 83 MCP tools — no cloud, full control. RocksDB+HNSW backend. Works with Claude Code, Cursor, and any MCP-compatible agent.149MIT- AlicenseNot gradedqualityBmaintenanceAn MCP-native, local-first memory server that gives AI agents persistent, structured memory across sessions and tools, enabling them to maintain identity and context without reconfiguration.3MIT
- AlicenseNot gradedqualityDmaintenancePersistent memory for AI coding agents. Enables agents to save and recall decisions, patterns, bugs, and context across sessions via an MCP server with local SQLite storage.24 npm2MIT
- AlicenseNot gradedqualityBmaintenanceMCP server providing persistent AI memory with four-tier retrieval (SQLite FTS5, graph, vector, LLM agent) to give AI assistants structured, long-term memory without RAG.1Apache 2.0