@agenr/openclaw-plugin 0.13.0 → 0.13.2

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## [0.13.2] - 2026-03-23
+
+### Surgeon
+
+- **Continuation loop prevents early exit.** If the surgeon model stops without calling `complete_pass` and has >10% budget remaining, a continuation prompt is injected to push it back to work. Up to 3 nudges before allowing exit. Eliminates the "surgeon quits at 1% budget" problem.
+- **Lowered default dedup similarity threshold from 0.82 to 0.60.** The threshold controls candidate surfacing, not merge execution — the surgeon agent still makes every merge decision. Lower threshold surfaces more candidates for review on large corpora.
+- **`reset` parameter for `query_dedup_clusters` and `query_contradiction_candidates`.** Query parameters are no longer permanently frozen after the first call. Pass `reset: true` to clear cached clusters and rebuild at a new threshold. Lets the surgeon start wide and narrow if noisy.
+- **Strengthened auto sweep prompts.** Contradictions phase always runs proactive scan (no more skipping when pending conflicts = 0). Budget discipline section added — surgeon must keep working while budget remains. Retirement throughput expectations: 500+ candidates on a 3K corpus, not 100.
+- **Dedup threshold guidance in prompts.** Surgeon is told the default is deliberately low, and can raise it via reset if too noisy.
+
+## [0.13.1] - 2026-03-23
+
+### MCP Server
+
+- **`agenr_store` tool added to MCP surface.** MCP consumers (Claude Desktop/Cowork, Claude Code, etc.) can now make structured memory writes with explicit type, subject, importance, expiry, tags, project, and scope — matching the fidelity of OpenClaw's store tool.
+- **Enriched tool descriptions with embedded doctrine.** All 5 MCP tool descriptions (`agenr_recall`, `agenr_store`, `agenr_extract`, `agenr_retire`, `agenr_update`) now carry usage guidance directly in their metadata — when to recall, query tips, importance calibration, lifetime selection, what to store vs. not store. MCP consumers no longer need external instruction files to use memory well.
+- **Fixed `scope` persistence bug.** Manual store writes were not persisting the `scope` field due to a missing column in the insert path. Fixed in the shared store persistence layer.
+
+### Surgeon
+
+- **Proactive contradiction discovery.** Surgeon can now discover contradictions proactively during sweeps, rather than only resolving pre-flagged conflicts.
+- **Supersession scan.** New surgeon pass identifies entries that have been superseded by newer, more complete information.
+- **Contradictions pass and auto sweep.** Combined contradictions + auto multi-pass mode where a single agent loop has all tools from all passes registered simultaneously.
+- **Dedup pass.** Dedicated surgeon dedup pass for identifying and merging near-duplicate entries.
+- **Graceful abort.** Surgeon now handles abort signals gracefully and removes artificial loop caps.
+- **Paginated retirement.** Retirement pass now paginates to handle large corpora without memory pressure.
+- **Inspect provenance.** New surgeon tool for inspecting entry provenance chains.
+- **Prompt loading fix.** Fixed surgeon prompt loading for bundled distribution.
+
+### Infrastructure
+
+- **Removed `agenr maintain` and `agenr consolidate` commands.** Surgeon is now the sole corpus-health entry point. Replace any cron jobs or scripts with `agenr surgeon run`.
+- **Watcher interval floor.** Enforced minimum watcher polling interval to prevent excessive resource usage.
+- **Default model migration.** Migrated defaults to gpt-5.4 models.
+- **Surgeon workflow limits and budget defaults.** Increased defaults for production workloads.
+
+## [0.13.0] - 2026-03-22
+
+### Architecture
+
+- **Hexagonal architecture restructure.** Complete reorganization of the codebase into a modular monolith with hexagonal (ports & adapters) architecture. `src/` now has four top-level directories: `modules/`, `shared/`, `edge/`, and `runtime/`.
+- **Five bounded context modules.** `recall`, `store`, `ingestion`, `surgeon`, and `eval` — each with `domain/`, `application/`, `ports/`, and `adapters/` layers.
+- **OpenClaw plugin as edge adapter.** Moved to `src/edge/openclaw/` with internal hex layering (`domain/`, `application/`, `adapters/`), alongside CLI, MCP, and watch edge adapters.
+- **Eliminated `src/memory/`.** The awkward middle layer between app and db is gone. Recall orchestration moved to the recall module; store pipeline moved to the store module.
+- **Eliminated `src/domain/`, `src/app/`, `src/prompts/`, `src/adapters/`.** Each module now owns its own domain logic, application workflows, and prompt templates.
+- **Runtime consolidation.** Collapsed 31 `*-defaults.ts` wiring files into 8 focused composition roots — one per module plus shared infrastructure.
+- **Module boundary tests.** New architecture boundary tests enforce: domain purity, no cross-module internal imports, ports-only cross-module communication.
+- **Operations owner matrix.** DB utility workflows assigned to owning modules or shared operations (`context/` → recall, `classify-entries/` → store, `clusters/` → surgeon, `watcher-report/` and `session-store-metrics/` → `src/shared/operations/`). Only genuinely cross-module admin tooling remains in `src/shared/operations/`.
+- **App-boundary allowlist dropped to zero.** All previously allowlisted cross-layer imports are now legitimate within-module imports or port-mediated cross-module calls.
+
+### Corpus Health
+
+- **Surgeon is now the sole corpus-health entry point.** Removed `agenr maintain` and standalone `agenr consolidate`. `agenr surgeon run` now owns deterministic cleanup, quality evolution, vector integrity checks, retirement, dedup/merge, and contradiction resolution.
+- **Maintenance and consolidation internals absorbed into surgeon.** Deterministic pre/post steps now run inside surgeon workflows, and clustering/merge infrastructure moved under `src/modules/surgeon/application/clustering/`.
+- **Migration note.** Replace any cron jobs or scripts invoking `agenr maintain` or `agenr consolidate` with `agenr surgeon run`.
+
 ## [0.12.3] - 2026-03-22
 
 ### Fixed

