Give Claude a memory that survives everything.
Compacts, crashes, restarts, weekends — works in Claude Code AND Claude Cowork.

# Add the marketplace
/plugin marketplace add hlsitechio/claude-memory

# Install the plugin
/plugin install claude-memory@hlsitechio

That's it. Restart Claude Code and memory is active. Claude will never lose context again.

💡 Works in Claude Cowork too! Same state.md, same memory. Start a task in Code, review it in Cowork — seamless cross-platform memory.

🚨 The problem: Claude starts every session blank. When the context window fills up, auto-compact fires and your conversation history is compressed. Terminal crash? Switch from Code to Cowork? Complete amnesia.

✅ The fix: claude-memory — a hook-based system that automatically saves and restores your working state across sessions, compacts, crashes, platform switches, and restarts.

Claude Code (terminal)              Claude Cowork (desktop)
┌────────────────────┐              ┌────────────────────┐
│ Build feature       │              │ Review progress     │
│ state.md updated    │───disk────→ │ Reads state.md      │
│ Goal: Auth system   │              │ "You're 3/7 done   │
│ Progress: 3/7 done  │              │  on auth system,    │
│ Findings: bypass!   │              │  found a bypass..." │
└────────────────────┘              └────────────────────┘
              Same state.md on disk

• Hunt in Code → findings saved to state.md
• Review in Cowork → /claude-memory:recall loads your full state
• Set goals in Cowork → Code picks them up on next session start
• Crash Code? → open Cowork, your memory is on disk, nothing lost

Session 1: You build something complex over 2 hours
            ↓ context fills up
            ↓ auto-compact fires 💥
Session 1 (continued): Claude forgot everything 🤷
            ↓ terminal crashes
Session 2: Total amnesia. "What were we working on?" 😶

v2 introduces state.md — a living document that Claude actively maintains:

# Session State
> Last updated: 14:30

## Goal
Build the user authentication system with JWT tokens

## Progress
- [x] Set up database schema
- [x] Implement login endpoint
- [ ] Add token refresh logic
- [ ] Write integration tests

## Findings
- Auth middleware needs to handle expired tokens gracefully
- Rate limiting should be per-user, not per-IP

Why this works: state.md lives on disk, not in context. When auto-compact fires, state.md is untouched. Claude reads it back and picks up exactly where it left off.

Every piece of state is also backed up as a state snapshot in .mci:

┌─────────────────────────────────────────────────────────┐
│ 🟢 SessionStart                                         │
│    → Creates/resumes session + state.md template         │
│    → Loads last .mci (cascades up to 7 days back)        │
│    → Detects crashes & recovers automatically            │
│    → First-run: copies templates, onboards Claude        │
├─────────────────────────────────────────────────────────┤
│ 🔵 UserPromptSubmit (every prompt)                       │
│    → Checks state.md health (exists? updated?)           │
│    → Auto-checkpoints state.md every ~10 prompts         │
│    → Estimates context usage & warns before compact ⚠️   │
│    → Captures legacy markers as backup                   │
├─────────────────────────────────────────────────────────┤
│ 🟠 PreCompact (before auto-compact)                      │
│    → Snapshots FULL state.md content to .mci             │
│    → 3-tier fallback: state.md → markers → JSONL         │
│    → Creates conversation backup 💾                      │
├─────────────────────────────────────────────────────────┤
│ 🔴 Stop (session end)                                    │
│    → Snapshots state.md to .mci                          │
│    → Generates session summary 📊                        │
└─────────────────────────────────────────────────────────┘

