remember

## Runtime Configuration (Step 0 — before any processing) Read these files to configure domain-specific behavior: 1. **`ops/derivation-manifest.md`** — vocabulary mapping, domain context - Use `vocabulary.notes` for the notes folder name - Use `vocabulary.note` for the note type name in output - Use `vocabulary.rethink` for rethink command name in threshold alerts - Use `vocabulary.topic_map` for MOC references 2. **`ops/config.yaml`** — thresholds - `self_evolution.observation_threshold` (default: 10) — for threshold alerts - `self_evolution.tension_threshold` (default: 5) — for threshold alerts 3. **`ops/methodology/`** — read existing methodology notes before creating new ones (prevents duplicates) If these files don't exist (pre-init invocation or standalone use), use universal defaults. ## EXECUTE NOW **Target: $ARGUMENTS** Parse immediately: - If target contains a quoted description or unquoted text: **explicit mode** — user describes friction directly - If target is empty: **contextual mode** — review recent conversation for corrections - If target contains `--mine-sessions` or `--mine`: **session mining mode** — scan ops/sessions/ for patterns **START NOW.** Reference below defines the three modes. --- ## Explicit Mode User provides a description: `/remember "don't process personal notes like research"` or `/remember always check for duplicates before creating` ### Step 1: Parse the Friction Analyze the user's description to extract: - **What the agent did wrong** (or what the user wants to prevent) - **What the user wants instead** (the correct behavior) - **The scope** — when does this apply? Always? Only for specific content types? Only in certain phases? - **The category** — which area of agent behavior does this affect? | Category | Applies When | |----------|-------------| | processing | How to extract, reduce, or handle content | | capture | How to record, file, or organize incoming material | | connection | How to find, evaluate, or add links between notes | | maintenance | How to handle health checks, reweaving, cleanup | | voice | How to write, what tone or style to use | | behavior | General agent conduct, interaction patterns | | quality | Standards for notes, descriptions, titles | ### Step 2: Check for Existing Methodology Notes Before creating a new note, read all files in `ops/methodology/`: ```bash ls -1 ops/methodology/*.md 2>/dev/null ``` For each existing note, check if it covers the same behavioral area. Specifically: - Does an existing note address the same friction? - Would the new learning extend an existing note rather than warrant a new one? | Check Result | Action | |-------------|--------| | No existing notes in this area | Create new methodology note | | Existing note covers different aspect of same area | Create new note, link to existing | | Existing note covers same friction | Extend existing note with new evidence instead of creating duplicate | | Existing note contradicts new friction | Create both a new methodology note AND an observation about the contradiction | ### Step 3: Create Methodology Note Write to `ops/methodology/`: **Rule Zero:** This methodology note becomes part of the system's canonical specification. ops/methodology/ is not a log of what happened — it is the authoritative declaration of how the system should behave. Write this note as a directive: what the agent SHOULD do, not what went wrong. Future sessions, /rethink drift checks, and meta-skills will consult this note as ground truth for system behavior. **Filename:** Convert the prose title to kebab-case. Example: "don't process personal notes like research" becomes `dont-process-personal-notes-like-research.md`. ```markdown --- description: [what this methodology note teaches — specific enough to be actionable] type: methodology category: [processing | capture | connection | maintenance | voice | behavior | quality] source: explicit created: YYYY-MM-DD status: active --- # [prose-as-title describing the learned behavior] ## What to Do [Clear, specific guidance. Not "be careful" but "when encountering X, do Y instead of Z."] ## What to Avoid [The specific anti-pattern this note prevents. What was the agent doing wrong?] ## Why This Matters [What goes wrong without this guidance. Connect to the user's actual friction — what broke, what was confusing, what wasted time.] ## Scope [When does this apply? Always? Only for certain content types? Only during specific phases? Be explicit about boundaries.] --- Related: [[methodology]] ``` **Writing quality for methodology notes:** - Be specific enough that a fresh agent session could follow this guidance without additional context - Use concrete examples where possible — "when processing therapy notes" not "when processing certain types of content" - State both the DO and the DON'T — methodology notes that only say what to do miss the anti-pattern that triggered them - Keep scope explicit — unbounded methodology notes get applied where they should not be ### Step 4: Update Methodology MOC Edit `ops/methodology.md` (create if missing): 1. Find the section for the note's category 2. Add the note with a context phrase: `- [[note title]] — [what this teaches]` 3. If no section exists for this category, create one ```markdown ## [Category] - [[existing note]] — what it teaches - [[new note]] — what this teaches ``` ### Step 5: Check Pattern Threshold Count methodology notes in the same category: ```bash grep -rl "^category: [CATEGORY]" ops/methodology/ 2>/dev/null | wc -l | tr -d ' ' ``` If 3+ notes exist in the same category, this is a signal for /{DOMAIN:rethink}: ``` This is friction capture #[N] in the "[category]" area. 3+ captures in the same area suggest a systemic pattern. Consider running /{DOMAIN:rethink} to review [category] methodology patterns and potentially elevate them to context file changes. ``` ### Step 6: Output ``` --=={ remember }==-- Captured: [brief description of the learning] Filed to: ops/methodology/[filename].md Updated: ops/methodology.md MOC Category: [category] [If pattern threshold reached:] This is friction capture #[N] in the "[category]" area. Consider running /{DOMAIN:rethink} to review [category] methodology patterns. ``` --- ## Contextual Mode No argument provided: `/remember` The agent reviews the current conversation to find corrections the user made that should become methodology notes. ### Step 1: Review Recent Context Scan the current conversation for correction signals. Look for: | Signal Type | Detection Patterns | Example | |------------|-------------------|---------| | Direct correction | "no", "that's wrong", "not like that", "incorrect" | "No, don't split that into separate notes" | | Redirection | "actually", "instead", "let's do X not Y", "stop" | "Actually, keep the original phrasing" | | Preference statement | "I prefer", "always do X", "never do Y", "from now on" | "Always check for duplicates first" | | Frustration signal | "again?", "I already said", "why did you", "that's the third time" | "Why did you create a duplicate again?" | | Quality correction | "too vague", "not specific enough", "that's not what I meant" | "That description is too vague — add the mechanism" | ### Step 2: Identify the Most Recent Correction From the detected corrections, identify the most recent one. Present it to the user for confirmation: ``` --=={ remember — contextual }==-- Detected correction: "[quoted user text]" Interpreted as: [What the agent should learn from this — specific behavioral change] Category: [category] Capture this as a methodology note? (yes / no / modify) ``` **Wait for user confirmation.** Do not create notes from inferred corrections without approval — the agent might misinterpret what the user meant. ### Step 3: Handle Response | Response | Action | |----------|--------| | "yes" | Create methodology note (same process as explicit mode, `source: contextual`) | | "no" | Do not create. Optionally ask what the user actually meant. | | "modify" or different description | Use the modified description instead | | User provides additional context | Incorporate into the methodology note | ### Step 4: If Multiple Corrections Detected If the conversation contains more than one correction: ``` Detected [N] corrections in this conversation: 1. "[quoted text]" → [interpretation] 2. "[quoted text]" → [interpretation] 3. "[quoted text]" → [interpretation] Capture all as methodology notes? (all / select numbers / none) ``` ### Step 5: If No Corrections Found ``` --=={ remember — contextual }==-- No recent corrections detected in this conversation. Options: - /remember "description" — capture specific friction with explicit text - /remember --mine-sessions — scan session transcripts for uncaptured patterns ``` --- ## Session Mining Mode Flag provided: `/remember --mine-sessions` or `/remember --mine` This mode scans stored session transcripts for friction patterns the user addressed during work but did not explicitly `/remember`. ### Step 1: Find Unmined Sessions ```bash # Find session files without mined: true marker UNMINED=$(grep -rL '^mined: true' ops/sessions/*.md 2>/dev/null) UNMINED_COUNT=$(echo "$UNMINED" | grep -c . 2>/dev/null || echo 0) ``` If no unmined sessions found: ``` --=={ remember — mine }==-- No unprocessed sessions found in ops/sessions/. All sessions have been mined for friction patterns. ``` ### Step 2: Mine Each Session For each unmined session, read the full content and search for: | Pattern | What to Look For | Significance | |---------|-----------------|-------------| | User corrections | "no", "that's wrong", "not like that" followed by correct approach | Direct methodology learning | | Repeated redirections | Same type of correction appearing multiple times | Strong behavioral signal | | Workflow breakdowns | Steps that failed, had to be retried, or produced wrong output | Process gap | | Agent confusion | Questions the agent asked that it should have known the answer to | Missing context or methodology | | Undocumented decisions | User made a choice without explaining reasoning — but the choice reveals a preference | Implicit methodology | | Escalation patterns | User moving from gentle correction to firm direction | Methodology note urgency signal | ### Step 3: Classify Findings For each detected pattern, classify into one of two output types: | Finding Type | Output | When | |-------------|--------|------| | Actionable methodology learning | Methodology note in `ops/methodology/` | Clear behavioral change needed. Agent can act on this. | | Novel observation requiring more context | Observation note in `ops/observations/` | Pattern detected but not yet clear enough for methodology guidance. Needs accumulation. | ### Step 4: Deduplicate Against Existing Notes Before creating any notes: 1. Read all existing methodology notes in `ops/methodology/` 2. Read all existing observations in `ops/observations/` 3. For each finding: - If an existing methodology note covers this → skip or add as evidence to existing - If an existing observation covers this → skip or add as evidence to existing - If novel → create new note ### Step 5: Create Notes **For methodology findings:** Follow the same creation process as explicit mode (Step 3 in Explicit Mode section), with `source: session-mining` and add `session_source: [session filename]`. **For observation findings:** ```markdown --- description: [what was observed and what it suggests] category: [friction | surprise | process-gap | methodology] status: pending observed: YYYY-MM-DD source: session-mining session_source: [session filename] --- # [the observation as a sentence] [What happened, which session, why it matters, and what pattern it might be part of.] --- Related: [[observations]] ``` ### Step 6: Mark Sessions as Mined After processing each session, add `mined: true` to its frontmatter: ```bash # Add mined marker to session file frontmatter ``` Use Edit tool to add `mined: true` after the existing frontmatter fields. Do not modify other frontmatter content. ### Step 7: Report ``` --=={ remember — mine }==-- Sessions scanned: [N] Methodology notes created: [count] - [filename] — [brief description] Observations created: [count] - [filename] — [brief description] Duplicates skipped: [count] - [existing note] — already covers [pattern] Sessions marked as mined: [list] [If pattern thresholds reached:] Category "[category]" now has [N] methodology notes. Consider running /{DOMAIN:rethink} to review [category] patterns. ``` --- ## The Methodology Learning Loop This is the complete cycle that /remember participates in: ``` Work happens → user corrects agent behavior (explicit or implicit) → /remember captures correction as methodology note → methodology note filed to ops/methodology/ → agent reads methodology notes at session start (via context file reference) → agent behavior improves → fewer corrections needed → when methodology notes accumulate (3+ in same category) → /rethink triages and detects patterns → patterns elevated to context file changes → system methodology evolves at the architectural level → the cycle continues with new friction at the edges ``` Each layer of this loop serves a different purpose: - **/remember** captures individual friction points — fast, low ceremony - **ops/methodology/** stores accumulated behavioral guidance — persists across sessions - **/rethink** detects patterns and proposes structural changes — periodic, deliberate - **ops/context.md** (or equivalent) embodies the system's stable methodology — changes rarely, by human approval The loop is healthy when methodology notes accumulate slowly (friction is being addressed) and /rethink elevates patterns to context-level changes when thresholds are exceeded. The loop is unhealthy when the same category keeps getting methodology notes without elevation (the system is capturing friction but not learning from it). ### Rule Zero: Methodology as Canonical Specification The methodology folder is more than a friction capture log. It is the system's authoritative self-model — the canonical specification from which drift is measured. **What this means for /remember:** - Every methodology note you create becomes part of the spec. Write directives, not incident reports. - The title should be an actionable behavior ("check for semantic duplicates before creating any note") not a problem description ("duplicate creation issue"). - Future /rethink sessions will compare system behavior against what methodology notes declare. Vague notes create unmeasurable specs. **What this means for the system:** - ops/methodology/ is consulted by meta-skills (/ask, /architect, /rethink) as the source of truth for how the system works. - Drift detection compares methodology note assertions against actual config.yaml and context file state. - When methodology notes are stale (older than config changes), the system surfaces this as a maintenance condition. The methodology folder is the spec. /remember writes the spec. /rethink enforces the spec. The loop is closed. --- ## Methodology Note Design ### Title Pattern Methodology note titles should describe what the agent should DO, not what went wrong: | Bad (describes problem) | Good (describes behavior) | |------------------------|--------------------------| | "duplicate creation issue" | "check for semantic duplicates before creating any note" | | "wrong tone problem" | "match the user's formality level in all output" | | "processing too aggressive" | "differentiate personal notes from research in processing depth" | The title is what the agent reads at session start. It should be immediately actionable as a behavioral directive. ### Body Quality Methodology notes are operational guidance, not essays. They should be: