Skip to main content
Agent skill

Maintaining Core Memory

Maintains an agent's core memory, the editable part of its system prompt. Use to modify the agent's core behavior, embed critical knowledge (needed on every turn), or instruct the agent on how to use deferred memory.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Maintaining Core Memory when an AI agent needs a reusable SKILL.md workflow for this job: Maintains an agent's core memory, the editable part of its system prompt. Use to modify the agent's core behavior, embed critical knowledge (needed on every turn), or instruct the agent on how to use deferred memory.

When not to use it

Skip Maintaining Core Memory when the task is outside the writing category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/maintaining-core-memory
# Save SKILL.md to ~/.claude/skills/maintaining-core-memory/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/maintaining-core-memory/SKILL.md. For a shared project, commit the folder at .claude/skills/maintaining-core-memory/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Maintaining Core Memory skill for this task: Use Maintaining Core Memory when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • chatgptinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • geminiinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • copilotinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • llamainferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • perplexityinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • mistralinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • grokinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

Core memory is the agent's prompt, refined over its lifetime. Treat each change as a revision of that prompt, not an append to a log: the usual edit sharpens, merges, or replaces an existing principle, and a new one earns its place only when no existing one can absorb it.

## Prompt format

The agent's system prompt is compiled from the Markdown files at the root of `$MEMORY_DIR`. Each root file except `MEMORY.md` becomes a block named after the file, in alphabetical order by filename, followed by the root `MEMORY.md`:

``` {{base system prompt}}

<human> <description>{{description from human.md frontmatter}}</description> {{body of human.md}} </human>

<persona> <description>{{description from persona.md frontmatter}}</description> {{body of persona.md}} </persona>

<memory> {{body of root MEMORY.md}} <deferred-memory> <directory path="{{dir}}/" index="{{dir}}/MEMORY.md" /> </deferred-memory> </memory> ```

Every root file except `MEMORY.md` starts with frontmatter containing exactly two fields:

```markdown --- name: human description: Who the user is and how they want to work together. --- ```

- The file name becomes the block name, so `human.md` renders as `<human>`. Choose short, stable names. - The `description` is rendered into the prompt. Write it for the agent: one line saying what the block holds. - Root `MEMORY.md` has no frontmatter. Its body is the only part of `<memory>` you write. - The `<deferred-memory>` list is generated: one entry per top-level directory that has its own `MEMORY.md`, showing only the path. `skills/` is never listed; skills appear separately. - Edits take effect only after they are committed, and only in later system prompts. The current conversation keeps the prompt it started with.

Read `$MEMORY_DIR/.memfs.config.json` if it exists. The memory repository's pre-commit hook enforces it:

- `maxCoreMemoryCharacters` caps the total size of all root Markdown (default 65,536 characters). - `maxFileCharacters` caps each memory file, frontmatter included (default 20,000 characters). `fileCharacterLimits` overrides it per glob; the first match wins and `null` removes the cap. - `readOnlyFiles` lists globs whose files cannot change. Do not edit them.

When the config file is absent, the defaults apply. Treat the limits as a ceiling, not a target: stay well below them. When an edit does not fit, move detail into deferred memory instead of raising a limit; change the config only when the user asks.

## Writing prompts

Core memory is the agent's working model: who it is, how the user thinks and what they value, and the principles that follow. It is not a list of rules.

- Treat a correction or preference as evidence about that model. Find the principle it belongs to and sharpen or rewrite that principle. Add a new one only when the evidence shows something the model was missing. - When several rules share a cause, replace them with the one principle that explains them all, and delete the lines it absorbs in the same edit. Adding the principle while keeping the old rules is a log with a summary on top. A healthy file becomes more general over time; a growing count of narrow rules is a sign of failure. - State the principle with the reason that makes it generalize: "Verify claims against the running system, because Sarah trusts evidence over plausibility", not three separate rules about tests, logs, and deployments. - Write to the agent in the second person or imperative mood: "Lead with the answer", not "The user likes answers first". Say what to do rather than only what to avoid. - Leave out provenance: no names, dates, quotes, or stories about the incident. Message history already holds the events, and the commit message records why the line changed and where the learning came from. When you edit a section that already contains provenance-laden rules, rewrite them as principles; nothing is lost, because git keeps the old text. - Update only from a pattern or an explicit instruction, not a single ambiguous event. - Check that a change does not contradict an existing line; resolve the conflict instead of adding both. - Write in plain language without all-caps or absolute emphasis. Overstated instructions get overapplied. - Leave out content the agent can cheaply rederive: file contents, command lists, current status, and recent activity. - Never store secrets. Reference them by name, such as `$SECRET_NAME`.

