Docs/API Reference

API Reference — 35 MCP Tools

All tools use JSON-RPC 2.0 over HTTPS POST to https://am-server-jbneh74b5q-uc.a.run.app/mcp with Authorization: Bearer avmem_sk_....

LadybugDB graph engineJWT/DID authenticationMCP Registry: io.github.fetchai/agentverse-memoryUsage metering: GET /v1/usage

Episodic

Episodic Memory

5 tools

Time-stamped events and interactions. Stored verbatim, indexed by TF-IDF in LadybugDB, pheromone weights updated on each retrieval.

memory_store_episodeNo LLM at write — sub-ms in-process engine write op

Store an episodic memory event for an agent. Zero-LLM: uses TF-IDF entity extraction, never calls an LLM.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Unique agent identifier
content	string	✅	The episode text, stored verbatim
metadata	object	❌	Arbitrary JSON metadata (tags, user_id, session_id, etc.)
occurred_at	string (ISO 8601)	❌	When the event occurred. Defaults to server time
importance	float [0,1]	❌	Initial importance weight. Default: 0.5

Returns

{ id, agent_id, content, occurred_at, created_at, importance, pheromone_weight, metadata }

Example call

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

memory_get_episodes

Retrieve episodes for an agent with optional filters. Returns chronological order (newest first) with semantic ranking when a query is provided.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Agent to get episodes for
query	string	❌	Optional semantic query to rank results by relevance
limit	integer	❌	Max results. Default: 10, max: 100
since	string (ISO 8601)	❌	Only episodes after this timestamp
until	string (ISO 8601)	❌	Only episodes before this timestamp
tags	array[string]	❌	Filter by metadata tags (AND logic)

Returns

{ episodes: [...with score field], total }

Example call

{
  "jsonrpc": "2.0", "id": 2,
  "method": "tools/call",
  "params": {
    "name": "memory_get_episodes",
    "arguments": {
      "agent_id": "research-agent-1",
      "query": "quarterly financial reports",
      "limit": 5,
      "since": "2026-01-01T00:00:00Z"
    }
  }
}

memory_search_episodes

Full-text and semantic search over episodes. Ranked by: TF-IDF similarity × pheromone weight × recency decay.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Agent to search episodes for
query	string	✅	Natural language query text
limit	integer	❌	Max results. Default: 10, max: 100
min_score	float [0,1]	❌	Minimum relevance score threshold. Default: 0.0
tags	array[string]	❌	Filter by metadata tags

Returns

{ episodes: [...with score field], total_checked }

Example call

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

memory_search_timeline

Search episodes within a time range with optional keyword filter. Optimized for temporal lookups using LadybugDB temporal index.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Agent to search
since	string (ISO 8601)	✅	Start of time range
until	string (ISO 8601)	✅	End of time range
keywords	array[string]	❌	Optional keyword filter (OR logic)
limit	integer	❌	Max results. Default: 50

Returns

Episodes sorted by occurred_at ascending.

Example call

{
  "jsonrpc": "2.0", "id": 4,
  "method": "tools/call",
  "params": {
    "name": "memory_search_timeline",
    "arguments": {
      "agent_id": "research-agent-1",
      "since": "2026-05-12T00:00:00Z",
      "until": "2026-05-12T23:59:59Z",
      "keywords": ["finance", "report"]
    }
  }
}

memory_consolidate_episodes

Merge multiple episodes from a time window into a single consolidated episode. Rule-based (no LLM) — concatenates and deduplicates by TF-IDF similarity.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Agent whose episodes to consolidate
since	string (ISO 8601)	✅	Start of window
until	string (ISO 8601)	✅	End of window
similarity_threshold	float [0,1]	❌	TF-IDF similarity merge threshold. Default: 0.85

Returns

New consolidated episode + { merged_count, deleted_ids }

Example call

{
  "jsonrpc": "2.0", "id": 5,
  "method": "tools/call",
  "params": {
    "name": "memory_consolidate_episodes",
    "arguments": {
      "agent_id": "research-agent-1",
      "since": "2026-04-01T00:00:00Z",
      "until": "2026-04-30T23:59:59Z",
      "similarity_threshold": 0.8
    }
  }
}

Semantic Memory — Entities & Relations

