agenr 1.9.3 → 2.0.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-04-13
+
+Procedural memory foundation, sync and recall pipelines, and unified routing major release.
+
+### Added
+
+- **Procedural memory ships as a first-class corpus lane.** Agenr now includes the procedural memory model, repo-authored procedure assets, CLI ingest support, sync plumbing, and fixture-backed validation coverage for procedure-aware workflows.
+- **Dedicated procedure recall and eval support.** The release adds a procedure-specific recall pipeline plus recall-eval fixture provisioning so procedural knowledge can be exercised independently from durable entries and episodes.
+
+### Changed
+
+- **Unified recall is now procedure-aware.** Recall routing can now surface procedural memory alongside the existing durable and episodic paths, tightening the retrieval model for task and workflow queries.
+- **Repository guidance now documents procedural-memory ownership more explicitly.** Architecture and subsystem docs were refreshed to explain where procedural behavior belongs and how it fits the broader memory stack.
+
+### Validation
+
+Changes since last push to `origin/master`:
+
+- docs: refresh surgeon markdown
+- Add procedural memory v1 design spec
+- Add procedural memory phase 1 foundation
+- Add procedural memory phase 2 sync pipeline
+- Add dedicated procedure recall pipeline
+- Add procedure-aware unified recall routing
+
 ## [1.9.3] - 2026-04-12
 
 Supersession sweep-exhaustion and plugin-manifest alignment patch release.

package/README.md

@@ -24,6 +24,7 @@ What makes agenr different is the combination of local-first storage, semantic e
 
 - 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?"
+- Procedural memory: repo-authored YAML procedures synced into durable structured runbooks for repeatable how-to workflows.
 - 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.
@@ -137,19 +138,20 @@ Compatibility policy:
 
 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 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, claim-key lifecycle counts, proposal backlog, and 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.                                                                                                                       |
