@clawmem-ai/clawmem 0.1.17 → 0.1.18

package/README.md

@@ -156,6 +156,7 @@ Full config with all options:
 - Summary or memory-capture failures do not block finalization; the conversation issue still closes, and the mirrored transcript remains the durable source of truth for manual follow-up.
 - Memory search and auto-recall only return open `type:memory` issues. Closed memory issues are treated as stale.
 - ClawMem automatically injects a small set of relevant memories before each turn using the agent's default repo and the backend recall API. Auto-recall is best-effort and quietly skips injection when backend recall is unavailable.
+- Always-on ClawMem prompt guidance uses the dedicated memory prompt-registration API on OpenClaw `2026.3.22+`. On `2026.3.7` through `2026.3.21`, ClawMem falls back to `before_prompt_build` `prependSystemContext`. Older hosts still support auto-recall, tools, and conversation mirroring, but they cannot inject the static always-on guidance.
 - `memory_recall` uses the backend `/api/v3/search/issues` endpoint scoped to the current repo plus `label:"type:memory"`. When backend recall is unavailable, use `memory_list` or `memory_get` to inspect memories explicitly.
 - Automatic durable capture happens when the session resets or ends. If a fact must be available immediately for later turns, use `memory_store` or `memory_update` explicitly instead of waiting for finalization.
 - The plugin exposes `memory_repos`, `memory_repo_create`, `memory_list`, `memory_get`, `memory_labels`, `memory_recall`, `memory_store`, `memory_update`, and `memory_forget` for mid-session use.

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "clawmem",
   "name": "ClawMem",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Repo-backed long-term memory plugin for OpenClaw with auto recall, durable memory capture, and conversation mirroring.",
   "kind": "memory",
   "skills": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawmem-ai/clawmem",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Repo-backed long-term memory plugin for OpenClaw with auto recall, durable memory capture, and conversation mirroring.",
   "type": "module",
   "license": "MIT",

package/src/service.test.ts

