fix(long-term-memory): 1.4.11 — reserve prompt overhead and refill dropped memories

[Promansis]

Linked issue

Closes #1252

Why this change

• Long-Term Memory measured only raw chunk text against the recall budget, then assembled the prompt with framing, preamble, labels and escaping on top. The assembled prompt therefore exceeded the limit, and the serializer dropped its tail without reconsidering the smaller chunks it had skipped earlier, so a high-scoring memory could be dropped while a chunk that fit was left out.
• Review of the fix (repaired before publication) added two cases: retrieval estimated cost from raw legacy chunk text while the serializer renders the label-stripped bullet form, so the reserved overhead could reject a chunk the serializer would have fit; and an empty recall caused by the reserved budget was recorded as no_matches, writing a zero-match injection receipt instead of a prompt-budget skip.

What changed

• prompt.ts: extracted renderLongTermMemoryPrompt, added estimateLongTermMemoryPromptOverhead and formatLongTermMemoryPromptBullet, and rewrote serializeLongTermMemoryPrompt to re-fit each candidate against the rendered prompt and skip an overflowing chunk instead of popping the tail.
• generation-injection.ts: reserves the fixed prompt overhead in the retrieval budget (guarding the case where the overhead alone fills it), requests the prompt-normalized token estimate, and records skipped/prompt_budget when the reserved budget rejected every candidate rather than writing a zero-match receipt.
• budget.ts / retrieval.ts: optional prompt-normalized estimate plus a debug-independent budgetExhausted signal; defaults preserve search and reconciliation callers.
• tests/long-term-memory-runtime.regression.ts: a/b/c refill case, legacy summary: chunk case, and a budget-exhausted receipt-preservation case.
• Rebuilt long-term-memory 1.4.11: manifest, server.mjs, artifact ZIP and catalog lane entries; changelog entry added.

Package and security impact

• Affected package IDs: long-term-memory
• Engine compatibility impact: none (min 2.4.1 / maxExclusive 4.0.0 unchanged; no capability API change)
• New or changed permissions/entrypoints: none
• Restart, storage, update, or uninstall impact: none (recall selection and prompt assembly only; no storage or lifecycle change)

Validation

• node scripts/validate-catalog.mjs passes locally
• git diff --check passes locally
• Rebuilt every affected manifest, payload, artifact, and catalog entry
• Installed or updated the affected package through Marinara Engine
• Checked supported modes, restart behavior, and uninstall cleanup
• Read and followed CONTRIBUTING.md

Manual verification notes

On 8383abe57f70eca2a0da875bbffb5ba16f2282d5 (pushed SHA), with MARINARA_AGENTS_ROOT and MARINARA_ENGINE_ROOT set:

• test-fast.sh (Prettier, ESLint, git diff --check): exit 0.
• npm run typecheck:packages: pass ("long-term-memory: no syntax errors, undefined names or unresolved modules").
• test-ltm.sh runtime, test-ltm.sh routes, test-ltm.sh debug-log: pass; runtime includes the new refill, legacy summary: and budget-exhausted cases.
• test-ltm.sh installation: pass ("Long-Term Memory 1.4.11 installation: install, offline restart, backup inclusion, uninstall, reinstall, and durable-byte preservation ok") against the exact committed ZIP.
• node scripts/test-catalog-lanes.mjs, node scripts/validate-package-locales.mjs, node scripts/validate-catalog.mjs, node scripts/tests/catalog-release-notes.regression.mjs: pass.
• Publish proof: repository and independent Engine checkout inputs captured before and after the checks; assertPublishProof verified unchanged on final HEAD immediately before push.
• Not performed: manual install/update through the Engine UI, and manual mode/restart/uninstall click-through beyond the installation regression.

Documentation impact

• No documentation changes needed — package README, architecture and UI docs describe the recall flow generically and remain accurate; no catalog membership, compatibility, setup or user-visible workflow changed.
• Updated this README catalog and package guidance
• Updated linked Marinara Engine documentation

UI evidence (if applicable)

None — server-side recall selection and prompt assembly change; no client UI surface.

Summary by CodeRabbit

• Bug Fixes
  • Long-Term Memory now accounts for fixed prompt overhead when selecting recalled information. If a chunk exceeds the available token budget, it is skipped so later, smaller chunks can still be included.
  • When no chunks fit, the system records a prompt-budget skip rather than treating the result as a zero-match recall. Existing injection information is preserved.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: Pasta-Devs/Marinara-Agents/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 0777e44f-7e5f-4cc5-aef9-9c34c8fb859d

📥 Commits

Reviewing files that changed from the base of the PR and between f45fc16 and 8383abe.

⛔ Files ignored due to path filters (2)

• artifacts/long-term-memory-1.4.11.zip is excluded by !**/*.zip, !artifacts/**
• packages/long-term-memory/server.mjs is excluded by !packages/**/server.mjs

📒 Files selected for processing (14)

• catalog/catalog.json
• catalog/notes.json
• catalog/v2/catalog.json
• catalog/v2/notes.json
• catalog/v3/catalog.json
• catalog/v3/notes.json
• packages/long-term-memory/CHANGELOG.md
• packages/long-term-memory/manifest.json
• packages/long-term-memory/src/engine/packages/server/src/services/long-term-memory/budget.ts
• packages/long-term-memory/src/engine/packages/server/src/services/long-term-memory/generation-injection.ts
• packages/long-term-memory/src/engine/packages/server/src/services/long-term-memory/prompt.ts
• packages/long-term-memory/src/engine/packages/server/src/services/long-term-memory/retrieval.ts
• scripts/build-feature-packages.mjs
• tests/long-term-memory-runtime.regression.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Long-Term Memory 1.4.11 adjusts prompt and retrieval budgeting. The serializer considers later chunks when a candidate does not fit. Generation injection reserves estimated prompt overhead, and package metadata and release notes are updated.

