Memory Retrieve

Purpose / When to Activate

Activate before

context-building

whenever a task requires historical context.

Never load full memory. Always filter by relevance. Never substitute summaries for durable memory (decisions, patterns, project).

---

3-Level Progressive Disclosure

Level 1 — INDEX SCAN (~5 tokens/entry)
  Read index.md → Decision Registry table (DEC | Domain | Level | Title)
  Agent identifies relevant decision(s) by domain and/or level

Level 2 — INDIVIDUAL ADR FILES (~300 tokens/file)
  Load specific decisions/DEC-{ID}.md files for full entry text
  Load other relevant category files (patterns, project, ops)
  Optionally traverse `related_to` in loaded files to discover adjacent decisions
  Or invoke `memory-search` Mode C for systematic cross-reference discovery

Level 3 — CROSS-DOMAIN SCAN (only for Decision Consistency Gate)
  Grep frontmatter across all DEC-*.md files for conflicts
  Only triggered when recording a new decision (see Decision Consistency Gate in decision-extraction skill)

---

Process

1. Read memory index (

   contexts/memory/index.md

   ). This contains:
   • Shared categories table (paths + purpose)
   • Decision Registry: one row per DEC-ID with domain, level, and title If

     index.md

     is absent or empty, fall back to scanning

     contexts/memory/

     directory structure.

2. Identify relevant decisions for the current task:

   • Filter the Decision Registry by domain (e.g.,

     billing

     ,

     matching

     )
   • Filter by level if scope is known (e.g., only

     architectural

     for implementation tasks)
   • From story/epic tags or explicit instruction scope

3. Load memory by durability class:

   Durable memory (decisions, patterns, project, ops, contacts, domains): → Load individual

   decisions/DEC-{ID}.md

   files directly. Full text, never summaries. → Summaries exist as INDEX-ONLY aids — they list entries for scanning but MUST NOT substitute for the full decision text. → Load only the specific decisions relevant to the task (typically 3-10 files).

   Ephemeral memory (sessions): → Prefer summaries if available (lower token cost).

4. For Decision Consistency Gate: → Scan the Decision Registry in index.md for ALL entries in the relevant domain → Load the specific

   DEC-{ID}.md

   files to check for conflicts → If uncertain about boundaries, also load decisions from adjacent domains

5. Freshness Check (Tier 2 files only)

   Pre-condition: verify that

   git

   is available on the PATH (

   git --version

   ). If

   git

   is unavailable, append the following note to the

   freshness_warnings

   section and skip the remainder of this step — proceed to Step 6 normally:

   Freshness check skipped: git not available

   For each file in the

   memory_context_bundle

   :

   a. If the file's frontmatter has no

   refresh_tier

   field, or

   refresh_tier

   ≠ 2 → skip (Tier 1 files are proactively refreshed via the post-delivery hook; Tier 3-4 are not checked at read time).

   b. If

   depends_on

   is absent or

   depends_on.code_paths

   is empty → skip (treat as Tier 4 — no check, no warning).

   c. If

   updated_at

   is absent or unparseable → append to

   freshness_warnings

   :

   Freshness check skipped: no valid updated_at — {file_path} Then skip this file.

   d. For each path in

   depends_on.code_paths

   :
   • If the path does not exist on disk, append to

     freshness_warnings

     :

     Freshness check skipped: {path} not found — depends_on may be stale Then skip this path.

   • Run:

     git log --oneline --since="{updated_at}" -- "{path}"

     (where

     {updated_at}

     is the file's frontmatter value, quoted exactly as-is).
   • Count the lines returned. If the count > 0, the file is

     POTENTIALLY_STALE

     for this path.

   e. If any path produced a non-zero commit count for this file, append one

   freshness_warnings

   entry per changed path in the format below (AC2):

   ⚠ FRESHNESS WARNING — {file_path}
     refresh_tier: 2
     updated_at: {date}
     changed_dependency: {code_path} ({N} commits since updated_at)
     action: verify content is still accurate before relying on it
   

   If no warnings are produced, the

   freshness_warnings

   section is omitted from the output (0 tokens).

6. Return

   memory_context_bundle

   — curated, minimal set of memory files relevant to the current task, plus any

   freshness_warnings

   produced in Step 5.

---

Output

memory_context_bundle

— curated set of memory files relevant to the current task, ready for

context-building

.

---

Quality Checks

• No full memory injection
• Context is focused on the task
• Agent loads only the specific DEC-{ID}.md files relevant to the task (typically 3-10)
• Summaries are NEVER substituted for durable memory (decisions, patterns, project)
• Decision Registry enables decision identification WITHOUT opening individual files
• Token budget: index (~1,500) + 3-10 individual decision files (~300 each) = ~4,500 tokens typical;

  freshness_warnings

  section adds ~100-200 tokens when Tier 2 staleness is detected, 0 tokens when all files are clean
• Only memory directly relevant to the task is included
• Freshness warnings are emitted for Tier 2 files with changed code dependencies — never silently suppressed.

---

Non-Goals

This skill must NOT:

• Load all memory files
• Decide what to do with retrieved memory
• Modify memory files
• Substitute summary one-liners for full decision text

Selective retrieval via progressive disclosure. Memory is never auto-loaded. Durable memory is never summarized away.