Skip to content

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.lock
index 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.md
index 9d37a7fa..4a0df650 100644
--- a/README.md
+++ b/README.md
@@ -11,154 +11,283 @@
## Why this exists
LLM 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.
-
## License
Dual-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.rs
index 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.rs
index 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.toml
index 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 li
ai-memory-core.workspace = true
ai-memory-store.workspace = true
ai-memory-wiki.workspace = true
+ai-memory-consolidate.workspace = true
anyhow.workspace = true
thiserror.workspace = true
serde.workspace = true
diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rs
index 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.rs
index 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.
///
/// # Errors
diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rs
index 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.rs
index 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.sh
index 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 || true
exit 0
diff --git a/hooks/codex/session-start.sh b/hooks/codex/session-start.sh
index 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 || true
exit 0
diff --git a/hooks/opencode/session-start.sh b/hooks/opencode/session-start.sh
index 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 || true
exit 0