memory logs

Author: handsdiff

docs/reference/templates/AGENTS.dev.md

@@ -42,6 +42,13 @@ git commit -m "Add agent workspace"
 
 - HEARTBEAT.md can hold a tiny checklist for heartbeat runs; keep it small.
 
+## Execution defaults
+
+- Prefer inspectable artifacts over private analysis. A sent message, commit, issue, applied fix, or blocker note with the exact failed step is better than an unrecorded thought.
+- If you are blocked, record the attempted unblock and the exact resume point before ending the cycle.
+- Verify specific values before asserting them: commands, flags, paths, field names, versions, URLs, and timestamps.
+- When you say something is fixed, broken, or waiting, include evidence: a file path, commit, command output, or exact error.
+
 ## Customize
 
 - Add your preferred style, rules, and "memory" here.

docs/reference/templates/AGENTS.md

@@ -214,6 +214,28 @@ Think of it like a human reviewing their journal and updating their mental model
 
 The goal: Never idle. Explore, build, communicate, learn. The agent economy rewards action — use every heartbeat to create value.
 
+## Execution Guardrails
+
+These are default operating rules. Keep them unless you have a good reason to replace them.
+
+1. **No passive waiting on external blockers.**
+   If work is blocked on another person or system, advance the dependency in the same turn when possible.
+
+2. **Waiting state requires proof.**
+   Only report "waiting" after you sent the request, retried the action, or recorded the exact blocker with enough detail to resume quickly.
+
+3. **Verify before asserting.**
+   For concrete facts like field names, URLs, API shapes, prices, numbers, timestamps, or what someone said, check the source before stating them. Default to lookup, not recall.
+
+4. **Read state changes should be intentional.**
+   If a system supports read, ack, triage, or similar state, do not clear it automatically just because you fetched it. Clear it only after handling it or making an explicit triage decision.
+
+5. **Report with evidence.**
+   When you say something is done, sent, blocked, or broken, include a concrete reference when possible: message link, file path, commit, command output, or exact error.
+
+6. **Leave behind an inspectable artifact.**
+   Every active work cycle should create something another person or future-you can inspect. Prefer external artifacts like messages, commits, issues, PRs, specs, or applied changes. If no external artifact is possible, leave a blocker artifact with the attempted unblock and the exact resume point.
+
 ## Make It Yours
 
 This is a starting point. Add your own conventions, style, and rules as you figure out what works.

docs/reference/templates/HEARTBEAT.dev.md

@@ -0,0 +1,13 @@
+---
+summary: "Dev agent HEARTBEAT.md"
+read_when:
+  - Using the dev gateway templates
+  - Updating the default dev agent heartbeat
+---
+
+# HEARTBEAT.md
+
+- Check for unfinished local dev work, errors, or follow-ups that need action.
+- Prefer work that leaves behind an inspectable artifact: a commit, script change, issue, note, or applied fix.
+- If you are blocked, record the attempted unblock, exact failure, and resume point before ending the cycle.
+- Reply `HEARTBEAT_OK` only when no useful action or blocker-advancing step remains.

docs/reference/templates/HEARTBEAT.md

@@ -39,3 +39,9 @@ Remove all non-comment lines below to disable heartbeat work cycles.
 - Rotate through these — you don't need to do everything every cycle
 - Track state in `memory/heartbeat-state.json` to avoid repeating yourself
 - Bias toward action over silence
+- Prefer actions that create new information or visible progress over passive review
+- If blocked, advance the dependency or record the exact blocker before ending the cycle
+- Leave one inspectable artifact behind in each active cycle; prefer sent messages, commits, issues, specs, or applied changes
+- If no external artifact is possible, record the attempted unblock and exact resume point before ending the cycle
+- When reporting progress, include concrete evidence when possible
+- `HEARTBEAT_OK` is for genuine no-op cycles, not for avoiding the next useful action

src/agents/memory-search.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import type { OpenClawConfig, MemorySearchConfig } from "../config/config.js";
 import { resolveStateDir } from "../config/paths.js";
 import type { SecretInput } from "../config/types.secrets.js";
+import { createSubsystemLogger } from "../logging/subsystem.js";
 import { clampInt, clampNumber, resolveUserPath } from "../utils.js";
 import { resolveAgentConfig } from "./agent-scope.js";
 
@@ -102,6 +103,70 @@ const DEFAULT_TEMPORAL_DECAY_ENABLED = false;
 const DEFAULT_TEMPORAL_DECAY_HALF_LIFE_DAYS = 30;
 const DEFAULT_CACHE_ENABLED = true;
 const DEFAULT_SOURCES: ReadonlyArray<"memory" | "sessions" | "history"> = ["memory"];