+| 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 ingest procedures [path]` | Sync repo-authored YAML procedures into procedural-memory revisions stored in the knowledge database.                                                             |
+| `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, claim-key lifecycle counts, proposal backlog, and 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`.
 
@@ -165,6 +167,9 @@ agenr ingest ~/.openclaw/agents/main/sessions/
 # Backfill episodic summaries
 agenr ingest episodes ~/.openclaw/agents/main/sessions/ --recent 30d
 
+# Preview procedure sync changes
+agenr ingest procedures --dry-run
+
 # Run the surgeon retirement pass (dry-run by default)
 agenr surgeon run --budget 2.00
 
@@ -189,12 +194,17 @@ Recall is a hybrid pipeline. Agenr embeds the query, retrieves candidates throug
 
 ## How Ingestion Works
 
-Agenr has two ingest pipelines over the same transcript corpus:
+Agenr has two transcript-ingest pipelines plus one repo-authored procedure sync path:
 
 - `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 procedures [path]` validates and syncs repo-authored procedural workflows from `procedures/` into the database.
+
+The two transcript 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. Procedure sync is different: it reads strict YAML authoring files, normalizes them into canonical stored revisions, and writes only when a procedure is new or semantically changed. Details: [docs/INGEST.md](./docs/INGEST.md), [docs/STORE.md](./docs/STORE.md), and [docs/PROCEDURES.md](./docs/PROCEDURES.md).
+
+## How Procedures Work
 
-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).
+Procedures are the durable how-to layer. They are authored in `procedures/` as reviewed YAML, normalized into canonical stored procedure revisions, and synced with `agenr ingest procedures [path]`. Phase 2 ships the authoring and sync path, including source-only updates and semantic supersession, but not yet procedure recall. For the current model, storage shape, and sync semantics, see [docs/PROCEDURES.md](./docs/PROCEDURES.md).
 
 ## How Episodes Work
 

package/dist/adapters/openclaw/index.js

@@ -7,7 +7,7 @@ import {
   parseTuiSessionKey,
   readOpenClawSessionsStore,
   storeEntriesDetailed
-} from "../../chunk-I6A6DPNF.js";
+} from "../../chunk-XD3446YW.js";
 import {
   EMBEDDING_DIMENSIONS,
   ENTRY_TYPES,
@@ -24,10 +24,10 @@ import {
   resolveEmbeddingModel,
   runUnifiedRecall,
   validateTemporalValidityRange
-} from "../../chunk-EMRMV2QR.js";
+} from "../../chunk-Y2BC7RCE.js";
 import {
   resolveClaimSlotPolicy
-} from "../../chunk-GUDCFFRV.js";
+} from "../../chunk-MEHOGUZE.js";
 
 // src/adapters/openclaw/index.ts
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
@@ -41,7 +41,7 @@ var ENTRY_TYPE_DESCRIPTION = "Knowledge type to store. Use fact for durable trut
 var EXPIRY_DESCRIPTION = "Lifetime bucket: core (always injected at session start, use sparingly), permanent (durable and recalled on demand), or temporary (short-horizon).";
 var UPDATE_EXPIRY_DESCRIPTION = `${EXPIRY_DESCRIPTION} Accepted values: ${EXPIRY_LEVELS.join(", ")}.`;
 var DEFAULT_RECALL_LIMIT = 10;
-var RECALL_MODES = ["auto", "entries", "episodes"];
+var RECALL_MODES = ["auto", "entries", "episodes", "procedures"];
 var RESULT_SUBJECT_LOG_LIMIT = 5;
 async function resolveTargetEntry(services, params, options = {}) {
   const id = readStringParam(params, "id");
@@ -89,7 +89,7 @@ function parseRecallMode(value) {
   if (value === void 0) {
     return void 0;
   }
-  if (value === "auto" || value === "entries" || value === "episodes") {
+  if (value === "auto" || value === "entries" || value === "episodes" || value === "procedures") {
     return value;
   }
   throw new Error(`Unsupported recall mode "${value}".`);
@@ -233,6 +233,10 @@ function formatUnifiedRecallResults(result) {
     lines.push(result.asOf);
     lines.push("");
   }
+  if (result.routing.queried.includes("procedures") || result.procedure || result.procedureCandidates.length > 0 || result.procedureNotices.length > 0) {
+    appendProcedureMatches(lines, result);
+    lines.push("");
+  }
   const renderEntriesFirst = result.routing.detectedIntent === "historical_state";
   if (renderEntriesFirst) {
     appendEntryMatches(lines, result);
@@ -256,6 +260,33 @@ function formatUnifiedRecallResults(result) {
   }
   return lines.join("\n");
 }
+function appendProcedureMatches(lines, result) {
+  lines.push("Procedure Matches");
+  if (!result.procedure && result.procedureCandidates.length === 0) {
+    lines.push("None.");
+  } else {
+    if (result.procedure) {
+      appendCanonicalProcedure(lines, result.procedure, result.procedureCandidates);
+    } else {
+      lines.push("Canonical procedure: none.");
+    }
+    const additionalCandidates = result.procedureCandidates.filter((candidate) => candidate.procedure.id !== result.procedure?.id);
+    if (additionalCandidates.length > 0) {
+      lines.push("Other Candidates");
+      for (const [index, candidate] of additionalCandidates.entries()) {
+        lines.push(
+          `${index + 1}. ${candidate.procedure.procedure_key} | ${candidate.procedure.title} | score ${candidate.score.toFixed(2)} | lexical=${candidate.scores.lexical.toFixed(2)} | vector=${candidate.scores.vector.toFixed(2)}`
+        );
+      }
+    }
+  }
+  if (result.procedureNotices.length > 0) {
+    lines.push("Procedure Notices");
+    for (const notice of result.procedureNotices) {
+      lines.push(`- ${notice}`);
+    }
+  }
+}
 function appendEntryMatches(lines, result) {
   lines.push("Entry Matches");
   if (result.projectedEntries.length === 0) {
@@ -294,6 +325,32 @@ function appendEpisodeMatches(lines, result) {
     lines.push(`   why_matched=${describeEpisodeMatch(episode)}`);
   }
 }
+function appendCanonicalProcedure(lines, procedure, candidates) {
+  const leadCandidate = candidates.find((candidate) => candidate.procedure.id === procedure.id);
+  lines.push(
+    leadCandidate ? `Canonical Procedure. ${procedure.procedure_key} | ${procedure.title} | score ${leadCandidate.score.toFixed(2)}` : `Canonical Procedure. ${procedure.procedure_key} | ${procedure.title}`
+  );
+  lines.push(`   goal=${procedure.goal}`);
+  appendLabeledList(lines, "when_to_use", procedure.when_to_use);
+  appendLabeledList(lines, "when_not_to_use", procedure.when_not_to_use);
+  appendLabeledList(lines, "prerequisites", procedure.prerequisites);
+  lines.push("   steps");
+  for (const [index, step] of procedure.steps.entries()) {
+    lines.push(`   ${index + 1}. [${step.kind}] ${step.instruction}`);
+    const stepDetails = formatProcedureStepDetails(step);
+    if (stepDetails.length > 0) {
+      for (const detail of stepDetails) {
+        lines.push(`      ${detail}`);
+      }
+    }
+  }
+  appendLabeledList(lines, "verification", procedure.verification);
+  appendLabeledList(lines, "failure_modes", procedure.failure_modes);
+  lines.push("   sources");
+  for (const source of procedure.sources) {
+    lines.push(`   - ${formatProcedureSource(source)}`);
+  }
+}
 function appendClaimTransitions(lines, result) {
   lines.push("Claim Transitions");
   if (result.claimTransitions.length === 0) {
@@ -314,11 +371,55 @@ function appendClaimTransitions(lines, result) {
   }
 }
 function formatUnifiedRecallLogSummary(result) {
+  const procedureCount = result.procedureCandidates.length;
+  const procedureSummary = result.procedure ? ` [procedure: ${JSON.stringify(truncate(result.procedure.title, 80))}]` : "";
   const entrySubjects = result.entries.map((entry) => entry.entry.subject.trim()).filter((subject) => subject.length > 0);
   const displayed = entrySubjects.slice(0, RESULT_SUBJECT_LOG_LIMIT).map((subject) => JSON.stringify(truncate(subject, 80)));
   const remaining = entrySubjects.length - RESULT_SUBJECT_LOG_LIMIT;
   const suffix = displayed.length === 0 ? "" : ` [entry subjects: ${displayed.join(", ")}${remaining > 0 ? `, ... and ${remaining} more` : ""}]`;
-  return `${result.episodes.length} episode${result.episodes.length === 1 ? "" : "s"}, ${result.entries.length} entr${result.entries.length === 1 ? "y" : "ies"}${suffix}`;
+  const entryEpisodeSummary = `${result.episodes.length} episode${result.episodes.length === 1 ? "" : "s"}, ${result.entries.length} entr${result.entries.length === 1 ? "y" : "ies"}`;
+  if (procedureCount === 0 && !result.procedure) {
+    return `${entryEpisodeSummary}${suffix}`;
+  }
+  return `${procedureCount} procedure candidate${procedureCount === 1 ? "" : "s"}, ${entryEpisodeSummary}${procedureSummary}${suffix}`;
+}
+function appendLabeledList(lines, label, values) {
+  lines.push(`   ${label}`);
+  if (values.length === 0) {
+    lines.push("   - none");
+    return;
+  }
+  for (const value of values) {
+    lines.push(`   - ${value}`);
+  }
+}
+function formatProcedureStepDetails(step) {
+  switch (step.kind) {
+    case "run_command":
+      return [`command=${step.command}`];
+    case "read_reference":
+      return [`ref=${formatProcedureSource(step.ref)}`];
+    case "inspect_state":
+      return [step.target ? `target=${step.target}` : void 0, step.query ? `query=${step.query}` : void 0].filter(
+        (value) => value !== void 0
+      );
+    case "edit_file":
+      return [`path=${step.path}`, `edit=${step.edit}`];
+    case "ask_user":
+      return [`prompt=${step.prompt}`];
+    case "invoke_tool":
+      return [step.tool ? `tool=${step.tool}` : void 0, step.arguments ? `arguments=${JSON.stringify(step.arguments)}` : void 0].filter(
+        (value) => value !== void 0
+      );
+    case "verify":
+      return step.checks.map((check) => `check=${check}`);
+    default:
+      return [];
+  }
+}
+function formatProcedureSource(source) {
+  const parts = [source.kind, source.label, source.path, source.locator].filter((value) => Boolean(value && value.length > 0));
+  return parts.join(" | ");
 }
 function formatTrace(entry, supersededBy, supersedes, claimFamily, recallEvents) {
   const slotPolicy = entry.claim_key ? claimFamily ? {
@@ -469,12 +570,12 @@ var RECALL_TOOL_PARAMETERS = {
   properties: {
     query: {
       type: "string",
-      description: "What you need to remember. Use a focused natural-language query rather than a broad 'everything' search. Phrase prior-state asks directly, for example 'what was the previous approach' or 'what changed from X to Y'."
+      description: "What you need to remember. Use a focused natural-language query rather than a broad 'everything' search. Phrase prior-state asks directly, for example 'what was the previous approach' or 'what changed from X to Y'. Phrase procedural asks directly, for example 'how do I rotate credentials' or 'what steps should I follow'."
     },
     mode: {
       type: "string",
       enum: [...RECALL_MODES],
-      description: "Recall mode: auto routes between exact entry recall, historical-state recall, and episodes; entries forces semantic recall; episodes forces temporal or semantic session recall."
+      description: "Recall mode: auto routes between exact entry recall, historical-state recall, procedural recall, and episodes; entries forces semantic recall; episodes forces temporal or semantic session recall; procedures forces procedural recall."
     },
     limit: {
       type: "integer",
@@ -512,7 +613,7 @@ function createAgenrRecallTool(ctx, servicesPromise, logger) {
   return {
     name: "agenr_recall",
     label: "Agenr Recall",
-    description: "Retrieve knowledge from agenr long-term memory. Use mode=auto for the normal path, including historical-state questions like what was the previous approach or what changed from X to Y; use mode=entries for exact facts and decisions; use mode=episodes for time-bounded 'what happened' questions. Time periods are parsed from the query text. Session-start recall is already handled automatically.",
+    description: "Retrieve knowledge from agenr long-term memory. Use mode=auto for the normal path, including historical-state questions like what was the previous approach or what changed from X to Y and procedural questions like how to do something or what steps to follow; use mode=entries for exact facts and decisions; use mode=episodes for time-bounded 'what happened' questions; use mode=procedures for canonical methods and checklists. Time periods are parsed from the query text. Session-start recall is already handled automatically.",
     parameters: RECALL_TOOL_PARAMETERS,
     async execute(_toolCallId, rawParams) {
       try {
@@ -559,6 +660,7 @@ function createAgenrRecallTool(ctx, servicesPromise, logger) {
         );
         const result = await runUnifiedRecall(request, {
           database: services.episodes,
+          procedures: services.procedures,
           recall: services.recall,
           embeddingAvailable: services.embeddingStatus.available,
           embeddingError: services.embeddingStatus.error,
@@ -588,6 +690,24 @@ function createAgenrRecallTool(ctx, servicesPromise, logger) {
           },
           ...result.asOf ? { asOf: result.asOf } : {},
           ...result.timeWindow ? { timeWindow: result.timeWindow } : {},
+          ...result.procedure ? {
+            procedure: {
+              id: result.procedure.id,
+              procedureKey: result.procedure.procedure_key,
+              title: result.procedure.title,
+              goal: result.procedure.goal
+            }
+          } : {},
+          procedures: result.procedureCandidates.map((candidate) => ({
+            id: candidate.procedure.id,
+            procedureKey: candidate.procedure.procedure_key,
+            title: candidate.procedure.title,
+            goal: candidate.procedure.goal,
+            score: candidate.score,
+            lexicalScore: candidate.scores.lexical,
+            vectorScore: candidate.scores.vector
+          })),
+          procedureNotices: result.procedureNotices,
           episodes: result.episodes.map((episode) => ({
             id: episode.episode.id,
             source: episode.episode.source,
@@ -1055,7 +1175,7 @@ function registerAgenrOpenClawTools(api, servicesPromise, logger) {
 var openclaw_plugin_default = {
   id: "agenr",
   name: "agenr",
-  version: "1.9.3",
+  version: "2.0.0",
   description: "agenr memory plugin for OpenClaw",
   kind: "memory",
   contracts: {
@@ -3193,6 +3313,7 @@ async function createAgenrOpenClawServices(config, options) {
     dbPath: resolvedConfig.dbPath,
     entries: runtimeServices.entries,
     episodes: runtimeServices.episodes,
+    procedures: runtimeServices.procedures,
     memory: runtimeServices.memory,
     embedding: runtimeServices.embedding,
     recall: runtimeServices.recall,
@@ -3229,6 +3350,7 @@ async function createRuntimeServices(dbPath, config, embeddingStatus, openClawCo
   return {
     entries: database,
     episodes: database,
+    procedures: database,
     memory: createOpenClawRepository(database, {
       claimSlotPolicyConfig: openClawContext.pluginConfig.memoryPolicy?.slotPolicies
     }),

package/dist/{chunk-I6A6DPNF.js → chunk-XD3446YW.js}

@@ -22,7 +22,7 @@ import {
   readOptionalString,
   readRequiredString,
   validateTemporalValidityRange
-} from "./chunk-EMRMV2QR.js";
+} from "./chunk-Y2BC7RCE.js";
 import {
   compactClaimKey,
   describeClaimKeyNormalizationFailure,
@@ -34,7 +34,7 @@ import {
   parseRelativeDate,
   resolveClaimSlotPolicy,
   validateExtractedClaimKey
-} from "./chunk-GUDCFFRV.js";
+} from "./chunk-MEHOGUZE.js";
 
 // src/adapters/openclaw/transcript/parser.ts
 import { createHash } from "crypto";