claude-memory-skill

╔══●══●══●══════════════════════════════════════════════╗
║                                                       ║
║  > tree ~/.claude/memory                              ║
║                                                       ║
║    ├── core.md          claude-memory-skill           ║
║    ├── topics/          ───────────────────           ║
║    │   └── *.md         a skill is all you need       ║
║    └── me.md                                          ║
║                                                       ║
╚═══════════════════════════════════════════════════════╝

An embarrassingly simple and minimal implementation for agentic memory.

No databases. No embeddings. No semantic search. Just markdown files and a skill that teaches Claude when to read and write.

The Problem

Claude Code forgets everything between sessions. Built-in auto-memory exists but:

• It's opaque (Claude decides what's "meaningful")
• Limited to 200 lines loaded at startup
• Not tightly integrated into the agentic loop
• No hierarchical organization (scales poorly)

The Solution

A skill-based memory protocol with:

• Hierarchical storage: core.md summaries → topics/<topic>.md details
• Background agents: Memory ops don't block the main agent
• Categorized entries: No dumping ground, everything has a topic
• Filesystem-based: Robust, inspectable, git-trackable

Installation

curl -fsSL https://raw.githubusercontent.com/hanfang/claude-memory-skill/main/install.sh | bash

Or clone and run locally:

git clone https://github.com/hanfang/claude-memory-skill.git
cd claude-memory-skill
./install.sh

What Gets Installed

~/.claude/
├── CLAUDE.md              # Hook added (or created)
├── commands/
│   └── mem.md             # The memory skill
└── memory/
    ├── core.md            # Summaries + pointers (always loaded)
    ├── me.md              # About you (always loaded)
    ├── topics/            # Detailed entries by topic
    │   └── <topic>.md
    └── projects/          # Project-specific memories
        └── .md

Architecture

┌─────────────────────────────────────────────────────┐
│  Main Agent                                         │
│  - Focuses on user's task                           │
│  - Spawns memory agent when needed                  │
│  - Doesn't wait (background)                        │
└─────────────────────┬───────────────────────────────┘
                      │ spawn (background)
                      ▼
┌─────────────────────────────────────────────────────┐
│  Memory Agent                                       │
│  - Reads core.md + relevant topics                  │
│  - Writes to topic files                            │
│  - Updates core.md summaries                        │
└─────────────────────────────────────────────────────┘

How It Works

Agent-Initiated (Automatic)

These run automatically — you don't invoke them:

Action	When	Blocking
load	Session start	No
save	Claude learns something useful	No
recall	Claude needs context	No

User-Initiated (Manual)

These are for you to inspect and manage memory:

Command	Description
/mem show	Display memory structure and contents
/mem forget <topic>	Remove a topic or specific entries

Tell Claude What to Remember