@simbimbo/memory-ocmemog 0.1.14 → 0.1.16

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.1.16 — 2026-03-25
+
+Platform support doc clarification for Linux/Windows service guidance.
+
+### Highlights
+- documented Linux systemd and Windows service runner guidance (no new code changes)
+
+## 0.1.15 — 2026-03-25
+
+Hydration stabilization + cross-platform default cleanup.
+
+### Highlights
+- made `/conversation/hydrate` read-only (no inline `refresh_state()` on the hot read path)
+- added hydrate stage timing + refresh_state source tagging for root-cause clarity
+- added plugin prepend-size logging and a dedicated hydrate stress harness
+- expanded platform-aware OpenClaw home defaults (OPENCLAW_HOME / OCMEMOG_OPENCLAW_HOME / XDG / Windows AppData)
+- updated transcript/test rig helpers and docs to match cross-platform defaults
+
 ## 0.1.14 — 2026-03-22
 
 Corrective follow-up to make the published release fully version-aligned.

package/README.md

@@ -73,10 +73,10 @@ The doctor command currently checks:
 
 ```bash
 # defaults:
-# - transcript mode: ~/.openclaw/workspace/memory/transcripts
-# - session mode: ~/.openclaw/agents/main/sessions (used when OCMEMOG_TRANSCRIPT_DIR is unset)
-export OCMEMOG_TRANSCRIPT_DIR="$HOME/.openclaw/workspace/memory/transcripts"
-export OCMEMOG_SESSION_DIR="$HOME/.openclaw/agents/main/sessions"
+# - transcript mode: <openclaw-home>/workspace/memory/transcripts
+# - session mode: <openclaw-home>/agents/main/sessions (used when OCMEMOG_TRANSCRIPT_DIR is unset)
+export OCMEMOG_TRANSCRIPT_DIR="${OPENCLAW_HOME:-$HOME/.openclaw}/workspace/memory/transcripts"
+export OCMEMOG_SESSION_DIR="${OPENCLAW_HOME:-$HOME/.openclaw}/agents/main/sessions"
 ./scripts/ocmemog-transcript-watcher.sh
 ```
 
@@ -117,9 +117,10 @@ Optional environment variables:
 - `OCMEMOG_EMBED_MODEL_LOCAL` (`simple` by default; legacy alias: `BRAIN_EMBED_MODEL_LOCAL`)
 - `OCMEMOG_EMBED_MODEL_PROVIDER` (`local-openai` to use the local llama.cpp embedding endpoint; `openai` remains available for hosted embeddings; legacy alias: `BRAIN_EMBED_MODEL_PROVIDER`)
 - `OCMEMOG_TRANSCRIPT_WATCHER` (`true` to auto-start transcript watcher inside the sidecar)
-- `OCMEMOG_TRANSCRIPT_ROOTS` (comma-separated allowed roots for transcript context retrieval; default: `~/.openclaw/workspace/memory`)
-- `OCMEMOG_TRANSCRIPT_DIR` (default: `~/.openclaw/workspace/memory/transcripts`)
-- `OCMEMOG_SESSION_DIR` (default: `~/.openclaw/agents/main/sessions`)
+- `OPENCLAW_HOME` / `OCMEMOG_OPENCLAW_HOME` (optional OpenClaw home override; default fallback is platform-aware: `~/.openclaw` on Unix, `XDG_DATA_HOME/openclaw` when set, or `%APPDATA%/OpenClaw` on Windows)
+- `OCMEMOG_TRANSCRIPT_ROOTS` (comma-separated allowed roots for transcript context retrieval; default: `<openclaw-home>/workspace/memory`)
+- `OCMEMOG_TRANSCRIPT_DIR` (default: `<openclaw-home>/workspace/memory/transcripts`)
+- `OCMEMOG_SESSION_DIR` (default: `<openclaw-home>/agents/main/sessions`)
 - `OCMEMOG_TRANSCRIPT_POLL_SECONDS` (poll interval for file/session watcher; default: `30`, or `120` in battery mode)
 - `OCMEMOG_INGEST_BATCH_SECONDS` (max lines per watcher batch; default: `30`, or `120` in battery mode)
 - `OCMEMOG_INGEST_BATCH_MAX` (max watcher batches before yield; default: `25`, or `10` in battery mode)
