MCP Tool Reference

Each tool’s inputSchema is standard JSON Schema, returned from tools/list. Every tool returns {"success": true, ...} on success or {"success": false, "error": "TOOL_ERROR", "message": "..."} on failure — errors are never thrown as JSON-RPC protocol errors, so check success in the result body.

store_memory

Store a new memory.

Parameters:

Name	Type	Required	Description
content	string	yes	The memory content
memory_type	"short_term" | "long_term"	—	Default short_term
tags	string[]	—	Classification tags
importance	number (0–1)	—	Importance score, default 0.5
emotional_valence	number (-1–1)	—	Default 0.0
arousal	number (0–1)	—	Default 0.0. >= 0.8 creates a protected “flashbulb” memory: force-promoted to long_term, importance floored at 0.9, exempt from decay/active-forgetting for 30 days. Only applies at creation time.
health	number (0–100)	—	Default 100.0
ttl	number (seconds)	—	Only meaningful for short_term
source	string	—	Free-text provenance tag
graph_extraction	object	—	{entities: [{name, entity_type?, description?}], relationships: [{source, target, relationship_type?, strength?}]} — max 100 entities / 200 relationships. Lets the calling LLM supply entities/relationships it already extracted; each entity becomes a linked long-term memory.

Example:

{
  "tool": "store_memory",
  "arguments": {
    "content": "User's timezone is Europe/Berlin.",
    "memory_type": "long_term",
    "tags": ["user", "timezone"],
    "importance": 0.6
  }
}

---

search_memories

Search memories by semantic similarity, keyword, or hybrid.

Parameters:

Name	Type	Required	Description
query	string	yes	Search query
search_type	"semantic" | "keyword" | "hybrid"	—	Default: "hybrid"
limit	number	—	Max results, default 10
related_to	string (UUID)	—	Boosts memories connected to this memory in the graph
filters	object	—	{memory_type, tags[], importance_min, importance_max}

Example:

{
  "tool": "search_memories",
  "arguments": {
    "query": "what timezone is this user in?",
    "search_type": "hybrid",
    "limit": 5
  }
}

Response shape (unwrapped from the MCP text-content envelope):

{
  "success": true,
  "query": "what timezone is this user in?",
  "results_count": 1,
  "results": [ { "memory": { "id": "...", "content": "..." }, "score": 0.91 } ],
  "summary": "Found 1 memories for 'what timezone is this user in?'"
}

---

get_memory

Retrieve a specific memory by ID.

Parameters:

Name	Type	Required	Description
memory_id	string	yes	Memory ID
include_connections	boolean	—	Include graph connections in the response

Fetching a memory boosts its health by +10 (capped at 100).

---

update_memory

Update the content or metadata of an existing memory.

Parameters:

Name	Type	Required	Description
memory_id	string	yes	Memory ID
content	string	—	New content
tags	string[]	—	New tags (replaces existing)
importance	number (0–1)	—	New importance score
emotional_valence	number (-1–1)	—	New emotional valence
arousal	number (0–1)	—	New arousal. Note: raising this to >= 0.8 on an existing memory does not retroactively apply flashbulb protection — that only happens at creation time
health	number (0–100)	—	New health score
source	string	—	New provenance tag

At least one optional field must be present.

---

delete_memory

Delete a memory, either soft (archive) or hard (permanent).

Parameters:

Name	Type	Required	Description
memory_id	string	yes	Memory ID
hard_delete	boolean	—	If true, permanently delete. Default: false (soft archive)

---

find_related

Traverse the relationship graph from a starting memory.

Parameters:

Name	Type	Required	Description
memory_id	string	yes	Starting memory ID
depth	number	—	Traversal depth, default 1, max 5
limit	number	—	Max results, default 10

Example:

{
  "tool": "find_related",
  "arguments": {
    "memory_id": "mem_01j...",
    "depth": 2
  }
}

---

promote_to_longterm

Promote a short-term memory to long-term.

Parameters:

Name	Type	Required	Description
memory_id	string	yes	Memory ID

Example:

{
  "tool": "promote_to_longterm",
  "arguments": { "memory_id": "mem_01j..." }
}

---

list_recent_memories

List recently created or accessed memories.

Parameters:

Name	Type	Required	Description
limit	number	—	Max results
memory_type	"short_term" | "long_term"	—	Filter by type
sort_by	"created_at" | "accessed_at"	—	Default: "created_at"

Example:

{
  "tool": "list_recent_memories",
  "arguments": { "limit": 10, "sort_by": "accessed_at" }
}