docs: update human and LLM docs and enhance tool/list schemas with actionable next steps
This commit is contained in:
Riz Ashraf committed
1 parent
961abb01e7
commit
4b307b55b9
12 files changed
+307
-336
No files matched your search
+76
-127
@@ -17,16 +17,78 @@ To prevent graph fragmentation and ensure seamless LLM context retrieval:
|
||||
|
||||
---
|
||||
|
||||
## 2. LLM Token Budgeting & RRF Search Optimization
|
||||
## 2. Consolidated Smart Tools Architecture
|
||||
|
||||
* **Token Budgeting (`summary_level` & `max_tokens`)**:
|
||||
When calling `list_active_tasks` or `list_tech_debt`, pass `summary_level: "compact"` or `"detailed"` and `max_tokens: 500` to constrain output size when token context budget is tight.
|
||||
* **Reciprocal Rank Fusion (RRF) Omni-Search**:
|
||||
`omni_search` uses Hybrid RRF (BM25 keyword search + Dense Vector Embeddings) to rank results semantically. You do not need exact keyword matches; query conceptually (e.g. "database lock issues").
|
||||
* **Delta Session Context (`memory://session/delta`)**:
|
||||
Passively read `memory://session/delta` to get a succinct delta of code changes, tasks, and tech debt recorded during the current working session.
|
||||
* **Context Warmup (`context_warmup`)**:
|
||||
Trigger the `context_warmup` prompt at session start to automatically synthesize delta changes, active tasks, tech debt, and pinned files in a single pass.
|
||||
The server consolidates granular single-purpose tools into domain-named smart tools. Always prefer the consolidated tools over legacy aliases:
|
||||
|
||||
* **`tasks`**: Complete task lifecycle management.
|
||||
- `action: "add"`: Create a new task (requires `title`, optional `description`, `git_branch`, `parent_id`, `dependencies`).
|
||||
- `action: "update"`: Update task status (requires `id`, `status: "pending" | "completed" | "cancelled"`).
|
||||
- `action: "delete"`: Delete task and child tasks (requires `id`).
|
||||
- `action: "list"`: List active tasks (optional `git_branch`, `summary_level: "compact" | "detailed" | "full"`, `max_tokens`).
|
||||
- `action: "set_criteria"`: Set acceptance criteria (requires `id`, `criteria: Vec<String>`).
|
||||
- `action: "verify"`: Verify criteria met (requires `id`).
|
||||
|
||||
* **`milestones`**: Milestone tracking.
|
||||
- `action: "add"`: Create milestone (requires `title`).
|
||||
- `action: "update"`: Update milestone status (requires `id`, `status`).
|
||||
- `action: "list"`: List milestones.
|
||||
|
||||
* **`sticky_notes`**: Ephemeral scratchpad notes with TTL.
|
||||
- `action: "add"`: Add note (requires `content`, optional `ttl_seconds`, `session_only`).
|
||||
- `action: "read"`: Read all active notes.
|
||||
- `action: "delete"`: Delete note by index (requires 1-based `index`).
|
||||
- `action: "clear"`: Clear all sticky notes.
|
||||
|
||||
* **`handoff_memos`**: Session handoff notes for future agents.
|
||||
- `action: "leave"`: Leave a memo (requires `content`).
|
||||
- `action: "read"`: Read active handoff memos.
|
||||
- `action: "clear"`: Clear memos.
|
||||
|
||||
* **`pinned_files`**: Focus file working set.
|
||||
- `action: "pin"`: Pin file to focus set (requires `path`).
|
||||
- `action: "unpin"`: Unpin file from focus set (requires `path`).
|
||||
- `action: "list"`: List pinned files.
|
||||
|
||||
* **`context_workspaces`**: Workspace context state snapshots.
|
||||
- `action: "save"`: Save context workspace (requires `name`).
|
||||
- `action: "load"`: Restore saved context workspace (requires `name`).
|
||||
- `action: "list"`: List saved context workspaces.
|
||||
- `action: "delete"`: Delete saved context workspace (requires `name`).
|
||||
- `action: "diff"`: Compare two saved context workspaces (requires `name`, `other_name`).
|
||||
|
||||
* **`pr_checklist`**: Pre-commit and PR checklist.
|
||||
- `action: "add"`: Add checklist item (requires `description`).
|
||||
- `action: "get"`: Get PR checklist items.
|
||||
- `action: "clear"`: Clear PR checklist.
|
||||
|
||||
* **`snippets`**: Reusable code snippet vault.
|
||||
- `action: "store"`: Store snippet (requires `query` as name, optional `language`, `code`, `description`, `tags`).
|
||||
- `action: "search"`: Search snippet vault (optional `query`, `tags`, `hybrid: true`).
|
||||
- `action: "delete"`: Delete snippet (requires `id`).
|
||||
- `action: "tag"`: Attach classification tags (requires `id`, `tags: Vec<String>`).
|
||||
|
||||
* **`decisions`**: Architectural Decision Records (ADRs).
|
||||
- `action: "log"`: Log ADR (requires `title`, optional `status`, `context`, `decision`, `consequences`).
|
||||
- `action: "query"`: Query ADRs (optional `query`).
|
||||
- `action: "delete"`: Delete ADR (requires `id`).
|
||||
|
||||
* **`tech_debt`**: Engineering debt backlog.
|
||||
- `action: "log"`: Log debt item (requires `description`, optional `ideal_solution`, `git_commit`, `git_branch`, `symbol_references`, `line_range`).
|
||||
- `action: "resolve"`: Resolve debt item (requires `id`).
|
||||
- `action: "list"`: List debt items (optional `include_resolved`).
|
||||
|
||||
* **`environment`**: Infrastructure and requirements tracking.
|
||||
- `action: "update_fingerprint"`: Update tool versions.
|
||||
- `action: "read_fingerprint"`: Read tool versions fingerprint.
|
||||
- `action: "log_requirement"`: Log environment variable requirement (requires `key`).
|
||||
- `action: "register"`: Register target environment (requires `name`).
|
||||
- `action: "get_details"`: Read full environment details.
|
||||
|
||||
* **`clipboard`**: OS Clipboard management.
|
||||
- `action: "read"`: Read OS clipboard.
|
||||
- `action: "write"`: Write text/html/files/image to clipboard.
|
||||
- `action: "toggle_watch"`: Toggle auto-clipboard watcher.
|
||||
|
||||
---
|
||||
|
||||
@@ -45,140 +107,27 @@ To prevent graph fragmentation and ensure seamless LLM context retrieval:
|
||||
---
|
||||
|
||||
## 5. Memory State Checkpointing & Rollbacks
|
||||
- **Tool:** `manage_checkpoint` (unifying `checkpoint_state`, `restore_state`, `create_snapshot`, `restore_snapshot`)
|
||||
- **Tool:** `checkpoint_state`, `restore_state` (or `create_snapshot`, `restore_snapshot`)
|
||||
- **When to use:** Before initiating a large refactor, running experimental subagent tasks, or executing destructive batch operations.
|
||||
- **Behavior:** Consolidates state snapshots and point-in-time checkpointers. Use `action: "create"`, `"restore"`, `"list"`, or `"delete"`.
|
||||
- **Behavior:** Saves or restores a point-in-time snapshot of graph entities, active tasks, and tech debt backlogs.
|
||||
|
||||
---
|
||||
|
||||
## 6. Symbol Reference Backlinks
|
||||
- **Tools:** `log_code_change`, `log_error_fix`, `log_tech_debt`
|
||||
- **When to use:** When logging changes or debt tied to specific code symbols or line boundaries.
|
||||
- **Behavior:** Accept `symbol_references` (e.g., `["MemoryState::new", "CreateEntitiesTool"]`) and `line_range` (e.g., `"L45-L90"`), automatically indexing code references for quick symbol backlink searches.
|
||||
|
||||
---
|
||||
|
||||
## 7. Ephemeral Sticky Notes with TTL
|
||||
- **Tool:** `manage_sticky_notes` (or granular `add_sticky_note`, `read_sticky_notes`, `delete_sticky_note`, `clear_sticky_notes`)
|
||||
- **When to use:** For temporary scratchpad items, temporary ports, task IDs, or transient notes.
|
||||
- **Behavior:** Supports `action: "add" | "read" | "delete" | "clear"`. Supports `ttl_seconds` for auto-expiration and `session_only: true` for automatic purging when the session ends.
|
||||
|
||||
---
|
||||
|
||||
## 8. Snippet Vault & Domain Tagging
|
||||
- **Tools:** `store_snippet`, `search_snippets`, `delete_snippet`, `tag_snippet`
|
||||
- **When to use:** Store exact multi-line code snippets, Nushell pipelines, or frequently used CLI commands.
|
||||
- **Behavior:** `search_snippets` supports `mode: "hybrid" | "keyword" | "semantic"` combining BM25 term frequency keyword matching with semantic tag scoring. Guarantees precise syntactic preservation. Use `tag_snippet` to attach domain tags (e.g., `["rust", "axum", "mcp"]`) for category-filtered searches.
|
||||
|
||||
---
|
||||
|
||||
## 9. Context & Subagent Namespaces
|
||||
- **Tools:** `manage_subagent_namespace` (unifying `create_subagent_namespace`, `condense_subagent_namespace`, `purge_subagent_namespace`)
|
||||
- **When to use:** Isolate graph queries, tasks, and tech debt to specific project or subagent scopes.
|
||||
- **Behavior:** `manage_subagent_namespace` manages subagent memory lifecycles (`action: "create" | "condense" | "purge"`). Condensing auto-promotes subagent entities/relations to the global Knowledge Graph.
|
||||
|
||||
---
|
||||
|
||||
## 10. Architectural Decision Records (ADRs)
|
||||
- **Tools:** `log_decision`, `query_decisions`, `delete_decision`
|
||||
- **When to use:** Whenever making a non-trivial architectural, environmental, or design decision.
|
||||
- **Behavior:** Permanently stores context, decision, and consequences to prevent future agents from second-guessing choices.
|
||||
|
||||
---
|
||||
|
||||
## 11. Graph Refactoring & Algorithms
|
||||
- **Tools:** `merge_entities`, `find_orphans`, `query_graph_path`, `condense_entity`
|
||||
- **When to use:** Run `find_orphans` periodically to clean unused nodes. Use `merge_entities` to combine duplicate concepts. Use `query_graph_path` to find shortest relational connections between components. Use `condense_entity` when entity observation counts grow large.
|
||||
|
||||
---
|
||||
|
||||
## 12. Dynamic Learned Preferences
|
||||
- **Tools:** `learn_preference`, `read_preferences`
|
||||
- **When to use:** When the user specifies personal or repository-specific preferences.
|
||||
- **Behavior:** Stores key-value behavioral preferences that persist across agent invocations.
|
||||
|
||||
---
|
||||
|
||||
## 13. Pinned Workspaces & Hot Files
|
||||
- **Tools:** `pin_file`, `unpin_file`, `list_pinned_files`
|
||||
- **When to use:** Pin 3–5 active working set files to maintain focus in large codebases.
|
||||
|
||||
---
|
||||
|
||||
## 14. Agent Handoffs & Memos
|
||||
- **Tools:** `leave_handoff_memo`, `read_handoff_memos`, `clear_handoff_memos`
|
||||
- **When to use:** Leave messages for future agent sessions or inspect pending handoff notes upon waking.
|
||||
|
||||
---
|
||||
|
||||
## 15. Real-time WebSocket Memory Sync
|
||||
- **Endpoint:** `ws://127.0.0.1:3000/ws`
|
||||
- **Behavior:** Broadcasts live state updates and activity notifications to the Brain Monitor UI in real time.
|
||||
|
||||
---
|
||||
|
||||
## 16. Self-Healing Graph Health Sweeper
|
||||
## 6. Self-Healing Graph Health Sweeper
|
||||
- **Tool:** `sweep_graph_health`
|
||||
- **When to use:** Periodically or before committing major graph changes to audit entity consistency.
|
||||
- **Behavior:** Detects orphaned nodes (0 relations), computes name similarity to identify near-duplicates (e.g., `APIGateway` vs `ApiGateway`), and provides structured `merge_entities` recommendations or auto-prunes orphans.
|
||||
|
||||
---
|
||||
|
||||
## 17. Causal Lineage & Provenance Tracker
|
||||
## 7. Causal Lineage & Provenance Tracker
|
||||
- **Tool:** `query_lineage`
|
||||
- **When to use:** When asking *"Why was this component modified?"* or *"What task or ADR led to this code change?"*
|
||||
- **Behavior:** Searches across tasks, ADRs, audit ledger entries, and error fixes to assemble a unified chronological timeline explaining the provenance behind any file, symbol, or commit.
|
||||
|
||||
---
|
||||
|
||||
## 18. Topological Unblocked Task Resolver
|
||||
- **Tool:** `get_next_actionable_tasks`
|
||||
- **When to use:** When orchestrating subagent execution or selecting the next task to work on.
|
||||
- **Behavior:** Evaluates task dependency DAGs and filters out any blocked tasks, returning only unblocked, actionable tasks ready for immediate execution.
|
||||
|
||||
---
|
||||
|
||||
## 19. Chain-of-Thought & Diagnostic Hypothesis Memory
|
||||
- **Tools:** `log_hypothesis`, `query_hypotheses`
|
||||
- **When to use:** During complex debugging or root cause analysis.
|
||||
- **Behavior:** Records hypotheses alongside tested evidence and status (`unverified`, `verified`, `rejected`). Allows subagents to query past diagnostic paths and avoid re-testing disproven hypotheses.
|
||||
|
||||
---
|
||||
|
||||
## 20. Workspace Context Diffing
|
||||
- **Tool:** `diff_context_workspaces`
|
||||
- **When to use:** When switching branches or comparing two saved context workspaces.
|
||||
- **Behavior:** Returns a structured delta highlighting added, removed, and shared pinned files and active task IDs between two context workspaces.
|
||||
|
||||
---
|
||||
|
||||
## 21. Universal Token Guardrails
|
||||
- **Behavior:** Automatically caps large MCP resource reads (e.g. `memory://graph/entities`) and list responses, adding summary headers (`"_meta": "Showing 100 of N items"`) to guarantee output stays within context window limits.
|
||||
|
||||
---
|
||||
|
||||
## 22. LLM Pre-Flight Context Bundle
|
||||
## 8. LLM Pre-Flight Context Bundle
|
||||
- **Tool:** `get_preflight_context`
|
||||
- **When to use:** At the start of a turn or subagent task to gain total situational awareness in 1 call.
|
||||
- **Behavior:** Aggregates current active branch, in-progress tasks with acceptance criteria, pinned files, top open tech debts, and active unverified hypotheses into a consolidated executive context bundle.
|
||||
|
||||
---
|
||||
|
||||
## 23. Self-Healing Symbol & Line Range Resolver
|
||||
- **Tool:** `resolve_stale_symbols`
|
||||
- **When to use:** When files have been deleted, moved, or heavily refactored.
|
||||
- **Behavior:** Verifies graph entities and tech debt symbol references against disk and AST, flagging and auto-healing stale pointers or broken file paths.
|
||||
|
||||
---
|
||||
|
||||
## 24. Inter-Agent Signal Bus
|
||||
- **Tools:** `broadcast_agent_signal`, `query_agent_signals`
|
||||
- **When to use:** For real-time coordination and event-driven communication between concurrent subagents (e.g., `PrePushAuditor` signaling `AUDIT_PASSED` to parent agent).
|
||||
- **Behavior:** Ephemeral TTL-backed signal bus storing structured agent events, payloads, and artifact URIs.
|
||||
|
||||
---
|
||||
|
||||
## 25. Automated Session Checkpoint on Shutdown
|
||||
- **Tool:** `auto_session_checkpoint`
|
||||
- **When to use:** Executed automatically on `/shutdown` or manually when pausing a session.
|
||||
- **Behavior:** Captures active tasks, unverified hypotheses, recent commit ledgers, and workspace state into a permanent `HandoffMemo` for seamless turn-taking and recovery.
|
||||
Reference in new issue
Block a user