agenr 0.9.86 → 0.9.88

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.9.88] - 2026-03-12
+
+### Fixed
+
+- Updated the OpenClaw plugin for `openclaw@2026.3.11` by migrating agenr command lifecycle handling from the stale typed `api.on("command", ...)` path to named `api.registerHook(["command:new", "command:reset"], ...)` registration, restoring clean command-hook compatibility and removing current-release hook registration warnings.
+- Removed temporary OpenClaw prompt-build debug instrumentation after confirming `prependSystemContext` and `prependContext` injection is functioning in the sandbox.
+
+## [0.9.87] - 2026-03-12
+
+### Changed
+
+- Added an OpenClaw `prependSystemContext` agenr-first memory doctrine that supersedes legacy markdown-memory guidance without replacing OpenClaw's dynamically built system prompt.
+- Split OpenClaw prompt-build injection into stable doctrine (`prependSystemContext`) and dynamic recalled memory (`prependContext`), preserving existing session-start, mid-session, signal, and nudge behavior.
+- Added the `openclawMemoryDoctrine.enabled` plugin config gate, default-enabled, so operators can disable the stable doctrine block without turning off dynamic memory injection.
+- Updated OpenClaw plugin docs, architecture notes, and regression coverage to reflect the new doctrine/system-context path and its no-op-session behavior.
+
 ## [0.9.86] - 2026-03-12
 
 ### Fixed

package/dist/{chunk-SC2E7CS3.js → chunk-3WWWJ6MN.js}

