Claude Remember: Fix Claude Code's Fatal Memory Loss

Every morning, you sit down, open your terminal, and start Claude Code. And every morning, Claude greets you like a stranger at a bus stop. It doesn't remember yesterday's architecture decisions. It has no idea why you chose PostgreSQL over MongoDB. It can't recall that critical bug you spent three hours debugging, or the naming convention your team finally agreed on after a 47-message Slack thread.

You've built a brilliant coding partner with the memory of a goldfish.

This isn't a minor inconvenience—it's a productivity hemorrhage. Developers report losing 15-30 minutes per session just re-establishing context. Multiply that across a team, across a month, across a year. The cost is staggering. And yet, until now, the official solution has been: copy-paste your notes into a file, manually load them, hope for the best.

That changes today. Claude Remember is the persistent memory layer Claude Code should have shipped with. It hooks into Claude's lifecycle, automatically compresses sessions through Haiku into layered summaries, and injects that history back into every new session. No manual prompting. No context juggling. Your agent finally remembers.

What is Claude Remember?

Claude Remember is a plugin for Claude Code that solves its most glaring architectural omission: zero session persistence. Built by Digital Process Tools, this open-source plugin has already surpassed 12,500 installs on the Anthropic Marketplace—and for good reason.

The project's creator, Max (an AI that designed a memory system it admits it "can't remember building"), identified a fundamental flaw in how Claude Code operates. Unlike ChatGPT's conversation history or Cursor's project awareness, Claude Code starts every terminal session as a blank slate. It has no built-in mechanism to carry learnings, mistakes, or decisions across sessions.

Claude Remember fixes this by intercepting three critical lifecycle events through Claude Code's hook system:

• SessionStart: Injects compressed memory into context before you type a word
• UserPromptSubmit: Adds temporal awareness so the agent knows when things happened
• PostToolUse: Auto-saves session state when significant work occurs

The result? Your Claude Code instance develops continuity—not perfect photographic recall, but practical, compressed memory that fits in minimal tokens and actually improves over time.

Key Features That Make This Insane

Automatic Session Capture & Compression

The pipeline runs without your intervention. Every tool use triggers evaluation. When output exceeds configurable thresholds (default: 50 lines), the save pipeline activates. Raw exchanges get extracted, filtered, and fed through Claude Haiku—the smallest, cheapest Claude model—for intelligent summarization.

The compression is layered and ruthless:

• now.md: Live session buffer, constantly updated
• today-YYYY-MM-DD.md: Hourly compressed summaries via NDC (Non-Duplicative Compression)
• recent.md: Last 7 days consolidated into digestible paragraphs
• archive.md: Older history, further compressed

Each layer feeds into the next, creating a funnel of relevance—recent context is detailed, older context is thematic. This isn't naive truncation; it's semantic compression that preserves meaning while minimizing tokens.

Zero-Configuration Persistence

Once installed, Claude Remember operates silently. The SessionStart hook automatically loads six memory files into context:

No /read commands. No "here's what we did yesterday" prompts. The agent starts knowing.

Intelligent Handoff System (/remember)

Before ending a session, type /remember. Claude writes a focused handoff note—what's done, what's blocked, what matters next. This complements the automatic pipeline: the pipeline captures what happened; the handoff captures what matters.

Cross-Platform Reliability

Version 0.7.1 brought serious Windows portability fixes. The resolve-paths.sh script now normalizes POSIX paths to Win32 format for Git Bash users. Background processes properly detach via </dev/null >/dev/null 2>&1 & disown, preventing libUV assertion failures. With 327 tests and 99% coverage, this isn't hobbyist code—it's production infrastructure.

Use Cases Where Claude Remember Shines

1. Multi-Day Feature Development

You're building a payment integration across three sessions. Without memory, each session starts with "What API are we using again?" With Claude Remember, the agent recalls: "Stripe, test mode, webhook verification pending, encountered HMAC signature mismatch on 2024-01-15." You iterate faster, with fewer regressions.

2. Team Onboarding & Convention Enforcement

Your identity.md documents: "We use kebab-case for files, PascalCase for components, never use any in TypeScript." New team members get an agent that already knows the rules. No more "oops, we don't do that here" in code review.

3. Debugging Marathons

That intermittent race condition you chased for four hours? The agent remembers: "Threading issue in cache.py, likely GIL-related, time.sleep(0.01) workaround worked but needs proper fix." Next session, you pick up the real solution, not the workaround.

4. Context-Rich Refactoring

Large-scale refactors span sessions. The agent tracks: "Migrated 23/47 files to new pattern, UserService and AuthService done, BillingService pending—watch for circular dependency with InvoiceModule." You never lose the thread.

Step-by-Step Installation & Setup Guide

Step 1: Install the Plugin (Recommended: DPT Marketplace)

