ClawMem

MCP server tools reference

Complete reference for ClawMem’s MCP server tools. These let AI agents search, retrieve, and manage persistent memory. All tools accept an optional vault parameter for multi-vault setups. Omit for the default vault.

Retrieval

memory_retrieve

Recommended entry point. Auto-classifies query and routes to the optimal backend.

Param	Type	Default	Description
query	string	required	Your question or search query
mode	enum	auto	Override: keyword, semantic, causal, timeline, discovery, complex, hybrid
limit	number	10	Max results
compact	boolean	true	Compact output (snippets vs full content)
vault	string	—	Named vault

Auto-routing:

• Timeline queries (“last session”, “yesterday”) → session history
• Causal queries (“why did we”, “what caused”) → intent_search with graph traversal
• Discovery queries (“similar to”, “related to”) → find_similar
• Complex queries (multi-topic) → query_plan
• Everything else → full hybrid search

query

Full hybrid pipeline: BM25 + vector + query expansion + cross-encoder reranking.

Param	Type	Default	Description
query	string	required	Search query
limit	number	10	Max results
compact	boolean	true	Compact output
collection	string	—	Filter by collection (comma-separated for multi)
intent	string	—	Domain hint for ambiguous queries (steers expansion, reranking, chunk selection)
candidateLimit	number	30	Candidates for reranking (tune precision vs speed)
vault	string	—	Named vault

BM25 strong-signal bypass: skips expansion when top BM25 hit >= 0.85 with gap >= 0.15 (disabled when intent is provided).

search

BM25 only. Zero GPU cost.

Param	Type	Default	Description
query	string	required	Search query
limit	number	10	Max results
compact	boolean	true	Compact output
collection	string	—	Filter by collection
vault	string	—	Named vault

vsearch

Vector only. Semantic similarity.

Param	Type	Default	Description
query	string	required	Search query
limit	number	10	Max results
compact	boolean	true	Compact output
collection	string	—	Filter by collection
vault	string	—	Named vault

intent_search

Intent-classified search with graph traversal. Use directly for “why”, “when”, “who” questions.

Param	Type	Default	Description
query	string	required	Search query
limit	number	10	Max results
force_intent	enum	—	Override: WHY, WHEN, ENTITY, WHAT
enable_graph_traversal	boolean	true	Multi-hop graph expansion
vault	string	—	Named vault

query_plan

Multi-topic decomposition. Use for complex queries spanning multiple subjects.

Param	Type	Default	Description
query	string	required	Complex or multi-topic query
limit	number	10	Max results
compact	boolean	true	Compact output
vault	string	—	Named vault

Document access

get

Retrieve a single document by path or docid.

