Agent skill

Memory Engineering

by alirezarezvani in alirezarezvani/claude-skills

A skill your agent uses 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…

MITAuto-check passedAgent Workflows

Install Memory Engineering

skills CLI
$ npx skills add alirezarezvani/claude-skills --skill memory-engineering -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install alirezarezvani/claude-skills memory-engineering --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/alirezarezvani/claude-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/engineering/memory-engineering/skills/memory-engineering .claude/skills/memory-engineering && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
memory-engineering
GitHub stars
28k
Token cost
~1.7k tokens
SKILL.md length
617 words
Files
12 (incl. scripts, references, assets)
Skills in repo
342
Repo updated
First seen
Licence
MIT

At a glance

A skill your agent uses 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…

  • Works in 7 steps: Never quote accuracy without cost per… → Never return a "best" memory system —… → Never auto-merge contradictions. The… → …
  • Paying for an agent memory system — adding memory to an agent
  • SKILL.md covers What this does, The four lenses, Workflow and Hard rules, plus 3 more sections
  • Runs Python scripts from its folder; calls python

What it does

Memory Engineering is an agent skill from alirezarezvani/claude-skills. 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.

Its SKILL.md is about 1.7k tokens, which your agent loads only when the skill is triggered. The skill folder holds 14 other files, including scripts, reference files and assets (for example `assets/forgetting_policy_template.md`, `assets/memory_design_spec.example.json` and `assets/memory_engineer_worksheet.md`).

It sits in Agent Workflows, covering Agent memory and Agent instruction files. The repository describes itself as: 380 Claude Code skills & agent skills & plugins (30+ Agents, 70+ custom commands, 380+ skills, customizable references, scripts)for Claude Code, Codex, Gemini CLI, Cursor, and 8… The licence is MIT.

When your agent uses it

  • Paying for an agent memory system — adding memory to an agent
  • Choosing between long-context / RAG / graph / agentic memory
  • Auditing what a CLAUDE.md
  • Memory directory actually holds

Example prompts

  • “/memory-engineering”

Requirements

  • Python 3

Workflow steps

7 steps, taken from the first numbered list in SKILL.md.

  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.

What it can do on your machine

Read from SKILL.md and the folder at commit 19392f7. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 4 files in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • python

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • x.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Memory Engineering loads about 1.7k tokens when it runs, and up to ~9.5k if it reads all its reference files. Until then it costs about 125 tokens; SKILL.md has 617 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~125
When it runs · the whole SKILL.md, loaded when a task matches
~1.7k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~9.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from alirezarezvani/claude-skills at commit 19392f7, republished under its MIT licence (© alirezarezvani). 617 words, ~1,669 tokens.