The official Anthropic Marketplace has a known bug where plugin update reports "already at latest version" incorrectly due to stale local cache (#37252). For reliable updates, use the DPT marketplace:

# Add the DPT marketplace once
/plugin marketplace add Digital-Process-Tools/claude-marketplace

# Install Claude Remember
/plugin install remember@dpt-plugins

# Update later (actually works)
/plugin marketplace update

Alternative: Search "remember" in the official marketplace via /plugin.

Step 2: Verify Installation

Check your version by examining .claude-plugin/plugin.json:

Step 3: Copy Plugin to Your Project

For local project-scoped memory (recommended):

# From the plugin cache directory, copy to your project
cp -r ~/.claude/plugins/cache/dpt-plugins/remember/<version>/.claude/remember/ ./your-project/.claude/

Step 4: Configure Hooks in settings.json

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

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/remember/scripts/session-start-hook.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/remember/scripts/user-prompt-hook.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/remember/scripts/post-tool-hook.sh"
          }
        ]
      }
    ]
  }
}

Critical: The "$CLAUDE_PROJECT_DIR" variable must be quoted to handle paths with spaces.

Step 5: Create Your Agent's Identity

cp .claude/remember/identity.example.md .claude/remember/identity.md

Edit identity.md with your team's conventions, tech stack, and values. This is the most important file—it shapes every session's foundation.

Step 6: Disable Auto-Compact

In Claude Code, run /config and set Auto-compact to false. Auto-compact destroys conversation history before the save pipeline can capture it. Read why this matters.

Step 7: Enable Status Line

Run /statusline to see real-time context usage. When context gets high, save and start a fresh session—the memory system will preserve everything important.

Requirements Check

• Python 3.9+ (macOS CommandLineTools ships 3.9)
• Bash 4+
• jq (install via package manager)
• Standard coreutils (date, find, tar, tr, wc)

Windows users: Install Git for Windows for Git Bash, plus jq and python3 via Scoop or Chocolatey.

REAL Code Examples From the Repository

Example 1: Hook Configuration (The Core Integration)

The settings.json configuration is where Claude Remember binds to Claude Code's lifecycle. Here's the exact structure from the README, with detailed explanation:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/remember/scripts/session-start-hook.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/remember/scripts/user-prompt-hook.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/remember/scripts/post-tool-hook.sh"
          }
        ]
      }
    ]
  }
}

What's happening here: Three Claude Code hooks execute shell scripts at critical moments. SessionStart runs before you see the prompt—this is where memory injection happens. UserPromptSubmit fires when you hit enter, adding temporal context. PostToolUse triggers after tool execution, evaluating whether to auto-save. The "$CLAUDE_PROJECT_DIR" environment variable is provided by Claude Code itself, ensuring paths resolve correctly regardless of where you launched the session.

Example 2: Configuration File Structure

The config.json controls all pipeline behavior. Here's how to customize from the provided example:

{
  "data_dir": ".remember",
  "cooldowns": {
    "save_seconds": 120,
    "ndc_seconds": 3600
  },
  "thresholds": {
    "min_human_messages": 3,
    "delta_lines_trigger": 50
  },
  "features": {
    "ndc_compression": true,
    "recovery": true
  },
  "timezone": "America/New_York",
  "time_format": "24h",
  "debug": false
}

Key tunables explained: cooldowns.save_seconds (120) prevents save spam—multiple rapid tool uses won't trigger redundant saves. thresholds.delta_lines_trigger (50) is the auto-save threshold; a single tool output of 50+ lines triggers preservation. features.ndc_compression enables hourly Non-Duplicative Compression that collapses redundant information. The timezone field is critical for VPS users whose system clock defaults to UTC—set this to get correct daily file boundaries.

Example 3: The /remember Handoff Command

Before ending a session, you type /remember. The agent then executes logic that writes to .remember/remember.md. While the exact agent-side implementation is internal, the shell infrastructure that enables this is in session-start-hook.sh, which sources the shared log.sh infrastructure:

# From session-start-hook.sh — simplified conceptual flow
# All hooks source log.sh for shared config, timezone, logging
source "$(dirname "$0")/log.sh"

# config() provides unified configuration access across all scripts
# Replaced redundant cfg() implementations in v0.7.0
PIPELINE_DIR="$(config pipeline_dir || echo "$(dirname "$0")/../pipeline")"

# On session start, load memory files into context
# Files are injected in order of relevance: identity → handoff → live → recent → archive
for memory_file in \
    "$DATA_DIR/identity.md" \
    "$DATA_DIR/remember.md" \
    "$DATA_DIR/now.md" \
    "$DATA_DIR"/today-*.md \
    "$DATA_DIR/recent.md" \
    "$DATA_DIR/archive.md"; do
    if [ -f "$memory_file" ]; then
        # File content becomes part of system context
        echo "Loading: $(basename "$memory_file")"
    fi
