Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Memory & Learning Tools

Seven tools for feedback-based learning, drift analysis, path explanation, and investigation trail management.

Current source limits: all v1 calibration rows are legacy_evidence_unqualified. Prediction abstains; the seek envelope stays at reverify or unprovable, retaining scores and rankings but emitting no current calibration receipt. Diagnostic calibrate_predict and calibrate_envelope handlers can persist historical rows without enabling act. Generic learn, debrief, and calibration routes remain policy-disabled. See calibration qualification.

Source clock contract: envelope calibration evaluates direct TrustLedger::record_defect history in Unix seconds, while row and historical receipt timestamps retain epoch milliseconds. Generic relevance feedback no longer writes that history. The unit repair does not establish statistical accuracy. See the clock contract and regression scope.


learn

Internal relevance-feedback edge adjustment. correct strengthens and wrong weakens existing edges among the resolved nodes and their direct contains children. Neither declares a defect, false alarm, or observed co-change. partial is refused without mutation because its single node list does not attribute the mixed feedback.

partial returns partial_feedback_requires_explicit_attribution; a zero-strength correct/wrong response has status: "no_op" and zero learning event counts.

The generic MCP/REST route remains policy-disabled. The request below documents its payload; it is not a public call recipe. See the learning event contract.

Parameters

ParameterTypeRequiredDefaultDescription
querystringYes–Context for the relevance feedback; it does not supply verified defect evidence.
agent_idstringYes–Calling agent identifier.
feedbackstringYes–Feedback type. Values: "correct" (relevance strengthening), "wrong" (relevance weakening). "partial" is recognized but refused without mutation; unknown values are also refused.
node_idsstring[]Yes–Node identifiers to apply feedback to. For "correct", these are the relevant results. For "wrong", these are the irrelevant ones.
strengthnumberNo0.2Finite, nonnegative adjustment magnitude; zero is a no-op. Existing edge-weight bounds apply.

Example Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "learn",
    "arguments": {
      "agent_id": "agent-1",
      "query": "session pool management",
      "feedback": "correct",
      "node_ids": ["file::session_pool.py", "file::worker_pool.py"],
      "strength": 0.3
    }
  }
}

Illustrative Internal Response

{
  "query": "session pool management",
  "feedback": "correct",
  "feedback_semantics": "retrieval_relevance",
  "nodes_found": 2,
  "nodes_expanded": 4,
  "edges_modified": 8,
  "strength": 0.3,
  "trust_records_updated": 0,
  "co_change_observations_recorded": 0,
  "tremor_observations_recorded": 2,
  "antibody_added": false
}

Interpretation

  • Relevant and irrelevant results can guide graph weighting in an authorized internal path.
  • Generic calls remain authority-blocked; do not retry a floor refusal.
  • A useful result does not prove a defect, a source change, or statistical calibration.

Side Effects

Positive-strength correct/wrong feedback can modify existing graph relevance weights and their weight-change telemetry. It does not write defect/false-alarm/partial ledger entries, observed co-change, or automatic antibodies. partial, invalid inputs, and zero strength leave learning state unchanged. Existing persistence formats and independently verified/observed producers are retained.

  • activate – the query tool whose results you are providing feedback on
  • drift – see cumulative weight changes from learning

drift

Weight and structural drift analysis. Compares the current graph state against a baseline (typically "last_session") to show what changed – new edges, removed edges, and weight drift. Useful for context recovery at session start.

Parameters

ParameterTypeRequiredDefaultDescription
agent_idstringYes–Calling agent identifier.
sincestringNo"last_session"Baseline reference point. Values: "last_session" (saved state from previous session), or a timestamp.
include_weight_driftbooleanNotrueInclude edge weight drift analysis. Shows which edges strengthened or weakened.

Example Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "drift",
    "arguments": {
      "agent_id": "agent-1",
      "since": "last_session",
      "include_weight_drift": true
    }
  }
}

Example Response

{
  "since": "last_session",
  "node_count_delta": 15,
  "edge_count_delta": 42,
  "new_nodes": ["file::forem_publisher.py", "file::forem_routes.py"],
  "removed_nodes": [],
  "top_weight_drifts": [
    { "edge": "session_pool.py -> worker_pool.py", "old": 0.45, "new": 0.72, "delta": 0.27 },
    { "edge": "chat_handler.py -> stream_parser.py", "old": 0.60, "new": 0.48, "delta": -0.12 }
  ],
  "elapsed_ms": 12.0
}

When to Use

  • Session start – after north pre-orients, drift recovers what changed since last session
  • After ingest – see what the new ingest changed
  • After extended learning – track cumulative drift from feedback
  • diverge – higher-level structural drift with anomaly detection
  • health – basic server health (call before drift)

