MCP Tools Reference
MuninnDB ships with 19 MCP tools. Once configured via muninn init, these appear as native tools in Claude Desktop, Cursor, Windsurf, VS Code, and any MCP-compatible agent — no API calls, no glue code.
Connection
The MCP server listens on port 8750 by default. The endpoint is http://localhost:8750/mcp (JSON-RPC 2.0 over HTTP). Auth is optional — set a Bearer token with --mcp-token or configure one via muninn init.
Rate limiting
The MCP server enforces 100 requests/sec sustained, 200 burst. This is per-server, not per-tool.
Core Tools
muninn_remember Store a new memory engram.
| Parameter | Type | Req | Description |
|---|---|---|---|
| content | string | ✓ | The information to remember |
| vault | string | — | Vault name (default: "default") |
| concept | string | — | Short label for what this memory is about |
| tags | []string | — | Labels for filtering and grouping |
| confidence | float | — | 0.0–1.0 — how certain you are (default 0.8) |
muninn_remember_batch Store up to 50 memories in one call. Same optional fields per item as muninn_remember (concept, tags, summary, etc.). More efficient than multiple muninn_remember calls.
| Parameter | Type | Req | Description |
|---|---|---|---|
| vault | string | — | Vault name (default: "default") |
| memories | []object | ✓ | Array of { content, concept?, tags?, summary?, ... } — max 50 items |
muninn_guide Get vault-aware usage instructions for the AI. Call on first connect; returns when to remember, when to recall, behavior mode, and quick tips. No required params.
| Parameter | Type | Req | Description |
|---|---|---|---|
| vault | string | — | Vault name (default: "default") |
Primary retrieval. Find the most relevant memories for a context. Runs the full 6-phase cognitive pipeline: BM25, temporal priority scoring, Hebbian boosting, embeddings, graph traversal.
| Parameter | Type | Req | Description |
|---|---|---|---|
| context | []string | ✓ | One or more search phrases describing what you need |
| vault | string | — | Vault to search (default: "default") |
| threshold | float | — | Minimum relevance score 0.0–1.0 (default 0.5) |
| limit | int | — | Max results (default 10) |
muninn_read Fetch a single memory by its ULID. Returns full record including temporal priority data (access count, last access), confidence, and associations.
| Parameter | Type | Req | Description |
|---|---|---|---|
| id | string | ✓ | Engram ULID |
| vault | string | — | Vault name (default: "default") |
muninn_forget Soft-delete a memory. The engram is archived — excluded from activation but restorable for 7 days via muninn_restore.
| Parameter | Type | Req | Description |
|---|---|---|---|
| id | string | ✓ | Engram ULID |
| vault | string | — | Vault name (default: "default") |
muninn_status Get vault health statistics: engram count, confidence histogram, temporal priority distribution, storage bytes.
| Parameter | Type | Req | Description |
|---|---|---|---|
| vault | string | — | Vault name (default: "default") |
muninn_session Get a summary of recent activity since a given time — activations, writes, and link events.
| Parameter | Type | Req | Description |
|---|---|---|---|
| since | string | ✓ | ISO 8601 timestamp (e.g. "2025-01-15T09:00:00Z") |
| vault | string | — | Vault name (default: "default") |
Graph & Relations
muninn_link Create a typed, weighted association between two engrams. Links are traversed during recall to surface related memories.
| Parameter | Type | Req | Description |
|---|---|---|---|
| source_id | string | ✓ | Source engram ULID |
| target_id | string | ✓ | Target engram ULID |
| relation | string | ✓ | supports · contradicts · depends_on · supersedes · relates_to · is_part_of · causes · preceded_by · followed_by · created_by_person · belongs_to_project · references · implements · blocks · resolves |
| vault | string | — | Vault name (default: "default") |
| weight | float | — | Association strength 0.0–1.0 (default 0.8) |
muninn_traverse Graph traversal from a starting memory. Follows association links hop-by-hop to find connected memories you may not know to ask for directly.
| Parameter | Type | Req | Description |
|---|---|---|---|
| start_id | string | ✓ | Starting engram ULID |
| vault | string | — | Vault name (default: "default") |
| max_hops | int | — | Max graph depth (default 2, max 5) |
| max_nodes | int | — | Max total results (default 20, max 100) |
| rel_types | []string | — | Filter by relation types |
muninn_contradictions Check the vault for known contradictions — pairs of engrams linked with the "contradicts" relation. Useful for consistency audits.
| Parameter | Type | Req | Description |
|---|---|---|---|
| vault | string | — | Vault name (default: "default") |
Lifecycle & State
muninn_evolve Update a memory with new content while preserving its history. The old version is archived and linked. Tracks why the memory changed.
| Parameter | Type | Req | Description |
|---|---|---|---|
| id | string | ✓ | Engram ULID |
| new_content | string | ✓ | The updated information |
| reason | string | ✓ | Why this memory changed |
| vault | string | — | Vault name (default: "default") |
muninn_state Transition a memory's lifecycle state. Useful for tracking work in progress, decisions, or task status.
| Parameter | Type | Req | Description |
|---|---|---|---|
| id | string | ✓ | Engram ULID |
| state | string | ✓ | planning · active · paused · blocked · completed · cancelled · archived |
| vault | string | — | Vault name (default: "default") |
| reason | string | — | Optional note on the transition |
muninn_decide Record a decision with its rationale and supporting evidence. Creates a structured decision engram automatically linked to referenced evidence.
| Parameter | Type | Req | Description |
|---|---|---|---|
| decision | string | ✓ | The decision made |
| rationale | string | ✓ | Why this decision was made |
| vault | string | — | Vault name (default: "default") |
| alternatives | []string | — | Options that were considered but not chosen |
| evidence_ids | []string | — | ULIDs of engrams supporting this decision |
muninn_restore Recover a soft-deleted memory within the 7-day restoration window.
| Parameter | Type | Req | Description |
|---|---|---|---|
| id | string | ✓ | Engram ULID |
| vault | string | — | Vault name (default: "default") |
Insight & Maintenance
muninn_consolidate Merge multiple engrams into a single unified memory. The originals are archived and linked to the new consolidated engram.
| Parameter | Type | Req | Description |
|---|---|---|---|
| ids | []string | ✓ | ULIDs to merge (max 50) |
| merged_content | string | ✓ | The unified content combining all originals |
| vault | string | — | Vault name (default: "default") |
muninn_explain Get a full score breakdown for a specific engram against a query. Shows how much each scoring component (BM25, temporal priority, Hebbian, semantic) contributed.
| Parameter | Type | Req | Description |
|---|---|---|---|
| engram_id | string | ✓ | Engram ULID to explain |
| query | []string | ✓ | The context phrases to score against |
| vault | string | — | Vault name (default: "default") |
muninn_list_deleted List soft-deleted memories that are still within the 7-day restoration window.
| Parameter | Type | Req | Description |
|---|---|---|---|
| vault | string | — | Vault name (default: "default") |
| limit | int | — | Max results (default 20, max 100) |
muninn_retry_enrich Re-queue an engram for plugin processing — useful if enrichment failed on initial write (e.g., LLM was temporarily unavailable).
| Parameter | Type | Req | Description |
|---|---|---|---|
| id | string | ✓ | Engram ULID |
| vault | string | — | Vault name (default: "default") |