Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

fix(mcp): validate synthesized answer citation identities

Mihael Zamin Sousa0c7e8a42f6f3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 77cfb862..fb9c5b93 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,16 @@ version in [`docs/changelog/`](docs/changelog/):
## [Unreleased]
+### Fixed
+
+- `memory_query(answer=true)` now validates model-generated citation paths
+ against the snippets supplied in that request. Unknown paths and paths
+ shared by distinct page versions withhold the answer, while retrieval hits
+ remain available with an `answer_unavailable` note. Repeated citations are
+ deduplicated in model order; the default query path makes no added calls
+ (#1682).
+
+
## [3.2.3] - 2026-10-24
### Changed
diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rs
index 9670f6f0..08d3baf9 100644
--- a/crates/ai-memory-mcp/src/server.rs
+++ b/crates/ai-memory-mcp/src/server.rs
@@ -939,8 +939,9 @@ async fn rerank_page_hits(
/// Synthesized "dialectic" answer attached to a `memory_query` response when
/// the caller opts in with `answer=true` and a provider is configured. The
-/// `text` is a natural-language answer drawn strictly from the retrieved hit
-/// snippets; `citations` are the page paths the model reported drawing from.
+/// `text` is generated by the model from the supplied snippets;
+/// `citations` are model-reported paths validated against the request's
+/// evidence. This checks source identity, not whether each claim is supported.
#[derive(Debug, Serialize)]
struct QueryAnswer {
text: String,
@@ -3290,7 +3291,7 @@ impl AiMemoryServer {
let (answer, answer_unavailable) = if args.answer.unwrap_or(false) {
match self.llm.as_ref() {
Some(llm) => {
- let request = build_answer_request(
+ let (request, sources) = build_answer_request(
&args.query,
&hits,
&global_scope_hits,
@@ -3305,13 +3306,17 @@ impl AiMemoryServer {
)
.await
{
- Ok(synth) => (
- Some(QueryAnswer {
- text: synth.answer,
- citations: synth.citations,
- }),
- None,
- ),
+ Ok(synth) => match validate_answer_citations(synth, &sources) {
+ Some(answer) => (Some(answer), None),
+ None => (
+ None,
+ Some(
+ "answer citations did not identify unambiguous supplied evidence; \
+ returning hits without an answer"
+ .into(),
+ ),
+ ),
+ },
Err(e) => {
// Redacted fields only: the `Display` of a provider
// failure carries the upstream response body, and
@@ -7691,10 +7696,8 @@ fn build_explore_request(
/// `prompts/explore_system.md`.
const EXPLORE_SYSTEM_PROMPT: &str = include_str!("../prompts/explore_system.md");
-/// System prompt for the opt-in `memory_query(answer=true)` synthesis. Keeps
-/// the model strictly grounded in the supplied snippets and forces the cited
-/// paths to come from the provided context (invariant against fabricated
-/// citations).
+/// System prompt for the opt-in `memory_query(answer=true)` synthesis.
+/// Citation membership is enforced separately after the provider returns.
const ANSWER_SYSTEM_PROMPT: &str = "You answer a user's question using ONLY the \
numbered memory-page snippets provided. Do not use any outside knowledge. \
Write a concise, direct answer grounded strictly in those snippets. In \
@@ -7703,17 +7706,46 @@ const ANSWER_SYSTEM_PROMPT: &str = "You answer a user's question using ONLY the
snippets do not contain enough information to answer, say so plainly in \
`answer` and return an empty `citations` list.";
+// A PageId identifies one scoped page version. A path shared by distinct IDs
+// cannot identify which scope or version a path-only citation means; None marks
+// that ambiguity without changing the public response or querying the store.
+type AnswerSources<'a> = HashMap<&'a str, Option<PageId>>;
+
+fn validate_answer_citations(
+ synth: AnswerSynthesis,
+ sources: &AnswerSources<'_>,
+) -> Option<QueryAnswer> {
+ if synth
+ .citations
+ .iter()
+ .any(|path| !sources.get(path.as_str()).is_some_and(Option::is_some))
+ {
+ return None;
+ }
+ let mut seen = HashSet::new();
+ let citations = synth
+ .citations
+ .iter()
+ .filter(|path| seen.insert(path.as_str()))
+ .cloned()
+ .collect();
+ Some(QueryAnswer {
+ text: synth.answer,
+ citations,
+ })
+}
+
/// Build the structured-output request for `memory_query(answer=true)`. Inlines
/// the retrieved hit snippets (project hits first, then any `_global` scope
/// hits) as numbered, path-labelled context so the model can ground its answer
/// and cite exact paths. Snippets are stripped of the FTS `<mark>` HTML so the
/// model sees clean text.
-fn build_answer_request(
+fn build_answer_request<'a>(
query: &str,
- hits: &[QueryHit],
- global_scope_hits: &[QueryHit],
+ hits: &'a [QueryHit],
+ global_scope_hits: &'a [QueryHit],
reasoning: ReasoningTier,
-) -> ai_memory_llm::ChatRequest {
+) -> (ai_memory_llm::ChatRequest, AnswerSources<'a>) {
fn clean(snippet: &str) -> String {
ai_memory_store::plain_snippet(snippet)
}
@@ -7722,8 +7754,17 @@ fn build_answer_request(
user.push_str(query);
user.push_str("\n\n## Memory page snippets\n\n");
let mut n = 0usize;
+ let mut sources = AnswerSources::new();
for hit in hits.iter().chain(global_scope_hits.iter()) {
n += 1;
+ sources
+ .entry(hit.hit.path.as_str())
+ .and_modify(|id| {
+ if *id != Some(hit.hit.id) {
+ *id = None;
+ }
+ })
+ .or_insert(Some(hit.hit.id));
user.push_str(&format!(
"{}. path: `{}`\n title: {}\n snippet: {}\n\n",
n,
@@ -7735,7 +7776,7 @@ fn build_answer_request(
if n == 0 {
user.push_str("(no snippets matched the query)\n\n");
}
- ai_memory_llm::ChatRequest {
+ let request = ai_memory_llm::ChatRequest {
system: Some(ANSWER_SYSTEM_PROMPT.into()),
messages: vec![ai_memory_llm::ChatMessage {
role: ai_memory_llm::Role::User,
@@ -7745,7 +7786,8 @@ fn build_answer_request(
// (byte-identical to the pre-tier answer path).
max_tokens: reasoning.scale_max_tokens(2_000),
temperature: Some(0.1),
- }
+ };
+ (request, sources)
}
/// Synthetic anonymous request `Parts` for callers arriving without request
@@ -8151,6 +8193,35 @@ mod tests {
.collect()
}
+ #[test]
+ fn answer_sources_distinguish_repeated_rows_from_ambiguous_paths() {
+ let mut hits: Vec<QueryHit> = rerank_test_hits(3)
+ .into_iter()
+ .map(|(hit, _)| QueryHit::from(hit))
+ .collect();
+ hits[1].hit = hits[0].hit.clone();
+ let path = hits[0].hit.path.as_str().to_owned();
+ let (_, sources) = build_answer_request("query", &hits[..2], &[], ReasoningTier::Minimal);
+ let answer = || AnswerSynthesis {
+ answer: "A supported answer".into(),
+ citations: vec![path.clone(), path.clone()],
+ };
+ assert_eq!(
+ validate_answer_citations(answer(), &sources)
+ .unwrap()
+ .citations
+ .as_slice(),
+ std::slice::from_ref(&path)
+ );
+
+ // Different scoped rows (or versions) can have the same path. A later
+ // repeat of the first row must not erase that ambiguity.
+ hits[2].hit.path = hits[0].hit.path.clone();
+ hits.swap(1, 2);
+ let (_, sources) = build_answer_request("query", &hits, &[], ReasoningTier::Minimal);
+ assert!(validate_answer_citations(answer(), &sources).is_none());
+ }
+
#[tokio::test]
async fn reranker_reorders_one_bounded_prefix_without_shrinking_large_limits() {
let (_tmp, _store, server, _ws, _proj) = setup_server().await;
diff --git a/crates/ai-memory-mcp/tests/suite/query_answer.rs b/crates/ai-memory-mcp/tests/suite/query_answer.rs
index c7241334..ee56b611 100644
--- a/crates/ai-memory-mcp/tests/suite/query_answer.rs
+++ b/crates/ai-memory-mcp/tests/suite/query_answer.rs
@@ -41,6 +41,7 @@ const PROJ: &str = "scratch";
/// synthesized shape AND that the default path never touches the LLM.
struct FakeAnswerLlm {
calls: Arc<AtomicUsize>,
+ response: Value,
}
#[async_trait::async_trait]
@@ -69,10 +70,7 @@ impl LlmProvider for FakeAnswerLlm {
) -> LlmResult<serde_json::Value> {
self.calls.fetch_add(1, Ordering::SeqCst);
// Shape must deserialize into the server's answer-synthesis struct.
- Ok(json!({
- "answer": "The widget subsystem stores its needle in notes/topic.md.",
- "citations": ["notes/topic.md"],
- }))
+ Ok(self.response.clone())
}
}
@@ -100,6 +98,17 @@ fn mount(server: AiMemoryServer) -> Router {
/// Build a harness; `with_provider` decides whether a fake LLM is attached.
async fn harness(with_provider: bool) -> Harness {
+ harness_with_response(
+ with_provider,
+ json!({
+ "answer": "The widget subsystem stores its needle in notes/topic.md.",
+ "citations": ["notes/topic.md"],
+ }),
+ )
+ .await
+}
+
+async fn harness_with_response(with_provider: bool, response: Value) -> Harness {
let tmp = TempDir::new().expect("tempdir");
let store = Store::open(tmp.path()).expect("store");
let ws = store.writer.get_or_create_workspace(WS).await.expect("ws");
@@ -115,6 +124,7 @@ async fn harness(with_provider: bool) -> Harness {
let calls = Arc::new(AtomicUsize::new(0));
let provider: Arc<dyn LlmProvider> = Arc::new(FakeAnswerLlm {
calls: calls.clone(),
+ response,
});
server = server.with_llm(provider);
Some(calls)
@@ -351,6 +361,207 @@ async fn answer_true_without_provider_degrades_gracefully() {
);
}
+#[tokio::test]
+async fn answer_rejects_a_citation_not_in_the_request() {
+ let h = harness_with_response(
+ true,
+ json!({
+ "answer": "Invented answer must not escape.",
+ "citations": ["notes/topic.md", "notes/fabricated.md"],
+ }),
+ )
+ .await;
+ seed_needle(&h).await;
+ let resp = call(
+ &h.router,
+ "memory_query",
+ query_args("needle", json!({"answer": true})),
+ )
+ .await;
+ assert_eq!(hit_paths(&resp), ["notes/topic.md"]);
+ assert!(resp.get("answer").is_none(), "unsupported answer: {resp}");
+ assert!(
+ resp.get("answer_unavailable").is_some(),
+ "missing reason: {resp}"
+ );
+ assert!(!resp.to_string().contains("Invented answer"));
+ assert!(!resp.to_string().contains("fabricated.md"));
+ assert_eq!(h.calls.as_ref().unwrap().load(Ordering::SeqCst), 1);
+}
+
+#[tokio::test]
+async fn answer_rejects_a_citation_from_an_unqueried_project() {
+ let h = harness_with_response(
+ true,
+ json!({
+ "answer": "Foreign answer must not escape.",
+ "citations": ["notes/foreign.md"],
+ }),
+ )
+ .await;
+ seed_needle(&h).await;
+ let foreign = h
+ .store
+ .writer
+ .get_or_create_project(h.ws, "foreign", None)
+ .await
+ .unwrap();
+ h.store
+ .writer
+ .upsert_page(page(
+ h.ws,
+ foreign,
+ "notes/foreign.md",
+ "needle foreign secret",
+ ))
+ .await
+ .unwrap();
+ let resp = call(
+ &h.router,
+ "memory_query",
+ query_args("needle", json!({"answer": true})),
+ )
+ .await;
+ assert_eq!(hit_paths(&resp), ["notes/topic.md"]);
+ assert!(resp.get("answer").is_none(), "foreign citation: {resp}");
+ assert!(resp.get("answer_unavailable").is_some());
+ assert!(!resp.to_string().contains("foreign"));
+ assert_eq!(h.calls.as_ref().unwrap().load(Ordering::SeqCst), 1);
+}
+
+#[tokio::test]
+async fn answer_rejects_same_path_citations_across_scopes() {
+ let h = harness(true).await;
+ seed_needle(&h).await;
+ let foreign_ws = h
+ .store
+ .writer
+ .get_or_create_workspace("other")
+ .await
+ .unwrap();
+ let foreign = h
+ .store
+ .writer
+ .get_or_create_project(foreign_ws, PROJ, None)
+ .await
+ .unwrap();
+ h.store
+ .writer
+ .upsert_page(page(
+ foreign_ws,
+ foreign,
+ "notes/topic.md",
+ "needle from another workspace",
+ ))
+ .await
+ .unwrap();
+ let resp = call(
+ &h.router,
+ "memory_query",
+ json!({
+ "query": "needle", "answer": true,
+ "scopes": [{"workspace": WS, "project": PROJ}, {"workspace": "other", "project": PROJ}],
+ }),
+ )
+ .await;
+ assert_eq!(hit_paths(&resp).len(), 2, "both scopes must match: {resp}");
+ assert!(resp.get("answer").is_none(), "ambiguous citation: {resp}");
+ assert!(resp.get("answer_unavailable").is_some());
+ assert_eq!(h.calls.as_ref().unwrap().load(Ordering::SeqCst), 1);
+}
+
+#[tokio::test]
+async fn answer_deduplicates_citations_in_model_order_and_preserves_unicode() {
+ let paths = ["notes/decisão.md", "notes/topic.md", "notes/決定.md"];
+ let h = harness_with_response(
+ true,
+ json!({
+ "answer": "All three snippets mention needle.",
+ "citations": [paths[0], paths[1], paths[0], paths[2], paths[1]],
+ }),
+ )
+ .await;
+ for path in paths {
+ h.store
+ .writer
+ .upsert_page(page(h.ws, h.proj, path, "needle appears here"))
+ .await
+ .unwrap();
+ }
+ let resp = call(
+ &h.router,
+ "memory_query",
+ query_args("needle", json!({"answer": true})),
+ )
+ .await;
+ assert_eq!(resp.pointer("/answer/citations"), Some(&json!(paths)));
+ assert!(resp.get("answer_unavailable").is_none());
+ assert_eq!(h.calls.as_ref().unwrap().load(Ordering::SeqCst), 1);
+}
+
+#[tokio::test]
+async fn answer_global_preferences_accept_unique_paths_and_refuse_collisions() {
+ for (path, accepted) in [("notes/global.md", true), ("notes/topic.md", false)] {
+ let h = harness_with_response(
+ true,
+ json!({
+ "answer": "The global preference mentions needle.",
+ "citations": [path],
+ }),
+ )
+ .await;
+ seed_needle(&h).await;
+ let global = ai_memory_store::create_global_scope(&h.store.writer)
+ .await
+ .unwrap();
+ h.store
+ .writer
+ .upsert_page(page(
+ global.workspace_id,
+ global.project_id,
+ path,
+ "needle global preference",
+ ))
+ .await
+ .unwrap();
+ let resp = call(
+ &h.router,
+ "memory_query",
+ query_args("needle", json!({"answer": true})),
+ )
+ .await;
+ assert_eq!(resp["global_scope_hits"].as_array().unwrap().len(), 1);
+ assert_eq!(resp.get("answer").is_some(), accepted, "{resp}");
+ assert_eq!(
+ resp.get("answer_unavailable").is_some(),
+ !accepted,
+ "{resp}"
+ );
+ assert_eq!(h.calls.as_ref().unwrap().load(Ordering::SeqCst), 1);
+ }
+}
+
+#[tokio::test]
+async fn answer_preserves_empty_citations_for_abstention() {
+ let h = harness_with_response(
+ true,
+ json!({
+ "answer": "The snippets do not contain enough information.",
+ "citations": [],
+ }),
+ )
+ .await;
+ seed_needle(&h).await;
+ let resp = call(
+ &h.router,
+ "memory_query",
+ query_args("needle", json!({"answer": true})),
+ )
+ .await;
+ assert_eq!(resp.pointer("/answer/citations"), Some(&json!([])));
+ assert!(resp.get("answer_unavailable").is_none());
+}
+
/// 4. Live smoke test: wire a real provider only when a key is in the
/// environment, and assert a non-empty answer. Skips cleanly (and is
/// `#[ignore]`d) so it never runs in CI or reads a key that isn't set. Run
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 7671424d..35ac64a8 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -729,7 +729,7 @@ does not need to ride on the public protocol change.
| Tool | Hint | Purpose |
|---|---|---|
-| `memory_query` | read-only | FTS5 + entity-match + graph RRF + optional vector RRF + observation-evidence stream (on by default) search, followed by bounded kind/tier/pinned/tag authority adjustment and raw fallback. Bumps access counters for page hits. Defaults to the current project; single-project calls (project implicit or named with `workspace`+`project`) also union the reserved `_global` preferences scope as `global_scope_hits`, and only an explicit multi-`scopes` set opts out (#930); `scopes` searches named sibling projects; `global=true` searches every project at once (each hit annotated with its workspace + project). With `AI_MEMORY_RERANKER=llm`, project/scopes candidate pools are fused before at most one final LLM relevance pass; query/title/snippet data is bounded and JSON-encoded, and any timeout, provider error, invalid/incomplete score set, or four-call concurrency saturation preserves the adjusted order. The distinct `global=true` FTS-only ranker and supplemental global-preference hits are not reranked. `explain=true` attaches per-hit `score_details` (per-stream ranks, matched entities, raw FTS/cosine/entity inverse-frequency scores, the matched observation ids when the observation stream voted, RRF contributions, graph provenance including the typed edge kind (`causes`/`fixes`/`contradicts`) a neighbour was reached by, the page's evidence count, authority multiplier, and optional rerank score) to project/scopes hits plus a top-level `streams_active` list and a `timings` object with each stream's wall time in milliseconds (`fts_ms`, `entity_ms`, `vector_ms` for the stored-vector scans, `graph_ms`, `observation_ms`, `rerank_ms`; a stream that did not run is left out, and `scopes` searches sum per stream). Timings are read only on an explained query; the normal path takes no clock reading for them. The global FTS-only ranker reports its active stream and `fts_ms` without per-hit details; `as_of` reports no timings. `include_expired=true` also returns TTL-expired pages. `include_superseded=true` also returns superseded (non-latest) page versions across the FTS/entity/vector/graph streams, each hit labelled `superseded: true` (the current version is never marked); default-off is byte-identical to the latest-only behaviour, and `global=true` / `as_of` are unaffected. `pin_first=true` prepends the project's bounded pinned latest pages (`ReaderPool::list_pinned_pages`, cap 10) ahead of the fused hits, deduped by page id (a pinned page that also matches appears once, marked `pinned: true`) and re-truncated to the requested limit; it applies to single-project searches (default or `workspace`+`project`), is ignored on `scopes`/`global`/`as_of`, and default-off is byte-identical. `answer=true` (opt-in, off by default) additionally synthesizes a cited natural-language answer over the top hits via the configured LLM provider (`complete_structured`, JSON-schema `{ answer, citations }`), attached as `answer: { text, citations }`; with no provider configured it returns the hits plus an `answer_unavailable` note instead of erroring, and with `answer` unset/`false` no provider is accessed and the response is byte-identical (invariant #13). It applies to the normal single-project/`scopes` path; `global`/`as_of` ignore it. Answer quality is not yet eval-validated. An optional `reasoning` tier (`minimal` (default) / `low` / `medium` / `high` / `max`) tunes the synthesis effort: `ChatRequest` carries no per-request reasoning field (the provider-level `reasoning_effort` is fixed at construction from config), so the tier maps to a per-tier max-token budget scaled off the path's base (answer base 2 000; `minimal` = 1x = byte-identical, `low` 1.5x, `medium` 2x, `high` 3x, `max` 4x). The tier is inert unless the `answer` LLM path runs (invariant #13); an unknown value is rejected by the schema (invariant #7). Optional `kind`, `tag`, `tier` and `path_prefix` filters narrow candidates before ranking, on every stream including the CJK substring search. |
+| `memory_query` | read-only | FTS5 + entity-match + graph RRF + optional vector RRF + observation-evidence stream (on by default) search, followed by bounded kind/tier/pinned/tag authority adjustment and raw fallback. Bumps access counters for page hits. Defaults to the current project; single-project calls (project implicit or named with `workspace`+`project`) also union the reserved `_global` preferences scope as `global_scope_hits`, and only an explicit multi-`scopes` set opts out (#930); `scopes` searches named sibling projects; `global=true` searches every project at once (each hit annotated with its workspace + project). With `AI_MEMORY_RERANKER=llm`, project/scopes candidate pools are fused before at most one final LLM relevance pass; query/title/snippet data is bounded and JSON-encoded, and any timeout, provider error, invalid/incomplete score set, or four-call concurrency saturation preserves the adjusted order. The distinct `global=true` FTS-only ranker and supplemental global-preference hits are not reranked. `explain=true` attaches per-hit `score_details` (per-stream ranks, matched entities, raw FTS/cosine/entity inverse-frequency scores, the matched observation ids when the observation stream voted, RRF contributions, graph provenance including the typed edge kind (`causes`/`fixes`/`contradicts`) a neighbour was reached by, the page's evidence count, authority multiplier, and optional rerank score) to project/scopes hits plus a top-level `streams_active` list and a `timings` object with each stream's wall time in milliseconds (`fts_ms`, `entity_ms`, `vector_ms` for the stored-vector scans, `graph_ms`, `observation_ms`, `rerank_ms`; a stream that did not run is left out, and `scopes` searches sum per stream). Timings are read only on an explained query; the normal path takes no clock reading for them. The global FTS-only ranker reports its active stream and `fts_ms` without per-hit details; `as_of` reports no timings. `include_expired=true` also returns TTL-expired pages. `include_superseded=true` also returns superseded (non-latest) page versions across the FTS/entity/vector/graph streams, each hit labelled `superseded: true` (the current version is never marked); default-off is byte-identical to the latest-only behaviour, and `global=true` / `as_of` are unaffected. `pin_first=true` prepends the project's bounded pinned latest pages (`ReaderPool::list_pinned_pages`, cap 10) ahead of the fused hits, deduped by page id (a pinned page that also matches appears once, marked `pinned: true`) and re-truncated to the requested limit; it applies to single-project searches (default or `workspace`+`project`), is ignored on `scopes`/`global`/`as_of`, and default-off is byte-identical. `answer=true` (opt-in, off by default) additionally synthesizes a cited natural-language answer over the top hits via the configured LLM provider (`complete_structured`, JSON-schema `{ answer, citations }`), attached as `answer: { text, citations }`. Citation paths must identify exactly one supplied page version, including supplemental preferences. Repeated citations are deduplicated in model order. An unknown path or a path shared by distinct page IDs withholds the whole answer and returns `answer_unavailable` with the unchanged retrieval hits; this includes same-path historical versions. Empty citations remain valid for abstention. This validates source identity, not the truth of generated claims. With no provider configured it returns the hits plus an `answer_unavailable` note instead of erroring, and with `answer` unset/`false` no provider is accessed and the response is byte-identical (invariant #13). It applies to the normal single-project/`scopes` path; `global`/`as_of` ignore it. Answer quality is not yet eval-validated. An optional `reasoning` tier (`minimal` (default) / `low` / `medium` / `high` / `max`) tunes the synthesis effort: `ChatRequest` carries no per-request reasoning field (the provider-level `reasoning_effort` is fixed at construction from config), so the tier maps to a per-tier max-token budget scaled off the path's base (answer base 2 000; `minimal` = 1x = byte-identical, `low` 1.5x, `medium` 2x, `high` 3x, `max` 4x). The tier is inert unless the `answer` LLM path runs (invariant #13); an unknown value is rejected by the schema (invariant #7). Optional `kind`, `tag`, `tier` and `path_prefix` filters narrow candidates before ranking, on every stream including the CJK substring search. |
| `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`; optional `workspace` + `project` targets a named sibling workspace/project. Use when an agent needs more than the 24-word snippets from `memory_query`. `include_related=true` also walks the link graph outward from the page (bounded BFS reusing the `page_links` primitive per node: default 1 hop, hard cap 3, global visited set for dedup/cycle-safety, total-node cap 50, cross-project aware) and returns a `related` array of reachable pages, each labelled with its `depth` (hop distance) and `direction` (`link`/`backlink`); default-off is byte-identical (no `related` field). The response carries the page's current version as `page_id`, the value compare-and-write calls pass back. A page whose `expires_at` TTL has passed is still returned and carries `expired: true`; a live page's response has no such field. |
| `memory_read_session_observations` | read-only | Page through ONE session's raw hook observations (`ObservationRecord` with full sanitized body, capped per row by `body_max_chars`), restricted to the rows that landed in the resolved scope and to sessions the caller may see; `total` and `elided_other_scope` report the in-scope count and the rows the session left in another project. `session_id` omitted reads the visible session with the newest captured work other than the caller's own, ended or cut off (`ReaderPool::recent_session_activity` over 30 days, preferring the caller session's cwd), else the latest completed visible session. |
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index ae475285..eaa13709 100644
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@ -34,6 +34,7 @@ means the boundary is not built yet.
| 1h | The profile learns only from what it may: the user's own prompts and curated pages, from contributing projects, never another operator's words in a private profile and never a restricted project in a shared one; stored text stays data | `ai-memory-store/src/profile.rs` `profile_prompts_since` (only `user-prompt` observations), `auto_improve_decided_by` (the decider agent a page's `auto_improve_proposal_id` resolves to), `profile_harvest_projects` / `profile_candidates` (`profile_contribute = 0` excluded, including candidates recorded before the opt-out); `ai-memory-store/src/ops.rs` `move_session` (a moved session's `session:<id>` prompt candidates are re-stamped into the target project in the same transaction, so they answer to its contribute flag and access mode, #1265); `ai-memory-consolidate/src/profile.rs` `user_written` (shared with the verbatim-residue caller in row 25: a harness turn or Codex's injected instructions stored as a prompt is skipped whole, and ai-memory's routing and untrusted-history blocks, fenced by markers on their own lines, are cut out before any sentence is read), the auto-approved-proposal skip in `harvest_project` (a page the auto-improve scheduler auto-approved is model output nobody reviewed and never becomes a candidate; a human-approved page, or one whose proposal id has no row, stays curated, #1211), `convergence_targets` (a `user` target keeps only candidates whose `contributor` is that operator, from projects the per-project choke point lets them read; a `global`/`workspace` target on an operator-distinguishing server drops restricted projects), `min_contributors` / `converge` (a team profile admits a statement only on evidence from at least two distinct operators, so one operator cannot plant a default in everyone's session start) (never rewrites a page without its `generated_by` stamp or whose body changed; `profile_entry_ledger` keeps a forgotten entry out), `classify_batch` / `merge_entry` (sanitized, JSON-encoded input; the evidence quote is always the user's sentence) | consolidate `integration::profile_harvest` `tool_output_is_never_a_candidate`, `an_opted_out_project_is_never_harvested`, `a_private_profile_never_harvests_another_operator`, `a_team_profile_never_harvests_a_restricted_project`, `a_team_profile_needs_more_than_one_operator` (one operator in two open projects not admitted; a second operator admits it; fails with the threshold at one), `a_personal_profile_admits_one_operators_habit` (control), `a_hand_edited_entry_is_never_clobbered`, `a_forgotten_entry_is_not_recreated_until_said_again`, `injected_instructions_stay_data`, `injected_instructions_and_ai_memory_blocks_are_never_candidates`, `page_metadata_fields_are_never_candidates`, `auto_approved_auto_improve_pages_are_never_candidates` (an auto-approved page refused; human-approved and hand-written controls admitted; fails with the decider check removed), consolidate `profile::tests::a_stored_page_metadata_field_is_not_a_waiting_habit` (each with a legitimate control; each fails with its guard removed); mcp `integration::admin_profile_routes` `review_and_rebuild_are_root_only_on_a_multi_user_server`; store `integration::session_move` `a_moved_sessions_profile_candidate_follows_the_target_projects_governance` (a session moved into an opted-out project stops counting and one moved into a restricted project is marked restricted; an open-target control still counts, from the target; fails with the `move_session` re-stamp removed); residue control in row 25 | STRONG |
| 1i | SessionEnd's bounded digest cannot read a foreign session by raw id | `ai-memory-store/src/reader.rs` `session_has_substantive_observation` joins the session row to the caller's `(workspace_id, project_id)`; `read_session_observations` validates that same tuple inside the read transaction before exposing its bounded snapshot, returning the same `SessionCollision` refusal for foreign and missing ids; `ai-memory-hooks/src/router.rs` supplies only the scope pinned by hook admission | `multi_session.rs` `session_end_readers_refuse_foreign_session_ids` (sibling-project and cross-workspace tuples cannot learn the substantive bit or open the snapshot; a missing id gets the same refusal; the owning tuple reads the one-row summary as the legitimate control). Removing either scope predicate fails its corresponding assertion | STRONG |
| 1i2 | The consolidation session read fails closed on a session with no observations in its target scope, and memory is bounded by the selection, not the session | `ai-memory-store/src/reader.rs` `read_session_observations_in_scope` opens the bounded session snapshot only when at least one observation of the session exists in the caller's `(workspace_id, project_id)` (an `EXISTS` over `observations`), returning `SessionCollision` for foreign, purged and missing alike; `SessionObservationSnapshot::projection_totals` reads `COUNT(*)` and `MIN`/`MAX(created_at)` in one aggregate inside the same read transaction; `SessionObservationSnapshot::row_by_rowid` re-reads a single row only when both `session_id = ?1` and `rowid = ?2` match, so a legitimate snapshot cannot fetch another session's body by raw rowid; `ai-memory-consolidate/src/projection.rs` `project_session_observations` streams rows one at a time, keeping only the two anchors' rowids and a bounded top-k heap of the best `limit - 2` rows (the shared `selection_key` the in-memory path sorts with), re-reading only the selected rows by rowid; residue candidate lists exist only while the opt-in residue is on; `ai-memory-consolidate/src/consolidator.rs` `consolidate_session` / `consolidate_session_multi` gate on the scope `resolve_target` already resolves (the observations' majority scope) and map the refusal to `EmptySession`, exactly as an empty session did before; auto-improve keeps its `session_project_ids` gate plus the sessions-row-gated `read_session_observations` (row 1i), and computes preflight, duration, report and prompt from one single snapshot read — a purge committed between the totals aggregate and the preflight decision cannot split the two generations, and a rowless session with the preflight minimums disabled is still reviewed with the empty `(none)` projection, as the full-load path did | `tests/suite/bounded_session_load.rs` `gated_reader_refuses_foreign_scopes` (a foreign workspace and a foreign project are refused with `SessionCollision`; the session's own scope reads the totals as the legitimate control), store `tests/suite/multi_session.rs` `rowid_fetch_refuses_foreign_sessions_with_legitimate_control` (a foreign session's rowid is refused through a legitimate snapshot in both directions; the session's own rowid reads as the control; removing only the session predicate from the rowid fetch fails it), `purged_session_is_refused_without_an_llm_call` (both entry points fail closed with `EmptySession` and no LLM call once the rows are gone), `stale_sessions_row_does_not_divert_the_write` (a sessions row frozen on another project does not move the write out of the observations' project), `hybrid_two_project_session_prompt_is_unchanged` (a two-project session keeps today's exact prompt: every row of the session id is projected, the page lands in the majority project), `streaming_projection_matches_the_frozen_base_projection` and `current_projection_matches_the_frozen_base_projection` (the new paths agree field for field with a verbatim frozen copy of the pre-change `projection.rs` — an independent rule — at the 256/257/300 sample-cap edges and below), `large_session_prompts_match_the_old_full_load_path` (at 150k, 100k and 5k rows the streaming prompts are byte-identical to the frozen projection and both `#[cfg(test)]` full-load oracles, with the top-k heap asserted bounded by the selection cap and zero residue tuples while residue is off), `auto_improve_review_uses_one_generation_of_the_session` (a purge committed inside the review's single snapshot read cannot split the report's count from the prompt's), `auto_improve_review_of_a_rowless_session_with_preflight_off` (a present rowless session with zero minimums still gets its `(none)` review), `zero_budget_streaming_path_keeps_the_old_no_budget_marker` (the zero-budget early return reaches the streaming path byte-identically), and the byte-identical equivalence tests against the full-load oracles (below and above the cap, residue on/off, character-budget pruning, `created_at` ties, 16-KiB bodies, routing text, auto-improve at/above its 48/72 limits and preflight) | STRONG — the LLM input is proven byte-identical to the pre-change full load, including against a frozen verbatim copy of the base projection; dropping the `EXISTS` predicate fails `gated_reader_refuses_foreign_scopes`; removing only the session predicate from the rowid fetch fails the store `rowid_fetch_refuses_foreign_sessions_with_legitimate_control` |
+| 1j | Synthesized answer citations refer only to unambiguous evidence supplied in that request | `ai-memory-mcp/src/server.rs` `build_answer_request` records path-to-`PageId` identity while rendering snippets; `validate_answer_citations` refuses unknown or ambiguous paths before returning any answer text | `query_answer.rs` `answer_rejects_a_citation_not_in_the_request`, `answer_rejects_a_citation_from_an_unqueried_project`, `answer_rejects_same_path_citations_across_scopes`, `answer_global_preferences_accept_unique_paths_and_refuse_collisions`; controls: `answer_true_with_provider_synthesizes_cited_answer`, `answer_deduplicates_citations_in_model_order_and_preserves_unicode`; `server.rs` `answer_sources_distinguish_repeated_rows_from_ambiguous_paths` | STRONG for source identity (the four refusal cases fail with the validator guard removed); generated claims and citation-free abstentions are not semantically verified |
| 2 | Workspace isolation | same as #1; same-named project → distinct ids per workspace | `scope.rs` cross-workspace resolution rows; `multi_scope` dedup/validate; `ai-memory-web` `history_replay.rs` (another workspace's page path, version id and session id answer 404, same tests and bites as row 1) | STRONG |
| 2b | Managed-workstream discovery stays checkout-local, including pagination | `ai-memory-workstream/src/repository.rs` `inspect_repository_fingerprints` shares the launch identity derivation without checkpoint scans; `ai-memory-cli/src/commands/resume.rs` `candidates_for_checkout` queries only the cwd, never registry links; the explicit `--all` walk (`candidates_across_checkouts`) lists each linked checkout through its own fingerprint-scoped request and applies `--workspace` before any request; `ai-memory-hooks/src/workstream.rs` `list_recent_workstreams` resolves an authorized explicit scope on every page; `ai-memory-store/src/workstream.rs` `list_recent` applies workspace/project/repository/worktree predicates before `LIMIT`/`OFFSET` | `resume.rs` `resume_lists_all_current_checkout_rows_not_registered_foreign_checkouts` (same scope/remote foreign checkout refused, 125 local rows visible), `empty_current_checkout_does_not_fall_back_to_the_registry`, `resume_all_walks_every_linked_checkout_and_honours_the_workspace_filter` (a foreign workspace filter sends no request; the default picker still ignores the registry); `workstream.rs` `recent_workstream_pages_reach_older_rows_without_crossing_checkout_or_scope` (foreign repo, worktree, project and workspace excluded on every page; 105 legitimate rows reach the client, huge offsets return nothing); store `recent_workstreams_are_checkout_local_and_include_linked_harnesses` (page two keeps native harness links); `repository.rs` `reports_origin_push_url_and_linked_worktree` verifies lightweight/full fingerprint parity and distinct worktree keys; CLI `resume_yolo_displays_picker_without_scanning_git_status` verifies listing skips status scans | STRONG |
| 3 | Multi-user auth ladder | `ai-memory-core/src/actor.rs` `AuthLevel::authorize`; `ai-memory-mcp/src/auth.rs` middleware; `admin.rs` `require_root_for_multiuser_admin` / `require_root`; `identity.rs` authorizes `NormalRead` behind the same machine bearer middleware as MCP; `serve.rs` mounts API-only and web+API protected routers behind `require_dual_auth` | `admin.rs` `multiuser_admin_routes_reject_db_user_tier` / `…reject_anonymous` / `create_user_as_user_tier_returns_403`; `auth.rs` unknown-bearer 401; `actor.rs` `skip_admission_chain_rejects_db_users`; `identity.rs` `identity_real_auth_isolates_users_root_and_revoked_keys`, `identity_anonymous_ignores_forged_headers_and_proxy_qualifies_oidc` (distinct users and root, invalid/revoked keys, forged headers, anonymous control); `serve.rs` `api_only_mode_keeps_data_authenticated_and_web_absent` (anonymous API read refused, authenticated control admitted, browser route absent; #986) | STRONG |