Repository navigation
Let a plugin require cluster-serialized writes: export getLockScope - #60
Merged
Merged
Conversation
A sink runs only on the node that takes the write, so a plugin whose sink-derived state needs writes to one memory serialized across nodes (summary-tree) could only document lockScope: cluster. getLockScope() reports the running plugin's setting, live, through the cross-app runtime; undefined while none runs in the domain or the running plugin is 0.1.5 or earlier. Bumps the version to 0.2.0. Refs HarperFast/summary-tree#3 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017xoBA8Da4eMNT6TffbkJNd Dispatch-Task: proposal-kriszyp-xr-summary-tree-3-agent-memory-ckewn072js-906c4a
…orrect the docs Routes through foreignRuntime so the version-skew warning applies, warns once when the running plugin predates lockScope, documents that the sink check catches only a downgrade, and guards withdraw in the README example. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017xoBA8Da4eMNT6TffbkJNd Dispatch-Task: proposal-kriszyp-xr-summary-tree-3-agent-memory-ckewn072js-906c4a
…elog 0.2.0 The cluster lock-scope suite now runs memory-consumer beside the plugin, so a distinct copy reads a non-default scope end to end. Drops the unused LockScope type re-export. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017xoBA8Da4eMNT6TffbkJNd Dispatch-Task: proposal-kriszyp-xr-summary-tree-3-agent-memory-ckewn072js-906c4a
…; warn an unscoped copy Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017xoBA8Da4eMNT6TffbkJNd Dispatch-Task: proposal-kriszyp-xr-summary-tree-3-agent-memory-ckewn072js-906c4a
… correct the recovery advice Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017xoBA8Da4eMNT6TffbkJNd Dispatch-Task: proposal-kriszyp-xr-summary-tree-3-agent-memory-ckewn072js-906c4a
…eparate copies Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017xoBA8Da4eMNT6TffbkJNd Dispatch-Task: proposal-kriszyp-xr-summary-tree-3-agent-memory-ckewn072js-906c4a
kriszyp
marked this pull request as ready for review
November 20, 2026 15:19
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
⊙ Problem
Sinks run only on the node that takes the write. At the default
lockScope: node, two nodes can rescope one memory at once, and summary-tree can keep serving its text in a partition it left. summary-tree's README requireslockScope: clusterbut cannot check it: agent-memory exports no way to read the setting (HarperFast/summary-tree#3).💡 Solution
getLockScope()returns the running plugin's'node'or'cluster', read live, orundefinedwhile none runs (or it is 0.1.5 or earlier).cluster; the README shows how.cluster, lock recovery after a crash can let two writes commit.🤔 Ship as 0.2.0, with the dated changelog heading?
The task asked for a minor bump, so merging this cuts 0.2.0, including other PRs' Unreleased entries. summary-tree's peer range
>=0.1.5 <0.2.0rejects 0.2.0, so it needs a release that raises its floor to usegetLockScope. An additive 0.1.6 would avoid that.🤔 Keep the
LockScopetype export?It is the getter's return type, so TypeScript callers can name it. No caller imports the public type by name, and one review round asked to drop it. Kept.
⚖️ Alternatives
Rejected: replicated sink calls, Harper's record-lock flag, a registration option
node, replication keeps the last write, so sinks would also see writes that lose. The race needs one order, not every write.replication.recordLocks: having record locks on does not mean agent-memory takes them.lockScopedefaults tonode, and the harper-eye deployment runs that way.requires: 'cluster'option onregisterMemorySink: a running 0.1.5 plugin would ignore it.🤔 The README's in-sink check throws, aborting the write
A sink that throws aborts every memory write while the scope is wrong, which fails closed. A sink could instead skip the call and mark its derived state stale. The README warns against using only the sink check across apps.
🔧 Changes
src/index.ts,src/runtime.ts:getLockScopeand the optionalMemoryRuntime.lockScope()member, answered by the running plugin's own setting.runningLockScopereads only the published runtime, never the calling copy's settings, which a deploy-validation load also applies. It warns once beside a runtime withoutlockScope, or from a copy loaded without its app scope beside a running plugin. Look hardest here: no local fallback is the invariant.README.md: new section "Depending on cluster-wide write ordering", with the startup and in-sink checks and their limits. The in-sink check reads the current setting, not the lock the write took. That gap is filed as #59.DESIGN.md:getLockScopecontract under Extension points; the runtime gainslockScope, with no local fallback.CHANGELOG.md,package.json,package-lock.json,src/version.ts.✅ Verification
Unit 526, integration 83, summary-tree 14/14 against this build; one claim not testable here
npm test: 526 pass. New tests cover each configured value read by a plugin registering after agent-memory, reloads (valid and rejected), no plugin yet, deploy validation, a runtime withoutlockScope, and the unscoped-copy warning on a read, tested on its own copy so the existing registration-warning test still proves its case (test/cross-copy.test.js).npm run test:integration: 83 pass.noderefuses to start, and agent-memory keeps serving. The new fixture app lists agent-memory, then a guard module (config, package) that throws unless the scope iscluster.cluster, the component starts, and a copy in another app readscluster. The cluster fixture now loads its module after the plugin and runs the same guard; memory-consumer's probe returns itsgetLockScope().main: integration suite 14/14 against this packed build, installed with--legacy-peer-deps(peer range above).Refs HarperFast/summary-tree#3
🤖 Generated by Claude Opus 5.5 (Anthropic); posted via @kriszyp.
Related PRs: none found
Complexity: medium
🤖 Generated with Claude Code
https://claude.ai/code/session_017xoBA8Da4eMNT6TffbkJNd
Deferred findings
d4c0efe112b106d7minor concurrency —README.md— sink check reads current lockScope, not the scope the write locked with — filed A sink's lockScope check reads the current setting, not the scope its write locked with #59deed755587e96549nit maintainability —src/index.ts— standalone LockScope type export has no named consumer — NOT FILEDOrigin — the dispatch brief this PR was written from
Let agent-memory sinks rely on cluster lock scope: export lockScope, or call sinks for replicated writes
Dispatch: task
proposal-kriszyp-xr-summary-tree-3-agent-memory-ckewn072js-906c4a· queued by unknown · ran by claude/opus/high · worker kzyp-xps-1Review-Coverage: authored=claude; ran=cursor-composer,codex,gemini,cursor-grok; late=cursor-grok:adjudicated; adjudicated=domain; declined=muse; rounds=6; full=2 @ 5408840
Review-Attention: read ~3m (decisions: sink-fail-closed, current-setting-vs-lock-taken, do-less-alternative, release-in-feature-pr) @ 5408840