Skill: indulgeback/claude-code-memory-skill (version 0.1.0)

--- name: "claude-code-memory" description: "Use when you want to set up, maintain, or review a Claude Code style layered memory workflow, including `CLAUDE.md` rules, session memory, durable memory, and promotion of stable learnings into instruction files." --- ## Overview Use this skill when the task involves memory design or memory hygiene for Claude Code or a similar coding agent. This skill organizes memory into three layers: 1. Instruction memory 2. Session memory 3. Durable memory The intent is to keep each layer narrow, useful, and easy to trust. ## Before you start - Identify the host tool's instruction file. For Claude Code this is usually `CLAUDE.md` or `CLAUDE.local.md`. Other common examples are `AGENTS.md` and `.github/copilot-instructions.md`. - Identify or create a repo-local durable memory directory. The default layout in this skill uses `.agent-memory/`. - Identify or create the session summary file at `.agent-memory/session/summary.md`. ## Layer 1: Instruction memory Treat the host instruction file as the rule layer. In Claude Code, this is the `CLAUDE.md` layer. Put information here only if it is: - stable - normative - broadly applicable across future work - costly for the agent to rediscover incorrectly Good candidates: - test commands - review expectations - approval boundaries - release process rules - communication style preferences that consistently apply Do not place transient task state here. ## Layer 2: Session memory Maintain `.agent-memory/session/summary.md` as the short-lived working notebook for the current thread. It should answer: - What is actively being worked on now - What did the user ask for - Which files and functions matter - Which commands have already been run - Which errors happened and how they were resolved - What remains next This layer should be updated during long tasks and before compaction or handoff. Use this structure: ```markdown # Session Title # Current State # Task Specification # Files and Functions # Workflow # Errors and Corrections # Key Results # Worklog ``` Keep it concise but concrete. Prefer file paths, exact commands, and specific failure modes over generic summaries. ## Layer 3: Durable memory Use `.agent-memory/` for long-lived memories that should survive across conversations. Store durable memories in topic files and keep `.agent-memory/MEMORY.md` as an index. Use the following durable memory types: ### `user-profile` Information about the user's role, goals, background, and level of familiarity. Examples: - backend-heavy engineer who wants frontend explanations grounded in systems concepts - founder who prefers quick trade-off summaries ### `working-style` Guidance about how to collaborate with this user or team. Examples: - run tests before proposing a commit - avoid long recap paragraphs - prefer one bundled refactor PR in this codebase ### `project-context` Important project facts that are not derivable from the repo. Examples: - freeze window dates - stakeholder constraints - migration rationale - incident aftermath that still shapes decisions ### `external-reference` Pointers to systems outside the repo. Examples: - which dashboard matters for this codepath - which Linear board tracks this class of bugs - which Slack channel owns deployment coordination ## Durable memory format Each durable memory should live in its own file with frontmatter: ```markdown --- name: testing-policy description: Integration tests in this repo must hit a real database type: working-style --- Integration tests in this repo must hit a real database. Why: A previous production migration failure was missed by mock-based coverage. How to apply: When changing data access or migrations, prefer real-db integration coverage over mocks. ``` The index file should stay short: ```markdown - [Testing Policy](testing-policy.md) - Real database integration tests are expected here ``` ## What not to save as durable memory Do not save these unless there is a strong reason and the non-obvious part is the actual point: - file structure - code architecture visible in the repo - git history - recent diff summaries - temporary task state - obvious commands already documented in project instructions If it can be recovered cheaply from the current repo, prefer not to save it as durable memory. ## Recall discipline Never trust durable memory blindly. Before acting on it: - verify named files still exist - grep for named functions or flags - prefer current repo state over historical memory if they conflict - update or remove stale memories when you discover drift ## Promotion workflow When reviewing memory, classify each item: - Promote to instruction memory - Keep in durable memory - Keep only in session memory - Delete as stale, duplicate, or overfit Promote into the instruction layer when the item has become a rule. Keep it in durable memory when it remains useful context but is not a rule. Keep it only in session memory when it is tied to the present thread. ## Review workflow When the user asks to review memory: 1. Read the host instruction file such as `CLAUDE.md` 2. Read `.agent-memory/MEMORY.md` 3. Read the most relevant durable topic files 4. Read `.agent-memory/session/summary.md` if current-thread context matters 5. Produce a report with: - promotions - cleanup - conflicts - ambiguous items Do not modify durable memory or instruction files without user approval unless the user explicitly asked you to apply the cleanup. ## File layout used by this skill ```text .agent-memory/ ├── MEMORY.md ├── user/ ├── style/ ├── project/ ├── references/ └── session/ └── summary.md ``` ## References - Architecture notes: [references/architecture.md](references/architecture.md) - Host tool mapping: [references/host-tool-mapping.md](references/host-tool-mapping.md) - Example durable memory files: [examples/persistent-memory/MEMORY.md](examples/persistent-memory/MEMORY.md) - Example session summary: [examples/session-memory/summary.md](examples/session-memory/summary.md)

