Skip to content

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

Rust

feat(web): filter search by kind and tier

Peterson Salmea22549ed08f2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5c3060f3..ea538f03 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,12 @@ and [0.x](docs/changelog/0.x.md).
## [Unreleased]
### Added
+- Added kind and tier filters to the web search. The search page in `/web`
+ has "Kind" and "Tier" selects, and `/web/search` accepts `kind` and `tier`
+ for both a project search and a cross-project one. The filter runs after
+ ranking, so the hits that remain keep the order `memory_query` gives them,
+ and a project search looks through its top 100 matches rather than the
+ first page of results. An unknown `tier` is a 400. (#1248)
- Added backlinks, outgoing links and an outline to the web page view. A page
in `/web` now has a side column (below the text on narrow screens) with "On
this page", the h2 and h3 headings linked to their anchors (shown from two
diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rs
index 33932fd5..1a4c6f8d 100644
--- a/crates/ai-memory-store/src/reader.rs
+++ b/crates/ai-memory-store/src/reader.rs
@@ -1237,6 +1237,13 @@ pub struct PageHitWithMeta {
pub snippet: String,
/// Relevance rank after the bounded authority adjustment (lower is better).
pub rank: f64,
+ /// Semantic kind, so the web search can filter without a second lookup.
+ /// Not serialized: the MCP `global_hits` shape stays as it was.
+ #[serde(skip)]
+ pub kind: String,
+ /// Memory tier; see `kind`.
+ #[serde(skip)]
+ pub tier: String,
}
/// One raw observation fallback hit returned when compiled wiki pages miss.
@@ -2618,6 +2625,8 @@ impl ReaderPool {
title,
snippet,
rank,
+ kind,
+ tier,
},
authority,
));
@@ -3500,7 +3509,8 @@ impl ReaderPool {
let sql = format!(
"SELECT workspaces.name, projects.name, pages.path, pages.title, \
{descriptor} AS snip, \
- CAST(pages.updated_at AS REAL) AS rank \
+ CAST(pages.updated_at AS REAL) AS rank, \
+ {kind_expr} AS kind, pages.tier \
FROM pages \
JOIN projects ON projects.id = pages.project_id \
JOIN workspaces ON workspaces.id = pages.workspace_id \
@@ -3508,6 +3518,7 @@ impl ReaderPool {
ORDER BY pages.updated_at DESC \
LIMIT ?1",
descriptor = page_descriptor_expr("pages.body", "pages.frontmatter_json"),
+ kind_expr = page_kind_expr("pages.path", "pages.frontmatter_json"),
not_expired = not_expired("pages", "?2"),
);
let mut stmt = conn.prepare_cached(&sql)?;
@@ -3521,11 +3532,22 @@ impl ReaderPool {
let title: String = row.get(3)?;
let snippet = page_descriptor(&row.get::<_, String>(4)?, &title);
let rank: f64 = row.get(5)?;
- Ok((workspace_name, project_name, path, title, snippet, rank))
+ let kind: String = row.get(6)?;
+ let tier: String = row.get(7)?;
+ Ok((
+ workspace_name,
+ project_name,
+ path,
+ title,
+ snippet,
+ rank,
+ kind,
+ tier,
+ ))
})?;
let mut hits = Vec::new();
for row in rows {
- let (workspace_name, project_name, path, title, snippet, rank) = row?;
+ let (workspace_name, project_name, path, title, snippet, rank, kind, tier) = row?;
hits.push(PageHitWithMeta {
workspace_name,
project_name,
@@ -3533,6 +3555,8 @@ impl ReaderPool {
title,
snippet,
rank,
+ kind,
+ tier,
});
}
Ok(hits)
@@ -8441,6 +8465,52 @@ impl ReaderPool {
.await
}
+ /// Semantic kind and tier of each latest page in `page_ids`, in one query.
+ ///
+ /// Ids that name no latest page are absent from the map. The caller has
+ /// already scoped the ids (they come from a search the viewer was allowed
+ /// to run), so this reads no repository the viewer could not.
+ ///
+ /// # Errors
+ /// Propagates any SQL or pool error.
+ pub async fn page_kinds_tiers_by_ids(
+ &self,
+ page_ids: &[PageId],
+ ) -> StoreResult<std::collections::HashMap<PageId, (String, String)>> {
+ if page_ids.is_empty() {
+ return Ok(std::collections::HashMap::new());
+ }
+ let id_blobs: Vec<Value> = page_ids
+ .iter()
+ .map(|id| Value::Blob(id.as_bytes().to_vec()))
+ .collect();
+ self.with_conn(move |conn| {
+ let placeholders = std::iter::repeat_n("?", id_blobs.len())
+ .collect::<Vec<_>>()
+ .join(", ");
+ let sql = format!(
+ "SELECT pg.id, {kind_expr}, pg.tier FROM pages pg \
+ WHERE pg.is_latest = 1 AND pg.id IN ({placeholders})",
+ kind_expr = page_kind_expr("pg.path", "pg.frontmatter_json"),
+ );
+ let mut stmt = conn.prepare(&sql)?;
+ let rows = stmt.query_map(params_from_iter(id_blobs.iter()), |row| {
+ Ok((
+ row.get::<_, Vec<u8>>(0)?,
+ row.get::<_, String>(1)?,
+ row.get::<_, String>(2)?,
+ ))
+ })?;
+ let mut out = std::collections::HashMap::new();
+ for row in rows {
+ let (id, kind, tier) = row?;
+ out.insert(PageId::from_slice(&id)?, (kind, tier));
+ }
+ Ok(out)
+ })
+ .await
+ }
+
/// Look up a page's workspace and project names by its path (across all
/// workspaces and projects). Returns the first `is_latest = 1` match.
///
diff --git a/crates/ai-memory-web/src/routes/search.rs b/crates/ai-memory-web/src/routes/search.rs
index 669c7c86..399b5848 100644
--- a/crates/ai-memory-web/src/routes/search.rs
+++ b/crates/ai-memory-web/src/routes/search.rs
@@ -11,10 +11,15 @@
//! - **Cross-project search** (no scope): FTS5 over every repository the
//! viewer may read, as `memory_query(global=true)` does. Its trace is the
//! FTS time alone; there are no per-hit streams to show.
+//!
+//! `kind` and `tier` narrow either mode *after* ranking, so the surviving
+//! hits keep the order `memory_query` gives them.
use std::collections::BTreeMap;
+use std::str::FromStr;
use std::sync::Arc;
+use ai_memory_core::Tier;
use ai_memory_store::{SearchExplain, StreamTimings};
use askama::Template;
use axum::extract::{Query, State};
@@ -25,8 +30,8 @@ use serde::Deserialize;
use crate::markdown;
use crate::state::WebState;
use crate::templates::{
- HitTrace, ScopeGroup, ScopeOption, SearchHit, SearchView, StreamTraceRow, TimingRow,
- encode_segment, page_href, project_href,
+ FilterOption, HitTrace, ScopeGroup, ScopeOption, SearchHit, SearchView, StreamTraceRow,
+ TimingRow, encode_segment, page_href, project_href,
};
/// Hits a cross-project search returns when the request names no `limit`.
@@ -35,6 +40,22 @@ const GLOBAL_DEFAULT_LIMIT: usize = 50;
const SCOPED_DEFAULT_LIMIT: usize = 20;
/// Upper bound on `limit`, the same clamp `memory_query` applies.
const MAX_LIMIT: usize = 100;
+/// Page kinds the filter offers: the kinds a path convention implies, which
+/// are also the ones the consolidator writes.
+const KINDS: [&str; 10] = [
+ "rule",
+ "slot",
+ "session",
+ "decision",
+ "gotcha",
+ "concept",
+ "procedure",
+ "note",
+ "preference",
+ "fact",
+];
+/// Memory tiers the filter offers, in `Tier` declaration order.
+const TIERS: [&str; 4] = ["working", "episodic", "semantic", "procedural"];
/// Query-string parameters for the search endpoint.
#[derive(Debug, Deserialize)]
@@ -52,6 +73,12 @@ pub(crate) struct SearchParams {
/// project. Wins over `workspace` + `project` when both are sent.
#[serde(default)]
pub scope: Option<String>,
+ /// Keep only pages of this kind; empty keeps every kind.
+ #[serde(default)]
+ pub kind: Option<String>,
+ /// Keep only pages of this tier; empty keeps every tier.
+ #[serde(default)]
+ pub tier: Option<String>,
/// Most hits to show, clamped to `1..=100`.
#[serde(default)]
pub limit: Option<usize>,
@@ -109,6 +136,26 @@ pub(crate) async fn handler(
}
},
};
+ let kind = non_empty(params.kind.as_deref()).map(str::to_owned);
+ let tier = match non_empty(params.tier.as_deref()) {
+ Some(value) if Tier::from_str(value).is_ok() => Some(value.to_owned()),
+ Some(_) => {
+ return (
+ StatusCode::BAD_REQUEST,
+ "tier must be working, episodic, semantic or procedural",
+ )
+ .into_response();
+ }
+ None => None,
+ };
+ let filtered = kind.is_some() || tier.is_some();
+ let keeps = |hit_kind: &str, hit_tier: &str| {
+ kind.as_deref().is_none_or(|k| k == hit_kind)
+ && tier.as_deref().is_none_or(|t| t == hit_tier)
+ };
+ // A filter runs after ranking, so the ranker is asked for the most it can
+ // return and the limit is applied to what survives.
+ let fetch_limit = |limit: usize| if filtered { MAX_LIMIT + 1 } else { limit + 1 };
let internal = |error: ai_memory_store::StoreError| {
tracing::error!(%error, "web search failed");
StatusCode::INTERNAL_SERVER_ERROR.into_response()
@@ -138,7 +185,7 @@ pub(crate) async fn handler(
&state,
&[(resolved.workspace_id, resolved.project_id)],
&query,
- limit + 1,
+ fetch_limit(limit),
explain,
&super::api::owner_filter_for(actor),
)
@@ -149,8 +196,22 @@ pub(crate) async fn handler(
};
timings = result.timings;
streams_active = result.streams_active;
- truncated = result.hits.len() > limit;
- for (position, (hit, details)) in result.hits.into_iter().take(limit).enumerate() {
+ // The trace position is the rank before filtering.
+ let mut ranked: Vec<_> = result.hits.into_iter().enumerate().collect();
+ if filtered {
+ let ids: Vec<_> = ranked.iter().map(|(_, (hit, _))| hit.id).collect();
+ let facets = match state.reader.page_kinds_tiers_by_ids(&ids).await {
+ Ok(facets) => facets,
+ Err(error) => return internal(error),
+ };
+ ranked.retain(|(_, (hit, _))| {
+ facets
+ .get(&hit.id)
+ .is_some_and(|(hit_kind, hit_tier)| keeps(hit_kind, hit_tier))
+ });
+ }
+ truncated = ranked.len() > limit;
+ for (position, (hit, details)) in ranked.into_iter().take(limit) {
let path = hit.path.as_str().to_owned();
hits.push(SearchHit {
href: page_href(workspace, project, &path),
@@ -175,7 +236,7 @@ pub(crate) async fn handler(
let started = explain.then(std::time::Instant::now);
let raw = match state
.reader
- .search_pages_with_meta(query.clone(), limit + 1, None, viewer)
+ .search_pages_with_meta(query.clone(), fetch_limit(limit), None, viewer)
.await
{
Ok(raw) => raw,
@@ -188,6 +249,10 @@ pub(crate) async fn handler(
});
streams_active = vec!["fts"];
}
+ let raw: Vec<_> = raw
+ .into_iter()
+ .filter(|h| keeps(&h.kind, &h.tier))
+ .collect();
truncated = raw.len() > limit;
for h in raw.into_iter().take(limit) {
let path = h.path.as_str().to_owned();
@@ -237,6 +302,8 @@ pub(crate) async fn handler(
})
.collect();
let hit_count = hits.len();
+ let kind_options = filter_options(&KINDS, kind.as_deref());
+ let tier_options = filter_options(&TIERS, tier.as_deref());
let global_href = format!("search?q={}", encode_segment(&query));
let view = SearchView {
global_href,
@@ -245,6 +312,9 @@ pub(crate) async fn handler(
query,
hits,
hit_count,
+ filtered,
+ kind_options,
+ tier_options,
workspace,
project,
explain,
@@ -267,6 +337,22 @@ pub(crate) async fn handler(
}
}
+/// The options of one filter select, with the current value marked. A value
+/// outside `known` (a custom frontmatter kind) is kept so the form round-trips.
+fn filter_options(known: &[&str], current: Option<&str>) -> Vec<FilterOption> {
+ let mut values: Vec<&str> = known.to_vec();
+ if let Some(current) = current.filter(|c| !known.contains(c)) {
+ values.push(current);
+ }
+ values
+ .into_iter()
+ .map(|value| FilterOption {
+ value: value.to_owned(),
+ selected: current == Some(value),
+ })
+ .collect()
+}
+
fn dash() -> String {
"—".to_owned()
}
diff --git a/crates/ai-memory-web/src/templates.rs b/crates/ai-memory-web/src/templates.rs
index 86792798..a3ce8613 100644
--- a/crates/ai-memory-web/src/templates.rs
+++ b/crates/ai-memory-web/src/templates.rs
@@ -626,6 +626,14 @@ pub(crate) struct TimingRow {
pub ms: String,
}
+/// One option of the search page's kind or tier filter.
+pub(crate) struct FilterOption {
+ /// The value the select submits and shows.
+ pub value: String,
+ /// The current search filters on this value.
+ pub selected: bool,
+}
+
/// One project in the search page's "Search in" selector.
pub(crate) struct ScopeOption {
/// `workspace/project`, the value the selector submits.
@@ -678,6 +686,12 @@ pub(crate) struct SearchView {
pub scope_groups: Vec<ScopeGroup>,
/// Link to the scoped project, for the breadcrumb.
pub project_href: String,
+ /// A kind or tier filter narrowed the hits.
+ pub filtered: bool,
+ /// Kinds the filter offers.
+ pub kind_options: Vec<FilterOption>,
+ /// Tiers the filter offers.
+ pub tier_options: Vec<FilterOption>,
}
impl SearchView {
diff --git a/crates/ai-memory-web/templates/search.html b/crates/ai-memory-web/templates/search.html
index 329336aa..667c153d 100644
--- a/crates/ai-memory-web/templates/search.html
+++ b/crates/ai-memory-web/templates/search.html
@@ -47,6 +47,28 @@
</optgroup>
{% endfor %}
</select>
+ <label for="search-kind" class="sr-only">Kind</label>
+ <select
+ id="search-kind"
+ name="kind"
+ class="rounded-md border border-slate-300 dark:border-slate-700 bg-white dark:bg-slate-900 px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-blue-500"
+ >
+ <option value="">Any kind</option>
+ {% for option in kind_options %}
+ <option value="{{ option.value }}"{% if option.selected %} selected{% endif %}>{{ option.value }}</option>
+ {% endfor %}
+ </select>
+ <label for="search-tier" class="sr-only">Tier</label>
+ <select
+ id="search-tier"
+ name="tier"
+ class="rounded-md border border-slate-300 dark:border-slate-700 bg-white dark:bg-slate-900 px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-blue-500"
+ >
+ <option value="">Any tier</option>
+ {% for option in tier_options %}
+ <option value="{{ option.value }}"{% if option.selected %} selected{% endif %}>{{ option.value }}</option>
+ {% endfor %}
+ </select>
<label for="search-q" class="sr-only">Search pages</label>
<input
id="search-q"
@@ -90,7 +112,7 @@
{% if query == "" %}
<p class="text-sm text-slate-500 dark:text-slate-400">Enter a search term above.</p>
{% else if hits.is_empty() %}
-<p class="text-sm text-slate-500 dark:text-slate-400">No results for <strong>{{ query }}</strong>.
+<p class="text-sm text-slate-500 dark:text-slate-400">No results for <strong>{{ query }}</strong>{% if filtered %} with these filters{% endif %}.
{% if self.scoped() %}
<a href="{{ global_href }}" class="ml-2 inline-block rounded-md border border-slate-300 dark:border-slate-700 px-3 py-1 text-slate-700 dark:text-slate-300 hover:bg-slate-50 dark:hover:bg-slate-900">Search all projects</a>
{% endif %}
diff --git a/crates/ai-memory-web/tests/suite/recall_trace.rs b/crates/ai-memory-web/tests/suite/recall_trace.rs
index e008ebce..ec0990e3 100644
--- a/crates/ai-memory-web/tests/suite/recall_trace.rs
+++ b/crates/ai-memory-web/tests/suite/recall_trace.rs
@@ -526,3 +526,151 @@ async fn project_search_shows_observation_excerpts_only_to_the_sessions_owner()
assert!(body.contains("plutonium"), "{uri}: owner's excerpt: {body}");
}
}
+
+/// A procedural `procedures/rotate.md` in `alpha`, matching the same query as
+/// the fixture's `fact`/`semantic` pages.
+async fn add_procedure(f: &Fixture) {
+ let ws = f
+ .store
+ .writer
+ .get_or_create_workspace("default")
+ .await
+ .unwrap();
+ f.wiki
+ .write_page(WritePageRequest {
+ frontmatter: serde_json::json!({"kind": "procedure"}),
+ tier: Tier::Procedural,
+ ..req(
+ ws,
+ f.alpha,
+ "procedures/rotate.md",
+ "# Rotate\n\nRun the token rotation script every week.",
+ )
+ })
+ .await
+ .unwrap();
+}
+
+fn hit_paths(body: &str) -> Vec<String> {
+ body.split("data-hit-path=\"")
+ .skip(1)
+ .filter_map(|rest| rest.split('"').next())
+ .map(str::to_owned)
+ .collect()
+}
+
+#[tokio::test]
+async fn search_filters_a_project_by_kind_and_tier_keeping_rank_order() {
+ let f = fixture(false).await;
+ add_procedure(&f).await;
+ let app = web(&f, Recall::default());
+ let base = "/web/search?q=token%20rotation&workspace=default&project=alpha";
+
+ let (status, body) = get(&app, base, None).await;
+ assert_eq!(status, StatusCode::OK, "{body}");
+ let all = hit_paths(&body);
+ assert!(all.contains(&"procedures/rotate.md".to_owned()), "{all:?}");
+ assert!(all.contains(&"notes/rotation.md".to_owned()), "{all:?}");
+
+ let (_, body) = get(&app, &format!("{base}&kind=procedure"), None).await;
+ assert_eq!(hit_paths(&body), ["procedures/rotate.md"], "{body}");
+ let (_, body) = get(&app, &format!("{base}&tier=procedural"), None).await;
+ assert_eq!(hit_paths(&body), ["procedures/rotate.md"], "{body}");
+
+ // The survivors of `kind=fact` are the unfiltered list minus the
+ // procedure, in the same order: the filter runs after ranking.
+ let expected: Vec<_> = all
+ .iter()
+ .filter(|p| *p != "procedures/rotate.md")
+ .cloned()
+ .collect();
+ let (_, body) = get(&app, &format!("{base}&kind=fact&tier=semantic"), None).await;
+ assert_eq!(hit_paths(&body), expected, "{body}");
+
+ // Filters combine with AND, and an empty result says why.
+ let (status, body) = get(&app, &format!("{base}&kind=procedure&tier=semantic"), None).await;
+ assert_eq!(status, StatusCode::OK, "{body}");
+ assert!(hit_paths(&body).is_empty(), "{body}");
+ assert!(body.contains("with these filters"), "{body}");
+
+ // The selects keep the current choice.
+ let (_, body) = get(
+ &app,
+ &format!("{base}&kind=procedure&tier=procedural"),
+ None,
+ )
+ .await;
+ assert!(
+ body.contains(r#"<option value="procedure" selected>"#),
+ "{body}"
+ );
+ assert!(
+ body.contains(r#"<option value="procedural" selected>"#),
+ "{body}"
+ );
+}
+
+#[tokio::test]
+async fn cross_project_search_filters_by_kind_and_rejects_an_unknown_tier() {
+ let f = fixture(false).await;
+ add_procedure(&f).await;
+ let app = web(&f, Recall::default());
+
+ let (_, body) = get(&app, "/web/search?q=token%20rotation&kind=procedure", None).await;
+ assert_eq!(hit_paths(&body), ["procedures/rotate.md"], "{body}");
+ // Control: without the filter beta's page is there too.
+ let (_, body) = get(&app, "/web/search?q=token%20rotation", None).await;
+ assert!(body.contains("notes/beta-rotation.md"), "{body}");
+
+ for uri in [
+ "/web/search?q=token&tier=bogus",
+ "/web/search?q=token&workspace=default&project=alpha&tier=bogus",
+ ] {
+ let (status, _) = get(&app, uri, None).await;
+ assert_eq!(status, StatusCode::BAD_REQUEST, "{uri}");
+ }
+}
+
+/// A filter only narrows: it never reaches a project the viewer may not read.
+#[tokio::test]
+async fn kind_filter_does_not_widen_what_a_viewer_can_read() {
+ let f = fixture(true).await;
+ add_procedure(&f).await;
+ let alice = human(&f.store, "alice").await;
+ let bob = human(&f.store, "bob").await;
+ f.store
+ .writer
+ .grant_memory(alice, f.alpha, GrantLevel::Read, None)
+ .await
+ .unwrap();
+ let app = web(&f, Recall::default());
+
+ for uri in [
+ "/web/search?q=token%20rotation&kind=fact",
+ "/web/search?q=token%20rotation&kind=procedure&tier=procedural",
+ ] {
+ let (status, body) = get(&app, uri, Some(bob)).await;
+ assert_eq!(status, StatusCode::OK, "{body}");
+ assert!(hit_paths(&body).is_empty(), "bob sees hits: {body}");
+ }
+ let (status, body) = get(
+ &app,
+ "/web/search?q=token%20rotation&scope=default/alpha&kind=procedure",
+ Some(bob),
+ )
+ .await;
+ assert_eq!(status, StatusCode::FORBIDDEN, "{body}");
+ assert!(!body.contains("procedures/rotate.md"), "{body}");
+
+ // Controls: alice reads alpha, not beta; an unrestricted viewer reads both.
+ let (_, body) = get(
+ &app,
+ "/web/search?q=token%20rotation&kind=fact",
+ Some(alice),
+ )
+ .await;
+ assert!(body.contains("notes/rotation.md"), "{body}");
+ assert!(!body.contains("notes/beta-rotation.md"), "{body}");
+ let (_, body) = get(&app, "/web/search?q=token%20rotation&kind=fact", None).await;
+ assert!(body.contains("notes/beta-rotation.md"), "{body}");
+}
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index 074bc464..131e4613 100644
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@ -105,7 +105,7 @@ means the boundary is not built yet.
| 14d | `include_related` and the web page's backlinks show and walk only readable projects (#708) | `ai-memory-store/src/reader.rs` `related_walk(.., viewer)` — both the outgoing and incoming hop queries carry `readable_repository_predicate("pg.project_id", viewer)`, the same far-end filter `page_links` and `page_links_preview` apply (the preview's visible totals are counted under it too), so a page in a project the viewer cannot read is neither returned nor expanded; `ai-memory-mcp/src/server.rs` `memory_read_page` passes `viewer_from_parts`, `ai-memory-web/src/routes/page.rs` passes the request's viewer to `page_links_preview`, and the access bump only touches the filtered nodes | `related_walk.rs` `the_walk_hides_and_does_not_cross_projects_the_viewer_cannot_read` (an outgoing and an incoming neighbour in an ungranted restricted project are absent, and so is a granted page reachable only through one; control: a granted restricted project is shown, and no viewer walks the whole graph) — fails with the predicate removed; `ai-memory-web` `tests/suite/routes.rs` `page_backlink_from_an_unreadable_project_is_hidden` (the `/web` page's "Cited by" omits a page in an ungranted restricted project, with no title, path or project name; controls: a reader of both projects and an unrestricted viewer see it) — fails with the page handler passing no viewer to `page_links_preview`; `related_walk.rs` `page_links_preview_caps_in_sql_and_counts_only_readable_neighbours` (back-links from an ungranted restricted project are neither listed nor counted in the total behind "and N more"; control: no viewer counts them all) — fails with the predicate removed; `ai-memory-mcp` `server.rs` `bob_does_not_see_restricted_pages_through_the_related_walk` (an ungranted user's `memory_read_page{include_related}` omits the restricted page; control: no viewer still reaches it) — fails with `memory_read_page` passing `None` instead of `viewer_from_parts` | STRONG |
| 14e | `memory_write_page` session evidence cites only a session of the target project (#708) | `ai-memory-mcp/src/server.rs` `memory_write_page` — a `session_id` is accepted only when `require_session_in_scope` resolves the session (where its observations landed, else its session row, as `Consolidator::session_target` does) to the same `(workspace_id, project_id)` the write grant was checked against; unknown and foreign ids get one refusal, so the error is no existence oracle; `scope: "global"` with a `session_id` is refused; `refuse_pinned_page_overwrite` keeps a write that cites a session off a pinned page; only a write to `sessions/<id>.md` reconciles the session's queued SessionEnd job | `server.rs` `write_page_refuses_a_session_from_another_project` (a foreign and an unknown session refused, no evidence row written, the foreign job still queued; control: the project's own session accepted), `session_evidence_write_leaves_a_pinned_page_alone` (control: the same write without `session_id` edits the page), `session_evidence_on_another_path_leaves_the_job_queued`, `write_page_rejects_a_malformed_or_global_session_id` — each of the scope check, the pinned check and the session-page-only reconcile proven to fail its test when removed | STRONG |
| 14f | Consolidation apply path validates cross-scope wikilinks against the store (#1218) | `ai-memory-consolidate/src/link_guard.rs` `unresolved_cross_scope_links` — every `[[project:path]]` / `[[workspace/project:path]]` / `[[_global:path]]` target in a proposed body is resolved with the no-create `lookup_existing_scope` (never creates a scope) and batch-checked via `reader.rs` `existing_latest_paths`; a missing workspace/project, an ambiguous project name, or a missing target page de-links the wikilink, while a genuine store failure aborts the consolidation before any write. Typed `relations:` frontmatter targets go through the same check, and `prune_relations` drops an unresolved entry (an emptied relation and an emptied map with it). `delink_body` → `ai-memory-wiki/src/markdown.rs` `delink_wikilinks` drops the brackets and keeps the label, skipping code fences and inline code exactly as `extract_links` does. Wired into all three apply paths (`consolidator.rs` single-page and batch, `bootstrap.rs`) after the pinned/foreign-slot/portable guards and before the atomic `Wiki::apply_batch` / `write_page`, so an invented cross-project dependency can no longer be written and flagged by the lint pass later. Same-project `[[target]]` links stay untouched by design (the target may be written later). The probe runs with no viewer, so it reports nothing for a `restricted` project (the global preferences project excepted): a link into one is always de-linked, and whether a link survived says nothing about which paths exist there | `consolidator.rs` `batch_delinks_invented_cross_scope_wikilinks` (invented `[[_global:nope]]`, `[[otherproj:notes/missing.md]]`, `[[ghostproj:x.md]]` de-linked to plain text; controls: a cross-scope link to an existing page and a same-project pending link survive byte-identical; `dangling_cross_project_links` left empty), `single_page_delinks_invented_cross_scope_wikilinks`, `single_page_drops_unresolved_cross_scope_relations` (unresolved `relations:` entries dropped; controls: a live cross-scope and a same-project target stay), `link_guard.rs` `prune_relations_drops_only_unresolved_cross_scope_entries`, `bootstrap.rs` `bootstrap_delinks_invented_cross_scope_wikilinks` — each proven to fail with the guard neutralized; `markdown.rs` `delink_wikilinks_strips_only_listed_cross_scope_links`, `delink_wikilinks_without_label_keeps_the_target_text`, `delink_wikilinks_skips_code_and_leaves_empty_set_untouched`; store `multi_session.rs` `existing_latest_paths_reports_exactly_the_live_paths` (exact live-path set, superseded path still resolves, foreign scope sees nothing), `existing_latest_paths_reports_nothing_for_a_restricted_project` (real and absent paths answer alike while restricted; control: reopened, the page is seen) | STRONG |
-| 14g | Web project search and its recall trace honour `memory_query`'s scope rules (#708) and never describe another project | `ai-memory-web/src/routes/search.rs` resolves `workspace`+`project` through `resolve_read_scope` (`lookup_existing_scope_guarded`, no-create, `ProjectAccess::Read`) before any ranking, and refuses partial scope; scoped `/api/v1/search` keeps `lookup_project` / `resolve_many_existing_scopes_guarded`; `ai-memory-web/src/recall.rs` ranks only the resolved scopes through `ReaderPool::hybrid_search_scopes`, whose streams and graph expansion are bound to each `(workspace_id, project_id)`; a search with no scope stays `search_pages_with_meta(.., viewer)` (readable repositories only) | `ai-memory-web` `tests/suite/recall_trace.rs` — `project_search_refuses_a_restricted_project_without_a_grant` (bob, with no grant, gets 403 from `/web/search` with and without `explain=1` and from scoped `/api/v1/search`, with no path, body text or trace in the response, and a `scopes` POST naming the restricted project next to an open one is refused; alice's grant and an unrestricted viewer are the controls), `project_search_fails_closed_on_unknown_and_partial_scope` (unknown project or workspace 404 with nothing created, partial scope 400), `explain_renders_stream_ranks_rrf_authority_and_timings` (a better-matching page in a sibling project never reaches the hits or the trace), `search_scope_selector_lists_only_readable_projects` (the search page's "Search in" selector lists only projects the viewer may read, and a hand-typed `scope=` for an ungranted project is a 403 that leaks nothing; controls: the granted reader and an unrestricted viewer; passing no viewer to `list_projects_with_stats` in the handler fails it), `routes.rs` `search_page_scope_selector_round_trips_and_rejects_malformed_values` (a malformed `scope` is a 400); `ai-memory-mcp` `tests/suite/web_search_parity.rs` (same top-k order as `memory_query` from `/web` and `/api/v1`, with a deterministic embedder and with none, explain on and off, and merged `scopes`; controls show a web search without the embedder, or the old FTS-only scoped search, would fail it) | STRONG. Bite checks: passing no viewer to `resolve_read_scope` in the search handler, to `lookup_project` or to `resolve_scopes` in the API each fails the restricted-project test; dropping the query vector in `recall.rs` fails the embedder parity tests |
+| 14g | Web project search and its recall trace honour `memory_query`'s scope rules (#708) and never describe another project | `ai-memory-web/src/routes/search.rs` resolves `workspace`+`project` through `resolve_read_scope` (`lookup_existing_scope_guarded`, no-create, `ProjectAccess::Read`) before any ranking, and refuses partial scope; scoped `/api/v1/search` keeps `lookup_project` / `resolve_many_existing_scopes_guarded`; `ai-memory-web/src/recall.rs` ranks only the resolved scopes through `ReaderPool::hybrid_search_scopes`, whose streams and graph expansion are bound to each `(workspace_id, project_id)`; a search with no scope stays `search_pages_with_meta(.., viewer)` (readable repositories only) | `ai-memory-web` `tests/suite/recall_trace.rs` — `project_search_refuses_a_restricted_project_without_a_grant` (bob, with no grant, gets 403 from `/web/search` with and without `explain=1` and from scoped `/api/v1/search`, with no path, body text or trace in the response, and a `scopes` POST naming the restricted project next to an open one is refused; alice's grant and an unrestricted viewer are the controls), `project_search_fails_closed_on_unknown_and_partial_scope` (unknown project or workspace 404 with nothing created, partial scope 400), `explain_renders_stream_ranks_rrf_authority_and_timings` (a better-matching page in a sibling project never reaches the hits or the trace), `search_scope_selector_lists_only_readable_projects` (the search page's "Search in" selector lists only projects the viewer may read, and a hand-typed `scope=` for an ungranted project is a 403 that leaks nothing; controls: the granted reader and an unrestricted viewer; passing no viewer to `list_projects_with_stats` in the handler fails it), `routes.rs` `search_page_scope_selector_round_trips_and_rejects_malformed_values` (a malformed `scope` is a 400); `recall_trace.rs` `kind_filter_does_not_widen_what_a_viewer_can_read` (a `kind`/`tier` filter only narrows: bob gets no hits and a 403 on a scoped search; alice and an unrestricted viewer are the controls), `search_filters_a_project_by_kind_and_tier_keeping_rank_order` (the filter runs after ranking, so survivors keep `memory_query`'s order); `ai-memory-mcp` `tests/suite/web_search_parity.rs` (same top-k order as `memory_query` from `/web` and `/api/v1`, with a deterministic embedder and with none, explain on and off, and merged `scopes`; controls show a web search without the embedder, or the old FTS-only scoped search, would fail it) | STRONG. Bite checks: passing no viewer to `resolve_read_scope` in the search handler, to `lookup_project` or to `resolve_scopes` in the API each fails the restricted-project test; dropping the query vector in `recall.rs` fails the embedder parity tests |
| 15 | Agent-archive restore path confinement, resource bounds, and consistency | `ai-memory-cli/src/commands/restore_agents.rs` stages only bounded regular UTF-8 entries; requires a one-to-one manifest/body/checksum/target mapping; allowlists destinations by scope; rejects symlinked descendants; writes each file atomically and rolls back earlier writes after a later failure. `backup_agents.rs` skips direct and directory-root source symlinks, bounds individual assets, and atomically replaces a private archive only after gzip completion | `backup_agents.rs` `restore_agents_rejects_path_traversal`, `restore_agents_rejects_unauthorized_destination_path`, `restore_agents_verifies_sha256_integrity`, `restore_agents_requires_a_complete_one_to_one_manifest`, `restore_agents_rejects_oversized_entries_from_the_header`, `restore_agents_rejects_a_symlinked_destination_parent`, `backup_agents_does_not_follow_config_or_asset_root_symlinks`, and `failed_backup_leaves_the_previous_archive_intact`; `backup_and_restore_agents_round_trip` is the valid-path control; `restore_agents::tests::rollback_removes_new_files_and_restores_overwrites` covers recovery | STRONG |
| 16 | Relay queue identity, migration, and private filesystem state | `companions/ai-memory-relay/src/queue.rs` `Queue::open_inner` performs read-only identity preflight, rechecks under `IMMEDIATE`, commits schema and metadata together; `configure` checks the presence of user objects and rechecks `identity`/`schema_version` metadata on the same connection before every bounded BUSY/LOCKED retry; `fsguard.rs` checks existing paths and creates owner-only files before SQLite opens them | `tests/relay.rs` `a_foreign_database_is_refused_byte_for_byte`, `unknown_schemas_refuse_without_mutation`, `a_foreign_database_with_a_writer_is_refused_before_write_coordination`, `a_foreign_identity_after_preflight_is_refused_without_mutation`, `a_foreign_identity_during_journal_retry_is_refused_without_mutation`, `journal_retry_refuses_a_changed_version_or_empty_database_without_mutation`; controls: `journal_transition_retries_sqlite_lock_without_losing_v1_values`, `fresh_queue_init_and_v1_reopens_work_across_processes`; recovery: `interrupted_and_failed_migrations_roll_back_and_recover`, `journal_reclassification_busy_preserves_committed_migration_and_retries_same_queue`; diagnostics: `classification_read_failures_display_the_sqlite_cause_once_and_preserve_foreign_bytes`; Unix privacy: `the_queue_database_and_its_sidecars_are_owner_only` and the contended migration control | Guard-removal proof covers preflight, locked recheck, and journal retry identity/version checks; full table structure is outside this classification. Windows path rejection is preserved; Windows ACL hardening remains operator-owned |
diff --git a/docs/usage.md b/docs/usage.md
index edab69a1..1b08b377 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -545,7 +545,8 @@ breadcrumbs, rendered markdown, metadata, and search. On a project, page,
namespace, history or session view the header search box searches that project;
elsewhere it searches every project with FTS5, like
`memory_query(global=true)`, and the search page's "Search in" selector picks
-a project. A page shows an outline of its headings, the pages that cite it and
+a project, and its "Kind" and "Tier" selects (`kind=` and `tier=`) keep only
+the pages of that kind or tier. A page shows an outline of its headings, the pages that cite it and
the pages it cites; a folder's namespace listing sorts by recent update or by
title and shows 25 pages at a time. The search on a project page ranks with
the same hybrid ranker as `memory_query` for that project, and its "Explain