Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(mcp): make global scope hits directly readable (#1802)
AkitaOnRailsff16dfa765c1
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c277f2a3..2180a1ed 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -13,6 +13,11 @@ version in [`docs/changelog/`](docs/changelog/):### Added+- `global_scope_hits` now include their workspace, project, and global scope,+ and `memory_read_page` accepts `scope: "global"`. Supplemental global search+ results can therefore be read directly without risking a same-path lookup in+ the caller's active project (#1802).+- Added `--project-id` to managed launches and checkout-local discovery torecover populated legacy name collisions without moving or merging history.An interactive launch offers authorized project choices and remembers thediff --git a/companions/ai-memory-ts/docs/arguments.md b/companions/ai-memory-ts/docs/arguments.mdindex a97a5842..f8ef7037 100644--- a/companions/ai-memory-ts/docs/arguments.md+++ b/companions/ai-memory-ts/docs/arguments.md@@ -48,6 +48,7 @@ Methods: `pages.read`, `pages.update`|---|---|| `workspace` | `workspace` || `project` | `project` |+| `scope` | `scope` || `path` | `path` || `query` | `query` || `include_related` | `includeRelated` |diff --git a/companions/ai-memory-ts/schema/tools.json b/companions/ai-memory-ts/schema/tools.jsonindex 2f884f8b..0b2f14a0 100644--- a/companions/ai-memory-ts/schema/tools.json+++ b/companions/ai-memory-ts/schema/tools.json@@ -762,6 +762,12 @@"null"]},+ "scope": {+ "type": [+ "null",+ "string"+ ]+ },"workspace": {"type": ["null",diff --git a/companions/ai-memory-ts/src/client.ts b/companions/ai-memory-ts/src/client.tsindex 6e4cb88f..d31a54c3 100644--- a/companions/ai-memory-ts/src/client.ts+++ b/companions/ai-memory-ts/src/client.ts@@ -291,7 +291,10 @@ export class PagesNamespace {async read(args: ReadPageArgs, options?: CallOptions): Promise<Page> {const where = "pages.read";const a = argsObject(args, where);- const scope = this.#core.scope(a.scope, where);+ if (a.global === true && a.scope !== undefined) {+ throw new ArgumentError(`${where}: global cannot be combined with scope`);+ }+ const scope = a.global === true ? undefined : this.#core.scope(a.scope, where);const hasPath = a.path !== undefined;const hasQuery = a.query !== undefined;if (hasPath === hasQuery) {@@ -302,7 +305,7 @@ export class PagesNamespace {const decoded = await this.#core.invoke("memory_read_page",wire({- ...scopeWire(scope),+ ...(scope === undefined ? { scope: "global" } : scopeWire(scope)),path: a.path,query: a.query,include_related: a.includeRelated === true ? true : undefined,diff --git a/companions/ai-memory-ts/src/coverage.ts b/companions/ai-memory-ts/src/coverage.tsindex faae477c..7c30c45d 100644--- a/companions/ai-memory-ts/src/coverage.ts+++ b/companions/ai-memory-ts/src/coverage.ts@@ -67,7 +67,7 @@ export const TOOL_COVERAGE: Readonly<Record<string, ToolClassification>> = {status: "wrapped",methods: ["pages.read", "pages.update"],phase: 1,- sends: [...SCOPE, "path", "query", "include_related", "related_depth", "max_chars"],+ sends: [...SCOPE, "scope", "path", "query", "include_related", "related_depth", "max_chars"],},memory_delete_page: {status: "wrapped",diff --git a/companions/ai-memory-ts/src/types.ts b/companions/ai-memory-ts/src/types.tsindex ed7fbba2..2484dc28 100644--- a/companions/ai-memory-ts/src/types.ts+++ b/companions/ai-memory-ts/src/types.ts@@ -168,6 +168,8 @@ export type PatchPageResult = WritePageResult;/** Options shared by both forms of {@link ReadPageArgs}. */export interface ReadPageBase extends ScopedArgs {+ /** Read from the reserved cross-project global scope. Cannot be combined with `scope`. */+ global?: boolean;/** Also walk the link graph and return the reachable pages in `related`. */includeRelated?: boolean;/** Hops to walk with `includeRelated` (default 1, capped at 3 by the server). */diff --git a/companions/ai-memory-ts/test/unit/client.test.ts b/companions/ai-memory-ts/test/unit/client.test.tsindex 3b7cf589..509bbd9a 100644--- a/companions/ai-memory-ts/test/unit/client.test.ts+++ b/companions/ai-memory-ts/test/unit/client.test.ts@@ -161,6 +161,15 @@ describe("pages", () => {});assert.equal(capped.truncated, true);assert.equal(capped.totalChars, 40_000);+ await memory.pages.read({ path: "preferences/style.md", global: true });+ assert.deepEqual(server.lastArgs(), {+ scope: "global",+ path: "preferences/style.md",+ });+ await assert.rejects(+ memory.pages.read({ path: "preferences/style.md", global: true, scope: OTHER }),+ ArgumentError,+ );server.tools.set("memory_read_page", () => payloads.read);const older = await memory.pages.read({ path: "notes/retries.md" });assert.equal(older.truncated, undefined);@@ -690,6 +699,7 @@ describe("wire names", () => {],}),memory.pages.read({ path: "p", includeRelated: true, relatedDepth: 2, maxChars: 500 }),+ memory.pages.read({ path: "global", global: true }),memory.pages.read({ query: "q" }),memory.pages.delete({ path: "p", expectedPageId: "v" }),memory.query({diff --git a/crates/ai-memory-core/src/routing_skills/ai-memory-retrieval/SKILL.md b/crates/ai-memory-core/src/routing_skills/ai-memory-retrieval/SKILL.mdindex 0b9b2add..6868bda9 100644--- a/crates/ai-memory-core/src/routing_skills/ai-memory-retrieval/SKILL.md+++ b/crates/ai-memory-core/src/routing_skills/ai-memory-retrieval/SKILL.md@@ -12,7 +12,7 @@ Use this skill for read-only ai-memory lookups, catch-up, and evaluating remembe- `memory_query` searches the current project's wiki for prior decisions, gotchas, procedures, rules, and session notes.- `memory_recent` lists the most recently updated pages when the user wants a light activity check.-- `memory_read_page` fetches a full page body after a search hit or direct path lookup. The body is capped by `max_chars` (default 12000, max 64000); the response's `truncated`/`total_chars` fields report whether it was cut and its full size. Raise `max_chars` only when you need the whole page. Pass `include_related: true` (optional `related_depth`, default 1, hard cap 3) to also walk the link graph outward and return a `related` array of reachable pages, each with its hop `depth` and edge `direction` (`link`/`backlink`); default off omits it.+- `memory_read_page` fetches a full page body after a search hit or direct path lookup. A `global_scope_hits` result carries its `workspace`, `project`, and `scope`; pass `scope: "global"` to read that reserved scope directly. The body is capped by `max_chars` (default 12000, max 64000); the response's `truncated`/`total_chars` fields report whether it was cut and its full size. Raise `max_chars` only when you need the whole page. Pass `include_related: true` (optional `related_depth`, default 1, hard cap 3) to also walk the link graph outward and return a `related` array of reachable pages, each with its hop `depth` and edge `direction` (`link`/`backlink`); default off omits it.- `memory_read_session_observations` reads one session's raw hook observations (prompts, tool calls, stops) in capture order, paged and body-capped, when the user asks what actually happened in a session or wants to check a compiled page against its evidence. It also continues a session that was cut off without ending: pass the `session_id` a session-start notice, `recent_sessions` or `newer_unended_session` names (a harness's native id, such as an OpenCode `ses_…` id, works too) with `order: "desc"`, and its newest prompts and tool results are where the work stopped.- `memory_status` reports whether ai-memory is healthy and how large the knowledge base is.- `memory_briefing` returns a structured read-only snapshot for agent consumption, including a bounded `pinned` list of the project's pinned standing-context pages (present only when the project has pins) and `recent_sessions`, the sessions with the newest captured work. An entry there with `ended: false` and `handed_off: false` that is not `current` was cut off or is still running; read it before an older handoff or page when the user asks to continue.diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex 4cd1e4a6..783e8060 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -833,6 +833,12 @@ struct QueryHit {hit: ai_memory_store::PageHit,#[serde(skip_serializing_if = "Option::is_none")]score_details: Option<ai_memory_store::SearchExplain>,+ #[serde(skip_serializing_if = "Option::is_none")]+ workspace: Option<String>,+ #[serde(skip_serializing_if = "Option::is_none")]+ project: Option<String>,+ #[serde(skip_serializing_if = "Option::is_none")]+ scope: Option<&'static str>,#[serde(skip)]evidence: Option<ai_memory_store::AnswerEvidenceMeta>,}@@ -842,6 +848,9 @@ impl From<ai_memory_store::PageHit> for QueryHit {Self {hit,score_details: None,+ workspace: None,+ project: None,+ scope: None,evidence: None,}}@@ -1725,6 +1734,10 @@ struct ReadPageArgs {/// both for the current project; static MCP clients must pass both.#[serde(default)]workspace: Option<String>,+ /// Set to `"global"` to read from the reserved cross-project global+ /// scope. Cannot be combined with `workspace` or `project`.+ #[serde(default)]+ scope: Option<String>,/// Opt-in: also walk the link graph outward from this page and return the/// reachable pages in a `related` array. Default false → the response is/// byte-identical to a plain single-page read (no `related` field).@@ -3064,6 +3077,9 @@ impl AiMemoryServer {.map(|(hit, details)| QueryHit {hit,score_details: details,+ workspace: None,+ project: None,+ scope: None,evidence: None,}).collect(),@@ -3250,6 +3266,9 @@ impl AiMemoryServer {.map(|(hit, score_details)| QueryHit {hit,score_details,+ workspace: Some(ai_memory_core::DEFAULT_WORKSPACE_NAME.to_owned()),+ project: Some(ai_memory_core::GLOBAL_SCOPE_PROJECT.to_owned()),+ scope: Some("global"),evidence: None,}).collect()@@ -3300,6 +3319,8 @@ impl AiMemoryServer {.await{Ok(Some(scope)) if scope.as_tuple() != current => {+ let (scope_workspace, scope_project) =+ self.scope_names(scope.workspace_id, scope.project_id).await;let ai_memory_store::HybridSearchOutcome { hits, .. } = self.search_project(scope.workspace_id,@@ -3325,6 +3346,9 @@ impl AiMemoryServer {QueryHit {hit,score_details,+ workspace: Some(scope_workspace.clone()),+ project: Some(scope_project.clone()),+ scope: None,evidence: None,}}));@@ -3342,6 +3366,9 @@ impl AiMemoryServer {.map(|(hit, score_details)| QueryHit {hit,score_details: score_details.filter(|_| explain),+ workspace: None,+ project: None,+ scope: None,evidence: None,}).collect();@@ -5170,6 +5197,8 @@ impl AiMemoryServer {`total_chars` (the untruncated length) so you know the real size \even when it wasn't cut. Raise `max_chars` only when you need the \whole page. \+ Set `scope: \"global\"` to read the reserved cross-project global \+ scope; do not combine it with `workspace`/`project`. \\Set `include_related: true` to also walk the link graph outward from \this page and get a `related` array of the reachable pages, each with \@@ -5194,22 +5223,63 @@ impl AiMemoryServer {// Same scope resolution as memory_query: an explicit workspace+project// can target a page in a DIFFERENT workspace (a sibling project on a// shared server). Plain `project` keeps the active-project chain.- let (ws, proj) = self- .effective_ids_for_read_args_with_actor(- args.workspace.as_deref(),- args.project.as_deref(),- &aps_actor,- Self::viewer_from_parts(Some(&parts)),- )- .await?;+ // The reserved global spelling is a no-create lookup and cannot be+ // mixed with explicit coordinates.+ let requested_scope = args.scope.as_deref().map(str::trim);+ let (ws, proj) = match requested_scope {+ None | Some("") => {+ self.effective_ids_for_read_args_with_actor(+ args.workspace.as_deref(),+ args.project.as_deref(),+ &aps_actor,+ Self::viewer_from_parts(Some(&parts)),+ )+ .await?+ }+ Some("global") => {+ if args+ .workspace+ .as_deref()+ .is_some_and(|s| !s.trim().is_empty())+ || args+ .project+ .as_deref()+ .is_some_and(|s| !s.trim().is_empty())+ {+ return Err(McpError::invalid_params(+ "scope: \"global\" cannot be combined with workspace/project",+ None,+ ));+ }+ ai_memory_store::lookup_global_scope(&self.reader)+ .await+ .map_err(Self::scope_error)?+ .ok_or_else(|| {+ Self::scope_error(+ ai_memory_store::ScopeResolutionError::ProjectNotFoundInWorkspace {+ workspace: ai_memory_core::DEFAULT_WORKSPACE_NAME.to_owned(),+ project: ai_memory_core::GLOBAL_SCOPE_PROJECT.to_owned(),+ },+ )+ })?+ .as_tuple()+ }+ Some(other) => {+ return Err(McpError::invalid_params(+ format!("unknown scope '{other}': the only supported value is \"global\""),+ None,+ ));+ }+ };// Diagnose cross-project scope-bleed: a read with no explicit scope// resolves to the active project, which may differ from the scope a// concurrent write landed in — the write persists but the by-path// read looks in the wrong bucket and 404s.- let auto_scoped = args- .workspace- .as_deref()- .is_none_or(|s| s.trim().is_empty())+ let auto_scoped = requested_scope.is_none_or(str::is_empty)+ && args+ .workspace+ .as_deref()+ .is_none_or(|s| s.trim().is_empty())&& args.project.as_deref().is_none_or(|s| s.trim().is_empty());let max_chars = args.max_chars@@ -13140,6 +13210,10 @@ mod tests {"default query must union the reserved global scope: {}",text.text);+ let payload: serde_json::Value = serde_json::from_str(&text.text).unwrap();+ assert_eq!(payload["global_scope_hits"][0]["workspace"], "default");+ assert_eq!(payload["global_scope_hits"][0]["project"], "_global");+ assert_eq!(payload["global_scope_hits"][0]["scope"], "global");assert!(!text.text.contains("score_details") && !text.text.contains("streams_active"),"ordinary default queries must preserve the old response shape"@@ -15363,6 +15437,7 @@ mod tests {path: None,project: None,workspace: None,+ scope: None,include_related: false,related_depth: None,max_chars: None,@@ -15413,6 +15488,7 @@ mod tests {path: None,project: None,workspace: None,+ scope: None,include_related: false,related_depth: None,max_chars: None,@@ -15436,6 +15512,7 @@ mod tests {path: Some(String::new()),project: None,workspace: None,+ scope: None,include_related: false,related_depth: None,}),@@ -15464,6 +15541,7 @@ mod tests {path: Some("notes/blankfill.md".into()),project: None,workspace: None,+ scope: None,include_related: false,related_depth: None,}),@@ -15522,6 +15600,7 @@ mod tests {path: Some("notes/sibling.md".into()),project: Some("docs".into()),workspace: Some("practice".into()),+ scope: None,include_related: false,related_depth: None,max_chars: None,@@ -15578,6 +15657,7 @@ mod tests {path: Some("notes/db-only-tool.md".into()),project: None,workspace: None,+ scope: None,include_related: false,related_depth: None,max_chars: None,@@ -15635,6 +15715,7 @@ mod tests {path: Some("notes/short.md".into()),project: None,workspace: None,+ scope: None,include_related: false,related_depth: None,max_chars: None,@@ -15684,6 +15765,7 @@ mod tests {path: Some("notes/long.md".into()),project: None,workspace: None,+ scope: None,include_related: false,related_depth: None,max_chars: Some(500),@@ -15768,6 +15850,7 @@ mod tests {path: Some(path.into()),project: None,workspace: None,+ scope: None,include_related: false,related_depth: None,}),@@ -15815,6 +15898,7 @@ mod tests {path: Some("notes/does-not-exist.md".into()),project: Some("scratch".into()),workspace: Some("default".into()),+ scope: None,include_related: false,related_depth: None,}),@@ -15836,6 +15920,7 @@ mod tests {path: None,project: Some("scratch".into()),workspace: Some("default".into()),+ scope: None,include_related: false,related_depth: None,}),@@ -15868,6 +15953,7 @@ mod tests {path: Some("blocked.md".into()),project: Some("scratch".into()),workspace: Some("default".into()),+ scope: None,include_related: false,related_depth: None,}),@@ -15897,6 +15983,7 @@ mod tests {path: Some("does-not-exist.md".into()),project: Some("scratch".into()),workspace: Some("default".into()),+ scope: None,include_related: false,related_depth: None,max_chars: None,@@ -15923,6 +16010,7 @@ mod tests {path: Some("does-not-exist.md".into()),project: None,workspace: None,+ scope: None,include_related: false,related_depth: None,max_chars: None,@@ -18818,6 +18906,7 @@ mod tests {query: None,project: None,workspace: None,+ scope: None,include_related: false,related_depth: None,max_chars: None,@@ -19067,6 +19156,7 @@ mod tests {path: Some("../x.md".into()),project: None,workspace: None,+ scope: None,include_related: false,related_depth: None,}),@@ -19344,6 +19434,7 @@ mod tests {query: None,project: None,workspace: None,+ scope: None,}),OptionalParts(parts_as_reader()),)@@ -19393,6 +19484,7 @@ mod tests {query: None,project: None,workspace: None,+ scope: None,}),OptionalParts(test_parts_default()),)@@ -19460,6 +19552,7 @@ mod tests {query: None,project: None,workspace: None,+ scope: None,}),OptionalParts(test_parts_default()),)@@ -19503,6 +19596,7 @@ mod tests {query: None,project: None,workspace: None,+ scope: None,}),OptionalParts(parts_as_reader()),)@@ -19680,6 +19774,74 @@ mod tests {}}+ #[tokio::test]+ async fn global_page_reads_are_explicit_and_preserve_local_collisions() {+ let tmp = TempDir::new().unwrap();+ let (_store, server, _joao, _maria) = global_gate_fixture(&tmp).await;++ let mut local = global_page("notes/collision.md", None, None, None);+ local.body = "# Local\n\nlocal-only marker".into();+ server+ .memory_write_page(Parameters(local), OptionalParts(test_parts_default()))+ .await+ .unwrap();+ server+ .memory_write_page(+ Parameters(global_page(+ "notes/collision.md",+ Some("global"),+ None,+ None,+ )),+ OptionalParts(test_parts_default()),+ )+ .await+ .unwrap();++ let read = |scope: Option<&str>| ReadPageArgs {+ query: None,+ path: Some("notes/collision.md".into()),+ project: None,+ workspace: None,+ scope: scope.map(str::to_owned),+ include_related: false,+ related_depth: None,+ max_chars: None,+ };+ let local = server+ .memory_read_page(Parameters(read(None)), OptionalParts(test_parts_default()))+ .await+ .unwrap();+ let global = server+ .memory_read_page(+ Parameters(read(Some("global"))),+ OptionalParts(test_parts_default()),+ )+ .await+ .unwrap();+ assert!(+ tool_json(&local)["body"]+ .as_str()+ .unwrap()+ .contains("local-only")+ );+ assert!(+ tool_json(&global)["body"]+ .as_str()+ .unwrap()+ .contains("globalverify")+ );++ let mut mixed = read(Some("global"));+ mixed.workspace = Some("default".into());+ mixed.project = Some("_global".into());+ let error = server+ .memory_read_page(Parameters(mixed), OptionalParts(test_parts_default()))+ .await+ .expect_err("global scope and explicit coordinates are mutually exclusive");+ assert!(error.message.contains("cannot be combined"));+ }+/// GHSA-7qj3-7wqw-m5w6: the reserved global scope is unioned into every/// user's reads, so a database user without a write grant on it must not/// write it — through `scope: "global"` or by naming `default/_global` —@@ -19759,6 +19921,7 @@ mod tests {query: None,project: Some("_global".into()),workspace: Some("default".into()),+ scope: None,}),OptionalParts(parts_as_user(maria)),)@@ -20023,6 +20186,7 @@ mod tests {query: None,project: Some(joaos.clone()),workspace: Some("default".into()),+ scope: None,}),OptionalParts(parts_as_user(maria)),)@@ -20540,6 +20704,7 @@ mod tests {query: None,project: None,workspace: None,+ scope: None,}),OptionalParts(parts),)@@ -20671,6 +20836,7 @@ mod tests {query: None,project: None,workspace: None,+ scope: None,}),OptionalParts(parts),)@@ -21393,6 +21559,7 @@ mod tests {path: Some("notes/default.md".into()),project: Some("typo".into()),workspace: None,+ scope: None,include_related: false,related_depth: None,max_chars: None,@@ -21479,6 +21646,7 @@ mod tests {path: Some("notes/temp.md".into()),project: None,workspace: None,+ scope: None,include_related: false,related_depth: None,max_chars: None,@@ -21629,6 +21797,7 @@ mod tests {path: Some("notes/retries.md".into()),project: None,workspace: None,+ scope: None,include_related: false,related_depth: None,}),@@ -21860,6 +22029,7 @@ mod tests {path: Some("notes/keep.md".into()),project: None,workspace: None,+ scope: None,include_related: false,related_depth: None,max_chars: None,@@ -21982,6 +22152,7 @@ mod tests {path: Some("notes/twin.md".into()),project: Some("shared".into()),workspace: Some("alpha".into()),+ scope: None,include_related: false,related_depth: None,max_chars: None,@@ -22002,6 +22173,7 @@ mod tests {path: Some("notes/twin.md".into()),project: Some("shared".into()),workspace: Some("beta".into()),+ scope: None,include_related: false,related_depth: None,max_chars: None,@@ -22827,6 +22999,7 @@ mod tests {path: Some("notes/bob-authored.md".into()),project: None,workspace: None,+ scope: None,include_related: false,related_depth: None,max_chars: None,@@ -25105,6 +25278,7 @@ mod tests {path: Some(path.into()),project: Some("scratch".into()),workspace: Some("default".into()),+ scope: None,include_related: false,related_depth: None,}),diff --git a/docs/usage.md b/docs/usage.mdindex f2493677..ae9e9eaf 100644--- a/docs/usage.md+++ b/docs/usage.md@@ -250,6 +250,11 @@ a page: a query aimed at a session-specific term can still return that session.`pinned` remains primarily a retention and automation-mutation control, not anunconditional search override.+Supplemental `global_scope_hits` are self-describing: each includes+`workspace`, `project`, and `scope: "global"`. Read one directly with its path+and `scope: "global"`; an unscoped read still selects the current project, so+same-path local and global pages remain distinct.+### Keep a lookup cheap`memory_read_session_observations` defaults to 20 rows of up to 1000 charactersdiff --git a/plugins/claude-code/skills/ai-memory-retrieval/SKILL.md b/plugins/claude-code/skills/ai-memory-retrieval/SKILL.mdindex 0b9b2add..6868bda9 100644--- a/plugins/claude-code/skills/ai-memory-retrieval/SKILL.md+++ b/plugins/claude-code/skills/ai-memory-retrieval/SKILL.md@@ -12,7 +12,7 @@ Use this skill for read-only ai-memory lookups, catch-up, and evaluating remembe- `memory_query` searches the current project's wiki for prior decisions, gotchas, procedures, rules, and session notes.- `memory_recent` lists the most recently updated pages when the user wants a light activity check.-- `memory_read_page` fetches a full page body after a search hit or direct path lookup. The body is capped by `max_chars` (default 12000, max 64000); the response's `truncated`/`total_chars` fields report whether it was cut and its full size. Raise `max_chars` only when you need the whole page. Pass `include_related: true` (optional `related_depth`, default 1, hard cap 3) to also walk the link graph outward and return a `related` array of reachable pages, each with its hop `depth` and edge `direction` (`link`/`backlink`); default off omits it.+- `memory_read_page` fetches a full page body after a search hit or direct path lookup. A `global_scope_hits` result carries its `workspace`, `project`, and `scope`; pass `scope: "global"` to read that reserved scope directly. The body is capped by `max_chars` (default 12000, max 64000); the response's `truncated`/`total_chars` fields report whether it was cut and its full size. Raise `max_chars` only when you need the whole page. Pass `include_related: true` (optional `related_depth`, default 1, hard cap 3) to also walk the link graph outward and return a `related` array of reachable pages, each with its hop `depth` and edge `direction` (`link`/`backlink`); default off omits it.- `memory_read_session_observations` reads one session's raw hook observations (prompts, tool calls, stops) in capture order, paged and body-capped, when the user asks what actually happened in a session or wants to check a compiled page against its evidence. It also continues a session that was cut off without ending: pass the `session_id` a session-start notice, `recent_sessions` or `newer_unended_session` names (a harness's native id, such as an OpenCode `ses_…` id, works too) with `order: "desc"`, and its newest prompts and tool results are where the work stopped.- `memory_status` reports whether ai-memory is healthy and how large the knowledge base is.- `memory_briefing` returns a structured read-only snapshot for agent consumption, including a bounded `pinned` list of the project's pinned standing-context pages (present only when the project has pins) and `recent_sessions`, the sessions with the newest captured work. An entry there with `ended: false` and `handed_off: false` that is not `current` was cut off or is still running; read it before an older handoff or page when the user asks to continue.diff --git a/plugins/codex/skills/ai-memory-retrieval/SKILL.md b/plugins/codex/skills/ai-memory-retrieval/SKILL.mdindex 0b9b2add..6868bda9 100644--- a/plugins/codex/skills/ai-memory-retrieval/SKILL.md+++ b/plugins/codex/skills/ai-memory-retrieval/SKILL.md@@ -12,7 +12,7 @@ Use this skill for read-only ai-memory lookups, catch-up, and evaluating remembe- `memory_query` searches the current project's wiki for prior decisions, gotchas, procedures, rules, and session notes.- `memory_recent` lists the most recently updated pages when the user wants a light activity check.-- `memory_read_page` fetches a full page body after a search hit or direct path lookup. The body is capped by `max_chars` (default 12000, max 64000); the response's `truncated`/`total_chars` fields report whether it was cut and its full size. Raise `max_chars` only when you need the whole page. Pass `include_related: true` (optional `related_depth`, default 1, hard cap 3) to also walk the link graph outward and return a `related` array of reachable pages, each with its hop `depth` and edge `direction` (`link`/`backlink`); default off omits it.+- `memory_read_page` fetches a full page body after a search hit or direct path lookup. A `global_scope_hits` result carries its `workspace`, `project`, and `scope`; pass `scope: "global"` to read that reserved scope directly. The body is capped by `max_chars` (default 12000, max 64000); the response's `truncated`/`total_chars` fields report whether it was cut and its full size. Raise `max_chars` only when you need the whole page. Pass `include_related: true` (optional `related_depth`, default 1, hard cap 3) to also walk the link graph outward and return a `related` array of reachable pages, each with its hop `depth` and edge `direction` (`link`/`backlink`); default off omits it.- `memory_read_session_observations` reads one session's raw hook observations (prompts, tool calls, stops) in capture order, paged and body-capped, when the user asks what actually happened in a session or wants to check a compiled page against its evidence. It also continues a session that was cut off without ending: pass the `session_id` a session-start notice, `recent_sessions` or `newer_unended_session` names (a harness's native id, such as an OpenCode `ses_…` id, works too) with `order: "desc"`, and its newest prompts and tool results are where the work stopped.- `memory_status` reports whether ai-memory is healthy and how large the knowledge base is.- `memory_briefing` returns a structured read-only snapshot for agent consumption, including a bounded `pinned` list of the project's pinned standing-context pages (present only when the project has pins) and `recent_sessions`, the sessions with the newest captured work. An entry there with `ended: false` and `handed_off: false` that is not `current` was cut off or is still running; read it before an older handoff or page when the user asks to continue.