Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: fix audited drift in frontend-api, windows, and Codex managed runs
AkitaOnRails013bf691fdd4
diff --git a/docs/frontend-api.md b/docs/frontend-api.mdindex 8e97d27a..d803d403 100644--- a/docs/frontend-api.md+++ b/docs/frontend-api.md@@ -98,19 +98,17 @@ All endpoints are `GET` unless noted. Paths under `/api/v1/`.GET /api/v1/workspaces```-**Response:** `{ "workspaces": [WorkspaceSummary, …] }`+**Response:** a bare JSON array, `[WorkspaceSummary, …]````json-{- "workspaces": [- {- "workspace_name": "default",- "project_count": 3,- "page_count": 412,- "last_updated": "2026-05-28T14:02:11.123Z"- }- ]-}+[+ {+ "workspace_name": "default",+ "project_count": 3,+ "page_count": 412,+ "last_updated": "2026-05-28T14:02:11.123Z"+ }+]````last_updated` is `null` for an empty workspace.@@ -122,19 +120,17 @@ GET /api/v1/projects # all projects across all workspacesGET /api/v1/projects?workspace=NAME # projects in one workspace```-**Response:** `{ "projects": [ProjectSummary, …] }`+**Response:** a bare JSON array, `[ProjectSummary, …]````json-{- "projects": [- {- "workspace_name": "default",- "project_name": "ai-memory",- "page_count": 138,- "last_updated": "2026-05-28T14:02:11.123Z"- }- ]-}+[+ {+ "workspace_name": "default",+ "project_name": "ai-memory",+ "page_count": 138,+ "last_updated": "2026-05-28T14:02:11.123Z"+ }+]```### 4.3 Pages (list)@@ -143,20 +139,18 @@ GET /api/v1/projects?workspace=NAME # projects in one workspaceGET /api/v1/workspaces/{workspace}/projects/{project}/pages```-**Response:** `{ "pages": [PageSummary, …] }`+**Response:** a bare JSON array, `[PageSummary, …]````json-{- "pages": [- {- "path": "decisions/0007-db.md",- "title": "Standardised on Postgres",- "kind": "decision",- "tier": "semantic",- "updated_at": "2026-05-27T09:12:00.000Z"- }- ]-}+[+ {+ "path": "decisions/0007-db.md",+ "title": "Standardised on Postgres",+ "kind": "decision",+ "tier": "semantic",+ "updated_at": "2026-05-27T09:12:00.000Z"+ }+]````404` if the workspace or project doesn't exist.@@ -185,7 +179,7 @@ links + back-links."updated_at": "2026-05-28T11:04:33.123Z","supersedes": null,"frontmatter": { "tags": ["adr"], "pinned": true },- "body": "# Standardised on Postgres\n\n…",+ "body_markdown": "# Standardised on Postgres\n\n…","links": [ { "path": "concepts/db-rules.md", "title": "DB rules", "kind": "rule" } ],"backlinks": [ { "path": "sessions/2026-05-27.md", "title": "Session 2026-05-27", "kind": "session" } ]}@@ -218,20 +212,20 @@ Content-Type: application/json}```-**Response:** `{ "hits": [PageHit, …] }`+**Response:** a bare JSON array, `[SearchHit, …]````json-{- "hits": [- {- "id": "01928d27-…",- "path": "concepts/karpathy-wiki.md",- "title": "Karpathy LLM Wiki pattern",- "snippet": "Andrej <mark>Karpathy</mark>'s LLM wiki design …",- "rank": -8.4- }- ]-}+[+ {+ "workspace": "default",+ "project": "ai-memory",+ "path": "concepts/karpathy-wiki.md",+ "title": "Karpathy LLM Wiki pattern",+ "kind": "concept",+ "snippet": "Andrej <mark>Karpathy</mark>'s LLM wiki design …",+ "rank": -8.4+ }+]```Rules:@@ -261,19 +255,17 @@ Every reader surface uses the same `kind` contract. An explicit frontmatter`rule`, `slot`, `session`, `decision`, `gotcha`, `concept`, `procedure`, and`note`, respectively. Other paths fall back to `fact`.-**Response:** `{ "pages": [BriefingPage, …] }`+**Response:** a bare JSON array, `[BriefingPage, …]````json-{- "pages": [- {- "path": "sessions/2026-05-28.md",- "title": "Session 2026-05-28",- "kind": "session",- "updated_at": "2026-05-28T14:02:11.123Z"- }- ]-}+[+ {+ "path": "sessions/2026-05-28.md",+ "title": "Session 2026-05-28",+ "kind": "session",+ "updated_at": "2026-05-28T14:02:11.123Z"+ }+]```### 4.7 Briefing (structured snapshot)diff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.mdindex 5307f171..b1115cd0 100644--- a/docs/managed-workstreams.md+++ b/docs/managed-workstreams.md@@ -500,6 +500,27 @@ protocol](managed-harness-contributions.md), including read-only extraction,pre-turn context delivery, migration invariants, deterministic tests, and anopt-in real-harness acceptance pass.+### Known issue: Codex's shared daemon and stale run ids (#987)++Recent Codex releases run sessions through a shared background app-server+daemon (`codex agents` lists it). The daemon keeps the environment it started+with, and the lifecycle hooks it launches inherit that environment — including+the `AI_MEMORY_RUN_ID` of whichever managed run auto-started it. A later+`ai-memory run codex` then reports that finished run, gets no continuity+context, and the server logs `managed SessionStart has no active run`.++Until the server-side fix lands, launch managed Codex sessions without the+daemon. Native arguments after the harness are forwarded to Codex:++```bash+ai-memory run codex --no-daemon+```++`--no-daemon` makes that one session run without the shared background server+even if one is already running; it is available on Codex's interactive and+`resume` commands (checked on Codex 0.156). Sessions started without it keep+the daemon behavior described above.+## Installation and recoveryManaged runs need current ai-memory lifecycle hooks so SessionStart can receivediff --git a/docs/support-matrix.md b/docs/support-matrix.mdindex 5ad8e5a0..5d63037a 100644--- a/docs/support-matrix.md+++ b/docs/support-matrix.md@@ -11,7 +11,7 @@| Windows via WSL2 | Supported | Use the Linux install path inside WSL2 when the agent runs there. || Native Windows | Experimental | Tagged releases publish `ai-memory-windows-x86_64.zip` with `ai-memory.exe`; Docker Desktop wrapper and source builds are also available. Native `ai-memory upgrade` is supported for writable x86_64 zip installs (checksum-verified zip + rename-aside self-replace + sibling `hooks/` refresh). Local supported profiles default to host-native hook commands; Claude Code may use its Windows exec form, while other agents use native single command strings matching their hook schema. PowerShell/Git Bash scripts are compatibility fallbacks. See [`docs/windows.md`](windows.md). || Claude Code | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. `install-mcp --session-aware` optionally enables per-session auto-scope isolation through a local stdio bridge. Optionally captures the assistant's final turn on `Stop` when installed with `--capture-assistant` and the server enables `capture_assistant` (double opt-in, off by default). |-| Codex | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. `SessionEnd` is wired since Codex CLI 0.145.0 (openai/codex#33895), so finished sessions get an automatic end-of-session summary/handoff; on older Codex the event is inert and `ai-memory finalize-session --agent codex` is the fallback. Optionally captures the assistant's final turn on `Stop` when installed with `--capture-assistant` and the server enables `capture_assistant` (double opt-in, off by default) — Codex's `Stop` payload carries `last_assistant_message`, same as Claude Code. |+| Codex | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. `SessionEnd` is wired since Codex CLI 0.145.0 (openai/codex#33895), so finished sessions get an automatic end-of-session summary/handoff; on older Codex the event is inert and `ai-memory finalize-session --agent codex` is the fallback. Managed runs (`ai-memory run codex`) can lose continuity through Codex's shared daemon inheriting a stale run id; launch with `--no-daemon` until #987 is fixed (see [`docs/managed-workstreams.md`](managed-workstreams.md)). Optionally captures the assistant's final turn on `Stop` when installed with `--capture-assistant` and the server enables `capture_assistant` (double opt-in, off by default) — Codex's `Stop` payload carries `last_assistant_message`, same as Claude Code. || Command Code | Supported | MCP config (`~/.commandcode/mcp.json`) + its four stable lifecycle-hook events (`~/.commandcode/settings.json`); native commands enforce capture exclusions and `SessionStart` injects handoffs. `Stop` is only a turn boundary, so use `ai-memory finalize-session --agent command-code` after the final turn; an interactive session launched with `ai-memory run command-code` is finalized automatically when it exits if the run can tie the session to itself (see [`docs/managed-workstreams.md`](managed-workstreams.md)). `ai-memory run command-code` adds exact v3 native-session resume and visible-event import; experimental unsandboxed Mods remain excluded. || Devin CLI | Supported | MCP config + lifecycle hooks. Hooks use Devin's `PostCompaction` event, inject handoffs via `hookSpecificOutput.additionalContext`, and omit subagent events because Devin does not expose them. || OpenCode | Supported | Remote MCP config + generated TypeScript plugin; generated plugin enforces capture exclusions. |diff --git a/docs/windows.md b/docs/windows.mdindex 276cd30b..3bb993f8 100644--- a/docs/windows.md+++ b/docs/windows.md@@ -643,10 +643,12 @@ from what the repository actually ships today.decision is made; it is a blocker for a frictionless Supported experience onApplication-Control-enforced fleets.-- **Native `ai-memory upgrade` path — in-progress.** A first-class in-place- upgrade for native Windows installs (release-binary and wrapper flows) is- tracked in #801/#802. Until it lands, upgrading is the manual- download/extract/re-`install-hooks` sequence in Scenarios B and C.+- **Native `ai-memory upgrade` path — done.** `ai-memory upgrade` upgrades a+ writable native install in place (#801, #802): it verifies the+ `ai-memory-windows-x86_64.zip` checksum, replaces `ai-memory.exe` by+ rename-aside, refreshes a sibling `hooks/` tree, and re-stages installed+ hooks — see Scenario B. A non-writable prefix (for example under Program+ Files) still upgrades through the manual download/extract sequence.Promotion to Supported is the maintainer's decision once the in-progress itemsare closed and the deferred code-signing policy is resolved (or explicitly