retrieve_with_traversal

Explore connected memory nodes from a starting point to analyze relationships and dependencies within a semantic graph, using depth limits and edge type filters.

Instructions

Start from a specific memory node and traverse the graph outward. Returns the starting node plus all reachable neighbors within the depth limit, scored by edge weight decay and depth penalty. Use after search_memory_graph to explore a specific node's neighborhood.

Input Schema

TableJSON Schema

Name	Required	Description
`start_node_id`	Yes	ID of the memory node to start traversal from.
`max_depth`	No	Maximum traversal depth from start node. Default: 2.
`edge_filter`	No	Only traverse edges of these types. Omit for all.

Implementation Reference

src/tools/memory-tools.ts:134-142 (handler)

The tool handler 'toolRetrieveWithTraversal' that processes the request and formats the output.

export async function toolRetrieveWithTraversal(options: RetrieveWithTraversalOptions): Promise<string> {
  const results = await retrieveWithTraversal(options.rootDir, options.startNodeId, options.maxDepth, options.edgeFilter);
  if (results.length === 0) return `❌ Node not found: ${options.startNodeId}`;

  const sections = [`Traversal from: ${results[0].node.label} (depth limit: ${options.maxDepth ?? 2})\n`];
  for (const result of results) sections.push(formatTraversalResult(result));

  return sections.join("\n");
}

src/core/memory-graph.ts:312-332 (handler)

The core implementation of 'retrieveWithTraversal' which handles graph traversal logic.

export async function retrieveWithTraversal(rootDir: string, startNodeId: string, maxDepth: number = 2, edgeFilter?: RelationType[]): Promise<TraversalResult[]> {
  const graph = await loadGraph(rootDir);
  const startNode = graph.nodes[startNodeId];
  if (!startNode) return [];

  startNode.lastAccessed = Date.now();
  startNode.accessCount++;

  const results: TraversalResult[] = [{
    node: startNode,
    depth: 0,
    pathRelations: [startNode.label],
    relevanceScore: 100,
  }];

  const visited = new Set([startNodeId]);
  collectTraversal(graph, startNodeId, 1, maxDepth, [startNode.label], visited, results, edgeFilter);

  scheduleSave(rootDir);
  return results;
}

src/tools/memory-tools.ts:43-48 (schema)

The interface 'RetrieveWithTraversalOptions' defining the input schema for the tool.

export interface RetrieveWithTraversalOptions {
  rootDir: string;
  startNodeId: string;
  maxDepth?: number;
  edgeFilter?: RelationType[];
}

Context+