## Teach with examples, not more rules

A correction that reveals a gap in a principle calls for sharpening its wording. A correction the principle already covers, such as the user pointing out the same kind of mistake again, means the principle is too abstract to apply: attach a contrastive example to it instead of rewording it again or adding another rule.

```markdown - Lead with the answer, because the user reads the first line and skims the rest. - Not: "I looked at the config, then the logs, and it turns out the timeout is too low." Instead: "The timeout is too low: 5s, and the slow query takes 8s." ```

- Keep at most one or two examples per principle, and make them differ from each other. A new correction replaces the weaker example rather than adding another. - Write the example as a generic instance of the behavior, not a record of the incident: no dates, names, or quotes. - Keep the bad half short and labeled, and end on the good half. The agent imitates the details of examples, including the ones it should avoid. - When a principle or example starts producing the wrong behavior, revise or remove it. A memory edit is a hypothesis about the agent's behavior; later conversations test it.

## Design root MEMORY.md so deferred memory gets used

The agent consults deferred memory only when something in its prompt tells it to. The generated `<deferred-memory>` list gives directory paths and nothing else, so root `MEMORY.md` decides whether everything outside core memory is ever read. A directory with no useful entry here is effectively lost.

- Give each directory a one-line entry saying when to open it, in the words a future request would use: "deployments, rollbacks, on-call runbooks", not "ops notes". - Name a specific deeper file when its topic would not be guessable from the directory entry. - Say what kinds of questions should send the agent to memory before it answers from assumption, such as an unfamiliar person, project, or system named in the conversation. - Do not re-index root files or skills; both are already in the prompt. - After adding a directory or file, check that a natural future request would reach it by reading only root `MEMORY.md` and the indexes beneath it.

## Shrink before you grow

When a root file is long or the total is near its limit:

1. Delete stale, duplicated, or rederivable content. 2. Move subject detail into deferred memory and leave a one-line pointer in root `MEMORY.md`. 3. Move procedures into skills.

## Commit memory changes

Every memory commit must let someone reading `git log` or `git blame` on a memory or skill line trace back to the events that justified it. Commit each learning separately; a learning may touch several files. When a turn produces several learnings, finish and commit one before editing for the next. From the repository root, stage only that learning's files and commit in one shell call:

```bash git add <changed files> && git commit -m "memory(<origin>): <what was learned>

<what happened: the events that led to this learning and why it should persist>

Sources: - <conversation ID> (<message IDs>), <who>, <date>: <what happened there>" ```

- `<origin>` is `self` when you edit your own memory during a conversation, or `dream` when you are a reflection or dream subagent reviewing past transcripts. - Provenance belongs in the commit, not the memory file: who said or did it (name and ID), when, the quote, and the incident go in the body and `Sources:`. The memory line states only the resulting rule or fact. For example, the file says "Be concise" and the commit says "feedback 'talk more concisely' from Charles <id> on <date>". Git dates the commit, not the event, so write the event date. - The subject states the learning itself, such as `memory(self): Sarah wants one commit per learning`, not the file edit. - The body tells the story: what the user said or corrected, what failed or succeeded, or what pattern recurred, and why it generalizes beyond that moment. A reader should understand why the memory exists without opening the sources. - `Sources:` lists the evidence precisely enough to find again, with one line on what happened at each: a conversation ID with the message IDs where it happened, a transcript or session ID, a file path, a URL, PR, or issue, or a commit hash. When the user explicitly asked for the change, cite that request. Resolve values such as `$CONVERSATION_ID` before writing them; never commit a literal variable name. - Do not invent a source. If the origin cannot be identified, write `Sources: unknown` and say why in the body. - Never include secrets.

Intended uses

  • Use Maintaining Core Memory when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.