Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs(hooks): note the running-checkpoint race and owner attribution (#1229)
Victor Alencard20915e36571
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 23e1df41..c4b2a811 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -19,12 +19,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0redelivery. SessionEnd enqueue stays opt-in via`AI_MEMORY_CONSOLIDATE_ON_SESSION_END`; the worker now starts whenevera consolidator exists so checkpoint jobs still run when that flag is- off. The rewrite is attributed to the session owner recorded at session- start. With a provider, the checkpoint write still goes through- `consolidate` admission, so a refusing policy leaves no page and queues- nothing. A failed enqueue fails the event so the redelivery queues the- rewrite. A checkpoint still queued when the session ends runs once even- with the SessionEnd opt-in off. (#1229)+ off. The worker now runs every queued job, opt-in SessionEnd jobs+ included, as the session owner recorded at session start instead of+ anonymously: `consolidate` admission sees that owner, the page records+ them in `last_modified_by`, and with `[slots] per_user` on the rewrite's+ slot updates land in their namespace. With a provider, the checkpoint+ write still goes through `consolidate` admission, so a refusing policy+ leaves no page and queues nothing. A failed enqueue fails the event so+ the redelivery queues the rewrite. A checkpoint still queued when the+ session ends runs once even with the SessionEnd opt-in off. Without the+ opt-in, a session that ends while its checkpoint rewrite is still running+ keeps that rewrite as the latest page, which can leave out the end of the+ session; the SessionEnd summary stays reachable as the superseded+ version. (#1229)- Replaced the unmaintained YAML library (`serde_yaml` and its`unsafe-libyaml` parser, RUSTSEC-2024-0449) with `serde-saphyr`. The serverreads existing page frontmatter to exactly the same values as before. Onediff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rsindex fd5421cb..5e6a9704 100644--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@ -906,7 +906,7 @@ async fn run_session_consolidation_worker({Ok(job) => job,Err(error) => {- tracing::warn!(%error, "SessionEnd consolidation queue claim failed");+ tracing::warn!(%error, "session consolidation queue claim failed");tokio::select! {() = cancel.cancelled() => return,() = notify.notified() => {},@@ -939,13 +939,13 @@ async fn run_session_consolidation_worker(Ok(()) => info!(session = %session_id,generation,- "SessionEnd: session page was written by the agent; consolidation skipped",+ "session page was written by the agent; queued consolidation skipped",),Err(error) => tracing::warn!(%error,session = %session_id,generation,- "SessionEnd consolidation skip could not complete the queue job",+ "session consolidation skip could not complete the queue job",),}#[cfg(test)]@@ -957,7 +957,7 @@ async fn run_session_consolidation_worker(%error,session = %session_id,generation,- "could not read the session page before SessionEnd consolidation; consolidating",+ "could not read the session page before queued consolidation; consolidating",),}let actor = session_consolidation_actor(&reader, session_id).await;@@ -966,7 +966,7 @@ async fn run_session_consolidation_worker(let result = tokio::select! {() = cancel.cancelled() => {if let Err(error) = writer.release_session_consolidation(job).await {- tracing::warn!(%error, %session_id, generation, "failed to release SessionEnd consolidation during shutdown");+ tracing::warn!(%error, %session_id, generation, "failed to release session consolidation during shutdown");}return;}@@ -990,7 +990,7 @@ async fn run_session_consolidation_worker(%error,session = %session_id,generation,- "SessionEnd consolidation succeeded but queue completion failed",+ "session consolidation succeeded but queue completion failed",),},Err(error) => {@@ -1018,7 +1018,7 @@ async fn run_session_consolidation_worker(error = %store_error,session = %session_id,generation,- "failed to persist SessionEnd consolidation failure",+ "failed to persist session consolidation failure",);} else if terminal {tracing::error!(@@ -1026,7 +1026,7 @@ async fn run_session_consolidation_worker(session = %session_id,generation,attempts,- "SessionEnd LLM consolidation exhausted retries; heuristic page remains",+ "queued LLM consolidation exhausted retries; heuristic page remains",);} else {tracing::warn!(@@ -1034,7 +1034,7 @@ async fn run_session_consolidation_worker(session = %session_id,generation,attempts,- "SessionEnd LLM consolidation failed; queued for retry",+ "queued LLM consolidation failed; queued for retry",);}}@@ -1903,11 +1903,11 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {match tokio::time::timeout(SHUTDOWN_GRACE, task).await {Ok(Ok(())) => {}Ok(Err(error)) => {- tracing::warn!(%error, "SessionEnd consolidation worker join failed");+ tracing::warn!(%error, "session consolidation worker join failed");}Err(_) => tracing::warn!(grace_secs = SHUTDOWN_GRACE.as_secs(),- "SessionEnd consolidation worker did not stop within the shutdown \+ "session consolidation worker did not stop within the shutdown \grace period; exiting anyway"),}diff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex 51481e87..2ce5ca24 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -96,7 +96,7 @@ Why not LanceDB/Qdrant/Kuzu/CozoDB/SurrealDB?**LLM for consolidation passes:**- **Off by default**, behaves like agentmemory after #138's fix. Without a provider, the system still works: synthetic compression (rule-based), no LLM-generated summaries, no `memory_consolidate` page-rewrite.-- With a provider, LLM consolidation runs on PreCompact / PostCompaction, on demand via `memory_consolidate`, and at session end only when `AI_MEMORY_CONSOLIDATE_ON_SESSION_END=true` (off by default). A substantive session end always writes a rule-based summary page + handoff regardless, except that a session page the agent wrote itself through `memory_write_page` with the session's id (`consolidated_by: agent`) is kept in place of the summary and skipped by the consolidation worker; a session containing only `SessionStart` / `SessionEnd` boundaries closes without either artifact or provider work and releases any startup handoff bound to that receiver. PreCompact / PostCompaction write a rule-based `sessions/<id>.md` checkpoint on the hook request (and skip both the synth and the queue when the agent already wrote that page). Provider work for those checkpoints, and for opt-in SessionEnd, is persisted by observation generation and consumed outside the hook request by one bounded retrying worker, so client drain cancellation cannot lose it. The worker starts whenever a consolidator is configured; SessionEnd enqueue stays behind the opt-in flag. Checkpoint jobs require the session to still be open (`ended_at IS NULL`) when they are queued; SessionEnd jobs still require it to have ended. With a provider, the checkpoint write keeps the `consolidate` admission operation, so a refusing policy leaves no page and queues nothing. A failed enqueue fails the hook event and leaves its ingest key incomplete, so the redelivery queues the rewrite. A checkpoint job still pending at session end is superseded only by an opt-in SessionEnd job; without the opt-in it runs once over the ended session. The automatic handoff and completed-end watermark commit in one SQLite transaction; an already-ended keyed replay converges the remaining wiki commit, provider enqueue, and ingest-key completion. The completed end also stores the observation count it covered; a resumed session re-enters the end path only after that count advances, avoiding non-convergent wall-clock comparisons. Optional 6h maintenance timer.+- With a provider, LLM consolidation runs on PreCompact / PostCompaction, on demand via `memory_consolidate`, and at session end only when `AI_MEMORY_CONSOLIDATE_ON_SESSION_END=true` (off by default). A substantive session end always writes a rule-based summary page + handoff regardless, except that a session page the agent wrote itself through `memory_write_page` with the session's id (`consolidated_by: agent`) is kept in place of the summary and skipped by the consolidation worker; a session containing only `SessionStart` / `SessionEnd` boundaries closes without either artifact or provider work and releases any startup handoff bound to that receiver. PreCompact / PostCompaction write a rule-based `sessions/<id>.md` checkpoint on the hook request (and skip both the synth and the queue when the agent already wrote that page). Provider work for those checkpoints, and for opt-in SessionEnd, is persisted by observation generation and consumed outside the hook request by one bounded retrying worker, so client drain cancellation cannot lose it. The worker starts whenever a consolidator is configured; SessionEnd enqueue stays behind the opt-in flag. Checkpoint jobs require the session to still be open (`ended_at IS NULL`) when they are queued; SessionEnd jobs still require it to have ended. With a provider, the checkpoint write keeps the `consolidate` admission operation, so a refusing policy leaves no page and queues nothing. A failed enqueue fails the hook event and leaves its ingest key incomplete, so the redelivery queues the rewrite. A checkpoint job still pending at session end is superseded only by an opt-in SessionEnd job; without the opt-in it runs once over the ended session. A checkpoint job already running at session end keeps its lease and writes after the SessionEnd summary; without the opt-in nothing runs after it, so the latest page can leave out the end of the session while the summary stays reachable as the superseded version. The worker runs every job, SessionEnd included, as the session owner recorded at session start, so admission, `last_modified_by` and per-user slot namespacing see that owner rather than an anonymous actor. The automatic handoff and completed-end watermark commit in one SQLite transaction; an already-ended keyed replay converges the remaining wiki commit, provider enqueue, and ingest-key completion. The completed end also stores the observation count it covered; a resumed session re-enters the end path only after that count advances, avoiding non-convergent wall-clock comparisons. Optional 6h maintenance timer.- Providers implement `LlmProvider { complete(...); complete_structured(...) }`. The current provider and authentication matrix lives in [`ARCHITECTURE.md`](ARCHITECTURE.md); this design boundary also covers OpenAI-compatible endpoints such as Ollama, vLLM, and LM Studio.- **Native HTTP per provider**, no LiteLLM-equivalent. The cognee tracker (#2412/#2430/#2537/#2608/#2749/#2782/#2840/#2842) showed silent-kwarg-drop in a generic gateway is the #1 source of provider bugs. Each provider gets typed JSON that errors on unknown fields. It is hand-coded, but correct.- **Structured output via JSON schema, not XML, not Instructor-style wrapping.** Use each provider's native JSON-mode where available; for Anthropic, request a tool-use response with a typed schema. Validate with `serde_json` + `schemars`-derived schemas.diff --git a/docs/llm-providers.md b/docs/llm-providers.mdindex 15fa9f1a..9f193558 100644--- a/docs/llm-providers.md+++ b/docs/llm-providers.md@@ -19,7 +19,11 @@ queued after those deterministic writes and handled by one bounded serverworker, so hook drain latency does not cancel it. The worker starts whenever aconsolidator is configured; SessionEnd enqueue stays behind the opt-in flag.A checkpoint rewrite still queued when the session ends runs once anyway, even-with the flag off. Failed jobs retry with backoff and survive a server restart. A resumed native session is ended again only after its+with the flag off. One already running when the session ends finishes after the+SessionEnd summary and replaces it, so with the flag off the latest page can+leave out the end of the session; the summary stays reachable as the superseded+version. Every queued job runs as the session owner recorded at session start,+not anonymously. Failed jobs retry with backoff and survive a server restart. A resumed native session is ended again only after itsobservation generation advances; the persisted generation watermark makesduplicate SessionEnd delivery and system clock skew converge without repeatedprovider work. The end watermark and automatic handoff commit atomically, anddiff --git a/docs/usage.md b/docs/usage.mdindex 7e465a6b..417c49dc 100644--- a/docs/usage.md+++ b/docs/usage.md@@ -127,7 +127,11 @@ through `consolidate` admission, so a policy that refuses consolidationleaves no page and queues nothing. A rewrite still queued when thesession ends runs once over the whole session even with`AI_MEMORY_CONSOLIDATE_ON_SESSION_END` off, replacing the rule-based-summary; with the opt-in on, the SessionEnd job supersedes it. After+summary; with the opt-in on, the SessionEnd job supersedes it. Without+the opt-in, a session that ends while that rewrite is still running+keeps the rewrite as the latest page, so it can leave out the end of the+session; the SessionEnd summary stays reachable as the superseded+version. Aftercompaction, the agent can recover the summary via `memory_recent` eventhough its raw chat history was compacted away.