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 scoping
Search memories (mimir_recall) — FTS5 keyword, dense vector, or hybrid (RRF) search with filters, query expansion, and recency-aware ranking
Proactive recall (mimir_recall_when) — surface memories whose triggers match the current task context
Fetch 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 LLM
Generate/store dense vector embeddings (mimir_embed) via Ollama or OpenAI-compatible endpoints
Session context injection (mimir_context) — pre-formatted markdown block of top entities for agent context
Ingest 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 attribution
Query 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)
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.
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
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.
# 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.dbPerseus 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, or capture
operation. 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.
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.
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.
Perseus Vault is designed to be MCP-native, local-first, zero-dependency, and agent-first.
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.
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 →
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 →
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 →
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
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.
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.
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.
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.
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.
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). |
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.
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. |
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. |
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. |
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 |
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). |
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. |
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.
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. |
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 |
|
# 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.keyperseus-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=1 and 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.
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 |
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.
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).
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.
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-embeddings feature).
Auto-embed on write (#271) — perseus_vault_remember embeds 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
no mode flag automatically selects hybrid (dense + keyword fused via RRF)
whenever embeddings exist, and transparently falls back to fts5 keyword
search when none do. No manual perseus_vault_embed step, 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/embeddings endpoint instead of the bundled model, set --llm-endpoint
(and --embedding-endpoint / --llm-api-key as 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.
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
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_when triggers)
Prospective query hints (#919) — optional 1–3 natural-language phrasings per entity (hints on perseus_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.
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
whose recall_when triggers 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_chars overrides both.
Capped always-on — always_on: true still works for identity-critical
facts, but the recall-first set is hard-capped (top 5) and overflow emits a
warning steering you to recall_when triggers.
Legacy opt-in — the old unconditional top-N dump is still available with
mode: "always_inject" (--legacy-context for prepare), 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-inperseus_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/embeddings
Supports single-entity and batch-category embedding
AES-256-GCM transparent encryption for live/history body_json and query hints
Enabled by default for fresh installs — the standard key is auto-generated at ~/.perseus-vault/secret.key on first write
--encryption-key flag for explicit keys; perseus-vault keygen for custom key generation
Existing plaintext databases fail closed with an init --rekey migration path (or explicit PERSEUS_VAULT_ALLOW_PLAINTEXT=1)
Protected FTS5 search uses keyed hmac-sha256-blind-token-v1 tokens for live and historical rows; it does not store body plaintext, but leaks deterministic token relationships
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.0 to expose)
Separate SQLite connection in WAL mode for concurrent reads
GitHub issues connector — ingest issues/PRs by repo, rate-limit aware
File watcher — scan directories for .md/.txt/.json files with content-hash dedup
YAML-based connector config via --connectors-config
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 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: 10Perseus 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.
Perseus Vault is a local-first MCP server — it runs entirely on your machine.
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.
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.
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.
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-based
status='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_purge reclaims space from archived rows.
No automatic off-machine backup is performed.
Email: privacy@perseus.observer
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 |
|
# 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)# 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 --versionMIT — see LICENSE.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language question to answer from stored memories | |
| top_k | No | Number of top entities to use as context (max 20) |
| Name | Required | Description |
|---|---|---|
| answer | No | Grounded answer with cited sources |
| sources | No | Cited source entities used in the answer |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the readOnlyHint and destructiveHint annotations by detailing the internal process: recalling top-k entities, assembling context, and querying the configured LLM (Ollama) for an answer with cited sources. It also discloses the dependency on the '--llm-endpoint' configuration, which is critical for the tool's operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences. The first sentence clearly states the primary function, and the second adds important internal details and a requirement. No extraneous words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters, full schema coverage, and an output schema (indicated by context), the description covers the key aspects: purpose, internal process (RAG, top-k, LLM), and a configuration requirement. It lacks explicit mention of which memories are queried (e.g., current workspace) but remains sufficiently complete for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for both parameters ('query' and 'top_k'), achieving 100% schema coverage. The description mentions 'Internally recalls top-k entities' which adds marginal context to the 'top_k' parameter but does not significantly enhance understanding beyond the schema. Given high schema coverage, the description adequately complements but does not surpass the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: ask a natural language question and get a grounded answer from stored memories via RAG. It uses a specific verb ('ask') and resource ('stored memories'), and the wording distinguishes it from sibling tools like 'mimir_recall' or 'mimir_synthesize' by emphasizing the natural language Q&A nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite ('Requires --llm-endpoint to be set') but does not provide explicit guidance on when to use this tool versus alternatives (e.g., mimir_recall for raw retrieval, mimir_synthesize for generation without memories). The usage context is somewhat implied through the tool's purpose, but lacking explicit when-not-to-use or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Entity key within the category | |
| category | Yes | Entity category | |
| as_of_unix_ms | Yes | Transaction-time instant (unix ms) to travel to |
| Name | Required | Description |
|---|---|---|
| id | No | |
| key | No | |
| found | No | False if the fact had not been recorded by as_of_unix_ms |
| status | No | |
| category | No | |
| body_json | No | The fact's content as it was at as_of_unix_ms |
| entity_type | No | |
| as_of_unix_ms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds valuable context about history retention ('when a fact is overwritten, the prior version is kept') and the return behavior ('Returns found=false if not recorded yet'). This goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences, each adding value: purpose, history explanation, use cases, return behavior. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown but indicated), the description covers purpose, behavior, and return field ('found'). It lacks mention of error conditions but is sufficiently complete for a time-travel query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description mentions 'category + key' and 'as_of_unix_ms' but uses similar wording as the schema. It does not add significant new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb ('return the version of a fact') and resource ('category + key') and distinguishes from siblings by highlighting time-travel and history. It also gives concrete use cases like 'what did we believe about X back then?'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use to answer...' providing clear context for when to use this tool. It does not explicitly exclude alternatives but implies that for current versions other tools would be used. This is sufficient for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | If true, preview changes without writing |
| Name | Required | Description |
|---|---|---|
| dry_run | No | |
| decay_updates | No | Entities whose decay score was updated |
| links_created | No | Auto-links created during cohere |
| archived_entities | No | Entities archived (cohere + compact) |
| promoted_entities | No | Entities promoted during cohere |
| db_size_delta_bytes | No | Change in SQLite file size in bytes |
| compact_archived_count | No | Entities archived during compact step |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, and the description elaborates on the specific operations (promote, link, archive, recalculate decay) and the atomicity of the pass. It provides behavior beyond annotations, though it could detail what gets archived or destroyed more precisely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences: the first states the action and steps, the second provides the dry_run option. No wasted words, front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the composite nature of the tool and the presence of an output schema, the description adequately covers the operation, steps, atomicity, and dry_run feature. It provides sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the single dry_run parameter (100% coverage). The description reinforces its purpose but adds little new meaning beyond the schema's description. Baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a full atomic grooming pass consisting of cohere, decay, and compact steps, and returns a summary report. This distinguishes it from sibling tools that operate individually (e.g., mimir_cohere, mimir_decay, mimir_compact).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It mentions using dry_run=true to preview without changes, offering conditional guidance. However, it does not explicitly state when to use this composite tool versus running the individual steps separately, leaving some ambiguity for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Tags for categorization | |
| session_id | No | Session identifier for traceability | |
| tokens_used | Yes | Total tokens consumed by the task | |
| turns_taken | Yes | Number of conversation turns the task took | |
| recall_count | No | How many times memory was recalled during this task | |
| task_success | No | Whether the task completed successfully | |
| task_description | Yes | Description of the task being measured | |
| memory_recall_used | Yes | Whether memory recall (mimir_recall) was used during this task |
| Name | Required | Description |
|---|---|---|
| entity_id | No | Created benchmark entity ID |
| created_at_unix_ms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states that the tool records a data point, which aligns with the destructiveHint annotation (modifying state). No contradictions; the annotation handles the behavioral trait, and the description adds the context of what is recorded. However, it does not disclose additional side effects like persistence or idempotency, which is acceptable given annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences (40 words), front-loaded with the action verb 'Record', and contains no redundant information. Every sentence adds value: the first states the primary purpose, the second explains the metrics and relation to mimir_recall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 parameters (4 required) and an output schema (not shown), the description covers the core purpose and the relationship to sibling tools. It mentions the metrics being tracked but does not elaborate on the output schema or optional parameters like tags and session_id, which are adequately documented in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds collective meaning by mentioning the key metrics (turns, tokens, success, memory recall) but does not provide new details beyond what the schema offers. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Record' and clearly identifies the resource as a 'performance benchmark data point'. It lists the tracked metrics (turns, tokens, success, memory recall) and explicitly distinguishes from sibling mimir_recall by noting aggregation for trend analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for recording benchmark data to measure Mimir's impact and directs users to aggregate with mimir_recall for analysis. While it does not list exclusions or alternatives beyond mimir_recall, the context is sufficient for an agent to decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | If true, count what would be done without making changes | |
| max_links | No | Maximum auto-links to create (default 20, max 100) | |
| archive_threshold | No | Decay score below which entities are auto-archived (default 0.05) | |
| promote_threshold | No | Retrieval count threshold for buffer to working promotion (default 3) |
| Name | Required | Description |
|---|---|---|
| linked | No | Number of auto-links created |
| decayed | No | Number of entities whose decay score was reduced |
| dry_run | No | |
| archived | No | Number of entities archived due to low decay |
| promoted | No | Number of entities promoted from buffer to working |
| entities_examined | No | Total non-archived entities examined |
| completed_at_unix_ms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool modifies memory (promotions, decay, auto-links, archives), which aligns with the 'destructiveHint: true' annotation. It adds context beyond the annotation by specifying what changes occur, though it could mention potential side-effects more explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first clearly defines purpose and actions, the second adds a practical tip. No extraneous information, highly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and 100% schema description coverage, the description adequately covers the tool's behavior, parameters, and usage. It lacks nothing essential for an autonomous grooming pass.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 4 parameters with descriptions (100% coverage). The description adds only a minor hint about dry_run. Baseline 3 is appropriate since the schema already provides adequate parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run an autonomous coherence grooming pass over the memory.' It lists specific actions (promotes buffer entities, applies decay, auto-links, archives) that distinguish it from siblings like mimir_compact, mimir_decay, or mimir_prune.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage hint: 'Use dry_run=true to preview without making changes.' It implies the tool is for grooming memory but does not explicitly compare to alternatives or state when not to use it. This is sufficient but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | If true, report what would be archived without making changes | |
| min_decay | No | Decay threshold — entities with decay score below this are archived |
| Name | Required | Description |
|---|---|---|
| dry_run | No | Whether this was a dry run |
| entities_archived | No | Number of entities actually archived (0 in dry-run mode) |
| entities_examined | No | Number of entities checked |
| completed_at_unix_ms | No | Completion timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description confirms destructive behavior via 'archive', aligning with the destructiveHint annotation. It adds the dry-run behavioral trait but does not disclose what archiving entails (e.g., reversibility, data loss). More transparency about consequences would improve this score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose and dry-run support, second suggests usage pattern. No redundant words or fluff; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of output schema (not shown but indicated), the description covers the core action and usage pattern adequately. It could detail consequences of archiving (e.g., recoverability), but overall it is sufficiently complete for a tool with well-documented parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with clear explanations for both parameters ('dry_run' and 'min_decay'). The tool description does not add new meaning beyond reiterating the decay threshold and dry-run mode, so value is marginal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Archive' and the resource 'entities whose decay score has fallen below a threshold'. It specifies the dry-run mode and mentions periodic/threshold-triggered usage, distinguishing it from sibling tools like mimir_prune or mimir_purge.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises to run 'periodically or threshold-triggered' and mentions dry-run mode for previewing. It does not explicitly state when not to use this tool or list alternatives, but the given context is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of conflicts to return / resolve | |
| offset | No | Number of entities to skip for pagination | |
| dry_run | No | When resolve=true, only report what would be invalidated unless set false | |
| resolve | No | Opt-in: invalidate the lower-certainty side of clear conflicts instead of only reporting them | |
| category | Yes | Category to scan for conflicts | general |
| threshold | No | Similarity threshold — pairs below this are flagged as conflicts | |
| certainty_margin | No | Minimum certainty gap to auto-resolve; closer pairs are skipped as ambiguous |
| Name | Required | Description |
|---|---|---|
| conflicts | No | Conflict pairs with similarity scores (detection mode) |
| invalidations | No | Winner/loser pairs invalidated or previewed (resolve mode) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Contradiction: description claims 'Read-only by default' but annotations set readOnlyHint=false, indicating the tool may cause side effects. This inconsistency undermines transparency. Otherwise, description explains behavior well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with main purpose upfront, then details on resolve mode. A bit lengthy but each sentence adds value. Could be slightly more concise, but still effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a complex tool with 7 parameters and output schema. Covers both detection and resolution, safety mechanisms, and parameter behavior. No gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 7 parameters have descriptions in schema (100% coverage). Description adds value by explaining how parameters interact (e.g., dry_run with resolve, certainty_margin for ambiguity) and the trigram similarity context for threshold.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool detects conflicting entities in the same category using trigram similarity on body_json. It distinguishes itself by offering both read-only detection and optional conflict resolution, specifying the exact purpose and key actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context: read-only by default, opt-in with resolve=true, dry_run preview, and certainty_margin to avoid ambiguous resolutions. Could explicitly state when not to use, but still strong guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of entities to include in the context block | |
| categories | No | Categories to include. Empty array = all categories. |
| Name | Required | Description |
|---|---|---|
| markdown | No | Markdown-formatted context block with entity details |
| total_chars | No | Character count of the markdown content |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds behavioral context by specifying the output is pre-formatted markdown and the downstream use case. It does not contradict annotations and provides useful information beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and every word adds value. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of a full input schema (100% coverage), an output schema, and readOnlyHint annotation, the description is sufficient. It explains the output format and use case, but could optionally include details about the structure of the markdown or how 'most important entities' are determined.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for both parameters (limit and categories). The description does not add additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a pre-formatted markdown context block of important entities for session injection, naming the downstream system Perseus. It is specific about the verb (return) and resource (context block), and the purpose is distinct from sibling tools like mimir_recall.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for pre-loading AI agent context before work begins (session injection). However, it does not explicitly state when to avoid using this tool or mention alternatives among the many sibling mimir tools. The guidance is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Tags for categorization | |
| category | No | Entity category (default: 'correction') | correction |
| session_id | No | Session identifier for traceability | |
| visibility | No | Visibility: 'private', 'workspace', or 'public' | workspace |
| task_context | Yes | What task was being attempted when the correction occurred | |
| wrong_approach | Yes | What the agent did that was wrong (the mistaken approach) | |
| user_correction | Yes | What the user said to correct the agent (the right way) |
| Name | Required | Description |
|---|---|---|
| key | No | |
| category | No | |
| entity_id | No | Created correction entity ID |
| journal_id | No | Created journal entry ID |
| created_at_unix_ms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations give destructiveHint: true, which the description aligns with by stating it stores entities. The description adds value beyond annotations by explaining the dual storage (correction entity and journal entry) and the self-improving feedback loop across sessions. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, front-loading the purpose and usage. Every sentence is informative and necessary: first sentence defines the action and storage, second covers when to use and the learning benefit. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters and an output schema (not shown), the description covers the main action, usage, and outcome. It could mention side effects or prerequisites, but the core functionality is well explained for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well documented. The description reinforces the key parameters (wrong_approach, user_correction, task_context) by naming them in prose, adding context that they capture what went wrong and what the user said.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Capture' and the resource 'user correction'. It distinguishes from siblings like mimir_remember and mimir_journal by specifying it stores corrections, not general facts. The phrase 'Use this every time the user corrects your approach' reinforces the specific purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use the tool: 'every time the user corrects your approach'. It does not explicitly list alternatives or when not to use, but the context implies other tools for other purposes, making it clear enough for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| auto_archived | No | Entities auto-archived because decay fell below 0.05 |
| entities_checked | No | Total entities evaluated |
| entities_updated | No | Entities whose decay score changed |
| completed_at_unix_ms | No | Completion timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral detail beyond the destructiveHint annotation by explaining auto-archiving of low-score entities and the effect on recall results. There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently front-load the main action and then provide usage and consequence. Every sentence is valuable, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, clear destructive side effect) and the existence of an output schema, the description covers all necessary aspects: what it does, when to use it, and behavioral outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage, the description's baseline is 4. It adds no parameter information because none is needed, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it recalculates Ebbinghaus decay scores and auto-archives fully decayed entities, specifying both the verb and resource. This distinguishes it from sibling tools like mimir_forget or mimir_purge by its specific decay recalculation purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises running periodically to keep memory fresh, providing clear usage context. However, it does not explicitly exclude use cases or compare alternatives among siblings, so guidance is good but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Entity key for single mode | |
| text | No | Text to embed (omit to use entity body_json) | |
| category | No | Entity category for single mode | |
| batch_limit | No | Max entities in batch mode | |
| batch_category | No | Embed all entities in this category lacking embeddings |
| Name | Required | Description |
|---|---|---|
| embedded | No | Number of entities embedded |
| dimensions | No | Vector dimensions |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description's addition of 'Generate and store' and the dependency on Ollama adds some context. But it doesn't detail what gets overwritten or the exact side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that front-load the purpose and then detail modes and requirements. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 optional parameters and an output schema, the description covers operation modes and prerequisites. It doesn't describe return values, but the output schema likely handles that. It's mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds minimal value beyond the overview of modes. It reiterates the mode logic but doesn't enhance parameter understanding significantly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates and stores dense vector embeddings for entities, distinguishes between single and batch modes, and mentions the Ollama endpoint. This differentiates it from sibling tools like mimir_recall or mimir_remember.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to use single mode (category+key) vs batch mode (batch_category) and notes the requirement for --llm-endpoint. However, it lacks explicit exclusions or alternatives, so it's not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Key of a stored entity to extract from (requires category). | |
| text | No | Raw text to extract from. If omitted, category + key of a stored entity are used. | |
| category | No | Category of a stored entity to extract from (requires key). | |
| strategy | No | Extractor strategy: 'rule_based' (local heuristics) or 'none' (no-op). | rule_based |
| Name | Required | Description |
|---|---|---|
| items | No | Extracted items, each an object with `kind` and `text`. |
| total | No | Number of items extracted |
| strategy | No | Extractor strategy used |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=true), description adds 'never writes to the store' and details on deterministic, local, no-network operation. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences, front-loaded with main purpose. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description covers inputs, usage, and behavioral traits sufficiently. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 100%, description adds clarification on usage of `text` vs `category`+`key` and explains `strategy` enum values (local heuristics vs no-op). Adds meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'extract' and resource 'structured knowledge' from raw text or stored entity. Distinguishes from siblings by specifying local, deterministic rule-based extractor. No tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains usage options: provide `text` or `category`+`key` directly. Does not explicitly list when not to use or alternatives, but clear context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| vault_dir | No | Temporary vault directory for the intermediate .md export files | /tmp/mimir-federate |
| to_workspace | Yes | Target workspace hash to import entities into | |
| from_workspace | Yes | Source workspace hash to export entities from |
| Name | Required | Description |
|---|---|---|
| exported | No | Number of entities exported from the source workspace |
| imported | No | Number of entities imported into the target workspace |
| remapped | No | Number of entities whose workspace_hash was remapped |
| import_errors | No | Any errors encountered during import |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide destructiveHint: true, so description doesn't need to repeat that, but the description says 'copying or moving' without clarifying whether source entities are preserved. No mention of authorization or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: purpose, mechanism, use case. Front-loaded with action verb. No unnecessary words. Efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists and parameter coverage is high. However, the tool involves data transfer and potential destructiveness; the description should clarify what happens to source entities and handling of duplicates. Lacks these details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good parameter descriptions. The tool description reiterates the purpose of each parameter without adding new details beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it federates entities between workspaces via export, remap, import. It distinguishes from manual file transfer but does not explicitly name sibling tools like mimir_vault_export/import or mimir_share, though the usage hint helps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this for cross-agent or cross-project knowledge sharing without manual file transfer', indicating when to use. Lacks explicit when-not-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Entity key to archive | |
| reason | No | Reason for archiving, logged for audit trail | |
| category | Yes | Entity category to archive |
| Name | Required | Description |
|---|---|---|
| key | No | Entity key |
| found | No | Whether the entity was found and archived |
| category | No | Entity category |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description adds that it is a soft-delete (recoverable) and that the entity becomes hidden from queries. This provides useful behavioral context that annotations alone do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the key action and effect. Every sentence adds value: the first explains what it does, the second when to use it. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, presence of an output schema, and full schema parameter descriptions, the description adequately covers purpose, behavior, and usage context. It is sufficient for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already includes descriptions for all three parameters. The description adds no additional meaning beyond what the schema provides, meeting the baseline for this score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('soft-delete an entity'), the mechanism ('setting archived=1'), and the effect ('hidden from queries but recoverable'). It implies a contrast with permanent deletion tools like purging, distinguishing its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use it to 'clean up stale or incorrect facts without permanent data loss,' providing clear context. It does not, however, mention when not to use it or list alternative sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Entity ID to retrieve (from recall result id field or preview cap footer) |
| Name | Required | Description |
|---|---|---|
| id | No | |
| key | No | |
| layer | No | |
| status | No | |
| category | No | |
| always_on | No | |
| body_json | No | Full entity body content |
| certainty | No | |
| decay_score | No | |
| entity_type | No | |
| retrieval_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the readOnlyHint annotation by stating 'Get an entity'. It adds behavioral context that the tool retrieves full body_json content, which is beyond what the annotation provides. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each providing essential information: purpose, usage recommendation, and parameter source. It is efficient with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema present), the description fully covers purpose, usage context, and parameter explanation. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 100%, so baseline is 3. The description adds extra context by explaining that the ID comes from a recall result or preview cap footer, which goes beyond the schema description alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get an entity by ID with its full body_json content', using a specific verb and resource, and distinguishes it from the sibling tool mimir_recall which returns preview-capped results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use after mimir_recall with preview_cap to read the complete body of a truncated result', providing clear context for when to use this tool, though it does not explicitly mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| status | No | Server health status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds that it checks server and DB, and returns simple status, which is useful context but doesn't go beyond what's expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words, front-loaded with purpose and usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully covers what the tool does, when to use it, and what it returns. Output schema exists, so no need to detail return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; baseline 4 applies as description doesn't need to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb (check), resource (Mimir server and its SQLite database), and output (healthy/unhealthy). Distinguishes from sibling mimir_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use for health checks and monitoring, and not for detailed stats, naming the alternative tool mimir_stats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | Preview documents without storing them | |
| connector | No | Specific connector to run (omit for all enabled) |
| Name | Required | Description |
|---|---|---|
| errors | No | Error messages from connectors that failed |
| dry_run | No | Whether this was a dry run |
| ingested | No | Number of documents ingested (or would be ingested in dry run) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint: true, indicating mutation. The description adds context about preview mode (dry_run) and connector selection, but does not detail potential side effects like overwriting or merging behavior, which would be useful. Overall, it adds some value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two sentences), front-loads the main purpose, and avoids any unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations and output schema present, the description adequately covers the tool's purpose, invocation patterns, and preview capability. It does not explain the exact behavior of syncing (e.g., upsert vs replace), but that is likely implied by the tool's name and common patterns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description reiterates the dry_run and connector usage but does not add significant new semantic information beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool syncs external data connectors (GitHub issues, file watcher) into Mimir, distinguishing it from many sibling tools that are about querying, managing, or modifying Mimir data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to call with no arguments (run all enabled connectors) and when to specify a connector, and mentions dry_run for preview. It does not explicitly discuss when not to use it or alternatives, but the context is sufficient for an AI agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Entity key (default: the file name) | |
| path | Yes | Path to the document file to ingest | |
| tags | No | Optional tags | |
| category | No | Entity category (default 'document') |
| Name | Required | Description |
|---|---|---|
| id | No | Stored entity id |
| key | No | |
| chars | No | Characters of text extracted |
| action | No | created or updated |
| category | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors beyond the destructiveHint annotation: it is local-only ('no cloud, no network'), describes format support (plaintext/markdown/structured-text work always, DOCX/PDF require a feature flag), and explains that extracted text is stored as a normal entity recallable via mimir_recall. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact (three sentences) and front-loaded with the core action. Every sentence adds essential information: what it does, where it runs, format quirks, defaults, and recall mechanism. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (format-dependent behavior, local processing, default values), the description covers all necessary aspects: processing location, format support with fallback, default values, and integration with recall. The presence of an output schema is noted but not required for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds valuable defaults: key defaults to file name, category defaults to 'document'. This enriches the schema-defined parameters. The description also implies that path is the primary parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool ingests a document file into memory by extracting text locally. It specifies the verb 'Ingest', the resource 'document file', and the scope (local extraction, no cloud/network). It distinguishes from siblings like mimir_ingest (general ingest) by focusing on file-based ingestion with local text extraction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use the tool (ingesting document files) and mentions limitations (DOCX/PDF require --features multimodal, otherwise error). It does not explicitly list when not to use, but the context is sufficient. It implies an alternative (mimir_recall for retrieval) but does not contrast with other ingest tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Related entity key for linking | |
| acted | No | What action was taken and why | |
| forward | No | What the plan is going forward | |
| agent_id | No | Agent identity (v1.2.0). Records which agent created this journal event. | |
| category | No | Related entity category for linking | |
| entity_id | No | Related entity ID for linking | |
| evaluated | No | What was evaluated: options considered, context, constraints | |
| event_type | No | Event type: 'decision', 'observation', 'action', 'error' | decision |
| Name | Required | Description |
|---|---|---|
| id | No | Journal event ID |
| event_type | No | Event type recorded |
| created_at_unix_ms | No | Creation timestamp in unix milliseconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint: true, suggesting the tool may have destructive side effects, but the description only says 'Append,' which implies additive behavior. No explanation of why it's destructive, what gets destroyed, or other behavioral traits beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states the purpose, the second explains the pattern. No superfluous content. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (not shown but present), the description does not need to explain return values. Parameter count is 8, all described in schema and enriched by pattern explanation. The description is complete for a logging tool with clear audit trail purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 8 parameters. The description adds value by explaining the 'evaluated/acted/forward' pattern, which provides context for how parameters like 'evaluated', 'acted', and 'forward' relate to each other, enriching the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Append a structured decision/observation log entry.' It uses specific verbs ('append', 'log') and names the resource ('decision/observation log entry'). Sibling tools like mimir_recall and mimir_context are differentiated by this logging focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'essential for audit trails and timeline reconstruction' but does not explicitly state when to use this tool versus alternatives (e.g., mimir_recall for retrieval, mimir_context for context). No exclusions or alternative suggestions are provided, leaving ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| to_id | Yes | Target entity ID (from mimir_remember return value) | |
| from_key | Yes | Source entity key | |
| relationship | No | Relationship type: 'depends_on', 'implements', 'extends', 'references', or custom | related |
| from_category | Yes | Source entity category |
| Name | Required | Description |
|---|---|---|
| to | No | Target entity ID |
| from | No | Source as 'category/key' |
| success | No | |
| relationship | No | Relationship type set |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description confirms the link creation is destructive (as per destructiveHint) but adds no further behavioral context beyond building a graph. Since annotations already flag destructiveness, the description provides marginal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loading the key action and purpose. Every sentence adds necessary context without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters and an output schema. The description covers the core functionality and relationship types, but omits prerequisites (e.g., entities must exist) and potential side effects. Given the output schema exists, the gap is moderate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already documented. The description mentions relationship types, which are also in the schema's 'relationship' parameter description. Thus, no significant extra meaning is added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and resource ('relationship link from one entity to another'), clearly stating the purpose. It distinguishes from sibling tools like mimir_unlink and mimir_traverse by explaining that it builds a knowledge graph for traversal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists allowed relationship types ('depends_on', 'implements', 'extends', 'references', or custom) and connects it to mimir_traverse. While it doesn't state when not to use, the sibling name mimir_unlink implies the complementary operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Run all maintenance operations (dedup, orphans, vacuum, reindex) | |
| dedup | No | Find duplicate (category, key) entities and archive the oldest | |
| vacuum | No | Run SQLite VACUUM to reclaim disk space | |
| dry_run | No | If true, preview changes without writing | |
| orphans | No | Detect journal entries and links pointing to non-existent entities | |
| reindex | No | Rebuild the FTS5 search index from entities table |
| Name | Required | Description |
|---|---|---|
| errors | No | Errors encountered during maintenance |
| dry_run | No | |
| dedup_archived | No | Number of duplicate entities archived |
| orphan_links_found | No | Orphan links detected |
| reindex_rows_affected | No | Rows reindexed into FTS5 |
| vacuum_reclaimed_bytes | No | Disk space reclaimed by VACUUM |
| orphan_journal_entries_found | No | Orphan journal entries detected |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that deduplication archives the oldest entity, vacuum reclaims disk space, and reindex rebuilds FTS5. It also mentions dry_run for preview. This adds detail beyond the 'destructiveHint' annotation, though it does not specify whether orphan detection deletes or only lists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first immediately states the tool's purpose and lists operations, the second gives actionable usage tips. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a maintenance tool with 6 boolean parameters and an output schema, the description covers the key operations and gives usage hints. It doesn't mention prerequisites or safety notes, but the destructiveHint annotation and dry_run option partially address that. Overall, it is sufficient for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, each parameter already has a description. The description adds value by showing how to combine parameters (dry_run with all) and the general usage pattern, providing context beyond the schema's individual definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly lists the specific maintenance operations (deduplicate, detect orphans, vacuum, reindex) and states it covers database maintenance. This clearly distinguishes it from sibling tools like mimir_ask or mimir_compact by its domain and actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives basic usage tips (dry_run=true to preview, use 'all' to run everything) but does not explain when to prefer this tool over individual siblings like mimir_prune or mimir_reindex. There is no explicit when-not or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| from_path | Yes | Absolute path to the v0.1.x SQLite database file to migrate |
| Name | Required | Description |
|---|---|---|
| errors | No | Any errors encountered during migration |
| entities_created | No | New entities created from old memories |
| entities_updated | No | Existing entities updated during merge |
| total_old_memories | No | Number of memories found in the old database |
| completed_at_unix_ms | No | Completion timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the process (reads old DB, converts, merges) adding behavioral context beyond the destructiveHint annotation, confirming it modifies the current database.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the main action without any extraneous words, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description covers purpose, process, and usage comprehensively for a one-time migration tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage and only one parameter fully described in the schema, the description adds no additional parameter meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool migrates a v0.1.x Mimir database to v0.5.0 schema, distinguishing it from siblings that perform other operations like ask or forget.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use this once per legacy database during upgrade' provides explicit when-to-use context, but no exclusions or alternatives are mentioned, which is acceptable given the one-time migration nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max entities to prune (0 = unlimited) | |
| dry_run | No | Preview without archiving | |
| category | No | Archive entities in this category | |
| min_decay | No | Archive entities with decay_score below this threshold | |
| older_than_days | No | Archive entities older than this many days |
| Name | Required | Description |
|---|---|---|
| reason | No | |
| dry_run | No | |
| archived | No | |
| examined | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide destructiveHint=true; description adds that dry_run allows preview and mentions cleaning purpose, but does not detail what 'archive' entails (e.g., reversibility, side effects) or how entities are affected beyond filtering criteria.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states action and criteria, second provides a tip and use case. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, destructive behavior, and an output schema, the description covers core action and a preview tip but omits behavioral details (e.g., what 'archive' means, error handling, or output format). Output schema exists, so return values need not be explained, but other gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with descriptions for all parameters. Description adds context for dry_run and relates cleaning to decay/age, but this is minimal beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it bulk archives entities by category, decay threshold, or age, with the verb 'archive' and resource 'entities'. It hints at cleaning stale memories but does not explicitly distinguish from siblings like mimir_forget or mimir_purge.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance to use dry_run=true for preview and states it's useful for cleaning stale memories, but lacks explicit when-not-to-use or alternative sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | If true, report what would be deleted without making changes |
| Name | Required | Description |
|---|---|---|
| dry_run | No | Whether this was a dry run |
| bytes_freed | No | Bytes reclaimed after VACUUM (0 in dry-run mode) |
| entities_deleted | No | Number of archived entities permanently deleted |
| completed_at_unix_ms | No | Completion timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description explicitly states that archived entities are deleted and NOT RECOVERABLE, and that VACUUM is performed. This adds crucial behavioral context not captured by annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences convey the core action, context, sibling differentiation, and parameter hint. No wasted words; front-loaded with the primary function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema covers return values, the description fully addresses what the tool does, side effects (irreversibility), comparison to siblings, and parameter usage. Complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds value by explaining that dry_run=true allows preview without changes, which clarifies the parameter's purpose beyond its schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: permanently delete archived entities and run VACUUM. It distinguishes from sibling tools (prune/forget) by specifying that it is the only operation that actually removes entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that this tool is for permanent deletion versus soft-archive from prune/forget, and mentions dry_run preview. It does not explicitly state prerequisites or when not to use, but the contrast with siblings provides sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Search mode: 'fts5' (keyword), 'dense' (vector), or 'hybrid' (fused via RRF) | fts5 |
| type | No | Filter by entity type, e.g. 'insight' or 'reference' | |
| limit | No | Maximum number of results to return (max 1000) | |
| query | Yes | Search query — words are OR'd together for broad recall | |
| offset | No | Number of results to skip for pagination | |
| agent_id | No | Agent identity filter (v1.2.0). When set, only entities with a matching agent_id are returned. Omit for no agent filtering. | |
| category | No | Filter by category, e.g. 'decision' or 'architecture' | |
| expansion | No | Configuration for FTS5 query expansion using Porter stemming | |
| min_decay | No | Minimum decay score threshold 0.0–1.0 — higher values return fresher results | |
| topic_path | No | Filter by topic path prefix, e.g. 'architecture/' | |
| preview_cap | No | If set, truncate body_json at N chars and append drill-down footer. Use mimir_get_entity to read full body. | |
| trust_weight | No | Additive boost for provenance/trust (default 0.15, on by default) — verified sources rank above unverified AI drafts on the same topic. Verified entities get the full boost; unverified ones are scaled by certainty. Set 0 to disable. Never penalizes. | |
| content_weight | No | Additive boost for content witness — rewards entities whose body text literally contains query terms. Damped by body length. Never penalizes. | |
| workspace_hash | No | Workspace scope filter (v1.2.0). When set, only entities with a matching workspace_hash are returned. Omit for no workspace filtering. | |
| include_archived | No | Include archived (soft-deleted) entities in results | |
| diversity_halving | No | Per-keyword diversity quota factor (1.0=disabled). Each distinct matched keyword gets ceil(N x halving^n) slots — first keyword N, second N/2, etc. | |
| recency_half_life_secs | No | Time-aware ranking for mode='hybrid' (default off). When set, each fused result's score is multiplied by 0.5^(age / this), where age is seconds since the memory was created — so a memory this many seconds old keeps half its weight and recent context outranks older but similar hits. Omit for relevance-only ranking. |
| Name | Required | Description |
|---|---|---|
| items | No | Matching entities with expanded body_json fields at top level |
| total | No | Number of results returned |
| variants | No | Number of query variants used when expansion is enabled |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true; description adds valuable behavioral details: OR'ing of words, relevance sorting, expanded fields, and transparent decryption of body_json, which is beyond what annotations offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with key information, no fluff. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite a complex tool with 17 parameters and output schema, the description omits mention of search modes (fts5, dense, hybrid) and filtering capabilities, leaving gaps for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter already described; the tool description adds no extra meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it searches entities with FTS5 keyword search, but does not explicitly differentiate from sibling tools that may offer alternative search methods like vector or hybrid.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides use cases (find facts, decisions, architecture notes) but lacks explicit guidance on when not to use or when alternatives like mimir_recall_when might be better.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum entities to return (default 10, max 100) | |
| context | Yes | The current task or context description to match against recall_when triggers |
| Name | Required | Description |
|---|---|---|
| items | No | |
| total | No | |
| context | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is clear. The description adds behavioral context (proactive, context-matching) but does not detail edge cases (e.g., no match behavior, performance). With annotations covering the main safety aspect, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence defines the function, the second gives concrete usage scenarios. Front-loads key information efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (2 params, output schema present), the description covers purpose, usage, and context. With output schema, return details are not needed. Some might expect a note on default limit, but schema covers that. Score 4 reflects slight gap in explaining the 'recall_when trigger' concept.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are documented. The description adds minimal extra meaning beyond the schema: it reinforces that 'context' is the task description to match triggers. This is marginal improvement, hence baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches entities based on recall_when triggers matching a given context. It uses specific verb and resource ('Search entities whose recall_when triggers match') and distinguishes from sibling tools like mimir_recall by focusing on trigger-based recall.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: 'for proactive just-in-time memory injection — before writing code, before plans, at session start.' It implies usage context but does not explicitly mention when not to use or name alternatives like mimir_recall.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| reindexed | No | Number of non-archived entities indexed into FTS5 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true. The description adds the return value (number reindexed) and specific triggers, but does not disclose other behavioral traits like potential locking, idempotency, or performance impact, which would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence states the action, the second provides context and return. Efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with destructive hint and output schema, the description covers purpose, triggers, and return. Could mention whether it is safe to run repeatedly, but overall sufficient given low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so no parameter documentation is needed. Baseline is 4 for zero-parameter tools, and the description does not need to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool rebuilds the FTS5 search index, with specific triggers like direct SQLite writes or interrupted archives. It distinguishes from siblings by focusing on index drift repair for recall/search, though it could explicitly contrast with other maintenance tools like mimir_compact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists when to use the tool (after direct SQLite write, interrupted archive, legacy database). It does not provide when-not-to-use or alternatives, but the context is sufficiently clear for the intended use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Unique key within the category, e.g. 'use-postgres-16' or 'deployment-strategy' | |
| tags | No | Tags for categorization and cross-referencing | |
| type | No | Entity type: 'insight', 'architecture', 'decision', 'reference', 'convention' | insight |
| status | No | Entity status: 'active', 'draft', 'deprecated' | active |
| agent_id | No | Agent identity (v1.2.0). Tracks which agent wrote this entity. Used for agent attribution and context filtering. | |
| category | Yes | Entity category: 'decision', 'architecture', 'convention', 'insight', or custom | |
| body_json | Yes | JSON object with the entity body — store content, summary, and any custom fields here | |
| importance | No | Initial importance 0.0–1.0 — sets the starting decay score | |
| topic_path | No | Hierarchical topic path, e.g. 'architecture/database/postgres' | |
| workspace_hash | No | Workspace scope identifier (v1.2.0). Empty = global. Entities with a workspace_hash are invisible to recall queries scoped to a different workspace. |
| Name | Required | Description |
|---|---|---|
| id | No | Entity ID, e.g. 'mem-a1b2c3d4e5f6' |
| key | No | Entity key |
| action | No | 'created' for new entities, 'updated' for existing ones |
| category | No | Entity category |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral details beyond the annotations: idempotency, encryption at rest (AES-256-GCM) when enabled, and the effect of always_on=true injecting into mimir_context. This complements the destructiveHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of four clear sentences. It front-loads the core function and immediately follows with key behaviors and use cases. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (10 parameters, 3 required), the description covers essential aspects: idempotency, encryption, always_on, certainty usage, and appropriate use cases. An output schema exists, so return values need not be described. It could mention behavior on conflict or error, but overall it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the schema already documents all parameters. The description adds context for key parameters (e.g., key as unique within category, body_json as JSON object) and explains the purpose of optional fields like always_on and certainty. It does not cover every parameter in detail but provides meaningful usage guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Store or update an entity by (category, key)' and lists specific use cases such as saving facts, decisions, architecture notes, and conventions. This distinguishes it from sibling retrieval or deletion tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions when to use the tool ('for saving facts, decisions, architecture notes, and conventions') and describes optional parameters like always_on and certainty. However, it does not explicitly state when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Entity key to score | |
| score | Yes | Quality score 0.0–1.0. 1.0 = verified, 0.5 = neutral, 0.0 = low quality | |
| category | Yes | Entity category to score |
| Name | Required | Description |
|---|---|---|
| key | No | Entity key |
| found | No | Whether the entity was found |
| score | No | Quality score assigned |
| category | No | Entity category |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description adds that high scores resist decay and rank higher, but lacks details on idempotency, reversibility, or required permissions. The behavioral context is sufficient but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the action and followed by consequences. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple scoring tool, the description covers purpose, effect, and usage. It does not explain the output format, but an output schema exists. It could mention prerequisites or error cases, but overall it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. The description does not add new meaning beyond what the schema provides for the three parameters. The baseline of 3 is appropriate as the schema already documents parameters clearly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Assign', the resource 'entity', and the score range 0.0-1.0. It explains the effect on decay and recall ranking, and lists usage scenarios (mark as accurate, verified, deprecated). This distinguishes it well from the many sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use the tool (to assign quality scores and mark entities) and hints at the consequences. However, it does not explicitly state when not to use it or compare to alternatives, which would further improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | State key to permanently delete |
| Name | Required | Description |
|---|---|---|
| key | No | Key that was deleted |
| found | No | Whether the key existed and was deleted |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, indicating the tool is destructive. The description adds that deletion is permanent and contrasts with soft-delete, providing useful context beyond the annotation. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each serving a distinct purpose: first states the action, second adds usage guidance and sibling differentiation. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema (present), the description adequately covers purpose, usage, and behavioral nuance. It is complete for the agent to correctly select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes the key parameter as 'State key to permanently delete'. The description mentions 'by key' but does not add substantial meaning beyond the schema, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a state entry by key, using a specific verb and resource. It distinguishes from the sibling tool mimir_forget, which is a soft-delete, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use: 'Use this to clean up expired or unused state entries.' Also clarifies when not to use by contrasting with mimir_forget, providing clear context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | State key to retrieve |
| Name | Required | Description |
|---|---|---|
| key | No | State key requested |
| found | No | Whether the key exists and hasn't expired |
| value | No | JSON value if found |
| created_at_unix_ms | No | Creation timestamp |
| expires_at_unix_ms | No | Expiration timestamp if TTL was set |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds behavioral detail beyond annotations by stating 'Returns null if the key has expired or doesn't exist,' which informs the agent about return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The description is front-loaded with the action, then provides return behavior and usage guidance, all in a compact form.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, output schema exists), the description covers purpose, null handling, and when to use, which is adequate. A minor gap is no mention of expiration behavior details, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents the 'key' parameter. The description does not add extra meaning beyond what is in the schema, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a state value by key' with a specific verb and resource. It distinguishes itself from the sibling tool mimir_recall by mentioning transient session state and FTS5 search, ensuring no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use this instead of mimir_recall for transient session state that doesn't need FTS5 search.' This clearly tells the agent when to use this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| prefix | No | Only return keys that start with this prefix |
| Name | Required | Description |
|---|---|---|
| keys | No | Matching state keys |
| total | No | Number of keys returned |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so description adds value by specifying the listing behavior and prefix filtering, but could mention potential limits or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences: first defines action, second provides use case. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given presence of an output schema and single optional parameter, description is mostly complete; could explicitly state that it returns a list of keys.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a documented prefix parameter; description restates the parameter briefly but adds no new details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists all state keys with optional prefix filtering, distinguishing it from sibling tools like mimir_state_get, mimir_state_set, and mimir_state_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context about when to use (discover state entries without exact keys) but does not explicitly mention when not to use or contrast with alternatives like mimir_state_get.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | State key — unique identifier for this state entry | |
| value_json | Yes | JSON value to store | |
| ttl_seconds | No | Time-to-live in seconds. Entry auto-expires and returns null after this duration. Omit for permanent state. |
| Name | Required | Description |
|---|---|---|
| key | No | State key set |
| ttl_seconds | No | TTL that was set, if any |
| expires_at_unix_ms | No | Expiration timestamp in unix milliseconds, if TTL was set |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark destructiveHint=true. Description adds TTL auto-expiration and permanent state option. Does not explicitly mention overwriting behavior, but that is implied by 'Set' and output schema may cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. First sentence states function, second gives usage context. Perfectly compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple setter with 3 parameters. Covers purpose, use cases, and TTL behavior. Output schema likely handles return values. Missing explicit overwriting note, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. Description reinforces TTL parameter purpose and connects to use cases, adding marginal semantic value beyond schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set a key-value state entry' with a specific verb and resource. It distinguishes itself from sibling state tools (get, delete, list) by focusing on creation/update with optional TTL.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases: session state, temporary flags, configuration values with TTL. Does not specify when not to use or contrast with alternatives like mimir_remember, but the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| by_type | No | Entity counts grouped by type |
| by_layer | No | Entity counts grouped by decay layer (buffer/working/core) |
| by_category | No | Entity counts grouped by category |
| newest_unix_ms | No | Newest entity creation timestamp |
| oldest_unix_ms | No | Oldest entity creation timestamp |
| total_entities | No | Total entities in the database |
| db_file_size_bytes | No | Database file size on disk in bytes |
| total_state_entries | No | Total state entries (including expired) |
| total_journal_events | No | Total journal events recorded |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, which is consistent with the description. The description adds value by detailing exactly what statistics are returned, which goes beyond the annotation's simple read-only indication. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently enumerates all returned statistics without redundancy. It is front-loaded with the main verb and resource, and every phrase adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists (as per context signals), the description is complete. It covers all aspects of the output, and the agent can rely on the output schema for detailed structuring.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so the description doesn't need to explain parameters. However, it compensates by describing the output, which is useful for an agent. Baseline for 0 params is 4, and this description meets that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Return') and clearly lists the types of statistics (entity counts by category, type, decay layer; journal count; state count; file size; date range). It distinguishes itself from sibling tools like 'mimir_health' which likely focuses on system status, whereas this focuses on database content statistics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly states its purpose (obtaining comprehensive stats), and given there are no parameters or configuration, the use case is clear. It doesn't explicitly state when not to use, but the context of sibling tools provides differentiation. A score of 4 is appropriate as it's clear but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Reason for superseding (recorded in archive_reason) | |
| to_key | Yes | Key of the NEW entity that supersedes | |
| from_key | Yes | Key of the OLD entity being superseded | |
| to_category | Yes | Category of the NEW entity that supersedes | |
| relationship | No | Link relationship type (default: 'supersedes') | supersedes |
| from_category | Yes | Category of the OLD entity being superseded |
| Name | Required | Description |
|---|---|---|
| relationship | No | |
| to_entity_id | No | ID of the new (superseding) entity |
| to_entity_key | No | |
| from_entity_id | No | ID of the old (superseded) entity |
| status_updated | No | New status of the old entity (always 'deprecated') |
| from_entity_key | No | |
| to_entity_category | No | |
| from_entity_category | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate destructiveHint=true, but the description adds that the old entity's status becomes 'deprecated', which is valuable behavioral context. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Purpose and usage are front-loaded, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description doesn't need to explain return values. It completely covers purpose, effect, and usage for this focused tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline 3. The description does not add extra meaning beyond the schema; the schema already describes each parameter clearly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it creates a 'supersedes' relationship from new to old fact and sets old entity to 'deprecated'. The verb 'Create' and resource 'supersedes relationship' are specific, distinguishing it from generic linking tools like mimir_link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this when a newer entity makes an older one obsolete.' Provides clear context for when to use. No exclusions or alternatives mentioned, but the sibling tools list includes many others, so this is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Tags applied to all synthesized entities | |
| session_id | No | Session identifier for traceability | |
| visibility | No | Visibility for synthesized entities | workspace |
| session_content | Yes | Full session transcript to synthesize lessons from |
| Name | Required | Description |
|---|---|---|
| dry_run | No | |
| lessons | No | Extracted lessons with type, summary, evidence, and confidence |
| journal_id | No | |
| entities_created | No | Number of lesson entities created |
| completed_at_unix_ms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true. The description adds that the tool creates entities linked to a journal entry, implying state mutation. But it does not detail the extent of destruction (e.g., whether prior entities are overwritten) or other side effects beyond creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) and front-loads the core purpose. Every sentence adds value: describing the action, the output structure, a prerequisite, and the broader goal. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 params, output schema exists), the description covers the synthesis process and prerequisite. It does not need to explain return values due to output schema. Minor gap: no mention of error conditions or performance implications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter having a description. The description adds minimal extra meaning beyond listing the lesson types and mention of tags/session_id/visibility in context, but does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs 'session synthesis' and extracts specific structured lessons (success, failure, correction, dead_end, decision). It distinguishes itself from sibling tools like mimir_ask or mimir_ingest by focusing on post-session analysis and entity creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It mentions the prerequisite 'Requires --llm-endpoint to be configured' and positions the tool as an 'overnight synthesis loop for agent self-improvement', implying a use case. However, it lacks explicit when-not-to-use or alternatives, leaving interpretation open.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of events to return (max 1000) | |
| to_ms | No | End time boundary in unix milliseconds | |
| offset | No | Number of events to skip for pagination | |
| from_ms | No | Start time boundary in unix milliseconds | |
| category | No | Filter by related entity category | |
| entity_id | No | Filter by related entity ID | |
| event_type | No | Filter by event type: 'decision', 'observation', 'action', 'error' |
| Name | Required | Description |
|---|---|---|
| items | No | Journal events matching the query |
| total | No | Number of events returned |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description's 'Query' aligns with that. The description adds context about reconstructing history but does not disclose additional behavioral traits like rate limits or data retention. With annotations present, the description provides marginal extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences that efficiently convey the tool's purpose and recommended use. No superfluous information; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 optional parameters with defaults) and the availability of an output schema, the description covers the core use case. It does not mention pagination or time format details, but the schema handles those. Slight lack of completeness in explaining how filters combine.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description summarizes optional filtering by event type, category, or entity but does not add deeper semantics or syntax details beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Query' and resource 'journal events' with time range and optional filters. It provides a specific use case ('reconstruct decision history') but does not explicitly differentiate from sibling tools like mimir_journal or mimir_recall.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description suggests using the tool to reconstruct decision history, implying a usage context. However, it does not specify when not to use it or mention alternative tools for related queries, leaving room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Starting entity key | |
| category | Yes | Starting entity category | |
| max_depth | No | Maximum traversal depth from the starting entity | |
| max_nodes | No | Maximum total nodes to traverse before stopping |
| Name | Required | Description |
|---|---|---|
| entity | Yes | Root entity with its links |
| traversed | Yes | Linked entities traversed from root |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, indicating no side effects. The description adds that the tool walks the graph to a configurable depth and returns a chain of linked entities, which provides additional behavioral context beyond the annotation. It also mentions stopping conditions (max_depth, max_nodes). No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and result. Every sentence adds value: first sentence describes what the tool does, second gives use cases. No redundancy or unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters and an output schema exists, the description adequately covers the input (starting entity, configurable limits) and purpose (exploring graphs). It omits details about output format but that's acceptable since an output schema is present. Missing explicit mention of dependency on mimir_link, but it's implied in 'relationship graphs built via mimir_link.'
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with descriptions for all 4 parameters. The overall description adds little beyond the schema: it restates that the traversal starts from a given entity and is configurable. Baseline is 3 due to high schema coverage; the description does not significantly enhance parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Walk the entity link graph') and resource ('starting from a given entity'), clearly distinguishing it from siblings like mimir_link (which creates links) and mimir_get_entity (which retrieves a single entity). It also mentions the configurable depth and return type, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the tool is 'useful for exploring dependencies, decision trees, and relationship graphs,' which gives clear context for when to use it. However, it does not explicitly mention when not to use it or direct alternatives, such as using mimir_get_entity for a single node or mimir_link for building the graph first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a relationship link from one entity to another. Use this to correct outdated or incorrect links in the knowledge graph.
| Name | Required | Description | Default |
|---|---|---|---|
| to_id | Yes | Target entity ID to unlink | |
| from_key | Yes | Source entity key | |
| from_category | Yes | Source entity category |
| Name | Required | Description |
|---|---|---|
| to | No | Target entity ID |
| from | No | Source as 'category/key' |
| success | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide destructiveHint=true, so the destructive nature is already known. Description adds the corrective purpose but no additional behavioral details (e.g., side effects, permissions). No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Purpose is front-loaded, followed by usage guidance. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, destructive tool with three required parameters and output schema present, the description provides purpose and usage context. Could be marginally improved by noting typical use cases, but it's complete for most needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters (100% coverage) with descriptions. Description does not add extra meaning beyond telling which is source and target, which can be inferred from the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Remove a relationship link') and the resource ('from one entity to another'), distinguishing it from siblings like mimir_link that likely create links.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use for 'correcting outdated or incorrect links,' giving clear context. Does not mention when not to use or alternatives beyond the implied opposite (mimir_link), but the guidance is specific and useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| vault_dir | No | Directory path to write .md files. Created if it doesn't exist. Use ~ for home directory. | ~/.mimir/vault |
| Name | Required | Description |
|---|---|---|
| errors | No | Any errors encountered during export |
| vault_dir | No | Absolute path to the vault directory |
| files_created | No | Number of new .md files created |
| files_updated | No | Number of existing .md files updated |
| completed_at_unix_ms | No | Completion timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint: true, and the description adds that files are human-readable, git-trackable, and Obsidian-compatible, which complements the annotation. However, it does not clarify whether exporting overwrites existing files, which would be useful for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the main action and output format. Every word adds value, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter interface and the presence of an output schema, the description covers the tool's purpose, output format, use cases, and parameter details adequately. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter vault_dir is fully described in the schema with default and path handling. The tool description adds context about writing to the vault directory, reinforcing its purpose beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports non-archived entities to .md files with YAML frontmatter, specifying a concrete verb and resource. It differentiates from siblings like mimir_vault_import.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists use cases ('backup, transfer between workspaces, or offline review'), providing clear usage context. It does not mention when not to use or alternatives, but the purpose is specific enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| vault_dir | No | Directory path to read .md files from. Use ~ for home directory. | ~/.mimir/vault |
| Name | Required | Description |
|---|---|---|
| errors | No | Any errors encountered during import |
| vault_dir | No | Absolute path of the vault directory read |
| files_created | No | Number of new entities created from files |
| files_updated | No | Number of existing entities updated |
| completed_at_unix_ms | No | Completion timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive (destructiveHint: true). The description adds important behavioral context: idempotency (re-running doesn't duplicate) and the specific processing of frontmatter and body. This goes beyond the annotation and provides reassurance and clarity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, no wasted words. It front-loads the purpose and adds essential details in the second sentence. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, clear operation), the description covers purpose, idempotency, pairing, and what is read. An output schema exists (not shown but present), so return values are covered elsewhere. It is complete enough for the agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a clear description for the only parameter 'vault_dir'. The tool description does not add additional parameter-specific details beyond the schema. Since schema coverage is high, the baseline is 3, and the description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: importing .md files from a vault directory into the database. It specifies the file type (.md), what it reads (YAML frontmatter and markdown body), and distinguishes itself from the sibling mimir_vault_export by naming it. The verb is specific and the resource is well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions idempotency, telling the agent it is safe to re-run. It also pairs the tool with mimir_vault_export for transfer, providing a usage context. However, it does not explicitly state when not to use this tool or list alternatives among the many siblings, but the pairing note is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| total | No | Number of categories |
| categories | No | All distinct categories in the database |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, so the description adds value by specifying the scope (distinct entity categories) and usage context. However, it does not disclose any additional behavioral traits (e.g., speed, permissions, or result format).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: first states the action, second provides usage guidance. No wasted words, perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, read-only), the description fully covers its purpose and usage context. Output schema exists, so no need to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the description has no burden. The mention of 'distinct entity categories' clarifies the scope beyond the schema, meeting the baseline for 0 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists distinct entity categories (specific verb+resource) and explains its role in discovering knowledge domains, distinguishing it from siblings like mimir_recall and mimir_context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using this tool before querying with mimir_recall or mimir_context, providing clear context. No when-not or alternatives listed, but for a simple discovery tool it's sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes, but the grooming-related tools (mimir_cohere, autocohere, compact, decay, prune) have overlapping functionality that could cause confusion. However, descriptions help differentiate them.
All tools follow a consistent 'mimir_<verb>[_<modifier>]' pattern with lowercase and underscores. No mixing of conventions, making naming predictable.
40 tools is high, but the domain of memory management requires many specialized operations. Some tools could potentially be consolidated, but the count is borderline appropriate for the scope.
The tool set covers CRUD, search, state management, linking, grooming, federation, import/export, feedback, journaling, and more. There are no obvious gaps for the stated purpose of agent memory management.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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 for AI agents — verbatim conversations, searchable by meaning.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Perseus-Computing-LLC/perseus-vault'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
