agenr 3.0.0 → 3.1.0

package/README.md

@@ -18,7 +18,7 @@ agenr gives agents a persistent brain: a local SQLite database of durable knowle
 
 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/agenr-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 host adapters are the OpenClaw memory plugin (`@agenr/agenr-plugin`) and the Skeln extension (`@agenr/skeln-plugin`). The CLI provides offline ingest, recall, and maintenance against that same database.
 
 ## Features
 
@@ -28,11 +28,12 @@ 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 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.
+- Surgeon maintenance passes for corpus health: claim-key quality, proposal resolution, supersession review, and retirement cleanup, all with audit history.
+- Agent tools for durable memory through the OpenClaw plugin (`store`, `recall`, `retire`, `update`, and `trace`) and the Skeln plugin (`store`, `recall`, `update`, `work`, and goal aliases).
 - Native OpenClaw memory plugin that replaces OpenClaw's built-in memory slot.
+- Skeln extension with working-memory tools, goal aliases, and shared recall/store semantics.
 - Local-first storage with SQLite/libSQL. Memory stays on your machine; only model and embedding calls leave it.
-- Designed for multi-agent systems so future adapters can share the same database.
+- Designed for multi-agent systems so OpenClaw, Skeln, and future adapters can share the same database.
 
 ## Quick Start - The Recommended Way
 
@@ -67,7 +68,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/agenr-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@3.0.0`.
 
 For local development or a custom build path, run `pnpm build` first and point OpenClaw at the plugin package root:
 
@@ -96,6 +97,17 @@ Migration note:
 - 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`.
 
+## Quick Start - Skeln Plugin (manual)
+
+If you use Skeln instead of OpenClaw, install the Skeln extension after configuring agenr:
+
+```bash
+pnpm link --global ./packages/skeln-plugin
+skeln extension add @agenr/skeln-plugin
+```
+
+The Skeln extension id is also `agenr`, so runtime config uses `extensions.settings.agenr.*`. For packaging, config, tool surface, and local development details, see [docs/SKELN-PLUGIN.md](./docs/SKELN-PLUGIN.md).
+
 ## Configuration
 
 `agenr init` and `agenr setup` handle configuration interactively. By default, agenr stores config at `~/.agenr/config.json` and the database at `~/.agenr/knowledge.db`.
@@ -138,23 +150,31 @@ 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 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.                                                                                                                       |
+| 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 trace`                       | Inspect one entry's provenance and claim-family lineage by id, subject, or `--last`.                                                                                   |
+| `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 surgeon maintenance. Defaults to the autonomous multi-pass sequence; use `--pass <type>` for one pass. 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 surgeon backlog`             | List open surgeon proposals across runs.                                                                                                                               |
+| `agenr surgeon proposals <runId>`   | Show proposals recorded for one surgeon run.                                                                                                                           |
+| `agenr surgeon review <proposalId>` | Apply or reject one open proposal.                                                                                                                                     |
+| `agenr scenarios list`              | List repo-local claim-key sandbox scenarios.                                                                                                                           |
+| `agenr scenarios run`               | Run one or more claim-key sandbox scenarios.                                                                                                                           |
+| `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`.
 
+The Skeln plugin exposes seven tools: `agenr_store`, `agenr_recall`, `agenr_update`, `agenr_work`, `get_goal`, `create_goal`, and `update_goal`. It does not expose `agenr_retire` or `agenr_trace`.
+
 Examples:
 
 ```bash
@@ -170,12 +190,15 @@ 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)
+# Run the default autonomous surgeon sequence (dry-run by default)
 agenr surgeon run --budget 2.00
 
-# Run the surgeon supersession pass
+# Run one explicit surgeon pass
 agenr surgeon run --pass supersession --budget 2.00
 