@@ -23,7 +23,7 @@ import {
   runSimpleStream,
   toErrorMessage,
   walCheckpoint
-} from "./chunk-2WXGL442.js";
+} from "./chunk-NQQUVGQO.js";
 import {
   MILLISECONDS_PER_DAY,
   parseDaysBetween,

package/dist/{chunk-3DJDQDWN.js → chunk-JK4M3SD3.js}

@@ -39,7 +39,7 @@ import {
   toErrorMessage,
   updateRecallMetadata,
   walCheckpoint
-} from "./chunk-2WXGL442.js";
+} from "./chunk-NQQUVGQO.js";
 import {
   toNumber,
   toRowsAffected,

package/dist/cli-main.js

@@ -42,7 +42,7 @@ import {
   runStoreService,
   runTraceService,
   ui
-} from "./chunk-3DJDQDWN.js";
+} from "./chunk-JK4M3SD3.js";
 import {
   ConflictAlreadyResolvedError,
   REVIEW_QUEUE_PATH,
@@ -57,7 +57,7 @@ import {
   showFlaggedMerges,
   toConflictLogRow,
   toRecord
-} from "./chunk-SC2E7CS3.js";
+} from "./chunk-3WWWJ6MN.js";
 import {
   APP_VERSION,
   DEFAULT_AROUND_RADIUS_DAYS,
@@ -165,7 +165,7 @@ import {
   walCheckpoint,
   warnIfLocked,
   writeConfig
-} from "./chunk-2WXGL442.js";
+} from "./chunk-NQQUVGQO.js";
 import {
   getCoRecallNeighbors,
   getTopCoRecallEdges,
@@ -15104,12 +15104,12 @@ function registerMaintainCommand(program) {
     "--only <tasks>",
     "Comma-separated task names: quality,edge-decay,clusters,conflicts,consolidation,retirement,reflection"
   ).option("--prune-edges", "When edge decay runs, delete edges below the configured decay floor").option("--verbose", "Show detailed per-task output").action(async (opts) => {
-    const { runMaintainCommand } = await import("./maintain-ULYZ53FZ.js");
+    const { runMaintainCommand } = await import("./maintain-K5UXHWUO.js");
     const result = await runMaintainCommand(opts);
     process.exitCode = result.exitCode;
   });
   maintainCommand.command("history").description("Show past maintenance runs").option("--db <path>", "Database path override").option("--limit <n>", "Max runs to show (default: 10)", parseIntOption).option("--json", "Output as JSON").action(async (opts) => {
-    const { runMaintainHistoryCommand } = await import("./maintain-ULYZ53FZ.js");
+    const { runMaintainHistoryCommand } = await import("./maintain-K5UXHWUO.js");
     const result = await runMaintainHistoryCommand(opts);
     process.exitCode = result.exitCode;
   });

package/dist/{maintain-ULYZ53FZ.js → maintain-K5UXHWUO.js}

@@ -17,7 +17,7 @@ import {
   resolveConflict,
   runConsolidationOrchestrator,
   toRecord
-} from "./chunk-SC2E7CS3.js";
+} from "./chunk-3WWWJ6MN.js";
 import {
   DEFAULT_DB_PATH,
   DEFAULT_TASK_MODEL,
@@ -43,7 +43,7 @@ import {
   resolveModelForLlmClient,
   runSimpleStream,
   walCheckpoint
-} from "./chunk-2WXGL442.js";
+} from "./chunk-NQQUVGQO.js";
 import {
   decayCoRecallEdges,
   getLastRecallActivity,

package/dist/openclaw-plugin/index.d.ts

@@ -122,6 +122,7 @@ type BeforePromptBuildEvent = {
 type BeforePromptBuildResult = {
     systemPrompt?: string;
     prependContext?: string;
+    prependSystemContext?: string;
 };
 type BeforeResetEvent = {
     sessionFile?: string;
@@ -155,6 +156,22 @@ type PluginToolOptions = {
     names?: string[];
     optional?: boolean;
 };
+type InternalHookEvent = {
+    type: "command" | "session" | "agent" | "gateway" | "message";
+    action: string;
+    sessionKey: string;
+    context: Record<string, unknown>;
+    timestamp: Date;
+    messages: string[];
+};
+type InternalHookHandler = (event: InternalHookEvent) => Promise<void> | void;
+type PluginHookOptions = {
+    priority?: number;
+    entry?: unknown;
+    name?: string;
+    description?: string;
+    register?: boolean;
+};
 type PluginApi = {
     id: string;
     name: string;
@@ -162,6 +179,7 @@ type PluginApi = {
     pluginConfig?: Record<string, unknown>;
     logger: PluginLogger;
     registerTool?: (tool: PluginTool, opts?: PluginToolOptions) => void;
+    registerHook?: (events: string | string[], handler: InternalHookHandler, opts?: PluginHookOptions) => void;
     on: {
         (hook: "before_agent_start", handler: (event: BeforeAgentStartEvent, ctx: PluginHookAgentContext) => Promise<BeforeAgentStartResult | undefined> | BeforeAgentStartResult | undefined): void;
         (hook: "before_prompt_build", handler: (event: BeforePromptBuildEvent, ctx: PluginHookAgentContext) => Promise<BeforePromptBuildResult | undefined> | BeforePromptBuildResult | undefined): void;

package/dist/openclaw-plugin/index.js

@@ -24,7 +24,7 @@ import {
   runStoreService,
   runTraceService,
   setSessionProject
-} from "../chunk-3DJDQDWN.js";
+} from "../chunk-JK4M3SD3.js";
 import {
   KNOWLEDGE_TYPES,
   SCOPE_LEVELS,
@@ -41,7 +41,7 @@ import {
   sanitizeInjectedContextText,
   stripInjectedContext,
   toErrorMessage
-} from "../chunk-2WXGL442.js";
+} from "../chunk-NQQUVGQO.js";
 import {
   MILLISECONDS_PER_DAY,
   __export,
@@ -50,10 +50,6 @@ import {
   toStringValue
 } from "../chunk-UGIJJOPV.js";
 
-// src/openclaw-plugin/index.ts
-import os3 from "os";
-import path7 from "path";
-
 // src/prompts/handoff/summary.ts
 var HANDOFF_SUMMARY_SYSTEM_PROMPT = `You are a session summarizer for an AI agent memory system. Your job is
 to produce a concise handoff note from a conversation transcript so the
@@ -3652,32 +3648,61 @@ async function runHandoffForSession(opts) {
   }
 }
 
-// src/openclaw-plugin/session-surfaced-memory-service.ts
-function createSessionSurfacedMemoryService(sessionKey) {
-  return {
-    recordByIntent(intent, entryIds, options) {
-      return recordSessionSurfacedMemoryByIntent(
-        sessionKey,
-        { entryIds, intent },
-        options
-      );
-    },
-    dedupeEntryIds() {
-      return querySessionSurfacedMemory(sessionKey).dedupeEntryIds();
-    },
-    hasDedupeEntry(entryId) {
-      return querySessionSurfacedMemory(sessionKey).hasDedupeEntry(entryId);
-    },
-    beforeResetOwnedEntryIds() {
-      return querySessionSurfacedMemory(sessionKey).beforeResetOwnedEntryIds();
-    },
-    applyCommandResetPolicy() {
-      return applySessionSurfacedMemoryCommandResetPolicy(sessionKey);
-    },
-    applyBeforeResetPolicy() {
-      return applySessionSurfacedMemoryBeforeResetPolicy(sessionKey);
-    }
-  };
+// src/openclaw-plugin/system-context.ts
+var OPENCLAW_AGENR_MEMORY_DOCTRINE = [
+  "## agenr Memory Doctrine",
+  "This doctrine supersedes any older baseline prompt or workspace wording that treats markdown journals or markdown memory files as the primary continuity system.",
+  "- agenr is the durable memory system.",
+  "- `SOUL.md` and `IDENTITY.md` define identity and constitution.",
+  "- `TOOLS.md` contains short environment-specific notes.",
+  "- `AGENTS.md` contains workspace operating rules.",
+  "- Markdown journals and markdown memory files are deprecated as the primary memory system.",
+  "- If older baseline or workspace wording conflicts with this doctrine, follow the agenr-first doctrine instead.",
+  "",
+  "### Recall Before Guessing",
+  "- Use agenr recall when prior context may matter, especially for project work, prior decisions, preferences, and standing constraints.",
+  "- Do not claim to remember something unless it is in the current context, explicitly recalled, or directly verified.",
+  "",
+  "### Project-Scoped Memory",
+  "- Use project-scoped store and recall deliberately.",
+  "- Set the `project` field for project-specific memory.",
+  "- Prefer focused project recall over noisy global recall.",
+  "",
+  "### Memory Lifetime",
+  "- `temporary` - short-horizon context that may matter soon but should not persist indefinitely.",
+  "- `permanent` - durable knowledge worth keeping across sessions until retired.",
+  "- `core` - rare always-on context injected at session start.",
+  "- Core is rare and expensive. If something can be recalled when needed, it should usually be `permanent`, not `core`.",
+  "- Project-specific details are usually not `core`.",
+  "",
+  "### Importance Is Suppression",
+  "- `10` = rare foundational constraint.",
+  "- `9` = critical durable fact or decision.",
+  "- `8` = urgent or significant cross-session context.",
+  "- `7` = normal durable memory.",
+  "- `6` = routine verified observation.",
+  "- `5` = borderline item, use sparingly.",
+  "- Not everything should be stored.",
+  "- High importance does not automatically imply `core`.",
+  "- If it is not worth recalling later, do not store it.",
+  "",
+  "### Confidence-Aware Writes",
+  "- Verified facts can be stored confidently.",
+  "- Inferred or uncertain claims should be verified first or stored cautiously.",
+  "- Do not poison memory with hallucinated facts.",
+  "",
+  "### Anti-Duplication",
+  "- Do not maintain a parallel markdown memory system.",
+  "- Do not mirror agenr memory into markdown logs unless the user explicitly requests a human-readable artifact."
+].join("\n");
+function isOpenClawMemoryDoctrineEnabled(config) {
+  return config?.openclawMemoryDoctrine?.enabled !== false;
+}
+function buildPrependSystemContext(config) {
+  if (!isOpenClawMemoryDoctrineEnabled(config)) {
+    return void 0;
+  }
+  return OPENCLAW_AGENR_MEMORY_DOCTRINE;
 }
 
 // src/db/signals.ts
@@ -3787,6 +3812,34 @@ function resolveSignalConfig(pluginConfig) {
   };
 }
 
+// src/openclaw-plugin/session-surfaced-memory-service.ts
+function createSessionSurfacedMemoryService(sessionKey) {
+  return {
+    recordByIntent(intent, entryIds, options) {
+      return recordSessionSurfacedMemoryByIntent(
+        sessionKey,
+        { entryIds, intent },
+        options
+      );
+    },
+    dedupeEntryIds() {
+      return querySessionSurfacedMemory(sessionKey).dedupeEntryIds();
+    },
+    hasDedupeEntry(entryId) {
+      return querySessionSurfacedMemory(sessionKey).hasDedupeEntry(entryId);
+    },
+    beforeResetOwnedEntryIds() {
+      return querySessionSurfacedMemory(sessionKey).beforeResetOwnedEntryIds();
+    },
+    applyCommandResetPolicy() {
+      return applySessionSurfacedMemoryCommandResetPolicy(sessionKey);
+    },
+    applyBeforeResetPolicy() {
+      return applySessionSurfacedMemoryBeforeResetPolicy(sessionKey);
+    }
+  };
+}
+
 // src/openclaw-plugin/hooks/before-prompt-build-shared.ts
 function getRecallEntryId(item) {
   if (typeof item !== "object" || item === null) {
@@ -7866,11 +7919,15 @@ async function handleBeforePromptBuild(event, ctx, params) {
       return;
     }
     logPromptBuildSections(params.debug, sectionResult.sections);
+    const prependSystemContext = buildPrependSystemContext(params.config);
     const prependContext = buildPrependContext(params.debug, sectionResult.sections);
-    if (!prependContext) {
+    if (!prependSystemContext && !prependContext) {
       return;
     }
-    return { prependContext };
+    return {
+      prependSystemContext,
+      prependContext
+    };
   } catch (err) {
     params.logger.warn(
       `agenr plugin before_prompt_build signal check failed: ${toErrorMessage(err)}`
@@ -8025,6 +8082,120 @@ async function handleBeforeReset(event, ctx, params) {
   }
 }
 
+// src/openclaw-plugin/hooks/command-events.ts
+import os3 from "os";
+import path7 from "path";
+var log3 = createLogger("command");
+function toCommandHookEvent(event) {
+  return {
+    type: "command",
+    action: event.action,
+    sessionKey: event.sessionKey,
+    timestamp: event.timestamp,
+    messages: Array.isArray(event.messages) ? event.messages : [],
+    context: event.context ?? {}
+  };
+}
+function resolveCommandAgentId(sessionKey) {
+  const parsed = parseOpenClawSessionIdentity(sessionKey);
+  const agentId = parsed.agentId?.trim();
+  return agentId && agentId.length > 0 ? agentId : "main";
+}
+function applyCommandResetPolicy(sessionKey, sessionId) {
+  clearMidSessionState(sessionKey);
+  createSessionSurfacedMemoryService(sessionKey).applyCommandResetPolicy();
+  if (sessionId && sessionId !== sessionKey) {
+    clearMidSessionState(sessionId);
+    createSessionSurfacedMemoryService(sessionId).applyCommandResetPolicy();
+  }
+}
+async function handleCommandEvent(event, params) {
+  try {
+    debugLog(
+      params.debug,
+      "command",
+      "triggered action=" + event.action + " sessionKey=" + event.sessionKey
+    );
+    const sessionKey = event.sessionKey?.trim() ?? "";
+    if (!sessionKey) {
+      return;
+    }
+    const sessionEntry = event.context.sessionEntry;
+    const sessionId = sessionEntry?.sessionId?.trim() || sessionKey;
+    applyCommandResetPolicy(sessionKey, sessionId);
+    const sessionFile = typeof sessionEntry?.sessionFile === "string" && sessionEntry.sessionFile.trim() ? sessionEntry.sessionFile.trim() : null;
+    log3.info(
+      `command hook: fired action=${event.action} sessionKey=${sessionKey} sessionFile=${sessionFile ?? "none"}`
+    );
+    let messages = [];
+    if (sessionFile) {
+      messages = await params.testingApi.readAndParseSessionJsonl(sessionFile);
+    }
+    if (messages.length === 0) {
+      return;
+    }
+    const agentId = resolveCommandAgentId(sessionKey);
+    const sessionsDir = params.config?.sessionsDir ?? path7.join(os3.homedir(), `.openclaw/agents/${agentId}/sessions`);
+    const defaultProject = params.config?.project?.trim() || void 0;
+    const sessionProjectState = await getSessionProjectState(sessionKey, params.config);
+    const projectAttribution = resolveOpenClawHandoffProjectAttribution({
+      sessionProjectState,
+      defaultProject
+    });
+    const storeConfig = {
+      ...params.config,
+      logger: params.logger
+    };
+    await params.testingApi.runHandoffForSession({
+      messages,
+      sessionFile,
+      sessionId,
+      sessionKey,
+      agentId,
+      agenrPath: params.agenrPath,
+      budget: params.budget,
+      defaultProject: projectAttribution.project ?? void 0,
+      projectAttribution,
+      storeConfig,
+      sessionsDir,
+      includeBackground: params.includeBackground,
+      logEnabled: params.handoffLogEnabled,
+      logDir: params.handoffLogDir,
+      debugEnabled: params.debug,
+      logger: params.logger,
+      source: "command",
+      dbPath: params.config?.dbPath
+    });
+    debugLog(params.debug, "command", "handoff complete");
+  } catch (err) {
+    params.logger.warn(
+      `agenr plugin command hook failed: ${toErrorMessage(err)}`
+    );
+  }
+}
+function registerAgenrCommandHooks(api, params) {
+  if (api.registerHook) {
+    api.registerHook(
+      ["command:new", "command:reset"],
+      async (event) => handleCommandEvent(event, params),
+      {
+        name: "agenr-command-events",
+        description: "Handle OpenClaw command lifecycle events for agenr reset cleanup and session handoff continuity."
+      }
+    );
+    return;
+  }
+  api.on(
+    "command",
+    async (event) => {
+      if (event.action !== "new" && event.action !== "reset") {
+        return;
+      }
+      await handleCommandEvent(toCommandHookEvent(event), params);
+    }
+  );
+}
+
 // src/openclaw-plugin/hooks/register-tools.ts
 import { Type } from "@sinclair/typebox";
 
@@ -8494,7 +8665,6 @@ var plugin = {
   name: "agenr memory context",
   description: "Injects agenr long-term memory into every agent session via before_prompt_build",
   register(api) {
-    const log3 = createLogger("plugin");
     const config = api.pluginConfig;
     const debug = isDebugEnabled(config);
     const includeBackground = config?.handoff?.includeBackground ?? false;
@@ -8526,6 +8696,17 @@ var plugin = {
       logger: api.logger,
       testingApi
     };
+    const commandParams = {
+      config,
+      debug,
+      budget,
+      includeBackground,
+      handoffLogEnabled,
+      handoffLogDir,
+      agenrPath,
+      logger: api.logger,
+      testingApi
+    };
     const toolParams = {
       config,
       debug,
@@ -8533,82 +8714,7 @@ var plugin = {
     };
     api.on("before_prompt_build", (event, ctx) => handleBeforePromptBuild(event, ctx, promptBuildParams));
     api.on("before_reset", (event, ctx) => handleBeforeReset(event, ctx, resetParams));
-    api.on(
-      "command",
-      async (event, ctx) => {
-        try {
-          debugLog(debug, "command", "triggered action=" + event.action + " sessionKey=" + event.sessionKey);
-          if (event.action !== "new" && event.action !== "reset") {
-            return;
-          }
-          if (event.action === "new" || event.action === "reset") {
-            const resetKey = event.sessionKey;
-            if (resetKey) {
-              clearMidSessionState(resetKey);
-              createSessionSurfacedMemoryService(resetKey).applyCommandResetPolicy();
-            }
-            const resetSessionId = event.context?.sessionEntry?.sessionId?.trim() ?? "";
-            if (resetSessionId && resetSessionId !== resetKey) {
-              clearMidSessionState(resetSessionId);
-              createSessionSurfacedMemoryService(resetSessionId).applyCommandResetPolicy();
-            }
-          }
-          const sessionKey = event.sessionKey;
-          if (!sessionKey) {
-            return;
-          }
-          const sessionFile = event.context?.sessionEntry?.sessionFile ?? null;
-          const sessionId = event.context?.sessionEntry?.sessionId ?? sessionKey;
-          log3.info(
-            `command hook: fired action=${event.action} sessionKey=${sessionKey} sessionFile=${sessionFile ?? "none"}`
-          );
-          let messages = [];
-          if (sessionFile) {
-            messages = await testingApi.readAndParseSessionJsonl(sessionFile);
-          }
-          if (messages.length === 0) {
-            return;
-          }
-          const agentId = ctx.agentId?.trim() || "main";
-          const sessionsDir = config?.sessionsDir ?? path7.join(os3.homedir(), `.openclaw/agents/${agentId}/sessions`);
-          const defaultProject = config?.project?.trim() || void 0;
-          const sessionProjectState = await getSessionProjectState(sessionKey, config);
-          const projectAttribution = resolveOpenClawHandoffProjectAttribution({
-            sessionProjectState,
-            defaultProject
-          });
-          const storeConfig = {
-            ...config,
-            logger: api.logger
-          };
-          await testingApi.runHandoffForSession({
-            messages,
-            sessionFile,
-            sessionId,
-            sessionKey,
-            agentId,
-            agenrPath,
-            budget,
-            defaultProject: projectAttribution.project ?? void 0,
-            projectAttribution,
-            storeConfig,
-            sessionsDir,
-            includeBackground,
-            logEnabled: handoffLogEnabled,
-            logDir: handoffLogDir,
-            debugEnabled: debug,
-            logger: api.logger,
-            source: "command",
-            dbPath: config?.dbPath
-          });
-          debugLog(debug, "command", "handoff complete");
-        } catch (err) {
-          api.logger.warn(
-            `agenr plugin command hook failed: ${toErrorMessage(err)}`
-          );
-        }
-      }
-    );
+    registerAgenrCommandHooks(api, commandParams);
     registerAgenrTools(api, toolParams);
   }
 };

package/openclaw.plugin.json

@@ -94,6 +94,17 @@
           }
         }
       },
+      "openclawMemoryDoctrine": {
+        "type": "object",
+        "description": "Stable agenr-first doctrine injected with prependSystemContext.",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "description": "Set false to disable stable doctrine injection while preserving dynamic prependContext memory injection."
+          }
+        }
+      },
       "dbPath": {
         "type": "string",
         "description": "Path to agenr DB. Defaults to AGENR_DB_PATH env or ~/.agenr/knowledge.db."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenr",
-  "version": "0.9.86",
+  "version": "0.9.88",
   "openclaw": {
     "extensions": [
       "dist/openclaw-plugin/index.js"

package/dist/{chunk-2WXGL442.js → chunk-NQQUVGQO.js}

@@ -7,25 +7,6 @@ import {
   toStringValue
 } from "./chunk-UGIJJOPV.js";
 
-// src/utils/errors.ts
-function toErrorMessage(error) {
-  if (error instanceof Error) {
-    return error.message;
-  }
-  if (error !== null && typeof error === "object") {
-    const maybeMessage = error.message;
-    if (typeof maybeMessage === "string") {
-      return maybeMessage;
-    }
-    try {
-      return JSON.stringify(error);
-    } catch {
-      return String(error);
-    }
-  }
-  return String(error);
-}
-
 // src/config.ts
 import fs2 from "fs";
 import os3 from "os";
@@ -213,6 +194,25 @@ function buildProjectFilter(params) {
   };
 }
 
+// src/utils/errors.ts
+function toErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (error !== null && typeof error === "object") {
+    const maybeMessage = error.message;
+    if (typeof maybeMessage === "string") {
+      return maybeMessage;
+    }
+    try {
+      return JSON.stringify(error);
+    } catch {
+      return String(error);
+    }
+  }
+  return String(error);
+}
+
 // src/utils/fs.ts
 import os2 from "os";
 import path2 from "path";
@@ -1512,6 +1512,12 @@ var APP_VERSION = (() => {
   return "0.0.0";
 })();
 
+// src/db/client.ts
+import { createClient } from "@libsql/client";
+import fs3 from "fs/promises";
+import os4 from "os";
+import path4 from "path";
+
 // src/utils/logger.ts
 var verboseEnabled = false;
 function isMockedConsoleFn(fn) {
@@ -1552,12 +1558,6 @@ function createLogger(prefix) {
   };
 }
 
-// src/db/client.ts
-import { createClient } from "@libsql/client";
-import fs3 from "fs/promises";
-import os4 from "os";
-import path4 from "path";
-
 // src/db/schema/definitions.ts
 var CREATE_IDX_ENTRIES_EMBEDDING_SQL = `
   CREATE INDEX IF NOT EXISTS idx_entries_embedding ON entries (