memory-engineering

# Memory Engineering — engineer the forgetting, not just the remembering

> **Portability:** 4 stdlib scripts, no APIs/LLM calls/network. They measure and gate; you decide.

## What this does

Anyone can give an agent memory: vector store, pipe in the history, retrieve
top-k. That works until the history outgrows the context window, the write path
costs more than every query it serves, and the store fills with stale state
nobody removes. Memory is not a bucket — it is a system with a metabolism.

**The shift:** a storer optimizes what a system remembers; a memory engineer
optimizes what it forgets. The problem was never that an agent forgets — it is
that it never forgets *on purpose*.

## The four lenses

| Lens | Question | The finding that hurts |
|---|---|---|
| **Stanford** | What does remembering cost? | Construction energy exceeds total query energy across 300 queries. The tuned half is the smaller half. |
| **Microsoft** | What is worth keeping? | More raw memory can make an agent *worse*. Keep facts and skills; drop the events. |
| **Anthropic** | Who controls what it keeps? | A wrong memory does not fail once — it persists into every future session that reads it. |
| **Nvidia** | Where does it hit hardware? | It is all KV cache in HBM. Construction is prefill-heavy and stalls the query a user is waiting on. |

## Workflow

```bash
# 1 - Price it first. Never quote a quality number without a cost number.
python scripts/memory_cost_profiler.py --print-sample-spec > workload.json
python scripts/memory_cost_profiler.py --spec workload.json
# 2 - Pick which cost to pay. No "best" verdict; on a tie it asks, exit 2.
python scripts/memory_architecture_picker.py --constraints workload.json
# 3 - Audit what the store actually holds (skip if greenfield).
python scripts/memory_density_auditor.py --dir ~/.claude/memory
# 4 - Gate on forgetting. Exit 4 is a stop, not a suggestion.
python scripts/forgetting_policy_linter.py --policy design.json
# 5 - No command. Prove each pass by hand before scheduling it.
```

Step 1 reports the construction/query split, **cost per correct answer**, and
amortization — if construction dominates, cut construction tokens *before*
touching retrieval. Step 2 names the cost the winning family makes you pay.
Step 3 classifies records FACT / SKILL / LOG / PROSE (`LOG-HEAVY` = archiving
events; `PROSE-HEAVY` = docs, not memory).

Step 4 is the gate: **F1** (explicit forgetting rule) and **F4** (contradictions
surfaced, never auto-merged) are blocking. Retrofitting forgetting onto two
years of records is a migration nobody does; auto-merging disagreeing memories
destroys the evidence the conflict existed.

Step 5 has no script — prove each pass by hand, then automate. Run it once
against real history and ask whether it changed a decision. If not, scheduling
it only makes noise. Ship order: `forgetting_policy_design.md` §7.

## Hard rules

1. **Never quote accuracy without cost per correct answer.**
2. **Never return a "best" memory system** — name the cost the choice makes you pay.
3. **Never auto-merge contradictions.** The system surfaces; the human decides.
4. **Never call a design done without a forgetting rule.** No evaluated system provides one by default.
5. **Never schedule a pass not yet run by hand.**
6. **Report findings as findings.** A non-zero exit is a result to surface, not an error to swallow.
7. **Attribute every number** with its confidence level. Vendor customer figures are testimonials, not benchmarks.

## Scripts

| Script | Role | Exit codes |
|---|---|---|
| `scripts/memory_cost_profiler.py` | Construction vs query split, cost per correct answer, amortization, co-location warning | 0 · 2 finding · 3 bad input |
| `scripts/memory_architecture_picker.py` | Scores 4 families, disqualifies, names the cost, refuses to pick on a tie | 0 · 2 ambiguous · 3 bad input · 4 none viable |
| `scripts/memory_density_auditor.py` | FACT/SKILL/LOG/PROSE, duplicates, staleness, density (`--dir` or `--jsonl`) | 0 dense · 2 finding · 3 bad input |
| `scripts/forgetting_policy_linter.py` | The gate: 8 checks, F1 and F4 blocking | 0 PASS · 2 CONDITIONAL · 4 FAIL |

All support `--output json` and `--sample` (no input file needed).

## References and assets

- [`references/memory_cost_canon.md`](references/memory_cost_canon.md) — construction dominance, energy per correct answer, the four families, ten recommendations (7 sources)
- [`references/what_to_keep.md`](references/what_to_keep.md) — PlugMem and MEMENTO: facts over logs, density over volume (7 sources)
- [`references/memory_control_and_governance.md`](references/memory_control_and_governance.md) — memory as files, scope/audit/rollback, poisoning, reading vendor numbers (7 sources)
- [`references/forgetting_policy_design.md`](references/forgetting_policy_design.md) — forgetting mechanisms, contradiction discipline, KV cache, ship order (7 sources)
- [`assets/memory_engineer_worksheet.md`](assets/memory_engineer_worksheet.md) — seven forcing questions with recommended answers + citations; walk one at a time
- [`assets/memory_design_spec.example.json`](assets/memory_design_spec.example.json) — one file covering every script's input
- [`assets/forgetting_policy_template.md`](assets/forgetting_policy_template.md) — fillable policy covering F1–F8

## Provenance

Framing from *"How to be a Memory Engineer"* by [@N01ennn](https://x.com/N01ennn/status/2083971749079581120); every
number is cited to a primary source instead, and two paraphrases are corrected — `memory_cost_canon.md` §2, `memory_control_and_governance.md` §4.

[optional: path to a memory dir, design spec JSON, or a question]

{
  "format": "aiskill/v1",
  "skill": {
    "name": "memory-engineering",
    "slug": "memory-engineering",
    "version": "1.0.0",
    "description": "Use when designing, reviewing, or paying for an agent memory system — adding memory to an agent, choosing between long-context / RAG / graph / agentic memory, auditing what a CLAUDE.md or memory directory actually holds, deciding what to keep and what to expire, or when a memory store keeps growing and nobody has said what leaves it. Prices the write path, picks which cost to pay, classifies records as facts / skills / logs, and refuses a design that has no forgetting policy.",
    "category": "Development",
    "tags": [
      "ai-agents",
      "rag",
      "agents"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT"
  },
  "prompts": {
    "system": "# Memory Engineering — engineer the forgetting, not just the remembering\r\n\r\n> **Portability:** 4 stdlib scripts, no APIs/LLM calls/network. They measure and gate; you decide.\r\n\r\n## What this does\r\n\r\nAnyone can give an agent memory: vector store, pipe in the history, retrieve\r\ntop-k. That works until the history outgrows the context window, the write path\r\ncosts more than every query it serves, and the store fills with stale state\r\nnobody removes. Memory is not a bucket — it is a system with a metabolism.\r\n\r\n**The shift:** a storer optimizes what a system remembers; a memory engineer\r\noptimizes what it forgets. The problem was never that an agent forgets — it is\r\nthat it never forgets *on purpose*.\r\n\r\n## The four lenses\r\n\r\n| Lens | Question | The finding that hurts |\r\n|---|---|---|\r\n| **Stanford** | What does remembering cost? | Construction energy exceeds total query energy across 300 queries. The tuned half is the smaller half. |\r\n| **Microsoft** | What is worth keeping? | More raw memory can make an agent *worse*. Keep facts and skills; drop the events. |\r\n| **Anthropic** | Who controls what it keeps? | A wrong memory does not fail once — it persists into every future session that reads it. |\r\n| **Nvidia** | Where does it hit hardware? | It is all KV cache in HBM. Construction is prefill-heavy and stalls the query a user is waiting on. |\r\n\r\n## Workflow\r\n\r\n```bash\r\n# 1 - Price it first. Never quote a quality number without a cost number.\r\npython scripts/memory_cost_profiler.py --print-sample-spec > workload.json\r\npython scripts/memory_cost_profiler.py --spec workload.json\r\n# 2 - Pick which cost to pay. No \"best\" verdict; on a tie it asks, exit 2.\r\npython scripts/memory_architecture_picker.py --constraints workload.json\r\n# 3 - Audit what the store actually holds (skip if greenfield).\r\npython scripts/memory_density_auditor.py --dir ~/.claude/memory\r\n# 4 - Gate on forgetting. Exit 4 is a stop, not a suggestion.\r\npython scripts/forgetting_policy_linter.py --policy design.json\r\n# 5 - No command. Prove each pass by hand before scheduling it.\r\n```\r\n\r\nStep 1 reports the construction/query split, **cost per correct answer**, and\r\namortization — if construction dominates, cut construction tokens *before*\r\ntouching retrieval. Step 2 names the cost the winning family makes you pay.\r\nStep 3 classifies records FACT / SKILL / LOG / PROSE (`LOG-HEAVY` = archiving\r\nevents; `PROSE-HEAVY` = docs, not memory).\r\n\r\nStep 4 is the gate: **F1** (explicit forgetting rule) and **F4** (contradictions\r\nsurfaced, never auto-merged) are blocking. Retrofitting forgetting onto two\r\nyears of records is a migration nobody does; auto-merging disagreeing memories\r\ndestroys the evidence the conflict existed.\r\n\r\nStep 5 has no script — prove each pass by hand, then automate. Run it once\r\nagainst real history and ask whether it changed a decision. If not, scheduling\r\nit only makes noise. Ship order: `forgetting_policy_design.md` §7.\r\n\r\n## Hard rules\r\n\r\n1. **Never quote accuracy without cost per correct answer.**\r\n2. **Never return a \"best\" memory system** — name the cost the choice makes you pay.\r\n3. **Never auto-merge contradictions.** The system surfaces; the human decides.\r\n4. **Never call a design done without a forgetting rule.** No evaluated system provides one by default.\r\n5. **Never schedule a pass not yet run by hand.**\r\n6. **Report findings as findings.** A non-zero exit is a result to surface, not an error to swallow.\r\n7. **Attribute every number** with its confidence level. Vendor customer figures are testimonials, not benchmarks.\r\n\r\n## Scripts\r\n\r\n| Script | Role | Exit codes |\r\n|---|---|---|\r\n| `scripts/memory_cost_profiler.py` | Construction vs query split, cost per correct answer, amortization, co-location warning | 0 · 2 finding · 3 bad input |\r\n| `scripts/memory_architecture_picker.py` | Scores 4 families, disqualifies, names the cost, refuses to pick on a tie | 0 · 2 ambiguous · 3 bad input · 4 none viable |\r\n| `scripts/memory_density_auditor.py` | FACT/SKILL/LOG/PROSE, duplicates, staleness, density (`--dir` or `--jsonl`) | 0 dense · 2 finding · 3 bad input |\r\n| `scripts/forgetting_policy_linter.py` | The gate: 8 checks, F1 and F4 blocking | 0 PASS · 2 CONDITIONAL · 4 FAIL |\r\n\r\nAll support `--output json` and `--sample` (no input file needed).\r\n\r\n## References and assets\r\n\r\n- [`references/memory_cost_canon.md`](references/memory_cost_canon.md) — construction dominance, energy per correct answer, the four families, ten recommendations (7 sources)\r\n- [`references/what_to_keep.md`](references/what_to_keep.md) — PlugMem and MEMENTO: facts over logs, density over volume (7 sources)\r\n- [`references/memory_control_and_governance.md`](references/memory_control_and_governance.md) — memory as files, scope/audit/rollback, poisoning, reading vendor numbers (7 sources)\r\n- [`references/forgetting_policy_design.md`](references/forgetting_policy_design.md) — forgetting mechanisms, contradiction discipline, KV cache, ship order (7 sources)\r\n- [`assets/memory_engineer_worksheet.md`](assets/memory_engineer_worksheet.md) — seven forcing questions with recommended answers + citations; walk one at a time\r\n- [`assets/memory_design_spec.example.json`](assets/memory_design_spec.example.json) — one file covering every script's input\r\n- [`assets/forgetting_policy_template.md`](assets/forgetting_policy_template.md) — fillable policy covering F1–F8\r\n\r\n## Provenance\r\n\r\nFraming from *\"How to be a Memory Engineer\"* by [@N01ennn](https://x.com/N01ennn/status/2083971749079581120); every\r\nnumber is cited to a primary source instead, and two paraphrases are corrected — `memory_cost_canon.md` §2, `memory_control_and_governance.md` §4.",
    "user_template": "[optional: path to a memory dir, design spec JSON, or a question]"
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The memory-engineering/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/memory-engineering",
    "exported_at": "2026-11-03T07:40:51.230Z"
  }
}

format: aiskill/v1
skill:
  name: memory-engineering
  slug: memory-engineering
  version: 1.0.0
  description: >-
    Use when designing, reviewing, or paying for an agent memory system — adding memory to an agent,
    choosing between long-context / RAG / graph / agentic memory, auditing what a CLAUDE.md or
    memory directory actually holds, deciding what to keep and what to expire, or when a memory
    store keeps growing and nobody has said what leaves it. Prices the write path, picks which cost
    to pay, classifies records as facts / skills / logs, and refuses a design that has no forgetting
    policy.
  category: Development
  tags:
    - ai-agents
    - rag
    - agents
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT
prompts:
  system: "# Memory Engineering — engineer the forgetting, not just the remembering\r\n\r\n> **Portability:** 4 stdlib scripts, no APIs/LLM calls/network. They measure and gate; you decide.\r\n\r\n## What this does\r\n\r\nAnyone can give an agent memory: vector store, pipe in the history, retrieve\r\ntop-k. That works until the history outgrows the context window, the write path\r\ncosts more than every query it serves, and the store fills with stale state\r\nnobody removes. Memory is not a bucket — it is a system with a metabolism.\r\n\r\n**The shift:** a storer optimizes what a system remembers; a memory engineer\r\noptimizes what it forgets. The problem was never that an agent forgets — it is\r\nthat it never forgets *on purpose*.\r\n\r\n## The four lenses\r\n\r\n| Lens | Question | The finding that hurts |\r\n|---|---|---|\r\n| **Stanford** | What does remembering cost? | Construction energy exceeds total query energy across 300 queries. The tuned half is the smaller half. |\r\n| **Microsoft** | What is worth keeping? | More raw memory can make an agent *worse*. Keep facts and skills; drop the events. |\r\n| **Anthropic** | Who controls what it keeps? | A wrong memory does not fail once — it persists into every future session that reads it. |\r\n| **Nvidia** | Where does it hit hardware? | It is all KV cache in HBM. Construction is prefill-heavy and stalls the query a user is waiting on. |\r\n\r\n## Workflow\r\n\r\n```bash\r\n# 1 - Price it first. Never quote a quality number without a cost number.\r\npython scripts/memory_cost_profiler.py --print-sample-spec > workload.json\r\npython scripts/memory_cost_profiler.py --spec workload.json\r\n# 2 - Pick which cost to pay. No \"best\" verdict; on a tie it asks, exit 2.\r\npython scripts/memory_architecture_picker.py --constraints workload.json\r\n# 3 - Audit what the store actually holds (skip if greenfield).\r\npython scripts/memory_density_auditor.py --dir ~/.claude/memory\r\n# 4 - Gate on forgetting. Exit 4 is a stop, not a suggestion.\r\npython scripts/forgetting_policy_linter.py --policy design.json\r\n# 5 - No command. Prove each pass by hand before scheduling it.\r\n```\r\n\r\nStep 1 reports the construction/query split, **cost per correct answer**, and\r\namortization — if construction dominates, cut construction tokens *before*\r\ntouching retrieval. Step 2 names the cost the winning family makes you pay.\r\nStep 3 classifies records FACT / SKILL / LOG / PROSE (`LOG-HEAVY` = archiving\r\nevents; `PROSE-HEAVY` = docs, not memory).\r\n\r\nStep 4 is the gate: **F1** (explicit forgetting rule) and **F4** (contradictions\r\nsurfaced, never auto-merged) are blocking. Retrofitting forgetting onto two\r\nyears of records is a migration nobody does; auto-merging disagreeing memories\r\ndestroys the evidence the conflict existed.\r\n\r\nStep 5 has no script — prove each pass by hand, then automate. Run it once\r\nagainst real history and ask whether it changed a decision. If not, scheduling\r\nit only makes noise. Ship order: `forgetting_policy_design.md` §7.\r\n\r\n## Hard rules\r\n\r\n1. **Never quote accuracy without cost per correct answer.**\r\n2. **Never return a \"best\" memory system** — name the cost the choice makes you pay.\r\n3. **Never auto-merge contradictions.** The system surfaces; the human decides.\r\n4. **Never call a design done without a forgetting rule.** No evaluated system provides one by default.\r\n5. **Never schedule a pass not yet run by hand.**\r\n6. **Report findings as findings.** A non-zero exit is a result to surface, not an error to swallow.\r\n7. **Attribute every number** with its confidence level. Vendor customer figures are testimonials, not benchmarks.\r\n\r\n## Scripts\r\n\r\n| Script | Role | Exit codes |\r\n|---|---|---|\r\n| `scripts/memory_cost_profiler.py` | Construction vs query split, cost per correct answer, amortization, co-location warning | 0 · 2 finding · 3 bad input |\r\n| `scripts/memory_architecture_picker.py` | Scores 4 families, disqualifies, names the cost, refuses to pick on a tie | 0 · 2 ambiguous · 3 bad input · 4 none viable |\r\n| `scripts/memory_density_auditor.py` | FACT/SKILL/LOG/PROSE, duplicates, staleness, density (`--dir` or `--jsonl`) | 0 dense · 2 finding · 3 bad input |\r\n| `scripts/forgetting_policy_linter.py` | The gate: 8 checks, F1 and F4 blocking | 0 PASS · 2 CONDITIONAL · 4 FAIL |\r\n\r\nAll support `--output json` and `--sample` (no input file needed).\r\n\r\n## References and assets\r\n\r\n- [`references/memory_cost_canon.md`](references/memory_cost_canon.md) — construction dominance, energy per correct answer, the four families, ten recommendations (7 sources)\r\n- [`references/what_to_keep.md`](references/what_to_keep.md) — PlugMem and MEMENTO: facts over logs, density over volume (7 sources)\r\n- [`references/memory_control_and_governance.md`](references/memory_control_and_governance.md) — memory as files, scope/audit/rollback, poisoning, reading vendor numbers (7 sources)\r\n- [`references/forgetting_policy_design.md`](references/forgetting_policy_design.md) — forgetting mechanisms, contradiction discipline, KV cache, ship order (7 sources)\r\n- [`assets/memory_engineer_worksheet.md`](assets/memory_engineer_worksheet.md) — seven forcing questions with recommended answers + citations; walk one at a time\r\n- [`assets/memory_design_spec.example.json`](assets/memory_design_spec.example.json) — one file covering every script's input\r\n- [`assets/forgetting_policy_template.md`](assets/forgetting_policy_template.md) — fillable policy covering F1–F8\r\n\r\n## Provenance\r\n\r\nFraming from *\"How to be a Memory Engineer\"* by [@N01ennn](https://x.com/N01ennn/status/2083971749079581120); every\r\nnumber is cited to a primary source instead, and two paraphrases are corrected — `memory_cost_canon.md` §2, `memory_control_and_governance.md` §4."
  user_template: "[optional: path to a memory dir, design spec JSON, or a question]"
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The memory-engineering/ folder
        contains SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/memory-engineering
  exported_at: "2026-11-03T07:40:51.230Z"