feat(openclaw): JSONL-backed retain queue for external API resilience

[akhater]

Summary

• When the external Hindsight API is unreachable, retain requests are now buffered in a local SQLite database (~/.openclaw/data/hindsight-retain-queue.db) instead of being silently lost
• Queue automatically flushes when connectivity is restored — either on next successful retain or via a periodic timer (default: every 60s)
• Queue persists across process restarts, so no memories are lost during outages or Azure App Service restarts
• Only active in external API mode — local daemon mode handles its own persistence, so the queue is never created and better-sqlite3 is never loaded

New config options

Option	Type	Default	Description
retainQueuePath	string	~/.openclaw/data/hindsight-retain-queue.db	SQLite DB path
retainQueueMaxAgeMs	number	-1 (forever)	Max age for queued items
retainQueueFlushIntervalMs	number	60000 (1 min)	Periodic flush interval

How it works

1. Retain HTTP call fails → request stored in SQLite with bank ID, full payload, metadata, and timestamp
2. Next successful retain triggers a flush attempt for queued items
3. Periodic timer also attempts flush every 60s
4. On flush: items sent FIFO, removed on success, stops on first failure (API still down)
5. On shutdown: queue closes cleanly, pending items preserved for next startup

Logging

• API unreachable — retain queued (3 pending, bank: max-openclaw): connect ECONNREFUSED
• Retain queue: 3 items pending from previous session, will flush shortly
• Queue flush: 3 queued retains delivered, queue empty

Test plan

• All 62 existing unit tests pass
• Builds cleanly with TypeScript
• better-sqlite3 lazy-loaded — daemon mode users unaffected
• Integration test: stop API, send messages, restart API, verify queue flushes

🤖 Generated with Claude Code

Heads up: PR includes the Claude Code attribution line — just letting you know before you see it.

[nicoloboschi]

Hey this might be a good idea, but let's use normal files, not SQLite. What we really need is to persist Json lines as payload to send once the API is active again

[akhater]

Makes total sense — swapped to a simple JSONL file. No more SQLite, no native deps. Each line is the exact JSON payload that would've gone to the API. Same queue logic (enqueue on failure, periodic flush, FIFO delivery, max age cleanup). Should be in the latest push.

[akhater]

@nicoloboschi Updated to use JSONL files as requested. Ready for re-review!

[nicoloboschi]

Two blockers — the O(n²) file I/O during flush and a dead-code guard that silently breaks flushing.

[nicoloboschi]

Bug: O(n² file I/O — remove(item.id) calls readAll() + writeAll() on every iteration, so flushing 50 items means 50 full file reads and 50 full file rewrites.

Collect the successfully-flushed IDs into an array, then do a single bulk removal after the loop:

const flushedIds: string[] = [];
for (const item of items) {
  // ... send ...
  flushedIds.push(item.id);
}
if (flushedIds.length > 0) retainQueue.removeMany(flushedIds);

Same concern applies to size() (called on every successful retain and on the timer) — it parses the entire file each time. Worth caching the count in memory and updating it on enqueue/remove.

[akhater]

Fixed — flush now collects flushed IDs and calls removeMany() for a single file rewrite at the end. Also cached the item count in memory so size() is O(1) — updated on every enqueue(), writeAll(), and removeMany(). @nicoloboschi

[nicoloboschi]

Bug: clientGlobal is read but never used. This checks (global as any).__hindsightClient and breaks out of the loop if it is falsy, but the variable is never referenced again — the code below uses clientsByBankId / clientOptions instead.

This means the flush silently does nothing whenever __hindsightClient happens to be unset, even if valid per-bank clients exist. Either:

• Remove this check entirely (it guards nothing), or
• Replace it with a check on what is actually needed (if (!clientOptions) break;)

[akhater]

Good catch — removed the clientGlobal check entirely and replaced it with if (!clientOptions) return which guards what's actually needed. Moved it before cleanup() too since there's no point expiring items if we can't flush anyway. @nicoloboschi

[nicoloboschi]

can you resolve conflicts?

[akhater]

@nicoloboschi Conflicts resolved — ready to merge!