agenticnotetaking/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/:

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.

---
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

## [Category]

- [[existing note]] — what it teaches
- [[new note]] — what this teaches

Step 5: Check Pattern Threshold

Count methodology notes in the same category:

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

# 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:

---
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:

# 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:

1. Specific enough for a fresh agent session — no assumed context from the session that created them
2. Scoped explicitly — when does this apply and when does it not?
3. Dual-sided — both what to do AND what to avoid
4. Evidence-grounded — reference the specific friction that triggered this learning

Category Selection

Choose the most specific applicable category:

| Category | Use When | |----------|---------| | processing | Friction during /reduce, extraction, claim creation | | capture | Friction during inbox filing, raw material handling | | connection | Friction during /reflect, link evaluation, MOC updates | | maintenance | Friction during /reweave, health checks, cleanup | | voice | Friction about writing style, tone, output formatting | | behavior | Friction about general agent conduct, interaction patterns, tool usage | | quality | Friction about note quality, description writing, title crafting |

If a friction point spans categories (e.g., "processing voice" or "capture quality"), choose the primary category and mention the secondary in the body.

---

Edge Cases

No ops/methodology/ Directory

Create it and the ops/methodology.md MOC:

---
description: Methodology notes capturing how this system has learned to operate
type: moc
---

# methodology

Methodology notes organized by category. Each note captures a specific behavioral learning.

## Processing

## Capture

## Connection

## Maintenance

## Voice

## Behavior

## Quality

Duplicate Friction

If a methodology note with very similar content already exists:

1. Do NOT create a duplicate
2. Link to the existing note
3. Add the new instance as evidence: update the existing note's body with the new context
4. Report: "Extended existing methodology note [[title]] with additional evidence"

Contradicting Existing Methodology

If the new friction CONTRADICTS an existing methodology note (user now wants the opposite of what was previously captured):

1. Create an observation in ops/observations/ documenting the contradiction
2. Update the existing methodology note's status to superseded and add superseded_by: [new note]
3. Create the new methodology note with the updated guidance
4. Report the contradiction and suggest /rethink if this is part of a broader pattern

No Sessions to Mine

Report clearly: "No unprocessed sessions found in ops/sessions/." Do not treat this as an error.

Very Long Sessions

For sessions longer than 2000 lines:

1. Process in chunks of ~500 lines
2. Track findings across chunks to detect patterns that span the session
3. Report chunk-level progress for transparency

Implicit vs Explicit Corrections

Some corrections are implicit — the user does it themselves rather than telling the agent to change:

• User manually edits a note the agent created (the edit reveals what was wrong)
• User chooses a different approach without explaining why
• User skips a step the agent suggested

In contextual mode, flag these as lower-confidence findings and always confirm before creating methodology notes from implicit signals.

Empty Conversation Context

In contextual mode with no conversation history (e.g., first message of a session):

--=={ remember — contextual }==--

  No conversation context available to analyze.
  Use /remember "description" to capture specific friction directly.