5 tools

Named entities and typed relationships. Forms a directed knowledge graph in LadybugDB. Temporal validity (valid_at / invalid_at) models facts that change over time.

memory_store_entity<10ms (LadybugDB native graph write, no LLM)

Store a named entity in the agent's knowledge graph. Entities are the nodes of your graph — people, companies, concepts, documents.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Owning agent
name	string	✅	Entity name (e.g., "Acme Corp", "Alice", "Q3 Budget")
entity_type	string	✅	Type category (e.g., "person", "organization", "concept", "document")
properties	object	❌	Key-value properties for the entity
metadata	object	❌	Arbitrary additional metadata

Returns

{ id, name, entity_type, properties, created_at }

Example call

{
  "jsonrpc": "2.0", "id": 6,
  "method": "tools/call",
  "params": {
    "name": "memory_store_entity",
    "arguments": {
      "agent_id": "research-agent-1",
      "name": "Acme Corp",
      "entity_type": "organization",
      "properties": { "industry": "technology", "founded": 2020 }
    }
  }
}

memory_get_entity

Retrieve a specific entity by ID or by name + agent_id.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Owning agent
entity_id	string	❌	The entity ID (ent_...)
name	string	❌	Entity name for direct lookup

Returns

Single entity object, or error -32004 if not found.

Example call

{
  "jsonrpc": "2.0", "id": 7,
  "method": "tools/call",
  "params": {
    "name": "memory_get_entity",
    "arguments": {
      "agent_id": "research-agent-1",
      "name": "Acme Corp"
    }
  }
}

memory_list_entities

List all entities for an agent, with optional type filter and pagination.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Agent to list entities for
entity_type	string	❌	Filter by entity type
limit	integer	❌	Max results. Default: 50
offset	integer	❌	Pagination offset. Default: 0

Returns

{ entities: [...], total, offset, limit }

Example call

{
  "jsonrpc": "2.0", "id": 8,
  "method": "tools/call",
  "params": {
    "name": "memory_list_entities",
    "arguments": {
      "agent_id": "research-agent-1",
      "entity_type": "organization",
      "limit": 20
    }
  }
}

memory_store_relation<10ms (direct graph write)

Create a typed relationship (edge) between two entities in the knowledge graph.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Owning agent
source	string	✅	Source entity name or ID
relation_type	string	✅	Relationship type (e.g., "works_at", "approved", "authored")
target	string	✅	Target entity name or ID
properties	object	❌	Edge properties (weight, confidence, etc.)
valid_at	string (ISO 8601)	❌	When this relation became true
invalid_at	string (ISO 8601)	❌	When this relation stopped being true

Returns

{ id, source, relation_type, target, properties, created_at }

Example call

{
  "jsonrpc": "2.0", "id": 9,
  "method": "tools/call",
  "params": {
    "name": "memory_store_relation",
    "arguments": {
      "agent_id": "research-agent-1",
      "source": "Alice",
      "relation_type": "approved",
      "target": "Q3 Budget",
      "properties": { "confidence": 0.95 },
      "valid_at": "2026-01-15T00:00:00Z"
    }
  }
}

memory_get_relations

Get all relations for an entity, optionally filtered by relation type and direction.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Owning agent
entity	string	✅	Entity name or ID to get relations for
relation_type	string	❌	Filter to specific relation type
direction	string	❌	"outgoing", "incoming", or "both". Default: "both"
limit	integer	❌	Max results. Default: 50

Returns

{ relations: [...], total }

Example call

{
  "jsonrpc": "2.0", "id": 10,
  "method": "tools/call",
  "params": {
    "name": "memory_get_relations",
    "arguments": {
      "agent_id": "research-agent-1",
      "entity": "Alice",
      "direction": "outgoing"
    }
  }
}

Graph & Search

6 tools

Query the knowledge graph, run semantic search, find neighbors, add triples, and compute shortest paths. Powered by LadybugDB (active fork of Kùzu).

memory_query_graph

Run a structured query against the knowledge graph. Supports entity/relation filters and multi-hop patterns.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Agent whose graph to query
query	string	✅	Natural language or structured graph query
limit	integer	❌	Max results. Default: 20
entity_types	array[string]	❌	Filter to specific entity types
relation_types	array[string]	❌	Filter to specific relation types

