feat(#956): add MemPalace memory capability (ADR-857 feature plug-in) (#1201)

* feat(#956): add MemPalace memory capability (ADR-857 feature plug-in)

Adds an opt-in, default-resilient ADR-857 feature capability that wires
MemPalace (local-first memory: MCP server + CLI) into the GSD loop:
deliberate recall before discuss/plan and verbatim + temporal-KG capture
at phase boundaries. Three memory modes (augment default; kg_backend and
replace forward-declared). Master gate mempalace.enabled (default off);
every hook onError:skip, zero gates; absent/disabled MemPalace => loop
unchanged. Transport is rendered-markdown only — MemPalace runs
out-of-process, no third-party code in gsd-core (ADR-857 §7).

Capability: capabilities/mempalace/ (manifest + 2 fragments), skills
commands/gsd/mempalace-{recall,capture}.md, agent
agents/gsd-mempalace-curator.md. Registration: ns-context router,
utility cluster, KNOWN_SKILLS, help full.md, model-catalog, copilot
install list, size baselines; regenerated capability-registry +
inventory manifest. ship:post wired into ship.md (wire-on-demand).

HELD on #1196: this capability also declares hooks at discuss:pre and
discuss:post, which are structurally un-wireable until the host-loop
conformance model covers the discuss phase (discuss-phase.md is not in
HOST_LOOP_FILES). The phase6-capstone-conformance gate therefore fails
on exactly those two orphaned points by design — see #1196. Once #1196
lands, rebase onto next and the gate goes green with no further change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(#956): backfill changeset PR number (#1201)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-06-14 02:09:10 -04:00
committed by GitHub
parent b1e8a74708
commit a375c4b354
29 changed files with 1117 additions and 31 deletions

View File

@@ -0,0 +1,71 @@
---
name: gsd:mempalace-capture
description: "File a phase artifact into MemPalace; mirror decision facts into its temporal KG"
argument-hint: "[CONTEXT.md|PLAN.md|SUMMARY.md]"
allowed-tools:
- Read
- Bash
requires: [config]
---
**STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by the command system. Using the Read tool on this file wastes tokens. Begin executing Step 0 immediately.**
## Step 0 -- Banner
**Before ANY tool calls**, display this banner:
```
GSD > MEMPALACE CAPTURE
```
Then proceed to Step 1.
## Step 1 -- Config Gate
Check whether the MemPalace capability is enabled by reading `.planning/config.json` directly with the Read tool.
1. Read `.planning/config.json` with the Read tool.
2. If the file does not exist, or `config.mempalace` is absent, or `config.mempalace.enabled !== true`, or `config.mempalace.capture_artifacts !== true`: display the disabled message and **STOP**.
3. Otherwise proceed to Step 2.
**Disabled message:**
```
GSD > MEMPALACE CAPTURE
MemPalace capture is disabled (mempalace.enabled / mempalace.capture_artifacts).
Nothing was filed; the loop proceeds normally.
```
This step is `onError: skip` at `discuss:post` / `plan:post` / `verify:post` -- capture never fails a phase.
## Step 2 -- Resolve target
1. **Artifact.** Take the artifact from `$ARGUMENTS`. If absent, infer from the loop point: `discuss:post` → `CONTEXT.md`, `plan:post` → `PLAN.md`, `verify:post` → `SUMMARY.md`.
2. **Room.** Map artifact → room:
- `CONTEXT.md` → `decisions`
- `PLAN.md` → `planning`
- `SUMMARY.md` → `milestones`
(Confirmed problem→fix pairs go to `problems` — see the `capture-problems` fragment used at `execute:wave:post`.)
3. **Wing.** `config.mempalace.wing` if non-empty, else `config.project_code`, else the repo directory name.
4. **Mode / transport.** Read `config.mempalace.memory_mode`. Prefer MCP (`mempalace_*`) when your MemPalace MCP server is registered and your runtime permits those tools; otherwise use the `mempalace` CLI (covered by this skill's `Bash` allow-tool), as in `mempalace-recall`.
## Step 3 -- File verbatim (idempotent)
On any error or timeout, stop and let the phase continue -- capture is best-effort.
1. **Dedup first.** Interactive: `mempalace_check_duplicate` on the artifact's deterministic drawer id. Headless: rely on `mempalace mine`'s content-hash idempotency.
2. **Add the drawer (verbatim).** File the exact artifact text into `room: <room>` of `wing: <wing>` with provenance (`source_file`, phase id). Interactive: `mempalace_add_drawer`. Headless: `mempalace mine <path> --wing <wing> --room <room>`.
3. **Mirror KG facts** when `config.mempalace.mirror_kg` is true: extract decision/delivery facts and `mempalace_kg_add` them with `valid_from` = the phase date (e.g. `(<project>, decided, <decision>)` from CONTEXT; `(<phase>, delivered, <capability>)` from SUMMARY). Only `augment` is currently wired, so these are an *additive* mirror of `.planning/graphs/`. (`kg_backend`/`replace` are forward-declared and behave as `augment` today.)
4. Re-running a phase MUST NOT create duplicate drawers (deterministic ids + `check_duplicate`).
## Step 4 -- Report
Print a one-line summary: `Filed <artifact> → <wing>/<room> (<n> KG facts)` or `MemPalace unavailable — capture skipped`.
## Anti-Patterns
1. DO NOT let any MemPalace error fail the step -- capture is `onError: skip`.
2. DO NOT write lossy summaries -- store the verbatim artifact text (AAAK compression is a separate, optional index).
3. DO NOT prune or delete drawers here -- pruning (`sync --apply`) is the curator agent's job at `ship:post`, wing-scoped only.
4. DO NOT skip the config gate or the dedup check.

View File

@@ -0,0 +1,102 @@
---
name: gsd:mempalace-recall
description: "Recall decisions, patterns, and surprises from MemPalace before planning"
argument-hint: "[phase-slug]"
allowed-tools:
- Read
- Write
- Bash
requires: [config]
---
**STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by the command system. Using the Read tool on this file wastes tokens. Begin executing Step 0 immediately.**
## Step 0 -- Banner
**Before ANY tool calls**, display this banner:
```
GSD > MEMPALACE RECALL
```
Then proceed to Step 1.
## Step 1 -- Config Gate
Check whether the MemPalace capability is enabled by reading `.planning/config.json` directly with the Read tool.
**DO NOT use `gsd-tools config get-value`** -- it hard-exits on missing keys.
1. Read `.planning/config.json` with the Read tool.
2. If the file does not exist: write the "unavailable" stub (Step 4) and **STOP**.
3. Parse the JSON. Proceed to Step 2 only if `config.mempalace && config.mempalace.enabled === true` **and** `config.mempalace.recall_on_plan !== false`. Otherwise display the disabled message and **STOP** (`recall_on_plan: false` turns plan-time recall off while leaving the rest of the capability enabled).
**Disabled message:**
```
GSD > MEMPALACE RECALL
MemPalace memory is disabled. To activate:
node <runtime-home>/gsd-core/bin/gsd-tools.cjs config-set mempalace.enabled true
Recall is opt-in; the loop proceeds normally without it.
```
This step is `onError: skip` at `plan:pre` -- recall never blocks planning.
## Step 2 -- Resolve wing, mode, and transport
1. **Wing.** Use `config.mempalace.wing` if non-empty; otherwise derive from `config.project_code`; otherwise fall back to the repository directory name.
2. **Mode.** Read `config.mempalace.memory_mode` (`augment` | `kg_backend` | `replace`, default `augment`). Only `augment` is wired today, so recall always treats the palace as additive; `kg_backend`/`replace` are forward-declared and behave as `augment`.
3. **Transport.** Prefer the **MCP tools** (`mempalace_*`) in interactive runs *when your MemPalace MCP server is registered and your runtime permits those tools*. Otherwise — headless/cron/autonomous runs, or runtimes that don't grant the MemPalace MCP tools — use the **CLI** (`mempalace wake-up`, `mempalace search`), which this skill's `Bash` allow-tool always covers. If neither is reachable, go to Step 4.
4. **Topic.** Read the phase `CONTEXT.md` (the consumed artifact). Derive a short search query from its title, goal, and key decisions.
## Step 3 -- Retrieve (read-only)
All calls in this step are side-effect-free. On any error or timeout, stop retrieving and write whatever was gathered (or the stub) -- never raise.
1. **Wake up** (cheap, ~600--900 tokens):
- Interactive: read the wing identity/summary, then `mempalace_search`.
- Headless: `mempalace wake-up --wing <wing>`.
2. **Targeted search:**
- Interactive: `mempalace_search(query=<topic>, wing=<wing>)`.
- Headless: `mempalace search "<topic>" --wing <wing>`.
3. **Knowledge-graph facts** (when `config.mempalace.mirror_kg` is true): `mempalace_kg_query` / `mempalace_kg_timeline` for decisions relevant to the topic and their validity windows. Only `augment` is currently wired, so the palace KG *supplements* GSD's native `.planning/graphs/` — do not treat it as the sole source. (`kg_backend`/`replace` are forward-declared and behave as `augment` today.)
4. **Dedup** the returned drawers/facts; keep the top results.
## Step 4 -- Write MEMORY-RECALL.md
Write `MEMORY-RECALL.md` in the current phase directory. The planner consumes it.
When recall succeeded, structure it as:
```markdown
# Memory Recall (MemPalace)
_Wing: <wing> · Mode: <mode> · Transport: <mcp|cli>_
## Prior decisions
- <decision> — <provenance: drawer id / kg fact, valid_from>
## Patterns
- <pattern> — <provenance>
## Surprises / gotchas
- <surprise> — <provenance>
```
When MemPalace is unreachable, write the stub and continue:
```markdown
# Memory Recall (MemPalace)
_MemPalace unavailable at recall time — proceeding without recalled memory._
```
## Anti-Patterns
1. DO NOT let any MemPalace error fail the step -- recall is `onError: skip`.
2. DO NOT write to the palace from this skill -- recall is read-only; capture is a separate skill.
3. DO NOT paste raw search output into the file -- distil to decisions/patterns/surprises with provenance.
4. DO NOT skip the config gate.

View File

@@ -1,11 +1,11 @@
---
name: gsd-context
description: "codebase intelligence | map graphify docs learnings"
description: "codebase intel | map graphify docs learnings mempalace"
argument-hint: ""
allowed-tools:
- Read
- Skill
requires: [map-codebase, graphify, docs-update, extract-learnings]
requires: [map-codebase, graphify, docs-update, extract-learnings, mempalace-recall, mempalace-capture]
---
Route to the appropriate codebase-intelligence skill based on the user's intent.
@@ -19,5 +19,7 @@ Route to the appropriate codebase-intelligence skill based on the user's intent.
| Generate a knowledge graph | gsd-graphify |
| Update project documentation | gsd-docs-update |
| Extract learnings from a completed phase | gsd-extract-learnings |
| Recall prior decisions and patterns before planning | gsd-mempalace-recall |
| File a phase artifact into MemPalace | gsd-mempalace-capture |
Invoke the matched skill directly using the Skill tool.