@@ -157,6 +158,15 @@ Boolean env values are parsed case-insensitively and support `1/0`, `true/false`
 - Sidecar binds to **127.0.0.1** by default. Keep it local unless you add auth + firewall rules.
 - If you expose the sidecar, set `OCMEMOG_API_TOKEN` and pass the header `x-ocmemog-token`.
 
+## Platform support
+
+- **Core Python package / sidecar:** intended to run cross-platform when Python + SQLite are available.
+- **Watcher path defaults:** now resolve from a platform-aware OpenClaw home (`OPENCLAW_HOME` / `OCMEMOG_OPENCLAW_HOME`, XDG, Windows AppData, then legacy `~/.openclaw`).
+- **Service/install helpers:** still split by platform.
+  - macOS: LaunchAgents supported in-tree
+  - Linux: run the sidecar directly with env overrides; if you want a service, create a systemd unit that calls `scripts/ocmemog-sidecar.sh` from your venv
+  - Windows: run the sidecar directly with env overrides; use Task Scheduler or NSSM if you need a persistent service
+
 ## One‑shot installer (macOS / local dev)
 
 ```bash
@@ -213,7 +223,7 @@ launchctl bootstrap gui/$UID scripts/launchagents/com.openclaw.ocmemog.guard.pli
 
 ## Recent changes
 
-### 0.1.14 (current main)
+### 0.1.16 (current main)
 
 Current main now includes:
 - integrated release-gate validation with a fresh-state memory contract proof

package/index.ts

@@ -1,4 +1,7 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/memory-core";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
 
 const DEFAULT_ENDPOINT = "http://127.0.0.1:17891";
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -12,6 +15,10 @@ type PluginConfig = {
 const AUTO_HYDRATION_ENABLED = ["1", "true", "yes"].includes(
   String(process.env.OCMEMOG_AUTO_HYDRATION ?? "false").trim().toLowerCase(),
 );
+const DURABLE_OUTBOX_ENABLED = !["0", "false", "no"].includes(
+  String(process.env.OCMEMOG_DURABLE_OUTBOX ?? "true").trim().toLowerCase(),
+);
+const DEFAULT_OUTBOX_PATH = path.join(os.homedir(), ".openclaw", "ocmemog-outbox.json");
 
 type SearchResponse = {
   ok: boolean;
@@ -57,6 +64,7 @@ type ConversationHydrateResponse = {
   recent_turns?: Array<Record<string, unknown>>;
   linked_memories?: Array<{ reference?: string; content?: string }>;
   summary?: Record<string, unknown>;
+  predictive_brief?: Record<string, unknown>;
   state?: Record<string, unknown>;
   error?: string;
 };
@@ -73,6 +81,122 @@ type ConversationScope = {
   thread_id?: string;
 };
 
+type DurableOutboxRecord = {
+  id: string;
+  kind: "conversation_ingest" | "conversation_checkpoint";
+  path: string;
+  body: Record<string, unknown>;
+  createdAt: string;
+  attempts: number;
+  lastError?: string;
+};
+
+function durableOutboxPath(): string {
+  const raw = String(process.env.OCMEMOG_DURABLE_OUTBOX_PATH ?? DEFAULT_OUTBOX_PATH).trim();
+  return raw || DEFAULT_OUTBOX_PATH;
+}
+
+function makeOutboxRecord(kind: DurableOutboxRecord["kind"], pathValue: string, body: Record<string, unknown>): DurableOutboxRecord {
+  return {
+    id: `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`,
+    kind,
+    path: pathValue,
+    body,
+    createdAt: new Date().toISOString(),
+    attempts: 0,
+  };
+}
+
+async function loadOutbox(): Promise<DurableOutboxRecord[]> {
+  if (!DURABLE_OUTBOX_ENABLED) return [];
+  const filePath = durableOutboxPath();
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? (parsed as DurableOutboxRecord[]) : [];
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException)?.code;
+    if (code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+async function saveOutbox(records: DurableOutboxRecord[]): Promise<void> {
+  if (!DURABLE_OUTBOX_ENABLED) return;
+  const filePath = durableOutboxPath();
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, JSON.stringify(records, null, 2), "utf8");
+}
+
+async function enqueueOutbox(record: DurableOutboxRecord): Promise<void> {
+  if (!DURABLE_OUTBOX_ENABLED) return;
+  const records = await loadOutbox();
+  records.push(record);
+  await saveOutbox(records);
+}
+
+async function flushOutbox(
+  api: OpenClawPluginApi,
+  config: PluginConfig,
+  options: { maxItems?: number } = {},
+): Promise<void> {
+  const maxItems = options.maxItems ?? 25;
+  if (!DURABLE_OUTBOX_ENABLED) return;
+  const records = await loadOutbox();
+  if (!records.length) return;
+  const remaining: DurableOutboxRecord[] = [];
+  let processed = 0;
+  for (let index = 0; index < records.length; index += 1) {
+    const record = records[index];
+    if (processed >= maxItems) {
+      remaining.push(...records.slice(index));
+      break;
+    }
+    try {
+      await postJson(config, record.path, record.body);
+      processed += 1;
+    } catch (error) {
+      remaining.push({
+        ...record,
+        attempts: (record.attempts || 0) + 1,
+        lastError: error instanceof Error ? error.message : String(error),
+      });
+      remaining.push(...records.slice(index + 1));
+      break;
+    }
+  }
+  await saveOutbox(remaining);
+  if (processed > 0) {
+    api.logger.info(`ocmemog durable outbox flushed ${processed} item(s)`);
+  }
+}
+
+async function durablePostJson(
+  api: OpenClawPluginApi,
+  config: PluginConfig,
+  record: DurableOutboxRecord,
+  options: { flushFirst?: boolean } = {},
+): Promise<void> {
+  const flushFirst = options.flushFirst ?? true;
+  if (flushFirst) {
+    try {
+      await flushOutbox(api, config);
+    } catch (error) {
+      api.logger.warn(`ocmemog durable outbox pre-flush failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  try {
+    await postJson(config, record.path, record.body);
+  } catch (error) {
+    await enqueueOutbox({
+      ...record,
+      attempts: (record.attempts || 0) + 1,
+      lastError: error instanceof Error ? error.message : String(error),
+    });
+    throw error;
+  }
+}
+
 function readConfig(raw: unknown): PluginConfig {
   const cfg = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
   return {
@@ -299,6 +423,52 @@ function sanitizeContinuityNoise(text: string, maxLen = 280): string {
   return cleaned;
 }
 
+function buildPredictiveBriefContext(payload: ConversationHydrateResponse): string {
+  if (!payload.ok) {
+    return "";
+  }
+  const brief = asRecord(payload.predictive_brief);
+  if (!brief) {
+    return "";
+  }
+  const lines: string[] = [];
+  const lane = sanitizeContinuityNoise(firstString(brief.lane), 48);
+  if (lane) {
+    lines.push(`Lane: ${lane}`);
+  }
+  const checkpoint = asRecord(brief.checkpoint);
+  const checkpointSummary = sanitizeContinuityNoise(firstString(checkpoint?.summary), 140);
+  if (checkpointSummary) {
+    lines.push(`Checkpoint: ${checkpointSummary}`);
+  }
+  const memories = Array.isArray(brief.memories) ? brief.memories : [];
+  const memoryLines = memories
+    .slice(0, 4)
+    .map((item) => {
+      const record = asRecord(item);
+      return sanitizeContinuityNoise(firstString(record?.content, record?.reference), 120);
+    })
+    .filter(Boolean);
+  if (memoryLines.length) {
+    lines.push(`Likely-needed facts: ${memoryLines.join(" | ")}`);
+  }
+  const openLoops = Array.isArray(brief.open_loops) ? brief.open_loops : [];
+  const openLoopLines = openLoops
+    .slice(0, 2)
+    .map((item) => {
+      const record = asRecord(item);
+      return sanitizeContinuityNoise(firstString(record?.summary, record?.reference), 100);
+    })
+    .filter(Boolean);
+  if (openLoopLines.length) {
+    lines.push(`Open loops: ${openLoopLines.join(" | ")}`);
+  }
+  if (!lines.length) {
+    return "";
+  }
+  return `Working memory brief (JIT by ocmemog):\n- ${lines.join("\n- ")}`;
+}
+
 function buildHydrationContext(payload: ConversationHydrateResponse): string {
   if (!payload.ok) {
     return "";
@@ -352,6 +522,10 @@ function buildTurnMetadata(message: unknown, ctx: { agentId?: string; sessionKey
 }
 
 function registerAutomaticContinuityHooks(api: OpenClawPluginApi, config: PluginConfig) {
+  void flushOutbox(api, config).catch((error) => {
+    api.logger.warn(`ocmemog durable outbox startup flush failed: ${error instanceof Error ? error.message : String(error)}`);
+  });
+
   api.on("before_message_write", (event, ctx) => {
     try {
       const role = extractRole(event.message);
@@ -366,7 +540,7 @@ function registerAutomaticContinuityHooks(api: OpenClawPluginApi, config: Plugin
       if (!scope.session_id && !scope.thread_id && !scope.conversation_id) {
         return;
       }
-      void postJson<{ ok: boolean }>(config, "/conversation/ingest_turn", {
+      const body = {
         ...scope,
         role,
         content,
@@ -374,8 +548,9 @@ function registerAutomaticContinuityHooks(api: OpenClawPluginApi, config: Plugin
         timestamp: extractTimestamp(event.message),
         source: "openclaw.before_message_write",
         metadata: buildTurnMetadata(event.message, ctx),
-      }).catch((error) => {
-        api.logger.warn(`ocmemog continuity ingest failed: ${error instanceof Error ? error.message : String(error)}`);
+      };
+      void durablePostJson(api, config, makeOutboxRecord("conversation_ingest", "/conversation/ingest_turn", body)).catch((error) => {
+        api.logger.warn(`ocmemog continuity ingest failed (queued for retry): ${error instanceof Error ? error.message : String(error)}`);
       });
     } catch (error) {
       api.logger.warn(`ocmemog continuity ingest scheduling failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -387,6 +562,7 @@ function registerAutomaticContinuityHooks(api: OpenClawPluginApi, config: Plugin
   // failures if a host runtime persists prepended context into transcript history.
   // Keep the memory backend and sidecar tools active, but only prepend continuity
   // when explicitly enabled and after the host runtime has been validated.
+  api.logger.info(`ocmemog auto hydration env raw=${String(process.env.OCMEMOG_AUTO_HYDRATION ?? '<unset>')} computed=${String(AUTO_HYDRATION_ENABLED)}`);
   if (AUTO_HYDRATION_ENABLED) {
     api.on("before_prompt_build", async (event, ctx) => {
       try {
@@ -399,7 +575,12 @@ function registerAutomaticContinuityHooks(api: OpenClawPluginApi, config: Plugin
           turns_limit: 4,
           memory_limit: 3,
         });
-        const prependContext = buildHydrationContext(payload);
+        const briefContext = buildPredictiveBriefContext(payload);
+        const continuityContext = buildHydrationContext(payload);
+        const prependContext = [briefContext, continuityContext].filter(Boolean).join("\n\n");
+        api.logger.info(
+          `ocmemog hydration prepend sizes brief=${briefContext.length} continuity=${continuityContext.length} combined=${prependContext.length}`,
+        );
         if (!prependContext) {
           return;
         }
@@ -419,11 +600,15 @@ function registerAutomaticContinuityHooks(api: OpenClawPluginApi, config: Plugin
       if (!sessionId) {
         return;
       }
-      await postJson<ConversationCheckpointResponse>(config, "/conversation/checkpoint", {
-        session_id: sessionId,
-        checkpoint_kind: "compaction",
-        turns_limit: 32,
-      });
+      await durablePostJson(
+        api,
+        config,
+        makeOutboxRecord("conversation_checkpoint", "/conversation/checkpoint", {
+          session_id: sessionId,
+          checkpoint_kind: "compaction",
+          turns_limit: 32,
+        }),
+      );
     } catch (error) {
       api.logger.warn(`ocmemog compaction checkpoint failed: ${error instanceof Error ? error.message : String(error)}`);
     }
@@ -435,11 +620,15 @@ function registerAutomaticContinuityHooks(api: OpenClawPluginApi, config: Plugin
       if (!sessionId) {
         return;
       }
-      await postJson<ConversationCheckpointResponse>(config, "/conversation/checkpoint", {
-        session_id: sessionId,
-        checkpoint_kind: "session_end",
-        turns_limit: 48,
-      });
+      await durablePostJson(
+        api,
+        config,
+        makeOutboxRecord("conversation_checkpoint", "/conversation/checkpoint", {
+          session_id: sessionId,
+          checkpoint_kind: "session_end",
+          turns_limit: 48,
+        }),
+      );
     } catch (error) {
       api.logger.warn(`ocmemog session-end checkpoint failed: ${error instanceof Error ? error.message : String(error)}`);
     }
@@ -473,6 +662,14 @@ const ocmemogPlugin = {
               items: { type: "string" },
               description: "Memory category.",
             },
+            metadataFilters: {
+              type: "object",
+              description: "Optional metadata filters (for example { domain: 'tbc', site: 'dal' }).",
+            },
+            lane: {
+              type: "string",
+              description: "Optional retrieval lane/domain hint (for example 'tbc'). Usually not needed when query context is clear.",
+            },
           },
         },
         async execute(_toolCallId: string, params: Record<string, unknown>) {
@@ -481,6 +678,8 @@ const ocmemogPlugin = {
               query: params.query,
               limit: params.limit,
               categories: params.categories,
+              metadata_filters: params.metadataFilters,
+              lane: params.lane,
             });
 
             const results = payload.results ?? [];
@@ -648,6 +847,7 @@ const ocmemogPlugin = {
             memoryType: { type: "string", description: "memory bucket (knowledge/reflections/etc.)" },
             source: { type: "string", description: "Optional source label." },
             taskId: { type: "string", description: "Optional task id for experience ingest." },
+            metadata: { type: "object", description: "Optional structured metadata (for example { domain: 'tbc', site: 'dal' })." },
           },
         },
         async execute(_toolCallId: string, params: Record<string, unknown>) {
@@ -658,6 +858,7 @@ const ocmemogPlugin = {
               memory_type: params.memoryType,
               source: params.source,
               task_id: params.taskId,
+              metadata: params.metadata,
             });
             return {
               content: [{ type: "text", text: `memory_ingest: ${payload.ok ? "ok" : "failed"}` }],

package/ocmemog/__init__.py

@@ -7,6 +7,6 @@ from importlib.metadata import PackageNotFoundError, version as _package_version
 try:
     __version__ = _package_version("ocmemog-sidecar")
 except PackageNotFoundError:  # pragma: no cover - package metadata may be unavailable in source layouts.
-    __version__ = "0.1.14"
+    __version__ = "0.1.16"
 
 __all__ = ["__version__"]

package/ocmemog/runtime/memory/conversation_state.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import json
 import os
 import re
+import sys
+import time
 from typing import Any, Dict, List, Optional, Sequence, Tuple
 
 from ocmemog.runtime import state_store
@@ -17,6 +19,7 @@ _COMMITMENT_RE = re.compile(
 )
 _CHECKPOINT_EVERY = max(0, int(os.environ.get("OCMEMOG_CONVERSATION_CHECKPOINT_EVERY", "6") or "6"))
 _MAX_STATE_TURNS = max(6, int(os.environ.get("OCMEMOG_CONVERSATION_STATE_TURNS", "24") or "24"))
+_SESSION_SOURCE_INLINE_MAINTENANCE = os.environ.get("OCMEMOG_SESSION_SOURCE_INLINE_MAINTENANCE", "false").strip().lower() in {"1", "true", "yes", "on"}
 _SHORT_REPLY_NORMALIZED = {
     "yes",
     "yeah",
@@ -578,6 +581,17 @@ def _get_turns_between_ids(
     return _rows_to_turns(rows)
 
 
+def _normalized_turn_source(source: Optional[str]) -> str:
+    return str(source or "").strip().lower()
+
+
+def _should_run_inline_turn_maintenance(*, source: Optional[str]) -> bool:
+    normalized = _normalized_turn_source(source)
+    if normalized == "session" and not _SESSION_SOURCE_INLINE_MAINTENANCE:
+        return False
+    return True
+
+
 def record_turn(
     *,
     role: str,
@@ -711,34 +725,107 @@ def record_turn(
         finally:
             conn.close()
 
-    turn_id = int(store.submit_write(_write, timeout=30.0))
-    try:
-        refresh_state(
-            conversation_id=conversation_id,
-            session_id=session_id,
-            thread_id=thread_id,
-        )
-        if _CHECKPOINT_EVERY > 0:
-            counts = get_turn_counts(conversation_id=conversation_id, session_id=session_id, thread_id=thread_id)
-            if counts["total"] > 0 and counts["total"] % _CHECKPOINT_EVERY == 0:
-                latest = get_latest_checkpoint(conversation_id=conversation_id, session_id=session_id, thread_id=thread_id)
-                if not latest or int(latest.get("turn_end_id") or 0) < turn_id:
-                    create_checkpoint(
-                        conversation_id=conversation_id,
-                        session_id=session_id,
-                        thread_id=thread_id,
-                        upto_turn_id=turn_id,
-                        checkpoint_kind="rolling",
-                    )
-    except Exception as exc:
+    def _write_session_fast() -> int:
+        conn = store.connect()
+        try:
+            if timestamp:
+                cur = conn.execute(
+                    """
+                    INSERT INTO conversation_turns (
+                        timestamp, conversation_id, session_id, thread_id, message_id,
+                        role, content, transcript_path, transcript_offset, transcript_end_offset,
+                        source, metadata_json, schema_version
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                    """,
+                    (
+                        timestamp,
+                        conversation_id,
+                        session_id,
+                        thread_id,
+                        message_id,
+                        turn_role,
+                        turn_content,
+                        transcript_path,
+                        transcript_offset,
+                        transcript_end_offset,
+                        source,
+                        json.dumps(enriched_metadata, ensure_ascii=False),
+                        store.SCHEMA_VERSION,
+                    ),
+                )
+            else:
+                cur = conn.execute(
+                    """
+                    INSERT INTO conversation_turns (
+                        conversation_id, session_id, thread_id, message_id,
+                        role, content, transcript_path, transcript_offset, transcript_end_offset,
+                        source, metadata_json, schema_version
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                    """,
+                    (
+                        conversation_id,
+                        session_id,
+                        thread_id,
+                        message_id,
+                        turn_role,
+                        turn_content,
+                        transcript_path,
+                        transcript_offset,
+                        transcript_end_offset,
+                        source,
+                        json.dumps(enriched_metadata, ensure_ascii=False),
+                        store.SCHEMA_VERSION,
+                    ),
+                )
+            conn.commit()
+            return int(cur.lastrowid)
+        finally:
+            conn.close()
+
+    normalized_source = _normalized_turn_source(source)
+    writer = _write_session_fast if normalized_source == "session" else _write
+    turn_id = int(store.submit_write(writer, timeout=30.0))
+    maintenance_ran = False
+    if _should_run_inline_turn_maintenance(source=source):
+        try:
+            refresh_state(
+                conversation_id=conversation_id,
+                session_id=session_id,
+                thread_id=thread_id,
+                source="record_turn",
+            )
+            if _CHECKPOINT_EVERY > 0:
+                counts = get_turn_counts(conversation_id=conversation_id, session_id=session_id, thread_id=thread_id)
+                if counts["total"] > 0 and counts["total"] % _CHECKPOINT_EVERY == 0:
+                    latest = get_latest_checkpoint(conversation_id=conversation_id, session_id=session_id, thread_id=thread_id)
+                    if not latest or int(latest.get("turn_end_id") or 0) < turn_id:
+                        create_checkpoint(
+                            conversation_id=conversation_id,
+                            session_id=session_id,
+                            thread_id=thread_id,
+                            upto_turn_id=turn_id,
+                            checkpoint_kind="rolling",
+                        )
+            maintenance_ran = True
+        except Exception as exc:
+            if normalized_source != "session":
+                emit_event(
+                    LOGFILE,
+                    "brain_conversation_turn_post_write_maintenance_failed",
+                    status="warn",
+                    error=str(exc),
+                    turn_id=turn_id,
+                )
+    if normalized_source != "session":
         emit_event(
             LOGFILE,
-            "brain_conversation_turn_post_write_maintenance_failed",
-            status="warn",
-            error=str(exc),
+            "brain_conversation_turn_recorded",
+            status="ok",
+            role=turn_role,
             turn_id=turn_id,
+            source=source or "",
+            inline_maintenance=maintenance_ran,
         )
-    emit_event(LOGFILE, "brain_conversation_turn_recorded", status="ok", role=turn_role, turn_id=turn_id)
     return turn_id
 
 
@@ -1468,7 +1555,7 @@ def create_checkpoint(
     emit_event(LOGFILE, "brain_conversation_checkpoint_created", status="ok", checkpoint_id=checkpoint_id, checkpoint_kind=checkpoint_kind)
     payload = get_checkpoint_by_id(checkpoint_id)
     try:
-        refresh_state(conversation_id=conversation_id, session_id=session_id, thread_id=thread_id)
+        refresh_state(conversation_id=conversation_id, session_id=session_id, thread_id=thread_id, source="checkpoint")
     except Exception as exc:
         emit_event(
             LOGFILE,
@@ -1761,7 +1848,9 @@ def refresh_state(
     session_id: Optional[str] = None,
     thread_id: Optional[str] = None,
     tolerate_write_failure: bool = False,
+    source: str = "unknown",
 ) -> Optional[Dict[str, Any]]:
+    refresh_started = time.perf_counter()
     _self_heal_legacy_continuity_artifacts(
         conversation_id=conversation_id,
         session_id=session_id,
@@ -1795,8 +1884,9 @@ def refresh_state(
         latest_checkpoint=latest_checkpoint,
         linked_memories=[],
     )
+    result: Optional[Dict[str, Any]]
     try:
-        return _upsert_state(
+        result = _upsert_state(
             conversation_id=conversation_id,
             session_id=session_id,
             thread_id=thread_id,
@@ -1822,10 +1912,26 @@ def refresh_state(
         if existing:
             metadata = existing.get("metadata") if isinstance(existing.get("metadata"), dict) else {}
             existing["metadata"] = {**metadata, "state_status": "stale_persisted"}
-            return existing
-        return _state_from_payload(
-            payload,
-            conversation_id=conversation_id,
-            session_id=session_id,
-            thread_id=thread_id,
+            result = existing
+        else:
+            result = _state_from_payload(
+                payload,
+                conversation_id=conversation_id,
+                session_id=session_id,
+                thread_id=thread_id,
+            )
+    elapsed_ms = round((time.perf_counter() - refresh_started) * 1000, 3)
+    trace_refresh = str(os.environ.get("OCMEMOG_TRACE_REFRESH_STATE", "")).strip().lower() in {"1", "true", "yes", "on"}
+    warn_ms_raw = os.environ.get("OCMEMOG_TRACE_REFRESH_STATE_WARN_MS", "15").strip()
+    try:
+        warn_ms = max(0.0, float(warn_ms_raw))
+    except Exception:
+        warn_ms = 15.0
+    if trace_refresh or elapsed_ms >= warn_ms:
+        print(
+            "[ocmemog][state] refresh_state "
+            f"source={source or 'unknown'} elapsed_ms={elapsed_ms:.3f} turns={len(turns)} unresolved_items={len(unresolved_items)} "
+            f"conversation_id={conversation_id or '-'} session_id={session_id or '-'} thread_id={thread_id or '-'}",
+            file=sys.stderr,
         )
+    return result