Skip to content

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

Rust

docs: list the compaction recap boundary and say what a reload writes

Giovanni Coutinhoc68e39a5a5fb
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 56f9eb83..47deab33 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -466,7 +466,7 @@ and [0.x](docs/changelog/0.x.md).
captured observations. Claude Code and Codex receive it with that prompt
through `UserPromptSubmit` `additionalContext`, OpenCode V1/V2 through the
plugin's system/context hook, and Grok Build on the next `PostToolUse`.
- Nothing is written, so a reload never consumes a baton (#NNN).
+ Serving the recap writes nothing, so a reload never consumes a baton (#NNN).
### Changed
- Documented the 2.x to 3.0 upgrade in `docs/upgrading-to-3.0.md`: what
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index 4ec56625..992223bb 100644
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@ -47,6 +47,7 @@ means the boundary is not built yet.
| 4f | Finalize-on-exit closes only a session the run provably owns (invariant #16) | `ai-memory-cli/src/commands/run.rs` `finalize_hookless_session` runs only for `harness.lacks_session_end_hook()` harnesses (Command Code, Kiro v2/v3, Antigravity); `own_native_session` returns a session only when it is named, chosen before the spawn, or linked under this run's own id in this checkout — a merely *discovered* native session (possibly a concurrent launch's) is never finalized | `run.rs` `a_session_linked_during_the_run_wins_over_discovery` — `own_native_session` returns `None` for the unlinked and other-checkout (`nested`) cases, so a foreign/concurrent session is refused; the named/linked control is finalized (#944) | STRONG |
| 4g | `memory_handoff_accept` `status` never points a caller at another session's baton | `ai-memory-store/src/reader.rs` `handoff_claimed_by_live_session` — the caller-supplied session id (header or native `_meta`, routing-only per row 6b) selects which claim to check, but the answer is bounded by the resolved `(workspace_id, project_id)`, the authenticated `handoff_owner_sql` owner filter, `state='accepted'`, and a still-open receiving session; `ai-memory-mcp/src/server.rs` `unclaimed_handoff` reports `consumed_by_hook` only on that match (and, for a requested `handoff_id`, only when it is the matched row), `none_pending` otherwise | `handoff_ownership.rs` `a_session_start_claim_is_confirmed_only_to_its_own_live_session` (forged session id under another operator, unattributed reader, foreign project, sibling session and ended session all empty; owner and root controls see the claim); `ai-memory-mcp` `tests/suite/handoff_identity.rs` `consumed_by_hook_is_reported_only_to_the_session_that_claimed_it` (over the production transport: a colleague forwarding the session id, the owner from another session, and a request with no session id all get `none_pending`; the claiming session gets `consumed_by_hook`) | STRONG |
| 4h | Offer-mode SessionStart never consumes or injects handoff-controlled text | `ai-memory-hooks/src/router.rs` `fetch_and_accept_handoff_at` branches on the startup configuration before admission/claim and `render_handoff_notice` emits only typed metadata (`HandoffId`, `AgentKind`, computed age); the normal writer CAS remains the only later claim path | `router.rs` `handoff_notice_is_metadata_only_and_never_carries_the_summary` plants hostile summary/questions/steps/files; `offer_mode_leaves_the_baton_open_and_notice_omits_the_summary` exercises the production hook route, asserts the row remains open, then proves the legitimate exact-id writer claim still consumes it (#1030) | STRONG |
+| 4i | The compaction recap reads one session's own captured text and never writes or claims | `ai-memory-hooks/src/recap.rs` `handle_recap`/`build_recap` — anchored on the session row (`session_project_ids`), then `grants::authorize_resolved(.., ProjectAccess::Read)` on that project and `session_summary_scoped` with the `/handoff` owner filter (`User(key)` or `Unattributed`), so another operator's session answers like an unknown id; open handoffs are read with `list_handoffs` under the same owner filter and never claimed; nothing is written (no claim, active-project publish, observation, or page); stored text is rendered inside the untrusted-history fence with its markers escaped (`escape_untrusted_history_markers`) | `recap.rs` `recap_returns_the_window_and_writes_nothing` (the handoff stays open and the session's row count is unchanged), `another_operator_cannot_read_an_owned_session` (owner control: `owner_reads_own_session`), `db_user_without_grant_on_restricted_project_gets_403` (no prompt text in the body), `recap_for_unknown_session_is_a_notice`, `fence_markers_in_stored_text_are_escaped` | STRONG |
| 5a | Pages shared: `author_id` is never a read filter (invariant #16) | `ai-memory-store/src/reader.rs` `search_pages`/`page_body_by_ids` — `author_id` is an attribution JOIN only, never a WHERE term; `observation_stream_votes` lets every session vote whatever its owner (the owner filter only withholds the observation excerpt and ids, never the vote or the page) | `multi_session.rs` — a page with a **non-null** `author_id` (operator A) is readable by operator B in the same project; `multi_session.rs` `another_operators_observations_lift_their_session_page_in_a_shared_project` (operator B's owned session, authored page and observations lift that page for operator A's query); `ai-memory-mcp` `server.rs` `observation_stream_evidence_stays_inside_a_restricted_project` (a second operator with only a read grant gets the session page lifted by the first operator's observation); `multi_session.rs` `observation_excerpts_follow_the_session_owner_while_the_vote_stays_shared` (B still gets A's session page ranked by A's observation, with the page's own snippet) | STRONG |
| 5b | Page supersession (loser stays reachable) | `ai-memory-store/src/ops.rs` `upsert_page_in_tx` — demote `is_latest=0` (never delete) + `supersedes` chain; read side: `reader.rs` `page_versions` lists every row at the path, with no `is_latest` filter, for `/web/w/…/h/*path` and `/api/v1/…/history/*path`. It does apply TTL expiry (`reader.rs` `history_visible`): a version whose own `expires_at` passed is neither listed nor readable by id, a path whose live version expired shows no history at all (the forget sweep hard-deletes every row there), and a `supersedes` link to a hidden version reads as `null`. Expiry is the only thing that hides a superseded version; a concurrent write never does | `multi_session.rs` `concurrent_writes_to_one_path_supersede_rather_than_destroy`; `retrieval_superseded.rs`; `multi_session.rs` `page_history_keeps_the_overwritten_version_and_stays_in_scope`; `ai-memory-web` `history_replay.rs` `history_keeps_both_sides_of_a_concurrent_divergent_write` (two attributed writers on one base: all three versions and both authors listed, one `is_latest`, the two writers' versions diff by id) and `history_lists_k_plus_one_versions_newest_first_and_diffs_the_latest`; bite: an `is_latest = 1` filter in `page_versions` fails both; `history_hides_expired_versions_and_expired_pages` (an expired superseded version and every version of a page whose live version expired answer 404 by path and by id on HTML and JSON, and the live successor's `supersedes` is `null`; control: a TTL in the future is listed and diffable; bites with the per-row predicate removed, with the live-version clause disabled, and with the `supersedes` hiding removed) | STRONG |
| 5c | Watcher reindex and Wiki writes share per-page serialization (invariant #16) | `ai-memory-wiki/src/wiki.rs` `reindex_page` takes `mutation_lock.read` before `reindex_page_locked` takes `lock_page`, covering disk read through the single-writer upsert; callers already holding the exclusive global guard do not reacquire it. `write_page` uses the same page mutex and `apply_batch` retains sorted, deduplicated locks; embedding runs after both guards are released | `wiki.rs` `reindex_page_lock_waits_before_reading_and_allows_another_path` (transient snapshot refused while locked, another path progresses, release indexes the committed bytes without rewriting disk), `reindex_page_lock_serializes_write_through_the_upsert` and `reindex_page_lock_and_reversed_duplicate_batches_do_not_deadlock` (real concurrent operations, final disk/SQL winner and supersession ancestry preserved); all three fail with the reindex page guard removed. `reindex_page_lock_releases_both_guards_before_embedding` checks both body and abstract embedding; `decay_cleanup_reindex_does_not_embed_under_the_exclusive_lock` covers the exclusive caller | STRONG for a shared Wiki handle and its clones. External editors and independently constructed Wiki handles do not participate in these locks |
diff --git a/docs/usage.md b/docs/usage.md
index b73e5b07..d2a286e5 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -176,8 +176,9 @@ and the one before it (or the session start):
- the project's open handoffs, listed and never claimed, this session's own
first.
-The rest of the prompt runs as usual with the recap in context. Nothing is
-written: no handoff is claimed, no observation or page is added.
+The rest of the prompt runs as usual with the recap in context. Serving the
+recap writes nothing: no handoff is claimed and no page or extra observation
+is added (the prompt itself is captured like any other).
| Harness | When the agent sees the recap |
|---|---|