Skip to content

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.md
index 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
### Fixed
diff --git a/crates/ai-memory-core/src/routing_snippet.rs b/crates/ai-memory-core/src/routing_snippet.rs
index 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 or
short snippet does **not** mean the page is empty (a large page can
diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rs
index 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.rs
index 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");