+const log = createSubsystemLogger("memory");
+const RESOLVED_MEMORY_CONFIG_LOG_STATE = new Map<string, string>();
+
+function summarizePathListForLog(paths: string[], max = 8): string[] {
+  if (paths.length <= max) {
+    return paths;
+  }
+  return [...paths.slice(0, max), `... (+${paths.length - max} more)`];
+}
+
+function maybeLogResolvedMemorySearchConfig(params: {
+  agentId: string;
+  defaults: MemorySearchConfig | undefined;
+  overrides: MemorySearchConfig | undefined;
+  resolved: ResolvedMemorySearchConfig | null;
+}): void {
+  const summary = params.resolved
+    ? {
+        agentId: params.agentId,
+        enabled: true,
+        hasDefaults: Boolean(params.defaults),
+        hasOverrides: Boolean(params.overrides),
+        provider: params.resolved.provider,
+        model: params.resolved.model || undefined,
+        fallback: params.resolved.fallback,
+        storePath: params.resolved.store.path,
+        vectorEnabled: params.resolved.store.vector.enabled,
+        sources: params.resolved.sources,
+        sessionMemory: params.resolved.experimental.sessionMemory,
+        extraPaths: summarizePathListForLog(params.resolved.extraPaths),
+        extraPathsCount: params.resolved.extraPaths.length,
+        excludePaths: summarizePathListForLog(params.resolved.excludePaths),
+        excludePathsCount: params.resolved.excludePaths.length,
+        sync: {
+          onSessionStart: params.resolved.sync.onSessionStart,
+          onSearch: params.resolved.sync.onSearch,
+          watch: params.resolved.sync.watch,
+          watchDebounceMs: params.resolved.sync.watchDebounceMs,
+          intervalMinutes: params.resolved.sync.intervalMinutes,
+          sessionDeltaBytes: params.resolved.sync.sessions.deltaBytes,
+          sessionDeltaMessages: params.resolved.sync.sessions.deltaMessages,
+        },
+        query: {
+          maxResults: params.resolved.query.maxResults,
+          minScore: params.resolved.query.minScore,
+          hybridEnabled: params.resolved.query.hybrid.enabled,
+          candidateMultiplier: params.resolved.query.hybrid.candidateMultiplier,
+          temporalDecay: params.resolved.query.hybrid.temporalDecay,
+        },
+        cacheEnabled: params.resolved.cache.enabled,
+      }
+    : {
+        agentId: params.agentId,
+        enabled: false,
+        hasDefaults: Boolean(params.defaults),
+        hasOverrides: Boolean(params.overrides),
+      };
+  const serialized = JSON.stringify(summary);
+  if (RESOLVED_MEMORY_CONFIG_LOG_STATE.get(params.agentId) === serialized) {
+    return;
+  }
+  RESOLVED_MEMORY_CONFIG_LOG_STATE.set(params.agentId, serialized);
+  log.debug("memory config resolved", summary);
+}
 
 function normalizeSources(
   sources: ReadonlyArray<"memory" | "sessions" | "history"> | undefined,
@@ -130,10 +195,13 @@ function resolveStorePath(agentId: string, raw?: string): string {
   const stateDir = resolveStateDir(process.env, os.homedir);
   const fallback = path.join(stateDir, "memory", `${agentId}.sqlite`);
   if (!raw) {
+    log.debug("memory config: store path (default)", { agentId, dbPath: fallback });
     return fallback;
   }
   const withToken = raw.includes("{agentId}") ? raw.replaceAll("{agentId}", agentId) : raw;
-  return resolveUserPath(withToken);
+  const resolved = resolveUserPath(withToken);
+  log.debug("memory config: store path", { agentId, raw, dbPath: resolved });
+  return resolved;
 }
 
 function mergeConfig(
@@ -369,7 +437,9 @@ export function resolveMemorySearchConfig(
   const overrides = resolveAgentConfig(cfg, agentId)?.memorySearch;
   const resolved = mergeConfig(defaults, overrides, agentId);
   if (!resolved.enabled) {
+    maybeLogResolvedMemorySearchConfig({ agentId, defaults, overrides, resolved: null });
     return null;
   }
+  maybeLogResolvedMemorySearchConfig({ agentId, defaults, overrides, resolved });
   return resolved;
 }

src/agents/tools/memory-tool.ts

@@ -1,7 +1,13 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawConfig } from "../../config/config.js";
 import type { MemoryCitationsMode } from "../../config/types.memory.js";
+import { createSubsystemLogger } from "../../logging/subsystem.js";
 import { resolveMemoryBackendConfig } from "../../memory/backend-config.js";
+import {
+  isDegradedMemoryStatus,
+  shortDiagnosticFingerprint,
+  summarizeMemoryStatus,
+} from "../../memory/diagnostics.js";
 import { getMemorySearchManager } from "../../memory/index.js";
 import type { MemorySearchResult } from "../../memory/types.js";
 import { parseAgentSessionKey } from "../../routing/session-key.js";
@@ -10,6 +16,8 @@ import { resolveMemorySearchConfig } from "../memory-search.js";
 import type { AnyAgentTool } from "./common.js";
 import { jsonResult, readNumberParam, readStringParam } from "./common.js";
 
+const log = createSubsystemLogger("memory-tool");
+
 const MemorySearchSchema = Type.Object({
   query: Type.String(),
   maxResults: Type.Optional(Type.Number()),
@@ -54,13 +62,20 @@ export function createMemorySearchTool(options: {
     parameters: MemorySearchSchema,
     execute: async (_toolCallId, params) => {
       const query = readStringParam(params, "query", { required: true });
+      const queryFingerprint = shortDiagnosticFingerprint(query);
       const maxResults = readNumberParam(params, "maxResults");
       const minScore = readNumberParam(params, "minScore");
       const { manager, error } = await getMemorySearchManager({
         cfg,
         agentId,
       });
       if (!manager) {
+        log.warn("memory_search tool unavailable", {
+          agentId,
+          sessionKey: options.agentSessionKey,
+          queryFingerprint,
+          error,
+        });
         return jsonResult(buildMemorySearchUnavailableResult(error));
       }
       try {
@@ -82,6 +97,26 @@ export function createMemorySearchTool(options: {
             ? clampResultsByInjectedChars(decorated, resolved.qmd?.limits.maxInjectedChars)
             : decorated;
         const searchMode = (status.custom as { searchMode?: string } | undefined)?.searchMode;
+        const logPayload = {
+          agentId,
+          sessionKey: options.agentSessionKey,
+          queryFingerprint,
+          queryLength: query.length,
+          requestedMaxResults: maxResults,
+          requestedMinScore: minScore,
+          resultCount: results.length,
+          rawResultCount: rawResults.length,
+          citations: citationsMode,
+          mode: searchMode,
+          ...summarizeMemoryStatus(status),
+        };
+        if (isDegradedMemoryStatus(status)) {
+          log.warn("memory_search tool completed with degraded backend", logPayload);
+        } else if (results.length === 0) {
+          log.info("memory_search tool returned 0 results", logPayload);
+        } else {
+          log.debug("memory_search tool completed", logPayload);
+        }
         return jsonResult({
           results,
           provider: status.provider,
@@ -92,6 +127,15 @@ export function createMemorySearchTool(options: {
         });
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        log.warn("memory_search tool failed", {
+          agentId,
+          sessionKey: options.agentSessionKey,
+          queryFingerprint,
+          queryLength: query.length,
+          requestedMaxResults: maxResults,
+          requestedMinScore: minScore,
+          error: message,
+        });
         return jsonResult(buildMemorySearchUnavailableResult(message));
       }
     },

src/auto-reply/reply/agent-runner-recall.ts

@@ -2,6 +2,7 @@ import path from "node:path";
 import { resolveMemorySearchConfig } from "../../agents/memory-search.js";
 import type { OpenClawConfig } from "../../config/config.js";
 import { createSubsystemLogger } from "../../logging/subsystem.js";
+import { shortDiagnosticFingerprint, summarizeMemoryStatus } from "../../memory/diagnostics.js";
 import { getMemorySearchManager } from "../../memory/search-manager.js";
 import type { MemorySearchResult } from "../../memory/types.js";
 
@@ -75,6 +76,7 @@ export async function runPreTurnMemoryRecall(params: {
   }
 
   const startMs = Date.now();
+  const queryFingerprint = shortDiagnosticFingerprint(params.incomingMessage);
   const searchSurfaceLines = buildSearchSurfaceLines(params.cfg, params.agentId);
 
   let managerResult;
@@ -84,7 +86,13 @@ export async function runPreTurnMemoryRecall(params: {
       agentId: params.agentId,
     });
   } catch (err) {
-    log.warn(`memory recall: failed to get manager: ${String(err)}`);
+    log.warn("memory recall: failed to get manager", {
+      agentId: params.agentId,
+      sessionKey: params.sessionKey,
+      incomingLength: params.incomingMessage.length,
+      queryFingerprint,
+      err: String(err),
+    });
     return formatRecallBlock({
       searchSurfaceLines,
       bodyLines: [
@@ -96,6 +104,13 @@ export async function runPreTurnMemoryRecall(params: {
 
   const { manager } = managerResult;
   if (!manager) {
+    log.warn("memory recall: manager unavailable", {
+      agentId: params.agentId,
+      sessionKey: params.sessionKey,
+      incomingLength: params.incomingMessage.length,
+      queryFingerprint,
+      error: managerResult.error ?? "memory manager unavailable",
+    });
     return formatRecallBlock({
       searchSurfaceLines,
       bodyLines: [
@@ -106,17 +121,27 @@ export async function runPreTurnMemoryRecall(params: {
   }
 
   let results: MemorySearchResult[];
+  const extraCandidates = (settings.excludeBootstrapped ? 3 : 0) + (settings.randomSlot ? 2 : 0);
+  const requestCount = settings.maxResults + extraCandidates;
   try {
     // Request extra candidates for filtering headroom (bootstrapped exclusion + random slot)
-    const extraCandidates = (settings.excludeBootstrapped ? 3 : 0) + (settings.randomSlot ? 2 : 0);
-    const requestCount = settings.maxResults + extraCandidates;
     results = await manager.search(params.incomingMessage, {
       maxResults: requestCount,
       minScore: settings.minScore,
       sessionKey: params.sessionKey,
     });
   } catch (err) {
-    log.warn(`memory recall: search failed: ${String(err)}`);
+    const status = manager.status();
+    log.warn("memory recall: search failed", {
+      agentId: params.agentId,
+      sessionKey: params.sessionKey,
+      incomingLength: params.incomingMessage.length,
+      queryFingerprint,
+      requestedMaxResults: requestCount,
+      minScore: settings.minScore,
+      err: String(err),
+      ...summarizeMemoryStatus(status),
+    });
     return formatRecallBlock({
       searchSurfaceLines,
       bodyLines: [
@@ -153,7 +178,17 @@ export async function runPreTurnMemoryRecall(params: {
 
   if (!results.length) {
     const elapsedMs = Date.now() - startMs;
-    log.info(`memory recall: 0 results (${elapsedMs}ms)`);
+    const status = manager.status();
+    log.info("memory recall: 0 results", {
+      agentId: params.agentId,
+      sessionKey: params.sessionKey,
+      elapsedMs,
+      incomingLength: params.incomingMessage.length,
+      queryFingerprint,
+      requestedMaxResults: requestCount,
+      minScore: settings.minScore,
+      ...summarizeMemoryStatus(status),
+    });
     return formatRecallBlock({
       searchSurfaceLines,
       bodyLines: [

src/cli/gateway-cli/dev.ts

@@ -57,7 +57,7 @@ async function ensureDevWorkspace(dir: string) {
   const resolvedDir = resolveUserPath(dir);
   await fs.promises.mkdir(resolvedDir, { recursive: true });
 
-  const [agents, soul, tools, identity, user] = await Promise.all([
+  const [agents, soul, tools, identity, user, heartbeat] = await Promise.all([
     loadDevTemplate(
       "AGENTS.dev.md",
       `# AGENTS.md - OpenClaw Dev Workspace\n\nDefault dev workspace for openclaw gateway --dev.\n`,
@@ -78,13 +78,18 @@ async function ensureDevWorkspace(dir: string) {
       "USER.dev.md",
       `# USER.md - User Profile\n\n- Name:\n- Preferred address:\n- Notes:\n`,
     ),
+    loadDevTemplate(
+      "HEARTBEAT.dev.md",
+      "# HEARTBEAT.md\n\n- Follow up on unfinished dev work.\n- Leave behind a commit, fix, or blocker note.\n- Reply HEARTBEAT_OK only when nothing useful remains.\n",
+    ),
   ]);
 
   await writeFileIfMissing(path.join(resolvedDir, "AGENTS.md"), agents);
   await writeFileIfMissing(path.join(resolvedDir, "SOUL.md"), soul);
   await writeFileIfMissing(path.join(resolvedDir, "TOOLS.md"), tools);
   await writeFileIfMissing(path.join(resolvedDir, "IDENTITY.md"), identity);
   await writeFileIfMissing(path.join(resolvedDir, "USER.md"), user);
+  await writeFileIfMissing(path.join(resolvedDir, "HEARTBEAT.md"), heartbeat);
 }
 
 export async function ensureDevGatewayConfig(opts: { reset?: boolean }) {

src/config/io.ts

@@ -810,6 +810,9 @@ export function createConfigIO(overrides: ConfigIoDeps = {}) {
       }
       const error = err as { code?: string };
       if (error?.code === "INVALID_CONFIG") {
+        deps.logger.warn(
+          `Invalid config fallback at ${configPath}: returning empty config object for this read`,
+        );
         return {};
       }
       deps.logger.error(`Failed to read config at ${configPath}`, err);