Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: retire the "Codex has no session-end" claim (follows #605)
AkitaOnRails19e9f3fe183f
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex fd50337d..eac8572b 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -82,8 +82,9 @@ from hook paths.converge. Existing ended sessions are baselined at migration instead ofbecoming historical catch-up work. Auto-commits the wiki. Clientswithout a reliable true session-end hook need an explicit ending action:- use `ai-memory finalize-session` for Codex, or- `ai-memory finalize-session --agent antigravity-cli` for Antigravity CLI.+ `ai-memory finalize-session --agent antigravity-cli` for Antigravity CLI+ (Codex has a native `SessionEnd` since CLI 0.145.0; `finalize-session+ --agent codex` is only the fallback on older Codex).The command selects the latest matching open session and enters the samecanonical SessionEnd path as a native hook. Generated session-pagefrontmatter records `session_id` plus the immutable `sessions.agent_kind`diff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex 533ebac0..76da5bee 100644--- a/docs/mcp-install.md+++ b/docs/mcp-install.md@@ -1277,7 +1277,7 @@ that *starts* the next one - to play nicely with ai-memory:| Side | What's needed | Covered by ||---|---|---|-| **Ending side** | The agent must create a handoff through a true session-end hook, the manual finalizer, or `memory_handoff_begin`. | Built-in automatically for Claude Code, Devin CLI, Cursor, Gemini CLI, Grok Build CLI, Zero, Kimi Code, OpenClaw, OpenCode, and OMP. Codex, Antigravity CLI, both Kiro CLI engines, and Command Code have no reliable true session-end event; run `ai-memory finalize-session` with the corresponding `--agent` after the final turn. MCP-only clients such as Swival must call `memory_handoff_begin` explicitly. |+| **Ending side** | The agent must create a handoff through a true session-end hook, the manual finalizer, or `memory_handoff_begin`. | Built-in automatically for Claude Code, Codex (native `SessionEnd`, Codex CLI 0.145.0+), Devin CLI, Cursor, Gemini CLI, Grok Build CLI, Zero, Kimi Code, OpenClaw, OpenCode, and OMP. Antigravity CLI, both Kiro CLI engines, and Command Code have no reliable true session-end event; run `ai-memory finalize-session` with the corresponding `--agent` after the final turn (also the fallback on Codex older than 0.145.0). MCP-only clients such as Swival must call `memory_handoff_begin` explicitly. || **Starting side** | Either (a) the session-start/plugin path injects the handoff via `/handoff`, OR (b) the model proactively calls `memory_handoff_accept` on first turn. | (a) is built-in for Claude Code / Codex / Devin CLI / Cursor / Gemini CLI / Antigravity CLI / Kimi Code / both Kiro CLI engines / Command Code / OpenClaw / OpenCode / OMP. It requires a client that consumes startup-hook stdout or an equivalent context-injection result. Grok and Zero discard SessionStart stdout; Swival is MCP-only. Use (b) for those clients. (b) works for any MCP-capable client if you nudge the model - see [the managed routing package](usage.md#install-the-routing-snippet-and-agent-skills). |OpenCode uses its official `session.deleted` plugin event for true session-enddiff --git a/docs/research-karpathy-llm-wiki.md b/docs/research-karpathy-llm-wiki.mdindex f3ca0c36..b5964a35 100644--- a/docs/research-karpathy-llm-wiki.md+++ b/docs/research-karpathy-llm-wiki.md@@ -81,7 +81,7 @@ Translating Karpathy faithfully - a "Karpathy-style" backend looks very differen- **Ingest must be a *write fan-out*, an insert.** A new observation should *touch ~10–15 existing pages* - updating an entity page, a concept page, a decisions log, a gotchas page. This is the single biggest deviation from vector RAG, which only ever appends.- **`index.md` and `log.md` as first-class files.** The log is the audit trail and the consolidation trigger source. Use the prefix convention (`## [YYYY-MM-DD] action | title`) so it's grep-able.- **Retrieval is hierarchical, nearest-neighbor.** Read `index.md` → narrow to candidate pages → read them → optionally fall back to hybrid search (BM25 + vector, RRF-fused) for novel queries. The index *is* the synthesis; the embeddings are a backstop.-- **Consolidation is an explicit, scheduled MCP operation**, not a side-effect. `memory_consolidate` is invoked on true session-end hooks where the client exposes them, on the manual `ai-memory finalize-session` flow for clients such as Codex and Antigravity CLI, on compaction events, or on a timer. It is LLM-driven (needs a provider key); if absent, it runs no-op as agentmemory does.+- **Consolidation is an explicit, scheduled MCP operation**, not a side-effect. `memory_consolidate` is invoked on true session-end hooks where the client exposes them, on the manual `ai-memory finalize-session` flow for clients without a true session-end hook such as Antigravity CLI, on compaction events, or on a timer. It is LLM-driven (needs a provider key); if absent, it runs no-op as agentmemory does.- **Cross-agent shared state.** Because the wiki is plain text, Claude Code, Codex, and OpenCode all read/write the *same* artifact. The MCP server is the gatekeeper; the markdown is the contract. No vendor lock.- **Coding-specific page types**: library gotchas, architectural decisions (ADR-style), failed approaches, repo conventions, environment quirks. Karpathy's example domains were personal/research; for coding agents the high-value pages are *failure modes* and *decisions*, because those are exactly what gets dropped on context compaction.