liteagents 2.8.2 → 2.9.0

package/packages/claude/commands/remember.md

@@ -9,10 +9,11 @@ Consolidate session stashes and friction analysis into a single project-local ME
 **Guardrails**
 - Favor straightforward, minimal implementations first and add complexity only when requested or clearly required.
 - Keep changes tightly scoped to the requested outcome.
+- **Precision over recall for hot memory.** A false antigen loaded into `@MEMORY.md` steers every future session. When unsure, record as a low-confidence episode — do not promote.
 
 **What it does**
 
-Reads all raw material (`.claude/stash/*.md` + `.claude/friction/antigen_clusters.json`), extracts durable facts, episodes, and behavioral preferences into a single `.claude/memory/MEMORY.md`, then injects a managed memory section into `CLAUDE.md`.
+Reads all raw material (`.claude/stash/*.md` + `.claude/friction/antigen_clusters.json`), extracts durable facts, episodes, and behavioral antigens into a single `.claude/memory/MEMORY.md`, then injects a managed memory section into `CLAUDE.md`.
 
 **Steps**
 
@@ -21,7 +22,7 @@ Reads all raw material (`.claude/stash/*.md` + `.claude/friction/antigen_cluster
    - Check for friction output at `.claude/friction/antigen_clusters.json` (preferred) or `.claude/friction/antigen_review.md` (fallback)
    - Read existing `.claude/memory/MEMORY.md` if it exists — create dir if missing
    - Read processed manifest at `.claude/memory/.processed` — skip already-processed stashes
-   - If no unprocessed stashes, report "nothing to consolidate" and stop
+   - If no unprocessed stashes AND no friction output, report "nothing to consolidate" and stop
 
 2. **Extract from unprocessed stashes** (use Task tool with sonnet model for each)
    - For each unprocessed stash, call sonnet to extract:
@@ -31,13 +32,72 @@ Reads all raw material (`.claude/stash/*.md` + `.claude/friction/antigen_cluster
    - Collect all new facts and episodes
 
 3. **Merge into MEMORY.md**
-   - Read existing `.claude/memory/MEMORY.md` and parse its three sections (## Facts, ## Episodes, ## Preferences)
+   - Read existing `.claude/memory/MEMORY.md` and parse its sections (## Facts, ## Episodes, ## Antigens)
    - **Facts section**: call sonnet with existing facts + newly extracted facts
      - Rules: new updates replace old, contradictions keep new version, duplicates dropped
      - Keep facts atomic, one line each
    - **Episodes section**: append new episode entries (append-only, timestamped, no dedup)
-   - **Preferences section**: only update if friction output exists (step 4)
-   - Write merged result to `.claude/memory/MEMORY.md` in this format:
+   - **Antigens section**: only update from friction output (step 4)
+   - Write merged result to `.claude/memory/MEMORY.md` in the format under step 6.
+
+4. **Distill friction into antigens** (only if friction output exists)
+
+   > Friction has already done the heavy part: it scanned the raw session logs,
+   > kept only **observed user reactions** (corrections, curses, repeated stops),
+   > pooled them per session, and lexically pre-grouped the obvious repeats. Each
+   > cluster carries `theme`, `suggested_artifact`, `confidence`, `severity`,
+   > `sessions` (recurrence count), `projects`, `signals`, `contexts` (the verbatim
+   > user quotes), `preceding` (the agent action + result just before the reaction —
+   > the trigger), and `self_suspect` (friction's guess that the user was correcting
+   > *themselves*). **You work from these short quotes — never re-read the session
+   > logs.** Friction's lexical grouping and flags are hints, not the verdict.
+
+   - Read `.claude/friction/antigen_clusters.json`.
+   - **4a. Classify target, then semantically consolidate** (the parts lexical matching can't do).
+     Call sonnet with the cluster quotes + their `preceding`/`projects`/`sessions`/`self_suspect`
+     (NOT the logs), and have it:
+     1. **Decide the target of each reaction — agent or self.** Drop *self/context*
+        corrections where the user redirected themselves ("wrong project", "wrong window",
+        "nevermind") — the agent did nothing wrong. `self_suspect` and an empty `preceding`
+        (no agent action) are strong cues. Keep only **agent-directed** reactions.
+     2. **Merge same-complaint paraphrases** that friction left split because they share no
+        words (e.g. "nothing landed, fuck you" + "it says pushed but none got it" → one antigen).
+     Output one object per surviving antigen:
+     ```json
+     {
+       "rule": "Verify the artifact is actually live after publish; a clean exit code ≠ done",
+       "target": "agent",
+       "evidence": ["both say pushed... none got it", "notng landed in live-claude, fuck you"],
+       "errors": ["Exit code 0 (claimed success)"],
+       "sessions": 2,
+       "confidence": "medium"
+     }
+     ```
+   - **4b. Route + tier by recurrence.** For each cluster and each LLM-merged group:
+     - `suggested_artifact: antigen` (recurring + severe) or an LLM-merged group → an
+       **antigen** (a "do/don't" behavioral rule), with its verbatim evidence quotes.
+     - `suggested_artifact: fact` (recurring + mild) → a **Fact**.
+     - `suggested_artifact: episode` that did **not** merge into a recurring group → an
+       **Episode** (one-off; recorded, not a rule).
+     - Confidence by distinct-session recurrence:
+       - **High** (5+ sessions) → loaded hot via `@MEMORY.md`
+       - **Medium** (3-4 sessions) → recorded under Antigens, *not* loaded hot
+       - **Low** (<3 sessions) → keep as Episode only
+   - **Never auto-promote.** Only High-confidence (5+ sessions) antigens load hot. A
+     single dramatic correction is an Episode, not an antigen.
+   - Update the Antigens section in MEMORY.md (promote/demote based on new recurrence).
+
+5. **Inject memory reference into CLAUDE.md**
+   - Compose the section between `<!-- MEMORY:START -->` and `<!-- MEMORY:END -->` markers:
+     ```
+     <!-- MEMORY:START -->
+     @MEMORY.md
+     <!-- MEMORY:END -->
+     ```
+   - The `@MEMORY.md` reference points to `.claude/memory/MEMORY.md` — Claude loads the full file directly, so no inline duplication is needed
+   - If CLAUDE.md already has MEMORY markers, replace the section between them
+   - If CLAUDE.md has no MEMORY markers, append the section at the end
+   - If no CLAUDE.md exists, create one with just the memory section
 
    ```markdown
    # Project Memory
@@ -45,52 +105,22 @@ Reads all raw material (`.claude/stash/*.md` + `.claude/friction/antigen_cluster
 
    ## Facts
    - [atomic fact 1]
-   - [atomic fact 2]
 
    ## Episodes
    ### YYYY-MM-DD - [title]
    - [bullet narrative]
 
-   ### YYYY-MM-DD - [title]
-   - [bullet narrative]
+   ## Antigens
+   ### High Confidence (loaded — applies every session)
+   - [behavioral rule] (evidence: [N] sessions — "[verbatim quote]")
 
-   ## Preferences
-   ### High Confidence
-   - [pattern] (evidence: [count] observations)
+   ### Medium Confidence (observing — not loaded)
+   - [behavioral rule] (evidence: [N] sessions)
 
-   ### Medium Confidence
-   - [pattern] (evidence: [count] observations)
-
-   ### Low Confidence
-   - [pattern] (evidence: [count] observations)
+   ### Low Confidence (needs more data)
+   - [pattern] (evidence: [N] sessions)
    ```
 
-4. **Distill friction into preferences** (only if friction output exists)
-   - Read `.claude/friction/antigen_clusters.json` — this contains clustered failure patterns with counts, user_context quotes, and tool sequences
-   - For the **top 10 clusters** (by score), extract the `contexts` field — these are the actual user messages that show behavioral patterns
-   - Call sonnet with:
-     - The top 10 clusters (signal, tool_pattern, count, sessions, contexts, errors)
-     - Existing Preferences section from MEMORY.md
-   - Extract BEHAVIORAL preferences (patterns demonstrated, not stated) — the user_context quotes are the primary evidence
-   - Confidence tiers:
-     - **High Confidence**: 5+ observations — available via @MEMORY.md
-     - **Medium Confidence**: 3+ observations — observing, not loaded
-     - **Low Confidence**: <3 observations — needs more data
-   - Promote/demote based on new evidence
-   - Update the Preferences section in MEMORY.md
-
-5. **Inject memory reference into CLAUDE.md**
-   - Compose the section between `<!-- MEMORY:START -->` and `<!-- MEMORY:END -->` markers:
-     ```
-     <!-- MEMORY:START -->
-     @MEMORY.md
-     <!-- MEMORY:END -->
-     ```
-   - The `@MEMORY.md` reference points to `.claude/memory/MEMORY.md` — Claude loads the full file directly, so no inline duplication is needed
-   - If CLAUDE.md already has MEMORY markers, replace the section between them
-   - If CLAUDE.md has no MEMORY markers, append the section at the end
-   - If no CLAUDE.md exists, create one with just the memory section
-
 6. **Update processed manifest**
    - Append paths of newly processed stashes to `.claude/memory/.processed`
 
@@ -98,13 +128,13 @@ Reads all raw material (`.claude/stash/*.md` + `.claude/friction/antigen_cluster
    - Number of stashes processed
    - Facts count (total, new)
    - Episodes count (total, new)
-   - Preferences count by confidence tier
+   - Antigens count by confidence tier, with how many newly promoted to hot
    - Confirm MEMORY.md and CLAUDE.md updated
 
 **File locations (all project-local)**
 - Memory file: `.claude/memory/MEMORY.md` (single source of truth, referenced as @MEMORY.md)
 - Stash files: `.claude/stash/*.md`
-- Friction output: `.claude/friction/antigen_clusters.json` (clustered patterns with user contexts)
+- Friction output: `.claude/friction/antigen_clusters.json` (observed-reaction clusters: theme, suggested_artifact, confidence, severity, sessions, projects, contexts)
 - Friction fallback: `.claude/friction/antigen_review.md` (human-readable clusters)
 - Processed manifest: `.claude/memory/.processed`
 - Output: `CLAUDE.md` (managed MEMORY section with @MEMORY.md reference)