Skip to content

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

Rust

fix(consolidate): drop unresolved cross-scope relations before the write

AkitaOnRails6c7c3698cd65
diff --git a/CHANGELOG.md b/CHANGELOG.md
index da2b0a2d..e7688ecb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -51,7 +51,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
wikilinks when a model ignored the #1207 prompt wording. The single-page,
batch and bootstrap apply paths now resolve every cross-scope wikilink
target against the store with no-create lookups before the write and
- rewrite an unresolvable one to its plain label text, so a missing target
+ rewrite an unresolvable one to its plain label text (an unresolvable
+ `relations:` frontmatter entry is dropped), so a missing target
can no longer mint the dangling cross-project edge that `ai-memory lint`
reports as `broken_link`. Resolved cross-scope links survive
byte-identical, and same-project pending links stay untouched by design.
diff --git a/crates/ai-memory-consolidate/src/bootstrap.rs b/crates/ai-memory-consolidate/src/bootstrap.rs
index 826ae8de..09ab6204 100644
--- a/crates/ai-memory-consolidate/src/bootstrap.rs
+++ b/crates/ai-memory-consolidate/src/bootstrap.rs
@@ -649,11 +649,11 @@ impl Bootstrap {
// bootstrap page cannot mint a dangling cross-project edge either.
// In-memory rewrite only; `apply_batch` stays the single atomic write.
let unresolved = {
- let bodies: Vec<(&PagePath, &str)> = requests
+ let pages: Vec<(&PagePath, &str, &serde_json::Value)> = requests
.iter()
- .map(|req| (&req.path, req.body.as_str()))
+ .map(|req| (&req.path, req.body.as_str(), &req.frontmatter))
.collect();
- crate::link_guard::unresolved_cross_scope_links(&self.reader, cfg.workspace_id, &bodies)
+ crate::link_guard::unresolved_cross_scope_links(&self.reader, cfg.workspace_id, &pages)
.await?
};
if !unresolved.is_empty() {
diff --git a/crates/ai-memory-consolidate/src/consolidator.rs b/crates/ai-memory-consolidate/src/consolidator.rs
index 0d5d4ecc..25f64de3 100644
--- a/crates/ai-memory-consolidate/src/consolidator.rs
+++ b/crates/ai-memory-consolidate/src/consolidator.rs
@@ -325,20 +325,21 @@ impl Consolidator {
page.title = new_title;
}
- // #1218: a cross-scope wikilink the model invented must not be
- // written — resolve each against the store and de-link the ones that
- // do not land on an existing page, so the write cannot mint a
- // dangling cross-project edge the lint pass would flag.
+ // #1218: a cross-scope link the model invented — body wikilink or
+ // `relations:` entry — must not be written. Resolve each against the
+ // store; de-link unresolved body links and drop unresolved relations,
+ // so the write cannot mint a dangling cross-project edge the lint
+ // pass would flag.
+ let mut frontmatter = build_frontmatter(&page, session_id, agent_kind);
let unresolved = crate::link_guard::unresolved_cross_scope_links(
&self.reader,
ws,
- &[(&path, page.body_markdown.as_str())],
+ &[(&path, page.body_markdown.as_str(), &frontmatter)],
)
.await?;
page.body_markdown =
crate::link_guard::delink_body(&page.body_markdown, &path, &unresolved).into_owned();
-
- let frontmatter = build_frontmatter(&page, session_id, agent_kind);
+ crate::link_guard::prune_relations(&mut frontmatter, &unresolved);
let id = self
.wiki
.write_page(WritePageRequest {
@@ -831,11 +832,11 @@ impl Consolidator {
// De-linking rewrites in memory only; `apply_batch` below stays the
// single atomic write.
let unresolved = {
- let bodies: Vec<(&PagePath, &str)> = requests
+ let pages: Vec<(&PagePath, &str, &serde_json::Value)> = requests
.iter()
- .map(|req| (&req.path, req.body.as_str()))
+ .map(|req| (&req.path, req.body.as_str(), &req.frontmatter))
.collect();
- crate::link_guard::unresolved_cross_scope_links(&self.reader, ws, &bodies).await?
+ crate::link_guard::unresolved_cross_scope_links(&self.reader, ws, &pages).await?
};
if !unresolved.is_empty() {
for (req, outcome) in requests.iter_mut().zip(outcomes_preview.iter_mut()) {
@@ -843,6 +844,7 @@ impl Consolidator {
crate::link_guard::delink_body(&req.body, &req.path, &unresolved).into_owned();
req.body = rewritten.clone();
outcome.new_body_markdown = rewritten;
+ crate::link_guard::prune_relations(&mut req.frontmatter, &unresolved);
}
}
@@ -5874,4 +5876,53 @@ mod tests {
assert!(stored.body.contains("[[otherproj:notes/exists.md]]"));
assert!(stored.body.contains("[[notes/pending.md]]"));
}
+
+ /// #1218 covers typed `relations:` edges too: an unresolved cross-scope
+ /// relation target is dropped before the write (an emptied relation goes
+ /// with it), while a live cross-scope target and a same-project target
+ /// stay, so frontmatter cannot mint the dangling edge the body guard
+ /// prevents.
+ #[tokio::test]
+ async fn single_page_drops_unresolved_cross_scope_relations() {
+ let tmp = tempfile::tempdir().unwrap();
+ let (store, wiki, session, ws, proj) = batch_fixture(tmp.path()).await;
+ seed_other_project_page(&store, &wiki, ws, "otherproj", "notes/exists.md").await;
+
+ let response = serde_json::json!({
+ "title": "Relation cleanup",
+ "body_markdown": "No links in the body.",
+ "tags": [],
+ "relations": {
+ "causes": ["otherproj:notes/missing.md", "otherproj:notes/exists.md", "notes/local.md"],
+ "fixes": ["ghostproj:x.md"],
+ },
+ });
+ Consolidator::new(
+ store.reader.clone(),
+ store.writer.clone(),
+ wiki.clone(),
+ Arc::new(ScriptedLlm(response)),
+ ws,
+ proj,
+ )
+ .consolidate_session(
+ session,
+ false,
+ ai_memory_core::ActorContext::anonymous(),
+ None,
+ None,
+ )
+ .await
+ .unwrap();
+
+ let path = PagePath::new(format!("sessions/{session}.md")).unwrap();
+ let stored = wiki.read_page(ws, proj, &path).unwrap();
+ assert_eq!(
+ stored.frontmatter["relations"]["causes"],
+ serde_json::json!(["otherproj:notes/exists.md", "notes/local.md"]),
+ "{}",
+ stored.frontmatter
+ );
+ assert!(stored.frontmatter["relations"].get("fixes").is_none());
+ }
}
diff --git a/crates/ai-memory-consolidate/src/link_guard.rs b/crates/ai-memory-consolidate/src/link_guard.rs
index 41102f86..8eb6bd58 100644
--- a/crates/ai-memory-consolidate/src/link_guard.rs
+++ b/crates/ai-memory-consolidate/src/link_guard.rs
@@ -25,8 +25,9 @@ use tracing::warn;
/// module handles.
pub(crate) type LinkKey = (Option<String>, Option<String>, String);
-/// Collect the cross-scope wikilink targets across `bodies` that do NOT
-/// resolve to an existing latest page in the store.
+/// Collect the cross-scope link targets across `pages` — body wikilinks and
+/// typed `relations:` frontmatter entries — that do NOT resolve to an
+/// existing latest page in the store.
///
/// Lookups are no-create and batched: each named scope is resolved once via
/// [`lookup_existing_scope`], then every path under it is checked in a
@@ -42,11 +43,14 @@ pub(crate) type LinkKey = (Option<String>, Option<String>, String);
pub(crate) async fn unresolved_cross_scope_links(
reader: &ReaderPool,
source_workspace_id: WorkspaceId,
- bodies: &[(&PagePath, &str)],
+ pages: &[(&PagePath, &str, &serde_json::Value)],
) -> Result<BTreeSet<LinkKey>, ScopeResolutionError> {
let mut targets: BTreeSet<LinkKey> = BTreeSet::new();
- for (page_path, body) in bodies {
- for link in ai_memory_wiki::extract_links(body, page_path) {
+ for (page_path, body, frontmatter) in pages {
+ let links = ai_memory_wiki::extract_links(body, page_path)
+ .into_iter()
+ .chain(ai_memory_wiki::extract_relation_links(frontmatter));
+ for link in links {
if link.project.is_some() {
targets.insert((link.workspace, link.project, link.path.as_str().to_string()));
}
@@ -125,3 +129,86 @@ pub(crate) fn delink_body<'a>(
body, page_path, unresolved,
))
}
+
+/// Drop every `relations:` entry whose target is in `unresolved`, then any
+/// relation left empty, then an empty `relations` map. Entries are matched
+/// through [`ai_memory_wiki::extract_relation_links`], so a target is keyed
+/// exactly as the write boundary will parse it.
+pub(crate) fn prune_relations(frontmatter: &mut serde_json::Value, unresolved: &BTreeSet<LinkKey>) {
+ if unresolved.is_empty() {
+ return;
+ }
+ let Some(relations) = frontmatter
+ .get_mut("relations")
+ .and_then(serde_json::Value::as_object_mut)
+ else {
+ return;
+ };
+ for (relation, targets) in relations.iter_mut() {
+ let Some(list) = targets.as_array_mut() else {
+ continue;
+ };
+ list.retain(|entry| {
+ let probe = serde_json::json!({ "relations": { relation.as_str(): [entry] } });
+ ai_memory_wiki::extract_relation_links(&probe)
+ .into_iter()
+ .all(|link| {
+ !unresolved.contains(&(
+ link.workspace,
+ link.project,
+ link.path.as_str().to_string(),
+ ))
+ })
+ });
+ }
+ relations.retain(|_, targets| targets.as_array().is_none_or(|list| !list.is_empty()));
+ if relations.is_empty()
+ && let Some(map) = frontmatter.as_object_mut()
+ {
+ map.remove("relations");
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn key(project: &str, path: &str) -> LinkKey {
+ (None, Some(project.to_string()), path.to_string())
+ }
+
+ #[test]
+ fn prune_relations_drops_only_unresolved_cross_scope_entries() {
+ let mut fm = serde_json::json!({
+ "title": "t",
+ "relations": {
+ "causes": ["ghost:notes/missing.md", "billing:notes/live.md", "local/page.md"],
+ "fixes": ["ghost:other"],
+ },
+ });
+ prune_relations(
+ &mut fm,
+ &BTreeSet::from([key("ghost", "notes/missing.md"), key("ghost", "other.md")]),
+ );
+ assert_eq!(
+ fm["relations"]["causes"],
+ serde_json::json!(["billing:notes/live.md", "local/page.md"])
+ );
+ assert!(
+ fm["relations"].get("fixes").is_none(),
+ "an emptied relation is removed"
+ );
+ }
+
+ #[test]
+ fn prune_relations_removes_an_emptied_map_and_ignores_an_empty_set() {
+ let original = serde_json::json!({ "relations": { "causes": ["ghost:x.md"] } });
+ let mut untouched = original.clone();
+ prune_relations(&mut untouched, &BTreeSet::new());
+ assert_eq!(untouched, original);
+
+ let mut fm = original;
+ prune_relations(&mut fm, &BTreeSet::from([key("ghost", "x.md")]));
+ assert!(fm.get("relations").is_none());
+ }
+}
diff --git a/crates/ai-memory-wiki/src/lib.rs b/crates/ai-memory-wiki/src/lib.rs
index bd0ef325..81b83cc7 100644
--- a/crates/ai-memory-wiki/src/lib.rs
+++ b/crates/ai-memory-wiki/src/lib.rs
@@ -27,7 +27,8 @@ pub use error::{WikiError, WikiResult};
pub use git::{COMMIT_AUTHOR_EMAIL, COMMIT_AUTHOR_NAME, GitAdapter};
pub use ledger::is_rotated_event_ledger;
pub use markdown::{
- Markdown, delink_wikilinks, derive_title, emit, extract_links, parse, rewrite_local_wikilinks,
+ Markdown, delink_wikilinks, derive_title, emit, extract_links, extract_relation_links, parse,
+ rewrite_local_wikilinks,
};
pub use migrations::run_pending as run_wiki_migrations;
pub use watcher::{DEBOUNCE_WINDOW, RECONCILE_INTERVAL, WatcherHandle};
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index b3659b4c..b84b502a 100644
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@ -90,7 +90,7 @@ means the boundary is not built yet.
| 14c | Client-supplied event time is bounded and self-scoped (#919) | `ai-memory-hooks/src/payload.rs` `HookEnvelope::occurred_at_micros` — a `/hook` caller's optional `occurred_at` must be `> 0` and `<= now + 5min`; it only sets the caller's *own* admitted session's `started_at`/`ended_at`/`created_at`, never another session/project/user, and the ingest dedup `seen_at`/TTL stays on `now` | `payload.rs` `occurred_at_micros_rejects_a_far_future_timestamp`, `…_rejects_non_positive_values`, `…_rejects_garbage_strings` | MEDIUM — self-scoped numeric bound; no cross-tenant surface (a client already controls its own content) |
| 14d | `include_related` shows and walks 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` applies, 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`, 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-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. `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`, `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 |
+| 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 |
| 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 |