path: README.md
content: # Claude Code Memory Skill

A clean-room layered memory workflow reconstructed from public analysis of Claude Code's memory architecture.

This repo packages the practical memory pattern people care about when they talk about Claude Code memory:

- instruction memory through `CLAUDE.md`-style rules
- session memory for active work continuity
- durable memory for facts worth carrying across conversations

If you searched for:

- `claude code memory`
- `claude code layered memory`
- `claude md memory workflow`
- `how claude code remembers context`

this is the open implementation you probably wanted.

It gives an agent three distinct memory lanes:

1. Instruction memory for durable rules
2. Session memory for the current workstream
3. Durable memory for facts worth carrying across conversations

The goal is simple: keep the main prompt lean, preserve the right context, and avoid turning every conversation into a total reset.

## In one sentence

This repository turns the Claude Code style memory pattern into a reusable skill you can install, inspect, and adapt.

## What this repo is

This repo is:

- a reusable skill for Claude Code style layered memory
- a clean-room reconstruction of the pattern, not a prompt dump
- a practical way to bring `CLAUDE.md` rules, session continuity, and durable memory into one workflow

This repo is not:

- an official Anthropic repository
- a verbatim copy of proprietary system prompts
- a claim that Claude Code uses these exact words

## Claude Code architecture -> this repo

| Claude Code style concept | What this repo gives you |
|---|---|
| `CLAUDE.md` rule layer | instruction memory workflow |
| current thread continuity | session memory template |
| long-lived memory files | durable indexed memory layout |
| memory cleanup and promotion | review workflow in `SKILL.md` |
| practical repo usage | installable examples and references |

## Why people look for Claude Code memory

The interest around Claude Code memory is not really about one prompt. It is about the architecture:

- rules belong in instruction files
- active work belongs in a session summary
- reusable, non-derivable facts belong in durable memory

That separation is what makes a coding agent feel coherent over time.

This repository turns that idea into an installable skill and a portable repo structure.

## Why this exists

Most coding agents have two failure modes:

- They forget important context between sessions
- They stuff too much transient detail into persistent memory

This skill separates memory by job:

- The instruction layer holds stable rules and collaboration preferences
- The session layer tracks the current task state, files, commands, and mistakes
- The durable layer stores only non-derivable facts that are still useful later

That makes memory easier to maintain, safer to trust, and cheaper to keep in prompt context.

## What is included

- A reusable `SKILL.md`
- A durable memory taxonomy
- A session-summary workflow
- A memory review and promotion workflow
- Example files you can copy into your own setup

## Quick start

1. Put this repo in your skills directory
2. Create `.agent-memory/` in the target project
3. Map your rule layer to `CLAUDE.md`, `CLAUDE.local.md`, `AGENTS.md`, or another instruction file
4. Keep active work in `.agent-memory/session/summary.md`
5. Store reusable facts as indexed topic files under `.agent-memory/`

