dd5a2211c9
* test(#1964): add failing-first semantic-recall contract tests Epic #1957 Phase 3C (final). Source-text-is-the-product contract tests: semantic recall via MemPalace (top-k meaning-similar prior resolutions, catches same-root-cause/different-wording cases), indexing resolved sessions at archive, graceful degradation to keyword matching when MemPalace is absent, knowledge-base.md stays the durable plain-text source of truth, agent Phase 0 / Matching Logic is semantic-first (the stale 'keyword overlap, not semantic similarity' claim must go), and no new embedding/vector infra (reuse MemPalace). Failing-first: reference, the Matching Logic reframe, the Phase 0 consolidation, and the archive indexing step do not yet exist. * feat(#1964): semantic knowledge-base recall via MemPalace (keyword fallback) Epic #1957 Phase 3C (FINAL). Replaces keyword-overlap matching with semantic recall: at Phase 0 the debugger queries MemPalace with the current symptoms and surfaces the top-k meaning-similar prior resolutions, catching the same-root-cause/different-wording cases keyword overlap missed (the self-noted 'keyword overlap, not semantic similarity' limitation). Resolved sessions are indexed into MemPalace at archive (symptoms + root_cause(s) + fix + recurrence guard). knowledge-base.md remains the durable plain-text source of truth; when MemPalace is absent the debugger falls back to keyword-overlap matching (logged, never a silent skip). No new embedding/vector infrastructure — MemPalace is reused. Size-neutral agent edits: the Matching Logic section reframed (keyword-only -> semantic-first + keyword-fallback + @-include); Phase 0's three keyword bullets consolidated into one semantic-first bullet; one MemPalace-indexing step added at archive. Agent at 57222 B (122 B headroom — final phase). Full rules in gsd-core/references/debugger-semantic-recall.md. INVENTORY + manifest + agent-size baseline + install-parity goldens + AGENTS.md updated. * fix(#1964): address orthogonal review (invocation mechanism, index Resolution-not-symptoms + redaction, fallback detail) - HIGH: the 'query MemPalace' instruction was WHAT-level only; the agent has no MCP tools. Added an Invocation section naming the Bash CLI (mempalace search --wing <wing>) + MCP-when-registered + wing resolution (config.mempalace.wing -> project_code -> project dir), matching every other MemPalace integration. Without this the feature silently degraded to keyword matching even when MemPalace was present. - MEDIUM (security x2): index the agent-authored Resolution summary (root_cause + fix + recurrence_guard), NOT raw user-supplied Symptoms — excludes attacker-controlled prose from the cross-session index AND reduces secret/PII leakage. Redact secret-shaped values before indexing. Stated the write order (KB append + commit MUST succeed before indexing). - LOW: restored 'identifiers' + 'case-insensitive' to the keyword fallback; added a test asserting the fallback mechanics survived the Phase 0 consolidation (Error patterns field, 2+ token overlap, identifiers, case-insensitive). * chore(#1964): ratchet agent-size baseline downward (leaner archive bullet shrank gsd-debugger.md 57222->57197) * chore(#1964): backfill changeset pr number (PR #2416)
4.1 KiB
Semantic Knowledge-Base Recall via MemPalace
Loaded by gsd-debugger via @-include from the knowledge_base_protocol
Matching Logic. Replaces keyword-overlap matching with semantic recall so a
prior session that resolved "requests hang under load" surfaces for a new "API
times out when many users connect" — same root cause, no shared keywords.
Why this exists
The knowledge base's self-noted limitation was explicit: "Matching is keyword overlap, not semantic similarity." Keyword overlap only fires on lexical coincidence — the highest-value recalls (same root cause, different wording) are exactly the ones it misses, and its value decays as the corpus grows.
The approach — reuse MemPalace, add no new infrastructure
Layer semantic recall on top of the existing knowledge base by reusing MemPalace (the semantic-memory capability already in this environment) — without adding new embedding or vector infrastructure (Choose Boring / Zawinski: spend no new "innovation token" on a bespoke vector store the debugger would own).
.planning/debug/knowledge-base.md remains the durable plain-text source of
truth; semantic recall is an additive layer over it, not a replacement.
Write — index resolved sessions at archive
At archive_session, after appending the entry to knowledge-base.md (the KB
append + commit MUST succeed first — knowledge-base.md is the durable source
of truth; skip indexing on KB-write failure), index the resolved session into
MemPalace.
Index the agent-authored Resolution summary — root_cause(s) + fix + the
Prevention recurrence_guard — NOT the raw user-supplied Symptoms. The
Resolution is the post-investigation, agent-synthesized signal; indexing it
(rather than raw symptoms) excludes attacker-controlled prose from the
cross-session index and reduces secret/PII leakage. Even so, redact
secret-shaped values (API keys, bearer tokens, JWTs, passwords, credentials)
from the summary before indexing — a bug report's error string can echo a
secret, and MemPalace is a cross-session, cross-project store.
Invocation (the agent has no MCP tools — use the CLI)
The gsd-debugger tools: frontmatter grants no MCP tools, so query and index
via the Bash CLI (the headless/autonomous path): mempalace search "<symptoms>" --wing <wing> to recall, and the matching index command on
archive. If an mempalace_search(query, wing) MCP tool is registered in the
runtime, prefer it. Resolve the wing from config.mempalace.wing → else the
project's project_code → else the project directory name (the same precedence
every other MemPalace integration uses).
Read — query MemPalace at Phase 0
At Phase 0, query MemPalace semantically with the current symptoms and surface the top-k meaning-similar prior resolutions as candidate hypotheses. Each surfaced candidate flows into Evidence exactly as a keyword-match candidate would — a hypothesis to test first, not a confirmed diagnosis.
This catches the same-root-cause / different-wording case: a prior "requests hang under load" resolution surfaces for "API times out when many users connect" even though no keywords overlap.
Graceful degradation — MemPalace absent
When MemPalace is unavailable (not installed, not configured, or the query
errors), fall back to keyword-overlap matching against
knowledge-base.md: extract nouns, error substrings, and identifiers
(function/variable names — often the highest-signal token) from
Symptoms.errors and Symptoms.actual, and scan each entry's Error patterns
field for 2+ token overlap (case-insensitive). The fallback is logged
(Kernighan — never a silent skip), and knowledge-base.md continues to be
written regardless, so no session is lost to a missing palace.
Scope boundary (Zawinski's Law)
An additive recall layer over the existing knowledge base, reusing an existing semantic-memory capability. Not a new command, not a vector database, not an embedding pipeline the debugger owns. Where MemPalace is absent the debugger behaves exactly as it did before this layer — keyword matching against the plain-text knowledge base.