---
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-05
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.**