agenr 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [1.4.0] - 2026-03-30
+
+Configurable summary models, surgeon personal knowledge protection, and documentation overhaul.
+
+### Added
+
+- **Configurable continuity and episode summary models.** New `continuityModel` and `episodeModel` fields in the OpenClaw plugin config (`plugins.entries.agenr.config`) allow overriding the model used for continuity and episode summary generation independently. Falls back to the agent's primary model when unset. Use a fast model like `openai/gpt-5.4-mini` for these structured extraction tasks instead of burning Opus tokens.
+- **Personal knowledge protection in surgeon.** The surgeon retirement pass now has explicit guidance that personal facts (family, pets, hardware, contacts, identity, physical environment) are durable by nature. Only retires personal entries when contradicted or clearly duplicated — not for low recall or moderate importance.
+- **Corpus age awareness in surgeon.** The `_meta` table now tracks `last_bulk_ingest_at`, surfaced via `get_health_stats`. The surgeon heavily discounts `recall_count = 0` when the corpus was rebuilt within 30 days, preventing mass retirements of freshly ingested entries.
+- **New documentation: `docs/EPISODES.md`.** Comprehensive episodic memory docs covering lifecycle, CLI usage, recall modes, temporal window parser, search modes, embeddings, session discovery, and architecture.
+- **New documentation: `docs/SURGEON.md`.** Comprehensive surgeon docs covering tools, CLI commands, dry-run vs apply, budget governance, configuration, protection thresholds, and audit history.
+
+### Changed
+
+- **Continuity summary timeout increased.** Inner timeout bumped from 15s to 30s, read-time wrapper from 20s to 35s. Prevents timeout failures when using slower models for continuity summaries.
+- **Updated `docs/RECALL.md`.** Added unified recall mode routing (`auto`/`entries`/`episodes`), auto-routing rules, temporal window parser reference, and episode search pipeline documentation.
+- **Updated `docs/INGEST.md`.** Added episode ingest section with full flag documentation, behavior differences from entry ingest, session discovery, surface reconstruction, and practical examples.
+- **Updated `README.md`.** Added episodic memory and surgeon to features list, CLI commands table, and new "How Episodes Work" and "How the Surgeon Works" sections with doc links.
+
 ## [1.3.0] - 2026-03-30
 
 Episodic memory — session-level temporal recall for the brain.

package/README.md

@@ -14,18 +14,20 @@ Local-first, durable memory infrastructure for AI agents.
 
 ## What is agenr?
 
-agenr gives agents a persistent brain: a local SQLite database of durable knowledge that survives across sessions, tools, and agent restarts. Instead of relying on fragile prompt state or file-based scratch memory, agents can ingest transcripts, extract decisions and lessons, store them as typed entries, and recall them later with semantic search and memory-aware ranking.
+agenr gives agents a persistent brain: a local SQLite database of durable knowledge that survives across sessions, tools, and agent restarts. Instead of relying on fragile prompt state or file-based scratch memory, agents can ingest transcripts, extract decisions and lessons, store them as typed entries, generate episodic summaries of what happened, and recall them later with semantic search and memory-aware ranking.
 
-It exists because most agent runtimes forget everything important between sessions. Even when a tool has a built-in memory feature, it is often lossy, file-based, or tightly coupled to one surface. agenr keeps memory structured and queryable: facts, decisions, preferences, lessons, todos, events, and relationships live in one local store instead of getting flattened into prompt text.
+It exists because most agent runtimes forget everything important between sessions. Even when a tool has a built-in memory feature, it is often lossy, file-based, or tightly coupled to one surface. agenr keeps memory structured and queryable: facts, decisions, preferences, lessons, tasks, milestones, relationships, and session-level episodes live in one local store instead of getting flattened into prompt text.
 
-What makes agenr different is the combination of local-first storage, semantic embeddings, hybrid recall, and adapter-friendly architecture. The core is hexagonal, so multiple agent systems can share the same brain over time. Today the production adapter is the OpenClaw memory plugin, published separately as `@agenr/openclaw-plugin`, and the CLI provides offline ingest and recall against that same database.
+What makes agenr different is the combination of local-first storage, semantic embeddings, hybrid recall, episodic temporal memory, and adapter-friendly architecture. The core is hexagonal, so multiple agent systems can share the same brain over time. Today the production adapter is the OpenClaw memory plugin, published separately as `@agenr/openclaw-plugin`, and the CLI provides offline ingest, recall, and maintenance against that same database.
 
 ## Features
 
