fix(memory): land verified question/SQL pairs as executable measures and segments

[luca-martial]

Problem

Verified question/SQL pairs ingested through ktx ingest --file were being captured as wiki prose instead of executable measures/segments, so the semantic layer stayed whatever the warehouse scan guessed from column names. Even an explicit "define measures and segments" instruction produced zero SL writes on a corpus full of verified SQL.

Root cause

Three independent issues on the --file memory-agent path:

1. Signal gate. detectCaptureSignals only fires the SL signal from SQL when userMessage.length >= 100. That gate is a reasonable proxy on the chat/research path, but ktx ingest --file sets userMessage to a fixed boilerplate string and carries the artifact in assistantMessage. So SQL-heavy files never force-loaded the SL capture skill and defaulted to wiki capture.
2. Preamble framing. memory_agent_external_ingest.md framed every artifact as a reference doc and routed rules/definitions to the wiki, with no instruction to encode a verified computation as a measure/segment or to revise a scan-guessed source in place. The do_not "don't fabricate" line also read as a brake on encoding a query (a query implies a measure rather than declaring one).
3. Re-run blindness. The SL index shown to the agent on each re-run listed measures and joins but not segments, so repeat passes could not see which existing sources were thin on segments and re-derived non-deterministically.

Changes (one commit each)

• fix(memory): fire SL capture signal for SQL-bearing external ingest — external ingest treats the deliberate submission itself as the substantive signal, so verified SQL fires the SL signal regardless of the boilerplate user message. Research/backfill keep the existing length gate. Adds two regression tests.
• feat(memory): encode verified question/SQL pairs as executable measures and segments — adds a verified_pairs directive (encode the computation, revise sources in place, verified material is authoritative over a conflicting scan guess), points the workflow at sl_capture, and clarifies that deriving a measure from a verified query is derivation from evidence, not fabrication.
• fix(memory): surface segments in the SL index for re-run gap targeting — the index now reports segment counts and names alongside measures, so a second pass targets gaps instead of re-deriving blindly; a source is only flagged for enrichment when measures, segments, and joins are all empty.

Verification

• pnpm --filter @kaelio/ktx run type-check — clean
• pnpm --filter @kaelio/ktx exec vitest run test/context/memory/ — 50 passed (incl. 2 new signal tests)
• pnpm run dead-code — clean (Biome + both Knip modes)

Notes

• No new flags or runtime paths; the fix routes through the existing external-ingest preamble and shared signal detector.
• A deterministic upstream projection of verified pairs (sqlglot: aggregation→measure, filter→segment) would make one-pass coverage exhaustive rather than convergent, and is a sensible follow-up, but is out of scope here.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ktx-docs-site	Ready	Preview, Comment	Jun 26, 2026 12:16am

[codecov-commenter]

Codecov Report

❌ Patch coverage is 37.50000% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ges/cli/src/context/memory/memory-agent.service.ts	0.00%	5 Missing ⚠️

📢 Thoughts on this report? Let us know!