@agenr/agenr-plugin 3.0.0 → 3.1.0

package/dist/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.");
   }

package/openclaw.plugin.json

@@ -1,11 +1,11 @@
 {
   "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": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenr/agenr-plugin",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "agenr memory plugin for OpenClaw",
   "type": "module",
   "exports": {
@@ -23,7 +23,7 @@
   "engines": {
     "node": ">=24"
   },
-  "license": "AGPL-3.0",
+  "license": "MIT",
   "scripts": {
     "build": "node build.mjs",
     "build:debug": "node build.mjs"