agent-memory-implementation
Restructures a chaotic or overgrown MEMORY.md into a clean 2-layer architecture based on how Claude Code's autoDream system organizes memory — a lightweight pointer index (always loaded) and topic files (loaded on demand). Stale or superseded memories are deleted or corrected in place — not archived. Use this skill whenever the user says \"clean up MEMORY.md\", \"reorganize my memory files\", \"MEMORY.md is getting too long\", \"fix my memory structure\", or when you observe that MEMORY.md exceeds 200 lines, contains full paragraphs instead of pointers, or mixes index entries with topic content.
simbajigege · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add simbajigege/book2skills --skill agent-memory-implementation技能说明
name: agent-memory-implementation description: "Restructures a chaotic or overgrown MEMORY.md into a clean 2-layer architecture based on how Claude Code's autoDream system organizes memory — a lightweight pointer index (always loaded) and topic files (loaded on demand). Stale or superseded memories are deleted or corrected in place — not archived. Use this skill whenever the user says "clean up MEMORY.md", "reorganize my memory files", "MEMORY.md is getting too long", "fix my memory structure", or when you observe that MEMORY.md exceeds 200 lines, contains full paragraphs instead of pointers, or mixes index entries with topic content." license: "Skill implementation guide for personal/educational use."
memory-architect
Restructures memory files into the 2-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 2-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
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.
No archive layer: The autoDream system does not maintain an archive directory. Stale, superseded, or contradicted memories are deleted or corrected in place (see consolidationPrompt.ts Phase 3–4). The memory directory is always the current truth, not a history log.
How Claude Code Writes Memories Automatically
Understanding the auto-extraction pipeline helps you restructure files in a way that works with the system rather than against it.
The extraction forked agent
At the end of every query loop (when the model returns a final response with no pending tool calls), Claude Code fires a forked agent in the background via executeExtractMemories() in services/extractMemories/extractMemories.ts. This agent:
- Receives the last N user/assistant messages as context
- Scans the memory directory for existing files (reads only frontmatter — the
descriptionfield is the primary signal) - Decides what is worth saving from this conversation
- Writes or updates
.mdfiles inside the memory directory, then updatesMEMORY.md
The fork shares the parent conversation's prompt cache (same tool list, same system prompt prefix, same cache key), so the extra token cost is near zero.
Mutual exclusion: if the main agent already wrote to the memory directory during the conversation (e.g., the user said "remember this"), the forked agent detects that and skips — no double-writes.
Turn budget: hard cap of 5 turns. The agent is instructed to batch all reads in turn 1 and all writes in turn 2 — no interleaving.
The extraction agent's prompt (reference: services/extractMemories/prompts.ts)
The prompt is assembled by buildExtractAutoOnlyPrompt() in four parts:
Part 1 — Role + tool constraints + efficiency strategy (hardcoded)
You are now acting as the memory extraction subagent.
Analyze the most recent ~{N} messages above and use them to update
your persistent memory systems.
Available tools: Read, Grep, Glob, read-only Bash (ls/find/cat/stat/
wc/head/tail), and Edit/Write for paths inside the memory directory
only. Bash rm is not permitted.
Turn budget strategy:
turn 1 — issue all Read calls in parallel for every file you might update
turn 2 — issue all Write/Edit calls in parallel
You MUST only use content from the last ~{N} messages.
Do not grep source files, read code to confirm patterns, or run git commands.
Part 2 — Existing memory manifest (injected dynamically)
## Existing memory files
- [feedback] feedback_testing.md: no DB mocks in integration tests
- [user] user_role.md: user is a PM learning the codebase
- ...
Check this list before writing — update an existing file rather than
creating a duplicate.
Generated by scanMemoryFiles() scanning each file's frontmatter. The description field in your frontmatter is this manifest line — if it's vague, the agent can't tell whether to update the file or create a new one.
Part 3 — Four memory types + What NOT to save (shared with system prompt)
Uses the same constants (TYPES_SECTION_INDIVIDUAL, WHAT_NOT_TO_SAVE_SECTION) from memdir/memoryTypes.ts that appear in the main agent's system prompt. One source of truth — the extraction agent uses the same criteria the main agent uses.
Part 4 — How to save (two-step write spec)
Step 1 — write topic file with frontmatter:
---
name: <slug>
description: <one-line summary — used for relevance matching>
type: user | feedback | project | reference
---
Step 2 — add one pointer line to MEMORY.md:
- [Title](file.md) — one-line hook
Implications for restructuring
descriptionis load-bearing — it's what both the extraction agent (dedup check) and the relevance scorer (read-time selection) use. A vague description like "notes" means neither can work correctly. Make it specific enough to answer "would this be relevant if the user asked about X?"- frontmatter type drives filing — the extraction agent uses the type taxonomy to decide which criteria apply. A file with the wrong type (or no type) will be handled incorrectly on future updates.
- MEMORY.md pointer hooks matter — the hook text after
—is what Claude reads to decide whether to load the full file. A hook t