+# Inspect the latest stored entry
+agenr trace --last
+
 # Reset the database
 agenr db reset
 ```
@@ -184,7 +207,7 @@ agenr db reset
 
 - Hexagonal structure: `src/core/` contains pure logic and `src/adapters/` contains infrastructure.
 - The core never imports from adapters or CLI code.
-- OpenClaw, the CLI, and future adapters all target the same underlying memory brain.
+- OpenClaw, Skeln, the CLI, and future adapters all target the same underlying memory brain.
 
 See [AGENTS.md](./AGENTS.md) for the full architecture and repository conventions.
 
@@ -204,7 +227,7 @@ The two transcript paths parse OpenClaw transcripts first, but they optimize for
 
 ## How Procedures Work
 
-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).
+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]`. Procedure recall is live through unified host-plugin `agenr_recall` and before-turn suggestion, but the standalone CLI `agenr recall` command still targets entry recall only. For the current model, storage shape, sync semantics, and read surfaces, see [docs/PROCEDURES.md](./docs/PROCEDURES.md).
 
 ## How Episodes Work
 
@@ -212,7 +235,7 @@ Episodes are session-level memory artifacts stored separately from durable entri
 
 ## How the Surgeon Works
 
-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).
+The surgeon is a maintenance system for the durable-memory corpus. Four passes are implemented today: `claim_key_quality`, `proposal_resolution`, `supersession`, and `retirement`. `agenr surgeon run` defaults to an autonomous sequence across those passes and is safe by default because it starts in dry-run mode; `--pass <type>` runs one pass, and `--apply` is the explicit mutation switch. For runtime details, governance, and audit behavior, see [docs/SURGEON.md](./docs/SURGEON.md).
 
 ## Development
 
@@ -238,4 +261,4 @@ agenr scenarios run --kind store --preserve --verbose
 
 ## License
 
-AGPL-3.0
+MIT

package/dist/adapters/openclaw/index.js

@@ -4,7 +4,7 @@ import {
   openClawTranscriptParser,
   parseTuiSessionKey,
   readOpenClawSessionsStore
-} from "../../chunk-TBFAARM5.js";
+} from "../../chunk-JSVQILB3.js";
 import {
   BEFORE_TURN_DEBUG_ARTIFACT_DEFAULT_TOP_K,
   BEFORE_TURN_DEBUG_ARTIFACT_MAX_TOP_K,
@@ -13,10 +13,10 @@ import {
 } from "../../chunk-GELCEVFA.js";
 import {
   EPISODE_SUMMARY_TIMEOUT_MS,
+  FETCH_TOOL_PARAMETERS,
   RECALL_TOOL_PARAMETERS,
   STORE_TOOL_PARAMETERS,
   UPDATE_TOOL_PARAMETERS,
-  asRecord,
   buildClaimExtractionRuntime,
   buildRecallToolServices,
   composeHostPluginServices,
@@ -25,46 +25,51 @@ import {
   embedEpisodeSummaryWithinBudget,
   extractRecentTurnsFromMessages,
   formatAgenrSessionStartRecall,
-  formatErrorMessage,
-  formatTargetSelector,
   formatUnifiedRecallResults,
   normalizeOptionalBoolean,
   normalizeOptionalPositiveInteger,
   normalizePluginInjectionMemoryPolicyConfig,
   normalizePromptText,
+  parseFetchToolParams,
   parseRecallToolParams,
   parseStoreToolParams,
   parseUpdateToolParams,
-  readBooleanParam,
   resolveBeforeTurnPolicy,
   resolveSessionIdentityKey,
   resolveSessionStartPolicy,
-  resolveTargetEntry,
+  runFetchMemoryTool,
   runRecallMemoryTool,
   runSessionStart,
   runStoreMemoryTool,
   runUpdateMemoryTool,
-  sanitizeUpdateToolParams,
   writeBoundedSingleTranscriptEpisode
-} from "../../chunk-MYZ2CWY6.js";
+} from "../../chunk-E2DHUFZK.js";
 import {
-  createSingleTranscriptDiscoveryPort
-} from "../../chunk-LAXNNWHM.js";
+  asRecord,
+  buildEntryMemoryResolverPorts,
+  createSingleTranscriptDiscoveryPort,
+  formatErrorMessage,
+  formatTargetSelector,
+  readBooleanParam,
+  resolveTargetEntry,
+  sanitizeFetchToolParams,
+  sanitizeUpdateToolParams
+} from "../../chunk-EEEL53X4.js";
 import {
-  buildRecallToolDetails,
   containsAgenrMemoryContext,
   formatAgenrBeforeTurnRecall,
+  runBeforeTurn,
+  stripAgenrMemoryContext
+} from "../../chunk-V5CDMHRN.js";
+import {
+  EMBEDDING_DIMENSIONS,
+  buildRecallToolDetails,
   formatRecallToolSummary,
   formatUnifiedRecallLogSummary,
-  runBeforeTurn,
   sanitizeRecallToolParams,
   sanitizeStoreToolParams,
-  stripAgenrMemoryContext,
   truncate
-} from "../../chunk-575MUIW5.js";
-import {
-  EMBEDDING_DIMENSIONS
-} from "../../chunk-ELR2HSVC.js";
+} from "../../chunk-NNO2V4GH.js";
 import {
   resolveClaimSlotPolicy
 } from "../../chunk-5LADPJ4C.js";
