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)
82 lines
4.1 KiB
Markdown
82 lines
4.1 KiB
Markdown
# 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.
|