From c84d0d79ecdbda3da5428ab1926b1d89246748b1 Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Wed, 18 Nov 2026 12:15:32 +0000 Subject: [PATCH] docs: sync README and reliability notes with recent fixes --- README.md | 13 ++++++++----- assets/diagrams/pipeline.svg | 4 ++-- docs/reliability/compression-recovery.md | 2 +- docs/reliability/graph-search-budget.md | 2 +- scripts/readme-diagrams.ts | 4 ++-- 5 files changed, 14 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index be25d9645f..c33a7612ed 100644 --- a/README.md +++ b/README.md @@ -807,9 +807,9 @@ The [architecture diagrams](#architecture) show the same flow. PostToolUse hook fires -> Stable event ID, durable capture inbox, offline spool when unavailable -> Privacy filter (strip secrets, API keys) - -> Store raw observation - -> Synthetic compression by default - (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true) + -> Build and store a searchable synthetic observation + -> Optional LLM compression of retained source + (requires a provider + AGENTMEMORY_AUTO_COMPRESS=true; empty source is skipped) -> Vector embedding when an embedding provider is active -> Index in BM25, plus vectors when enabled @@ -836,7 +836,7 @@ Modeled on how human brains process memory, including sleep consolidation. | **Semantic** | Extracted facts and patterns | "What I know" | | **Procedural** | Workflows and decision patterns | "How to do it" | -Memories decay over time (Ebbinghaus curve). Frequently accessed memories strengthen. Stale memories auto-evict. Contradictions are detected and resolved. +Memories decay over time (Ebbinghaus curve). Frequently accessed memories strengthen. Stale memories auto-evict. Auto-forget checks contradictions only between memories with the same agent scope, excluding pairs with different explicit projects; an unscoped project can still be compared with a scoped one. ### What Gets Captured @@ -953,6 +953,8 @@ Three tool surfaces, smallest to largest: `AGENTMEMORY_TOOLS=core` trims visibil +`memory_save` accepts `concepts` and `files` as comma-separated strings or arrays of strings. Use `sourceObservationIds` (an array) to attach observation provenance and `ttlDays` (a positive number of days, including fractions) to set expiry. Invalid lists, non-positive TTLs and unrepresentable expiry dates are rejected. These fields also work through `POST /agentmemory/remember` and standalone MCP. In the standalone local fallback, expired memories are pruned during recall, smart search and export, with a deletion audit entry. +
Extended tools (54 total, the default surface) @@ -968,7 +970,7 @@ Three tool surfaces, smallest to largest: `AGENTMEMORY_TOOLS=core` trims visibil | `memory_team_feed` | Recent shared items | | `memory_audit` | Audit trail of operations | | `memory_governance_delete` | Delete with audit trail | -| `memory_snapshot_create` | Git-versioned snapshot | +| `memory_snapshot_create` | Git-versioned snapshot; state read failures return an error instead of saving an incomplete snapshot | | `memory_action_create` | Create work items with dependencies | | `memory_action_update` | Update action status | | `memory_frontier` | Unblocked actions ranked by priority | @@ -1251,6 +1253,7 @@ EMBEDDING_PROVIDER=local # Disable scheduled auto-forget and lesson/insight decay # AUTO_FORGET_ENABLED=false +# AUTO_FORGET_INTERVAL_MS=3600000 (60000–2147483647 ms; invalid values use 3600000) # LESSON_DECAY_ENABLED=false # INSIGHT_DECAY_ENABLED=false ``` diff --git a/assets/diagrams/pipeline.svg b/assets/diagrams/pipeline.svg index 0b29b40cd9..18ed5804f4 100644 --- a/assets/diagrams/pipeline.svg +++ b/assets/diagrams/pipeline.svg @@ -54,12 +54,12 @@ Observation 04 -raw, per session +synthetic, stored provenance stamp Compress 05 -synthetic default +retained source LLM opt-in Index diff --git a/docs/reliability/compression-recovery.md b/docs/reliability/compression-recovery.md index d372cd4580..5e753ad791 100644 --- a/docs/reliability/compression-recovery.md +++ b/docs/reliability/compression-recovery.md @@ -1,6 +1,6 @@ # Recovering failed observation compression -LLM compression is optional. With `AGENTMEMORY_AUTO_COMPRESS=true`, capture first stores a searchable synthetic observation with privacy-filtered source. A provider error, invalid response or interrupted worker leaves that observation available for search and records a pending or failed compression state. Capture acknowledgement means the observation was stored; it does not mean model compression succeeded. +LLM compression is optional. With `AGENTMEMORY_AUTO_COMPRESS=true`, capture first stores a searchable synthetic observation with privacy-filtered source. If no usable source remains, capture skips model compression and does not mark the observation pending. A provider error, invalid response or interrupted worker leaves that observation available for search and records a pending or failed compression state. Capture acknowledgement means the observation was stored; it does not mean model compression succeeded. Inspect a session before retrying: diff --git a/docs/reliability/graph-search-budget.md b/docs/reliability/graph-search-budget.md index 3939f8da66..61b0f9c893 100644 --- a/docs/reliability/graph-search-budget.md +++ b/docs/reliability/graph-search-budget.md @@ -4,7 +4,7 @@ Hybrid search allows 500 ms for optional graph enrichment after keyword and vect Cancellation prevents additional graph work after the request expires. Name, character, observation and adjacency postings avoid listing canonical graph scopes. Every request checks the active generation and index revision before returning graph evidence. Pending writes, import, mesh updates, reset or restore invalidate an in-flight view. Optional model context contains only titles of current observations authorized for the requested scope; graph properties and intermediate labels do not become model evidence. -The graph view returns at most 500 nodes and uses a separate budget of 2,048 reads and 4 MiB. Default pages follow indexed inventory order, not a global degree ranking. Filtered counts describe examined records when the response is truncated. Temporal and graph-node lookups also report partial results when their budgets or projection limits are reached. Graph statistics use maintained index counts; an unavailable index reports unknown counts rather than an empty graph. +The graph view returns at most 500 nodes and uses a separate budget of 2,048 reads and 4 MiB. If its byte budget is exhausted, it retains already collected nodes and edges with `truncated: true`, provided the final generation and revision checks still succeed. A changed index discards those results and returns a retry warning. Default pages follow indexed inventory order, not a global degree ranking. Filtered counts describe examined records when the response is truncated. Temporal and graph-node lookups also report partial results when their budgets or projection limits are reached. Graph statistics use maintained index counts; an unavailable index reports unknown counts rather than an empty graph. Existing stores require an [explicit legacy migration](graph-index-migration.md). Its initial discovery still reads complete scopes because the pinned engine cannot paginate them. Startup, indexed search, graph views, graph-node lookup and server status never start that scan, and automatic legacy boot compaction is deferred. Explicit maintenance, export, mesh push and snapshot creation remain bulk operations. The standalone MCP graph-stats resource still enumerates canonical graph scopes and requires a separate update; the bounded server graph-stats function does not. The index adds write and storage overhead, so a large migration needs a maintenance window and disk capacity. diff --git a/scripts/readme-diagrams.ts b/scripts/readme-diagrams.ts index bfab5ed190..6632e96bd4 100644 --- a/scripts/readme-diagrams.ts +++ b/scripts/readme-diagrams.ts @@ -325,8 +325,8 @@ function pipeline(f: DiagramFacts): string { box(0, 48, ["Event", "stable event ID", "dedupe on replay"], { n: 1 }); box(1, 48, ["Inbox", "durable capture", "spool if offline"], { n: 2 }); box(2, 48, ["Privacy filter", "keys, tokens, URLs", " tags"], { n: 3, hot: true }); - box(3, 48, ["Observation", "raw, per session", "provenance stamp"], { n: 4 }); - box(4, 48, ["Compress", "synthetic default", "LLM opt-in"], { n: 5 }); + box(3, 48, ["Observation", "synthetic, stored", "provenance stamp"], { n: 4 }); + box(4, 48, ["Compress", "retained source", "LLM opt-in"], { n: 5 }); box(5, 48, ["Index", "BM25 always", "vectors opt-in"], { n: 6 }); lane(170, "Stop · SessionEnd", "end of turn or session", "wash");