Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs+tests: post-merge audit follow-up for #56/#57/#58/#59
AkitaOnRails7a86e12fefbd
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 7f891bcf..4320f1cc 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,78 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added+- **`memory_query { global: true }` — cross-project global search** that+ reaches every project in every workspace in one call, with each hit+ annotated by its workspace + project so the agent can tell where it+ came from. Use when the agent doesn't know which project holds a+ cross-cutting note (shared infra/ops, a sibling app). Mutually+ exclusive with `scopes`/`project`/`workspace`. Routing snippet ++ `MEMORY_INSTRUCTIONS` now teach both broadening modes (`scopes` for+ named siblings, `global=true` for unknown locations) and explicitly+ warn that `memory_query` returns snippets — use `memory_read_page`+ for full bodies. The prompt-surface contradiction the original PR+ shipped ("there is no global 'search everything' mode" right after+ the bullet advertising `global=true`) was caught in the post-merge+ audit and rewritten; the prompt regression test now refuses any+ variant of that legacy phrasing+ ([#56], thanks @djalmajr).+- **Cross-project wiki links + dependency graph.** Wikilinks gain an+ explicit scope qualifier: `[[project:path.md]]` for a sibling project+ in the same workspace, `[[workspace/project:path.md]]` for another+ workspace. Bare links are unchanged (resolve within the source's own+ project). `links.to_workspace` / `links.to_project` join the primary+ key so the same `to_path` can land in two different projects without+ colliding. `memory_lint` now reports dangling cross-project refs+ (typo'd project vs missing/renamed target page), `memory_briefing`+ exposes `cross_project_dependents` / `cross_project_dependencies`+ per project, and `GET /api/v1/graph` returns the resolved cross-+ project edges for a graph view. Migration V13 rebuilds the `links`+ table preserving existing rows as `(to_workspace=NULL,+ to_project=NULL)` — same "local" semantics as before+ ([#57], thanks @djalmajr).++### Changed+- **FTS5 queries OR-join bare multi-word inputs** instead of the+ pre-existing AND default. A natural-language query like+ `"have we discussed cross project search strategy"` previously+ required every word to co-occur in one page — near-zero recall for+ multi-word queries, which the caller silently mistook for "never+ recorded". OR + BM25 ranking (callers already `ORDER BY rank`) keeps+ the best-matching pages at the top of the list, so the user-visible+ top-N is still AND-ish; OR just adds a relevant tail instead of+ returning nothing. Explicit FTS5 syntax (`OR`/`AND`/`NOT`/`NEAR`,+ quoted phrases, parens) is detected and preserved verbatim so the+ exact-match escape hatch stays available. 5 new unit tests guard the+ preservation contract (post-merge audit). Migration V12 rebuilds the+ FTS tables with `unicode61 remove_diacritics 2` so accent-free+ Portuguese queries (`"descricao da sessao"`) match accented stored+ text (`"descrição da sessão"`); contentless FTS — source rows+ untouched ([#58], thanks @djalmajr).+- **MCP write tools now honour the session's project (and create+ named projects on demand).** Three correctness fixes on+ `memory_write_page` / `memory_lint` / `memory_forget_sweep`:+ - A `memory_write_page { project: "X" }` for a project name that+ doesn't exist used to silently fall through to the session's+ active project (find-only resolution); writes meant for a fresh+ project polluted the current one. A new `write_target_ids`+ helper uses **get-or-create** for an explicit project name, so+ a named write always lands where the agent asked.+ - `memory_lint` + `memory_forget_sweep` previously always targeted+ the server's baked `--project` regardless of the session, so a+ cross-project lint or retention sweep could never reach the+ project the user was actually working in. Both now resolve+ through the same find-only `effective_ids_for_read_args` path+ the read tools use, with the hook-published active project as+ the fallback.+ - Both `lint` / `sweep` and the new `write_page` add explicit+ `workspace` + `project` args (defaulted to current session,+ documented with the v0.5.2 "**Omit unless the user explicitly+ names a *different* project.**" tail). 2 regression tests cover+ "Bug B" (explicit-project write must create + land) and+ "Bug C" (sweep must evaluate the named project, not the baked+ default) ([#59], thanks @djalmajr).+## [0.7.1] - 2026-05-29### Fixeddiff --git a/crates/ai-memory-core/src/routing_snippet.rs b/crates/ai-memory-core/src/routing_snippet.rsindex 517b4104..602bed89 100644--- a/crates/ai-memory-core/src/routing_snippet.rs+++ b/crates/ai-memory-core/src/routing_snippet.rs@@ -81,13 +81,17 @@ scales automatically to how long it's been since the last activity### 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` searches only the **current** project by default. If a+search comes back empty or thin, the knowledge may live in a **sibling+project** — shared `infra`, `ops`, or a related app. Don't conclude+"we never recorded it" after a single project misses; broaden instead:++- **Know which projects to check?** Re-run with explicit `scopes`, e.g.+ `scopes: [{ "workspace": "default", "project": "infra" }]`.+- **Don't know where it lives?** Pass `global=true` to search every+ project in every workspace at once. Each hit is annotated with its+ workspace + project so you can tell where it came from. `global=true`+ cannot be combined with `scopes`/`project`/`workspace`.`memory_query` returns **snippets, not full page bodies** — an empty orshort snippet does **not** mean the page is empty (a large page candiff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex ea85804a..36272e16 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -95,16 +95,20 @@ the conversation calls for them:\n\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\+`memory_query` searches only ONE project (the current one) by default. \+If a query returns nothing useful, the knowledge may live in a SIBLING \+project — shared `infra`, `ops`, or a related app. Two ways to \+broaden: (a) re-run with explicit `scopes: [{workspace, project}]` \+when you know which projects to check; (b) pass `global=true` to \+search EVERY project in EVERY workspace at once when you don't know \+where the knowledge lives — each hit then carries its workspace + \+project name. `global=true` cannot be combined with \+`scopes`/`project`/`workspace`. 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 \@@ -1533,22 +1537,44 @@ 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.)+ // Both surfaces must point the agent at `scopes` **and** at+ // `global=true` (the two broadening modes), warn that query returns+ // snippets (not full page bodies), and NOT contain the contradictory+ // legacy "no global mode" phrasing that briefly shipped in #56.+ // (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`"+ "prompt must teach broadening via `scopes`"+ );+ assert!(+ prompt.contains("global=true") || prompt.contains("global = true"),+ "prompt must also teach broadening via `global=true`");assert!(prompt.contains("sibling") || prompt.contains("SIBLING"),"prompt must mention knowledge can live in a sibling project");assert!(- prompt.contains("snippet"),+ prompt.contains("snippet") || prompt.contains("SNIPPET"),"prompt must warn that query returns snippets, not full bodies");+ // Guard against the contradiction: standalone prose must not say+ // a global mode doesn't exist when the bullet/table-row above it+ // advertises `global=true`.+ let no_global_phrases = [+ "no global \"search everything\" mode",+ "NO global 'search everything' mode",+ "no global 'search everything' mode",+ "NO global \"search everything\" mode",+ ];+ for phrase in no_global_phrases {+ assert!(+ !prompt.contains(phrase),+ "prompt must not contain the contradictory phrase {phrase:?}"+ );+ }}}diff --git a/crates/ai-memory-store/src/fts_query.rs b/crates/ai-memory-store/src/fts_query.rsindex 2f3f349b..5c843990 100644--- a/crates/ai-memory-store/src/fts_query.rs+++ b/crates/ai-memory-store/src/fts_query.rs@@ -121,6 +121,55 @@ mod tests {assert_eq!(prepare_fts5_query("quick OR slow"), "quick OR slow");}+ /// AND is the FTS5 default but operators can be explicit — when the+ /// caller writes one, the OR-join must NOT mangle it into+ /// `foo OR AND OR bar`. Same for NOT and NEAR. (The escape hatch from+ /// the broad-recall default is what makes the OR-join safe to land.)+ #[test]+ fn explicit_and_operator_is_preserved() {+ assert_eq!(prepare_fts5_query("foo AND bar"), "foo AND bar");+ }++ #[test]+ fn explicit_not_operator_is_preserved() {+ assert_eq!(prepare_fts5_query("foo NOT bar"), "foo NOT bar");+ }++ #[test]+ fn explicit_near_operator_is_preserved() {+ assert_eq!(prepare_fts5_query("foo NEAR bar"), "foo NEAR bar");+ }++ /// A query containing a quoted phrase is treated as explicit FTS5+ /// syntax — `"exact phrase" baz` must not become+ /// `"exact" OR "phrase" OR baz` (which destroys the phrase semantics).+ /// The exact assertion is "space-joined, not OR-joined"; what the+ /// individual tokens look like after `prepare_fts5_token` is a+ /// separate concern (and unchanged from pre-#58 behaviour).+ #[test]+ fn quoted_phrase_query_is_not_or_joined() {+ let q = prepare_fts5_query("\"exact phrase\" baz");+ assert!(+ !q.contains(" OR "),+ "explicit quoted-phrase query must not get OR-joined; got {q}"+ );+ }++ /// Same escape-hatch logic for parenthesised sub-expressions —+ /// `(foo OR bar) AND baz` must survive unmangled.+ #[test]+ fn parenthesised_query_is_not_or_joined() {+ let q = prepare_fts5_query("(foo OR bar) AND baz");+ assert!(+ !q.contains("OR (foo"),+ "parens detection must skip OR-join entirely; got {q}"+ );+ assert!(+ q.contains("AND"),+ "explicit AND inside parens query must survive; got {q}"+ );+ }+#[test]fn known_columns_are_preserved() {assert_eq!(prepare_fts5_query("title:handoff"), "title:handoff");