# neuromcp MCP tools

<!-- AUTO-GENERATED by scripts/generate-tools-doc.ts — do not edit by hand.
     Regenerate with: npx tsx scripts/generate-tools-doc.ts -->

neuromcp registers **46 tools**. This document is generated from the
actual registrations, so names, descriptions and parameters are exactly
what an MCP client sees.

## Index

- **Core memory** (11): `store_memory`, `search_memory`, `recall_answer`, `recall_memory`, `forget_memory`, `consolidate`, `memory_stats`, `export_memories`, `import_memories`, `backfill_embeddings`, `search_all`
- **Knowledge graph** (6): `create_entity`, `create_relation`, `query_graph`, `search_claims`, `compute_centrality`, `update_importance`
- **Episodes** (10): `start_episode`, `end_episode`, `list_episodes`, `get_episode`, `cluster_memories`, `list_clusters`, `get_cluster_memories`, `summarize_cluster`, `summarize_episode`, `memory_timeline`
- **Multi-agent** (9): `register_agent`, `find_expert`, `agent_conflicts`, `review_queue`, `review_memory`, `init_reviews`, `compress_memories`, `find_transferable`, `transfer_memories`
- **Verbatim store** (3): `store_verbatim`, `search_verbatim`, `verbatim_stats`
- **Wiki** (3): `wiki_ingest`, `wiki_lint`, `wiki_briefing`
- **Attribution & usefulness** (3): `log_retrieval`, `cite_memories`, `usefulness_stats`
- **Reflection** (1): `generate_reflection`

## Core memory

### `store_memory`