Download SKILL.mdSave it as .claude/skills/memory-engineering/SKILL.md (or your agent's skills folder). This skill also uses 11 other files; get the full folder from GitHub.
name
memory-engineering
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.
argument-hint
[optional: path to a memory dir, design spec JSON, or a question]
license
MIT
metadata.version
1.0.0
metadata.build_pattern
Four-lens synthesis (Stanford / Microsoft / Anthropic / Nvidia) + 4 deterministic stdlib scripts, with a blocking forgetting gate
metadata.distinct_from
llm-wiki (maintains one specific markdown vault; this audits and prices any memory system); skillopt-sleep (runs a nightly consolidation loop; this decides…

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

LensQuestionThe finding that hurts
StanfordWhat does remembering cost?Construction energy exceeds total query energy across 300 queries. The tuned half is the smaller half.
MicrosoftWhat is worth keeping?More raw memory can make an agent worse. Keep facts and skills; drop the events.
AnthropicWho controls what it keeps?A wrong memory does not fail once — it persists into every future session that reads it.
NvidiaWhere 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.

Show full SKILL.md (287 more words)Show less

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

ScriptRoleExit codes
scripts/memory_cost_profiler.pyConstruction vs query split, cost per correct answer, amortization, co-location warning0 · 2 finding · 3 bad input
scripts/memory_architecture_picker.pyScores 4 families, disqualifies, names the cost, refuses to pick on a tie0 · 2 ambiguous · 3 bad input · 4 none viable
scripts/memory_density_auditor.pyFACT/SKILL/LOG/PROSE, duplicates, staleness, density (--dir or --jsonl)0 dense · 2 finding · 3 bad input
scripts/forgetting_policy_linter.pyThe gate: 8 checks, F1 and F4 blocking0 PASS · 2 CONDITIONAL · 4 FAIL

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

References and assets

Provenance

Framing from "How to be a Memory Engineer" by @N01ennn; 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.

© alirezarezvani, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 11 other files (scripts, references, assets) in engineering/memory-engineering/skills/memory-engineering of alirezarezvani/claude-skills.

  • SKILL.md
  • assets/forgetting_policy_template.md
  • assets/memory_design_spec.example.json
  • assets/memory_engineer_worksheet.md
  • references/forgetting_policy_design.md
  • references/memory_control_and_governance.md
  • references/memory_cost_canon.md
  • references/what_to_keep.md
  • scripts/forgetting_policy_linter.py
  • scripts/memory_architecture_picker.py
  • scripts/memory_cost_profiler.py
  • scripts/memory_density_auditor.py

Open the folder on GitHubat commit 19392f7

Compare with similar skills

Memory Engineering next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Memory Engineering compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Memory Engineering this skillalirezarezvani/claude-skills28k—~1.7kAutomated safety check: PassMIT
Neat-Freak Knowledge CloseoutKKKKhazix/khazix-skills21k—~1.9kAutomated safety check: PassMIT
SkillOpt Sleep Cyclemicrosoft/SkillOpt18k—~2.3kAutomated safety check: PassMIT
CLAUDE.md Improveranthropics/claude-plugins-official38k5 repos~1.5kAutomated safety check: PassApache-2.0
Harness Engineering10xChengTu/harness-engineering1021 repos~1kAutomated safety check: PassNone
Codebase Analyzerseverity1/claude-code-auto-memory159—~1.5kAutomated safety check: PassMIT

Similar skills

  • Neat-Freak Knowledge Closeout

    KKKKhazix/khazix-skills

    Brings project docs, agent rule files, authorized memory and leftover workspace files back in line with what the code and runtime actually do at the end of a work session.

    21k GitHub stars~1.9k tokensUpdated 7 days ago
    Agent WorkflowsAuto-check passed
  • SkillOpt Sleep Cycle

    microsoft/SkillOpt

    Official

    Runs an on-demand or nightly sleep cycle that reviews past Claude Code sessions and proposes validated updates to CLAUDE.md and skills.

    18k GitHub stars~2.3k tokensUpdated 2 days ago
    Agent WorkflowsAuto-check passed
  • CLAUDE.md Improver

    anthropics/claude-plugins-official

    Official

    Finds every CLAUDE.md file in a repository, scores each against quality criteria, shows a report, then makes targeted updates after you approve.

    38k GitHub starsUsed in 5 repos~1.5k tokens
    Agent WorkflowsAuto-check passed
  • Harness Engineering

    10xChengTu/harness-engineering

    Set up and improve harness engineering (AGENTS.md, docs/, lint rules, eval systems, project-level prompt engineering) for AI-agent-friendly codebases.

    102 GitHub starsUsed in 1 repo~1k tokens
    Agent WorkflowsAuto-check passed
  • Codebase Analyzer

    severity1/claude-code-auto-memory

    This skill should be used when the user asks to "initialize auto-memory", "create CLAUDE.md", "set up project memory", or runs the /auto-memory:init command.

    159 GitHub stars~1.5k tokensUpdated 5 mo ago
    Agent WorkflowsAuto-check passed
  • Self Improving For Codex

    GODGOD126/self-improving-for-codex

    Build or maintain a Codex-native self-improving memory loop using global AGENTS.md, a persistent memories directory, and optional nightly refinement automation.

    130 GitHub stars~1.2k tokensUpdated 1 mo ago
    Agent WorkflowsAuto-check passed

More from alirezarezvani/claude-skills

All 342 skills in this repo
  • Agile Product Owner

    alirezarezvani/claude-skills

    Writes INVEST-checked user stories with acceptance criteria, splits epics, plans sprints from velocity and ranks the backlog with a weighted score.

    28k GitHub starsUsed in 3 repos~3.2k tokens
    Auto-check passed
  • Product Strategist

    alirezarezvani/claude-skills

    OKR cascade toolkit for product leaders: generates aligned company-to-team OKRs from five strategy types and scores how well they line up.

    28k GitHub starsUsed in 2 repos~1.8k tokens
    Auto-check passed
  • App Store Optimization

    alirezarezvani/claude-skills

    App Store Optimization (ASO) toolkit for researching keywords, analyzing competitor rankings, generating metadata suggestions, and improving app visibility on Apple App Store and Google Play Store.

    28k GitHub starsUsed in 1 repo~4.2k tokens
    Auto-check passed
  • AWS Solution Architect

    alirezarezvani/claude-skills

    Design AWS architectures for startups using serverless patterns and IaC templates.

    28k GitHub starsUsed in 1 repo~2.5k tokens
    Auto-check passed
  • Campaign Analytics

    alirezarezvani/claude-skills

    Calculates attribution, funnel and ROI figures for marketing campaigns with three Python scripts that need only the standard library.

    28k GitHub starsUsed in 1 repo~2.1k tokens
    Auto-check passed
  • Code to PRD

    alirezarezvani/claude-skills

    Reverse-engineers a frontend, backend or fullstack codebase into a product requirements document with per-page docs, an enum dictionary and an API inventory.

    28k GitHub starsUsed in 1 repo~4.9k tokens
    Auto-check passed

Categories

Questions about Memory Engineering

What does Memory Engineering do?

A skill your agent uses 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…. Memory Engineering is an agent skill from alirezarezvani/claude-skills.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.

When should I use Memory Engineering?

Memory Engineering fits situations like: paying for an agent memory system — adding memory to an agent; choosing between long-context / RAG / graph / agentic memory; auditing what a CLAUDE.md; memory directory actually holds.

How do I install Memory Engineering in Claude Code?

Run `npx skills add alirezarezvani/claude-skills --skill memory-engineering -a claude-code`. Or copy the skill folder (engineering/memory-engineering/skills/memory-engineering in alirezarezvani/claude-skills) into .claude/skills/memory-engineering in your project. Claude Code loads it when a task matches its description.

How do I install Memory Engineering in Codex?

Run `npx skills add alirezarezvani/claude-skills --skill memory-engineering -a codex`. Or copy the skill folder (engineering/memory-engineering/skills/memory-engineering in alirezarezvani/claude-skills) into .agents/skills/memory-engineering in your project. Codex loads it when a task matches its description.

Can I use Memory Engineering in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add alirezarezvani/claude-skills --skill memory-engineering -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/memory-engineering, .gemini/skills/memory-engineering, .github/skills/memory-engineering and .opencode/skills/memory-engineering in your project.

What does Memory Engineering need to run?

Going by SKILL.md and its folder, Memory Engineering needs Python for the scripts in its folder and the command-line tools its instructions call (python). Our summary lists: Python 3.

Does Memory Engineering access the network?

SKILL.md names 1 domain. As links in the text: x.com. This is read from the text; nothing was executed.

Is Memory Engineering safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Memory Engineering use?

Memory Engineering is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Memory Engineering use?

About 1.7k tokens (SKILL.md is roughly 6.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 7.8k tokens, read only when the agent opens those files.

What are the alternatives to Memory Engineering?

Skills that share tags, products or a category with Memory Engineering: Neat-Freak Knowledge Closeout (KKKKhazix/khazix-skills, 21k stars), SkillOpt Sleep Cycle (microsoft/SkillOpt, 18k stars), CLAUDE.md Improver (anthropics/claude-plugins-official, 38k stars) and Harness Engineering (10xChengTu/harness-engineering, 102 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Memory Engineering?

alirezarezvani (a GitHub user) maintains it in alirezarezvani/claude-skills, which has 27,829 GitHub stars. The repository holds 342 skills in this directory. The repository was last updated on August 30, 2026.

Source: alirezarezvani/claude-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.