API Reference — 35 MCP Tools

Store an episodic memory event. Zero-LLM at write time ($0 ingest) — TF-IDF tokenization only, never calls an LLM or embedding model. Large content is auto-chunked.

Parameters

Returns

{ stored: true, id: "<uuid>", ids: ["<uuid>", ...], chunks, agent_id }

Example call

{
  "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": {
    "name": "memory_store_episode",
    "arguments": {
      "content": "User asked for Q1 financials summary.",
      "metadata": { "user_id": "user_42", "tags": ["finance", "q1"] }
    }
  }
}

Retrieve the most recent episodes for the authenticated agent (newest first).

Parameters

Returns

{ episodes: [...], count }

Example call

{
  "jsonrpc": "2.0", "id": 2,
  "method": "tools/call",
  "params": {
    "name": "memory_get_episodes",
    "arguments": { "limit": 5 }
  }
}

Hybrid search over episodes. Default retrieval is hybrid (RRF fusion of TF-IDF ∪ dense embeddings) — embeddings are computed read-path only, so writes stay zero-LLM. Set use_hybrid:false for lexical-only TF-IDF. Optional pheromone re-ranking for warm/repeated-access workloads.

Parameters

Returns

{ results: [{ episode, score, ... }], count, retrieval: "hybrid"|"tfidf" }

Example call

{
  "jsonrpc": "2.0", "id": 3,
  "method": "tools/call",
  "params": {
    "name": "memory_search_episodes",
    "arguments": {
      "query": "What did the user ask about quarterly reports?",
      "limit": 5
    }
  }
}

Return episodes whose validity falls within a time window. Optimized for temporal lookups using the LadybugDB temporal index.

Parameters

Returns

{ episodes: [...], count, window: { start, end } }

Example call

{
  "jsonrpc": "2.0", "id": 4,
  "method": "tools/call",
  "params": {
    "name": "memory_search_timeline",
    "arguments": {
      "start_time": "2026-05-12T00:00:00Z",
      "end_time": "2026-05-12T23:59:59Z"
    }
  }
}

Consolidate older episodes. Rule-based (no LLM); episodes with pheromone weight < 0.1 are soft-deleted.

Parameters

Returns

{ consolidated, before, note }

Example call

{
  "jsonrpc": "2.0", "id": 5,
  "method": "tools/call",
  "params": {
    "name": "memory_consolidate_episodes",
    "arguments": {
      "before_time": "2026-04-30T23:59:59Z"
    }
  }
}

Store a named entity in the agent's knowledge graph. Entities are the nodes of your graph — people, companies, concepts, documents. Can also encode a subject-predicate-object fact via predicate/object_value.

Parameters

Returns

{ id: "<uuid>", entity_id, stored: true }

Example call

{
  "jsonrpc": "2.0", "id": 6,
  "method": "tools/call",
  "params": {
    "name": "memory_store_entity",
    "arguments": {
      "entity_id": "Acme Corp",
      "type": "organization",
      "description": "Technology company founded in 2020",
      "properties": { "industry": "technology", "founded": 2020 }
    }
  }
}

Retrieve a specific entity by its id/name. Returns found:false if absent.

Parameters

Returns

found → { entity, found: true } · absent → { found: false, entity_id }

Example call

{
  "jsonrpc": "2.0", "id": 7,
  "method": "tools/call",
  "params": {
    "name": "memory_get_entity",
    "arguments": { "entity_id": "Acme Corp" }
  }
}

List entities in the agent's knowledge graph.

Parameters

Returns

{ entities: [...], count }

Example call

{
  "jsonrpc": "2.0", "id": 8,
  "method": "tools/call",
  "params": {
    "name": "memory_list_entities",
    "arguments": { "limit": 20 }
  }
}

Create a typed relationship (edge) between two entities in the knowledge graph. Endpoints may be a UUID or a name (a new name is auto-created as a stub).

Parameters

Returns