why

Path explanation between two nodes. Finds and explains the relationship paths connecting a source node to a target node. Returns all paths up to max_hops, ranked by cumulative edge strength.

Parameters

ParameterTypeRequiredDefaultDescription
sourcestringYes–Source node identifier.
targetstringYes–Target node identifier.
agent_idstringYes–Calling agent identifier.
max_hopsintegerNo6Maximum hops in path search. Higher values find more indirect paths but take longer.

Example Request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "why",
    "arguments": {
      "agent_id": "agent-1",
      "source": "file::worker_pool.py",
      "target": "file::whatsapp_manager.py",
      "max_hops": 4
    }
  }
}

Example Response

{
  "source": "file::worker_pool.py",
  "target": "file::whatsapp_manager.py",
  "paths": [
    {
      "nodes": ["worker_pool.py", "process_manager.py", "whatsapp_manager.py"],
      "relations": ["calls::cancel", "imports"],
      "cumulative_strength": 0.68,
      "hops": 2
    },
    {
      "nodes": ["worker_pool.py", "spawner.py", "chat_handler.py", "whatsapp_manager.py"],
      "relations": ["imported_by", "calls", "imports"],
      "cumulative_strength": 0.31,
      "hops": 3
    }
  ],
  "total_paths_found": 2,
  "elapsed_ms": 15.0
}

When to Use

  • Understanding dependencies – “why are these two modules connected?”
  • Tracing influence – find the relationship chain between distant modules
  • Bug investigation – understand how a change in A could affect B
  • hypothesize – tests a claim about the relationship (more powerful)
  • impact – finds all affected nodes (broader scope)

trail_save

Persist the current investigation state – nodes visited, hypotheses formed, conclusions reached, and open questions. Captures activation boosts for later restoration.

Parameters

ParameterTypeRequiredDefaultDescription
agent_idstringYes–Calling agent identifier.
labelstringYes–Human-readable label for this investigation.
hypothesesobject[]No[]Hypotheses formed during investigation. Each object has: statement (string, required), confidence (number, default 0.5), supporting_nodes (string[]), contradicting_nodes (string[]).
conclusionsobject[]No[]Conclusions reached. Each object has: statement (string, required), confidence (number, default 0.5), from_hypotheses (string[]), supporting_nodes (string[]).
open_questionsstring[]No[]Open questions remaining for future investigation.
tagsstring[]No[]Tags for organization and search.
summarystringNo–Optional summary. Auto-generated if omitted.
visited_nodesobject[]No[]Explicitly list visited nodes with annotations. Each object has: node_external_id (string, required), annotation (string, optional), relevance (number, default 0.5). If omitted, captured from active perspective state.
activation_boostsobjectNo{}Map of node_external_id to boost weight [0.0, 1.0]. Re-injected on resume.

Example Request

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "trail_save",
    "arguments": {
      "agent_id": "agent-1",
      "label": "auth-leak-investigation",
      "hypotheses": [
        {
          "statement": "Auth tokens leak through session pool",
          "confidence": 0.7,
          "supporting_nodes": ["file::session_pool.py", "file::auth_discovery.py"]
        },
        {
          "statement": "Rate limiter missing from auth chain",
          "confidence": 0.9,
          "supporting_nodes": ["file::middleware.py"]
        }
      ],
      "open_questions": ["Does the rate limiter apply to WebSocket connections?"],
      "tags": ["security", "auth", "session"],
      "activation_boosts": {
        "file::session_pool.py": 0.8,
        "file::auth_discovery.py": 0.6
      }
    }
  }
}

Example Response

{
  "trail_id": "trail_agent1_001_a1b2c3",
  "label": "auth-leak-investigation",
  "agent_id": "agent-1",
  "nodes_saved": 47,
  "hypotheses_saved": 2,
  "conclusions_saved": 0,
  "open_questions_saved": 1,
  "graph_generation_at_creation": 42,
  "created_at_ms": 1710300000000
}

When to Use

  • End of investigation session – save your work before ending a session
  • Before context compaction – checkpoint your investigation state
  • Cross-session continuity – resume exactly where you left off

trail_resume

Restore a saved investigation. Re-injects activation boosts into the graph, validates that saved nodes still exist, detects staleness, and optionally downgrades hypotheses whose supporting nodes are missing.

Parameters

ParameterTypeRequiredDefaultDescription
agent_idstringYes–Calling agent identifier.
trail_idstringYes–Trail ID to resume (from trail_save or trail_list).
forcebooleanNofalseResume even if trail is stale (>50% missing nodes). Default behavior: refuse to resume stale trails.