Returns

{ results: [...], query_ms }

Example call

{
  "jsonrpc": "2.0", "id": 11,
  "method": "tools/call",
  "params": {
    "name": "memory_query_graph",
    "arguments": {
      "agent_id": "research-agent-1",
      "query": "Who approved the Q3 budget?",
      "limit": 10
    }
  }
}

memory_semantic_search

Semantic search across all memory types (episodes, entities, relations, procedures). Returns results ranked by TF-IDF similarity × pheromone weight.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Agent to search
query	string	✅	Natural language search query
memory_types	array[string]	❌	Limit to types: ["episodic","entity","relation","procedural"]. Default: all
limit	integer	❌	Max results. Default: 10
min_score	float [0,1]	❌	Minimum relevance threshold

Returns

{ results: [...with type and score], total_checked }

Example call

{
  "jsonrpc": "2.0", "id": 12,
  "method": "tools/call",
  "params": {
    "name": "memory_semantic_search",
    "arguments": {
      "agent_id": "research-agent-1",
      "query": "What do we know about Acme Corp?",
      "memory_types": ["entity", "relation", "episodic"],
      "limit": 15
    }
  }
}

memory_get_neighbors

Get immediate neighbors of an entity in the knowledge graph (1-hop). Fast lookup for exploring local graph structure.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Agent whose graph to query
entity	string	✅	Entity name or ID
direction	string	❌	"outgoing", "incoming", or "both". Default: "both"
limit	integer	❌	Max neighbors. Default: 20

Returns

{ neighbors: [...with relation info], count }

Example call

{
  "jsonrpc": "2.0", "id": 13,
  "method": "tools/call",
  "params": {
    "name": "memory_get_neighbors",
    "arguments": {
      "agent_id": "research-agent-1",
      "entity": "Acme Corp",
      "direction": "both",
      "limit": 20
    }
  }
}

memory_graph_add_triple<15ms (creates entities + edge)

Add a (subject, predicate, object) triple to the knowledge graph. Convenience method that auto-creates entities if they don't exist.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Owning agent
subject	string	✅	Subject entity name
predicate	string	✅	Relationship predicate
object	string	✅	Object entity name
subject_type	string	❌	Type for auto-created subject entity. Default: "entity"
object_type	string	❌	Type for auto-created object entity. Default: "entity"
properties	object	❌	Edge properties

Returns

{ subject_id, relation_id, object_id, created_entities: [...] }

Example call

{
  "jsonrpc": "2.0", "id": 14,
  "method": "tools/call",
  "params": {
    "name": "memory_graph_add_triple",
    "arguments": {
      "agent_id": "research-agent-1",
      "subject": "Fetch.ai",
      "predicate": "develops",
      "object": "Agentverse Memory",
      "subject_type": "organization",
      "object_type": "product"
    }
  }
}

memory_graph_neighbors

Multi-hop neighbor exploration with depth control. Returns subgraph of nodes and edges within N hops of a seed entity.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Agent whose graph to explore
entity	string	✅	Seed entity name or ID
max_depth	integer	❌	Max hop depth. Default: 2, max: 5
relation_types	array[string]	❌	Only traverse these relation types
limit	integer	❌	Max nodes. Default: 50

Returns

{ nodes: [...], edges: [...], depth_reached }

Example call

{
  "jsonrpc": "2.0", "id": 15,
  "method": "tools/call",
  "params": {
    "name": "memory_graph_neighbors",
    "arguments": {
      "agent_id": "research-agent-1",
      "entity": "Acme Corp",
      "max_depth": 2,
      "limit": 30
    }
  }
}

memory_graph_shortest_path

Find the shortest path between two entities in the knowledge graph using BFS/A* with optional pheromone-weighted edges.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Agent whose graph to search
source	string	✅	Source entity name or ID
target	string	✅	Target entity name or ID
max_depth	integer	❌	Maximum path length. Default: 6
weighted	boolean	❌	Use pheromone-weighted A* (vs unweighted BFS). Default: false

Returns

{ path: [nodes with edges], total_weight, hops } or null if no path.

Example call