Store a new memory with semantic deduplication, contradiction detection, surprise scoring, and entity extraction. Returns the memory ID, contradictions found (resolution supersede/coexist are claim-backed and recorded as graph edges; flag is heuristic-only and reported here but never stored in the graph), surprise score, and extracted entities.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content` | string | yes | The memory content to store |
| `namespace` | string | no | Namespace to store in (default: config default) |
| `category` | string | no | Category label (e.g. "code", "conversation", "fact") |
| `tags` | array | no | Tags for filtering |
| `importance` | number | no | Importance score 0-1 (default: 0.5) |
| `source` | enum | no | Source of the memory |
| `source_trust` | enum | no | Trust level |
| `project_id` | string | no | Project identifier |
| `agent_id` | string | no | Agent identifier |
| `metadata` | record | no | Arbitrary metadata |
| `expires_at` | string | no | ISO 8601 expiration timestamp |
| `valid_from` | string | no | ISO 8601 timestamp when this fact becomes valid (default: now) |
| `valid_to` | string | no | ISO 8601 timestamp when this fact stops being valid |
| `episode_id` | string | no | Episode ID to associate this memory with (from start_episode) |

### `search_memory`

Search memories using hybrid vector + full-text search with RRF ranking, graph boost, and cognitive priming. Supports temporal queries (valid_at) to find what was true at a specific time.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | yes | Search query text |
| `namespace` | string | no | Namespace to search (default: config default) |
| `limit` | number | no | Max results (default: 10) |
| `category` | string | no | Filter by category |
| `tags` | array | no | Filter: all tags must be present |
| `min_importance` | number | no | Minimum importance threshold |
| `min_trust` | enum | no | Minimum trust level |
| `after` | string | no | Only memories created after this ISO timestamp |
| `before` | string | no | Only memories created before this ISO timestamp |
| `hybrid` | boolean | no | Use hybrid search (default: true) |
| `valid_at` | string | no | ISO 8601 timestamp — only return memories valid at this time (temporal query) |
| `include_superseded` | boolean | no | Include superseded / expired (window-closed) memories. Default false — only current facts. A valid_at query overrides this. |
| `graph_boost` | boolean | no | Boost results connected via knowledge graph (default: true) |
| `episode_id` | string | no | Filter by episode ID — only return memories from this episode |
| `explain` | boolean | no | Include explanation metadata: trust reason, contradictions, temporal validity, claims, confidence breakdown (default: true) |
| `compact` | boolean | no | Return a reduced 7-field projection per result (id, content, similarity_score, category, tags, importance, created_at) instead of all 37 DB fields. Default FALSE in 0.19 for semver-safe upgrade; will default TRUE in 1.0. Pass `compact: true` to opt in now. |

### `recall_answer`

Answer a question FROM memory: runs hybrid retrieval, then returns a synthesized, CITED extractive answer (every sentence traces to a stored memory id) PLUS an explicit gap-analysis — what memory does NOT cover and the freshness boundary (stale_since). Returns status "not_in_memory" instead of fabricating when nothing matches. Deterministic, no LLM. Prefer this over search_memory when you need a grounded answer rather than raw chunks.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | yes | The question to answer from memory |
| `namespace` | string | no | Namespace to search (default: config default) |
| `limit` | number | no | How many memories to synthesize over (default: 8) |
| `category` | string | no | Filter by category |
| `after` | string | no | Only memories created after this ISO timestamp |
| `before` | string | no | Only memories created before this ISO timestamp |
| `valid_at` | string | no | ISO 8601 timestamp — only memories valid at this time |
| `include_superseded` | boolean | no | Include superseded / expired (window-closed) memories. Default false — only current facts. A valid_at query overrides this. |
| `max_sentences` | number | no | Max sentences in the answer (default: 5) |

### `recall_memory`

Recall memories by ID, namespace, category, or tags without semantic search.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | no | Specific memory ID to recall |
| `namespace` | string | no | Namespace filter |
| `category` | string | no | Category filter |
| `tags` | array | no | Tags filter: all must match |
| `limit` | number | no | Max results (default: 20) |
| `include_superseded` | boolean | no | Include superseded / expired (window-closed) memories. Default false — only current facts. Ignored for id lookups (an explicit id fetch always returns the row). |

### `forget_memory`

Tombstone (soft-delete) memories matching the given filters. At least one filter is required.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | no | Specific memory ID to forget |
| `namespace` | string | no | Namespace filter |
| `tags` | array | no | Tags filter |
| `older_than_days` | number | no | Delete memories older than N days |
| `below_importance` | number | no | Delete memories below this importance |
| `dry_run` | boolean | no | Preview what would be deleted without actually deleting |

### `consolidate`

Run consolidation: merge near-duplicates, decay stale memories, prune low-value, sweep expired, purge old tombstones. Set commit=true to apply.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | no | Namespace to consolidate (default: config default) |
| `similarity_threshold` | number | no | Similarity threshold for merging |
| `decay_lambda` | number | no | Decay rate parameter |
| `min_importance_after_decay` | number | no | Prune threshold after decay |
| `commit` | boolean | yes | If false, returns a dry-run plan. If true, executes the plan. |

### `memory_stats`

Get statistics about stored memories: counts, categories, trust levels, importance, and database size.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | no | Namespace to get stats for (default: config default, "*" for all) |

### `export_memories`

Export memories as JSONL or JSON for backup or migration.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | no | Namespace to export (default: config default, "*" for all) |
| `format` | enum | no | Export format (default: jsonl) |
| `include_tombstoned` | boolean | no | Include soft-deleted memories |

### `import_memories`

Import memories from JSONL or JSON data. Deduplicates by content hash.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | yes | JSONL or JSON array string of memory records |
| `namespace` | string | no | Override namespace for all imported memories |
| `trust` | enum | no | Trust level for imported memories (default: unverified) |

### `backfill_embeddings`

Recompute embeddings for all memories missing from the vector store. Also syncs FTS index.

_No parameters._

### `search_all`

Unified search across both extracted memories and verbatim text. Returns results with source labels and per-source quotas.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | yes | Search query text |
| `namespace` | string | no | Namespace filter |
| `limit` | number | no | Max results per source (default: 5) |
| `after` | string | no | Only entries after this ISO timestamp |
| `before` | string | no | Only entries before this ISO timestamp |
| `episode_id` | string | no | Filter by episode |

## Knowledge graph

### `create_entity`

Create or update an entity in the knowledge graph. Entities represent concepts, people, tools, or any named thing.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | yes | Entity name |
| `entity_type` | string | no | Entity type (default: "concept"). Examples: person, tool, project, concept, package, url. "memory_proxy" is reserved and rejected. |
| `namespace` | string | no | Namespace (default: config default) |
| `metadata` | record | no | Arbitrary metadata |

### `create_relation`

Create a typed relation between two entities in the knowledge graph. Supports temporal validity.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source_entity_id` | string | yes | Source entity ID |
| `target_entity_id` | string | yes | Target entity ID |
| `relation_type` | string | yes | Relation type: causes, fixes, contradicts, relates_to, part_of, depends_on, supersedes, similar_to |
| `namespace` | string | no | Namespace (default: config default) |
| `weight` | number | no | Relation strength 0-1 (default: 1.0) |
| `metadata` | record | no | Arbitrary metadata |
| `valid_from` | string | no | ISO 8601 timestamp when relation becomes valid |
| `valid_to` | string | no | ISO 8601 timestamp when relation stops being valid |