Example Request

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "trail_resume",
    "arguments": {
      "agent_id": "agent-1",
      "trail_id": "trail_agent1_001_a1b2c3"
    }
  }
}

Example Response

{
  "trail_id": "trail_agent1_001_a1b2c3",
  "label": "auth-leak-investigation",
  "stale": false,
  "generations_behind": 3,
  "missing_nodes": [],
  "nodes_reactivated": 47,
  "hypotheses_downgraded": [],
  "trail": {
    "trail_id": "trail_agent1_001_a1b2c3",
    "agent_id": "agent-1",
    "label": "auth-leak-investigation",
    "status": "active",
    "created_at_ms": 1710300000000,
    "last_modified_ms": 1710300000000,
    "node_count": 47,
    "hypothesis_count": 2,
    "conclusion_count": 0,
    "open_question_count": 1,
    "tags": ["security", "auth", "session"],
    "summary": "Investigating auth token leaks through session pool"
  },
  "elapsed_ms": 22.5
}

When to Use

  • Session start – restore a previous investigation
  • Cross-agent handoff – agent B resumes agent A’s trail
  • After re-ingest – check if investigation nodes survived the graph update
  • trail_save – save a trail to resume later
  • warmup – simpler priming without full trail restoration

trail_list

List saved investigation trails with optional filters. Returns compact summaries suitable for selecting a trail to resume.

Parameters

ParameterTypeRequiredDefaultDescription
agent_idstringYes–Calling agent identifier.
filter_agent_idstringNo–Filter to a specific agent’s trails. None = all agents.
filter_statusstringNo–Filter by status: "active", "saved", "archived", "stale", "merged".
filter_tagsstring[]No[]Filter by tags (any match).

Example Request

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "trail_list",
    "arguments": {
      "agent_id": "agent-1",
      "filter_status": "saved",
      "filter_tags": ["security"]
    }
  }
}

Example Response

{
  "trails": [
    {
      "trail_id": "trail_agent1_001_a1b2c3",
      "agent_id": "agent-1",
      "label": "auth-leak-investigation",
      "status": "saved",
      "created_at_ms": 1710300000000,
      "last_modified_ms": 1710300000000,
      "node_count": 47,
      "hypothesis_count": 2,
      "conclusion_count": 0,
      "open_question_count": 1,
      "tags": ["security", "auth", "session"]
    }
  ],
  "total_count": 1
}

When to Use

  • Session start – see what investigations are available to resume
  • Multi-agent coordination – see trails from other agents
  • Cleanup – find stale or merged trails

trail_merge

Combine two or more investigation trails. Merges visited nodes, hypotheses, and conclusions. Uses confidence+recency scoring for conflict resolution. Discovers cross-connections between independently explored areas.

Parameters

ParameterTypeRequiredDefaultDescription
agent_idstringYes–Calling agent identifier.
trail_idsstring[]Yes–Two or more trail IDs to merge.
labelstringNo–Label for the merged trail. Auto-generated if omitted.

Example Request

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "trail_merge",
    "arguments": {
      "agent_id": "agent-1",
      "trail_ids": ["trail_agent1_001_a1b2c3", "trail_analyst_002_d4e5f6"],
      "label": "combined-auth-investigation"
    }
  }
}

Example Response

{
  "merged_trail_id": "trail_agent1_003_g7h8i9",
  "label": "combined-auth-investigation",
  "source_trails": ["trail_agent1_001_a1b2c3", "trail_analyst_002_d4e5f6"],
  "nodes_merged": 83,
  "hypotheses_merged": 5,
  "conflicts": [
    {
      "hypothesis_a": "Session pool leaks tokens",
      "hypothesis_b": "Session pool tokens are properly scoped",
      "resolution": "resolved",
      "winner": "Session pool leaks tokens",
      "score_delta": 0.35
    }
  ],
  "connections_discovered": [
    {
      "type": "bridge_edge",
      "detail": "auth_discovery.py connects the auth trail to the session trail",
      "from_node": "file::auth_discovery.py",
      "to_node": "file::session_pool.py",
      "weight": 0.72
    }
  ],
  "elapsed_ms": 45.0
}

Conflict Resolution

When merging hypotheses that contradict each other:

  • confidence+recency scoring determines the winner
  • If the score delta is too small, the conflict is marked "unresolved" for human review
  • Source trails are set to "merged" status after a successful merge

When to Use

  • Multi-agent investigation – combine findings from parallel agents
  • Investigation continuation – merge an old investigation with new findings
  • Consolidation – clean up related but separate investigation threads