package/README.md

@@ -34,7 +34,7 @@ That's it. The interactive wizard handles everything: auth setup, platform detec
 - **Extract** - An LLM reads your transcripts and pulls out structured entries. Smart filtering removes noise (tool calls, file contents, boilerplate - about 80% of a typical session) before the LLM sees it. Hedged or unverified agent claims are capped at importance 5 with an `unverified` tag.
 - **Store** - Entries get embedded and compared against existing knowledge. Near-duplicates reinforce existing entries. New information gets inserted. Online dedup catches copies in real-time.
 - **Recall** - Semantic search plus memory-aware ranking. Entries you recall often score higher. Stale entries decay. Contradicted entries get penalized.
-- **Consolidate** - Periodic cleanup: rule-based expiry first, then optional LLM-assisted merging for entries that say the same thing differently.
+- **Surgeon** - Corpus health maintenance: deterministic cleanup, quality evolution, vector integrity checks, and LLM-assisted retirement, dedup, and contradiction resolution.
 
 ```text
 Transcript -> Filter -> Extract -> Store -> Recall
@@ -48,7 +48,7 @@ Transcript -> Filter -> Extract -> Store -> Recall
 An **OpenAI API key** for embeddings (`text-embedding-3-small`). Embeddings cost fractions of a penny per operation - a full ingestion of 100+ session transcripts runs about $0.10 total.
 
 For the LLM extraction step, AGENR supports:
-- **OpenAI API key** (recommended) - `gpt-4.1` is highly recommended for best extraction quality; `gpt-4.1-mini` is the default and works well if cost is a concern; `gpt-4.1-nano` is the budget option
+- **OpenAI API key** (recommended) - `gpt-5.4-mini` is the default baseline and recommended balance of quality and cost; `gpt-5.4` is the higher-quality option and the default surgeon model; `gpt-4.1-mini` remains available as a lower-cost fallback
 - **OpenAI Pro subscription** - no API key needed
 - **Anthropic Claude subscription** - no API key needed
 
@@ -133,7 +133,7 @@ Adds instructions to `~/.codeium/windsurf/memories/global_rules.md` and wires `.
 agenr init   # auto-detects platform, falls back to generic AGENTS.md
 ```
 
-Or start `agenr mcp` as a stdio MCP server and configure it in your tool's MCP settings manually. Your agent gets `agenr_recall`, `agenr_extract`, `agenr_retire`, and `agenr_update` as tools.
+Or start `agenr mcp` as a stdio MCP server and configure it in your tool's MCP settings manually. Your agent gets `agenr_recall`, `agenr_store`, `agenr_extract`, `agenr_retire`, and `agenr_update` as tools.
 
 ## How Memory Works
 
@@ -179,12 +179,12 @@ When a session ends, the plugin writes a handoff using a fallback-first strategy
 
 See [docs/OPENCLAW.md](./docs/OPENCLAW.md) for the current startup flow and [docs/OPENCLAW_HANDOFFS.md](./docs/OPENCLAW_HANDOFFS.md) for the detailed handoff lifecycle.
 
-### Consolidation
+### Corpus Health
 
-Periodic cleanup merges near-duplicates and expires stale entries. Run manually or let the init wizard prompt you after a bulk ingest:
+The surgeon is the single corpus-health entry point. It runs deterministic pre-steps first, then performs the selected semantic pass. A bare run defaults to a full `auto` sweep:
 
 ```bash
