memory-loop

English | 简体中文

The agent forgets. The repo doesn't.

Background

Loop Engineering by Addy Osmani describes a shift in how we work with coding agents:

"You shouldn't be prompting coding agents anymore. You should be designing loops that prompt your agents."

A loop needs five building blocks — automations, worktrees, skills, connectors, and sub-agents — plus one place to remember stuff:

"A markdown file, or a Linear board, anything that lives outside the single conversation and holds what's done and what is next... the model forgets everything between runs so the memory has to be on disk and not in the context. The agent forgets, the repo doesn't."

memory-loop is that sixth piece, built as a Claude Code plugin. Install it once, and every project you open gets a persistent, structured memory that loads automatically at session start and updates as you work.

How it works

┌─────────────────────────────────────────────────────┐
│  Session starts                                     │
│    └── SessionStart hook fires automatically        │
│          ├── First time? Creates .claude/memory/    │
│          ├── Copies default schema.yaml             │
│          ├── Generates empty MEMORY.md              │
│          └── Injects memory content into context ──►│ Claude sees past decisions,
│                                                     │ goals, and gotchas instantly
│  Agent works ──────────────────────────────────────►│
│                                                     │
│  Task complete?                                     │
│    └── /memory-loop:save                           │
│          └── Agent reads schema → writes entries   │
│                                                     │
│  Session ends                                       │
│    └── Stop hook fires                              │
│          └── Warns if MEMORY.md needs compression  │
│                                                     │
│  Memory too large?                                  │
│    └── /memory-loop:compress                       │
│          └── Archives old entries → archive.md     │
└─────────────────────────────────────────────────────┘

Files created in your project

your-project/
└── .claude/
    └── memory/
        ├── MEMORY.md      ← hot layer, injected every session
        ├── archive.md     ← cold layer, created on first compress
        └── schema.yaml    ← your customizable schema

Tip: Commit these files to share memory with your team, or add .claude/memory/ to .gitignore to keep them local.

Installation

One command. Works across all your projects.

claude plugin install github:yucai0302/memory-loop

That's it. The plugin activates on the next Claude Code session.

Scope options

Quickstart: what happens after installation

Step 1 — Open any project in Claude Code

The plugin fires automatically on session start. No manual setup needed.

[memory-loop] Initialized project memory at .claude/memory/MEMORY.md
[memory-loop] Edit .claude/memory/schema.yaml to customize tracked fields.

======= PROJECT MEMORY (memory-loop) =======
# Project Memory
## Project Context
_Not yet set..._
...
=============================================
[memory-loop] Memory loaded (312 chars). Update it with /memory-loop:save

Step 2 — Work normally. When you finish a task, save.

/memory-loop:save

The agent reviews what happened in the session and writes structured entries:

Memory updated:
  + Completed: "Set up authentication middleware | JWT + Redis session"
  + Gotcha: "[auth] Token expiry not propagated to frontend → add 401 interceptor"
  - Active Goal: "Implement login flow" (marked done)

Step 3 — Next session, memory is already there

Open the project again. The session start hook automatically injects everything the agent learned last time. No prompting needed.

Step 4 — Check health, compress when needed

/memory-loop:status    # show file size and section counts
/memory-loop:compress  # archive old entries when memory grows large

Customizing the schema

Edit .claude/memory/schema.yaml in your project. Changes take effect on the next session.

version: "1.0"

hot_layer:
  sections:
    - name: "Project Context"
      description: "Project type, core tech stack, architecture overview."
      max_items: 1
      format: "prose"

    - name: "Active Goals"
      description: "Tasks currently in progress."
      max_items: 5
      format: "- [goal description] | started: YYYY-MM-DD"

    - name: "Decisions"
      description: "Key technical decisions."
      max_items: 10
      format: "- YYYY-MM-DD | chose X over Y | reason: Z"

    - name: "Gotchas"
      description: "Known bugs, traps, constraints the agent must respect."
      max_items: 20
      format: "- [module] problem → workaround / rule"

    - name: "Completed"
      description: "Recently finished tasks, rolling window."
      max_items: 10
      format: "- YYYY-MM-DD | task | outcome"

compression:
  trigger_chars: 8000       # warn when MEMORY.md exceeds this
  keep_recent_decisions: 5  # keep N newest on compress
  keep_recent_completed: 3  # keep N newest on compress

Adding custom sections

Any section you add to hot_layer.sections is picked up automatically:

    - name: "API Contracts"
      description: "External API endpoints this project depends on and their quirks."
      max_items: 15
      format: "- [service] endpoint | note"

Commands reference

You can also trigger saving naturally in conversation:

• "Update the project memory"
• "Save what we did to memory"
• "Record this decision"

Why this design

Why project-scoped and not global?
Memory is specific to a codebase. Decisions and gotchas in project A are noise in project B.

Why a markdown file and not a vector database?
At the scale of a single project's working memory, full injection beats semantic retrieval. No retrieval gaps, no missed critical gotchas. When the file grows large, /memory-loop:compress archives old entries — the structured hot/cold split happens over time, not at write time.

Why warn instead of auto-compress?
Compression moves information. That should be a deliberate act, not something that silently drops context you might need.

Why not write to CLAUDE.md?
CLAUDE.md is for project conventions you write once. MEMORY.md is dynamic state that changes every session. Mixing them makes both harder to manage.

Requirements

• Claude Code v2.0+
• bash (macOS / Linux / WSL)
• yq (optional — for per-project compression thresholds)

brew install yq   # macOS
snap install yq   # Linux

Contributing

Issues and PRs welcome.

If you build a custom schema for a specific domain (chip design, data science, game dev, etc.), consider contributing it to examples/ so others can start with something relevant.

License

MIT © yucai0302

Star History