### `query_graph`

Traverse the knowledge graph starting from an entity. Returns connected nodes and edges up to max_depth hops. Supports temporal queries. Without entity_id/entity_name it returns an OVERVIEW: the top-N entities of the namespace ranked by number of relations (contradicts edges not counted), with the relations among them; internal memory_proxy entities that only back contradicts edges are excluded from the overview.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `entity_id` | string | no | Start entity ID |
| `entity_name` | string | no | Start entity name (will find closest match) |
| `namespace` | string | no | Namespace (default: config default) |
| `max_depth` | number | no | Maximum traversal depth (default: 2) |
| `relation_types` | array | no | Filter by relation types |
| `valid_at` | string | no | ISO 8601 timestamp — only show relations valid at this time |
| `limit` | number | no | Maximum nodes to return (default: 50) |

### `search_claims`

Search atomic claims extracted from memories. Claims are verifiable facts with subject-predicate-object structure.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | no | Search text (matches content, subject, or object) |
| `memory_id` | string | no | Get all claims from a specific memory |
| `limit` | number | no | Max results (default: 20) |

### `compute_centrality`

Run weighted PageRank over the knowledge graph to compute entity centrality scores. Entities with more connections and higher-weight edges rank higher. Persists results for search boosting.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | no | Namespace (default: config default) |
| `damping` | number | no | Damping factor (default: 0.85) |
| `max_iterations` | number | no | Max iterations (default: 20) |

### `update_importance`

Recalculate adaptive importance for all memories in a namespace. Boosts frequently accessed, recently relevant, and graph-central memories. Run after clustering and PageRank for best results.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | no | Namespace (default: config default) |

## Episodes

### `start_episode`

Start a new episode (session/task context). Memories stored with this episode_id will be grouped together. Use to track what happened during a session.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | yes | Episode title (e.g. "Deploy agentproofs-io", "Debug auth flow") |
| `namespace` | string | no | Namespace (default: config default) |
| `metadata` | record | no | Arbitrary metadata |

### `end_episode`

End an active episode. Optionally provide a summary, or one will be auto-generated from the most important memories in the episode.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `episode_id` | string | yes | Episode ID to end |
| `summary` | string | no | Episode summary (auto-generated if omitted) |

### `list_episodes`

List episodes in a namespace. Shows memory count per episode.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | no | Namespace to list from |
| `limit` | number | no | Max episodes to return (default: 20) |
| `active_only` | boolean | no | Only show active (not ended) episodes |

### `get_episode`

Get details of a specific episode including memory count.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `episode_id` | string | yes | Episode ID to retrieve |

### `cluster_memories`