{ id: "<uuid>", from_id, to_id, predicate, stored: true }

Example call

{
  "jsonrpc": "2.0", "id": 9,
  "method": "tools/call",
  "params": {
    "name": "memory_store_relation",
    "arguments": {
      "from_id": "Alice",
      "to_id": "Q3 Budget",
      "predicate": "approved",
      "weight": 0.95
    }
  }
}

Get all relations for an entity.

Parameters

Returns

{ relations: [...], count, entity_id }

Example call

{
  "jsonrpc": "2.0", "id": 10,
  "method": "tools/call",
  "params": {
    "name": "memory_get_relations",
    "arguments": { "entity_id": "Alice" }
  }
}

Run a keyword query against the knowledge graph.

Parameters

Returns

Backend graph-query result object (matched nodes/edges; backend-defined shape)

Example call

{
  "jsonrpc": "2.0", "id": 11,
  "method": "tools/call",
  "params": {
    "name": "memory_query_graph",
    "arguments": { "query": "Who approved the Q3 budget?" }
  }
}

TF-IDF semantic search over entities. Returns results ranked by similarity.

Parameters

Returns

{ results: [{ entity, score }], count }

Example call

{
  "jsonrpc": "2.0", "id": 12,
  "method": "tools/call",
  "params": {
    "name": "memory_semantic_search",
    "arguments": {
      "query": "What do we know about Acme Corp?",
      "limit": 15
    }
  }
}

Expand the immediate neighbors of an entity in the knowledge graph. Fast lookup for exploring local graph structure.

Parameters

Returns

{ neighbors: [...], count, entity_id, hops }

Example call

{
  "jsonrpc": "2.0", "id": 13,
  "method": "tools/call",
  "params": {
    "name": "memory_get_neighbors",
    "arguments": {
      "entity_id": "Acme Corp",
      "hops": 1
    }
  }
}

Add a (subject, predicate, object) triple to the low-level triple store. Auto-creates nodes if they don't exist.

Parameters

Returns

{ stored: true, triple_id: "<uuid>", subject, predicate, object }

Example call

{
  "jsonrpc": "2.0", "id": 14,
  "method": "tools/call",
  "params": {
    "name": "memory_graph_add_triple",
    "arguments": {
      "subject": "Fetch.ai",
      "predicate": "develops",
      "object": "Agentverse Memory"
    }
  }
}

Multi-hop neighbor exploration over the triple store, with depth and direction control.

Parameters

Returns

{ node, depth, direction, count, neighbors: [{ subject, predicate, object }] }

Example call

{
  "jsonrpc": "2.0", "id": 15,
  "method": "tools/call",
  "params": {
    "name": "memory_graph_neighbors",
    "arguments": {
      "node": "Fetch.ai",
      "depth": 2,
      "direction": "both"
    }
  }
}

Find the shortest path between two nodes in the triple store using BFS.

Parameters

Returns

{ from, to, undirected, found, hops, path: [...] }

Example call

{
  "jsonrpc": "2.0", "id": 16,
  "method": "tools/call",
  "params": {
    "name": "memory_graph_shortest_path",
    "arguments": {
      "from": "Alice",
      "to": "Q3 Budget",
      "undirected": true
    }
  }
}

Store a procedural memory — a named skill with an ordered step sequence.

Parameters

Returns

{ id: "<uuid>", name, stored: true }

Example call

{
  "jsonrpc": "2.0", "id": 17,
  "method": "tools/call",
  "params": {
    "name": "memory_store_procedure",
    "arguments": {
      "name": "generate_q1_report",
      "description": "Produce Q1 financial summary",
      "steps": [
        "Query Salesforce for Q1 revenue data",
        "Compare to Q4 prior year",
        "Draft 3-bullet summary",
        "Send to Slack #finance"
      ]
    }
  }
}

Retrieve a specific procedure by procedure_id or by name (one of the two is required).

Parameters

Returns

