Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(mcp): cross-project recall — global search + broaden-on-miss guidance (#56)
Djalma Júnior9808a01d3a75
diff --git a/crates/ai-memory-core/src/routing_snippet.rs b/crates/ai-memory-core/src/routing_snippet.rsindex 0be0cc14..517b4104 100644--- a/crates/ai-memory-core/src/routing_snippet.rs+++ b/crates/ai-memory-core/src/routing_snippet.rs@@ -60,7 +60,7 @@ match the intent to the tool. They do not need to name the tool.| User says / situation | Tool ||---|---|-| "have we discussed X?" / "search memory for Y" / before proposing architecture | `memory_query` |+| "have we discussed X?" / "search memory for Y" / before proposing architecture | `memory_query` (current project; `scopes` for named siblings; `global=true` to search every project) || "what's been going on" / "show recent activity" (light) | `memory_recent` || "is ai-memory healthy?" / "how big is the wiki?" | `memory_status` || "give me the stats" / structured snapshot for the agent to consume | `memory_briefing` |@@ -79,6 +79,22 @@ going on" use case — it returns a prose digest whose verbosityscales automatically to how long it's been since the last activity(< 1 h → one line; > 30 days → full catchup).+### When the current project comes up empty — broaden the search++`memory_query` searches only the **current** project; there is **no+global "search everything" mode**. If a search comes back empty or+thin, the knowledge may live in a **sibling project** — shared `infra`,+`ops`, or a related app. Re-run `memory_query` with explicit `scopes`+naming those projects, e.g. `scopes: [{ "workspace": "default",+"project": "infra" }]`. Don't conclude "we never recorded it" after a+single project misses.++`memory_query` returns **snippets, not full page bodies** — an empty or+short snippet does **not** mean the page is empty (a large page can+match outside the snippet window). To read the whole page, use+`memory_read_page` (by `path`, or pass a `query` to fetch the top hit's+full body).+### When you write a project rule, write it hereIf you're about to write a durable project rule ("always X", "neverdiff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex 9a57dc8b..ea85804a 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -46,7 +46,10 @@ the conversation calls for them:\n\\n\- `memory_query` — when the user references prior work you don't \recognise, or asks 'have we done / discussed X', or you're about \- to propose architecture (always check first).\n\+ to propose architecture (always check first). Defaults to the \+ current project; pass `scopes` to search named sibling projects, \+ or `global=true` to search EVERY project at once when you don't \+ know where the knowledge lives.\n\- `memory_recent` — at session start, or when the user asks 'what's \been going on lately'. Returns the N most-recent pages.\n\- `memory_status` — when the user asks 'is ai-memory healthy' or \@@ -91,6 +94,18 @@ the conversation calls for them:\n\in the right rules file (Claude Code → CLAUDE.md, Codex / \OpenCode / Cursor / Gemini → AGENTS.md).\n\\n\+**When the current project comes up empty, broaden — don't stop.** \+`memory_query` searches only ONE project (the current one); there is \+NO global 'search everything' mode. If a query returns nothing useful, \+the knowledge may live in a SIBLING project — shared `infra`, `ops`, \+or a related app. Re-run `memory_query` with explicit \+`scopes: [{workspace, project}]` naming those projects; don't conclude \+'we never recorded it' after one project misses. Note also that \+`memory_query` returns SNIPPETS, not full page bodies — an empty or \+short snippet does NOT mean the page is empty (a large page can match \+outside the snippet window); to read the whole page use \+`memory_read_page` (by `path`, or a `query` for the top hit's body).\n\+\n\The routing snippet this very text comes from can also be installed \into the project's CLAUDE.md / AGENTS.md so the guidance survives \across sessions. From the agent: ask 'install ai-memory routing'. \@@ -170,6 +185,13 @@ struct QueryArgs {/// knowledge. Cannot be combined with `workspace`/`project`.#[serde(default)]scopes: Vec<MemoryScopeArg>,+ /// Search EVERY project in every workspace in one call (cross-project+ /// global search). Use when you don't know which project holds the+ /// knowledge — e.g. shared infra/ops notes. When true, omit+ /// `project`/`workspace`/`scopes`; each hit is annotated with its+ /// workspace + project so you can tell where it came from.+ #[serde(default)]+ global: Option<bool>,}#[derive(Debug, Serialize, Deserialize, schemars::JsonSchema)]@@ -209,6 +231,10 @@ struct MemoryQueryResponse {hits: Vec<ai_memory_store::PageHit>,#[serde(skip_serializing_if = "Vec::is_empty")]raw_hits: Vec<ai_memory_store::ObservationHit>,+ /// Populated only by a `global=true` query: cross-project hits, each+ /// carrying its workspace + project name.+ #[serde(skip_serializing_if = "Vec::is_empty")]+ global_hits: Vec<ai_memory_store::PageHitWithMeta>,}#[derive(Debug, Serialize)]@@ -668,12 +694,42 @@ impl AiMemoryServer {Returns up to `limit` pages with HTML-marked snippets and a rank \score (lower rank = better match). Only latest page versions. \If compiled wiki search misses, `raw_hits` contains bounded raw \- observation fallback matches.")]+ observation fallback matches. Set `global=true` to search EVERY \+ project at once (cross-project) when you don't know which project \+ holds the knowledge — each hit then carries its workspace + \+ project name.")]async fn memory_query(&self,Parameters(args): Parameters<QueryArgs>,) -> Result<CallToolResult, McpError> {let limit = args.limit.unwrap_or(self.default_limit).clamp(1, 100);+ if args.global.unwrap_or(false) {+ if !args.scopes.is_empty()+ || args+ .workspace+ .as_deref()+ .is_some_and(|s| !s.trim().is_empty())+ || args+ .project+ .as_deref()+ .is_some_and(|s| !s.trim().is_empty())+ {+ return Err(McpError::internal_error(+ "global cannot be combined with workspace/project/scopes",+ None,+ ));+ }+ let global_hits = self+ .reader+ .search_pages_with_meta(args.query.clone(), limit)+ .await+ .map_err(|e| McpError::internal_error(e.to_string(), None))?;+ return ok_json(&MemoryQueryResponse {+ hits: Vec::new(),+ raw_hits: Vec::new(),+ global_hits,+ });+ }if !args.scopes.is_empty()&& (args.workspace@@ -741,7 +797,11 @@ impl AiMemoryServer {} else {Vec::new()};- let response = MemoryQueryResponse { hits, raw_hits };+ let response = MemoryQueryResponse {+ hits,+ raw_hits,+ global_hits: Vec::new(),+ };ok_json(&response)}@@ -1470,6 +1530,28 @@ mod tests {}}+ #[test]+ fn prompts_teach_cross_project_search_strategy() {+ // Regression: a single-project miss must not read as "never recorded".+ // Both surfaces must point the agent at `scopes` and warn that query+ // returns snippets, not full page bodies. (Learned the hard way when+ // cluster-access info lived in a sibling `infra` project.)+ for prompt in [MEMORY_INSTRUCTIONS, ai_memory_core::SNIPPET_BODY] {+ assert!(+ prompt.contains("scopes"),+ "prompt must teach broadening the search via `scopes`"+ );+ assert!(+ prompt.contains("sibling") || prompt.contains("SIBLING"),+ "prompt must mention knowledge can live in a sibling project"+ );+ assert!(+ prompt.contains("snippet"),+ "prompt must warn that query returns snippets, not full bodies"+ );+ }+ }+#[test]fn prompts_route_permanent_annotations_to_write_page_not_handoff() {for prompt in [MEMORY_INSTRUCTIONS, ai_memory_core::SNIPPET_BODY] {@@ -1538,6 +1620,7 @@ mod tests {project: None,scopes: Vec::new(),workspace: None,+ global: None,})).await.unwrap();@@ -1586,6 +1669,7 @@ mod tests {project: None,scopes: Vec::new(),workspace: None,+ global: None,})).await.unwrap();@@ -1640,6 +1724,7 @@ mod tests {project: Some("unit-testing".into()),scopes: Vec::new(),workspace: Some("practice".into()),+ global: None,})).await.unwrap();@@ -1737,6 +1822,7 @@ mod tests {},],workspace: None,+ global: None,})).await.unwrap();@@ -1754,6 +1840,93 @@ mod tests {assert!(!text.contains("hidden.md"), "unexpected hidden hit: {text}");}+ #[tokio::test]+ async fn memory_query_global_searches_all_projects() {+ let (_tmp, store, server, ws, _pj) = setup_server().await;+ let other = store+ .writer+ .get_or_create_project(ws, "infra", None)+ .await+ .unwrap();+ let other_ws = store.writer.get_or_create_workspace("ops").await.unwrap();+ let third = store+ .writer+ .get_or_create_project(other_ws, "runbooks", None)+ .await+ .unwrap();+ for (w, p, path, body) in [+ (ws, other, "cluster.md", "global_token lives in infra"),+ (+ other_ws,+ third,+ "deploy.md",+ "global_token lives in ops runbooks",+ ),+ ] {+ store+ .writer+ .upsert_page(NewPage {+ workspace_id: w,+ project_id: p,+ path: PagePath::new(path).unwrap(),+ title: path.into(),+ body: body.into(),+ tier: Tier::Semantic,+ frontmatter_json: serde_json::json!({}),+ pinned: false,+ links: Vec::new(),+ })+ .await+ .unwrap();+ }++ let result = server+ .memory_query(Parameters(QueryArgs {+ query: "global_token".into(),+ limit: Some(10),+ project: None,+ scopes: Vec::new(),+ workspace: None,+ global: Some(true),+ }))+ .await+ .unwrap();+ let text = result+ .content+ .first()+ .and_then(|c| c.as_text())+ .map(|t| t.text.clone())+ .unwrap();+ // Both projects (across two workspaces) surface in one global call,+ // each annotated with its project name.+ assert!(text.contains("cluster.md"), "expected infra hit: {text}");+ assert!(text.contains("deploy.md"), "expected ops hit: {text}");+ assert!(+ text.contains("infra"),+ "hit must carry project name: {text}"+ );+ assert!(text.contains("global_hits"), "global hits field: {text}");+ }++ #[tokio::test]+ async fn memory_query_global_rejects_explicit_scope() {+ let (_tmp, _store, server, _ws, _pj) = setup_server().await;+ let err = server+ .memory_query(Parameters(QueryArgs {+ query: "x".into(),+ limit: Some(5),+ project: Some("product".into()),+ scopes: Vec::new(),+ workspace: None,+ global: Some(true),+ }))+ .await;+ assert!(+ err.is_err(),+ "global must not combine with project/workspace/scopes"+ );+ }+#[tokio::test]async fn memory_status_returns_counts() {let (_tmp, _store, server, _ws, _pj) = setup_server().await;@@ -2299,6 +2472,7 @@ mod tests {project: None,scopes: Vec::new(),workspace: None,+ global: None,})).await.expect("oversized limit should be clamped, not refused");@@ -2326,6 +2500,7 @@ mod tests {project: None,scopes: Vec::new(),workspace: None,+ global: None,})).await;// Either a tidy 0-hit Ok (FTS5 is occasionally lenient) ordiff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 6964e359..ef2de158 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -207,7 +207,7 @@ invariants below.| Tool | Hint | Purpose ||---|---|---|-| `memory_query` | read-only | FTS5 + graph RRF + optional vector RRF search, with raw fallback. Bumps access counters for page hits. |+| `memory_query` | read-only | FTS5 + graph RRF + optional vector RRF search, with raw fallback. Bumps access counters for page hits. Defaults to the current project; `scopes` searches named sibling projects; `global=true` searches every project at once (each hit annotated with its workspace + project). || `memory_recent` | read-only | Most-recently-updated `is_latest=1` pages. || `memory_read_page` | read-only | Fetch the FULL body of a single wiki page by `path` or by top FTS5 hit for a `query`. Use when an agent needs more than the 24-word snippets from `memory_query`. || `memory_status` | read-only | Counts, paths, version. |