## Why this is relevant to Claude Code users

If you already use Claude Code, this repo maps naturally onto the way people structure memory around it:

- instruction layer -> `CLAUDE.md` and `CLAUDE.local.md`
- session layer -> a repo-local running summary
- durable layer -> indexed memory topic files

If you use another coding agent, the same pattern still works. Only the host instruction file changes.

## Memory model

```mermaid
flowchart TD
    A["Current conversation"] --> B["Session memory"]
    A --> C["Durable memory review"]
    C --> D["Durable memory index + topic files"]
    C --> E["Instruction layer"]
    B --> F["Compaction / resume context"]
    D --> G["Future conversations"]
    E --> G
```

## What makes the pattern work

The separation matters more than the wording:

- instruction memory answers: "how should the agent behave here?"
- session memory answers: "what is happening right now?"
- durable memory answers: "what should still be known next week?"

When those answers live in one file, the agent gets noisier. When they live in separate layers, the memory is easier to maintain and easier to trust.

### 1. Instruction layer

This is where stable rules belong:

- project conventions
- collaboration preferences
- approval boundaries
- testing and release expectations

For Claude Code users, this usually means:

- `CLAUDE.md`
- `CLAUDE.local.md`

For other tools, map this layer to whatever instruction file you already use:

- `AGENTS.md`
- `.github/copilot-instructions.md`
- project-level system prompt files

### 2. Session layer

This is the working notebook for the current thread:

- current state
- task specification
- important files and functions
- commands that matter
- errors and corrections
- terse worklog

It is short-lived and should be optimized for continuity, not permanence.

### 3. Durable memory layer

This is the long-term memory directory. It stores things that are not obvious from the repo itself and are still useful later.

This skill uses four durable memory types:

- `user-profile`
- `working-style`
- `project-context`
- `external-reference`

## Install

### As a Claude Code or Codex skill

Clone this repo into your skills directory:

```bash
git clone <your-repo-url> ~/.codex/skills/layered-memory-skill
```

Or symlink it while developing:

```bash
ln -s /path/to/layered-memory-skill ~/.codex/skills/layered-memory-skill
```

### As a prompt pattern for other agents

If your agent platform does not support native skills, copy the workflow from:

- [SKILL.md](./SKILL.md)
- [references/architecture.md](./references/architecture.md)
- [references/host-tool-mapping.md](./references/host-tool-mapping.md)

Then adapt the file paths to your agent runtime.

## Suggested file layout

```text
.agent-memory/
├── MEMORY.md
├── user/
├── style/
├── project/
├── references/
└── session/
    └── summary.md
```

`MEMORY.md` should stay lightweight. Use it as an index that points to topic files rather than a dumping ground.

## Who this is for

- Claude Code users who want a more explicit memory layout
- people building Codex, Cursor, or custom repo agents
- teams experimenting with durable memory for coding workflows
- anyone trying to recreate the useful part of Claude Code memory without relying on prompt dumps

## Promotion rules

Promote something into the instruction layer only when it is:

- stable
- normative
- broadly applicable
- likely to be wrong if the agent has to rediscover it every time

Keep something in durable memory when it is:

- true but not derivable from the code
- useful in future sessions
- not yet stable enough to become an instruction

Keep something only in session memory when it is:

- specific to the current task
- likely to expire soon
- only useful for resuming the present thread

## Examples

- Durable index: [examples/persistent-memory/MEMORY.md](./examples/persistent-memory/MEMORY.md)
- Durable user memory: [examples/persistent-memory/user-profile.md](./examples/persistent-memory/user-profile.md)
- Durable style memory: [examples/persistent-memory/testing-policy.md](./examples/persistent-memory/testing-policy.md)
- Session summary: [examples/session-memory/summary.md](./examples/session-memory/summary.md)

## Reconstructed from public analysis

