agenr 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## [1.6.0] - 2026-04-02
+
+Store nudge, memory guidance improvements, plugin rename, and dead code cleanup.
+
+### Added
+
+- **Store nudge system.** Mid-session memory prompting via `[MEMORY CHECK]` injection. When the agent goes N turns without storing to agenr, a nudge is injected via `prependContext` reminding it to review recent conversation for durable knowledge. Escalating message tone across nudge ordinals. Three-level store outcome classification (stored/skipped/failed) with separate tracking for explicit memory maintenance actions (`claimKey`, `supersedes`, `agenr_update`, `agenr_retire`). Configurable via `storeNudge.enabled`, `storeNudge.threshold` (default 8), and `storeNudge.maxPerSession` (default 5).
+- **`after_tool_call` hook.** New hook handler for real-time memory action detection. Synchronous state mutation (no async before write) to avoid races with OpenClaw's fire-and-forget dispatch. Classifies `agenr_store`, `agenr_update`, and `agenr_retire` tool calls.
+- **`MidSessionTracker`.** Separate per-session runtime state tracker for nudge logic, distinct from `SessionStartTracker`. Tracks turn counts, store counts, nudge counts, stored subjects (bounded to last 5), and three-level memory action timestamps. Includes session cleanup via TTL pruning.
+- **Session identity helper.** Shared `resolveSessionIdentityKey()` used by both trackers for consistent session key resolution.
+- **ESLint safety rules.** New eslint config with safety rules for the codebase.
+
+### Changed
+
+- **Improved memory guidance.** Tightened prompt section and store tool descriptions informed by Claude Code memory research. Includes success recording ("store validated wins, not just corrections"), compact exclusion filters, session-vs-durable distinction, and Rule → Why → How to apply structure hints for lessons and preferences.
+- **Plugin package renamed.** `@agenr/openclaw-plugin` → `@agenr/agenr-plugin` across all source, docs, tests, and config. Fixes the `deriveIdHint` compatibility warning — `agenr-plugin` matches the `{manifestId}-plugin` pattern.
+- **Non-first-turn `before_prompt_build` path.** Previously returned `undefined` immediately. Now handles mid-session nudge injection with skip guards for non-user triggers (heartbeat, cron, memory).
+
+### Removed
+
+- **Dead internal session filtering.** Removed `isInternalAgenrSession` guard and `INTERNAL_AGENR_SESSION_PREFIX` constant from `before-prompt-build.ts`. The `temp:agenr-*` session prefix is no longer used in v1 — internal worker sessions use different mechanisms.
+
+## [1.5.0] - 2026-04-01
+
+Temporal validity, claim extraction, surgeon supersession pass, and OpenClaw auth improvements.
+
+### Added
+
+- **Temporal validity schema.** New `valid_from`, `valid_to`, `claim_key`, `supersession_kind`, and `supersession_reason` columns on entries. Entries can now express when a fact is true in the world, how facts replace each other, and why. All columns are nullable and backward-compatible.
+- **Claim key extraction.** Automatic `claim_key` assignment at store time via LLM classification. Identifies the `entity/attribute` slot an entry occupies (e.g., `jim/home_city`, `agenr/default_model`). Runs as a best-effort pipeline stage — entries store normally if extraction fails or is disabled. Supports entity hint seeding from existing claim keys to prevent namespace drift. Configurable confidence threshold (default 0.8), eligible types (fact, preference, decision), and model override.
+- **Claim extraction in bulk ingest.** `agenr ingest` now runs batch claim extraction with configurable concurrency. Entries that already have a `claim_key` are skipped.
+- **Claim extraction model in CLI setup.** `agenr setup` and `agenr init` now include a "Claim extraction" stage in the model customization flow, alongside extraction, dedup, episode, and surgeon.
+- **Explicit supersession in store pipeline.** `agenr_store` accepts optional `supersedes`, `claim_key`, `valid_from`, and `valid_to` fields. When `supersedes` is provided, the old entry is atomically linked to the new one in a transaction.
+- **Surgeon supersession pass.** New `agenr surgeon run --pass supersession` finds entries that should be linked via `superseded_by` and creates those links with kind and reason. Candidate generation groups by shared claim key (highest confidence) or shared subject+type (medium confidence). Four new tools: `query_supersession_candidates`, `link_supersession`, `assign_claim_key`, `set_validity`. Hard rules enforced in code: no cross-type links, no milestone supersession, no core-expiry supersession.
+- **`claimExtractionModel` in OpenClaw plugin config.** Model override for claim extraction at store time, using OpenClaw's auth system.
+- **Lightweight OpenClaw LLM client.** New `createOpenClawLlmClient` factory resolves credentials from OpenClaw's `modelAuth.resolveApiKeyForProvider` and calls pi-ai's `completeSimple()` directly — no embedded agent runner overhead.
+
+### Changed
+
+- **OpenClaw continuity and episode summaries use lightweight LLM client.** Migrated from the heavy embedded agent runner (`runEmbeddedPiAgent` with temp directories and full agent lifecycle) to the new `createOpenClawLlmClient` for direct `completeSimple()` calls. Same auth, dramatically less overhead.
+- **OpenClaw claim extraction uses OpenClaw auth.** Store-time claim extraction now resolves credentials through OpenClaw's `modelAuth` system instead of agenr's CLI credentials. Fixes silent failures when agenr API keys aren't configured in OpenClaw-hosted contexts.
+- **Surgeon is now pass-aware.** The agent loop, prompt selection, tool selection, and completion guards are all driven by the pass type. Shared infrastructure (budget, audit, trace) remains pass-agnostic.
+- **Multi-surface session continuity.** Improved continuity resolution across different chat surfaces and session types.
+- **Architecture cleanup.** Internal refactoring across multiple phases for cleaner module boundaries.
+
+### Documentation
+
+- **Model config auth boundary.** New architecture doc and updated code comments clarifying the split between CLI-context models (agenr auth) and OpenClaw-context models (OpenClaw auth).
+- **Updated README.md and SURGEON.md** with supersession pass documentation.
+
 ## [1.4.0] - 2026-03-30
 
 Configurable summary models, surgeon personal knowledge protection, and documentation overhaul.
