# Memory Architect

> memory-architect

- Skill: `q2wxec/memory-architect` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add q2wxec/memory-architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/q2wxec/memory-architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: q2wxec (https://skillmd.com/u/q2wxec)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/q2wxec/memory-architect

---


# memory-architect

Restructures memory files into the 3-layer architecture that Claude Code's `autoDream` service uses internally — designed to keep the always-loaded index small while making deeper knowledge accessible on demand.

## The 3-Layer Architecture

Claude Code's memory system (`services/autoDream/`) uses this structure:

```
MEMORY.md          ← Layer 1: Always loaded, pointer-only index (~200 lines max)
├── topic-file.md  ← Layer 2: Domain knowledge, loaded when relevant
├── another-topic.md
└── archive/       ← Layer 3: Historical context, rarely needed
    └── old-decisions.md
```

**Layer 1 — MEMORY.md index**: Loaded into every conversation. Must stay under ~200 lines (lines beyond 200 get truncated). Each entry is a one-line pointer: `- [Title](file.md) — one-line hook`. No content, just pointers. This is what Claude scans to decide what to load.

**Layer 2 — Topic files**: Contain the actual knowledge. Claude loads these on demand when their pointer appears relevant. Can be as long as needed. Each file has YAML frontmatter with `name`, `description`, and `type`.

**Layer 3 — Archive**: Old decisions, superseded approaches, historical context. Not referenced from MEMORY.md unless explicitly needed. Useful for debugging ("why did we do X two months ago?") but shouldn't pollute active context.

## Restructuring Process

### Step 1 — Audit what exists

Read `MEMORY.md` and all memory files in the same directory. Catalog:
- Total line count of MEMORY.md
- Which entries are pointer-only (good) vs. have inline content (needs extraction)
- Which topic files have grown unwieldy (>200 lines) and should be split
- Which entries are clearly stale, superseded, or contradicted

### Step 2 — Classify each entry

For each piece of content, decide its layer:

| Content type | Layer |
|---|---|
| Universal facts, always-relevant rules | L1 pointer → L2 file |
| Project-specific decisions, current constraints | L1 pointer → L2 file |
| Historical "why we did X" context | L3 archive |
| Superseded approaches | L3 archive or delete |
| Contradicted facts | Delete or correct |
| Step-by-step implementation details | Delete (code is the record) |

### Step 3 — Restructure

**For MEMORY.md:**
- Keep only pointer lines (one per memory file)
- Format: `- [Descriptive Title](filename.md) — one-line hook (what makes this relevant?)`
- Keep under 200 lines total
- Group related pointers with brief section headers if helpful (e.g., `## Architecture`, `## User preferences`)
- Remove entries for deleted/archived files

**For topic files:**
- Each file gets proper frontmatter:
  ```markdown
  ---
  name: <topic name>
  description: <one-line — used to judge relevance in future conversations>
  type: user | feedback | project | reference
  ---
  ```
- `feedback` type: lead with the rule, then `**Why:**` and `**How to apply:**` lines
- `project` type: lead with the fact/decision, then `**Why:**` and `**How to apply:**`
- Consolidate near-duplicate files (same topic, slightly different angles) into one
- Convert relative dates to absolute dates ("last week" → "2026-03-15")

**For archive:**
- Create `archive/` subdirectory if it doesn't exist
- Move genuinely historical content there
- Do NOT add archive files to MEMORY.md index (they're for reference, not proactive loading)

### Step 4 — Verify

After restructuring:
- MEMORY.md under 200 lines? 
- Every pointer in MEMORY.md points to an existing file?
- Every topic file has valid frontmatter?
- No content directly in MEMORY.md (only pointers)?
- No duplicate or near-duplicate topic files?

### Step 5 — Report

Tell the user:
- Before/after line count for MEMORY.md
- How many topic files created/merged/archived/deleted
- Any contradictions found and how resolved

## Common anti-patterns to fix

**Bloated index** — MEMORY.md has paragraphs of content instead of pointers. Extract to topic files.

**One giant file** — Everything dumped into a single `memories.md`. Split by topic.

**Missing frontmatter** — Topic files without `name`/`description`/`type`. Add it — the description is what helps Claude decide whether to load the file.

**Stale facts** — Memory says "using postgres 14" but codebase shows 16. Fix at source.

**Temporal decay** — "We decided last week to use X". Convert to absolute date; also verify if decision still stands.

**Archive in index** — Historical context cluttering MEMORY.md. Move to `archive/`.