refactor: Enforce agentic API design across mcp-memory handlers

- Replaced unconstrained JSON serialization (serde_json) with dense YAML (serde_yaml) to prevent context window bloat (ADR-0122).
- Replaced 404/empty array dead ends with token-efficient LLM fallback hints in router and meta/graph handlers.
- Ensured graceful error fallbacks instead of hard crashes.

server/src/handlers/graph.rs

@@ -791,7 +791,7 @@ impl McpTool for SearchNodesHandler {
                     }
                 }
             }
-            Ok::<String, crate::error::AppError>(serde_yaml::to_string(&matched_entities)?)
+            if matched_entities.is_empty() { Ok::<String, crate::error::AppError>(format!("No entities found matching query. Try using a different keyword or relaxing the search query.")) } else { Ok::<String, crate::error::AppError>(serde_yaml::to_string(&matched_entities)?) }
         })?;
         Ok(data)
     }
@@ -832,7 +832,7 @@ impl McpTool for OpenNodesHandler {
                     result.entities.insert(name, e);
                 }
             }
-            Ok::<String, crate::error::AppError>(serde_yaml::to_string(&result)?)
+            if result.entities.is_empty() { Ok::<String, crate::error::AppError>(format!("No matching nodes found.")) } else { Ok::<String, crate::error::AppError>(serde_yaml::to_string(&result)?) }
         })?;
         Ok(data)
     }

server/src/handlers/meta.rs

@@ -126,7 +126,7 @@ impl McpTool for SearchErrorFixesHandler {
                     })
                     .collect();
 
-                Ok::<String, crate::error::AppError>(serde_yaml::to_string(&suggestions)?)
+                if suggestions.is_empty() { Ok::<String, crate::error::AppError>("No matching error fixes found. Try relaxing the search query.".to_string()) } else { Ok::<String, crate::error::AppError>(serde_yaml::to_string(&suggestions)?) }
             })?;
             return Ok(data);
         }
@@ -153,7 +153,7 @@ impl McpTool for SearchErrorFixesHandler {
                     }
                 })
                 .collect();
-            Ok::<String, crate::error::AppError>(serde_yaml::to_string(&filtered)?)
+            if filtered.is_empty() { Ok::<String, crate::error::AppError>(format!("No matching results found.")) } else { Ok::<String, crate::error::AppError>(serde_yaml::to_string(&filtered)?) }
         })?;
         Ok(data)
     }
@@ -339,7 +339,7 @@ impl McpTool for QueryRecentChangesHandler {
                     c
                 })
                 .collect();
-            Ok::<String, crate::error::AppError>(serde_yaml::to_string(&filtered)?)
+            if filtered.is_empty() { Ok::<String, crate::error::AppError>(format!("No matching results found.")) } else { Ok::<String, crate::error::AppError>(serde_yaml::to_string(&filtered)?) }
         })?;
         Ok(data)
     }
@@ -552,7 +552,7 @@ impl McpTool for DecisionsHandler {
                         .collect();
 
                     if include_body {
-                        Ok::<String, crate::error::AppError>(serde_yaml::to_string(&filtered)?)
+                        if filtered.is_empty() { Ok::<String, crate::error::AppError>(format!("No matching results found.")) } else { Ok::<String, crate::error::AppError>(serde_yaml::to_string(&filtered)?) }
                     } else {
                         let compact: Vec<_> = filtered
                             .iter()

server/src/router.rs

@@ -65,9 +65,9 @@ impl McpResource for GraphEntitiesResource {
                 "_meta": format!("Showing 100 of {} total entities. Use omni_search or get_subgraph for targeted entity discovery.", data.len()),
                 "entities": truncated
             });
-            Ok(serde_json::to_string_pretty(&res)?)
+            Ok(serde_yaml::to_string(&res)?)
         } else {
-            Ok(serde_json::to_string_pretty(&data)?)
+            Ok(serde_yaml::to_string(&data)?)
         }
     }
 }
@@ -93,9 +93,9 @@ impl McpResource for GraphRelationsResource {
                 "_meta": format!("Showing 200 of {} total relations. Use query_graph_path or get_subgraph for targeted relation discovery.", data.len()),
                 "relations": truncated
             });
-            Ok(serde_json::to_string_pretty(&res)?)
+            Ok(serde_yaml::to_string(&res)?)
         } else {
-            Ok(serde_json::to_string_pretty(&data)?)
+            Ok(serde_yaml::to_string(&data)?)
         }
     }
 }
@@ -120,7 +120,7 @@ impl McpResource for TasksActiveResource {
             .read()
             .unwrap_or_else(|e| e.into_inner());
         let data: Vec<_> = tasks.iter().filter(|t| t.is_active()).collect();
-        Ok(serde_json::to_string_pretty(&data)?)
+        Ok(serde_yaml::to_string(&data)?)
     }
 }
 
@@ -144,7 +144,7 @@ impl McpResource for DecisionsActiveResource {
             .read()
             .unwrap_or_else(|e| e.into_inner());
         let data: Vec<_> = adrs.iter().filter(|a| a.status == "accepted").collect();
-        Ok(serde_json::to_string_pretty(&data)?)
+        Ok(serde_yaml::to_string(&data)?)
     }
 }
 
@@ -168,7 +168,7 @@ impl McpResource for TechDebtActiveResource {
             .read()
             .unwrap_or_else(|e| e.into_inner());
         let data: Vec<_> = debts.iter().filter(|d| !d.is_resolved).collect();
-        Ok(serde_json::to_string_pretty(&data)?)
+        Ok(serde_yaml::to_string(&data)?)
     }
 }
 
@@ -267,7 +267,7 @@ impl McpResource for SessionDeltaResource {
             "timestamp": now,
         });
 
-        Ok(serde_json::to_string_pretty(&delta)?)
+        Ok(serde_yaml::to_string(&delta)?)
     }
 }
 
@@ -360,7 +360,7 @@ impl MemoryHandler {
                     .cache
                     .read()
                     .unwrap_or_else(|e| e.into_inner());
-                Ok(serde_json::to_string_pretty(&*items)?)
+                Ok(serde_yaml::to_string(&*items)?)
             }
         }
         struct RecentActivitiesResource;
@@ -382,7 +382,7 @@ impl MemoryHandler {
                     .cache
                     .read()
                     .unwrap_or_else(|e| e.into_inner());
-                Ok(serde_json::to_string_pretty(&*items)?)
+                Ok(serde_yaml::to_string(&*items)?)
             }
         }
 
@@ -405,7 +405,7 @@ impl MemoryHandler {
                     .cache
                     .read()
                     .unwrap_or_else(|e| e.into_inner());
-                Ok(serde_json::to_string_pretty(&*items)?)
+                Ok(serde_yaml::to_string(&*items)?)
             }
         }
 
@@ -660,7 +660,7 @@ impl MemoryHandler {
                         Err(e) => Some(crate::mcp::error(id, -32603, &e.to_string())),
                     }
                 } else {
-                    Some(crate::mcp::error(id, -32602, "Resource not found"))
+                    Some(crate::mcp::error(id, -32602, "Resource not found. To see available resources, call the list_resources tool or query the 'resources/list' endpoint." ))
                 }
             }