{
  "jsonrpc": "2.0", "id": 16,
  "method": "tools/call",
  "params": {
    "name": "memory_graph_shortest_path",
    "arguments": {
      "agent_id": "research-agent-1",
      "source": "Alice",
      "target": "Q3 Budget",
      "max_depth": 5,
      "weighted": true
    }
  }
}

Procedural Memory

4 tools

Skill definitions: goal → steps → outcome. Stores repeatable workflows an agent has learned. Matched by TF-IDF similarity to goal descriptions.

memory_store_procedure

Store a procedural memory — a named skill with goal, step sequence, and outcome description.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Owning agent
name	string	✅	Unique skill name (e.g., "generate_q1_report")
goal	string	✅	What this procedure accomplishes
steps	array[string]	✅	Ordered list of step descriptions
outcome	string	❌	Expected output or success criteria
metadata	object	❌	Arbitrary metadata

Returns

Stored procedure object with id.

Example call

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

memory_get_procedure

Retrieve a specific procedure by ID or by name.

Parameters

Name	Type	Req.	Description
procedure_id	string	❌	The procedure ID (proc_...)
agent_id	string	❌	Agent (required if using name lookup)
name	string	❌	Procedure name for direct lookup

Returns

Single procedure object, or error -32004.

Example call

{
  "jsonrpc": "2.0", "id": 18,
  "method": "tools/call",
  "params": {
    "name": "memory_get_procedure",
    "arguments": {
      "agent_id": "research-agent-1",
      "name": "generate_q1_report"
    }
  }
}

memory_match_procedure

Find the best matching procedure for a goal. Returns ranked candidates by TF-IDF similarity, with optional context hydration from related episodes.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Agent to search procedures for
goal	string	✅	Goal or task description to match against
limit	integer	❌	Max results. Default: 5
include_context	boolean	❌	Include top relevant episodes as context. Default: false
context_limit	integer	❌	Number of context episodes if include_context=true. Default: 5

Returns

{ procedures: [...with score], context_episodes?: [...] }

Example call

{
  "jsonrpc": "2.0", "id": 19,
  "method": "tools/call",
  "params": {
    "name": "memory_match_procedure",
    "arguments": {
      "agent_id": "research-agent-1",
      "goal": "How do I make a quarterly financial report?",
      "include_context": true
    }
  }
}

memory_update_procedure

Update a procedure's steps, goal, or outcome. Increments version number.

Parameters

Name	Type	Req.	Description
procedure_id	string	✅	The procedure ID to update
goal	string	❌	Updated goal
steps	array[string]	❌	New step list (replaces existing)
outcome	string	❌	Updated outcome

Returns

Updated procedure object with incremented version.

Example call

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

Working Memory

4 tools

Ephemeral key/value store with optional TTL. For scratchpad state, active task context, and short-lived agent state that does not need graph indexing.

memory_set_working

Set a key in the agent's working memory with an optional TTL. Values are stored as JSON.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Owning agent
key	string	✅	Key name (e.g., "current_task", "active_user")
value	any (JSON)	✅	Value to store (any JSON-serializable type)
ttl_seconds	integer	❌	Expiry in seconds. Omit for no expiry. Max: 86400 (24h)

Returns

{ key, set_at, expires_at }

Example call

{
  "jsonrpc": "2.0", "id": 21,
  "method": "tools/call",
  "params": {
    "name": "memory_set_working",
    "arguments": {
      "agent_id": "research-agent-1",
      "key": "current_task",
      "value": { "task": "q1_report", "user": "user_42" },
      "ttl_seconds": 3600
    }
  }
}

memory_get_working

Retrieve a value from working memory by key.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Owning agent
key	string	✅	Key to retrieve

Returns

{ key, value, set_at, expires_at } or null if expired/missing.

Example call

{
  "jsonrpc": "2.0", "id": 22,
  "method": "tools/call",
  "params": {
    "name": "memory_get_working",
    "arguments": { "agent_id": "research-agent-1", "key": "current_task" }
  }
}

memory_list_working

List all non-expired working memory keys for an agent.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Owning agent

Returns

Array of { key, value, set_at, expires_at }

Example call

{
  "jsonrpc": "2.0", "id": 23,
  "method": "tools/call",
  "params": {
    "name": "memory_list_working",
    "arguments": { "agent_id": "research-agent-1" }
  }
}

memory_clear_working

Delete a specific working memory key, or clear all working memory for an agent.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Owning agent
key	string	❌	Specific key to delete. Omit to clear all working memory.

Returns

{ cleared: true, keys_deleted: N }

Example call

{
  "jsonrpc": "2.0", "id": 24,
  "method": "tools/call",
  "params": {
    "name": "memory_clear_working",
    "arguments": { "agent_id": "research-agent-1", "key": "current_task" }
  }
}

Pheromone Trails

2 tools

Stigmergic memory trails with 5 decay types. Deposit pheromones on memories to influence future retrieval ranking. The more a memory is accessed, the stronger its trail.

memory_deposit_pheromone

Deposit a pheromone signal on a memory item (episode, entity, relation, or procedure). Strengthens the retrieval weight for future queries.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Owning agent
target_id	string	✅	ID of the memory item to deposit on
pheromone_type	string	❌	Type: "relevance", "success", "novelty", "importance", "recency". Default: "relevance"
amount	float	❌	Deposit amount (0.0–1.0). Default: 0.1

Returns

{ target_id, new_weight, pheromone_type, deposited_at }

Example call

{
  "jsonrpc": "2.0", "id": 25,
  "method": "tools/call",
  "params": {
    "name": "memory_deposit_pheromone",
    "arguments": {
      "agent_id": "research-agent-1",
      "target_id": "ep_01hxq7kn3mabc",
      "pheromone_type": "success",
      "amount": 0.3
    }
  }
}

memory_get_pheromone

Get the current pheromone weight and trail history for a memory item.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Owning agent
target_id	string	✅	ID of the memory item

Returns

{ target_id, total_weight, trails: [{type, amount, deposited_at}], decay_applied }

Example call

{
  "jsonrpc": "2.0", "id": 26,
  "method": "tools/call",
  "params": {
    "name": "memory_get_pheromone",
    "arguments": {
      "agent_id": "research-agent-1",
      "target_id": "ep_01hxq7kn3mabc"
    }
  }
}

Graph Traversal

2 tools

Advanced graph traversal: multi-hop exploration and shortest-path finding with pheromone-weighted edge costs. A* pathfinding available on Builder+ tiers.

memory_find_pathBuilder+

Find the shortest semantic path between two entities in the knowledge graph. Uses A* pathfinding with pheromone edge weights.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Agent whose graph to search
source	string	✅	Source entity
target	string	✅	Target entity
max_depth	integer	❌	Maximum path length. Default: 5

Returns

{ path: [edge objects], total_weight, hops } or null if no path.

Example call

{
  "jsonrpc": "2.0", "id": 27,
  "method": "tools/call",
  "params": {
    "name": "memory_find_path",
    "arguments": {
      "agent_id": "research-agent-1",
      "source": "Alice",
      "target": "Q3 Budget",
      "max_depth": 4
    }
  }
}

memory_traverse_graph

Traverse the knowledge graph starting from a seed entity. Uses A* with pheromone-weighted edge costs (Pro tier). Explorer/Builder use BFS.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Agent whose graph to traverse
seed_node	string	✅	Starting entity label
max_depth	integer	❌	Maximum hop depth. Default: 2, max: 5 (Pro: 10)
predicate_filter	array[string]	❌	Only traverse edges with these predicates
limit	integer	❌	Max nodes to return. Default: 20

Returns

{ nodes: [...], edges: [...], traversal_ms }

Example call

{
  "jsonrpc": "2.0", "id": 28,
  "method": "tools/call",
  "params": {
    "name": "memory_traverse_graph",
    "arguments": {
      "agent_id": "research-agent-1",
      "seed_node": "Acme Corp",
      "max_depth": 3,
      "limit": 30
    }
  }
}

Shared Spaces

5 tools

Multi-agent shared memory with JWT/DID-authenticated access control. Create spaces, invite agents, share entities, and query across all members' knowledge graphs.

memory_create_shared_spaceBuilder+

Create a shared memory space. The creating agent becomes the space owner. Uses JWT Bearer token authentication for secure access.

Parameters

Name	Type	Req.	Description
owner_agent_id	string	✅	Creating/owning agent
name	string	✅	Human-readable space name
description	string	❌	Optional space description
max_agents	integer	❌	Max agents allowed in space. Default: 10