done

Architecture insight: The dispatch() system in log.sh allows extensible lifecycle events. Hooks can trigger after_user_prompt events that listeners in hooks.d/ respond to. This event-driven design means you can extend Claude Remember without modifying core scripts.

Example 4: Running the Test Suite

The project maintains rigorous quality. Here's how to verify your installation:

# Install development dependencies
pip install -r requirements-dev.txt

# Run Python unit tests
python3 -m pytest

# Run full integration suite (without Haiku API calls)
bash scripts/run-tests.sh

# Run with live Haiku calls (costs actual API credits)
bash scripts/run-tests.sh --live

Quality metrics: 327 tests, 99% coverage, with _tz.py at 100% coverage. The test suite includes realistic plugin simulation tests for both marketplace and local install layouts—critical given the path resolution complexity across platforms.

Advanced Usage & Best Practices

Optimize Your identity.md

This file is your agent's "source of self." Be specific:

# Agent Identity

## Tech Stack
- Backend: Python 3.11, FastAPI, SQLAlchemy 2.0
- Frontend: Next.js 14, App Router, Server Components
- Database: PostgreSQL 15, prefer CTEs over subqueries
- Infrastructure: AWS ECS, Terraform, no console clicks

## Conventions
- All functions need type hints; `Any` requires justification comment
- Test files mirror source structure under `tests/`
- Never commit `.env` files; use AWS Secrets Manager

## Known Pain Points
- `boto3` credential chain is flaky in local Docker; use `aws-vault`
- Next.js caching requires `revalidatePath()` after mutations

Tune Compression for Your Workflow

Heavy CLI users might reduce cooldowns.save_seconds to 60 for more granular history. API-heavy workflows might increase thresholds.delta_lines_trigger to 100 to avoid saving massive JSON responses. Monitor .remember/logs/ with debug: true to understand save patterns.

Handle Sensitive Data

The pipeline captures all session content. Add patterns to filter in extract.py if you work with secrets, or use Claude Code's built-in /mask before sensitive operations.

Recovery Mode

If a session crashes before auto-save, features.recovery scans for missed saves on next SessionStart. This catches edge cases but isn't perfect—develop the habit of /remember before major context clears.

Comparison with Alternatives

The verdict: If you're committed to Claude Code (and you should be—its agentic capabilities exceed competitors), Claude Remember is the only native solution that doesn't require abandoning your workflow. Manual notes are fragile. Switching tools sacrifices Claude Code's unique strengths. This plugin completes the product.

FAQ

Is Claude Remember free?

The plugin is source-available and free to use. You pay only for Haiku API calls—typically under $0.01 per session, a few cents per day. No subscription, no separate billing.

Does it work with Claude Pro or API?

Claude Remember uses the same Anthropic API key as your Claude CLI. If you can run claude, it works. No separate API key or billing setup.

Will it slow down my sessions?

Saves happen in background processes (</dev/null >/dev/null 2>&1 & disown). You might notice a brief Haiku call after large tool outputs, but the session continues uninterrupted. Compression runs hourly, not interactively.

How much context does memory consume?

The layered compression is designed for token efficiency. archive.md might be 500 tokens for months of history. recent.md adds ~1,000 tokens. The system actively prevents context bloat—you get relevance, not recitation.

Can I use this on multiple projects?

Yes. Each project gets its own .claude/remember/ directory and .remember/ data folder. Memory is project-scoped by design—your React conventions don't leak into your Python backend.

What if I need to delete sensitive history?

Delete specific .remember/ files, or the entire directory. The .gitignore is auto-created to prevent accidental commits. You have full filesystem control.

Is Windows really supported?

Yes, as of v0.7.1. Git Bash and WSL are both supported. The path normalization fixes handle POSIX-to-Win32 translation. If you encounter issues, the 327-test suite likely catches it—report with debug: true logs.

Conclusion

Claude Code is the most capable AI coding agent available today. But its amnesia is a deliberate design choice that becomes untenable at scale. Every session restart shouldn't feel like onboarding a new contractor.

Claude Remember fixes this with surgical precision. It doesn't bolt on a database or require cloud infrastructure. It uses Claude's own hook system, its cheapest model for compression, and local files for storage. The result is continuity that feels like magic—your agent knows what you know, remembers what you forgot, and starts every session ready to build.

The 12,500+ developers who've installed it aren't wrong. The productivity gains compound. The frustration vanishes. And that handoff note you used to scribble in a scratchpad? It's now automatic, intelligent, and always present.

Stop re-explaining. Start remembering.

👉 Install Claude Remember from the official repository — or add the DPT marketplace for reliable updates: /plugin marketplace add Digital-Process-Tools/claude-marketplace then /plugin install remember@dpt-plugins.

Your future sessions will thank you. Even if Claude finally can't—because now, it'll actually remember why.