This repository was designed from public analysis of layered memory behavior discussed around Claude Code and similar coding agents, then rewritten into an original, reusable skill.

The important thing here is the workflow, not any single leaked phrase:

- route stable rules into instruction files
- keep active work in session memory
- save only durable, non-derivable facts into long-term memory

That is the part worth reusing.

## Star this repo if

- you want Claude Code style memory in an open form
- you think coding agents need better memory hygiene
- you want a concrete starting point instead of vague prompt advice

## FAQ

### Is this a copy of Claude Code's internal prompt?

No. This is a clean-room skill and repo design that captures the layered memory idea without reproducing proprietary prompt text.

### Why call it Claude Code Memory Skill?

Because the intended audience is people trying to recreate the layered memory workflow associated with Claude Code in a reusable, open form. The repo is named for compatibility and discoverability, not official affiliation.

### Why not keep everything in one big instruction file?

Because rules, active task state, and long-lived facts decay at different speeds. Mixing them makes the agent noisier and harder to trust.

### Can I adapt this to a different agent stack?

Yes. The core pattern is portable. Only the instruction-file mapping changes.


path: agents/openai.yaml
content: interface:
  display_name: "Claude Code Memory"
  short_description: "Recreate Claude Code style layered memory in your repo"
  default_prompt: "Set up or maintain a Claude Code style layered memory workflow for this project, including CLAUDE.md rules, session memory, durable memory, and promotion review."


path: examples/persistent-memory/MEMORY.md
content: - [User Profile](user-profile.md) - This user is strong in backend systems and prefers frontend explanations that tie back to architecture
- [Testing Policy](testing-policy.md) - Changes touching persistence should be validated against a real database
- [Release Context](release-context.md) - Non-critical merges are avoided during the mobile release window
- [Latency Dashboard](external-reference.md) - Request-path changes should be checked against the on-call latency dashboard


path: examples/persistent-memory/external-reference.md
content: ---
name: latency-dashboard
description: The on-call latency dashboard is the first place to check after request-path changes
type: external-reference
---

The team watches the request latency dashboard first when debugging issues in the request path.

Why:
It is the fastest way to tell whether a change affected tail latency or regional error spikes.

How to apply:
If you modify routing, middleware, persistence on the hot path, or request fan-out behavior, check the latency dashboard before calling the change safe.


path: examples/persistent-memory/release-context.md
content: ---
name: release-context
description: Non-critical merges are avoided during the mobile release window
type: project-context
---

The project avoids non-critical merges during the mobile release window.

Why:
The release branch is cut under tight QA timing and unrelated churn creates avoidable risk.

How to apply:
If a requested change is not urgent, suggest delaying merge timing or reducing scope during the release window.


path: examples/persistent-memory/testing-policy.md
content: ---
name: testing-policy
description: Persistence-heavy changes should be validated against a real database
type: working-style
---

When changing queries, migrations, or persistence-sensitive code, prefer tests that touch a real database over mock-only coverage.

Why:
The team has been burned by mock-based tests passing while a production migration or SQL behavior failed.

How to apply:
If the work touches schema, query generation, or transactions, add or run integration coverage before declaring the change safe.


path: examples/persistent-memory/user-profile.md
content: ---
name: user-profile
description: The user is backend-heavy and prefers explanations grounded in architecture
type: user-profile
---

The user has deep backend experience and wants frontend or UI explanations framed in terms of systems, data flow, and trade-offs rather than visual terminology alone.

Why:
They move faster when new concepts are connected to architecture and runtime behavior.

How to apply:
When explaining React, UI state, or browser behavior, anchor the explanation in control flow, data ownership, and failure modes.


path: examples/session-memory/summary.md
content: # Session Title
Fix flaky checkout integration tests

# Current State
The checkout test suite was narrowed to two flaky database-backed cases. The likely cause is shared fixture state between retries. Next step is to isolate transaction setup in the payment test helper.