1. 📂 Creates .claude-memory/sessions/ directory
2. 📝 Creates state.md — your living state file (Claude's external brain)
3. 🎭 Copies IDENTITY.md and PREFERENCES.md templates to your project
4. 🧠 Injects v2 rules so Claude understands state.md immediately
5. 💬 Guides Claude through a first-run welcome message

/plugin marketplace update hlsitechio
/plugin update claude-memory@hlsitechio

For full control or if you want to customize the hooks:

git clone https://github.com/hlsitechio/claude-memory.git
cd claude-memory
./install.sh /path/to/your/project

The installer will:

1. 📂 Copy 4 hook scripts to your project's .claude/hooks/
2. 📄 Install CLAUDE.md with v2 rules
3. ⚙️ Generate .claude/settings.local.json with hook configuration
4. 🗂️ Create the .claude-memory/sessions/ directory
5. 🎭 Optionally install identity templates (IDENTITY.md, PREFERENCES.md)

state.md is your primary recovery mechanism. It lives on disk, completely outside the context window. When compact fires:

1. Pre-compact hook snapshots state.md → .mci (automatic)
2. Anthropic's black box compact compresses the conversation
3. SessionStart fires, tells Claude: "Read state.md"
4. Claude reads Goal/Progress/Findings and resumes work

No data loss. No "what were we doing?" No amnesia.

If the terminal crashes (Stop hook never fires):

1. On next startup, SessionStart detects the crash (no end marker)
2. Loads the .mci from the crashed session
3. state.md is still on disk — full state preserved
4. Injects a CRASH RECOVERY block telling Claude what happened
5. Claude resumes — no questions asked

Every ~10 prompts, the hook auto-snapshots state.md to .mci. Even if Claude never manually saved and the terminal crashes, there's recent state.

When loading memory, SessionStart searches:

current session .mci
  → previous session (timed out)
    → earlier sessions today
      → yesterday → ... → up to 7 days back

In v2, markers are primarily display formatting. The real memory lives in state.md.

The prompt-capture hook still watches for markers in Claude's responses and auto-saves them to facts.md/context.md/intent.md. This is backward compatibility — state.md is primary.

When Claude writes:

[!] Found that the API rate limit can be bypassed by rotating User-Agent headers

v2 behavior: Claude should also Edit the Findings section of state.md. Legacy backup: The hook auto-captures it to facts.md.

The .mci file is auto-generated by hooks as a safety net:

--- [PC] state.md Snapshot @ 14:30:00 ---
Memory: GOAL: Build the user filtering API with pagination support
Context: PROGRESS: - [x] Database schema designed\n- [x] GET endpoint working\n- [ ] Add filters
Intent: FINDINGS: Auth bypass found in middleware — blocks release until fixed

🛡️ In v2, you rarely need to think about .mci. The hooks handle it automatically by snapshotting state.md.

.claude-memory/
├── current-session          ← pointer to active session
└── 📂 sessions/
    └── 📂 2026-02-20/
        ├── 📂 session-1/
        │   ├── 📝 state.md           ← YOUR EXTERNAL BRAIN (v2 primary)
        │   ├── 📄 facts.md           ← 🔴 [!] legacy backup
        │   ├── 📄 context.md         ← 🟡 [*] legacy backup
        │   ├── 📄 intent.md          ← 🟢 [>] legacy backup
        │   ├── 📄 memory.md          ← 🔵 [i] entries + session log
        │   ├── 🛡️ memory.mci         ← auto-generated safety net
        │   ├── 💾 compact-*.md       ← conversation backups
        │   └── 📊 session-summary.md ← tool stats, files modified
        └── 📂 session-2/
            └── ...

Plugin hooks are configured automatically via hooks.json. No manual setup needed.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|clear|compact",
        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/session-start.js\"", "timeout": 30 }]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/prompt-capture.js\"", "timeout": 5 }]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pre-compact.js\"", "timeout": 30 }]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/session-stop.js\"", "timeout": 30 }]
      }
    ]
  }
}

For git-clone installs, the installer generates .claude/settings.local.json:

{
  "hooks": {
    "SessionStart": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh\"" }] }
    ],
    "UserPromptSubmit": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/prompt-capture.sh\"", "timeout": 5 }] }
    ],
    "PreCompact": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/pre-compact.sh\"" }] }
    ],
    "Stop": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-stop.sh\"", "timeout": 30 }] }
    ]
  }
}

Battle-tested over 100+ sessions spanning 2 months.

MIT — see LICENSE

• Breaking: Replaced append-only marker files with single state.md living document
• New: state.md with Goal/Progress/Findings sections — Claude's external brain
• New: Cross-platform support — Claude Code + Claude Cowork share the same state.md
• New: Pre-compact snapshots FULL state.md content (not just last line)
• New: 3-tier fallback: state.md → marker files → JSONL transcript
• New: Auto-checkpoint every ~10 prompts snapshots state.md to .mci
• New: state.md health monitoring in prompt-capture hook
• Improved: Post-compact recovery reads state.md directly — no data loss
• Improved: Markers simplified to display formatting + legacy auto-capture
• Backward Compatible: Legacy marker files still created and populated

• Plugin marketplace support
• 7-day .mci cascade for session recovery
• Crash detection and auto-recovery
• Cross-platform Node.js hooks

• Persistent state memory system
• 4 lifecycle hooks (SessionStart, UserPromptSubmit, PreCompact, Stop)
• Marker-to-file contract
• Session management with date-based directories

Issues and pull requests welcome!

🐛 Report Bug   •   💡 Request Feature   •   ⭐ Star the Repo

_{Built with 🧠 by hlsitechio — giving Claude a memory it deserves.}