Param	Type	Default	Description
file	string	required	File path or docid (#abc123)
fromLine	number	—	Start line
maxLines	number	—	Line limit
lineNumbers	boolean	false	Include line numbers
vault	string	—	Named vault

multi_get

Retrieve multiple documents by glob pattern or comma-separated list.

Param	Type	Default	Description
pattern	string	required	Glob pattern or comma-separated paths
maxLines	number	—	Line limit per document
maxBytes	number	10240	Max total bytes
lineNumbers	boolean	false	Include line numbers
vault	string	—	Named vault

find_similar

k-NN vector neighbors of a reference document.

Param	Type	Default	Description
file	string	required	Path of reference document
limit	number	5	Max results
vault	string	—	Named vault

find_causal_links

Trace causal decision chains from a document.

Param	Type	Default	Description
docid	string	required	Document ID
direction	enum	both	causes, caused_by, or both
depth	number	5	Max traversal depth (1-10)
vault	string	—	Named vault

timeline

Temporal neighborhood — what was created/modified before and after a document.

Param	Type	Default	Description
docid	string	required	Document ID
before	number	5	Documents to show before (1-20)
after	number	5	Documents to show after (1-20)
same_collection	boolean	false	Constrain to same collection
vault	string	—	Named vault

memory_evolution_status

Track how a document’s A-MEM metadata evolved over time.

Param	Type	Default	Description
docid	string	required	Document ID
limit	number	10	Max evolution entries (1-100)
vault	string	—	Named vault

session_log

Recent session history with handoffs and file changes.

Param	Type	Default	Description
limit	number	10	Max sessions
vault	string	—	Named vault

Mutations

memory_pin

Pin a memory for permanent prioritization (+0.3 composite boost).

Param	Type	Default	Description
query	string	required	Search query or path to find the memory
unpin	boolean	false	Set true to unpin
vault	string	—	Named vault

memory_snooze

Temporarily hide a memory from context surfacing.

Param	Type	Default	Description
query	string	required	Search query or path to find the memory
until	string	—	ISO date (e.g., 2026-04-01). Omit to unsnooze.
vault	string	—	Named vault

memory_forget

Permanently deactivate a memory.

Param	Type	Default	Description
query	string	required	Search query or path to find the memory
confirm	boolean	true	False = preview only
vault	string	—	Named vault

Search behavior (v0.2.6+, all three tools): Query matching cascades through four strategies: exact path match → BM25 full-text → title-token overlap → vector similarity. This prevents “No matching memory found” errors when the document exists but BM25 fails to match (e.g., too many AND’d terms). Path-like queries (containing / or ending in .md) try direct path matching first. memory_forget requires higher confidence to act — ambiguous matches return candidates instead of mutating.

Lifecycle

lifecycle_status

Document lifecycle statistics: active, archived, forgotten, pinned, snoozed counts.

Param	Type	Default	Description
vault	string	—	Named vault

lifecycle_sweep

Archive stale documents based on lifecycle policy.

Param	Type	Default	Description
dry_run	boolean	true	Preview only (no action)
vault	string	—	Named vault

lifecycle_restore

Restore auto-archived documents.

Param	Type	Default	Description
query	string	—	Search archived docs by keyword
collection	string	—	Restore all from a collection
all	boolean	false	Restore everything
vault	string	—	Named vault

Maintenance

status

Quick index health check.

Param	Type	Default	Description
vault	string	—	Named vault

reindex

Trigger re-scan of all collections.

Param	Type	Default	Description
vault	string	—	Named vault

index_stats

Detailed statistics: content type distribution, staleness, embedding coverage.

Param	Type	Default	Description
vault	string	—	Named vault

build_graphs

Build temporal backbone and semantic graph.

Param	Type	Default	Description
graph_types	array	["all"]	temporal, semantic, or all
semantic_threshold	number	0.7	Similarity threshold for semantic edges
vault	string	—	Named vault

profile

Get or rebuild the user profile (static facts + dynamic context).

Param	Type	Default	Description
rebuild	boolean	false	Force rebuild

beads_sync

Sync Beads issues from Dolt backend into the search index.

Param	Type	Default	Description
project_path	string	cwd	Path to project with .beads/ directory

Vault management

list_vaults

Show configured vault names and paths. Returns empty in single-vault mode.

vault_sync

Index markdown from a directory into a named vault.

Param	Type	Default	Description
vault	string	required	Target vault name
content_root	string	required	Directory path to index
pattern	string	**/*.md	Glob pattern
collection_name	string	vault name	Collection name in the vault

Restricted-path validation rejects sensitive directories (/etc/, /root/, .ssh, .env, credentials, .aws, .kube).

kg_query

Query the SPO knowledge graph for an entity’s temporal relationships.

Param	Type	Default	Description
entity	string	required	Entity name or ID
as_of	string	—	Date filter (YYYY-MM-DD) — only facts valid at this date
direction	enum	both	outgoing, incoming, or both
vault	string	—	Named vault

Uses entity resolution (FTS search) first, falls back to slug normalization. Returns triples with subject, predicate, object, valid_from, valid_to, confidence, and current status.

diary_write

Write to the agent’s diary. For non-hooked environments where hooks don’t capture session context automatically.

Param	Type	Default	Description
entry	string	required	Diary entry text
topic	string	general	Topic tag (e.g., ‘technical’, ‘user_facts’, ‘session’)
agent	string	agent	Agent name writing the entry
vault	string	—	Named vault

Entries stored via saveMemory() with ms-resolution paths to prevent dedup of rapid writes.

diary_read

Read recent diary entries.

Param	Type	Default	Description
last_n	number	10	Number of entries to return
agent	string	—	Filter by agent name
vault	string	—	Named vault

This site is open source. Improve this page.