@@ -72,6 +77,168 @@ import {
 // src/adapters/openclaw/index.ts
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
 
+// src/adapters/openclaw/tools/shared.ts
+import { failedTextResult, readNumberParam, readStringArrayParam, readStringParam, textResult } from "openclaw/plugin-sdk/agent-runtime";
+var OPENCLAW_PARAM_READER = {
+  readString: readStringParam,
+  readNumber: readNumberParam,
+  readStringArray: readStringArrayParam
+};
+function toOpenClawToolResult(outcome) {
+  if (outcome.failed) {
+    return failedTextResult(outcome.text, {
+      ...outcome.details,
+      status: "failed"
+    });
+  }
+  return textResult(outcome.text, outcome.details);
+}
+async function resolveTargetEntry2(services, params, options = {}) {
+  return resolveTargetEntry(buildEntryMemoryResolverPorts(services), params, options);
+}
+function logToolCall(logger, toolName, ctx, summary, sanitizedParams) {
+  logger.info(`[agenr] tool=${toolName} ${formatToolSessionContext(ctx)} ${summary}`);
+  logger.info(`[agenr] tool=${toolName} ${formatToolSessionContext(ctx)} params=${JSON.stringify(sanitizedParams)}`);
+}
+function logToolFailure(logger, toolName, ctx, error) {
+  logger.warn(`[agenr] tool=${toolName} ${formatToolSessionContext(ctx)} failed: ${formatErrorMessage(error)}`);
+}
+function sanitizeRetireToolParams(params) {
+  return {
+    ...params.id ? { id: params.id } : {},
+    ...params.subject ? { subject: params.subject } : {},
+    ...params.reason !== void 0 ? { reasonLength: params.reason.length } : {}
+  };
+}
+function sanitizeTraceToolParams(params) {
+  return {
+    ...params.id ? { id: params.id } : {},
+    ...params.subject ? { subject: params.subject } : {},
+    ...params.last !== void 0 ? { last: params.last } : {}
+  };
+}
+function formatTrace(entry, supersededBy, supersedes, claimFamily, recallEvents) {
+  const slotPolicy = entry.claim_key ? claimFamily ? {
+    policy: claimFamily.slotPolicy ?? resolveClaimSlotPolicy(claimFamily.claimKey).policy,
+    reason: claimFamily.slotPolicyReason ?? resolveClaimSlotPolicy(claimFamily.claimKey).reason
+  } : resolveClaimSlotPolicy(entry.claim_key) : void 0;
+  const lines = [
+    `Trace for ${entry.id} | ${entry.subject}`,
+    `type=${entry.type} expiry=${entry.expiry} importance=${entry.importance} retired=${entry.retired}`,
+    `content=${truncate(entry.content, 220)}`
+  ];
+  if (supersededBy) {
+    lines.push(`superseded_by=${supersededBy.id} | ${supersededBy.subject}`);
+  }
+  if (supersedes.length > 0) {
+    lines.push(`supersedes=${supersedes.map((item) => `${item.id} (${item.subject})`).join(", ")}`);
+  }
+  if (entry.claim_key) {
+    lines.push(`claim_key=${entry.claim_key}`);
+    if (slotPolicy) {
+      lines.push(`slot_policy=${slotPolicy.policy}`);
+      lines.push(`slot_policy_reason=${slotPolicy.reason}`);
+    }
+  }
+  if (claimFamily && claimFamily.entries.length > 0) {
+    lines.push(
+      `claim_family=${claimFamily.claimKey} | slot_policy=${slotPolicy?.policy ?? "exclusive"} | ${claimFamily.entries.map((item) => `${item.id}:${describeTraceEntryState(item)}:${formatClaimLifecycleLabel(item)}`).join(", ")}`
+    );
+    if (slotPolicy) {
+      lines.push(`claim_family_policy_reason=${slotPolicy.reason}`);
+    }
+    const transitionSummary = summarizeTraceClaimFamilyTransition(claimFamily.entries);
+    if (transitionSummary) {
+      lines.push(`transition=${transitionSummary}`);
+    }
+  }
+  if (entry.valid_from || entry.valid_to) {
+    lines.push(`validity=${entry.valid_from ?? "?"} -> ${entry.valid_to ?? "ongoing"}`);
+  }
+  if (entry.supersession_kind) {
+    lines.push(`supersession_kind=${entry.supersession_kind}${entry.supersession_reason ? ` reason=${truncate(entry.supersession_reason, 120)}` : ""}`);
+  }
+  if (recallEvents.length > 0) {
+    lines.push(
+      `recent_recalls=${recallEvents.map((event) => `${event.recalledAt}${event.query ? ` query=${event.query}` : ""}${event.sessionKey ? ` session=${event.sessionKey}` : ""}`).join(" ; ")}`
+    );
+  }
+  return lines.join("\n");
+}
+function toolFailureResult(error) {
+  return failedTextResult(formatErrorMessage(error), {
+    status: "failed"
+  });
+}
+function formatToolSessionContext(ctx) {
+  const normalizedSessionId = ctx.sessionId?.trim();
+  const normalizedSessionKey = ctx.sessionKey?.trim();
+  if (normalizedSessionId && normalizedSessionKey) {
+    return `session=${normalizedSessionId} key=${normalizedSessionKey}`;
+  }
+  if (normalizedSessionId) {
+    return `session=${normalizedSessionId}`;
+  }
+  if (normalizedSessionKey) {
+    return `key=${normalizedSessionKey}`;
+  }
+  return "session=unknown";
+}
+function describeTraceEntryState(entry) {
+  if (entry.superseded_by) {
+    return "superseded";
+  }
+  if (entry.retired || entry.valid_to) {
+    return "historical";
+  }
+  return "current";
+}
+function formatClaimLifecycleLabel(entry) {
+  if (!entry.claim_key) {
+    return "no-key";
+  }
+  return entry.claim_key_status ?? "legacy";
+}
+function summarizeTraceClaimFamilyTransition(entries) {
+  const current = entries.find((entry) => !entry.retired && !entry.superseded_by);
+  const prior = [...entries].reverse().find((entry) => entry.id !== current?.id && (entry.superseded_by !== void 0 || entry.retired || entry.valid_to !== void 0));
+  if (current && prior) {
+    return `${prior.id} -> ${current.id}`;
+  }
+  if (prior) {
+    return `${prior.id} is historical with no current sibling in the traced family`;
+  }
+  if (current) {
+    return `${current.id} is the only current sibling in the traced family`;
+  }
+  return void 0;
+}
+
+// src/adapters/openclaw/tools/fetch.ts
+function createAgenrFetchTool(ctx, servicesPromise, logger) {
+  return {
+    name: "agenr_fetch",
+    label: "Agenr Fetch",
+    description: "Fetch the full body and metadata for one durable memory entry by id or subject.",
+    parameters: FETCH_TOOL_PARAMETERS,
+    async execute(_toolCallId, rawParams) {
+      try {
+        const params = parseFetchToolParams(rawParams, OPENCLAW_PARAM_READER);
+        logToolCall(logger, "agenr_fetch", ctx, `target=${formatTargetSelector(params.id, params.subject)}`, sanitizeFetchToolParams(params));
+        const services = await servicesPromise;
+        return toOpenClawToolResult(
+          await runFetchMemoryTool(params, services, {
+            extraDetails: { sessionKey: ctx.sessionKey }
+          })
+        );
+      } catch (error) {
+        logToolFailure(logger, "agenr_fetch", ctx, error);
+        return toolFailureResult(error);
+      }
+    }
+  };
+}
+
 // src/adapters/openclaw/tools/recall.ts
 import { textResult as textResult2 } from "openclaw/plugin-sdk/agent-runtime";
 import { randomUUID } from "crypto";
@@ -297,151 +464,6 @@ function buildTopCandidates(result, reasonsByEntryId, topK) {
   });
 }
 
