feat(openclaw): expose Hindsight docs as memory bridge artifacts

[frvade]

Closes #963.

Summary

• register OpenClaw publicArtifacts support in the Hindsight OpenClaw plugin
• fetch Hindsight banks/documents over the existing external HTTP API and materialize them as markdown under memory/hindsight-bridge/
• add one focused test that covers the document export path

Verification

• cd hindsight-integrations/openclaw && npm run build
• cd hindsight-integrations/openclaw && npm test

[nicoloboschi]

Code review notes:

Must fix

• Missing pagination in listHindsightPublicArtifacts (src/index.ts): documents query is hardcoded to ?limit=100&offset=0. Banks with >100 documents will silently drop artifacts. Loop until the API returns fewer than limit items.
• No error isolation in the fetch loop: if a single document GET fails, the whole call throws — and we may already have written a partial set of files to the user's workspace. Wrap per-document fetches in try/catch, log, and continue so one bad doc doesn't nuke the export.

Should fix

• N+1 / sequential I/O: for each bank we list, then for each doc we fetch individually, fully sequentially. Parallelize with a bounded concurrency (e.g. p-limit) per bank — this will be painfully slow on real workspaces.
• kind: 'daily-note' is misleading: these aren't daily notes, they're Hindsight documents. If OpenClaw's bridge requires this literal string, add a comment explaining why; otherwise use a more accurate kind.
• Locally redeclared SDK contract (src/types.ts): MemoryPluginPublicArtifact and MemoryPluginCapability are hand-rolled here instead of imported from the OpenClaw SDK. If OpenClaw changes the shape this plugin drifts silently. Import the real type or add a comment acknowledging the duplication.
• Sync FS inside async function: mkdirSync / writeFileSync block the event loop while materializing many artifacts. Prefer fs/promises.
• Test coverage is thin: one happy-path test (1 bank, 1 doc, default workspace). Missing: pagination boundary, fetch failure, empty bank list, runtime without registerMemoryCapability, multi-workspace (agents.list with multiple entries). For code that writes to the user's filesystem this is under-covered.
• Unrelated comment churn: // Default: true (on) — backward compatible → // Default: true (on), backward compatible is noise, please drop.

Notes

• listArtifacts sounds read-only but materializes markdown files on disk. Mirrors the OpenClaw contract, but worth a one-line comment on the exported function so future readers aren't surprised.
• original_text is written verbatim with no size cap — fine for v1, but flag-worthy for very large documents.

Overall direction looks right and scoped to #963. The two must-fix items (silent 100-doc cap + all-or-nothing error handling during a filesystem-mutating call) will bite real users before tests will — I'd block on those; the rest is polish.

[frvade]

Addressed all review items from #pullrequestreview-4097275838 across three commits (d3f03e7, 2b307b5, 50631cb):

Must fix — both resolved in d3f03e7:

• Pagination: loop until items.length < pageSize, no more 100-doc cap
• Error isolation: failed per-document fetches are logged and skipped

Should fix — resolved in 2b307b5 + 50631cb:

• N+1 sequential I/O → batched with Promise.allSettled, concurrency 8
• kind: 'daily-note' → added inline comment explaining it's the closest OpenClaw bridge kind
• Locally redeclared SDK types → added comment + TODO to replace once OpenClaw ships a types package
• Sync FS → switched to fs/promises (mkdir/writeFile)
• Test coverage → added: pagination boundary, fetch failure + continue, empty bank list, multi-workspace materialization (5 tests total)
• Unrelated comment churn → reverted (em-dash restored)

Notes — resolved in 50631cb:

• Added JSDoc on listHindsightPublicArtifacts clarifying it materializes files despite the "list" name
• Added note that original_text is written with no size cap (acceptable for v1)

Also reverted an accidental package-lock.json drift (local→npm dep resolution) that was unrelated to this feature (2b307b5).

[frvade]

@nicoloboschi — merged the latest main into this branch, conflicts are resolved, and targeted tests pass. Could you take another look when you get a chance? Thanks!

[frvade]

Merged latest main into this branch, resolved the OpenClaw integration conflict, and pushed the updated branch.

@nicoloboschi could you please take another look when you have a moment?