Repository navigation
Let another plugin scan memories and add bootstrap sections and search annotations - #45
Merged
Merged
Conversation
…h annotations scanMemories() walks stored memory rows in createdAt, id order for trusted in-process builders, paged and resumable. registerBootstrapSection() adds a section to GET /Memory/bootstrap after pinned and needsReview, within the budget they left, as id-less memories entries clients frame as stored data. registerSearchAnnotator() attaches per-hit data to q searches (REST and MCP recall) without being able to change the hits. A throwing contributor is logged and left out. All three reach the running plugin from another app through the per-worker runtime registry. Refs #36. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Dispatch-Task: agent-memory-summary-extension-points
Register a frozen copy of each section and annotator, so the name checked at registration is the one dispatch uses. Validate rendered items with Array.from, so a sparse array is caught inside the section's own boundary. Copy the scan cursor's Date before yielding the page. Skip the annotation await entirely when nothing is registered. Warn about an older running plugin also when the copy first calls it, once per runtime. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Dispatch-Task: agent-memory-summary-extension-points
…r annotators Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Dispatch-Task: agent-memory-summary-extension-points
…older plugin publishing late Bootstrap with no registered section keeps one four-way Promise.all. A section or annotator registered before any plugin published makes the domain's runtime an accessor, so an older plugin's plain publish runs the same old-runtime check. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Dispatch-Task: agent-memory-summary-extension-points
…oads from escaping Promise.all The running plugin skips an annotator whose name is a hit field in its version, or a section named like a built-in, since a copy of another version validated the name against its own lists. The recent and relevant loads are async, so a synchronous query throw rejects instead of leaving the other loads' rejections unobserved. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Dispatch-Task: agent-memory-summary-extension-points
Annotators get a frozen copy of the hit list holding the result objects, so they still cannot add, drop or reorder hits, but agent-memory no longer deep-clones the hits, JSON-copies annotation values, reads Maps through Map.prototype, checks for sparse item arrays, or rechecks contributor names in the running plugin. Failures (a throw or a rejection) are still contained and logged. The recent and relevant bootstrap loads return to the shape origin/main has. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Dispatch-Task: agent-memory-summary-extension-points
…her bootstrap load's rejection Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Dispatch-Task: agent-memory-summary-extension-points
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Dispatch-Task: agent-memory-summary-extension-points
kriszyp
marked this pull request as ready for review
November 13, 2026 04:50
This was referenced Nov 13, 2026
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
A separate summary-tree plugin (#36) needs to read every memory and add topic summaries to bootstrap and to search hits. Today nothing outside agent-memory's guarded routes may read the
Memorytable, and no other plugin can add to those responses.💡 Solution
Three exports let another app reach the running plugin, like
registerMemorySink:scanMemories()walks stored memories oldest first, resumable after any row. Trusted plugin code only; no route reaches it.registerBootstrapSection()adds a bootstrap section afterpinnedandneedsReview, within the budget left. Items arrive asmemoriesentries without anid, so the Claude Code plugin shows them unchanged.registerSearchAnnotator()addshit[name]toqsearches (REST, MCPrecall) without changing which hits return or their order.A throwing contributor is logged and left out.
⚖️ Alternatives
🤔 Hooks inside agent-memory, not routes wrapped by the plugin
The planning review asked whether the plugin could wrap agent-memory's routes at the same URL instead. Ruled out: the package exports no route class,
configure()re-mounts routes whenurlPathchanges, and handlers return serialized responses. Each of the three surfaces would also redo budget packing and failure handling.🤔 Contributors are trusted, like sinks
agent-memory catches a contributor's throw or rejection and checks that section items are strings. It does not guard against other malformed values, or stop contributors mutating the hits they are handed. That follows the brief's trust level and a steer from the queueing session. Two consequences are tracked in #40.
Other options
{ text }: the Claude client skips any record that does not fit its own framed budget. A single block sized to the remaining budget is therefore dropped whole whenever a pinned entry comes before it, while items in priority order lose only their tail. The companion plugin is also briefed with both forms.^5.3.1peer range.🔧 Changes
Product and architecture tour: where contributed output enters bootstrap and search (one diagram)
Product and architecture tour
Bootstrap sections
What does a session see at startup once a summary plugin is installed?
pinned,needsReview,recent,relevant: memories only.needsReviewandrecent, inside the same budget.One budget, packed in order
Sections render after pinned and needsReview are packed. Each gets the remaining budget while recent and relevant keep loading.
flowchart LR P[pinned] --> N[needsReview] --> S[sections] --> R[recent] --> Q[relevant]Search annotations
What does a search hit carry once an annotator is registered?
Example: a hit with its topic
A summary plugin registers an annotator named
summariesthat returns a Map from hit id to the topic nodes holding that memory.Outcome:
GET /Memory/?q=deployreturns each mapped hit with asummariesfield. The hits, their order and their other fields are unchanged.Reading every memory
How does a derived store build itself and catch up?
Bootstrap
origin/main's single four-wayPromise.allwhen no section is registered. With sections, they render after pinned and needsReview pack while recent and relevant still load. Each item that does not fit is skipped, never truncated.charsis measured by agent-memory, never read from the contributor (a change from the brief).bootstrapItemsaccepts{ text }or an array of{ title?, content }.renderBootstrapSectionsgives each section one try/catch and a log line at most once a minute.watch=true, only memory ids are watched, and the Claude client neither watches nor caches contributed entries (tested end to end through its hooks).🤔 Sections go before
recentThe brief says "after pinned and needsReview, before relevant" and does not mention
recent.recentholds up to 50 of the caller's own memories, enough to fill the Claude client's 4,000-character budget, so a section placed after it would rarely show.Search
runAnnotatorshands every annotator one frozen copy of the hit list, then merges by position in agent-memory's own list. Called from REST and MCPrecall, only whenqis set. With nothing registered, no promise is awaited.score(registerchecks this, and stores a frozen copy of what was registered).🤔 Annotators skip listings and bootstrap's relevant search
The
order=createdlisting feedscopy-memories, whose import rejects unknown fields. Bootstrap has its own extension point.Scan and across apps
enforceExecutionOrder, reusing?order=created's tie-break. It selects the view's fields plusembeddingandembeddingModel, and copies the cursor'sDatebefore the consumer sees the row. DESIGN states that it is a walk, not a snapshot or a change feed.MemoryRuntime.scanMemoriesand the domain lists are optional members, so domains and runtimes from 0.1.4 still work.🤔 Warning beside a 0.1.4 plugin
A 0.1.4 plugin never reads sections or annotators.
warnIfOldRuntimewarns once per runtime. When the registration comes first,noteExtensionRegisteredturns the domain'sruntimeinto an accessor, because 0.1.4 publishes with a plain assignment. Reads and writes behave as before.Docs
DESIGN.md: the extension points for the scan, sections and annotators; who authorizes contributed output; the trust rule; across apps; the data-model exception; bootstrap order and search.README.mdhas usage and permissions.CHANGELOG.mdhas[Unreleased]entries; the version bump and release are left to the owner.CLAUDE.mdnames the reader exception.✅ Verification
test/extensions.test.js(new) covers resuming in a same-timestamp group across pages, placement and budget, the Claude client path, hit order, failing annotators, a Map from another realm, a closing database and the 0.1.4 warning. Cross-copy tests cover a second copy's section, annotator and scan, registered before and after the plugin loads.23dc59d. New cross-app tests run under both thevm-current-contextandvmloaders, through the consumer fixture.Performance: no extra work when nothing is registered, beyond one registry length check.
Framing-Verdict: option-set-too-narrow — resolved by overruling the two missing alternatives with the facts above.
Refs #36
🤖 Generated by Claude Code (Claude Opus 5.5); posted via @kriszyp.
Related PRs: #41 overlaps (merged; this extends its runtime registry and the same DESIGN.md section)
Complexity: complicated
Deferred findings
8adc8f46716c1c03minor correctness —src/extensions.ts— running plugin no longer rechecks reserved hit fields and section names at dispatch across versions — NOT FILED45ab778fcd9fd78bminor reliability —src/extensions.ts— sparse render array escapes validation and fails bootstrap — NOT FILEDOrigin — the dispatch brief this PR was written from
Add the agent-memory extension points a separately packaged summary-tree plugin needs (issue #36), so that plugin can build topic summaries over memories and serve them in bootstrap and beside search hits without reading the Memory table directly. Three additions, all exported from the package index and reachable across apps through the existing per-worker runtime registry (src/runtime.ts domain), with the same rules as registerMemorySink: (1) scanMemories(): a read-only async iterable over Memory rows for trusted in-process derived builders (initial build and catch-up after restart); (2) registerBootstrapSection(section): lets another plugin contribute a named section to GET /Memory/bootstrap (and the MCP equivalent if bootstrap is exposed there), placed after
pinnedandneedsReviewand beforerelevant, rendered per caller with the resolved principal and within the caller's character budget; (3) registerSearchAnnotator(annotator): lets another plugin attach per-hit data to search results (GET /Memory/?q= and MCP recall), given the resolved principal and the hits. Update DESIGN.md (Extension points, Search and bootstrap) in the same PR. A companion task (summary-tree-agent-memory-plugin, repo HarperFast/summary-tree) builds the consumer against this API; keep the contract below unless the plan finds a concrete problem, and if you change it say so in the PR body.Acceptance
Unit tests: scanMemories yields active/unexpired rows by default, every row with includeInactive, resumes from
afterwithout skipping or repeating rows that share a createdAt; a registered bootstrap section appears in the right position, respects the budget, and a throwing section is omitted without failing bootstrap; a search annotator's data appears per hit under its name, cannot change hit set or order, and a throwing annotator is skipped. A cross-app test (same pattern as the existing cross-copy runtime tests) shows a second copy of the package registering a section and an annotator that the running plugin uses. DESIGN.md updated. Existing tests green on Node 22 and 24. Do not touch the Claude Code plugin client or the release.Dispatch: task
agent-memory-summary-extension-points· queued by kris-session · ran by claude/opus/xhigh · worker kzyp-xps-1Ready-For-Promotion: 23dc59d urgency=normal late=none
Review-Coverage: authored=claude; ran=codex,cursor-composer,gemini; adjudicated=domain; declined=cursor-grok,muse; rounds=7; full=1 @ 23dc59d
Review-Attention: read ~7m (decisions: do-less-alternative, requirement-shift, load-order-containment, trusted-contributors, contributor-owns-authorization, registering-copy-name-check, runtime-accessor, perf-cost) @ 23dc59d