MCP Tool Reference

SHAPECategories at a glance

DISCOVERYDiscovery — orient before you act

Lightweight probes an agent uses on session start: is the engine alive, how big is the graph, what types exist, and where has activity concentrated lately.

ping

Liveness check. Returns engine status, version, and node count.

{}

get_summary

Total objects, attributes, edges, and per-type counts.

{}

get_schema

List all types, or get one type with its fields and inheritance chain.

{ "type_name": "concept" }

get_activity_summary

Per-type heat scores — surprise + recency, bounded by a time window.

{ "from_millis": 1712880000000 }

READRead — pull objects out of the graph

The bread-and-butter reads. One object by id, paginated lists by type, substring or exact-index search on attributes, and two graph walks for ancestry and downstream impact.

get_object

One object by ULID — full attributes, outgoing and incoming edges.

{ "object_id": "01JRW...", "include_lineage": true }

list_objects

Paginated list by type. Includes descendant types via the hierarchy.

{ "object_type": "concept", "limit": 10, "page": 0 }

search_objects

Substring match on an attribute value. Returns summaries.

{ "key": "title", "value": "turbo", "limit": 10 }

search_indexed

Exact match using the B-tree attribute index. Filter-by-field on a type.

{ "object_type": "concept", "filters": { "status": "developing" }, "limit": 50 }

traverse_references

BFS along edges. Direction (outgoing / incoming / both), depth, edge type.

{ "start_id": "01JRW...", "direction": "outgoing", "max_depth": 2 }

forward_trace

Walk incoming edges only — discover what depends on a given object.

{ "object_id": "01JRW...", "max_depth": 3 }

WRITEWrite — mutate the graph

The minimal write surface. Every mutation goes through the commitlog with per-principal attribution, and every write triggers re-embedding so semantic search stays in sync.

create_object

New object of a given type with initial attributes and optional parent.

{ "object_type": "concept", "attributes": { "title": "New Concept", "status": "seed" } }

set_attributes

Patch attributes on an existing object. Rejects invalid state-machine transitions.

{ "object_id": "01JRW...", "attributes": { "status": "mature" } }

delete_object

Delete an object and every edge touching it.

{ "object_id": "01JRW..." }

delete_attribute

Remove a single attribute from an object — does not delete the object.

{ "object_id": "01JRW...", "key": "status" }

SEMANTICSemantic — vector search

Embeddings are local (all-MiniLM-L6-v2 via ONNX) and compressed to 3-bit via TurboQuant. Semantic search runs against the per-twin vector index; no cloud call.

semantic_search

Natural-language query → top-k matches by cosine similarity.

{ "query": "how does knowledge graph compression work", "top_k": 5, "min_score": 0.3 }

find_similar

Top-k objects nearest a given object in embedding space.

{ "object_id": "01JRW...", "top_k": 5 }

MEMORY LOOPMemory loop — context, relevance, curation

The Phase 5.7 / 5.8 surface. A blended relevance signal (semantic similarity + recency + surprise), a budget-capped context envelope across five tiers, and an explicit keep / drop call agents run at session end.

load_relevant_context

Per-principal context envelope — seeds, lineage, siblings, descendants, lateral. Budget-capped.

{ "query": "vector compression for edge devices", "object_types": ["concept", "entity"], "top_k": 10 }

get_relevance

Rank nodes by surprise-gated relevance — surprise + momentum + recency.

{ "object_type": "concept", "limit": 10 }

curate_memory

End-of-session handoff. Boost what was useful, suppress what was noise.

{ "keep": ["01JRW..."], "drop": ["01JRX..."] }

TYPE SYSTEMType system — schema as data

Schema lives in the graph. Agents define types and extend them at runtime; no migration step, no engine restart. The type hierarchy is inherited transparently into list and traversal queries.

define_object_type

Create a new object type with optional parent and field definitions.

{ "type_name": "decision", "parent_type": "concept", "fields": [{ "name": "outcome", "field_type": "text" }] }

add_field_to_type

Extend an existing type with one more field. Existing objects keep their shape.

{ "type_name": "concept", "field": { "name": "owner", "field_type": "text", "required": false } }

STATEState machine — declare and audit

A state machine attaches to a field on a type. The engine enforces allowed transitions on every write and keeps the full transition log as an audit trail.

define_state_machine

States, initial state, transitions, terminal states — bound to a type and a field.

{ "object_type": "decision", "states": ["proposed","accepted","rejected"], "initial_state": "proposed", "transitions": [{ "from": "proposed", "to": "accepted" }] }

get_transition_history

Audit trail of every state change on one object.

{ "object_id": "01JRW..." }

BACKUPBackup — snapshot the runtime

The commitlog is the system of record; the snapshot is a fast-rehydrate optimisation. Backup bundles both, plus the vector index, into one timestamped archive.

backup_data

Bundle the .ioboxx runtime data — snapshot, commitlog, vectors — into an archive.

{ "output_dir": "./backups" }

TRANSPORTStdio for Claude Code, HTTP for everything else

The engine ships two transports. Pick by client.

• Stdio. Started by the client at session open, terminated at session close. The IDE owns the lifecycle; there is no background process to babysit. This is the path for Claude Code, Cursor, and Claude Desktop. Pass --stdio --no-watch when the engine is launched.
• Streamable HTTP. A persistent server at http://localhost:3002/mcp (the binary’s default port). Used by long-running agents, hosted deployments, and any MCP client that prefers a network endpoint over a spawned subprocess.

AUTHOne JWT, one trust boundary

For local stdio sessions there is no auth — the transport is per-process and the agent inherits the user’s shell trust. For HTTP and hosted deployments, every tools/call carries a Bearer JWT.

• JWT auth. The engine takes a --jwt-secret flag and validates every request against it. In the IOBOXX deployment Keycloak is the IdP and the same ES256 key authenticates SpacetimeDB SQL and the MCP tower. One token, both surfaces, no drift path.
• Commitlog integrity. A separate --hmac-key flag enables HMAC-signed commitlog entries. This is integrity, not auth — it gates whether a replayed log entry is trusted at startup.
• OAuth 2.0. Supported per the MCP spec for MCP server endpoints that front a third-party identity provider; the standard Anthropic-authored protocol covers the handshake.

AGENTSAgents are users

Every agent that touches the graph registers as a first-class principal — its own AppUser id, its own email (agent-claude-code@system.local for the Claude Code Fundi). Registration goes through a register_agent reducer on the state engine before the agent issues any tool calls. The Phase 5.6 principal model means every write on the commitlog carries the agent’s identity; token-compensation attribution and per-principal relevance both fall out of the same log.

That’s why the tool surface above doesn’t include identity management — identity lives in the state engine’s reducer layer, not in the MCP. The MCP layer assumes the principal is already established and dispatches every call against it.

RELATEDWhere to go next

• /docs/quickstart — wire the engine into Claude Code in five minutes.
• /docs/architecture/memory — what the tools above act on. The two-layer substrate.
• /docs/architecture/memory/portability — why an MCP client and an LLM choice are independent of the memory.