Tools Reference

Overview

Quick Decision Guide

Storage Tools

remember

Store an observation without evidence. Writes a Memory node.

Scenario: User mentions a preference.

User: "I always use pnpm, not npm" Agent: [calls remember]

{
  "content": "User prefers pnpm over npm",
  "tags": ["preferences", "tooling"]
}

Parameters:

Returns: { "node_id": "mem_abc123" }

learn

Store a claim with evidence. Writes a Knowledge-layer Claim node.

Scenario: Agent learns a project fact from documentation.

User: "Check the README for the build process" Agent: [reads README, calls learn]

{
  "claim": "Project uses esbuild for bundling",
  "source": "document",
  "evidence": ["file://README.md"],
  "confidence": 0.95
}

Parameters:

Returns: { "node_id": "know_abc123", "evidence_status": "valid" }

update

Supersede existing knowledge with new information.

Scenario: A fact has changed.

Agent: [reads updated config, calls update]

{
  "target": "know_abc123",
  "content": "Project now uses Vite for bundling",
  "evidence": ["https://docs.project.com/build"]
}

Parameters:

*One of target or query is required.

Returns:

• Success: { "status": "updated", "node_id": "new_uuid", "superseded_id": "old_uuid" }
• Ambiguous: { "status": "ambiguous", "candidates": [...] } if query matches multiple nodes
• Not found: { "status": "not_found" } — use learn() instead

Retrieval Tools

recall

Search or fetch knowledge. Call this at the start of any task and before storing anything (to supersede, not duplicate).

Scenario: Agent needs to know user preferences.

{
  "query": "user preferences for package managers"
}

Parameters:

*At least one of query or node_ids should be provided.

Returns: Array of matching nodes with content and metadata. A withheld count is reported when low-confidence nodes are hidden.

Temporal filtering: Requires fusion_mode=true. Accepts relative ("7d", "1w") or ISO datetime.

{"query": "auth changes", "fusion_mode": true, "since": "7d"}

trace

Trace the provenance of a belief back to its sources.

Scenario: User asks why agent thinks something.

User: "Why do you think I prefer functional programming?"

{
  "node_id": "bel_abc123",
  "direction": "up"
}

Parameters:

Returns: Provenance chain with confidence at each step, plus root_sources (up) or leaf_nodes (down).

Management Tools

forget

Request deletion of a node. Enters tombstone state before permanent deletion.

Scenario: User requests data deletion.

{
  "node_id": "mem_abc123",
  "reason": "User requested deletion"
}

Parameters:

Returns: { "status": "tombstoned", "node_id": "...", "cascade_count": 3 }

tick

Lightweight engagement check. Use when you have seen a marker but choose not to act on it, or to signal active engagement.

Scenario: Agent notices an engagement marker but the current task is unrelated.

{
  "about_hint": ["node_123", "node_456"],
  "engagement_type": "viewed"
}

Parameters:

Returns: { "status": "ok", "markers": [...], "nudges": [...] }

Coordination Tools

agents

List agents registered in the silo.

{}

Parameters:

Returns:

{
  "agents": [
    {
      "agent_id": "uuid",
      "role": "assistant",
      "first_seen": "2024-01-01T00:00:00Z",
      "last_seen": "2024-01-15T00:00:00Z",
      "node_count": 42,
      "trust_score": 0.85
    }
  ]
}

introspect

Query metacognitive state of the knowledge graph.

Parameters:

Query types:

• volatility: Topics with high supersession churn (unstable knowledge)
• gaps: Frequently-asked but unanswered queries
• provenance: Which agents contributed to a belief
• contributions: Agent contribution stats

{"query_type": "gaps", "min_threshold": 3}

conflicts

List contradictions between nodes.

{
  "status": "unresolved",
  "limit": 10
}

Parameters:

Returns: Array of conflicts with both node contents and agent attributions.

dismiss_conflict

Mark a conflict as not-a-real-conflict.

{
  "conflict_id": "uuid",
  "reason": "Different contexts, not actually contradictory"
}

escalate_conflict

Flag a conflict for human review.

{
  "conflict_id": "uuid",
  "message": "Need domain expert to verify"
}

resolve_conflict

Pick a winner and optionally supersede the loser.

{
  "conflict_id": "uuid",
  "winner_id": "node_uuid",
  "supersede": true
}

Parameters: