Distill Methodology

Guidelines for automated knowledge extraction and consolidation across memory systems.

Knowledge Candidate Criteria

An insight qualifies as a knowledge candidate when it meets ANY of these:

Confidence Scoring

Auto-store threshold: candidates scoring >= 0.8 are auto-stored to the vector store (silent, cold layer) via semantic_store — see the memory-ingest Stop hook. This is the single source of truth for that threshold.

Tier Routing

Tier paths and what belongs in each are defined in the agent-memory skill (§ Memory Tiers) -- do not restate them here. Route shared candidates to KNOWLEDGE.md and agent:{name} candidates to that agent's MEMORY.md.

Overflow: if KNOWLEDGE.md would exceed 200 lines, route the candidate to the most relevant agent file.

Output Format

Candidates are structured as:

- content: The knowledge text (max 500 chars)
- source: File path or "conversations:N_occurrences"
- source_type: conversation | spec | memory | semantic
- confidence: 0.0-1.0
- target_tier: shared | agent:{name}
- tags: categorization tags

200-Line Limit Enforcement

KNOWLEDGE.md has a hard limit of 200 lines (read in full by agents). When merging would exceed this limit:

1. High-confidence candidates (>= 0.7) get priority
2. Lower-confidence candidates overflow to agent-specific files
3. The orchestrator routes overflow to the most relevant agent based on tags

Dry-Run vs Apply

• Dry-run (default): Report what would change, write nothing
• Apply: Create timestamped backup, then write merged content
• Restore: Revert files from any backup timestamp

Conversation-Scoped Distillation

The /learn command runs distillation against a single conversation rather than mining all of .scaffolding/conversations/. This mode is backend-free and self-contained — no session-log mining, no database.

Inputs for one conversation_id (a UUID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). .scaffolding/conversations/ is a symlink to <share>/projects/<repo-name>/conversations; paths are unchanged:

Apply the Knowledge Candidate Criteria and Confidence Scoring above against these files only. With a single conversation, the "Cross-conversation pattern" criterion does not apply; rely on the Decision-section and pattern-keyword criteria. If context.md is absent, there is nothing to distill — exit cleanly.

Repeated failures (from timeline.md). A line under repeated failures (the same tool + normalized target failed >= 2 times in a run) becomes a gotcha candidate with a fixed confidence of 0.5. At 0.5 it is below the 0.8 auto-store threshold, so it goes to .scaffolding/.ingest-queue / /learn for propose-then-confirm and is NEVER auto-stored. Describe the failing command or tool and the count only; the timeline holds no output, so do not invent a cause.

Skill Promotion Criterion

Each distilled candidate routes to one of two destinations:

Promote to a skill only when the candidate is a generalizable procedure, not a single fact. A one-off fact ("module X has a 301 redirect bug") is a memory entry; a recurring procedure ("how to safely roll a zero-downtime migration") is a skill. When in doubt, prefer a memory entry — skills carry an auto-invocation cost and should stay few and sharp.