-- Hybrid recall: vector similarity, lexical FTS, temporal awareness, recency decay, and importance weighting.
+- Hybrid recall for durable knowledge: vector similarity, lexical FTS, temporal awareness, recency decay, and importance weighting.
+- Episodic memory: session-level summaries with temporal filtering and optional semantic episode search for questions like "what happened yesterday?"
 - LLM-powered knowledge extraction from conversation transcripts.
 - Semantic deduplication using exact hashes, normalized hashes, embeddings, and within-run clustering.
-- Session continuity with predecessor resolution, recent transcript tails, and LLM-generated session summaries.
+- Session continuity with predecessor resolution, recent transcript tails, and LLM-generated continuity summaries.
+- Surgeon retirement pass for corpus maintenance: inspect stale candidates, simulate recall impact, and retire semantically obsolete knowledge with audit history.
 - Agent tools for `store`, `recall`, `retire`, `update`, and `trace` through the OpenClaw plugin.
 - Native OpenClaw memory plugin that replaces OpenClaw's built-in memory slot.
 - Local-first storage with SQLite/libSQL. Memory stays on your machine; only model and embedding calls leave it.
@@ -46,7 +48,7 @@ It walks through:
 - model selection filtered by the auth method you chose
 - OpenAI embedding key setup
 - OpenClaw detection and optional plugin installation
-- session scanning and optional bulk ingestion of existing transcripts
+- session scanning and optional bulk ingestion of existing transcripts into durable entries and episodic summaries
 
 Run `agenr init` again any time you want to re-run onboarding, reinstall the plugin, or ingest another batch of existing sessions.
 
@@ -109,10 +111,10 @@ Key config fields:
 
 | Field                            | What it does                                                                                                                                                                      |
 | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `auth`                           | Authentication method: `openai-api-key`, `openai-subscription`, `anthropic-api-key`, `anthropic-oauth`, or `anthropic-token`.                                                     |
+| `auth`                           | Authentication method: `openai-api-key`, `openai-subscription`, `anthropic-api-key`, `anthropic-oauth`, or `anthropic-token`.                                                 |
 | `provider` / `model`             | Default LLM provider and model used for extraction tasks unless overridden.                                                                                                       |
 | `credentials`                    | Stored manual credentials. Today that can include `openaiApiKey`, `anthropicApiKey`, and `anthropicOauthToken`. The config file is written with locked-down permissions (`0600`). |
-| `credentials.openaiApiKey`       | OpenAI key used for embeddings, and also for extraction when `auth` is `openai-api-key`. Older configs may still rely on legacy `embeddingApiKey` or `apiKey` fallback fields.    |
+| `credentials.openaiApiKey`       | OpenAI key used for embeddings, and also for extraction when `auth` is `openai-api-key`. Older configs may still rely on legacy `embeddingApiKey` or `apiKey` fallback fields. |
 | `embeddingModel`                 | Embedding model. Defaults to `text-embedding-3-small`.                                                                                                                            |
 | `extractionModel` / `dedupModel` | Optional per-pipeline overrides so extraction and dedup can use different provider/model pairs.                                                                                   |
 | `extractionContext`              | Optional user context injected into extraction prompts to help the model decide what is worth remembering.                                                                        |
@@ -128,7 +130,7 @@ Important: when agenr is running as an OpenClaw plugin, session summaries use Op
 
 ## CLI Commands
 
-The current CLI surface is intentionally small. Today the `db` group only exposes `reset`.
+The CLI surface is still intentionally compact, but it now covers setup, recall, ingest, and corpus maintenance.
 
 | Command                        | What it does                                                                                                             |
 | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
@@ -138,6 +140,10 @@ The current CLI surface is intentionally small. Today the `db` group only expose
 | `agenr ingest <path>`          | Default durable-entry ingest shorthand. Equivalent to `agenr ingest entries <path>`.                                     |
 | `agenr ingest entries <path>`  | Bulk-ingest one file or directory of OpenClaw transcript files into durable knowledge entries.                           |
 | `agenr ingest episodes <path>` | Backfill episodic summaries from OpenClaw session transcripts, including rotated `.reset.*` and `.deleted.*` files.      |
