memory-query-capture

# memory-query-capture

Capture valuable assistant synthesis from conversation into durable semantic memory pages. This is the compounding primitive — explorations accumulate as reusable knowledge rather than evaporating into chat history.

## When to Use

Any time an assistant response produces analytical output worth preserving: comparisons, gap analyses, architectural assessments, synthesis narratives. Invoked explicitly by the user, suggested ambiently by the system, or chained automatically by other skills.

## Parameters

### --consumer (optional)
Consumer ID to write against. Resolved via ADR-021 D4 precedence: explicit > wrapper > auto-detect.

### --type (optional)
Page type: `synthesis`, `comparison`, `analysis`, or `gap`. If omitted, determined by heuristic or user prompt.

### --title (optional)
Page title. If omitted, derived from content via headline extraction or summarization.

## Invocation Modes

### Ambient mode
Suggested automatically when a query response exceeds a length/value threshold. The system presents a capture prompt; the user confirms or dismisses.

### Explicit mode
User invokes directly: "save this as a page", "capture that comparison", or calls `memory-query-capture` with parameters.

### Skill-chain mode
Any skill can call `memory-query-capture` as a final step after producing analytical output. The calling skill passes `--type` and `--title` to skip heuristics.

## Operation

1. **Capture synthesis** — extract the last assistant synthesis from conversation state.
2. **Determine page type** — from `--type` flag, content heuristic, or user prompt.
3. **Resolve consumer** — determine target consumer via ADR-021 D4 precedence (explicit > wrapper > auto-detect).
4. **Resolve destination** — read `memory.topology.derivedPages` from consumer's `manifest.json` and select the matching subdirectory (`derivedPages.synthesis`, `derivedPages.comparison`, etc.).
5. **Title the page** — from `--title` flag or derived from content (first heading, key noun phrase, or summarized label).
6. **Add cross-references** — identify source pages cited in the synthesis and insert cross-reference links per the consumer's `crossRefStyle` setting.
7. **Write page** — create the Markdown file at the resolved destination path.
8. **Update index and log** — call `memory-log-append` with `--op query-capture` and metadata about the captured page.
9. **Mark provenance** (optional) — record query origin, model actor, and sources cited in a provenance block at the end of the page.

## Page-Type Heuristics

When `--type` is not provided, the skill inspects the synthesis content:

| Content pattern | Assigned type |
|-----------------|---------------|
| Comparison table, side-by-side columns | `comparison` |
| Narrative prose with connective reasoning | `synthesis` |
| Gap analysis, missing coverage, "what's absent" | `gap` |
| Bullet-point assessment, evaluation criteria | `analysis` |

If the heuristic is ambiguous, prompt the user to select.

## Consumer Resolution

Follows ADR-021 D4 precedence:

1. **Explicit** — `--consumer` flag provided on invocation.
2. **Wrapper** — a parent skill passes consumer context down the chain.
3. **Auto-detect** — inspect `.aiwg/frameworks/registry.json` for the active consumer with a `memory.topology` contract.

If no consumer can be resolved, abort with a clear error requesting `--consumer`.

## Cross-Reference Style

The consumer's `manifest.json` declares a `crossRefStyle` — one of:

- `wikilink` — `[[page-name]]`
- `markdown` — `[page name](relative/path.md)`
- `at-mention` — `@consumer/path/to/page.md`

The skill reads this setting and formats all source-page links accordingly.

## Error Handling

- If no synthesis content is available in conversation state, report "nothing to capture" and exit.
- If the destination directory does not exist, create it before writing.
- Log write failures via `memory-log-append` are **non-blocking** — the page write is the primary operation.
- If consumer topology lacks a `derivedPages` mapping for the resolved type, fall back to the consumer's base memory directory.

## Schema Reference

@semantic-memory/schemas/memory-log-event.md

## Examples

```
# Explicit capture after a deep comparison
memory-query-capture --consumer research-complete --type comparison --title "Redis vs Valkey feature matrix"

# Ambient capture (system-suggested, user confirms)
> Your comparison of caching strategies looks worth preserving. Capture as a page? [Y/n]
memory-query-capture --type synthesis

# Skill-chain: architecture-evolution calls capture after producing assessment
memory-query-capture --consumer sdlc-complete --type analysis --title "Microservices migration readiness"
```