cc-os/docs/plans/b3-memsearch-injection-review.md

# B3 — memsearch SessionStart injection cost review

_Reviewed 2026-07-08. memsearch v0.4.6 (installed) / v0.4.11 (also cached, not yet installed). Plugin: `memsearch@memsearch-plugins`._

## What gets injected

`hooks/session-start.sh` (both cached versions, logic unchanged 0.4.6→0.4.11) builds a
`# Recent Memory` block on every SessionStart and returns it as `additionalContext`:

- Finds the daily memory files under `$MEMORY_DIR` (`~/.memsearch/memory/YYYY-MM-DD.md`),
  sorted by filename descending, and takes the **2 most recent**.
- For each of those 2 files, greps lines matching `^(#{2,4} |- )` (headings + bullets) and
  takes the **first 40 matching lines** (`head -40`).
- Concatenates both files' extracts under one `# Recent Memory` heading and returns it.

This is entirely hardcoded (`head -2`, `head -40`) in the shell script — there is no
per-file/per-line/byte cap that's user-configurable.

## Measurements (cc-os project, last ~7 days of session transcripts)

Extracted the `additionalContext` string from every SessionStart hook event whose payload
contained `# Recent Memory`, across `~/.claude/projects/-home-jared-dev-cc-os/*.jsonl`
(61 SessionStart events found in that window — heavy usage during the WS2/WS4 eval loops,
so this sample is skewed toward busy days, not a quiet baseline).

| Stat | chars | approx tokens (÷4) |
|---|---|---|
| min | 5,976 | ~1,494 |
| median | 11,721 | ~2,930 |
| avg | 11,978 | ~2,995 |
| max | 15,407 | ~3,852 |

This roughly confirms the ~13 KB figure already observed. Size scales with how many
`##`/`###`/bullet lines the 2 most recent daily files accumulated that day — on a day with a
lot of sessions/subagent activity (like the recent eval-loop days), each daily file alone can
hit the 40-line cap, so the injection saturates near its structural ceiling
(2 files × 40 lines × ~150–200 chars/line ≈ 12,000–16,000 chars), matching the observed range.

Caveat: this is a per-project sample from one heavy-usage repo (cc-os) over 7 days; other
projects' daily files will differ, and this sampling method (string-matching the raw jsonl,
not a documented API) is the best available without deeper memsearch internals — reasonably
solid since the hook's exact output string was recovered from real transcripts, not estimated.

## Config surface found

Read `skills/memory-config/SKILL.md` (both cached versions) and `hooks/session-start.sh`
directly. Findings:

- The **documented** TOML config surface (`plugins.claude-code.summarize`, `.project_review`,
  `.user_profile`, `.memory_to_skill`, `[llm.providers.*]`, `[prompts]`) controls
  summarization, maintenance artifacts (PROJECT.md/USER.md), skill distillation, and provider
  routing — **none of it touches the SessionStart recall injection**.
- No `[plugins.claude-code.session_start]` or equivalent section exists in the documented
  schema, and none of the constants used by the injection logic (`head -2` file count,
  `head -40` line count, the `^(#{2,4} |- )` grep pattern) appear anywhere in `config.toml`,
  `memsearch config list --resolved/--global/--project`, or the SKILL.md. They are hardcoded
  in `hooks/session-start.sh` itself.
- The only adjacent, real lever is **memory file density**: since the cap is by line count
  (not token count) over headings+bullets, whatever produces terse vs. verbose daily-file
  bullets (the Stop-hook summarizer, governed by `plugins.claude-code.summarize.model`,
  defaults to haiku) indirectly controls how much of the 40-line budget per file is "real
  signal" vs. how many days of content get squeezed out.

## Recommendation

**No first-class cap/trim setting exists in memsearch's config schema for this injection.**
The two concrete options, in preference order:

1. **Workaround, no code change (recommended to try first):** the injection is driven purely
   by memory-file content density, not by any setting. If daily files are noisy (e.g. many
   short low-signal bullets from busy multi-session days, as in the cc-os sample), the
   Stop-hook summarizer producing those bullets is the actual place to add discipline —
   tightening what counts as bullet-worthy would shrink the 40-line/file budget's real size
   without touching the plugin. This is a memsearch summarizer/prompt-quality issue, not a
   session-cost cap.
2. **Direct edit, unsupported (only if (1) is insufficient):** hand-edit the cached
   `hooks/session-start.sh` at
   `~/.claude/plugins/cache/memsearch-plugins/memsearch/<version>/hooks/session-start.sh`,
   lowering `head -2` → `head -1` (halves injection size, roughly ~6–8 KB/day instead of
   ~12–15 KB) and/or `head -40` → a smaller value (e.g. 20). Expected savings: cutting to 1
   file × 20 lines would drop the typical injection from ~11–15 KB (~2,900–3,850 tokens) to
   roughly ~3 KB (~750 tokens), a ~75% reduction. **Caveat:** this is an unmanaged edit to
   plugin-cache source — it will be silently overwritten on the next
   `claude plugin update memsearch` / cache refresh, is not upstream-supported, and isn't a
   "setting" in the config-surface sense the task asked to identify. Treat it as a stopgap,
   not a durable fix; if this repo wants a durable cap, the change belongs upstream in
   `zilliztech/memsearch` (file an issue/PR to add a
   `[plugins.claude-code.session_start]` `max_files` / `max_lines_per_file` config section)
   rather than as a local hack here.

No setting was applied — this is a review/recommendation only per the task.