feat(context): add limit & compact query params to GET /context (byte-compatible)

[todie]

Closes #163 (together with #161).

Stacking note

This PR is stacked on top of #161 (perf: shrink SessionStart hook injection). Review #161 first. Because GitHub doesn't support cross-repo stacked PRs with a fork base, this PR's diff against main currently includes #161's changes. Once #161 lands, I'll rebase and force-push-with-lease, and the diff will shrink to just this PR's additions (5 files, +192/−17).

If you'd prefer, I can open this as a single combined PR instead — just let me know.

Motivation

#161 solved the SessionStart token cost client-side, in the hook, using awk. That's the right shape for users who can't easily rebuild the engram binary, but it has drawbacks as a long-term solution:

1. The knob lives far from the data. The decision about how much context to render should be made in the Go code that knows the data model, not in a shell script that parses the rendered output. Every client (MCP, the CLI, the TUI, external agents) currently has to re-implement its own compaction if it wants short output.
2. Compact truncation is fragile in shell. The awk pass works but has edge cases — byte vs rune truncation, multi-line observation bodies with embedded ### headers that could confuse section tracking, etc. Doing it in Go is about 20 lines and covers all of them correctly.
3. Shell compaction can't undo server-side work. The server still serializes the full 300-char content preview for every observation on every request, even if the client immediately throws it away. It's wasted CPU and memory on the engram daemon.

This PR moves the knobs into the server via two new query parameters on GET /context, while preserving byte-for-byte backward compatibility for existing callers.

Design: byte-compatible interface via zero-value options struct

The core requirement: don't break any existing caller. FormatContext is called from:

• internal/server/server.go (HTTP handler) — 1 site
• internal/mcp/mcp.go (MCP context tool) — 1 site
• cmd/engram/main.go (CLI context command) + test shim storeFormatContext — 2 sites
• internal/store/store_test.go — 8 direct test assertions
• cmd/engram/main_extra_test.go — 2 shim overrides

Changing the signature of FormatContext(project, scope string) would cascade to ~15 call sites, many of them in tests that pin exact output strings. That's too much churn for a feature addition.

The pattern I chose — used elsewhere in this codebase (SearchOptions, AddObservationParams) — is the options struct + wrapper idiom:

type ContextOptions struct {
    Limit   int  // 0 → use MaxContextResults default
    Compact bool // false → legacy behaviour (inline 300-char preview)
}

// FormatContext is a thin wrapper that forwards a zero-value ContextOptions
// to FormatContextWithOptions. This keeps every existing caller unchanged.
func (s *Store) FormatContext(project, scope string) (string, error) {
    return s.FormatContextWithOptions(project, scope, ContextOptions{})
}

func (s *Store) FormatContextWithOptions(project, scope string, opts ContextOptions) (string, error) {
    // ... new implementation honoring opts ...
}

Byte-compatibility proof: a zero-value ContextOptions{} hits the same code paths as the old FormatContext body. The Limit <= 0 branch falls back to s.cfg.MaxContextResults (exactly what the old code used). The !opts.Compact branch renders - [%s] **%s**: %s\n with truncate(obs.Content, 300) (exactly the old format string). No conditionals flip, no new allocations in the default path.

Empirical verification: I built both the old binary (main) and this branch, pointed them at the same 200+ observation database, and compared the responses:

old binary, /context                 → 7949 B, ~1.0 ms
new binary, /context (no params)     → 7949 B, ~0.9 ms   ← byte-for-byte identical
new binary, /context?limit=8&compact=1 → 728 B, ~0.8 ms   ← −91%

The default-params path is a byte-identical drop-in replacement for the old behavior.

Query parameters

param	values	effect
limit	positive integer	Cap the observations section at N bullets. 0, negative, missing, or unparseable → falls back to MaxContextResults (default 20). Sessions (5) and prompts (10) are never affected.
compact	strconv.ParseBool: 1, 0, t, f, T, F, true, false, True, False, TRUE, FALSE	Render observation bullets as - [type] **title** only, dropping the : <300 chars of body> preview. Unknown values silently fall back to false (legacy behavior).

Caveat on compact=: I originally documented "yes" as accepted because I assumed ParseBool followed common-sense rules. It doesn't — only the 12 values above. The second commit in this PR fixes the misleading inline comment. I considered accepting yes/no via a custom parser but decided consistency with the Go stdlib was more valuable than convenience, and silent fallback to false is safer than erroring out on unknown values (bad clients get the old behavior, not a 400).

Hook integration (matched-version fast path + mixed-version fallback)

plugin/claude-code/scripts/session-start.sh is updated to pass ?limit=${ENGRAM_CONTEXT_LIMIT}&compact=1. On a matched-version deployment (new plugin + new binary), the server does the compaction and the awk pass from #161 becomes a near no-op. On a mixed-version deployment (new plugin + old binary), the old binary silently ignores the unknown query params, returns the full response, and the awk fallback from #161 compacts it client-side. Both cases produce a correctly compacted output.

This is the main reason I kept the awk pass in the hook rather than removing it in this PR.

Measurement methodology

