Skip to content

fix(openclaw): harden thread capture and release surfaces#175

Merged
wey-gu merged 11 commits intomainfrom
dev_0620
Apr 9, 2026
Merged

fix(openclaw): harden thread capture and release surfaces#175
wey-gu merged 11 commits intomainfrom
dev_0620

Conversation

@wey-gu
Copy link
Copy Markdown
Member

@wey-gu wey-gu commented Apr 9, 2026

Summary

This PR prepares the OpenClaw integration for release and tightens the thread-capture contract.

The final shape is broader and more defensible than the original incident report:

  • capture no longer depends on a single runtime path when the Context Engine slot is active
  • one logical OpenClaw chat persists as one Mem thread
  • internal OpenClaw helper sessions no longer pollute Threads
  • stored thread content is cleaned before persistence
  • package metadata, validator rules, docs, and troubleshooting are aligned for npm and ClawHub release

What Changed

Capture reliability

  • keep lifecycle hook capture enabled as a safety net when plugins.slots.contextEngine = "nowledge-mem"
  • make nowledge_mem_status report the real active capture mode (hooks vs context-engine+hooks)
  • make the CLI-backed memory tool path vs API-backed thread-sync path explicit in diagnostics

Thread shape cleanup

  • derive thread identity from stable OpenClaw sessionKey, not transient sessionId
  • exclude internal helper sessions such as temp:* and subagent sessions
  • strip synthetic /new / /reset startup prompts from persisted user content
  • strip OpenClaw directive tags and internal openclaw-control-ui sender envelopes before persistence

Release surfaces

  • align package / manifest / registry versions
  • keep ClawHub-required metadata while omitting unnecessary hard host gates
  • strengthen the OpenClaw release validator and publish runbook
  • clarify user docs for:
    • CE on / CE off behavior
    • remote config via nmem config client ...
    • restart semantics for sessionDigest
    • inspecting synced OpenClaw threads with nmem t list --source openclaw

Validation

Passed locally:

  • node nowledge-mem-openclaw-plugin/scripts/validate-plugin.mjs
  • cd nowledge-mem-openclaw-plugin && npm pack --dry-run
  • cd ../3pp/clawhub && bun clawhub package publish /.../nowledge-mem-openclaw-plugin --dry-run

Manual/local verification completed:

  • OpenClaw plugin loads on the current host
  • nowledge_mem_status reports the expected mode and routing
  • live local plugin copy updated and loaded in OpenClaw

Notes

  • This PR improves reliability and cleanup around the reported thread-sync area, but it does not claim that every observed user report had the same root cause.
  • Later follow-up suggested at least one report likely involved sessionDigest being off after a restart. The docs and postmortem were updated to reflect that nuance.

Note

Medium Risk
Changes core thread-capture/persistence filtering and routing between Context Engine and hook paths; mistakes could cause missed captures or unexpected thread shapes despite idempotent tail-sync safeguards.

Overview
Improves OpenClaw thread auto-sync reliability by keeping lifecycle capture hooks enabled even when the Context Engine slot is active, and by making thread identity prefer the stable sessionKey so CE afterTurn and hook capture append to the same Mem thread.

Tightens what gets persisted: excludes internal/helper sessions (temp:*, subagents), strips synthetic /new//reset startup prompts, removes OpenClaw directive tags, and drops openclaw-control-ui sender metadata wrappers from stored thread messages.

Updates diagnostics and release surfaces: nowledge_mem_status now reports the effective capture mode (hooks vs context-engine+hooks), CE registration fallback details, and the split between CLI-backed memory tools and HTTP API thread sync; bumps the OpenClaw integration/plugin to 0.8.8, removes hard host gates (openclaw.install.minHostVersion/peerDependencies), and updates the validator/runbook/docs to match.

Reviewed by Cursor Bugbot for commit 32005c3. Bugbot is set up for automated code reviews on this repo. Configure here.

Summary by CodeRabbit

  • New Features

    • Improved status reporting showing Context Engine registration state and capture routing (context-engine vs hooks).
  • Bug Fixes

    • Better capture hygiene: excludes internal/helper sessions and transient control metadata; ensures stable thread appends when Context Engine is used.
    • Thread-sync behavior more reliable across session lifecycle.
  • Documentation

    • Expanded troubleshooting, configuration guidance, and clarifications on session/thread capture behavior.
  • Chores

    • Plugin and integration versions bumped to v0.8.8.

