memory-retrieve

name	memory-retrieve
description	Load only the minimum relevant memory for a task using 3-level progressive disclosure. Activate before context-building — never load full memory dumps. Never substitute summaries for durable memory.
license	ELv2
compatibility	Works with any filesystem-based AI coding agent
metadata	{"author":"gaai-framework","version":"2.2","category":"cross","track":"cross-cutting","id":"SKILL-MEMORY-RETRIEVE-001","updated_at":"2026-04-05T00:00:00.000Z","status":"stable"}
inputs	["contexts/memory/index.md (registry — always read first, contains Decision Registry + file map)","contexts/memory/** (any category registered in index.md — resolved at runtime)"]
outputs	["memory_context_bundle"]

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.