@@ -87,7 +137,7 @@ This release splits the OpenClaw plugin into its own publishable npm package and
 
 ### Added
 
-- **Standalone OpenClaw plugin package.** Publishes the OpenClaw integration separately as `@agenr/openclaw-plugin` while keeping the runtime plugin id as `agenr`.
+- **Standalone OpenClaw plugin package.** Publishes the OpenClaw integration separately as `@agenr/agenr-plugin` while keeping the runtime plugin id as `agenr`.
 - **Workspace-based build layout.** Adds `pnpm-workspace.yaml` and package-specific build wiring for the dedicated plugin package.
 - **Plugin packaging coverage.** Expands tests to verify the standalone plugin package metadata, manifest/version alignment, and that the plugin entry graph stays free of CLI-only code.
 - **Plugin-specific docs.** Adds package-level README content and OpenClaw docs covering the new install and local development paths.
@@ -95,7 +145,7 @@ This release splits the OpenClaw plugin into its own publishable npm package and
 ### Changed
 
 - **CLI package is no longer the plugin package.** The root `agenr` package now builds the CLI plus the plugin package, but no longer exposes OpenClaw plugin metadata itself.
-- **OpenClaw install instructions updated.** Installation now uses `openclaw plugins install @agenr/openclaw-plugin`, with migration guidance for existing users and unchanged plugin id/config keys.
+- **OpenClaw install instructions updated.** Installation now uses `openclaw plugins install @agenr/agenr-plugin`, with migration guidance for existing users and unchanged plugin id/config keys.
 - **Init flow updated for split packaging.** OpenClaw setup and installation flows now point at the standalone plugin package instead of the root package.
 
 ### Fixed

package/README.md

@@ -16,9 +16,9 @@ Local-first, durable memory infrastructure for AI agents.
 
 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, tasks, milestones, relationships, and session-level episodes 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, 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, 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.
+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/agenr-plugin`, and the CLI provides offline ingest, recall, and maintenance against that same database.
 
 ## Features
 
@@ -27,7 +27,7 @@ What makes agenr different is the combination of local-first storage, semantic e
 - 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 continuity summaries.
-- Surgeon retirement pass for corpus maintenance: inspect stale candidates, simulate recall impact, and retire semantically obsolete knowledge with audit history.
+- Surgeon maintenance passes for corpus health: run retirement cleanup for stale entries or supersession review for same-slot lineage, both 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.
@@ -57,7 +57,7 @@ Run `agenr init` again any time you want to re-run onboarding, reinstall the plu
 If you already have agenr configured, or you want to install the plugin separately:
 
 ```bash
-openclaw plugins install @agenr/openclaw-plugin
+openclaw plugins install @agenr/agenr-plugin
 openclaw gateway restart
 ```
 
@@ -66,7 +66,7 @@ The OpenClaw plugin id remains `agenr`, so `plugins.entries.agenr`, `plugins.slo
 After the plugin is installed, `openclaw plugins update agenr` continues to target that same plugin id.
 If `plugins.entries.agenr.config` is omitted, the plugin falls back to agenr's normal config resolution: `AGENR_CONFIG_PATH`, then `~/.agenr/config.json`, and the `dbPath` from that config or `~/.agenr/knowledge.db`.
 
-If you want to pin an exact plugin release, install a versioned package spec such as `openclaw plugins install @agenr/openclaw-plugin@1.0.1`.
+If you want to pin an exact plugin release, install a versioned package spec such as `openclaw plugins install @agenr/agenr-plugin@1.0.1`.
 
 For local development or a custom build path, run `pnpm build` first and point OpenClaw at the plugin package root:
 
@@ -92,7 +92,7 @@ If `config.json` is not next to `dbPath`, add `"configPath": "/path/to/config.js
 
 Migration note:
 
-- Existing users who originally installed the plugin from the `agenr` package should reinstall once with `openclaw plugins install @agenr/openclaw-plugin` so OpenClaw records the new npm package source.
+- Existing users who originally installed the plugin from the `agenr` package should reinstall once with `openclaw plugins install @agenr/agenr-plugin` so OpenClaw records the new npm package source.
 - After that reinstall, `openclaw plugins update agenr` should continue to work because updates key off the plugin id `agenr`.
 
 ## Configuration
@@ -111,16 +111,21 @@ 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`. Agenr no longer reads legacy `embeddingApiKey` or `apiKey` 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.                                                                        |
 | `dbPath`                         | Knowledge database location. Defaults to `~/.agenr/knowledge.db` unless overridden.                                                                                               |
 
-Important: when agenr is running as an OpenClaw plugin, session summaries use OpenClaw's configured LLM and auth, not agenr's. Agenr's config is still required for embeddings and for CLI-based ingestion/recall.
+Important: when agenr is running as an OpenClaw plugin, session summaries and store-time claim extraction use OpenClaw's configured LLM auth, not agenr's. Agenr's config is still required for embeddings and for CLI-based ingestion/recall.
+
+Compatibility policy:
+
+- Agenr only supports the current `config.json` shape. Move any legacy `apiKey` value into `credentials.openaiApiKey` or `credentials.anthropicApiKey`, move any `embeddingApiKey` value into `credentials.openaiApiKey`, then remove the legacy fields.
+- Agenr only supports fresh databases and databases already at the current schema version. Older schema versions are no longer auto-migrated at startup.
 
 ## What You Need
 
@@ -132,19 +137,19 @@ Important: when agenr is running as an OpenClaw plugin, session summaries use Op
 
 The CLI surface is still intentionally compact, but it now covers setup, recall, ingest, and corpus maintenance.
 
-| Command                        | What it does                                                                                                             |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
-| `agenr init`                   | Interactive first-run wizard: auth, model selection, OpenClaw detection, plugin install, and optional initial ingestion. |
-| `agenr setup`                  | Configure auth, model defaults, embeddings, and the agenr database path.                                                 |
-| `agenr recall <query>`         | Run the hybrid recall pipeline with optional temporal and type/tag filters.                                              |
-| `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.                                                                              |
+| Command                         | What it does                                                                                                                                                      |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agenr init`                    | Interactive first-run wizard: auth, model selection, OpenClaw detection, plugin install, and optional initial ingestion.                                          |
+| `agenr setup`                   | Configure auth, model defaults, embeddings, and the agenr database path.                                                                                          |
+| `agenr recall <query>`          | Run the hybrid recall pipeline with optional temporal and type/tag filters.                                                                                       |
+| `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 a surgeon maintenance pass. Defaults to retirement; use `--pass supersession` for lineage review. 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 <runId>` | 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`.
 
@@ -163,6 +168,9 @@ agenr ingest episodes ~/.openclaw/agents/main/sessions/ --recent 30d
 # Run the surgeon retirement pass (dry-run by default)
 agenr surgeon run --budget 2.00
 
+# Run the surgeon supersession pass
+agenr surgeon run --pass supersession --budget 2.00
+
 # Reset the database
 agenr db reset
 ```
@@ -184,7 +192,7 @@ Recall is a hybrid pipeline. Agenr embeds the query, retrieves candidates throug
 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?"
+- `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).
 
@@ -194,7 +202,7 @@ Episodes are session-level memory artifacts stored separately from durable entri
 
 ## 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).
+The surgeon is a maintenance system for the durable-memory corpus. Today it supports two passes: retirement, which reviews stale entries for conservative cleanup, and supersession, which links older entries to newer replacements without deleting history. `agenr surgeon run` is safe by default because it starts in dry-run mode; `--pass supersession` switches the workflow, and `--apply` is the explicit mutation switch. For runtime details, governance, and audit behavior, see [docs/SURGEON.md](./docs/SURGEON.md).
 
 ## Development
 
@@ -210,10 +218,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/agenr-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