# 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\", \"M…

- **Type:** Skill
- **Install:** `agentstack add skill-simbajigege-book2skills-agent-memory-implementation`
- **Verified:** Pending review
- **Seller:** [simbajigege](https://agentstack.voostack.com/s/simbajigege)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [simbajigege](https://github.com/simbajigege)
- **Source:** https://github.com/simbajigege/book2skills/tree/main/skills/agent-memory-implementation
- **Website:** https://book2skills.com/

## Install

```sh
agentstack add skill-simbajigege-book2skills-agent-memory-implementation
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

1. Receives the last N user/assistant messages as context
2. Scans the memory directory for existing files (reads only frontmatter — the `description` field is the primary signal)
3. Decides what is worth saving from this conversation
4. Writes or updates `.md` files inside the memory directory, then updates `MEMORY.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: 
  description: 
  type: user | feedback | project | reference
  ---

Step 2 — add one pointer line to MEMORY.md:
  - [Title](file.md) — one-line hook
```

### Implications for restructuring

- **`description` is 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 that just says "misc notes" wastes the slot.

## Memory Type Definitions

Read [`references/memory-type-definitions.md`](references/memory-type-definitions.md) for the verbatim XML from `memdir/memoryTypes.ts` — the four type specs (`user`, `feedback`, `project`, `reference`) and the exclusion list. Load it when deciding what to extract from a conversation and which type to assign to each memory.

---

## 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 | Condense into relevant L2 file or delete |
| Superseded approaches | Delete |
| Contradicted facts | Delete or correct at source |
| 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 files

**For topic files:**
- Each file gets proper frontmatter:
  ```markdown
  ---
  name: 
  description: 
  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")

### 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/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.

**Historical context in index** — Old decisions or "why we did X" cluttering MEMORY.md. Either condense the rationale into the relevant topic file's `**Why:**` line, or delete if no longer relevant.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [simbajigege](https://github.com/simbajigege)
- **Source:** [simbajigege/book2skills](https://github.com/simbajigege/book2skills)
- **License:** MIT
- **Homepage:** https://book2skills.com/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-simbajigege-book2skills-agent-memory-implementation
- Seller: https://agentstack.voostack.com/s/simbajigege
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.