found → { procedure, found: true } · absent → { found: false, procedure_id }

Example call

{
  "jsonrpc": "2.0", "id": 18,
  "method": "tools/call",
  "params": {
    "name": "memory_get_procedure",
    "arguments": { "name": "generate_q1_report" }
  }
}

Find the best matching procedures for a task. Returns ranked candidates by TF-IDF similarity.

Parameters

Returns

{ results: [...], count }

Example call

{
  "jsonrpc": "2.0", "id": 19,
  "method": "tools/call",
  "params": {
    "name": "memory_match_procedure",
    "arguments": {
      "task": "How do I make a quarterly financial report?"
    }
  }
}

Replace a procedure's steps. Creates a new version (the previous version is retained). Identify the procedure by procedure_id or name.

Parameters

Returns

{ new_id: "<uuid>", old_procedure_id, updated: true }

Example call

{
  "jsonrpc": "2.0", "id": 20,
  "method": "tools/call",
  "params": {
    "name": "memory_update_procedure",
    "arguments": {
      "name": "generate_q1_report",
      "steps": [
        "Query Salesforce for Q1 revenue data",
        "Compare to Q4 prior year",
        "Draft 5-bullet summary",
        "Review with manager",
        "Send to Slack #finance"
      ],
      "reason": "Added manager review step"
    }
  }
}

Set a key in the agent's working memory with an optional TTL. Non-string content is JSON-encoded.

Parameters

Returns

{ key, set: true, ttl_seconds }

Example call

{
  "jsonrpc": "2.0", "id": 21,
  "method": "tools/call",
  "params": {
    "name": "memory_set_working",
    "arguments": {
      "key": "current_task",
      "content": "Drafting Q1 financial report for user_42",
      "ttl_seconds": 3600
    }
  }
}

Retrieve a value from working memory by key. Returns found:false if absent or expired.

Parameters

Returns

found → { item, found: true } · absent/expired → { found: false, key }

Example call

{
  "jsonrpc": "2.0", "id": 22,
  "method": "tools/call",
  "params": {
    "name": "memory_get_working",
    "arguments": { "key": "current_task" }
  }
}

List all live (non-expired) working-memory items for the agent.

Parameters

No parameters.

Returns

{ items: [...], count }

Example call

{
  "jsonrpc": "2.0", "id": 23,
  "method": "tools/call",
  "params": {
    "name": "memory_list_working",
    "arguments": {}
  }
}

Delete a specific working memory key, or clear all working memory (omit key).

Parameters

Returns

single key → { key, removed } · clear-all → { cleared: true, keys_deleted }

Example call

{
  "jsonrpc": "2.0", "id": 24,
  "method": "tools/call",
  "params": {
    "name": "memory_clear_working",
    "arguments": { "key": "current_task" }
  }
}

Deposit a pheromone signal on a node (episode UUID or entity name/ID). Strengthens its retrieval weight for future queries.

Parameters

Returns

{ node_id, new_weight, node_type: "episode"|"entity" }

Example call

{
  "jsonrpc": "2.0", "id": 25,
  "method": "tools/call",
  "params": {
    "name": "memory_deposit_pheromone",
    "arguments": {
      "node_id": "Acme Corp",
      "strength": 0.3
    }
  }
}

Get the current pheromone weight for a node.

Parameters

Returns

found → { node_id, weight, node_type } · absent → { node_id, found: false }

Example call

{
  "jsonrpc": "2.0", "id": 26,
  "method": "tools/call",
  "params": {
    "name": "memory_get_pheromone",
    "arguments": { "node_id": "Acme Corp" }
  }
}

Find a path between two entities using A* pathfinding. Builder+ tier — lower tiers receive an in-band -32002 forbidden error; use memory_traverse_graph (BFS) on the free Explorer tier.

Parameters

Returns

{ path: [...], hops, from_id, to_id } (Builder+; else in-band -32002)

Example call