+| `agenr surgeon run`            | Execute the surgeon retirement pass. Dry-run by default; add `--apply` to mutate the corpus.                            |
+| `agenr surgeon status`         | Show corpus health plus the latest surgeon run summary.                                                                  |
+| `agenr surgeon history`        | Show recent surgeon runs.                                                                                                |
+| `agenr surgeon actions <run>`  | Show the audit trail for one surgeon run.                                                                                |
 | `agenr db reset`               | Delete and recreate the knowledge database.                                                                              |
 
 The OpenClaw plugin also gives the agent five tools directly inside the runtime: `agenr_store`, `agenr_recall`, `agenr_retire`, `agenr_update`, and `agenr_trace`.
@@ -148,12 +154,15 @@ Examples:
 # Recall knowledge
 agenr recall "what decisions did we make about the API?"
 
-# Ingest transcripts
+# Ingest transcripts into durable entries
 agenr ingest ~/.openclaw/agents/main/sessions/
 
-# Backfill episode summaries
+# Backfill episodic summaries
 agenr ingest episodes ~/.openclaw/agents/main/sessions/ --recent 30d
 
+# Run the surgeon retirement pass (dry-run by default)
+agenr surgeon run --budget 2.00
+
 # Reset the database
 agenr db reset
 ```
@@ -172,7 +181,20 @@ Recall is a hybrid pipeline. Agenr embeds the query, retrieves candidates throug
 
 ## How Ingestion Works
 
-Ingestion is transcript-to-memory: parse OpenClaw JSONL transcripts, normalize them, choose whole-file or chunked extraction, run LLM extraction, validate the structured entries, deduplicate them within the ingest run, generate embeddings, and then persist surviving entries through the store pipeline. The current CLI ingest path is OpenClaw-transcript-specific. Details: [docs/INGEST.md](./docs/INGEST.md) and [docs/STORE.md](./docs/STORE.md).
+Agenr has two ingest pipelines over the same transcript corpus:
+
+- `agenr ingest entries <path>` extracts durable typed knowledge such as facts, decisions, preferences, lessons, milestones, and relationships.
+- `agenr ingest episodes <path>` generates one narrative summary per session so the brain can answer temporal questions like "what happened last week?"
+
+Both paths parse OpenClaw transcripts first, but they optimize for different outputs: entry ingest distills durable knowledge and runs semantic dedup across the whole ingest batch, while episode ingest does a session-by-session preflight pass, uses `sessions.json` metadata when available, reconstructs missing surface metadata for rotated files, and writes episodic summaries. Details: [docs/INGEST.md](./docs/INGEST.md) and [docs/STORE.md](./docs/STORE.md).
+
+## How Episodes Work
+
+Episodes are session-level memory artifacts stored separately from durable entries. They preserve temporal narrative: what happened in a session, when it happened, which agent/session it belonged to, and optionally an embedding for semantic episode search. Recall can route narrative or time-bounded questions toward episodes automatically, or combine episode and entry results in mixed mode. For implementation details and the episode recall model, see [docs/EPISODES.md](./docs/EPISODES.md).
+
+## How the Surgeon Works
+
+The surgeon is a maintenance pass for the durable-memory corpus. It evaluates retirement candidates, inspects related context, can simulate recall impact before mutation, and records runs plus per-action audit history in the database. `agenr surgeon run` is safe by default because it starts in dry-run mode; `--apply` is the explicit mutation switch. For runtime details, governance, and audit behavior, see [docs/SURGEON.md](./docs/SURGEON.md).
 
 ## Development
 
@@ -188,10 +210,10 @@ pnpm check        # format + lint + typecheck + test
 | Problem                                                           | What to check                                                                                                                                                                                                                        |
 | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `agenr init` cannot complete setup                                | Re-run `agenr setup` and verify the selected auth method is actually available. Subscription flows depend on the relevant external login being present, and non-OpenAI extraction setups still need a separate OpenAI embedding key. |
-| `openclaw plugins install @agenr/openclaw-plugin` fails           | Make sure the `openclaw` CLI is installed and on `PATH`. For local development, run `pnpm build` and use `plugins.load.paths` instead.                                                                                               |
-| `agenr recall` or `agenr_recall` fails with embedding/auth errors | Embeddings always use OpenAI. Confirm `credentials.openaiApiKey` is configured, or re-run `agenr setup` to set the embedding key explicitly.                                                                                         |
-| SQLite says the database is locked                                | Avoid running multiple writers against the same DB at once. Stop overlapping ingest/reset runs, restart the OpenClaw gateway if needed, then retry.                                                                                  |
-| OpenClaw does not pick up the plugin                              | Restart the gateway, confirm `plugins.slots.memory` is `agenr`, confirm `plugins.allow` contains `agenr`, and for dev installs confirm `plugins.load.paths` points at the built `packages/openclaw-plugin` directory.                |
+| `openclaw plugins install @agenr/openclaw-plugin` fails           | Make sure the `openclaw` CLI is installed and on `PATH`. For local development, run `pnpm build` and use `plugins.load.paths` instead.                                                                                            |
+| `agenr recall` or `agenr_recall` fails with embedding/auth errors | Embeddings always use OpenAI. Confirm `credentials.openaiApiKey` is configured, or re-run `agenr setup` to set the embedding key explicitly.                                                                                        |
+| SQLite says the database is locked                                | Avoid running multiple writers against the same DB at once. Stop overlapping ingest/reset runs, restart the OpenClaw gateway if needed, then retry.                                                                                 |
+| OpenClaw does not pick up the plugin                              | Restart the gateway, confirm `plugins.slots.memory` is `agenr`, confirm `plugins.allow` contains `agenr`, and for dev installs confirm `plugins.load.paths` points at the built `packages/openclaw-plugin` directory.               |
 
 ## License
 

package/dist/{chunk-2FKQCRGD.js → chunk-DSP74MEN.js}

@@ -947,6 +947,7 @@ var SCHEMA_VERSION = "4";
 var VECTOR_INDEX_NAME = "idx_entries_embedding";
 var EPISODE_VECTOR_INDEX_NAME = "idx_episodes_embedding";
 var BULK_WRITE_STATE_META_KEY = "bulk_write_state";
+var LAST_BULK_INGEST_META_KEY = "last_bulk_ingest_at";
 var CREATE_ENTRIES_TABLE_SQL = `
   CREATE TABLE IF NOT EXISTS entries (
     id TEXT PRIMARY KEY,
@@ -1386,8 +1387,28 @@ async function finalizeBulkWrites(db) {
       sql: "DELETE FROM _meta WHERE key = ?",
       args: [BULK_WRITE_STATE_META_KEY]
     });
