diff --git a/src/agents/cache-trace.ts b/src/agents/cache-trace.ts
index 62d672ad575a..4dfd6b52cb44 100644
--- a/src/agents/cache-trace.ts
+++ b/src/agents/cache-trace.ts
@@ -1,3 +1,6 @@
+/**
+ * Optional JSONL diagnostics for agent cache/session/prompt tracing.
+ */
 import crypto from "node:crypto";
 import path from "node:path";
 import { resolveStateDir } from "../config/paths.js";
@@ -11,8 +14,8 @@ import type { AgentMessage, StreamFn } from "./runtime/index.js";
 import { stableStringify } from "./stable-stringify.js";
 import { buildAgentTraceBase } from "./trace-base.js";
 
-// Optional cache-trace diagnostics for prompt/session/cache debugging. Payloads
-// are redacted before JSONL output while stable digests preserve correlation.
+// Payloads are redacted before JSONL output while stable digests preserve
+// correlation across prompt/session/cache stages.
 type CacheTraceStage =
   | "cache:result"
   | "cache:state"
diff --git a/src/agents/cache/agent-cache-store.sqlite.ts b/src/agents/cache/agent-cache-store.sqlite.ts
index 6e241d6a7db1..b5f2dc290481 100644
--- a/src/agents/cache/agent-cache-store.sqlite.ts
+++ b/src/agents/cache/agent-cache-store.sqlite.ts
@@ -1,3 +1,6 @@
+/**
+ * SQLite implementation of the agent runtime cache store.
+ */
 import {
   MAX_DATE_TIMESTAMP_MS,
   asDateTimestampMs,
@@ -24,13 +27,13 @@ import type {
   AgentRuntimeCacheWriteOptions,
 } from "./agent-cache-store.js";
 
-// SQLite-backed agent runtime cache. Entries are scoped per agent/scope pair and
-// can store JSON values, binary blobs, and optional expiration timestamps.
+/** Options for an agent/scope-scoped SQLite runtime cache. */
 export type SqliteAgentCacheStoreOptions = OpenClawAgentDatabaseOptions & {
   scope: string;
   now?: () => number;
 };
 
+/** Options for writing a single SQLite agent cache entry. */
 export type WriteSqliteAgentCacheEntryOptions = SqliteAgentCacheStoreOptions &
   AgentRuntimeCacheWriteOptions;