Tools Reference

Overview

Quick Decision Guide

Tool Reference

remember

Store an observation without evidence.

Scenario: User mentions a preference.

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

{
  "content": "User prefers pnpm over npm",
  "context": "stated during project setup"
}

Parameters:

• content (required): What to remember
• context (optional): When/where this was observed
• supersedes (optional): node_id of knowledge being updated

Returns: { "node_id": "mem_abc123" }

learn

Store a claim with evidence.

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",
  "evidence": [
    {"type": "documentation", "content": "README.md states 'npm run build uses esbuild'", "uri": "file://README.md"}
  ],
  "confidence": 0.95
}

Parameters:

• claim (required): The fact being asserted
• evidence (required): Array of evidence objects
• confidence (optional): 0.0-1.0, defaults to 0.8
• supersedes (optional): node_id being updated

Returns: { "node_id": "know_abc123" }

believe

Form a conclusion from existing knowledge.

Scenario: Agent synthesizes a belief from multiple facts.

{
  "conclusion": "User values developer experience over raw performance",
  "about": ["mem_abc123", "know_def456"],
  "reasoning": "Prefers TypeScript (type safety) and pnpm (speed) over alternatives"
}

Parameters:

• conclusion (required): The belief being formed
• about (required): Array of node_ids this belief is based on
• reasoning (required): Why this conclusion follows
• supersedes (optional): node_id being updated

Returns: { "node_id": "bel_abc123" }

recall

Search and retrieve knowledge.

Scenario: Agent needs to know user preferences.

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

Parameters:

• query (optional): Natural language search
• node_id (optional): Retrieve specific node
• include_evidence (optional): Include evidence chains

Returns: Array of matching nodes with content and metadata.

trace

Show evidence chain for a belief.

Scenario: User asks why agent thinks something.

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

{
  "query": "preference for functional programming"
}

Returns: Evidence chain showing:

• Source observations/claims
• Intermediate inferences
• Confidence at each step

link

Connect two nodes with a typed relationship.

Scenario: Connect related preferences.

{
  "from": "mem_abc123",
  "to": "mem_def456", 
  "relationship": "supports"
}

Parameters:

• from (required): Source node_id
• to (required): Target node_id
• relationship (required): Type of connection (supports, contradicts, related_to, etc.)

Returns: { "link_id": "link_abc123" }

forget

Remove a node from memory.

Scenario: User requests data deletion.

{
  "node_id": "mem_abc123"
}

Parameters:

• node_id (required): Node to remove

Returns: { "deleted": true }

Note: Linked nodes are not deleted, but links to the deleted node are removed.

hypothesize

Create a tentative belief while working through a problem.

Scenario: Agent is debugging and forms a hypothesis.

{
  "hypothesis": "The bug is caused by a race condition in the auth flow",
  "based_on": ["mem_abc123"],
  "confidence": 0.6
}

Parameters:

• hypothesis (required): Tentative belief
• based_on (optional): Supporting node_ids
• confidence (optional): How confident (0.0-1.0)

Returns: { "hypothesis_id": "hyp_abc123", "session_id": "..." }

Hypotheses are working state. Use commit within the same session to crystallize into durable belief.

revise

Update a hypothesis with new information. Only works within the session that created the hypothesis.

Scenario: Agent finds more evidence.

{
  "hypothesis_id": "hyp_abc123",
  "new_content": "The race condition is specifically in the token refresh",
  "new_confidence": 0.8
}

Parameters:

• hypothesis_id (required): Hypothesis to update
• new_content (optional): Updated hypothesis text
• new_confidence (optional): Updated confidence

Returns: Updated hypothesis.

commit

Crystallize a hypothesis into a durable belief.

Scenario: Agent confirms hypothesis was correct.

{
  "hypothesis_id": "hyp_abc123"
}

Parameters:

• hypothesis_id (required): Hypothesis to commit

Returns: { "node_id": "bel_abc123" } (now a belief)

reason

Store a multi-step reasoning chain.

Scenario: Agent documents its reasoning process.

{
  "steps": [
    {"step": 1, "content": "User wants faster builds"},
    {"step": 2, "content": "Current bundler is webpack"},
    {"step": 3, "content": "esbuild is 10-100x faster than webpack"},
    {"step": 4, "content": "Recommend migrating to esbuild"}
  ],
  "conclusion": "Recommend esbuild migration"
}

Parameters:

• steps (required): Array of reasoning steps
• conclusion (required): Final conclusion

Returns: { "node_id": "rsn_abc123" }

reflect

Store a meta-observation about own beliefs.

Scenario: Agent notices a contradiction in its knowledge.

{
  "observation": "My beliefs about user's testing preferences are inconsistent",
  "about": ["bel_abc123", "bel_def456"],
  "action": "Should ask user to clarify"
}

Parameters:

• observation (required): Meta-observation
• about (optional): Relevant node_ids
• action (optional): Suggested action

Returns: { "node_id": "ref_abc123" }

patterns

Get workflow templates for common tasks.

Scenario: Agent wants to know how to handle a situation.

{
  "action": "get",
  "name": "onboarding"
}

Returns: Workflow guide for the requested pattern.

dismiss

Dismiss a Contradiction or StaleCommitment marker after resolving it.

Scenario: Agent has addressed a contradiction flagged by the system and wants to clear it.

{
  "marker_id": "mrk_abc123",
  "reason": "Resolved by updating the stale belief with current evidence"
}

Parameters:

• marker_id (required): ID of the marker to dismiss
• reason (required): Why the marker is being dismissed

Returns: { "dismissed": true }

tick

Acknowledge a system marker without taking any action. Use this when you have seen a marker but deliberately choose not to act on it right now.

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

{
  "about_hint": "stale belief on user testing preferences"
}

Parameters:

• about_hint (optional): Brief note on what was acknowledged

Returns: { "acknowledged": true }