-agenr consolidate
+agenr surgeon run --apply
 ```
 
 ## Advanced
@@ -242,7 +242,7 @@ If you prefer manual MCP setup over `agenr init`, start the stdio server:
 agenr mcp
 ```
 
-This exposes four MCP tools: `agenr_recall`, `agenr_extract`, `agenr_retire`, and `agenr_update`. Persistent session capture comes from watcher ingestion and platform integrations rather than an MCP `agenr_store` tool.
+This exposes five MCP tools: `agenr_recall`, `agenr_store`, `agenr_extract`, `agenr_retire`, and `agenr_update`. Use `agenr_store` for precise structured writes. Watcher ingestion and platform integrations still remain useful for transcript-scale capture.
 
 ## Commands
 
@@ -262,7 +262,7 @@ This exposes four MCP tools: `agenr_recall`, `agenr_extract`, `agenr_retire`, an
 | `agenr watcher install` | Install background watch daemon (macOS launchd) |
 | `agenr watcher status` | Show daemon status (running/stopped, pid, watched file, recent logs) |
 | `agenr watcher logs` | Stream or show recent daemon logs |
-| `agenr consolidate` | Clean up and merge near-duplicates |
+| `agenr surgeon run` | Run corpus-health maintenance: cleanup, quality evolution, vector checks, and retirement/dedup/contradictions |
 | `agenr benchmark` | Run extraction against benchmark fixtures and score results |
 | `agenr context` | Generate context file for AI tool integration |
 | `agenr health` | Show database health and forgetting candidates |
@@ -286,7 +286,7 @@ Deep dive: [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)
 
 The core pipeline is stable and tested. We use it daily managing thousands of knowledge entries across OpenClaw sessions.
 
-**Shipped:** extraction, storage, recall (semantic + browse), MCP integration, online dedup, consolidation, smart filtering, live watching, daemon mode, cross-session handoff (LLM-summarized), three-phase context injection, interactive init wizard, cost estimation, DB isolation, benchmarking.
+**Shipped:** extraction, storage, recall (semantic + browse), MCP integration, online dedup, surgeon corpus health passes, smart filtering, live watching, daemon mode, cross-session handoff (LLM-summarized), three-phase context injection, interactive init wizard, cost estimation, DB isolation, benchmarking.
 
 **Next:** GUI Management Console (browse, search, and curate your knowledge database visually), Cursor live signals, Claude Code UserPromptSubmit adapter, transitive project dependencies.
 
@@ -305,7 +305,7 @@ For the product thesis, see [docs/vision.md](./docs/vision.md).
 | `agenr init` wizard fails to detect platform | Pass `--platform openclaw` (or `codex`, `claude-code`, etc.) explicitly |
 | Plugin install fails during wizard | Run `openclaw plugins install agenr` manually, then `openclaw gateway restart` |
 | Embeddings fail | Set `OPENAI_API_KEY` env var or `agenr config set-key openai <key>` |
-| Database locked | Wait for consolidation to finish, or check `~/.agenr/consolidation.lock` |
+| Database locked | Wait for the active write-heavy command to finish (`agenr ingest --bulk`, `agenr surgeon run --apply`, etc.) and retry |
 | Recall returns nothing after force-kill | `agenr db rebuild-index` (vector index corruption) |
 | Extraction fails mid-file | Retry - dedup skips already-stored entries |
 | Stale handoff entries persist | Run `agenr recall --browse --since 1d` to check, then `agenr retire --id <id>` |