mirror of
https://github.com/akitaonrails/ai-memory.git
synced 2026-10-02 03:24:46 +08:00
docs: fix audited drift in frontend-api, windows, and Codex managed runs
- frontend-api.md (#986): the list, search, and recent routes return bare JSON arrays, not `{ "workspaces": … }`-style wrappers (the route tests assert `as_array()`); a page read returns `body_markdown`, not `body`; a search hit carries workspace/project/kind and no `id`. - windows.md (#758): native `ai-memory upgrade` is done (#801/#802), not in-progress. - managed-workstreams.md + support matrix (#987): document the Codex shared daemon handing hooks a stale AI_MEMORY_RUN_ID and the `--no-daemon` workaround until the server-side fix lands. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MDbhmszrjG9s5MrPrTuNtm
This commit is contained in:
AkitaOnRails
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
695805eb88
commit
013bf691fd
+50
-58
@@ -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 workspaces
|
||||
GET /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 workspace
|
||||
GET /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)
|
||||
|
||||
@@ -500,6 +500,27 @@ protocol](managed-harness-contributions.md), including read-only extraction,
|
||||
pre-turn context delivery, migration invariants, deterministic tests, and an
|
||||
opt-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 recovery
|
||||
|
||||
Managed runs need current ai-memory lifecycle hooks so SessionStart can receive
|
||||
|
||||
@@ -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. |
|
||||
|
||||
+6
-4
@@ -643,10 +643,12 @@ from what the repository actually ships today.
|
||||
decision is made; it is a blocker for a frictionless Supported experience on
|
||||
Application-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 items
|
||||
are closed and the deferred code-signing policy is resolved (or explicitly
|
||||
|
||||
Reference in New Issue
Block a user