• Database: my real working engram.db with 200+ observations across several months (ctodie project), all in personal scope. Mix of session_summary (multi-line markdown), pattern, discovery, decision, manual, bug types.
• Setup: built both binaries from the same git state (old = main, new = this branch), ran each in turn on port 7438 to avoid stepping on the live daemon's port. Hit /context 3 times per variant with curl -w \"time_total=%{time_total}s size=%{size_download}\\n\" to smooth out cold-start jitter.
• Latencies are loopback. Don't read too much into the micro-differences; the real signal is the payload size delta. The "fast" path is ~10% faster mainly because it serializes less data, not because of any algorithmic win.

binary	request	payload	median latency
old (main)	/context?project=ctodie	7949 B	~1.0 ms
new (this PR)	/context?project=ctodie (default params)	7949 B	~0.9 ms
new (this PR)	/context?project=ctodie&limit=8&compact=1	728 B (−91%)	~0.8 ms

End-to-end SessionStart hook injection, real project:

	bytes
original (before #161)	~9800
after #161 alone (shell awk)	~1900 (−81%)
after #161 + this PR (server-side)	~1151 (−88%)

Risk analysis

What could break?

1. Silent semantic drift in FormatContext. Mitigated by TestFormatContextWithOptions asserting defaultCtx == legacyCtx as exact string equality. Any future refactor that touches FormatContextWithOptions without updating this test will flag a drift immediately.
2. Query-param injection. Both params are parsed with strconv.Atoi / strconv.ParseBool before any store interaction. Unparseable values silently fall back to defaults, never reach the store, and never affect the SQL query (the store-level limit passed to RecentObservations is either a validated positive int or the config default).
3. Existing test fixtures breaking. None did. go test ./... → 748 passed → 749 passed (one new test) → 750 passed (one more assertion in the e2e suite). All existing tests untouched.
4. MCP clients expecting the old format. MCP clients go through internal/mcp/mcp.go which still calls FormatContext(project, scope) — i.e. the backward-compat wrapper. Their output is unchanged byte-for-byte.

What's the rollback?

• git revert <merge-commit>. No database migration, no config file format change, no on-disk state change. The new ContextOptions struct and FormatContextWithOptions method disappear with the revert; nothing outside the store package depends on them.

Tests

• New: internal/store/store_test.go::TestFormatContextWithOptions. Covers:
  • ContextOptions{} → byte-equal to FormatContext (backward compat)
  • Compact: true → drops content preview, keeps titles
  • Limit: 2 → exactly 2 observation bullets (using strings.Count)
  • Limit: 3, Compact: true → both knobs compose correctly
  • Limit: 0 → falls back to default (byte-equal to legacy)
• Extended: internal/server/server_e2e_test.go's /context test now also hits ?limit=1&compact=1 and asserts the compact payload is strictly smaller than the default and contains no : <body> segments.
• Full suite: go test ./... → 748 passed in 10 packages (was 747 before the new test; a second e2e assertion brings it to 749 on this branch).

Files changed (this PR's additions only, excluding #161)

internal/server/server.go                   | 25 ++++++--
internal/server/server_e2e_test.go          | 20 ++++++
internal/store/store.go                     | 43 ++++++++++++-
internal/store/store_test.go                | 96 +++++++++++++++++++++++++++++
plugin/claude-code/scripts/session-start.sh | 25 +++++---
5 files changed, 192 insertions(+), 17 deletions(-)

Commits

1. feat(context): add limit + compact query params to GET /context — the main change
2. docs(context): fix compact= param comment — ParseBool rejects 'yes' — drive-by doc fix after I benchmarked the live binary and caught the inaccuracy

Happy to squash if you prefer a single commit.

🤖 Generated with Claude Code

[Alan-TheGentleman]

Review — APPROVED

Excelente PR. Backward compatibility verificada al 100%, bien testeada, y la implementación es idiomática.

Backward Compatibility ✓

• FormatContext(project, scope) sigue existiendo como wrapper de FormatContextWithOptions con zero-value options
• MCP clients siguen llamando FormatContext() directamente — output byte-por-byte idéntico
• GET /context sin query params → flujo idéntico al handler anterior
• El test de defaultCtx == legacyCtx como string equality es un guardrail excelente

Compact mode ✓

• Elimina solo el preview de contenido, mantiene type + título + sesiones + prompts
• Suficiente para que un agente sepa QUÉ existe y haga mem_get_observation on-demand

Edge cases ✓

• limit=0, limit=-1, limit=abc → todos caen al default correctamente
• Double safety net en RecentObservations — redundante pero seguro
• limit + compact combinados → testeado

Observaciones menores (non-blocking)

1. Test e2e de compact: la assertion busca **: como substring global — podría matchear un título de observation. Mejor verificar línea por línea.
2. compact=yes cae silenciosamente a false: strconv.ParseBool no acepta "yes"/"on". El fallback es safe (retorna full context) pero puede confundir.
3. Squash commits antes de merge — el commit 1 es de PR #161.

Fantástico laburo. El patrón de options struct + wrapper es consistente con SearchOptions del mismo codebase. Se puede mergear con confianza.