{
  "jsonrpc": "2.0", "id": 27,
  "method": "tools/call",
  "params": {
    "name": "memory_find_path",
    "arguments": {
      "from_id": "Alice",
      "to_id": "Q3 Budget",
      "max_hops": 4
    }
  }
}

Traverse the knowledge graph from a starting node using BFS or DFS. Available on every tier, including the free Explorer plan.

Parameters

Returns

{ visited: [...], count, start_id, algorithm, max_depth }

Example call

{
  "jsonrpc": "2.0", "id": 28,
  "method": "tools/call",
  "params": {
    "name": "memory_traverse_graph",
    "arguments": {
      "start_id": "Acme Corp",
      "algorithm": "bfs",
      "max_depth": 3
    }
  }
}

Create a shared memory space. The calling agent becomes the space owner. Requires a space JWT (POST /v1/space-token from a Builder+ key).

Parameters

Returns

{ space_id, name, owner_did, members, created_at, status: "created" }

Example call

{
  "jsonrpc": "2.0", "id": 29,
  "method": "tools/call",
  "params": {
    "name": "memory_create_shared_space",
    "arguments": { "name": "research-team" }
  }
}

Join an existing shared memory space (the JWT must grant access to it). Requires a space JWT.

Parameters

Returns

{ space_id, agent_did, role, members, status: "joined" }

Example call

{
  "jsonrpc": "2.0", "id": 30,
  "method": "tools/call",
  "params": {
    "name": "memory_join_shared_space",
    "arguments": {
      "space_id": "space_04ia...",
      "role": "writer"
    }
  }
}

Store an entity into a shared space's knowledge graph (requires writer/owner role). Requires a space JWT.

Parameters

Returns

{ space_id, entity_id: "<uuid>", name, entity_type, stored_by, status: "stored" }

Example call

{
  "jsonrpc": "2.0", "id": 31,
  "method": "tools/call",
  "params": {
    "name": "memory_shared_store_entity",
    "arguments": {
      "space_id": "space_04ia...",
      "name": "Project Alpha",
      "entity_type": "project",
      "description": "Active high-priority project"
    }
  }
}

Query the shared knowledge graph across all agents in a space (requires reader/writer/owner role). Empty/omitted query lists all entities. Requires a space JWT.

Parameters

Returns

{ space_id, query, count, results: [{ id, name, entity_type, description, score? }] }

Example call

{
  "jsonrpc": "2.0", "id": 32,
  "method": "tools/call",
  "params": {
    "name": "memory_shared_query",
    "arguments": {
      "space_id": "space_04ia...",
      "query": "What has any agent learned about Project Alpha?",
      "limit": 10
    }
  }
}

List all shared spaces the agent belongs to, including ownership info and member counts. Requires a space JWT.

Parameters

No parameters.

Returns

{ agent_did, count, spaces: [{ space_id, name, owner_did, my_role, member_count, created_at }] }

Example call

{
  "jsonrpc": "2.0", "id": 33,
  "method": "tools/call",
  "params": {
    "name": "memory_list_shared_spaces",
    "arguments": {}
  }
}

Get usage statistics and memory counts for the authenticated agent, including tier and monthly ops consumption.

Parameters

No parameters.

Returns

{ agent_id, tier, monthly_ops_used, monthly_op_limit, memory: { episode_count, entity_count, relation_count, procedure_count, working_count } }

Example call

{
  "jsonrpc": "2.0", "id": 34,
  "method": "tools/call",
  "params": {
    "name": "memory_get_stats",
    "arguments": {}
  }
}

Permanently delete all memory data for the agent — episodes, entities, relations, procedures, working memory, and pheromone trails. Irreversible (GDPR).

Parameters

Returns

{ agent_id, deleted: true, note }

Example call

{
  "jsonrpc": "2.0", "id": 35,
  "method": "tools/call",
  "params": {
    "name": "memory_delete_agent",
    "arguments": { "confirm": true }
  }
}