Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
M11: auto-surface handoff at SessionStart + checkpoint at PreCompact
AkitaOnRails93a444375d0c
diff --git a/Cargo.lock b/Cargo.lockindex 82cde316..ecb295ea 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -95,6 +95,7 @@ dependencies = [name = "ai-memory-hooks"version = "0.1.0"dependencies = [+ "ai-memory-consolidate","ai-memory-core","ai-memory-store","ai-memory-wiki",diff --git a/README.md b/README.mdindex 9d37a7fa..4a0df650 100644--- a/README.md+++ b/README.md@@ -11,154 +11,283 @@## Why this existsLLM coding agents lose all context when a session ends. Today's-"memory" tools either (a) require the user to manually invoke `write_note`-every time something matters, or (b) wrap a vector database in a chat-shim and call it RAG.+"memory" tools either (a) require the user to manually invoke+`write_note` every time something matters, or (b) wrap a vector+database in a chat shim and call it RAG.-This project takes a different bet, faithful to+ai-memory takes a different bet, faithful to[Andrej Karpathy's "LLM Wiki"](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)pattern: knowledge is **compiled** at ingest time into a structured,-cross-linked, supersedeable wiki on disk — not retrieved over raw logs at-query time. The wiki is plain markdown in a git repo, so you can `grep`-it, open it in Obsidian, diff it, and back it up with `rsync`.+cross-linked, supersedeable wiki on disk — not retrieved over raw logs+at query time. The wiki is plain markdown in a git repo, so you can+`grep` it, open it in Obsidian, diff it, and back it up with `rsync`.-Capture is **automatic** via the agent CLI's lifecycle hooks; there is no-`write_note` ceremony. Consolidation runs in the background when a session-ends: the LLM reads recent observations and rewrites the relevant wiki-pages atomically with full supersession history.--Read [`docs/research-karpathy-llm-wiki.md`](docs/research-karpathy-llm-wiki.md)-for the pattern, and [`docs/design-decisions.md`](docs/design-decisions.md)-for how this project implements it.+Capture is **fully automatic** via the agent CLI's lifecycle hooks; there+is no `write_note` ceremony. Consolidation runs in the background when+a session ends and when the agent's own context window is about to be+compacted — both moments where state would otherwise be lost.## Status-**v0.2 complete.** Milestones M0 through M10 have shipped:--- ✅ **M0–M1** — Workspace, SQLite substrate, FTS5, file watcher, atomic writes.-- ✅ **M2 / M2.5** — MCP server (`rmcp` 1.7), Docker image, backup/restore.-- ✅ **M3 / M4** — Auto-capture via Claude Code / Codex / OpenCode hooks; typed cross-agent handoffs.-- ✅ **M5 / M6** — Wiki git versioning with auto-commit; LLM provider trait (Anthropic, OpenAI, OpenAI-compat).-- ✅ **M7a / M7b** — Karpathy-style single-page LLM consolidation + multi-page atomic fan-out.-- ✅ **M8** — Retention sweep with episodic decay + access reinforcement; rule + LLM lint.-- ✅ **M9** — Pluggable embedders (OpenAI, Voyage, plus a deterministic synthetic embedder for tests); hybrid RRF retrieval over `page_embeddings`.-- ✅ **M10** — Recall@5 eval harness, consolidated [`ARCHITECTURE.md`](docs/ARCHITECTURE.md), this README refresh.+**v0.2 complete.** Milestones M0 through M10 have shipped. Single+package; 57+ unit + integration tests passing, `cargo clippy+--workspace -D warnings` clean, `cargo fmt --check` clean.-Single-package design: **57 unit + integration tests passing**,-`cargo clippy --workspace -D warnings` clean, `cargo fmt --check` clean.+## Quick start (Docker)-## Architecture in 60 seconds--A single Rust binary, optionally containerised. Runs as an-[MCP](https://modelcontextprotocol.io/) server over stdio + HTTP. Owns a-data directory containing:+The recommended way to run ai-memory is as a long-lived container on+your dev machine or homelab. The image is published to Docker Hub at+[`akitaonrails/ai-memory:latest`](https://hub.docker.com/r/akitaonrails/ai-memory).+```bash+# Zero-LLM mode: pure FTS5 search, rule-based session summaries.+# No API keys needed. Good for trying it out.+docker run -d --name ai-memory \+ -p 49374:49374 \+ -v ai-memory-data:/data \+ akitaonrails/ai-memory:latest```-<data_dir>/-├── wiki/ # markdown source of truth (git-versioned)-├── raw/ # immutable session log archive-├── db/ # SQLite (FTS5 + page_embeddings) — derived index-├── models/ # reserved for local embedding model (v0.3+)-└── logs/ # rolling daily tracing output++```bash+# Full mode: LLM-driven consolidation + hybrid search.+# Recommended defaults: Claude Sonnet for consolidation,+# OpenAI text-embedding-3-small for embeddings.+docker run -d --name ai-memory \+ -p 49374:49374 \+ -v ai-memory-data:/data \+ -e AI_MEMORY_LLM_PROVIDER=anthropic \+ -e ANTHROPIC_API_KEY=sk-ant-... \+ -e AI_MEMORY_EMBEDDING_PROVIDER=openai \+ -e OPENAI_API_KEY=sk-... \+ akitaonrails/ai-memory:latest```-Agent lifecycle hooks fire-and-forget POST to the server's HTTP ingress.-The server queues writes through a single SQLite writer (no-`database is locked`). On session end, an optional LLM-driven pass-rewrites pages atomically with supersession (`is_latest=false` +-`supersedes` chain) and opens a typed handoff for the next agent. The-retention sweep (M8) decays unused episodic content while semantic-concept pages compound forever; pinned pages are exempt. Retrieval is-FTS5 by default; when an embedder is configured, hybrid RRF over-`page_embeddings` joins the FTS5 ranks.+The server listens on `127.0.0.1:49374` (port `0xC0DE` — "CODE" in hex,+in IANA's dynamic/private range so it won't clash with registered+services). MCP endpoint: `http://127.0.0.1:49374/mcp`. Hook ingress:+`http://127.0.0.1:49374/hook`.-Storage moves between machines via `ai-memory backup --to <tarball>`-(SQLite online backup + git wiki) or just `rsync` of the data dir.+Inspect state with `docker exec ai-memory ai-memory status --json`.+Wiki and SQLite live in the `ai-memory-data` volume; back up with+`docker run --rm -v ai-memory-data:/data busybox tar -czf - /data >+ai-memory-$(date +%F).tar.gz`.-See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the canonical-data-flow diagram + crate breakdown + cross-cutting invariants.+## Configure your agent CLI-## Quick start+Each agent CLI needs two things wired up:-Requires Rust 1.95+. Three ways to run it, in increasing order of-"homelab-ready":+1. **MCP connection** — so the agent can call `memory_query`,+ `memory_recent`, etc.+2. **Lifecycle hooks** — so the server auto-captures session events.+ This is what makes capture "free".-### Local: cargo build+### Claude Code```bash-# Build, init, and run the MCP server over stdio (attach with claude mcp).-cargo build --release --workspace-./target/release/ai-memory init-claude mcp add ai-memory -- ./target/release/ai-memory serve --transport stdio+# 1. Register the MCP server (HTTP transport).+claude mcp add --transport http ai-memory http://127.0.0.1:49374/mcp++# 2. Install the lifecycle hooks. Clone the repo to get the scripts:+git clone https://github.com/akitaonrails/ai-memory ~/.ai-memory+cd ~/.ai-memory && cargo build --release+# Then print the JSON to merge into ~/.claude/settings.json:+~/.ai-memory/target/release/ai-memory install-hooks --agent claude-code```-Or with HTTP transport for `mcp-inspector` / curl / a remote Claude Code:+The hook scripts are tiny POSIX shell wrappers that `curl` the event+JSON to `127.0.0.1:49374/hook` with sub-second timeouts. They never+block the agent.++### OpenAI Codex```bash-./target/release/ai-memory serve --transport http --bind 127.0.0.1:49374+# 1. MCP — add to ~/.codex/config.toml:+[mcp_servers.ai-memory]+url = "http://127.0.0.1:49374/mcp"++# 2. Lifecycle hooks — Codex uses its own hooks file; the install+# helper prints the snippet to merge:+~/.ai-memory/target/release/ai-memory install-hooks --agent codex```-### Local: Docker Compose+### OpenCode```bash-docker compose -f docker/docker-compose.yml up -d --build-# State lives in the `ai-memory-data` named volume.-# Attach Claude Code at http://localhost:49374/mcp+# Same pattern; see `ai-memory install-hooks --agent opencode` for+# the agent-specific config format.+~/.ai-memory/target/release/ai-memory install-hooks --agent opencode```-### Full CLI subcommand list+## LLM provider, models, and API keys++ai-memory works in three intensity tiers. **The default Docker run is+the zero-LLM tier** — no API keys required, everything still works,+just with deterministic rule-based summaries and FTS5-only retrieval.++| Tier | What you get | Env vars | Cost |+|---|---|---|---|+| **Zero-LLM** | FTS5 search, rule-based session pages, auto-handoffs | (none) | $0 |+| **+ LLM consolidation** | LLM rewrites session pages as coherent narratives; LLM-driven contradiction lint; PreCompact checkpoints | `AI_MEMORY_LLM_PROVIDER=anthropic` + `ANTHROPIC_API_KEY` | ~$0.01–0.05 per session |+| **+ Hybrid retrieval** | RRF over FTS5 + vector cosine similarity. Better recall on paraphrased queries | `AI_MEMORY_EMBEDDING_PROVIDER=openai` + `OPENAI_API_KEY` | ~$0.0001 per page on backfill |++### Recommended models (chosen as defaults)++If you set the **provider** but not the model, ai-memory picks+sensible defaults. Override with the corresponding env var.++| Setting | Default | Why this default | Override |+|---|---|---|---|+| Anthropic LLM | `claude-sonnet-4-7` | Smart enough to summarise a session into coherent narrative; cheap enough to run on every session-end without thinking about it. Not a reasoning model — consolidation doesn't benefit from extended thinking. | `AI_MEMORY_LLM_MODEL` |+| OpenAI LLM | `gpt-4o-mini` | Closest OpenAI equivalent to the Sonnet tier in price/quality. | `AI_MEMORY_LLM_MODEL` |+| OpenAI embedding | `text-embedding-3-small` (1536-dim) | Best price/quality from OpenAI; 5× cheaper than `text-embedding-3-large` with marginal recall loss. | `AI_MEMORY_EMBEDDING_MODEL` + `AI_MEMORY_EMBEDDING_DIM` |+| Voyage embedding | `voyage-3` (1024-dim) | Voyage's current general-purpose recommendation. | same |++For **self-hosted LLMs** (Ollama, vLLM, LM Studio):```bash-./target/release/ai-memory --help # full subcommand tree-./target/release/ai-memory init # create the data dir layout-./target/release/ai-memory serve # MCP server (stdio default; +http)-./target/release/ai-memory watch # standalone filesystem watcher-./target/release/ai-memory write-page \- --path notes/foo.md --title Foo --body "..." # manual wiki write-./target/release/ai-memory search "karpathy" # FTS5 query (CLI only; MCP picks hybrid when embedder set)-./target/release/ai-memory status --json # counts + paths-./target/release/ai-memory commit -m "..." # stage + commit the wiki repo-./target/release/ai-memory backup --to bak.tar.gz # SQLite online backup → tarball-./target/release/ai-memory restore --from bak.tar.gz # extract + re-open-./target/release/ai-memory reset --confirm # wipe data (refuses while siblings alive)-./target/release/ai-memory install-hooks --agent claude-code # print hook config snippet-./target/release/ai-memory llm-test --provider anthropic --model claude-sonnet-4-7 --prompt "hi"-./target/release/ai-memory forget-sweep [--dry-run] # M8 retention-./target/release/ai-memory lint [--dry-run] # M8 rule + LLM lint-./target/release/ai-memory embed [--dry-run] # M9 backfill embeddings+docker run -d --name ai-memory \+ -p 49374:49374 \+ -v ai-memory-data:/data \+ -e AI_MEMORY_LLM_PROVIDER=openai-compat \+ -e AI_MEMORY_LLM_BASE_URL=http://host.docker.internal:11434/v1 \+ -e AI_MEMORY_LLM_MODEL=qwen2.5-coder:14b \+ akitaonrails/ai-memory:latest+```++There is no safe default model for `openai-compat` — what you can run+depends on your local setup, so the model env var is required.++## How to use it in practice++The point of ai-memory is that you mostly **don't** think about it.+Lifecycle hooks capture every prompt + tool call + session boundary+automatically. The agent gains awareness of prior work without you+typing anything special. That said, a few patterns are worth knowing:++### Cross-agent handoff (the headline feature)++```+$ claude+> "Working on the auth refactor. The current approach uses JWT but+ we found the rotation story is broken. Investigating session+ cookies as an alternative."+[work for an hour]+> /exit++$ codex # in the same directory, hours or days later+[Codex starts; the SessionStart hook synchronously fetches the open+ handoff and prepends it to the session.]+> "Picking up from prior work: you were investigating session cookies+ as an alternative to broken JWT rotation. Continuing?"```-### Optional features via env+You did nothing special. The handoff was created automatically on+Claude Code's session-end, and surfaced automatically on Codex's+session-start.-The system runs with **zero LLM / zero embedder configured** — pure-FTS5 retrieval, synthetic session summaries, no consolidation. Add-features by setting env vars; everything is opt-in.+### Context-window compaction recovery++When Claude Code or Codex compact their working context, the+`PreCompact` hook fires and ai-memory writes a fresh+`sessions/<id>.md` page summarising the session so far (LLM-driven+if you've configured a provider, rule-based otherwise). After+compaction, the agent can call `memory_recent` to recover the+high-signal summary even though its raw history is gone.++### Spelunking your own history++The wiki dir is plain markdown in a git repo:```bash-# Enable LLM-driven consolidation + lint contradiction detection-AI_MEMORY_LLM_PROVIDER=anthropic-AI_MEMORY_LLM_MODEL=claude-sonnet-4-7-ANTHROPIC_API_KEY=sk-ant-...--# Enable hybrid retrieval (RRF over FTS5 + vector cosine)-AI_MEMORY_EMBEDDING_PROVIDER=openai-AI_MEMORY_EMBEDDING_MODEL=text-embedding-3-small-AI_MEMORY_EMBEDDING_DIM=1536-OPENAI_API_KEY=sk-...+docker exec ai-memory ls /data/wiki/sessions/+docker exec ai-memory cat /data/wiki/sessions/<uuid>.md++# Open in Obsidian or any markdown viewer:+docker cp ai-memory:/data/wiki ./my-ai-memory-wiki+obsidian ./my-ai-memory-wiki++# Time-travel:+docker exec ai-memory git -C /data/wiki log --oneline+```++### Nudging the agent to use memory proactively++Lifecycle hooks handle *capture* and *handoff resume* without you+typing anything. Proactive *querying* (e.g. "did we already decide+on this?") still depends on the agent thinking to call+`memory_query`. The tool descriptions already nudge in that+direction, but for projects where memory is load-bearing, drop this+snippet into your project's `CLAUDE.md`:++```markdown+## Long-term memory++This project uses ai-memory. The SessionStart hook auto-fetches any+pending handoff. Beyond that, proactively use:++- `memory_query` — before proposing architecture, when the user+ references prior work you don't recognise, or when investigating+ a bug that might have a known root cause.+- `memory_recent` — at session start (in addition to the auto-fetched+ handoff) to scan the last few pages.+- `memory_handoff_begin` — optional; only if you want to capture+ extra context beyond what the SessionEnd hook captures by default.```-Then run `ai-memory embed` once to backfill embeddings for existing-pages.+This is the least obtrusive way to encourage proactive use — it+lives in the project's own instructions rather than every user+prompt.++## CLI reference (when not using Docker)-### Override the data dir+If you'd rather run ai-memory directly:```bash-AI_MEMORY_DATA_DIR=/srv/ai-memory ./target/release/ai-memory init+cargo build --release --workspace+./target/release/ai-memory init # create data dir+./target/release/ai-memory serve --transport http \+ --bind 127.0.0.1:49374 # MCP HTTP + hooks+./target/release/ai-memory status --json # counts + paths+./target/release/ai-memory search "karpathy" # FTS5 query+./target/release/ai-memory backup --to bak.tar.gz # snapshot+./target/release/ai-memory restore --from bak.tar.gz # restore+./target/release/ai-memory forget-sweep [--dry-run] # retention+./target/release/ai-memory lint [--dry-run] # contradiction + orphan audit+./target/release/ai-memory embed [--dry-run] # backfill embeddings+./target/release/ai-memory --help # full subcommand tree```-Default location is `dirs::data_local_dir().join("ai-memory")` —-`~/.local/share/ai-memory` on Linux, `~/Library/Application Support/ai-memory`-on macOS.+Data dir defaults to `~/.local/share/ai-memory` on Linux,+`~/Library/Application Support/ai-memory` on macOS. Override with+`AI_MEMORY_DATA_DIR=/path`.++## Architecture in 60 seconds++A single Rust binary, optionally containerised. Runs as an+[MCP](https://modelcontextprotocol.io/) server over stdio + HTTP. Owns+a data directory containing:++```+<data_dir>/+├── wiki/ # markdown source of truth (git-versioned)+├── raw/ # immutable session log archive+├── db/ # SQLite (FTS5 + page_embeddings) — derived index+├── models/ # reserved for local embedding model (v0.3+)+└── logs/ # rolling daily tracing output+```++Agent lifecycle hooks fire-and-forget POST to the server's HTTP+ingress. The server queues writes through a single SQLite writer+(no `database is locked`). On session end an optional LLM-driven pass+rewrites pages atomically with supersession (`is_latest=false` ++`supersedes` chain) and opens a typed handoff for the next agent. The+retention sweep decays unused episodic content while semantic concept+pages compound forever; pinned pages are exempt. Retrieval is FTS5+by default; when an embedder is configured, hybrid RRF over+`page_embeddings` joins the FTS5 ranks.++See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the canonical+data-flow diagram + crate breakdown + cross-cutting invariants.## Docs@@ -174,8 +303,8 @@ on macOS.| [`issues-basic-memory.md`](docs/issues-basic-memory.md) | File-watcher + capture-friction landmines. || [`issues-cognee.md`](docs/issues-cognee.md) | LLM-gateway + multi-store landmines. |-[`CLAUDE.md`](CLAUDE.md) at the repo root holds the per-session operating-rules; pinned to every Claude Code conversation that touches this repo.+[`CLAUDE.md`](CLAUDE.md) at the repo root holds the per-session+operating rules for the maintainer's own Claude Code sessions.## Influences and prior art@@ -185,18 +314,12 @@ rules; pinned to every Claude Code conversation that touches this repo.- **[cognee](https://github.com/topoteretes/cognee)** — pipeline composition and triplet embeddings.- **[A-MEM](https://arxiv.org/abs/2502.12110)** — Zettelkasten-style atomic notes with link evolution.-## Contributing--The project is intentionally narrow in v1 scope; see the non-goals in-[`docs/design-decisions.md`](docs/design-decisions.md) §13. Issues and PRs-welcome once we cut v1.0; for now, the cleanest way to follow along is to-read the milestones in the design-decisions doc.-## LicenseDual-licensed under MIT OR Apache-2.0.## Acknowledgements-This codebase is being built collaboratively with Claude Code (Anthropic-Claude Opus 4.7) following the plan documented in `docs/design-decisions.md`.+This codebase is being built collaboratively with Claude Code+(Anthropic Claude Opus 4.7) following the plan documented in+`docs/design-decisions.md`.diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rsindex 9a28ad63..33b9e9c8 100644--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@ -1,5 +1,8 @@//! `ai-memory serve` — MCP server with optional filesystem watcher.+use std::sync::Arc;++use ai_memory_consolidate::Consolidator;use ai_memory_hooks::{HookState, hook_router};use ai_memory_llm::{build_embedder, embedder_from_env, provider_from_env};use ai_memory_mcp::AiMemoryServer;@@ -83,19 +86,33 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {if let Some(e) = embedder.clone() {server = server.with_embedder(e);}- if let Some(cfg) = provider_from_env()? {+ // Build the consolidator (if LLM configured) once, then share the+ // Arc between the MCP server (for `memory_consolidate` + lint) and+ // the hook router (for PreCompact checkpointing).+ let consolidator: Option<Arc<Consolidator>> = if let Some(cfg) = provider_from_env()? {let llm = ai_memory_llm::build_provider(cfg).context("building LLM provider from env")?;info!(provider = llm.name(),model = llm.model(),- "memory_consolidate + memory_lint LLM features enabled",+ "memory_consolidate + PreCompact LLM checkpointing enabled",);- server = server.with_consolidator(wiki.clone(), llm);+ let c = Arc::new(Consolidator::new(+ store.reader.clone(),+ store.writer.clone(),+ wiki.clone(),+ llm.clone(),+ ws,+ proj,+ ));+ server = server.with_consolidator_arc(wiki.clone(), llm, c.clone());+ Some(c)} else {info!(- "AI_MEMORY_LLM_PROVIDER unset; memory_consolidate disabled, lint runs rule-based only"+ "AI_MEMORY_LLM_PROVIDER unset; memory_consolidate disabled, PreCompact \+ falls back to rule-based checkpoint, lint runs rule-based only");- }+ None+ };match args.transport {TransportKind::Stdio => {@@ -118,6 +135,7 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {writer: store.writer.clone(),reader: store.reader.clone(),wiki: wiki.clone(),+ consolidator: consolidator.clone(),});let router = axum::Router::new().nest_service("/mcp", mcp_service)diff --git a/crates/ai-memory-core/src/ids.rs b/crates/ai-memory-core/src/ids.rsindex ae092bb9..eddaba1c 100644--- a/crates/ai-memory-core/src/ids.rs+++ b/crates/ai-memory-core/src/ids.rs@@ -152,6 +152,19 @@ pub enum AgentKind {Other,}+impl AgentKind {+ /// Kebab-case wire string matching the serde representation.+ #[must_use]+ pub const fn as_str(self) -> &'static str {+ match self {+ Self::ClaudeCode => "claude-code",+ Self::Codex => "codex",+ Self::OpenCode => "open-code",+ Self::Other => "other",+ }+ }+}+#[cfg(test)]mod tests {use super::*;diff --git a/crates/ai-memory-hooks/Cargo.toml b/crates/ai-memory-hooks/Cargo.tomlindex f28637c5..9c98e52e 100644--- a/crates/ai-memory-hooks/Cargo.toml+++ b/crates/ai-memory-hooks/Cargo.toml@@ -12,6 +12,7 @@ description = "Hook payload schemas, sanitisation, and HTTP ingress for agent liai-memory-core.workspace = trueai-memory-store.workspace = trueai-memory-wiki.workspace = true+ai-memory-consolidate.workspace = trueanyhow.workspace = truethiserror.workspace = trueserde.workspace = truediff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rsindex a488f8d7..108edd96 100644--- a/crates/ai-memory-hooks/src/router.rs+++ b/crates/ai-memory-hooks/src/router.rs@@ -10,9 +10,10 @@use std::str::FromStr;use std::sync::Arc;+use ai_memory_consolidate::Consolidator;use ai_memory_core::{- AgentKind, NewHandoff, NewObservation, NewSession, ObservationKind, ProjectId, SessionId,- WorkspaceId,+ AgentKind, Handoff, NewHandoff, NewObservation, NewSession, ObservationKind, ProjectId,+ SessionId, WorkspaceId,};use ai_memory_store::WriterHandle;use ai_memory_wiki::Wiki;@@ -21,13 +22,14 @@ use axum::Router;use axum::extract::{Query, State};use axum::http::StatusCode;use axum::response::IntoResponse;-use axum::routing::post;+use axum::routing::{get, post};use jiff::Timestamp;+use serde::Deserialize;use tracing::{debug, info, warn};use uuid::Uuid;use crate::log;-use crate::payload::{HookEnvelope, HookEvent, HookQuery};+use crate::payload::{HookEnvelope, HookEvent, HookQuery, parse_agent};use crate::sanitize::Sanitized;use crate::synth::synthesize_session_page;@@ -44,13 +46,19 @@ pub struct HookState {pub reader: ai_memory_store::ReaderPool,/// Wiki handle — used to write the session-summary page.pub wiki: Wiki,+ /// Optional LLM-driven consolidator. When set, PreCompact uses it+ /// to refresh `sessions/<id>.md` before the agent loses its+ /// working context. When `None`, falls back to the deterministic+ /// rule-based synth (still useful, just lower-signal).+ pub consolidator: Option<Arc<Consolidator>>,}-/// Build a router with the single `POST /hook` route mounted on the-/// returned [`Router`].+/// Build a router with `POST /hook` (event ingress) and `GET /handoff`+/// (synchronous handoff-fetch for session-start hooks).pub fn hook_router(state: HookState) -> Router {Router::new().route("/hook", post(handle_hook))+ .route("/handoff", get(handle_handoff)).with_state(Arc::new(state))}@@ -64,6 +72,92 @@ async fn handle_hook((StatusCode::ACCEPTED, "queued")}+/// Query params for `GET /handoff`.+#[derive(Debug, Clone, Deserialize)]+pub struct HandoffQuery {+ /// Identifier of the agent fetching the handoff. Used to mark the+ /// handoff as accepted-by; defaults to `Other` if unrecognised.+ pub agent: Option<String>,+ /// Optional cwd filter. When provided, only handoffs whose stored+ /// cwd matches this string are returned. Note: the cwd string is+ /// not canonicalized; symlinked paths must match byte-for-byte.+ pub cwd: Option<String>,+}++/// Synchronous endpoint used by `session-start.sh` to discover any+/// pending handoff from a previous agent. Returns plain text Markdown+/// (or an empty body when no handoff is open) with a 1-second cap on+/// the server side so the agent never blocks measurably on startup.+///+/// Side effect: when a handoff is found, it is *marked accepted* before+/// the response is sent. Two agents starting in parallel therefore+/// race; whichever arrives first wins. That is intentional — handoffs+/// are 1:1, not broadcast.+async fn handle_handoff(+ State(state): State<Arc<HookState>>,+ Query(query): Query<HandoffQuery>,+) -> impl IntoResponse {+ match fetch_and_accept_handoff(&state, query).await {+ Ok(Some(markdown)) => (StatusCode::OK, markdown),+ Ok(None) => (StatusCode::OK, String::new()),+ Err(e) => {+ warn!(error = %e, "handoff fetch failed");+ (StatusCode::OK, String::new())+ }+ }+}++async fn fetch_and_accept_handoff(+ state: &HookState,+ query: HandoffQuery,+) -> anyhow::Result<Option<String>> {+ let agent = query.agent.as_deref().map_or(AgentKind::Other, parse_agent);+ let handoff = state+ .reader+ .latest_open_handoff(state.workspace_id, state.project_id, query.cwd)+ .await?;+ let Some(h) = handoff else {+ return Ok(None);+ };+ state.writer.accept_handoff(h.id, agent, None).await?;+ Ok(Some(render_handoff_markdown(&h)))+}++fn render_handoff_markdown(h: &Handoff) -> String {+ let mut buf = String::with_capacity(512);+ buf.push_str("> ai-memory — pending handoff from previous session\n");+ buf.push_str(&format!(+ "> from: {from} | created: {ts}\n",+ from = h.from_agent.as_str(),+ ts = h.created_at,+ ));+ buf.push_str("\n## Summary\n");+ buf.push_str(&h.summary);+ if !h.open_questions.is_empty() {+ buf.push_str("\n\n## Open questions\n");+ for q in &h.open_questions {+ buf.push_str(&format!("- {q}\n"));+ }+ }+ if !h.next_steps.is_empty() {+ buf.push_str("\n## Next steps\n");+ for s in &h.next_steps {+ buf.push_str(&format!("- {s}\n"));+ }+ }+ if !h.files_touched.is_empty() {+ buf.push_str("\n## Files touched recently\n");+ for f in &h.files_touched {+ buf.push_str(&format!("- `{f}`\n"));+ }+ }+ buf.push_str(+ "\n_Tip: call `memory_query` or `memory_recent` to recover \+ more detail from prior sessions._\n",+ );+ buf+}+async fn process_envelope(state: Arc<HookState>, env: HookEnvelope) {if let Err(e) = process(&state, env).await {warn!(error = %e, "hook processing failed");@@ -118,6 +212,16 @@ async fn process(state: &HookState, env: HookEnvelope) -> anyhow::Result<()> {warn!(error = %e, "log.md append failed");}+ // On PreCompact, refresh `sessions/<id>.md` so the wiki captures+ // the working state before the agent's compaction throws it out+ // of context. Does NOT end the session and does NOT create a+ // handoff. The eventual SessionEnd supersedes this page.+ if matches!(env.event, HookEvent::PreCompact) {+ if let Err(e) = consolidate_or_synth(state, session_id).await {+ warn!(error = %e, "PreCompact consolidation failed; continuing");+ }+ }+// On SessionEnd, synthesize the summary page, end the session, and// auto-create a handoff so the next agent can pick up.if matches!(env.event, HookEvent::SessionEnd) {@@ -244,6 +348,54 @@ fn build_auto_handoff(}}+/// Write a fresh `sessions/<id>.md` for the current session without+/// ending it. Used by the PreCompact branch to checkpoint state before+/// the agent's working context collapses.+async fn consolidate_or_synth(state: &HookState, session_id: SessionId) -> anyhow::Result<()> {+ if let Some(c) = state.consolidator.as_ref() {+ let outcome = c.consolidate_session(session_id, false).await?;+ debug!(+ session = %session_id,+ path = %outcome.path,+ "PreCompact: LLM consolidation written",+ );+ let _ = state.wiki.commit_all(&format!(+ "pre-compact(session {}): checkpoint",+ short_id(&session_id.to_string()),+ ));+ return Ok(());+ }+ let observations = state.reader.observations_for_session(session_id).await?;+ if observations.is_empty() {+ return Ok(());+ }+ let new_page = synthesize_session_page(+ state.workspace_id,+ state.project_id,+ session_id,+ &observations,+ );+ state+ .wiki+ .write_page(ai_memory_wiki::WritePageRequest {+ workspace_id: new_page.workspace_id,+ project_id: new_page.project_id,+ path: new_page.path,+ frontmatter: new_page.frontmatter_json,+ body: new_page.body,+ tier: new_page.tier,+ pinned: new_page.pinned,+ title: None,+ })+ .await?;+ let _ = state.wiki.commit_all(&format!(+ "pre-compact(session {}): checkpoint",+ short_id(&session_id.to_string()),+ ));+ debug!(session = %session_id, "PreCompact: rule-based checkpoint written");+ Ok(())+}+fn short_id(s: &str) -> String {s.chars().take(8).collect()}diff --git a/crates/ai-memory-llm/src/factory.rs b/crates/ai-memory-llm/src/factory.rsindex 02b93e98..159fa79b 100644--- a/crates/ai-memory-llm/src/factory.rs+++ b/crates/ai-memory-llm/src/factory.rs@@ -172,12 +172,22 @@ pub fn embedder_from_env() -> LlmResult<Option<EmbedderConfig>> {},Err(_) => return Ok(None),};- let model = std::env::var("AI_MEMORY_EMBEDDING_MODEL")- .map_err(|_| LlmError::NotConfigured("AI_MEMORY_EMBEDDING_MODEL".into()))?;- let dim: u32 = std::env::var("AI_MEMORY_EMBEDDING_DIM")- .map_err(|_| LlmError::NotConfigured("AI_MEMORY_EMBEDDING_DIM".into()))?- .parse()- .map_err(|e| LlmError::NotConfigured(format!("AI_MEMORY_EMBEDDING_DIM: {e}")))?;+ // Recommended embedder defaults; override via env. text-embedding-3-small+ // is the price/quality sweet spot for OpenAI; voyage-3 is Voyage's+ // current general-purpose model. Dim follows model when defaulted.+ let model = match std::env::var("AI_MEMORY_EMBEDDING_MODEL") {+ Ok(s) if !s.is_empty() => s,+ _ => match provider {+ EmbedderChoice::OpenAi => "text-embedding-3-small".to_string(),+ EmbedderChoice::Voyage => "voyage-3".to_string(),+ },+ };+ let dim: u32 = match std::env::var("AI_MEMORY_EMBEDDING_DIM") {+ Ok(s) if !s.is_empty() => s+ .parse()+ .map_err(|e| LlmError::NotConfigured(format!("AI_MEMORY_EMBEDDING_DIM: {e}")))?,+ _ => default_embedding_dim(provider, &model),+ };let base_url = std::env::var("AI_MEMORY_EMBEDDING_BASE_URL").ok();let api_key = match provider {EmbedderChoice::OpenAi => std::env::var("OPENAI_API_KEY")@@ -194,6 +204,19 @@ pub fn embedder_from_env() -> LlmResult<Option<EmbedderConfig>> {}))}+/// Default dim for known embedding models. Used when the operator+/// omits `AI_MEMORY_EMBEDDING_DIM`. Falls back to a model-family+/// default; unknown models still require an explicit dim.+fn default_embedding_dim(provider: EmbedderChoice, model: &str) -> u32 {+ match (provider, model) {+ (EmbedderChoice::OpenAi, "text-embedding-3-small") => 1536,+ (EmbedderChoice::OpenAi, "text-embedding-3-large") => 3072,+ (EmbedderChoice::OpenAi, _) => 1536,+ (EmbedderChoice::Voyage, "voyage-3-large") => 1024,+ (EmbedderChoice::Voyage, _) => 1024,+ }+}+/// Construct an `Arc<dyn LlmProvider>` matching the config.////// # Errorsdiff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex ce30da15..0aee2a9b 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -203,12 +203,33 @@ impl AiMemoryServer {self}+ /// Variant of [`Self::with_consolidator`] that accepts a pre-built+ /// `Arc<Consolidator>`. Used when the same consolidator must be+ /// shared with another subsystem (e.g. the hook router's+ /// PreCompact branch) so both paths see the same handle.+ #[must_use]+ pub fn with_consolidator_arc(+ mut self,+ wiki: Wiki,+ llm: Arc<dyn LlmProvider>,+ consolidator: Arc<Consolidator>,+ ) -> Self {+ self.consolidator = Some(consolidator);+ self.llm = Some(llm);+ self.wiki = Some(wiki);+ self+ }+/// Full-text search the wiki via FTS5. Returns up to `limit` hits with/// HTML-marked snippets and a rank score.- #[tool(description = "Full-text search the long-term memory wiki via FTS5. \- Returns up to `limit` matching pages with HTML-marked snippets and a \- rank score (lower rank = better match). Only the latest version of \- each page is searched.")]+ #[tool(description = "Search the project's long-term memory wiki — \+ prior sessions, decisions, gotchas, architecture notes captured \+ by ai-memory across earlier runs. Call this BEFORE proposing \+ designs, BEFORE answering 'why does X work this way', and \+ whenever the user references prior work you don't recognise. \+ FTS5 + (when configured) hybrid RRF re-ranking. Returns up to \+ `limit` pages with HTML-marked snippets and a rank score \+ (lower rank = better match). Only latest page versions.")]async fn memory_query(&self,Parameters(args): Parameters<QueryArgs>,@@ -243,8 +264,11 @@ impl AiMemoryServer {/// Return the N most-recently-updated pages.#[tool(description = "Return the N most-recently-updated wiki pages \- (descending by updated_at). Useful for resuming a session: \- the agent can read the last few pages to see what was worked on.")]+ for this project (descending by updated_at). Call this at the \+ START of any session to see what the previous session was \+ working on — even when no explicit handoff exists. Cheap, fast, \+ no LLM cost. Pair with memory_query when you need to drill into \+ specifics.")]async fn memory_recent(&self,Parameters(args): Parameters<RecentArgs>,@@ -380,8 +404,11 @@ impl AiMemoryServer {/// Fetch the latest open handoff for this project (optionally filtered/// by cwd) and mark it accepted.#[tool(description = "Fetch the latest open handoff for this project \- and mark it accepted. Returns the summary + open questions + next \- steps so the agent can prepend them to the session context.")]+ and mark it accepted. The SessionStart hook already calls this \+ for you and prepends the result, so most sessions never need to \+ invoke it directly. Call it manually only when the user asks \+ 'where did we leave off?' or when you suspect a handoff was \+ missed. Returns summary + open questions + next steps.")]async fn memory_handoff_accept(&self,Parameters(args): Parameters<HandoffAcceptArgs>,diff --git a/crates/ai-memory-wiki/src/git.rs b/crates/ai-memory-wiki/src/git.rsindex 9b7e27c5..60c231d3 100644--- a/crates/ai-memory-wiki/src/git.rs+++ b/crates/ai-memory-wiki/src/git.rs@@ -76,6 +76,14 @@ impl GitAdapter {debug!("working tree clean; no commit");return Ok(None);}+ // Fresh repo with no HEAD yet: still skip the commit if there+ // is nothing staged. Otherwise we'd produce an "initial" commit+ // pointing at the empty tree, which surprises both `git log`+ // and our own callers.+ if repo.head().is_err() && index.len() == 0 {+ debug!("fresh repo, empty index; no commit");+ return Ok(None);+ }let tree = repo.find_tree(tree_oid).map_err(map_git_err)?;let sig = Signature::now(COMMIT_AUTHOR_NAME, COMMIT_AUTHOR_EMAIL).map_err(map_git_err)?;diff --git a/hooks/claude-code/session-start.sh b/hooks/claude-code/session-start.shindex 18637f8f..db193784 100755--- a/hooks/claude-code/session-start.sh+++ b/hooks/claude-code/session-start.sh@@ -1,10 +1,20 @@#!/bin/sh# Claude Code SessionStart hook.-# Reads the event JSON from stdin and forwards it to a running-# ai-memory server. Fire-and-forget: never blocks the agent.+#+# 1. Forwards the event JSON to the ai-memory server (fire-and-forget).+# 2. Synchronously fetches any pending cross-agent handoff and prints+# it to stdout — Claude Code prepends this to the session, so the+# next agent picks up where the previous one left off without the+# user having to ask.+#+# Both calls are capped at sub-second timeouts so a server outage+# never blocks startup. The hook always exits 0.SERVER="${AI_MEMORY_HOOK_URL:-http://127.0.0.1:49374}"-curl -s --max-time 0.5 \+PAYLOAD=$(cat)+echo "$PAYLOAD" | curl -s --max-time 0.5 \-X POST "$SERVER/hook?event=session-start&agent=claude-code" \-H "Content-Type: application/json" \--data-binary @- >/dev/null 2>&1 || true+curl -s --max-time 1.0 \+ "$SERVER/handoff?agent=claude-code" 2>/dev/null || trueexit 0diff --git a/hooks/codex/session-start.sh b/hooks/codex/session-start.shindex 20dc51a3..8cdf1c7b 100755--- a/hooks/codex/session-start.sh+++ b/hooks/codex/session-start.sh@@ -1,8 +1,15 @@#!/bin/sh-# codex session-start hook.+# codex SessionStart hook.+#+# Same shape as the claude-code variant: POST the event to /hook, then+# synchronously GET /handoff and echo the markdown so codex sees any+# pending cross-agent handoff at session start.SERVER="${AI_MEMORY_HOOK_URL:-http://127.0.0.1:49374}"-curl -s --max-time 0.5 \+PAYLOAD=$(cat)+echo "$PAYLOAD" | curl -s --max-time 0.5 \-X POST "$SERVER/hook?event=session-start&agent=codex" \-H "Content-Type: application/json" \--data-binary @- >/dev/null 2>&1 || true+curl -s --max-time 1.0 \+ "$SERVER/handoff?agent=codex" 2>/dev/null || trueexit 0diff --git a/hooks/opencode/session-start.sh b/hooks/opencode/session-start.shindex f2ef5eaa..f4a46a57 100755--- a/hooks/opencode/session-start.sh+++ b/hooks/opencode/session-start.sh@@ -1,8 +1,15 @@#!/bin/sh-# opencode session-start hook.+# opencode SessionStart hook.+#+# Same shape as the claude-code variant: POST the event to /hook, then+# synchronously GET /handoff and echo the markdown so opencode sees+# any pending cross-agent handoff at session start.SERVER="${AI_MEMORY_HOOK_URL:-http://127.0.0.1:49374}"-curl -s --max-time 0.5 \+PAYLOAD=$(cat)+echo "$PAYLOAD" | curl -s --max-time 0.5 \-X POST "$SERVER/hook?event=session-start&agent=open-code" \-H "Content-Type: application/json" \--data-binary @- >/dev/null 2>&1 || true+curl -s --max-time 1.0 \+ "$SERVER/handoff?agent=open-code" 2>/dev/null || trueexit 0