# Task Specification
Stabilize the checkout integration suite without replacing real database coverage. Preserve current test semantics and avoid hiding legitimate race conditions.

# Files and Functions
- `tests/integration/checkout.test.ts` - failing suite
- `tests/helpers/payment-fixtures.ts` - shared setup suspected of leaking state
- `src/payments/createCheckoutSession.ts` - target codepath under test

# Workflow
- `pnpm test tests/integration/checkout.test.ts --runInBand`
- `pnpm test tests/integration/checkout.test.ts --runInBand --repeat 10`
- `pnpm lint`

# Errors and Corrections
- Mocking the payment layer made the flake disappear but invalidated the purpose of the test, so that approach was rejected.
- Retrying the suite without isolating fixture state only hid the failure pattern.

# Key Results
No final fix yet. We isolated the failure to shared setup in payment fixtures rather than the checkout service itself.

# Worklog
- Reproduced the flake locally
- Narrowed failures to two cases
- Compared shared fixture state across retries
- Rejected mock-based workaround


path: references/architecture.md
content: # Layered Memory Architecture

This skill separates memory by job instead of storing everything in one place.

## The three layers

### Instruction layer

This is the rule layer. It belongs in the host tool's durable instruction file.

Use it for:

- repo-wide conventions
- stable team expectations
- durable personal collaboration preferences
- approval and release boundaries

This layer should be hard to change and easy to trust.

### Session layer

This is the active work notebook for the current thread.

Use it for:

- what is being worked on now
- next steps
- important files
- key commands
- errors and corrections
- output artifacts produced in the session

This layer is optimized for continuity and compaction, not permanence.

### Durable layer

This is the cross-session fact layer.

Use it for:

- information about the user
- collaboration guidance
- project facts not visible in the repo
- references to external systems

This layer should be slower to grow than the session layer.

## Routing rules

Ask three questions before saving:

1. Is this already derivable from the repo
2. Will this matter outside the current thread
3. Is this a rule, a temporary state, or a reusable fact

Route based on the answer:

- rule -> instruction layer
- temporary state -> session layer
- reusable fact -> durable layer

## Durable memory hygiene

The durable layer fails when it becomes a junk drawer.

Watch for these smells:

- duplicate topic files
- stale release notes stored as memory
- copied commit summaries
- code structure that should have been rediscovered from the repo
- team policies mixed with one user's personal preference

When you see drift, prefer:

- consolidate
- shorten
- delete stale entries
- promote only the most stable items into the instruction layer

## Why this pattern works

It reduces two common agent failures:

- forgetting important non-code context
- polluting long-term memory with transient work details

The instruction layer tells the agent how to behave.
The session layer helps it resume work.
The durable layer helps it remember facts worth carrying forward.


path: references/host-tool-mapping.md
content: # Host Tool Mapping

This skill is intentionally tool-agnostic.

Map the instruction layer to the host tool you already use.

## Common mappings

### Claude Code

- Instruction layer: `CLAUDE.md` or `CLAUDE.local.md`
- Durable layer: repo-local memory directory such as `.agent-memory/`
- Session layer: `.agent-memory/session/summary.md`

### Codex

- Instruction layer: `AGENTS.md`, project instructions, or repo-local guidance file
- Durable layer: `.agent-memory/`
- Session layer: `.agent-memory/session/summary.md`

### GitHub Copilot

- Instruction layer: `.github/copilot-instructions.md`
- Durable layer: `.agent-memory/`
- Session layer: `.agent-memory/session/summary.md`

### Cursor or Windsurf

- Instruction layer: the tool's repo rules file
- Durable layer: `.agent-memory/`
- Session layer: `.agent-memory/session/summary.md`

## Recommended defaults

If your tool does not have a durable instruction file, create one and keep it small.

Recommended repo-local layout:

```text
.agent-memory/
├── MEMORY.md
├── user/
├── style/
├── project/
├── references/
└── session/
    └── summary.md
```

This keeps the durable layer explicit and portable across tools.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)