---
name: memory
description: |
  Cross-run memory system that learns from past ArcheFlow runs. Detects recurring findings,
  stores lessons, and injects known issues into agent prompts so the same mistakes are not
  repeated across orchestrations.
  <example>User: "archeflow memory list"</example>
  <example>User: "archeflow memory add 'User prefers single bundled PR'"</example>
  <example>Automatically loaded at run start and after run.complete</example>
---

# Cross-Run Memory

ArcheFlow forgets everything after each run. This skill extracts lessons from completed runs and injects them into future agent prompts, so recurring issues (timeline errors, missing null checks) are caught proactively.

## Storage

```
.archeflow/memory/lessons.jsonl     # Append-only, one lesson per line
.archeflow/memory/archive.jsonl     # Decayed lessons (frequency reached 0)
.archeflow/memory/audit.jsonl       # Injection audit trail
```

## Lesson Types

| Type | Source | Description |
|------|--------|-------------|
| `pattern` | Auto-detected | Recurring finding across runs (same category + similar description) |
| `preference` | Manual | User correction or workflow preference (injected immediately, skips frequency threshold) |
| `archetype_hint` | Auto-detected | Per-archetype insight (e.g., Sage catches voice drift in monologues) |
| `anti_pattern` | Manual or auto | Something that was tried and failed -- avoid repeating |

## Lesson JSON Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | `m-NNN` (monotonically increasing) |
| `ts` | ISO 8601 | Created or last updated |
| `run_id` | string | Run that created or last triggered this lesson |
| `type` | string | `pattern`, `preference`, `archetype_hint`, `anti_pattern` |
| `source` | string | Archetype name or `user_feedback` |
| `description` | string | Human-readable lesson text |
| `frequency` | integer | Times this lesson was triggered |
| `severity` | string | `bug`, `warning`, `info`, `recommendation` |
| `domain` | string | `writing`, `code`, `general`, or project-specific |
| `tags` | string[] | Keywords for matching and filtering |
| `archetype` | string? | For `archetype_hint` -- which archetype this applies to |
| `last_seen_run` | string | Run ID where last matched |
| `runs_since_last_seen` | integer | Counter for decay |

Example:
```jsonl
{"id":"m-001","ts":"2026-04-03T14:00:00Z","run_id":"2026-04-03-der-huster","type":"pattern","source":"guardian","description":"Timeline references must match story start day","frequency":2,"severity":"bug","domain":"writing","tags":["continuity","timeline"],"last_seen_run":"2026-04-03-der-huster","runs_since_last_seen":0}
```

---

## Auto-Detection

After each `run.complete`, extract lessons from findings:

```bash
./lib/archeflow-memory.sh extract .archeflow/events/<run_id>.jsonl
```

The script reads `review.verdict` events, matches findings against existing lessons by keyword overlap (50%+ threshold), increments frequency on matches, and creates new candidate lessons (frequency: 1) for unmatched findings with severity >= WARNING.

**Promotion rule:** A finding needs `frequency >= 2` (seen in 2+ runs) before injection. This filters out one-off noise. Preferences skip this threshold.

## Injection

Before spawning agents, inject relevant lessons:

```bash
LESSONS=$(./lib/archeflow-memory.sh inject <domain> <archetype>)
```

Rules: filters by domain (or `general`), optionally by archetype, requires `frequency >= 2`, sorts by frequency descending, caps at 10 lessons. Lessons with `frequency >= 5` are always injected regardless of filters.

Injected as a markdown section appended to the agent's system prompt:

```markdown
## Known Issues (from past runs)
- Timeline references must match story start day [seen 3x, guardian]
- Voice drift common in monologue passages >200 words [seen 2x, sage]
```

## Decay

After each `run.complete`, apply decay: lessons not seen for 10 runs lose 1 frequency. When frequency reaches 0, the lesson is archived.

```bash
./lib/archeflow-memory.sh decay
```

## Manual Management

```bash
archeflow memory add "User prefers single bundled PR"   # Add preference (injected immediately)
archeflow memory list                                    # Show all active lessons
archeflow memory forget m-002                            # Archive a lesson
```

## Audit Trail

Track which lessons are injected per run and whether they were effective. Pass `--audit <run_id>` to inject to log records. After a run, `audit-check <run_id>` compares injected lessons against review findings: no matching finding = helpful (issue prevented), matching finding = ineffective (issue repeated despite injection).

```bash
./lib/archeflow-memory.sh inject "$DOMAIN" "" --audit "$RUN_ID"
./lib/archeflow-memory.sh audit-check <run_id>
```

## Integration Points

| Moment | Action | Script Command |
|--------|--------|----------------|
| After `run.complete` | Extract lessons from findings | `archeflow-memory.sh extract <events.jsonl>` |
| After extraction | Apply decay to all lessons | `archeflow-memory.sh decay` |
| Before agent spawn | Inject relevant lessons | `archeflow-memory.sh inject <domain> <archetype>` |
| User command | Add/list/forget lessons | `archeflow-memory.sh add/list/forget` |