Changes

Recall budget and release

Layer / File(s)	Summary
Rendered-prompt chunk fitting packages/long-term-memory/src/engine/packages/server/src/services/long-term-memory/prompt.ts, tests/long-term-memory-runtime.regression.ts	The serializer tests each candidate against the rendered prompt estimate. It removes a candidate that exceeds the limit and continues with later candidates. Regression coverage checks that a later fitting chunk is retained.
Retrieval budget and injection packages/long-term-memory/src/engine/packages/server/src/services/long-term-memory/budget.ts, .../retrieval.ts, .../generation-injection.ts, tests/long-term-memory-runtime.regression.ts	Retrieval supports prompt-normalized estimates and reports budget exhaustion. Generation injection reserves estimated prompt overhead and records a prompt_budget skip when no chunks fit because of the budget. Tests cover the adjusted budget, normalized text, and preservation of the prior injection receipt.
Version 1.4.11 package and catalog metadata packages/long-term-memory/manifest.json, packages/long-term-memory/CHANGELOG.md, scripts/build-feature-packages.mjs, catalog/catalog.json, catalog/notes.json, catalog/v2/*, catalog/v3/*	The package version, artifact checksums and sizes, and release notes are updated for version 1.4.11. The catalog notes remove the 1.3.31 entry.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant prepareGenerationLongTermMemory
  participant prompt
  participant retrieveLongTermMemory
  participant applyLtmBudget
  prepareGenerationLongTermMemory->>prompt: Estimate fixed prompt overhead
  prepareGenerationLongTermMemory->>retrieveLongTermMemory: Pass adjusted budget and normalized estimate option
  retrieveLongTermMemory->>applyLtmBudget: Apply budget to retrieval candidates
  applyLtmBudget-->>retrieveLongTermMemory: Return selected chunks and budget exhaustion status
  retrieveLongTermMemory-->>prepareGenerationLongTermMemory: Return retrieval result
  prepareGenerationLongTermMemory->>prompt: Serialize chunks using configured budget
  prompt-->>prepareGenerationLongTermMemory: Return rendered prompt or null

Loading

Merge Risk: ⚪ Minimal · up to 8383a

The recall-budget change is ready to merge after normal package and catalog validation.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	Issue #1252 requires reserving prompt overhead and retrying skipped chunks. prompt.ts now checks each candidate against the rendered prompt and continues after an oversized candidate, with regressio…	When estimated overhead equals or exceeds the configured budget, give retrieval no content budget and report budget exhaustion when it rejects candidates. Add a regression case that confirms this path does not produce a zero-match receipt.
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 6 files. (8 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the Long-Term Memory fix: reserve prompt overhead and refill dropped memories. It is specific and concise enough to scan in history.
Description check	✅ Passed	The description covers the required sections, links issue #1252, explains the change and package impact, and gives detailed validation notes, including checks that were not performed. The validation c…
Out of Scope Changes check	✅ Passed	The source changes in budget.ts, prompt.ts, retrieval.ts, and generation-injection.ts, plus their regression tests and the 1.4.11 package and catalog updates, support issue #1252. The summarie…

Full details: Linked Issues check

Explanation

Issue #1252 requires reserving prompt overhead and retrying skipped chunks. prompt.ts now checks each candidate against the rendered prompt and continues after an oversized candidate, with regression coverage for refill. However, the change summary says generation-injection.ts subtracts overhead only when the configured budget exceeds it, and otherwise uses the unadjusted budget. In that case retrieval can accept a chunk that the serializer rejects because framing alone consumes the budget. The summary does not establish that this path records a prompt_budget skip or avoids a false no-match receipt.

Full details: Docstring Coverage

Explanation

Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 6 files. (8 skipped: 8 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Some tools did not complete. Review the errors below.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

packages/long-term-memory/src/engine/packages/server/src/services/long-term-memory/budget.ts

typescript-eslint does not support TS 7.0.
Please see https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/#running-side-by-side-with-typescript-6.0 to run typescript-eslint using the TS 6 API.
See also typescript-eslint/typescript-eslint#10940 for tracking typescript-eslint's support for TS >=7.1

Oops! Something went wrong! :(

ESLint: 10.11.0

Error: typescript-eslint does not support TS 7.0.
at Object. (/.eslint-tmp/node_modules/typescript-eslint/dist/index.js:52:11)
at Module._compile (node:internal/modules/cjs/loader:1830:14)
at Object..js (node:internal/modules/cjs/loader:1961:10)
at Module.load (node:internal/modules/cjs/loader:1553:32)
at Module._load (node:internal/modules/cjs/loader:1355:12)
at wrapModuleLoad (node:internal/modules/cjs/loader:255:19)
at loadCJSModuleWithModuleLoad (node:internal/modules/esm/translators:326:3)
at ModuleWrap. (node:internal/modules/esm/translators:231:7)
at ModuleJob.run (node:internal/modules/esm/module_job:437:25)
at async node:internal/modules/esm/loader:639:26

packages/long-term-memory/src/engine/packages/server/src/services/long-term-memory/generation-injection.ts

ESLint skipped: the matched ESLint configuration already failed (config-incompatibility).

packages/long-term-memory/src/engine/packages/server/src/services/long-term-memory/prompt.ts

ESLint skipped: the matched ESLint configuration already failed (config-incompatibility).

• 3 others

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}