Run k-means clustering on memories in a namespace. Groups semantically related memories into clusters. Returns cluster labels, sizes, and assignments.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | no | Namespace to cluster (default: config default) |
| `k` | number | no | Number of clusters (auto-selected if omitted: sqrt(n/2), clamped 2-20) |
| `max_iterations` | number | no | Max k-means iterations (default: 10) |

### `list_clusters`

List all clusters in a namespace with their labels and memory counts.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | no | Namespace (default: config default) |

### `get_cluster_memories`

Get all memories in a specific cluster, ordered by distance from centroid.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | yes | Cluster ID |
| `limit` | number | no | Max memories to return (default: 20) |

### `summarize_cluster`

Generate an extractive summary of a cluster. Selects the most central, representative sentences from cluster memories using embedding centrality.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | yes | Cluster ID to summarize |
| `max_sentences` | number | no | Max sentences in summary (default: 5) |

### `summarize_episode`

Generate an extractive summary of an episode. Selects the most central, representative sentences from episode memories.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `episode_id` | string | yes | Episode ID to summarize |
| `max_sentences` | number | no | Max sentences in summary (default: 5) |

### `memory_timeline`

Track how knowledge about a topic evolved over time. Follows supersession chains and shows full revision history.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | yes | Topic to track evolution of |
| `namespace` | string | no | Namespace (default: config default) |
| `after` | string | no | Only show entries after this ISO date |
| `before` | string | no | Only show entries before this ISO date |
| `include_superseded` | boolean | no | Include superseded / expired (window-closed) versions (default: true). Set false to return only currently-valid entries. |
| `limit` | number | no | Max entries (default: 20) |

## Multi-agent

### `register_agent`

Register or update an agent profile with expertise topics. Auto-counts memories.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | yes | Unique agent identifier |
| `name` | string | yes | Agent display name |
| `namespace` | string | no |  |
| `expertise` | array | no | Topic expertise tags |
| `metadata` | record | no |  |

### `find_expert`

Find agents with expertise matching a query topic.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | yes | Topic to find experts for |
| `namespace` | string | no |  |
| `limit` | number | no |  |

### `agent_conflicts`

Find conflicting knowledge between different agents on the same topic.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | no |  |
| `topic` | string | no | Narrow to a specific topic |

### `review_queue`

Get memories due for spaced repetition review. Returns overdue memories ordered by urgency + importance.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | no |  |
| `limit` | number | no |  |
| `min_importance` | number | no |  |

### `review_memory`

Record a review of a memory. Quality 0-5 (SM-2 scale: 0=forgot, 5=perfect). Updates interval and schedules next review.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `memory_id` | string | yes | Memory to review |
| `quality` | number | yes | Recall quality (0=forgot, 5=perfect) |

### `init_reviews`

Initialize spaced repetition for important memories that do not have a review schedule yet.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | no |  |
| `min_importance` | number | no | Minimum importance to include (default: 0.5) |

### `compress_memories`

Compress old similar memories into digest memories. Reduces DB size while preserving knowledge. Hard-deletes ancient zero-access tombstones.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | no |  |
| `age_days` | number | no | Compress memories older than N days (default: 30) |
| `min_cluster` | number | no | Minimum cluster size for compression (default: 3) |
| `threshold` | number | no | Similarity threshold for clustering (default: 0.80) |

### `find_transferable`

Find memories in a source namespace that could be useful in a target namespace. Scores by transferability (universal vs project-specific).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source_namespace` | string | yes | Source namespace |
| `target_namespace` | string | yes | Target namespace |
| `min_importance` | number | no |  |
| `categories` | array | no |  |
| `limit` | number | no |  |

### `transfer_memories`

Copy memories from source to target namespace. Optionally adapts content by stripping project-specific references.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `memory_ids` | array | yes | Memory IDs to transfer |
| `target_namespace` | string | yes | Target namespace |
| `adapt` | boolean | no | Strip project-specific paths/hosts (default: true) |

## Verbatim store

### `store_verbatim`

Store raw conversation text verbatim — no summarization, no consolidation, never pruned. Use for exact recall of what was said.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content` | string | yes | Raw text to store verbatim |
| `namespace` | string | no | Namespace (default: config default) |
| `agent_id` | string | no | Agent that produced this text |
| `episode_id` | string | no | Episode to associate with |
| `metadata` | record | no | Arbitrary metadata |