Returns

{ space_id, name, invite_token, created_at, owner_agent_id }

Example call

{
  "jsonrpc": "2.0", "id": 29,
  "method": "tools/call",
  "params": {
    "name": "memory_create_shared_space",
    "arguments": {
      "owner_agent_id": "orchestrator-1",
      "name": "research-team",
      "description": "Shared context for the research team",
      "max_agents": 5
    }
  }
}

memory_join_shared_spaceBuilder+

Join an existing shared memory space using an invite token. JWT authentication required.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Joining agent
space_id	string	✅	Space to join
invite_token	string	✅	Invite token from space owner

Returns

{ joined: true, space_id, member_count }

Example call

{
  "jsonrpc": "2.0", "id": 30,
  "method": "tools/call",
  "params": {
    "name": "memory_join_shared_space",
    "arguments": {
      "agent_id": "worker-agent-1",
      "space_id": "space_04ia...",
      "invite_token": "inv_abc123xyz"
    }
  }
}

memory_shared_store_entityBuilder+

Store an entity into a shared space's knowledge graph. The entity becomes visible to all space members.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Storing agent (must be a space member)
space_id	string	✅	Target shared space
name	string	✅	Entity name
entity_type	string	✅	Entity type
properties	object	❌	Entity properties

Returns

{ id, name, entity_type, space_id, stored_by, created_at }

Example call

{
  "jsonrpc": "2.0", "id": 31,
  "method": "tools/call",
  "params": {
    "name": "memory_shared_store_entity",
    "arguments": {
      "agent_id": "worker-agent-1",
      "space_id": "space_04ia...",
      "name": "Project Alpha",
      "entity_type": "project",
      "properties": { "status": "active", "priority": "high" }
    }
  }
}

memory_shared_queryBuilder+

Query the shared knowledge graph across all agents in a space. Returns semantically ranked results from all member agents' contributions.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Querying agent (must be a space member)
space_id	string	✅	Space to query
query	string	✅	Natural language query
limit	integer	❌	Max results. Default: 20
entity_types	array[string]	❌	Filter to specific entity types

Returns

{ results: [...with agent_id and score], space_id, agents_queried }

Example call

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

memory_list_shared_spacesBuilder+

List all shared spaces an agent is a member of, including ownership info and member counts.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Agent to list spaces for

Returns

{ spaces: [{ space_id, name, role, member_count, created_at }] }

Example call

{
  "jsonrpc": "2.0", "id": 33,
  "method": "tools/call",
  "params": {
    "name": "memory_list_shared_spaces",
    "arguments": { "agent_id": "worker-agent-1" }
  }
}

System

2 tools

Usage statistics and agent management. Monitor ops consumption via GET /v1/usage endpoint.

memory_get_stats

Get usage statistics for an agent: entity count, episode count, storage used, ops consumed this billing period.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Agent to get stats for

Returns

{ episode_count, entity_count, relation_count, procedure_count, storage_bytes, ops_this_period, ops_limit, plan }

Example call

{
  "jsonrpc": "2.0", "id": 34,
  "method": "tools/call",
  "params": {
    "name": "memory_get_stats",
    "arguments": { "agent_id": "research-agent-1" }
  }
}

memory_delete_agent

Permanently delete all memory data for an agent — episodes, entities, relations, procedures, working memory, and pheromone trails. This action is irreversible.

Parameters

Name	Type	Req.	Description
agent_id	string	✅	Agent to delete all data for
confirm	boolean	✅	Must be true to confirm deletion

Returns

{ deleted: true, agent_id, items_deleted: { episodes, entities, relations, procedures } }

Example call

{
  "jsonrpc": "2.0", "id": 35,
  "method": "tools/call",
  "params": {
    "name": "memory_delete_agent",
    "arguments": {
      "agent_id": "research-agent-1",
      "confirm": true
    }
  }
}

🐳 Self-Hosting

All 35 tools are available when self-hosting via Docker Compose (Dockerfile.standalone). Run docker compose up to start a local instance with LadybugDB. Usage metering is available at GET /v1/usage.

← MCP Integration

Connecting clients, auth, rate limits

Getting Started →

SDK installation and first memories