3-Tier Memory System for Claude Code

Structured persistent memory across sessions. Never lose context, learnings, or action items again.

Prerequisites

Claude Code 2.1.x or later is required (the plugin system was introduced in v2.1). Check your version:

claude --version

If you need to update: claude update

Quick start

There are 3 steps. The first two you only do once. After that you just use /checkpoint.

Step 1: Install the plugin

Run these commands in your terminal (regular shell):

claude plugin marketplace add vzert/3-tier-memory
claude plugin install 3-tier-memory@3-tier-memory-marketplace

Then start (or restart) Claude Code for the plugin to activate.

Already inside Claude Code? The equivalent REPL commands are: /plugin marketplace add vzert/3-tier-memory, then /plugin install 3-tier-memory@3-tier-memory-marketplace, then /reload-plugins.

Troubleshooting: If install says "not found", verify the marketplace was added: claude plugin marketplace list. You may need to restart Claude Code after adding the marketplace.

Step 2: Initialize memory in your project (once per project)

New project (no existing memory):

/3-tier-memory:setup-memory

Existing project (already has memory/ set up manually):

/3-tier-memory:migrate

setup-memory creates everything from scratch. migrate installs the plugin's local commands (/checkpoint, /status, /audit) without touching your existing data.

Both are the only time you use long namespaced commands. After that:

Step 3: Day-to-day usage

/checkpoint
/checkpoint fix-auth-bug

That's it. /checkpoint saves your session, extracts action items, captures learnings, updates all indexes, and git commits everything.

What it does

Session logs — automatic session tracking with git commits
Action items tracking — dual-write system (active aggregator + monthly archive)
Learnings — topic-based knowledge from past mistakes, injected at session start
Plans & Research — lifecycle tracking from idea to execution (when applicable)
Relevance recall — on every prompt, the most relevant memory (rules, sessions, action items) is surfaced automatically, ranked by relevance × recency × importance (lexical engine, zero dependencies)
Staleness signals — action items older than 30 days are flagged for reconciliation; learnings can carry last_verified and are surfaced by /audit-3t
Hooks — auto-inject open action items + learnings at session start, surface relevant memory per prompt, detect unregistered files

Commands

/checkpoint-3t — save session state (logs, action items, learnings, indexes, git commit)
/status-3t — quick health overview
/audit-3t — run verification checklists (structure, bridge, wikilinks, staleness, index budget, broken links)
/backfill-3t — reconstruct memory from past JSONL conversation history
/consolidate-3t — dedup learnings (index-driven pre-filter + early-exit), resolve contradictions via supersede, reflect recent sessions into higher-level rules
/enrich-3t — one-time backfill of importance:/_creado: into a pre-existing corpus so recall and staleness work on legacy files

The 3-Tier Architecture

Tier 1: MEMORY.md (auto-loaded, <200 lines)
   links to
Tier 2: _index files (lean aggregators, 30-60 lines each)
   links to
Tier 3: detail files in typed folders (full content)

Dual-write rule: sessions, action items, and learnings ALWAYS go to both Tier 2 (index) and Tier 3 (detail file). Plans and research only when applicable.

Alternative install methods

Team setup (auto-prompt when teammates trust the repo)

Add to your project's .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "3-tier-memory-marketplace": {
      "source": {
        "source": "github",
        "repo": "vzert/3-tier-memory"
      }
    }
  }
}

Important: extraKnownMarketplaces only makes the marketplace known — each team member still needs to run claude plugin install 3-tier-memory@3-tier-memory-marketplace and restart Claude Code.

Manual installation (no `claude plugin` commands needed)

If claude plugin is not available (older Claude Code version) or your AI agent cannot run it:

Clone the marketplace repository:

git clone https://github.com/vzert/3-tier-memory.git \
  ~/.claude/plugins/marketplaces/3-tier-memory-marketplace

