forge

Forge Skill

Cross-vendor analog: the capture half of Anthropic Managed Agents' memory + dreaming pair (May 2026). Forge mines transcripts; $curate --mode=dream curates between sessions. Off the API, local, cross-vendor.

Typically runs automatically via SessionEnd hook.

Loop position: capture sub-step of move 7 in the operating loop. Extracts candidate learnings from transcripts; the promotion ratchet decides which ones survive (one-offs die at handoff; repeats promote to .agents/learnings/). Forge is the funnel, not the filter.

Extract knowledge from session transcripts.

How It Works

The SessionEnd hook runs:

ao forge transcript --last-session --queue --quiet

This queues the session for knowledge extraction.

Flags

Promote Mode

Given /forge --promote:

Promote Step 1: Find Pending Files

ls -lt .agents/knowledge/pending/*.md 2>/dev/null
ls -lt .agents/ao/pending.jsonl 2>/dev/null

If no pending files found, report "No pending extractions" and exit.

Promote Step 2: Process Each Pending File

For each file in .agents/knowledge/pending/:

1. Read the file content
2. Validate it has required fields (# Learning:, **Category**:, **Confidence**:)
3. Copy to .agents/learnings/ (preserving filename)
4. Remove the source file from .agents/knowledge/pending/

Promote Step 3: Process Pending Queue

Promote Step 4: Report

Done. Return immediately after reporting.

Manual Execution

Given /forge [path]:

Step 1: Identify Transcript

With ao CLI:

Without ao CLI: Look at recent conversation history and extract learnings manually.

Step 2: Extract Knowledge Types

Read skills/forge/references/uncaptured-lesson-patterns.md for signal patterns and the 26 known uncaptured lesson categories.

Look for these patterns in the transcript:

Uncaptured Lesson Matching: During transcript scanning, match events against the 26 known uncaptured lesson patterns (see references/uncaptured-lesson-patterns.md). Pre-fill learning templates with matched pattern metadata (category, base confidence, pattern number tag).

Step 3: Write Candidates

Write to: .agents/forge/YYYY-MM-DD-forge.md

Step 4: Index for Search

Step 5: Update Capture Tracking

After extracting learnings that match uncaptured lesson patterns (Step 2), record which patterns were captured. This state lives in .agents/forge/capture-tracking.json (a runtime artifact, never in skills/).

1. Read .agents/forge/capture-tracking.json if it exists, otherwise start with {}
2. For each matched pattern, add or update an entry keyed by pattern number:

   {
     "3": {"captured": true, "date": "2026-03-30", "learning_path": ".agents/learnings/tooling/use-bin-cp.md"},
     "7": {"captured": true, "date": "2026-03-29", "learning_path": ".agents/learnings/operations/worktree-commit.md"}
   }
3. Write the updated JSON back to .agents/forge/capture-tracking.json

Pattern numbers correspond to the numbered headings in references/uncaptured-lesson-patterns.md (1-30, 26 total patterns).

Step 6: Report Results

Tell the user:

• Number of items extracted by type
• Location of forge output
• Candidates ready for promotion to learnings
• Capture progress: "X/26 uncaptured lesson patterns captured" (read from .agents/forge/capture-tracking.json)

The Quality Pool

Forged candidates enter at Tier 0 (.agents/forge/), then promote to Tier 1 (.agents/learnings/) via human review, 2+ citations, or auto-promote when confidence >= 0.7 (ao-free fallback).

Key Rules

• Runs automatically - usually via hook
• Extract, don't interpret - capture what was said
• Score by confidence - not all extractions are equal
• Queue for review - candidates need validation

Examples

See references/examples.md [blocked] for the SessionEnd hook invocation walkthrough and manual transcript-mining walkthrough.

Troubleshooting

Reference Documents

• references/forge.feature [blocked] — Executable spec: mine transcripts → queued candidates, funnel-not-filter, --promote, consumes-transcripts-not-skills (soc-qk4b)
• references/uncaptured-lesson-patterns.md [blocked] — signal patterns and 26 known uncaptured lesson categories for transcript mining
• references/feedback-compiler-drafts.md [blocked] — auto-drafted learning workflow (F5.4 fail->pass ledger transitions, cli/internal/feedbackcompiler)