### `search_verbatim`

Search raw verbatim text using full-text search. Returns exact matches from stored conversations. Use for literal recall.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | yes | Search query |
| `namespace` | string | no | Namespace filter (default: config default, "*" for all) |
| `limit` | number | no | Max results (default: 10) |
| `after` | string | no | Only entries after this ISO timestamp |
| `before` | string | no | Only entries before this ISO timestamp |
| `episode_id` | string | no | Filter by episode |
| `agent_id` | string | no | Filter by agent |

### `verbatim_stats`

Get statistics about verbatim storage: total entries, size, and distribution by namespace.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | no | Namespace filter (default: config default, "*" for all) |

## Wiki

### `wiki_ingest`

Read a file from the wiki raw-sources/ directory and extract structured metadata (title, type, key concepts, related pages). Returns analysis the LLM uses to decide which wiki pages to create or update. Does NOT write pages itself.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `filename` | string | yes | Name of the file in raw-sources/ (e.g. "article.md") — plain file name only, no paths |

### `wiki_lint`

Scan all wiki pages and check for health issues: missing frontmatter, pages not in index.md, stale pages (>30 days), thin pages (<5 lines), unprocessed raw sources, broken related links. Writes lint-report.md.

_No parameters._

### `wiki_briefing`

Generate a structured briefing from the wiki: active projects, unprocessed sources, recent changelog entries, stale pages needing attention. Use for morning status checks.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `days` | number | no | Lookback period in days (default: 7) |

## Attribution & usefulness

### `log_retrieval`

Log a retrieval event so future searches can learn which memories are actually helpful. Call right after search_memory. Pass retrieved_ids (all top-K), cited_ids (those actually used in the answer, if known), and an outcome label (helpful/neutral/harmful). Usefulness scores are applied as a prior in future rankings.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | yes | The user query that triggered the search |
| `namespace` | string | no |  |
| `retrieved_ids` | array | yes | All memory IDs returned from the search |
| `cited_ids` | array | no | Memory IDs actually used in the answer |
| `outcome` | enum | no |  |
| `critic_reason` | string | no | Short reason for the outcome label |
| `model` | string | no | Model that produced the answer |
| `session_id` | string | no | Opaque session key so a per-session critic can filter events without cross-session contamination. Falls back to NEUROMCP_SESSION_ID env var. |

### `cite_memories`

Attach a late verdict to a previously-logged retrieval event. Use when the agent answers first and a critic scores the answer afterward. Updates the memory_usefulness prior based on which retrieved memories were cited + outcome.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `event_id` | string | yes | retrieval event id returned by log_retrieval |
| `cited_ids` | array | yes | Memory IDs actually used in the answer |
| `outcome` | enum | no |  |
| `critic_reason` | string | no |  |

### `usefulness_stats`

List memories ranked by observed usefulness (helpful vs harmful citation ratio). Use to inspect which memories the agent actually leans on, or to pick high-confidence source material for reflection.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | no |  |
| `min_observations` | number | no | Minimum observation count (default 1) |
| `limit` | number | no |  |

## Reflection

### `generate_reflection`

Synthesise a meta-reflection memory from memories that have been proven helpful (helpful_count >= min_helpful). Safeguarded: only touches memories with explicit positive critic signal — no speculation on unvalidated content. Stored as category=reflection so downstream searches can include or exclude meta-memories explicitly.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | no |  |
| `window_days` | number | no | Lookback window (default 14) |
| `min_helpful` | number | no | Minimum helpful_count required (default 1) |
| `max_clusters` | number | no | Max category sections in the reflection (default 5) |