MCP tools reference

Derived from mcp_server/main.py.

Eight tools. Six are reads and are always registered. The two that mutate appear only when SODAMEM_MCP_ALLOW_WRITE=true — which sodamem install writes for you into the client config it generates.

tool	kind	always on
search_memory	read	✅
get_context	read	✅
list_memories	read	✅
entity_timeline	read	✅
explore_memory	read	✅
refine_search	read	✅
add_memories	write	needs SODAMEM_MCP_ALLOW_WRITE=true
delete_memory	write	needs SODAMEM_MCP_ALLOW_WRITE=true

user_id is optional on every tool: when the client config pins one, the tool resolves it and the model never sees the field. See Scoping.

Reads

search_memory

argument	type	default	bounds
query	string	—	required, non-empty
user_id	string	from config
top_k	int	10	clamped to 1–100

Ranked hits. Zero model calls.

get_context

argument	type	default
query	string	—
user_id	string	from config

Prompt-ready evidence block: pre-formatted text plus the citations behind it. This is the tool to reach for when the model is about to answer — it returns something you paste, not something you assemble.

list_memories

argument	type	default	bounds
user_id	string	from config
limit	int	50	clamped to 1–200
offset	int	0

Paginate for large stores.

entity_timeline

argument	type
entity_id	string, required
user_id	string, from config

One entity's history in order, each item still pointing at its source. Use it when the question is "what is this thing's history" rather than "what matches this query".

explore_memory

argument	type	default	bounds
user_id	string	from config
limit	int	25	clamped to 1–100

Walks the graph outward from a starting point instead of ranking against a query.

refine_search

argument	type	default	bounds
query	string	—	required
user_id	string	from config
top_k	int	10	clamped to 1–100

Writes

add_memories

Ingests turns and extracts facts. Needs extraction credentials — see Environment variables · LLM. Registered only under SODAMEM_MCP_ALLOW_WRITE=true.

delete_memory

Archives a memory: it leaves search and context, the record and its provenance stay. Physical erasure is a separate, off-by-default server setting (SODAMEM_ALLOW_PURGE), not something this tool can reach.

Installing

sodamem daemon ensure
sodamem install claude-code
sodamem clients             # what install supports

See Coding assistants for which clients also get hooks, and CLI for every flag.