+    await db.execute({
+      sql: `
+        INSERT INTO _meta (key, value)
+        VALUES (?, ?)
+        ON CONFLICT(key) DO UPDATE SET value = excluded.value
+      `,
+      args: [LAST_BULK_INGEST_META_KEY, (/* @__PURE__ */ new Date()).toISOString()]
+    });
   });
 }
+async function getLastBulkIngestAt(db) {
+  try {
+    const result = await db.execute({
+      sql: "SELECT value FROM _meta WHERE key = ? LIMIT 1",
+      args: [LAST_BULK_INGEST_META_KEY]
+    });
+    const row = result.rows[0];
+    return row?.value ? String(row.value) : null;
+  } catch {
+    return null;
+  }
+}
 async function getSchemaVersion(db) {
   try {
     const result = await db.execute("SELECT value FROM _meta WHERE key = 'schema_version' LIMIT 1");
@@ -2227,6 +2248,7 @@ export {
   getEntry,
   retireEntry,
   updateEntry,
+  getLastBulkIngestAt,
   createDatabase,
   DEFAULT_SURGEON_COST_CAP,
   DEFAULT_SURGEON_DAILY_COST_CAP,

package/dist/cli.js

@@ -20,6 +20,7 @@ import {
   deserializeTags,
   getAuthMethodDefinition,
   getEntry,
+  getLastBulkIngestAt,
   isAgenrAuthMethod,
   mapEntryRow,
   readBoolean,
@@ -34,7 +35,7 @@ import {
   retireEntry,
   updateEntry,
   writeConfig
-} from "./chunk-2FKQCRGD.js";
+} from "./chunk-DSP74MEN.js";
 import {
   parseRelativeDate,
   recall
@@ -7659,6 +7660,12 @@ function getSurgeonSystemPrompt() {
     "",
     "Use `source_file` and `source_context` as provenance clues. A transcript path, session file, or narrow snippet can explain why something looks like a temporary handoff or progress artifact. Provenance is evidence, not a retirement reason by itself.",
     "",
+    "## Corpus Age Awareness",
+    "",
+    "`get_health_stats` returns `lastBulkIngestAt` - the timestamp of the most recent bulk ingest (corpus rebuild). When the corpus has been recently rebuilt (within the last 30 days), treat `recall_count = 0` as carrying almost no signal. Every entry in a freshly rebuilt corpus starts at zero recalls regardless of its actual importance. In this window, weight content value, type durability, and subject uniqueness much more heavily than recall history.",
+    "",
+    "Even outside the rebuild window, never use `recall_count = 0` as the sole or primary retirement reason. Zero recall is a weak staleness signal that must be combined with other evidence: content obsolescence, clear supersession, or expired temporal relevance.",
+    "",
     "## Budget Awareness",
     "",
     "Use your budget carefully, but do not stop early just because a batch looks healthy. Keep paginating while candidates remain and your budget allows it. `complete_pass` will reject shallow completion when too much of the candidate pool remains unexplored.",
@@ -7718,6 +7725,20 @@ function getSurgeonRetirementPassPrompt() {
     "- `lesson` - Rarely retire unless the lesson is tied to a tool, pattern, or situation that no longer applies.",
     "- `relationship` - Retire when the relationship is clearly outdated or no longer real.",
     "",
+    "## Personal Knowledge",
+    "",
+    "Personal facts about the user - family members, pets, relationships, hardware, home setup, contact information, vehicles, physical environment, and identity details - are durable by nature even when importance is moderate. These entries represent the user's life context, not transient project state. They have lasting retrieval value because future sessions need this context to be helpful and personable.",
+    "",
+    "Retire personal knowledge entries only when:",
+    "- Explicitly contradicted by a newer entry (for example, a pet has passed away or a family member has moved)",
+    "- The entry is a clear duplicate of another active entry with identical or better coverage",
+    "",
+    "Do NOT retire personal knowledge entries because:",
+    "- They have low or zero recall count",
+    "- They have moderate importance (5-7)",
+    "- They lack project tags",
+    "- They seem like trivia - if it's about the user's life, it is not trivia to them",
+    "",
     "## Common Retirement Patterns",
     "",
     "- Old unrecalled temporaries",
@@ -7726,6 +7747,12 @@ function getSurgeonRetirementPassPrompt() {
     "- Resolved problems and obsolete workarounds",
     "- Older entries that are clearly covered better by newer entries on the same subject or cluster",
     "",
+    "## What Looks Like a Pattern But Is Not",
+    "",
+    "- Personal facts with zero recall - these are the user's life, not expired project context",
+    "- Hardware, infrastructure, and environment details - these have ongoing operational value",
+    "- Contact information and identity details - the user expects the system to know these",
+    "",
     "Use `source_file` and `source_context` to judge whether an entry came from a narrow session artifact, a handoff, a progress note, or a durable source. Provenance can explain why a memory existed and whether it was meant to last.",
     "",
     "## Budget Awareness",
@@ -8035,18 +8062,20 @@ function createHealthStatsTool(deps) {
     description: "Inspect current corpus health and the latest surgeon run summary.",
     parameters: GET_HEALTH_STATS_SCHEMA,
     async execute() {
-      const [health, lastRun] = await Promise.all([
+      const [health, lastRun, lastBulkIngestAt] = await Promise.all([
         getSurgeonHealthStats(deps.executor, {
           protectRecalledDays: deps.protection.protectRecalledDays,
           protectMinImportance: deps.protection.protectMinImportance,
           now: deps.now()
         }),
-        getLastSurgeonRun(deps.executor)
+        getLastSurgeonRun(deps.executor),
+        getLastBulkIngestAt(deps.db)
       ]);
       return toolResult({
         now: deps.now().toISOString(),
         health,
-        lastRun
+        lastRun,
+        lastBulkIngestAt
       });
     }
   };
@@ -8641,6 +8670,7 @@ async function runSurgeon(options, deps) {
       budgetTracker
     });
     const tools = createSurgeonTools({
+      db: deps.db,
       executor: deps.db,
       runId,
       project: options.project,

package/dist/internal-recall-eval-server.js

@@ -9,7 +9,7 @@ import {
   readConfig,
   resolveEmbeddingApiKey,
   resolveEmbeddingModel
-} from "./chunk-2FKQCRGD.js";
+} from "./chunk-DSP74MEN.js";
 import {
   recall
 } from "./chunk-EUPZHNOY.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenr",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Agent memory - local-first knowledge infrastructure for AI agents",
   "type": "module",
   "bin": {