Add these keys to your ~/.claude/settings.json (create the file if it doesn't exist — merge into existing JSON if it does):

{
  "extraKnownMarketplaces": {
    "3-tier-memory-marketplace": {
      "source": {
        "source": "github",
        "repo": "vzert/3-tier-memory"
      }
    }
  },
  "enabledPlugins": {
    "3-tier-memory@3-tier-memory-marketplace": true
  }
}

Restart Claude Code. The plugin will be active.

Development / testing a local copy

claude --plugin-dir ./3-tier-memory/plugins/3-tier-memory

Loads the plugin for one session only. Useful for testing changes before publishing.

Updates

Updates are automatic. Starting with version 1.9.0, the plugin auto-enables marketplace updates on every session start. You don't need to do anything — new versions are pulled and applied by Claude Code at startup.

On each session start:

Hooks update immediately (the plugin runs from the latest cached version)
/checkpoint auto-syncs — the plugin compares your local version against the latest and copies if needed. You'll see "ACTUALIZADO" if it was updated.
memory/ structure is untouched — your data is yours

Uninstall

Remove the plugin

In your terminal:

claude plugin uninstall 3-tier-memory@3-tier-memory-marketplace

Or inside Claude Code: /plugin uninstall 3-tier-memory@3-tier-memory-marketplace then /reload-plugins.

Remove the marketplace

claude plugin marketplace remove 3-tier-memory-marketplace

Clean up a project's memory (optional)

The plugin doesn't auto-delete project files. To fully remove from a project:

rm -rf memory/                          # memory directory
rm -f .claude/commands/checkpoint.md    # local /checkpoint command

The auto-memory bridge at ~/.claude/projects/<encoded-path>/memory/MEMORY.md can also be deleted if no longer needed.

Directory structure after setup

your-project/
├── .claude/
│   └── commands/
│       └── checkpoint.md      <- your local /checkpoint command
└── memory/
    ├── MEMORY.md              # Tier 1: lean index + checkpoint protocol
    ├── _pendientes.md         # Tier 2: open action items
    ├── _session-index.md      # Tier 2: session history
    ├── _learnings.md          # Tier 2: learnings topic index
    ├── _plans-index.md        # Tier 2: plan registry
    ├── _research-index.md     # Tier 2: research tracker
    ├── learnings/             # Tier 3: topic files
    ├── sessions/              # Tier 3: session logs
    ├── pendientes/            # Tier 3: monthly archives
    ├── plans/                 # Tier 3: plan files
    └── research/              # Tier 3: research files

Troubleshooting

"My AI agent says plugins don't exist"

Claude Code's plugin system was added in v2.1.x. AI agents trained before this release may not recognize the /plugin or claude plugin commands. The commands are real and built into Claude Code.

Options:

Verify your Claude Code version: claude --version (must be 2.1.x+)
Use the terminal commands (claude plugin ...) instead of REPL commands (/plugin ...) — they're equivalent and easier for agents to execute
Use the Manual installation method above — it requires only git clone and editing a JSON file

"Plugin not found" or install fails

The marketplace must be added before the plugin can be installed. Verify:

claude plugin marketplace list

If 3-tier-memory-marketplace is not listed, add it first:

claude plugin marketplace add vzert/3-tier-memory

If the marketplace shows but install still fails, remove and re-add:

claude plugin marketplace remove 3-tier-memory-marketplace
claude plugin marketplace add vzert/3-tier-memory
claude plugin install 3-tier-memory@3-tier-memory-marketplace

/checkpoint not recognized after setup

Make sure /3-tier-memory:setup-memory ran successfully — it creates .claude/commands/checkpoint.md in your project. If the file exists but the command isn't recognized, restart Claude Code or run /reload-plugins.

Hooks not firing

The plugin's hooks (action items + learnings injection at session start) activate after install + restart. If they don't fire, run /doctor inside Claude Code to check for plugin errors.

Check installed version

claude plugin list

Updates not arriving?

If you're on a version older than 1.9.0, auto-update may not be enabled. Force a manual update:

cd ~/.claude/plugins/marketplaces/3-tier-memory-marketplace && git pull

Then:

claude plugin install 3-tier-memory@3-tier-memory-marketplace

After this, version 1.9.0+ will auto-enable updates for all future sessions.

Checkpoint reminder fires too early (large-context models)

The plugin nudges you to run /checkpoint-3t as the conversation fills the context window. By default it assumes a 200k window — so on a 1M-context model (e.g. opus[1m]) the reminder, and Claude Code's own auto-compaction, can feel premature. Two independent things:

Claude Code's auto-compaction triggers on its own threshold (often ~200k) and doesn't reliably scale to 1M. The harness exposes no threshold setting — only on/off. To stop premature compaction on a 1M model, disable it: export DISABLE_AUTO_COMPACT=1 (or /config → auto-compact off). The transcript records the base model id without the [1m] suffix, so the plugin can't auto-detect your real window either.
The plugin's checkpoint nudge reads your actual token usage from the transcript and is configurable. Tell it your real window so it nudges at ~80% of that, not of 200k:
```
export THREET_CONTEXT_WINDOW=1000000   # your model's context window in tokens
export THREET_CHECKPOINT_RATIO=0.8     # optional: nudge at this fraction (default 0.8)
```
Put these in your shell profile (or .claude/settings.json env) so they persist. The nudge is independent of auto-compaction, so it still works after you disable it.

License

MIT

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
.claude/commands		.claude/commands
memory/learnings		memory/learnings
plugins/3-tier-memory		plugins/3-tier-memory
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md

Navigation Menu

Repository files navigation

3-Tier Memory System for Claude Code

Prerequisites

Quick start

Step 1: Install the plugin

Step 2: Initialize memory in your project (once per project)

Step 3: Day-to-day usage

What it does

Commands

The 3-Tier Architecture

Alternative install methods

Team setup (auto-prompt when teammates trust the repo)

Manual installation (no `claude plugin` commands needed)

Development / testing a local copy

Updates

Uninstall

Remove the plugin

Remove the marketplace

Clean up a project's memory (optional)

Directory structure after setup

Troubleshooting

"My AI agent says plugins don't exist"

"Plugin not found" or install fails

/checkpoint not recognized after setup

Hooks not firing

Check installed version

Updates not arriving?

Checkpoint reminder fires too early (large-context models)

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

3-Tier Memory System for Claude Code

Prerequisites

Quick start

Step 1: Install the plugin

Step 2: Initialize memory in your project (once per project)

Step 3: Day-to-day usage

What it does

Commands

The 3-Tier Architecture

Alternative install methods

Team setup (auto-prompt when teammates trust the repo)

Manual installation (no claude plugin commands needed)

Development / testing a local copy

Updates

Uninstall

Remove the plugin

Remove the marketplace

Clean up a project's memory (optional)

Directory structure after setup

Troubleshooting

"My AI agent says plugins don't exist"

"Plugin not found" or install fails

/checkpoint not recognized after setup

Hooks not firing

Check installed version

Updates not arriving?

Checkpoint reminder fires too early (large-context models)

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Manual installation (no `claude plugin` commands needed)