feat(context): add limit + compact query params to GET /context

[todie]

Stacked on top of #1. Review #1 first — the merge base for this PR is optimize/session-start-tokens, not main.

Summary

PR #1 worked around the ~8 KB /context payload client-side with awk. This PR moves the knobs into the server, so the rendering choice lives next to the data and works correctly for non-shell clients too.

New query parameters on GET /context:

param	effect
limit=N	Cap the observations section at N bullets. Zero or absent falls back to MaxContextResults (20). Sessions (5) and prompts (10) are unchanged.
compact=1	Render observation bullets as - [type] **title**, dropping the : <300 chars of body> preview. Parsed with strconv.ParseBool so 1, true, yes etc. all work.

Backward compatibility

• FormatContext(project, scope) stays as a thin wrapper over the new FormatContextWithOptions(project, scope, opts) with a zero-value ContextOptions, so all ~15 existing callers and test fixtures are untouched.
• A GET /context request with no new params produces byte-for-byte identical output to the pre-change binary — verified empirically, see benchmark.

Hook update

plugin/claude-code/scripts/session-start.sh now passes ?limit=${ENGRAM_CONTEXT_LIMIT}&compact=1 to the server. The awk post-processor from #1 stays in place as a belt-and-suspenders fallback for users whose binary is older than their plugin — on a new server it's a near no-op; on an old server it still compacts things client-side.

Tests

• store: new TestFormatContextWithOptions covers:
  • default equivalence with FormatContext
  • Compact: true dropping previews
  • Limit: N capping observations
  • Limit + Compact composition
  • Limit <= 0 falling back to MaxContextResults
• server e2e: existing /context test now also hits ?limit=1&compact=1 and asserts the compact payload is strictly smaller and contains no `: ` segments.
• Full suite: go test ./... → 748 passed in 10 packages.

Benchmark (ctodie project, 200+ observations, loopback)

binary	request	payload	latency
old	/context	7949 B	~1.0 ms
new	/context (default params)	7949 B	~0.9 ms
new	/context?limit=8&compact=1	728 B	~0.8 ms

Byte-for-byte identity on the default-params case confirms backward compat. The -91% on the compact path is the real win.

End-to-end SessionStart hook injection

	payload
original (before #1)	~9800 B
after #1 (shell awk only)	~1900 B (−81%)
after #1 + #2 (server-side)	~1151 B (−88%)

PR #1 alone already solved the token cost for users who can't upgrade their binary; this PR makes the fast path the default and keeps the shell fallback for mixed-version deployments.

Test plan

• go test ./... — 748 passed
• Build engram from this branch, run against real ctodie DB, verify default params return byte-for-byte match with old binary
• Verify ?limit=8&compact=1 returns 728 B on same DB
• End-to-end SessionStart hook: 1151 B output, well-formed, tools list present
• Old binary silently ignores new params and returns full context (shell awk fallback then compacts it) — mixed-version deployment works
• Reviewer to sanity-check on a fresh project

Files changed (5)

• internal/store/store.go — add ContextOptions, FormatContextWithOptions; FormatContext becomes a wrapper
• internal/store/store_test.go — new TestFormatContextWithOptions
• internal/server/server.go — parse limit + compact query params
• internal/server/server_e2e_test.go — extend existing /context test
• plugin/claude-code/scripts/session-start.sh — pass new params; keep awk fallback

🤖 Generated with Claude Code