wey-gu and others added 4 commits April 9, 2026 11:52
The 0.8.3 release added peerDependencies.openclaw which OpenClaw's
plugin loader may enforce at install or load time, silently preventing
the plugin from registering. This broke thread auto-sync and all other
plugin functionality for affected users.

Retain openclaw.compat.pluginApi metadata for ClawHub validation only.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@wey-gu
Copy link
Copy Markdown
Member Author

wey-gu commented Apr 9, 2026

bugbot run

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Apr 9, 2026

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough
🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 42.86% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (2 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title directly reflects the main focus of the changeset: hardening thread capture reliability, identity derivation, and cleanup across multiple capture paths and release surfaces.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch dev_0620

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@wey-gu
Copy link
Copy Markdown
Member Author

wey-gu commented Apr 9, 2026

@codex review

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5b1af09643

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread nowledge-mem-openclaw-plugin/src/tools/status.js Outdated
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
nowledge-mem-openclaw-plugin/README.md (1)

508-526: Consider simplifying version references for clarity.

This troubleshooting section references multiple version milestones (0.8.x, 0.8.3, 0.7.x → 0.8.0, 0.8.6+, 0.8.5 and earlier), which may confuse users trying to diagnose their current setup. Lines 523-524 explain historical packaging changes that don't directly help users fix the issue.

Consider restructuring to:

  1. Lead with the diagnostic steps (run nowledge_mem_status, check the listed items)
  2. Keep the 0.8.6+ vs 0.8.5-and-earlier distinction since it affects the workaround
  3. Move or remove historical context about 0.8.3 packaging and the 0.7.x → 0.8.0 jump

This would make the troubleshooting more actionable for users on current versions.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@nowledge-mem-openclaw-plugin/README.md` around lines 508 - 526, Rework this
troubleshooting block to lead with the actionable diagnostic steps (run
nowledge_mem_status and verify plugin load, sessionDigest=true, backend
reachability, and active capture path: hook events vs Context Engine afterTurn),
then clearly state only the important version distinction that affects behavior
(keep the 0.8.6+ vs 0.8.5-and-earlier note about capture hooks and the temporary
workaround of removing plugins.slots.contextEngine = "nowledge-mem"), and remove
or relocate the historical packaging/version notes (the 0.8.3 and 0.7.x → 0.8.0
commentary) so the section is concise and focused on immediate debugging and the
practical workaround.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@nowledge-mem-openclaw-plugin/RELEASING.md`:
- Around line 101-102: The docs and validator disagree about
openclaw.install.minHostVersion: scripts/validate-plugin.mjs currently rejects
minHostVersion unconditionally but RELEASING.md says it's conditionally allowed;
update RELEASING.md to match the validator by changing the checklist bullet
about openclaw.install.minHostVersion to state it is not allowed (or must not be
present) unless the validator is changed, and add a brief note referencing
scripts/validate-plugin.mjs so future maintainers know the authoritative check
to update if behavior changes.

---

Nitpick comments:
In `@nowledge-mem-openclaw-plugin/README.md`:
- Around line 508-526: Rework this troubleshooting block to lead with the
actionable diagnostic steps (run nowledge_mem_status and verify plugin load,
sessionDigest=true, backend reachability, and active capture path: hook events
vs Context Engine afterTurn), then clearly state only the important version
distinction that affects behavior (keep the 0.8.6+ vs 0.8.5-and-earlier note
about capture hooks and the temporary workaround of removing
plugins.slots.contextEngine = "nowledge-mem"), and remove or relocate the
historical packaging/version notes (the 0.8.3 and 0.7.x → 0.8.0 commentary) so
the section is concise and focused on immediate debugging and the practical
workaround.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 31b58a5f-8c20-4bfa-9d42-81a1fb652c00

📥 Commits

Reviewing files that changed from the base of the PR and between 259468f and 5b1af09.

⛔ Files ignored due to path filters (1)
  • nowledge-mem-openclaw-plugin/package-lock.json is excluded by !**/package-lock.json
📒 Files selected for processing (10)
  • integrations.json
  • nowledge-mem-openclaw-plugin/CHANGELOG.md
  • nowledge-mem-openclaw-plugin/README.md
  • nowledge-mem-openclaw-plugin/RELEASING.md
  • nowledge-mem-openclaw-plugin/openclaw.plugin.json
  • nowledge-mem-openclaw-plugin/package.json
  • nowledge-mem-openclaw-plugin/scripts/validate-plugin.mjs
  • nowledge-mem-openclaw-plugin/src/hooks/capture.js
  • nowledge-mem-openclaw-plugin/src/index.js
  • nowledge-mem-openclaw-plugin/src/tools/status.js

Comment thread nowledge-mem-openclaw-plugin/RELEASING.md Outdated
Copy link
Copy Markdown

@cursor cursor Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

Reviewed by Cursor Bugbot for commit 5b1af09. Configure here.

@wey-gu wey-gu changed the title fix(openclaw): ce enabled caused syncing failure fix(openclaw): harden thread capture and release surfaces Apr 9, 2026
@wey-gu
Copy link
Copy Markdown
Member Author

wey-gu commented Apr 9, 2026

bugbot run

Copy link
Copy Markdown

@cursor cursor Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 32005c3. Configure here.

Comment thread nowledge-mem-openclaw-plugin/src/hooks/capture.js Outdated
Comment thread nowledge-mem-openclaw-plugin/src/tools/status.js
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
nowledge-mem-openclaw-plugin/src/tools/status.js (1)

105-141: Minor redundancy in ceSlot derivation.

Lines 106-109 duplicate the same slot-normalization logic already performed at lines 72-75 for details.contextEngineSlot. Consider reusing details.contextEngineSlot directly:

-const ceSlot =
-	contextEngineSlot && String(contextEngineSlot).trim()
-		? String(contextEngineSlot).trim()
-		: "legacy";
+const ceSlot = details.contextEngineSlot;

This is a minor nit—the current code is functionally correct.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@nowledge-mem-openclaw-plugin/src/tools/status.js` around lines 105 - 141, The
ceSlot normalization is duplicated—use the already-normalized
details.contextEngineSlot instead of re-trimming contextEngineSlot: set ceSlot =
details.contextEngineSlot (or remove ceSlot and reference
details.contextEngineSlot directly), then compute ceActive =
details.contextEngineSlot === "nowledge-mem" && contextEngineRegistered and
derive captureMode using cfg.sessionDigest and that ceActive value; update all
subsequent checks and log messages that currently reference ceSlot to use
details.contextEngineSlot so the normalization logic is not repeated.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@nowledge-mem-openclaw-plugin/src/tools/status.js`:
- Around line 105-141: The ceSlot normalization is duplicated—use the
already-normalized details.contextEngineSlot instead of re-trimming
contextEngineSlot: set ceSlot = details.contextEngineSlot (or remove ceSlot and
reference details.contextEngineSlot directly), then compute ceActive =
details.contextEngineSlot === "nowledge-mem" && contextEngineRegistered and
derive captureMode using cfg.sessionDigest and that ceActive value; update all
subsequent checks and log messages that currently reference ceSlot to use
details.contextEngineSlot so the normalization logic is not repeated.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: afc97256-7fb1-4826-b012-692989f5c8bd

📥 Commits

Reviewing files that changed from the base of the PR and between 5b1af09 and 32005c3.

⛔ Files ignored due to path filters (1)
  • nowledge-mem-openclaw-plugin/package-lock.json is excluded by !**/package-lock.json
📒 Files selected for processing (12)
  • integrations.json
  • nowledge-mem-openclaw-plugin/CHANGELOG.md
  • nowledge-mem-openclaw-plugin/CLAUDE.md
  • nowledge-mem-openclaw-plugin/README.md
  • nowledge-mem-openclaw-plugin/RELEASING.md
  • nowledge-mem-openclaw-plugin/openclaw.plugin.json
  • nowledge-mem-openclaw-plugin/package.json
  • nowledge-mem-openclaw-plugin/src/ce-state.js
  • nowledge-mem-openclaw-plugin/src/context-engine.js
  • nowledge-mem-openclaw-plugin/src/hooks/capture.js
  • nowledge-mem-openclaw-plugin/src/index.js
  • nowledge-mem-openclaw-plugin/src/tools/status.js
✅ Files skipped from review due to trivial changes (3)
  • nowledge-mem-openclaw-plugin/RELEASING.md
  • nowledge-mem-openclaw-plugin/openclaw.plugin.json
  • nowledge-mem-openclaw-plugin/src/ce-state.js
🚧 Files skipped from review as they are similar to previous changes (4)
  • integrations.json
  • nowledge-mem-openclaw-plugin/src/hooks/capture.js
  • nowledge-mem-openclaw-plugin/package.json
  • nowledge-mem-openclaw-plugin/README.md

@wey-gu wey-gu merged commit 050555a into main Apr 9, 2026
1 check was pending
@wey-gu wey-gu deleted the dev_0620 branch April 9, 2026 08:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant