Skip to content

Claude Code plugin: inject all of bootstrap within budget, render section entries and summaryTree topics - #50

Merged
kriszyp merged 10 commits into
mainfrom
fix/claude-plugin-sections-annotations
Nov 14, 2026
Merged

kriszyp merged 10 commits into
mainfrom
fix/claude-plugin-sections-annotations

Conversation

@kriszyp

@kriszyp kriszyp commented Nov 14, 2026 •

Copy link
Copy Markdown
Member
A girl loads a dog's saddlebag with the whole bundle of datefruit crates while her brother tags the first crate

⊙ Problem

The Claude Code plugin renders bootstrap sections and search annotators (0.1.5) badly:

💡 Solution

⚖️ Alternatives

🤔 Fixed overhead estimate, or exact server count?

The plugin sends one overhead computed for stated sizes (64-char id, 32-char author, 64 chars of scopes): 308 against ~200 typical. An entry within ~110 characters of the budget is not packed; larger metadata falls back to the prefix. Exact alternative: the server also counts each entry's id, author and scopes. Tracked in #53.

🤔 Two overhead parameters

A section item frames in ~137 characters, not 308 (no id, author or scopes). One parameter wasted ~170 per item, so sectionItemOverhead exists, defaulting to entryOverhead.

🤔 Sections: budgetChars is now room for one item

Sections get budgetChars net of one item overhead plus itemOverheadChars. A one-item section fits exactly; a multi-item one ignoring itemOverheadChars loses tail items. Unchanged at overhead 0. summary-tree's orientation should adopt it.

🔧 Changes

✅ Verification

Tests

Server: parameter parsing, per-memory charge, per-section-item charge and budgetChars. Plugin: every entry packed at the stated sizes fits; an older server gets an in-order prefix; delimiter escaping, with a whitespace-run timing check that fails before the linear fix. Earlier in this PR: section entries (header, state, cache); ordered prefix vs skip-ahead; offline cache keeps skipping ahead; recall with and without summaryTree, one block per topic, no late block; closing tags, nonces and topic delimiters in summaries escaped; malformed and oversized annotation fields ignored; escaped summaries stay within 400 characters.

Fixes #52

Docs: README and DESIGN.md here; no documentation-site page covers this.

Framing-Verdict: better-alternative-exists (de73c2f4892b) — overruled (owner ruling; that alternative cuts ~40%)

🤖 Generated by Claude Code (Claude Opus 5.5); posted via @kriszyp.

🤖 Generated with Claude Code

Related PRs: #45 independent (merged; added the section and annotator API this extends), 2 others independent
Complexity: medium

Deferred findings

Accepted behavior

Behavior the owner ruled intended, so there is nothing to file.

3 minor or nit
  • 28f58940dd32cf61 nit reliability — claude-plugin/lib/hooks.mjs — Bootstrap tail entries not injected are still watched and renewed — accepted: owner (Kris) ruled it intended, 2026-11-13, dispatch task agent-memory-50-bootstrap-entry-overhead ruling 2a
  • 7f7ad50df32c8e88 nit performance — claude-plugin/lib/format.mjs — Per-call topic overhead: per-hit resolveTopic, extra topic regex pass, DATA_NOTICE escaped twice — accepted: owner (Kris) ruled it intended, 2026-11-13, dispatch task agent-memory-50-bootstrap-entry-overhead ruling 2a
  • b6438665486bf620 nit correctness — claude-plugin/lib/format.mjs — Topic block omitted when tight, including the single-oversized fallback which emits topicId with no block — accepted: owner (Kris) ruled it intended, 2026-11-13, dispatch task agent-memory-50-bootstrap-entry-overhead ruling 2a
Origin — the dispatch brief this PR was written from

Make agent-memory's Claude Code plugin client (claude-plugin/) render the output of bootstrap sections and search annotators correctly. Three parts: (1) render id-less bootstrap section entries without a fake id; (2) make the session-start injection keep what the server packed instead of silently dropping it at the client's character budget; (3) show the summaryTree annotation on recall hits. Open a draft PR.

Acceptance

Unit tests in test/claude-plugin.test.js covering: an id-less orientation section entry renders without id="unknown" and survives state/cache handling; a bootstrap response packed to the budget is fully injected (fails on main, passes after); recall hits with and without summaryTree; the summaryTree text is sanitized (a closing-tag/nonce injection attempt in the summary is escaped). Existing tests pass; npm test green. Draft PR. Follow harper-engineering-guidelines.

Dispatch: task agent-memory-claude-plugin-sections-annotations · queued by kris-session · ran by claude/opus/high · worker kzyp-xps-1

Ready-For-Promotion: 027a1f7 urgency=normal late=folded

Review-Coverage: authored=claude; ran=cursor-composer,gemini,codex,gemini-carbon,cursor-grok; late=gemini-carbon:adjudicated,cursor-grok:adjudicated; adjudicated=domain; declined=muse; rounds=10; full=5 @ 027a1f7

Review-Attention: read ~5m (decisions: client-side-overhead-estimate, two-overhead-params, section-budget-net-of-one-item, do-less-alternative) @ 027a1f7

kriszyp and others added 4 commits November 13, 2026 16:14
…tion entries and summaryTree topics

- Request a bootstrap budget net of the plugin's framing (60% of what the wrapper and banners leave) and render
  an in-order prefix, so a typical response is injected whole instead of losing ~40% of its entries.
- Render id-less bootstrap section entries with only their section attribute.
- Show a recall hit's summaryTree topic as attributes plus one sanitized topic block per injection; escape topic
  delimiters in all bodies.

Dispatch-Task: agent-memory-claude-plugin-sections-annotations
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… the request-share trade-off

Dispatch-Task: agent-memory-claude-plugin-sections-annotations
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ep truncation surrogate-safe

Dispatch-Task: agent-memory-claude-plugin-sections-annotations
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dispatch-Task: agent-memory-claude-plugin-sections-annotations
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
kriszyp and others added 2 commits November 13, 2026 18:28
…ts exact budget

GET /Memory/bootstrap takes optional entryOverhead and sectionItemOverhead
(0..10000, default 0; sectionItemOverhead defaults to entryOverhead), charged
per packed memory and per contributed section item. Sections receive
itemOverheadChars, and budgetChars is the room for one item net of it.

The Claude Code plugin drops the 60% request share: it requests its budget
less wrapper and banners, with overheads computed from its own record format
at stated sizes, so every packed entry is injected in order. The ordered
prefix stays as the fallback for larger entries and older servers.

Fixes #52

Dispatch-Task: agent-memory-50-bootstrap-entry-overhead
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ads; qualify the docs

Dispatch-Task: agent-memory-50-bootstrap-entry-overhead
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
kriszyp and others added 4 commits November 13, 2026 19:00
…ing in the bootstrap fit contract

Dispatch-Task: agent-memory-50-bootstrap-entry-overhead
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…a bare [word

The closed-form memory/topic/agent-memory-data patterns backtracked
quadratically on repeated unclosed openers; the opener-only patterns
neutralize every delimiter on their own.

Dispatch-Task: agent-memory-50-bootstrap-entry-overhead
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Two adjacent \s* around an optional / split a long whitespace run every
possible way; (?:\/\s*)? leaves one way to match.

Dispatch-Task: agent-memory-50-bootstrap-entry-overhead
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dispatch-Task: agent-memory-50-bootstrap-entry-overhead
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kriszyp
kriszyp marked this pull request as ready for review November 14, 2026 14:47
@kriszyp
kriszyp merged commit 3dd894e into main Nov 14, 2026
2 checks passed
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.

Claude plugin bootstrap: reduced request budget drops long pins and erases them from the offline cache

1 participant