@@ -108,22 +108,34 @@ function testBuildClawMemPromptSection(): void {
 function createFakePluginApi(options?: {
   slot?: string;
   exposeCapability?: boolean;
+  exposePromptSection?: boolean;
+  runtimeVersion?: string;
 }) {
   let registeredCapability: { promptBuilder?: typeof buildClawMemPromptSection } | undefined;
   let registeredPromptSection: typeof buildClawMemPromptSection | undefined;
+  const handlers = new Map<string, Array<(...args: any[]) => unknown>>();
+  const warnings: string[] = [];
+  const infos: string[] = [];
   const api = {
     id: "clawmem",
     name: "ClawMem",
     source: "test",
     registrationMode: "test",
     config: {},
-    pluginConfig: {},
+    pluginConfig: {
+      agents: {
+        main: {
+          token: "test-token",
+          defaultRepo: "acme/memory",
+        },
+      },
+    },
     logger: {
-      info: () => {},
-      warn: () => {},
+      info: (message: string) => { infos.push(message); },
+      warn: (message: string) => { warnings.push(message); },
     },
     runtime: {
-      version: "2026.4.9",
+      version: options?.runtimeVersion ?? "2026.4.9",
       config: {
         loadConfig: () => ({
           plugins: {
@@ -138,7 +150,11 @@ function createFakePluginApi(options?: {
       },
       subagent: {},
     },
-    on: () => {},
+    on: (event: string, handler: (...args: any[]) => unknown) => {
+      const current = handlers.get(event) ?? [];
+      current.push(handler);
+      handlers.set(event, current);
+    },
     registerTool: () => {},
     registerService: () => {},
     ...(options?.exposeCapability === false
@@ -148,15 +164,22 @@ function createFakePluginApi(options?: {
             registeredCapability = capability;
           },
         }),
-    registerMemoryPromptSection: (builder: typeof buildClawMemPromptSection) => {
-      registeredPromptSection = builder;
-    },
+    ...(options?.exposePromptSection === false
+      ? {}
+      : {
+          registerMemoryPromptSection: (builder: typeof buildClawMemPromptSection) => {
+            registeredPromptSection = builder;
+          },
+        }),
   };
 
   return {
     api,
     getRegisteredCapability: () => registeredCapability,
     getRegisteredPromptSection: () => registeredPromptSection,
+    getWarnings: () => warnings,
+    getInfos: () => infos,
+    getHandler: (event: string) => handlers.get(event)?.[0],
   };
 }
 
@@ -181,6 +204,50 @@ function testFallsBackToLegacyMemoryPromptSectionRegistration(): void {
   assert(prompt.includes("## ClawMem"), "expected the fallback builder to emit ClawMem guidance");
 }
 
+function testOlderHostWithoutPromptRegistrationDoesNotWarn(): void {
+  const fake = createFakePluginApi({
+    exposeCapability: false,
+    exposePromptSection: false,
+    runtimeVersion: "2026.3.13",
+  });
+  createClawMemPlugin(fake.api as never);
+
+  assert(fake.getWarnings().length === 0, "expected older hosts without prompt registration to avoid warnings");
+  assert(
+    fake.getInfos().some((message) => message.includes("falling back to before_prompt_build prependSystemContext")),
+    "expected older hosts to log an informational compatibility note",
+  );
+}
+
+function testModernHostWithoutPromptRegistrationWarns(): void {
+  const fake = createFakePluginApi({
+    exposeCapability: false,
+    exposePromptSection: false,
+    runtimeVersion: "2026.3.22",
+  });
+  createClawMemPlugin(fake.api as never);
+
+  assert(
+    fake.getWarnings().some((message) => message.includes("falling back to before_prompt_build prependSystemContext")),
+    "expected warning when a new-enough host is missing prompt registration",
+  );
+}
+
+async function testOlderModernHostInjectsPromptGuidanceViaPrependSystemContext(): Promise<void> {
+  const fake = createFakePluginApi({
+    exposeCapability: false,
+    exposePromptSection: false,
+    runtimeVersion: "2026.3.13",
+  });
+  createClawMemPlugin(fake.api as never);
+
+  const handler = fake.getHandler("before_prompt_build");
+  assert(typeof handler === "function", "expected before_prompt_build handler to be registered for modern hosts");
+  const result = await handler?.({ prompt: "hi" }, { agentId: "main" }) as { prependContext?: string; prependSystemContext?: string } | void;
+  assert(Boolean(result && result.prependSystemContext?.includes("## ClawMem")), "expected static ClawMem guidance to use prependSystemContext fallback");
+  assert(!result || !result.prependContext, "expected no dynamic recall context when the prompt is too short for auto-recall");
+}
+
 function testSkipsAlwaysOnPromptWhenClawMemIsNotSelectedMemoryPlugin(): void {
   const fake = createFakePluginApi({ slot: "other-memory" });
   createClawMemPlugin(fake.api as never);
@@ -262,6 +329,9 @@ testResolvePromptHookModeLegacy();
 testResolvePromptHookModeLegacyForUnknownVersion();
 testRegistersAlwaysOnMemoryPromptCapability();
 testFallsBackToLegacyMemoryPromptSectionRegistration();
+testOlderHostWithoutPromptRegistrationDoesNotWarn();
+testModernHostWithoutPromptRegistrationWarns();
 testSkipsAlwaysOnPromptWhenClawMemIsNotSelectedMemoryPlugin();
+await testOlderModernHostInjectsPromptGuidanceViaPrependSystemContext();
 
 console.log("service tests passed");

package/src/service.ts

@@ -19,8 +19,21 @@ type CollaborationPermission = "read" | "write" | "admin";
 type CollaborationTeamRole = "member" | "maintainer";
 type MemoryPromptBuilder = NonNullable<MemoryPluginCapability["promptBuilder"]>;
 type MemoryPromptBuilderParams = Parameters<MemoryPromptBuilder>[0];
+type PromptBuildInjection = { prependContext?: string; prependSystemContext?: string };
 
 const MODERN_PROMPT_HOOK_MIN_HOST_VERSION = "2026.3.7";
+const MEMORY_PROMPT_REGISTRATION_MIN_HOST_VERSION = "2026.3.22";
+const CLAWMEM_PROMPT_GUIDANCE_TOOL_NAMES = [
+  "memory_repos",
+  "memory_repo_create",
+  "memory_list",
+  "memory_labels",
+  "memory_recall",
+  "memory_get",
+  "memory_store",
+  "memory_update",
+  "memory_forget",
+] as const;
 type PromptHookMode = "modern" | "legacy";
 
 class ClawMemService {
@@ -34,6 +47,7 @@ class ClawMemService {
   private unsubTranscript?: () => void;
   private loadPromise: Promise<void> | null = null;
   private readonly configPromises = new Map<string, Promise<boolean>>();
+  private injectPromptGuidanceViaSystemContext = false;
 
   constructor(private readonly api: OpenClawPluginApi) {
     this.config = resolvePluginConfig(api);
@@ -41,7 +55,7 @@ class ClawMemService {
 
   register(): void {
     const promptHookMode = resolvePromptHookMode(this.api);
-    this.registerMemoryPromptGuidance();
+    this.registerMemoryPromptGuidance(promptHookMode);
     if (promptHookMode === "modern") {
       this.api.on("before_prompt_build", async (ev, ctx) => this.handleBeforePromptBuild(ev, ctx.agentId));
     } else {
@@ -97,7 +111,7 @@ class ClawMemService {
     });
   }
 
-  private registerMemoryPromptGuidance(): void {
+  private registerMemoryPromptGuidance(promptHookMode: PromptHookMode): void {
     if (!this.isSelectedMemoryPlugin()) return;
 
     const api = this.api as OpenClawPluginApi & {
@@ -115,7 +129,37 @@ class ClawMemService {
       return;
     }
 
-    this.api.logger.warn?.("clawmem: host does not expose memory prompt registration; always-on prompt guidance is disabled");
+    const hostVersion = resolveOpenClawHostVersion(this.api);
+    const comparison = hostVersion ? compareOpenClawVersions(hostVersion, MEMORY_PROMPT_REGISTRATION_MIN_HOST_VERSION) : null;
+    if (promptHookMode === "modern") {
+      this.injectPromptGuidanceViaSystemContext = true;
+      if (comparison !== null && comparison < 0) {
+        this.api.logger.info?.(
+          `clawmem: OpenClaw ${hostVersion} predates memory prompt registration (requires ${MEMORY_PROMPT_REGISTRATION_MIN_HOST_VERSION}+); falling back to before_prompt_build prependSystemContext for always-on prompt guidance`,
+        );
+        return;
+      }
+
+      this.api.logger.warn?.(
+        hostVersion
+          ? `clawmem: OpenClaw ${hostVersion} does not expose memory prompt registration; falling back to before_prompt_build prependSystemContext for always-on prompt guidance`
+          : "clawmem: host does not expose memory prompt registration; falling back to before_prompt_build prependSystemContext for always-on prompt guidance",
+      );
+      return;
+    }
+
+    if (comparison !== null && comparison < 0) {
+      this.api.logger.info?.(
+        `clawmem: OpenClaw ${hostVersion} predates memory prompt registration and prompt-level system-context fallback; always-on prompt guidance is unavailable on this host`,
+      );
+      return;
+    }
+
+    this.api.logger.warn?.(
+      hostVersion
+        ? `clawmem: OpenClaw ${hostVersion} does not expose memory prompt registration; always-on prompt guidance is disabled`
+        : "clawmem: host does not expose memory prompt registration; always-on prompt guidance is disabled",
+    );
   }
 
   private isSelectedMemoryPlugin(): boolean {
@@ -1766,12 +1810,17 @@ class ClawMemService {
     });
   }
 
-  private async handleBeforePromptBuild(event: unknown, agentId?: string): Promise<{ prependContext: string } | void> {
+  private async handleBeforePromptBuild(event: unknown, agentId?: string): Promise<PromptBuildInjection | void> {
     const context = await this.collectAutoRecallContext(event, agentId);
+    const systemContext = this.injectPromptGuidanceViaSystemContext ? buildFallbackPromptGuidanceText(event) : undefined;
     // Auto-recall is per-turn dynamic context, so keep it out of the system prompt.
     // OpenClaw documents dynamic context on `prependContext`: https://github.com/maweibin/openclaw/blob/d9a2869ad69db9449336a2e2846bd9de0e647ac6/docs/concepts/agent-loop.md?plain=1#L85
     // Changing the system prompt can defeat provider prefix caching.
-    return context ? { prependContext: context } : undefined;
+    if (!context && !systemContext) return undefined;
+    return {
+      ...(systemContext ? { prependSystemContext: systemContext } : {}),
+      ...(context ? { prependContext: context } : {}),
+    };
   }
 
   private async handleBeforeAgentStart(event: unknown, agentId?: string): Promise<{ prependContext: string } | void> {
@@ -2389,6 +2438,14 @@ export function buildClawMemPromptSection(params: MemoryPromptBuilderParams): st
   return lines;
 }
 
+function buildFallbackPromptGuidanceText(event: unknown): string | undefined {
+  const record = asRecord(event);
+  const availableTools = resolvePromptGuidanceAvailableTools(record.availableTools);
+  const citationsMode = typeof record.citationsMode === "string" ? record.citationsMode.trim() || undefined : undefined;
+  const text = buildClawMemPromptSection({ availableTools, ...(citationsMode ? { citationsMode } : {}) }).join("\n").trim();
+  return text || undefined;
+}
+
 export function extractPromptTextForRecall(event: unknown): string | undefined {
   const direct = normalizePromptText(event);
   if (direct) return direct;
@@ -2416,6 +2473,25 @@ function joinNaturalLanguageList(items: string[]): string {
   return `${items.slice(0, -1).join(", ")}, and ${items[items.length - 1]}`;
 }
 
+function resolvePromptGuidanceAvailableTools(value: unknown): Set<string> {
+  const names = collectToolNames(value);
+  return names.size > 0 ? names : new Set(CLAWMEM_PROMPT_GUIDANCE_TOOL_NAMES);
+}
+
+function collectToolNames(value: unknown): Set<string> {
+  const names = new Set<string>();
+  const values = value instanceof Set ? [...value] : Array.isArray(value) ? value : [];
+  for (const entry of values) {
+    if (typeof entry === "string" && entry.trim()) {
+      names.add(entry.trim());
+      continue;
+    }
+    const record = asRecord(entry);
+    if (typeof record.name === "string" && record.name.trim()) names.add(record.name.trim());
+  }
+  return names;
+}
+
 function extractPromptTextFromMessages(value: unknown): string | undefined {
   if (!Array.isArray(value)) return undefined;
   let fallback: string | undefined;

package/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "extends": "../openclaw/tsconfig.json",
   "compilerOptions": {
+    "outDir": "./dist",
     "baseUrl": ".",
     "paths": {
       "openclaw/plugin-sdk": ["../openclaw/src/plugin-sdk/index.ts"],