-// src/adapters/openclaw/tools/shared.ts
-import { failedTextResult, readNumberParam, readStringArrayParam, readStringParam, textResult } from "openclaw/plugin-sdk/agent-runtime";
-var OPENCLAW_PARAM_READER = {
-  readString: readStringParam,
-  readNumber: readNumberParam,
-  readStringArray: readStringArrayParam
-};
-function toOpenClawToolResult(outcome) {
-  if (outcome.failed) {
-    return failedTextResult(outcome.text, {
-      ...outcome.details,
-      status: "failed"
-    });
-  }
-  return textResult(outcome.text, outcome.details);
-}
-async function resolveTargetEntry2(services, params, options = {}) {
-  return resolveTargetEntry(
-    {
-      getEntryById: async (id) => await services.entries.getEntry(id) ?? (await services.memory.getEntryTrace(id))?.entry ?? null,
-      findEntryBySubject: async (subject) => services.memory.findEntryBySubject(subject),
-      findMostRecentEntry: async () => services.memory.findMostRecentEntry()
-    },
-    params,
-    options
-  );
-}
-function logToolCall(logger, toolName, ctx, summary, sanitizedParams) {
-  logger.info(`[agenr] tool=${toolName} ${formatToolSessionContext(ctx)} ${summary}`);
-  logger.info(`[agenr] tool=${toolName} ${formatToolSessionContext(ctx)} params=${JSON.stringify(sanitizedParams)}`);
-}
-function logToolFailure(logger, toolName, ctx, error) {
-  logger.warn(`[agenr] tool=${toolName} ${formatToolSessionContext(ctx)} failed: ${formatErrorMessage(error)}`);
-}
-function sanitizeRetireToolParams(params) {
-  return {
-    ...params.id ? { id: params.id } : {},
-    ...params.subject ? { subject: params.subject } : {},
-    ...params.reason !== void 0 ? { reasonLength: params.reason.length } : {}
-  };
-}
-function sanitizeTraceToolParams(params) {
-  return {
-    ...params.id ? { id: params.id } : {},
-    ...params.subject ? { subject: params.subject } : {},
-    ...params.last !== void 0 ? { last: params.last } : {}
-  };
-}
-function formatTrace(entry, supersededBy, supersedes, claimFamily, recallEvents) {
-  const slotPolicy = entry.claim_key ? claimFamily ? {
-    policy: claimFamily.slotPolicy ?? resolveClaimSlotPolicy(claimFamily.claimKey).policy,
-    reason: claimFamily.slotPolicyReason ?? resolveClaimSlotPolicy(claimFamily.claimKey).reason
-  } : resolveClaimSlotPolicy(entry.claim_key) : void 0;
-  const lines = [
-    `Trace for ${entry.id} | ${entry.subject}`,
-    `type=${entry.type} expiry=${entry.expiry} importance=${entry.importance} retired=${entry.retired}`,
-    `content=${truncate(entry.content, 220)}`
-  ];
-  if (supersededBy) {
-    lines.push(`superseded_by=${supersededBy.id} | ${supersededBy.subject}`);
-  }
-  if (supersedes.length > 0) {
-    lines.push(`supersedes=${supersedes.map((item) => `${item.id} (${item.subject})`).join(", ")}`);
-  }
-  if (entry.claim_key) {
-    lines.push(`claim_key=${entry.claim_key}`);
-    if (slotPolicy) {
-      lines.push(`slot_policy=${slotPolicy.policy}`);
-      lines.push(`slot_policy_reason=${slotPolicy.reason}`);
-    }
-  }
-  if (claimFamily && claimFamily.entries.length > 0) {
-    lines.push(
-      `claim_family=${claimFamily.claimKey} | slot_policy=${slotPolicy?.policy ?? "exclusive"} | ${claimFamily.entries.map((item) => `${item.id}:${describeTraceEntryState(item)}:${formatClaimLifecycleLabel(item)}`).join(", ")}`
-    );
-    if (slotPolicy) {
-      lines.push(`claim_family_policy_reason=${slotPolicy.reason}`);
-    }
-    const transitionSummary = summarizeTraceClaimFamilyTransition(claimFamily.entries);
-    if (transitionSummary) {
-      lines.push(`transition=${transitionSummary}`);
-    }
-  }
-  if (entry.valid_from || entry.valid_to) {
-    lines.push(`validity=${entry.valid_from ?? "?"} -> ${entry.valid_to ?? "ongoing"}`);
-  }
-  if (entry.supersession_kind) {
-    lines.push(`supersession_kind=${entry.supersession_kind}${entry.supersession_reason ? ` reason=${truncate(entry.supersession_reason, 120)}` : ""}`);
-  }
-  if (recallEvents.length > 0) {
-    lines.push(
-      `recent_recalls=${recallEvents.map((event) => `${event.recalledAt}${event.query ? ` query=${event.query}` : ""}${event.sessionKey ? ` session=${event.sessionKey}` : ""}`).join(" ; ")}`
-    );
-  }
-  return lines.join("\n");
-}
-function toolFailureResult(error) {
-  return failedTextResult(formatErrorMessage(error), {
-    status: "failed"
-  });
-}
-function formatToolSessionContext(ctx) {
-  const normalizedSessionId = ctx.sessionId?.trim();
-  const normalizedSessionKey = ctx.sessionKey?.trim();
-  if (normalizedSessionId && normalizedSessionKey) {
-    return `session=${normalizedSessionId} key=${normalizedSessionKey}`;
-  }
-  if (normalizedSessionId) {
-    return `session=${normalizedSessionId}`;
-  }
-  if (normalizedSessionKey) {
-    return `key=${normalizedSessionKey}`;
-  }
-  return "session=unknown";
-}
-function describeTraceEntryState(entry) {
-  if (entry.superseded_by) {
-    return "superseded";
-  }
-  if (entry.retired || entry.valid_to) {
-    return "historical";
-  }
-  return "current";
-}
-function formatClaimLifecycleLabel(entry) {
-  if (!entry.claim_key) {
-    return "no-key";
-  }
-  return entry.claim_key_status ?? "legacy";
-}
-function summarizeTraceClaimFamilyTransition(entries) {
-  const current = entries.find((entry) => !entry.retired && !entry.superseded_by);
-  const prior = [...entries].reverse().find((entry) => entry.id !== current?.id && (entry.superseded_by !== void 0 || entry.retired || entry.valid_to !== void 0));
-  if (current && prior) {
-    return `${prior.id} -> ${current.id}`;
-  }
-  if (prior) {
-    return `${prior.id} is historical with no current sibling in the traced family`;
-  }
-  if (current) {
-    return `${current.id} is the only current sibling in the traced family`;
-  }
-  return void 0;
-}
-
 // src/adapters/openclaw/tools/recall.ts
 function createAgenrRecallTool(ctx, servicesPromise, logger) {
   return {
@@ -727,6 +749,7 @@ function createAgenrUpdateTool(ctx, servicesPromise, logger) {
 function registerAgenrOpenClawTools(api, servicesPromise, logger) {
   api.registerTool((ctx) => createAgenrStoreTool(ctx, servicesPromise, logger), { names: ["agenr_store"] });
   api.registerTool((ctx) => createAgenrRecallTool(ctx, servicesPromise, logger), { names: ["agenr_recall"] });
+  api.registerTool((ctx) => createAgenrFetchTool(ctx, servicesPromise, logger), { names: ["agenr_fetch"] });
   api.registerTool((ctx) => createAgenrRetireTool(ctx, servicesPromise, logger), { names: ["agenr_retire"] });
   api.registerTool((ctx) => createAgenrUpdateTool(ctx, servicesPromise, logger), { names: ["agenr_update"] });
   api.registerTool((ctx) => createAgenrTraceTool(ctx, servicesPromise, logger), { names: ["agenr_trace"] });
@@ -736,11 +759,11 @@ function registerAgenrOpenClawTools(api, servicesPromise, logger) {
 var openclaw_plugin_default = {
   id: "agenr",
   name: "agenr",
-  version: "3.0.0",
+  version: "3.1.0",
   description: "agenr memory plugin for OpenClaw",
   kind: "memory",
   contracts: {
-    tools: ["agenr_store", "agenr_recall", "agenr_retire", "agenr_update", "agenr_trace"]
+    tools: ["agenr_store", "agenr_recall", "agenr_fetch", "agenr_retire", "agenr_update", "agenr_trace"]
   },
   uiHints: {
     dbPath: {
@@ -1156,6 +1179,7 @@ function normalizeStoreNudgeConfig(value) {
 // src/adapters/openclaw/format/prompt-section.ts
 var MEMORY_TOOL_NAMES = {
   recall: "agenr_recall",
+  fetch: "agenr_fetch",
   store: "agenr_store",
   update: "agenr_update",
   retire: "agenr_retire",
@@ -1177,6 +1201,7 @@ function buildAgenrMemoryPromptSection({
     "## Memory Recall",
     "Before answering anything about prior work, decisions, preferences, people, dates, unfinished work, or past sessions, call agenr_recall first. Session-start recall is automatic, and conservative before-turn recall may also appear as injected background context; use agenr_recall mid-session when you need context you do not already have.",
     "agenr_recall supports exact fact recall plus historical and episodic recall behind one tool: use mode=entries for exact facts, decisions, thresholds, and versions; use mode=auto for prior-state questions like what was the previous approach, what did we use before, or what changed from X to Y; use mode=episodes when you explicitly want session narrative recall.",
+    "agenr_recall returns truncated entry previews with ids, scores, and preview_truncated flags.",
     "For temporal narrative questions, put the time phrase in the query itself: examples include yesterday, last week, this month, 2 weeks ago, or in March.",
     "One focused agenr_recall call with the right scope beats several broad ones.",
     "When Agenr injects memory automatically, treat it as non-user background context and use it silently when relevant rather than forcing it into the reply.",
@@ -1215,6 +1240,9 @@ function buildAgenrMemoryPromptSection({
   if (availableTools.has(MEMORY_TOOL_NAMES.update) || availableTools.has(MEMORY_TOOL_NAMES.retire)) {
     lines.push("When memory is contradicted by live evidence, fix it with agenr_update or agenr_retire instead of silently working around it.");
   }
+  if (availableTools.has(MEMORY_TOOL_NAMES.fetch)) {
+    lines.push("Call agenr_fetch with id when preview_truncated=true or exact stored wording is required.");
+  }
   if (availableTools.has(MEMORY_TOOL_NAMES.trace)) {
     lines.push("Use agenr_trace when provenance, recall history, or supersession matters.");
   }