riz/mcp-memory
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update human and LLM docs and enhance tool/list schemas with actionable next steps

Browse Source
This commit is contained in:
Riz Ashraf committed 2026-10-05 11:22:55 +01:00
1 parent 961abb01e7
commit 4b307b55b9
12 files changed
+307 -336
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

server/src/handlers/env.rs
+2 -2
View File
@@ -190,7 +190,7 @@ impl McpTool for EnvironmentHandler {
}
EnvAction::LogRequirement => {
let key = req.key.ok_or_else(|| {
crate::error::AppError::Internal("key is required for 'log_requirement' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'key' for action 'log_requirement'. Next step: Provide environment variable 'key' string in request and retry.".to_string())
})?;
let desc = req.description.unwrap_or_default();
let secret = req.is_secret.unwrap_or(false);
@@ -198,7 +198,7 @@ impl McpTool for EnvironmentHandler {
}
EnvAction::Register => {
let name = req.name.ok_or_else(|| {
crate::error::AppError::Internal("name is required for 'register' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'name' for action 'register'. Next step: Provide environment 'name' string in request and retry.".to_string())
})?;
let url = req.url.unwrap_or_default();
let desc = req.description.unwrap_or_default();
server/src/handlers/meta.rs
+4 -4
View File
@@ -545,7 +545,7 @@ impl McpTool for DecisionsHandler {
match req.action {
DecisionAction::Log => {
let title = req.title.ok_or_else(|| {
crate::error::AppError::Internal("title is required for 'log' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'title' for action 'log'. Next step: Provide ADR 'title' string in request and retry.".to_string())
})?;
let status = req.status.unwrap_or_else(|| "accepted".to_string());
let context = req.context.unwrap_or_default();
@@ -568,7 +568,7 @@ impl McpTool for DecisionsHandler {
}
DecisionAction::Delete => {
let id = req.id.ok_or_else(|| {
crate::error::AppError::Internal("id is required for 'delete' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'id' for action 'delete'. Next step: Provide ADR 'id' string in request and retry.".to_string())
})?;
DeleteDecisionHandler.execute(serde_json::json!({"id": id}), state).await
}
@@ -597,7 +597,7 @@ impl McpTool for TechDebtHandler {
match req.action {
TechDebtAction::Log => {
let desc = req.description.ok_or_else(|| {
crate::error::AppError::Internal("description is required for 'log' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'description' for action 'log'. Next step: Provide tech debt 'description' in request and retry.".to_string())
})?;
let ideal = req.ideal_solution.unwrap_or_default();
LogTechDebtHandler.execute(
@@ -615,7 +615,7 @@ impl McpTool for TechDebtHandler {
}
TechDebtAction::Resolve => {
let id = req.id.ok_or_else(|| {
crate::error::AppError::Internal("id is required for 'resolve' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'id' for action 'resolve'. Next step: Provide tech debt 'id' string in request and retry.".to_string())
})?;
ResolveTechDebtHandler.execute(serde_json::json!({"id": id}), state).await
}
server/src/handlers/notes.rs
+4 -4
View File
@@ -27,7 +27,7 @@ impl McpTool for StickyNotesHandler {
match req.action {
StickyNoteAction::Add => {
let content = req.content.ok_or_else(|| {
crate::error::AppError::Internal("content is required for 'add' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'content' for action 'add'. Next step: Provide non-empty 'content' string in request and retry.".to_string())
})?;
let now = crate::handlers::utils::now_secs();
let expires_at = if let Some(ttl) = req.ttl_seconds {
@@ -64,7 +64,7 @@ impl McpTool for StickyNotesHandler {
}
StickyNoteAction::Delete => {
let idx = req.index.ok_or_else(|| {
crate::error::AppError::Internal("index is required for 'delete' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'index' for action 'delete'. Next step: Provide 1-based sticky note 'index' integer in request and retry.".to_string())
})?;
let mut success = false;
state.code.sticky.modify(|notes| {
@@ -77,7 +77,7 @@ impl McpTool for StickyNotesHandler {
Ok("Sticky note deleted.".to_string())
} else {
Err(crate::error::AppError::Internal(
"Invalid sticky note index.".to_string(),
"Invalid sticky note index. Next step: Call sticky_notes with action='read' to view active notes and valid 1-based indices, then retry.".to_string(),
))
}
}
@@ -236,7 +236,7 @@ impl McpTool for HandoffMemosHandler {
match req.action {
HandoffMemoAction::Leave => {
let content = req.content.ok_or_else(|| {
crate::error::AppError::Internal("content is required for 'leave' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'content' for action 'leave'. Next step: Provide non-empty 'content' string in request and retry.".to_string())
})?;
let ns = req.namespace.unwrap_or_else(|| crate::models::default_namespace());
state.telemetry.handoff_memos.modify(|memos| {
server/src/handlers/tasks.rs
+10 -10
View File
@@ -532,7 +532,7 @@ impl McpTool for TasksHandler {
match req.action {
TaskAction::Add => {
let title = req.title.ok_or_else(|| {
crate::error::AppError::Internal("title is required for 'add' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'title' for action 'add'. Next step: Provide non-empty 'title' string in request and retry.".to_string())
})?;
let description = req.description.unwrap_or_default();
let add_args = serde_json::json!({
@@ -546,10 +546,10 @@ impl McpTool for TasksHandler {
}
TaskAction::Update => {
let id = req.id.ok_or_else(|| {
crate::error::AppError::Internal("id is required for 'update' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'id' for action 'update'. Next step: Provide task 'id' string in request and retry.".to_string())
})?;
let status = req.status.ok_or_else(|| {
crate::error::AppError::Internal("status is required for 'update' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'status' for action 'update'. Next step: Provide valid 'status' ('pending', 'completed', or 'cancelled') in request and retry.".to_string())
})?;
let update_args = serde_json::json!({
"id": id,
@@ -559,7 +559,7 @@ impl McpTool for TasksHandler {
}
TaskAction::Delete => {
let id = req.id.ok_or_else(|| {
crate::error::AppError::Internal("id is required for 'delete' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'id' for action 'delete'. Next step: Provide task 'id' string in request and retry.".to_string())
})?;
let del_args = serde_json::json!({
"id": id,
@@ -576,10 +576,10 @@ impl McpTool for TasksHandler {
}
TaskAction::SetCriteria => {
let id = req.id.ok_or_else(|| {
crate::error::AppError::Internal("id is required for 'set_criteria' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'id' for action 'set_criteria'. Next step: Provide task 'id' string in request and retry.".to_string())
})?;
let criteria = req.criteria.ok_or_else(|| {
crate::error::AppError::Internal("criteria array is required for 'set_criteria' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'criteria' for action 'set_criteria'. Next step: Provide array of acceptance criteria descriptions in request and retry.".to_string())
})?;
let set_args = serde_json::json!({
"id": id,
@@ -589,7 +589,7 @@ impl McpTool for TasksHandler {
}
TaskAction::Verify => {
let id = req.id.ok_or_else(|| {
crate::error::AppError::Internal("id is required for 'verify' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'id' for action 'verify'. Next step: Provide task 'id' string in request and retry.".to_string())
})?;
let verify_args = serde_json::json!({
"id": id,
@@ -620,7 +620,7 @@ impl McpTool for MilestonesHandler {
match req.action {
MilestoneAction::Add => {
let title = req.title.ok_or_else(|| {
crate::error::AppError::Internal("title is required for 'add' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'title' for action 'add'. Next step: Provide non-empty 'title' string in request and retry.".to_string())
})?;
let add_args = serde_json::json!({
"title": title,
@@ -630,10 +630,10 @@ impl McpTool for MilestonesHandler {
}
MilestoneAction::Update => {
let id = req.id.ok_or_else(|| {
crate::error::AppError::Internal("id is required for 'update' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'id' for action 'update'. Next step: Provide milestone 'id' string in request and retry.".to_string())
})?;
let status = req.status.ok_or_else(|| {
crate::error::AppError::Internal("status is required for 'update' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'status' for action 'update'. Next step: Provide milestone 'status' in request and retry.".to_string())
})?;
let update_args = serde_json::json!({
"id": id,
server/src/handlers/workspaces.rs
+11 -11
View File
@@ -496,13 +496,13 @@ impl McpTool for PinnedFilesHandler {
match req.action {
PinnedFileAction::Pin => {
let path = req.path.ok_or_else(|| {
crate::error::AppError::Internal("path is required for 'pin' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'path' for action 'pin'. Next step: Provide absolute or relative file 'path' in request and retry.".to_string())
})?;
PinFileHandler.execute(serde_json::json!({"file_path": path, "namespace": ns}), state).await
}
PinnedFileAction::Unpin => {
let path = req.path.ok_or_else(|| {
crate::error::AppError::Internal("path is required for 'unpin' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'path' for action 'unpin'. Next step: Provide file 'path' in request and retry.".to_string())
})?;
UnpinFileHandler.execute(serde_json::json!({"file_path": path, "namespace": ns}), state).await
}
@@ -534,7 +534,7 @@ impl McpTool for ContextWorkspacesHandler {
match req.action {
ContextWorkspaceAction::Save => {
let name = req.name.ok_or_else(|| {
crate::error::AppError::Internal("name is required for 'save' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'name' for action 'save'. Next step: Provide workspace 'name' string in request and retry.".to_string())
})?;
let pinned_files = req.pinned_files.unwrap_or_default();
let active_task_ids = req.active_task_ids.unwrap_or_default();
@@ -550,7 +550,7 @@ impl McpTool for ContextWorkspacesHandler {
}
ContextWorkspaceAction::Load => {
let name = req.name.ok_or_else(|| {
crate::error::AppError::Internal("name is required for 'load' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'name' for action 'load'. Next step: Provide workspace 'name' string in request and retry.".to_string())
})?;
LoadContextWorkspaceHandler.execute(serde_json::json!({"name": name, "namespace": ns}), state).await
}
@@ -559,16 +559,16 @@ impl McpTool for ContextWorkspacesHandler {
}
ContextWorkspaceAction::Delete => {
let name = req.name.ok_or_else(|| {
crate::error::AppError::Internal("name is required for 'delete' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'name' for action 'delete'. Next step: Provide workspace 'name' string in request and retry.".to_string())
})?;
DeleteContextWorkspaceHandler.execute(serde_json::json!({"name": name, "namespace": ns}), state).await
}
ContextWorkspaceAction::Diff => {
let name = req.name.ok_or_else(|| {
crate::error::AppError::Internal("name is required for 'diff' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'name' for action 'diff'. Next step: Provide primary workspace 'name' in request and retry.".to_string())
})?;
let other = req.other_name.ok_or_else(|| {
crate::error::AppError::Internal("other_name is required for 'diff' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'other_name' for action 'diff'. Next step: Provide secondary workspace 'other_name' in request and retry.".to_string())
})?;
DiffContextWorkspacesHandler.execute(serde_json::json!({"workspace_a": name, "workspace_b": other, "namespace": ns}), state).await
}
@@ -597,7 +597,7 @@ impl McpTool for PrChecklistHandler {
match req.action {
PrChecklistAction::Add => {
let desc = req.description.ok_or_else(|| {
crate::error::AppError::Internal("description is required for 'add' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'description' for action 'add'. Next step: Provide checklist item 'description' string in request and retry.".to_string())
})?;
AddPrChecklistItemHandler.execute(serde_json::json!({"description": desc, "namespace": ns}), state).await
}
@@ -631,7 +631,7 @@ impl McpTool for SnippetsHandler {
match req.action {
SnippetAction::Store => {
let name = req.query.or(req.id).ok_or_else(|| {
crate::error::AppError::Internal("name is required for 'store' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'query' or 'id' as snippet name for action 'store'. Next step: Provide snippet name in 'query' field and retry.".to_string())
})?;
let lang = req.language.unwrap_or_else(|| "text".to_string());
let code = req.code.unwrap_or_default();
@@ -657,13 +657,13 @@ impl McpTool for SnippetsHandler {
}
SnippetAction::Delete => {
let id = req.id.or(req.query).ok_or_else(|| {
crate::error::AppError::Internal("id/name is required for 'delete' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'id' or 'query' for action 'delete'. Next step: Provide snippet ID/name in request and retry.".to_string())
})?;
DeleteSnippetHandler.execute(serde_json::json!({"name": id}), state).await
}
SnippetAction::Tag => {
let id = req.id.or(req.query).ok_or_else(|| {
crate::error::AppError::Internal("id/name is required for 'tag' action".to_string())
crate::error::AppError::Internal("Missing required parameter 'id' or 'query' for action 'tag'. Next step: Provide snippet ID/name and 'tags' array in request and retry.".to_string())
})?;
let tags = req.tags.unwrap_or_default();
TagSnippetHandler.execute(serde_json::json!({"name": id, "tags": tags}), state).await
server/src/instructions.md
+76 -127
View File
@@ -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.
server/src/models.rs
-1
View File
@@ -311,7 +311,6 @@ pub struct AgentSignal {
#[cfg(test)]
mod tests {
use super::*;
use axum::http::StatusCode;
use axum::response::IntoResponse;
use crate::error::AppError;
server/src/tools.rs
+94 -25
View File
@@ -140,7 +140,13 @@ pub enum StickyNoteAction {
Clear,
}
/// Ephemeral sticky notes with TTL (add, read, delete, clear).
/// Ephemeral sticky notes with TTL for scratchpad items, ports, and transient notes.
/// Actions:
/// - 'add': Add note. Required: content. Optional: ttl_seconds, session_only.
/// - 'read': Read all active notes.
/// - 'delete': Delete note. Required: index (1-based integer).
/// - 'clear': Clear all active notes.
/// Next steps on error: Ensure required fields for the specific action are supplied.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct StickyNotesTool {
/// Action to perform: 'add', 'read', 'delete', or 'clear'.
@@ -1093,7 +1099,12 @@ pub enum HandoffMemoAction {
Clear,
}
/// Manage handoff memos across sessions (leave, read, clear).
/// Persistent handoff memos for passing session context to future agents.
/// Actions:
/// - 'leave': Post a handoff memo. Required: content. Optional: namespace.
/// - 'read': Inspect active memos. Optional: namespace.
/// - 'clear': Clear memos. Optional: namespace, ids.
/// Next steps on error: Check parameter requirements for 'leave' or 'clear' actions.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct HandoffMemosTool {
/// Action to perform: 'leave', 'read', or 'clear'.
@@ -1117,7 +1128,15 @@ pub enum TaskAction {
Verify,
}
/// Consolidated task management (add, update, delete, list, set_criteria, verify).
/// Action-oriented task tracking system (add, update, delete, list, set_criteria, verify).
/// Actions:
/// - 'add': Create task. Required: title. Optional: description, git_branch, parent_id, dependencies.
/// - 'update': Update task status. Required: id, status ('pending'|'completed'|'cancelled').
/// - 'delete': Delete task & subtasks. Required: id.
/// - 'list': List active tasks. Optional: git_branch, summary_level ('compact'|'detailed'|'full'), max_tokens.
/// - 'set_criteria': Set acceptance criteria. Required: id, criteria (array of strings).
/// - 'verify': Verify criteria met. Required: id.
/// Next steps on error: Check required parameters or call list to verify task IDs.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct TasksTool {
/// Action to perform: 'add', 'update', 'delete', 'list', 'set_criteria', or 'verify'.
@@ -1126,7 +1145,7 @@ pub struct TasksTool {
pub id: Option<String>,
/// Task title (required for 'add').
pub title: Option<String>,
/// Task description (required for 'add').
/// Task description (optional for 'add').
pub description: Option<String>,
/// New status: 'pending', 'completed', or 'cancelled' (for 'update').
pub status: Option<String>,
@@ -1152,7 +1171,12 @@ pub enum MilestoneAction {
List,
}
/// Consolidated milestone management (add, update, list).
/// Project milestone management (add, update, list).
/// Actions:
/// - 'add': Create milestone. Required: title. Optional: namespace.
/// - 'update': Update milestone status. Required: id, status.
/// - 'list': List milestones. Optional: namespace.
/// Next steps on error: Provide required title for 'add' or id/status for 'update'.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct MilestonesTool {
/// Action to perform: 'add', 'update', or 'list'.
@@ -1175,7 +1199,12 @@ pub enum PinnedFileAction {
List,
}
/// Consolidated pinned files focus management (pin, unpin, list).
/// Pinned working set files management (pin, unpin, list).
/// Actions:
/// - 'pin': Pin file to active focus set. Required: path. Optional: namespace.
/// - 'unpin': Unpin file from focus set. Required: path. Optional: namespace.
/// - 'list': List pinned files. Optional: namespace.
/// Next steps on error: Provide exact file path for pin/unpin operations.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct PinnedFilesTool {
/// Action to perform: 'pin', 'unpin', or 'list'.
@@ -1196,14 +1225,21 @@ pub enum ContextWorkspaceAction {
Diff,
}
/// Consolidated context workspace state management (save, load, list, delete, diff).
/// Context workspace snapshots management (save, load, list, delete, diff).
/// Actions:
/// - 'save': Save current pinned files & task IDs. Required: name. Optional: pinned_files, active_task_ids, namespace.
/// - 'load': Restore saved workspace state. Required: name. Optional: namespace.
/// - 'list': List saved context workspaces. Optional: namespace.
/// - 'delete': Delete saved workspace. Required: name. Optional: namespace.
/// - 'diff': Compare two context workspaces. Required: name, other_name. Optional: namespace.
/// Next steps on error: Check workspace name or list existing workspaces first.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ContextWorkspacesTool {
/// Action to perform: 'save', 'load', 'list', 'delete', or 'diff'.
pub action: ContextWorkspaceAction,
/// Workspace name.
/// Workspace name (required for 'save', 'load', 'delete', 'diff').
pub name: Option<String>,
/// Second workspace name (for 'diff').
/// Second workspace name (required for 'diff').
pub other_name: Option<String>,
/// Pinned file paths (for 'save').
pub pinned_files: Option<Vec<String>>,
@@ -1221,7 +1257,12 @@ pub enum PrChecklistAction {
Clear,
}
/// Consolidated PR checklist management (add, get, clear).
/// Pre-commit and Pull Request checklist management (add, get, clear).
/// Actions:
/// - 'add': Add PR checklist item. Required: description. Optional: namespace.
/// - 'get': Get PR checklist items. Optional: namespace.
/// - 'clear': Clear PR checklist. Optional: namespace.
/// Next steps on error: Provide description for 'add' action.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct PrChecklistTool {
/// Action to perform: 'add', 'get', or 'clear'.
@@ -1241,14 +1282,20 @@ pub enum SnippetAction {
Tag,
}
/// Consolidated reusable code snippets management (store, search, delete, tag).
/// Syntactically preserved reusable code snippets vault (store, search, delete, tag).
/// Actions:
/// - 'store': Store snippet. Required: query (or id) as snippet name. Optional: language, code, description, tags.
/// - 'search': Search snippets. Optional: query, tags, hybrid (boolean for BM25+vector search).
/// - 'delete': Delete snippet. Required: id (or query) as snippet name.
/// - 'tag': Tag snippet. Required: id (or query), tags (array of strings).
/// Next steps on error: Ensure snippet name/query or id is provided.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct SnippetsTool {
/// Action to perform: 'store', 'search', 'delete', or 'tag'.
pub action: SnippetAction,
/// Snippet ID (required for 'delete', 'tag').
/// Snippet ID or name (required for 'delete', 'tag').
pub id: Option<String>,
/// Search query or snippet name.
/// Search query or snippet name (required for 'store').
pub query: Option<String>,
/// Snippet language (for 'store').
pub language: Option<String>,
@@ -1270,7 +1317,12 @@ pub enum DecisionAction {
Delete,
}
/// Consolidated Architectural Decision Records (ADRs) management (log, query, delete).
/// Architectural Decision Records (ADRs) log (log, query, delete).
/// Actions:
/// - 'log': Record ADR. Required: title. Optional: status, context, decision, consequences, namespace.
/// - 'query': Search ADRs. Optional: query, namespace.
/// - 'delete': Remove ADR. Required: id.
/// Next steps on error: Provide title for 'log' or id for 'delete'.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct DecisionsTool {
/// Action to perform: 'log', 'query', or 'delete'.
@@ -1279,13 +1331,13 @@ pub struct DecisionsTool {
pub id: Option<String>,
/// ADR title (required for 'log').
pub title: Option<String>,
/// ADR status (required for 'log').
/// ADR status (for 'log').
pub status: Option<String>,
/// Context & problem statement (required for 'log').
/// Context & problem statement (for 'log').
pub context: Option<String>,
/// Decision made (required for 'log').
/// Decision made (for 'log').
pub decision: Option<String>,
/// Consequences & tradeoffs (required for 'log').
/// Consequences & tradeoffs (for 'log').
pub consequences: Option<String>,
/// Search query string (for 'query').
pub query: Option<String>,
@@ -1301,7 +1353,12 @@ pub enum TechDebtAction {
List,
}
/// Consolidated technical debt management (log, resolve, list).
/// Technical debt backlog management (log, resolve, list).
/// Actions:
/// - 'log': Record technical debt. Required: description. Optional: ideal_solution, git_commit, git_branch, symbol_references, line_range, namespace.
/// - 'resolve': Mark tech debt resolved. Required: id.
/// - 'list': List tech debt items. Optional: include_resolved, namespace.
/// Next steps on error: Provide description for 'log' or valid ID for 'resolve'.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct TechDebtTool {
/// Action to perform: 'log', 'resolve', or 'list'.
@@ -1310,7 +1367,7 @@ pub struct TechDebtTool {
pub id: Option<String>,
/// Tech debt description (required for 'log').
pub description: Option<String>,
/// Ideal solution (required for 'log').
/// Ideal solution (optional for 'log').
pub ideal_solution: Option<String>,
/// Include resolved tech debt items (for 'list').
pub include_resolved: Option<bool>,
@@ -1336,20 +1393,27 @@ pub enum EnvAction {
GetDetails,
}
/// Consolidated environment & infrastructure management (update_fingerprint, read_fingerprint, log_requirement, register, get_details).
/// Environment requirements, tool fingerprints & infrastructure management.
/// Actions:
/// - 'update_fingerprint': Update tool versions. Optional: tool_versions map, namespace.
/// - 'read_fingerprint': Read current environment fingerprint. Optional: namespace.
/// - 'log_requirement': Log environment variable requirement. Required: key. Optional: description, is_secret, namespace.
/// - 'register': Register remote target environment. Required: name. Optional: url, description, requires_vpn, namespace.
/// - 'get_details': Get full environment details. Optional: namespace.
/// Next steps on error: Provide key for 'log_requirement' or name for 'register'.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct EnvironmentTool {
/// Action to perform.
/// Action to perform: 'update_fingerprint', 'read_fingerprint', 'log_requirement', 'register', or 'get_details'.
pub action: EnvAction,
/// Map of tool names to versions (for 'update_fingerprint').
pub tool_versions: Option<std::collections::HashMap<String, String>>,
/// Env variable key (for 'log_requirement').
/// Env variable key (required for 'log_requirement').
pub key: Option<String>,
/// Description (for 'log_requirement', 'register').
pub description: Option<String>,
/// Secret flag (for 'log_requirement').
pub is_secret: Option<bool>,
/// Environment name (for 'register').
/// Environment name (required for 'register').
pub name: Option<String>,
/// Environment URL (for 'register').
pub url: Option<String>,
@@ -1367,7 +1431,12 @@ pub enum ClipboardAction {
ToggleWatch,
}
/// Consolidated OS clipboard management (read, write, toggle_watch).
/// OS Clipboard management (read, write, toggle_watch).
/// Actions:
/// - 'read': Read current clipboard contents.
/// - 'write': Write content to OS clipboard. Optional: text, html, files, image_path.
/// - 'toggle_watch': Enable or disable auto-clipboard ingestion. Optional: enabled (bool).
/// Next steps on error: Provide text/html/files/image_path when calling 'write'.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ClipboardTool {
/// Action to perform: 'read', 'write', or 'toggle_watch'.