Loading ToolBench
Fractal memory system for Roo Code via MCP protocol — graph-based knowledge management with vector search, navigation history, and multi-tiered viewport (Hot/Cold/Archive)
Cortex presents 15 tools with complete input schemas and structured descriptions. However, quality is uneven. Desktop tools (desktop_open, desktop_focus, desktop_history) have rich, contextual descriptions explaining the fractal memory model. Graph tools (graph_add_node, graph_add_relation, etc.) have clear schemas with type enums and detailed parameter docs. Vector tools are similarly well-structured. However, critical gaps emerge: (1) No documented output schemas, the server provides no specification of what fields/structures tools return, leaving LLMs to infer response format. (2) No error handling guidance, tools lack recovery hints, retryability markers, or actionable error messages. (3) Tool composition is fragmented, graph_update_node and graph_supersede both modify state but with different semantics; descriptions don't clarify when to use each. (4) Schemas use description text to constrain values (e.g., 'Hot=3-10 nodes') rather than formal JSON Schema properties (minItems, maxItems, pattern). These gaps are typical for production knowledge-graph servers but prevent LLMs from reasoning confidently about outputs and error paths. Input definitions are solid (avg 85/100), but output and error design are weak (avg 35/100).
Focus on a specific node — expand its subgraph with all relations and child nodes. Use when you need to explore context around a specific task, fact, or decision. Also logs this focus to navigation history for Hot/Cold tier calculations. workspace_id is OPTIONAL.
Get navigation history for a workspace session. Use to understand what was recently worked on or to restore context. workspace_id is OPTIONAL.
Open a workspace session and return its Desktop Viewport (Hot/Cold/Archive tiers). Use at the START of every task to initialize or resume a session. Returns: session root, hot nodes (current focus + direct relations), cold nodes (other active nodes, titles only), archive info (old nodes, search only). Hot=3-10 nodes always in context, Cold=10-100 by focus/search, Archive=100+ by vector_search only. Without workspace_id, opens YOUR PROJECT's workspace (from CORTEX_WORKSPACE_ID / --workspace). To see another project's viewport, pass its workspace_id explicitly.
Add a node to the knowledge graph. Supports 13 types (entity, fact, decision, thought, chunk, question, hypothesis, action, error, note, pattern, goal, constraint — all vectorized; session, task, subtask, fileref — graph only). Text in data.text or data.title is automatically indexed into Qdrant vector search for vectorizable types. For fileref nodes, pass path in data.path. workspace_id is OPTIONAL.
No documented output schemas. Tools list input parameters with full JSON Schema detail, but return types are undocumented. LLMs cannot predict what fields (node_id, relations, hot_nodes, etc.) to expect from graph_open or graph_get_node responses. This forces LLMs to guess the structure and makes error recovery impossible.
No error handling guidance. Tools lack error recovery hints. E.g., graph_search and vector_search may return no results, but descriptions don't say 'returns empty array if no matches found' or 'try graph_traverse to explore nearby context'. graph_delete_node is destructive (marked DESTRUCTIVE) but lacks a dry_run option or confirmation pattern to prevent accidental cascading deletes.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 55 | <=2025-11-25 | v2 |
Create a relation between two nodes. Supports 22 relation types: Hierarchical (contains, decomposes_to, belongs_to), Semantic (derives_from, supports, contradicts, related_to, questions, answers), Index (indexes Entity->Fileref, extracted_from Fact/Chunk->Fileref, references, implements, relates_to_file), Chronological (sequel_to, supersedes, leads_to, resolves, triggers), Dependency (depends_on, blocks, constrained_by).
Decompose a task into subtasks.
Delete a node (and optionally its subtree).
Get a node with its relations and child nodes. Use to inspect a node's full context: what it contains, what it relates to, what references it.
Full-text + semantic search across the graph (SQLite LIKE + Qdrant vector similarity). Search optionally across all workspaces or narrow to one. Returns ranked results.
Supersede a node (create new version, link old -> new via 'supersedes' relation, archive old). Use when a thought/decision/fact is outdated but you want to keep history.
Traverse the graph starting from a node, following relations. Optionally filter by relation type. Uses recursive CTE up to specified depth. Use to discover how nodes are connected in the graph.
Update a node's data or apply a mutation strategy (Strategy A: Update, Strategy B: Supersede).
Walk along a reasoning chain (sequel_to, derives_from, leads_to). Returns nodes in backward and forward directions.
Pure semantic search (Qdrant) without full-text fallback. Useful for similarity across all workspaces or when full-text is not needed.
Manually index a piece of text into Qdrant under a workspace. Useful for external content (documents, web pages, etc.) that you want to make searchable.
Overlapping tool semantics without clear disambiguation. graph_update_node (strategy: update|supersede) and graph_supersede both modify state, but the distinction is buried in optional strategy enum. LLMs may incorrectly choose one over the other. Description should explicitly state: 'Use graph_update_node for edits that preserve node identity; use graph_supersede when creating a new version with full history tracking.'
Constraint description vs formal schema mismatch. Parameters like node_type use free-text enum descriptions (e.g., 'Supports 13 types (entity, fact, decision, ...)') but some enums embedded in description text rather than strict JSON Schema enum arrays. This works but is not machine-parseable, tools accepting arbitrary user input risk malformed requests.
Missing pagination guidance for list-like results. graph_search and vector_search accept top_k (max results) but no guidance on whether results are ranked, paginated, or cursor-based. For large workspaces, returning top_k items may truncate crucial results. Description should clarify ranking and offer next_cursor or offset patterns if results exceed limit.
workspace_id resolution is implicit and non-standard. Many tools document 'workspace_id is OPTIONAL' and 'falls back to env/CWD folder name / default', but this fallback logic is not formally specified and could surprise LLMs unfamiliar with Cortex. Parameters should explicitly name fallback behavior: '(Optional. Defaults to CORTEX_WORKSPACE_ID env var, then current directory name, then "default".)'
Data loss risk from default values. graph_delete_node has cascade=false as default, which is safe, but graph_decompose and graph_update_node both accept generic 'data' objects (untyped JSON) that could silently overwrite fields. Descriptions should warn: 'data is merged (not replaced), existing fields not in data are preserved.' or 'data replaces entire node, preserve fields you want to keep.'
Tool composition gaps. Desktop viewport tools (desktop_open, desktop_focus) and graph_get_node both fetch node context, but it's unclear which is better for a given task. Descriptions lack guidance on when to use desktop tier-based retrieval vs direct graph traversal. LLMs will experiment inefficiently.