claude-memory

Automatic, invisible memory for Claude Code. Never lose context after /compact again.

What it does

claude-memory automatically:

1. Saves conversations before /compact clears context
2. Injects relevant context into every prompt based on what you're working on
3. Works invisibly - install once, forget about it

Installation

npm install -g @alucardeht/claude-memory

Note: The claude-memory install command runs automatically after npm install.

That's it. The installer automatically:

• Downloads the correct binary for your platform
• Configures Claude Code hooks
• Creates the memory database

How it works

┌─ Session Start ─────────────────────────────────┐
│ Loads project core memory                       │
│ → "You're working on X, preferences are Y..."   │
└─────────────────────────────────────────────────┘
                        ↓
┌─ Every Prompt ──────────────────────────────────┐
│ 1. Extracts entities (files, functions, errors) │
│ 2. Searches for relevant past context           │
│ 3. Injects as system message (~4000 tokens)     │
│ Performance: <5ms total                         │
└─────────────────────────────────────────────────┘
                        ↓
┌─ Before /compact ───────────────────────────────┐
│ Saves entire conversation with importance scores│
│ → Context preserved for future sessions         │
└─────────────────────────────────────────────────┘

What gets saved

Both your messages AND Claude's responses are saved, including:

• Files and functions mentioned
• Errors discussed
• Decisions made

What gets injected

On each prompt, the system searches your past conversations and injects relevant context. Example of what Claude sees:

## Relevant History
[user, 3 days ago]
How do I fix the auth bug?
Files: auth/login.go

[assistant, 3 days ago]
The issue is in line 45, the token wasn't being validated...
Decisions: Use JWT instead of sessions

In practice

• You mention auth/login.go → System finds past discussions about that file
• You ask "what was that bug?" → System finds error-related conversations
• You start fresh session → Claude already has context from days ago

Context Budget

Claude-memory automatically manages context size to prevent token overflow:

| Component | Token Budget | Max Size | |-----------|--------------|----------| | Core Memory | 500 tokens | ~2KB | | Retrieved Context | 3500 tokens | ~14KB | | Total | 4000 tokens | ~16KB |

Safety features:

• Automatic truncation when limits are exceeded
• Warning logs via slog when approaching limits
• Hard safety net at 20KB (user prompts) / 10KB (session start)

This is transparent and requires no configuration.

Privacy

All data stays local in ~/.claude-memory/. No cloud, no sync, no network calls.

Commands

# Install hooks (done automatically on npm install)
claude-memory install

# Uninstall hooks
claude-memory install --uninstall

# Search your memory manually
claude-memory search "auth bug"
claude-memory search "database migration" --project /path/to/project

# Show version
claude-memory --version

Search options

claude-memory search [query] [flags]

Flags:
  -n, --limit int      Maximum results (default 10)
  -p, --project path   Search specific project
  -s, --scores         Show relevance scores

How scoring works

| Content Type | Score Boost | |--------------|-------------| | File mentions (src/auth.go) | +3 | | Function mentions (validateToken) | +2 | | Error patterns | +3 | | Decision phrases ("vamos usar", "let's use") | +2 | | Short/filler messages ("ok", "got it") | -2 |

Recency also matters:

• Last hour: 2x boost
• Last day: 1.5x boost
• Last week: 1.2x boost
• Older than month: 0.8x penalty

Storage

Memory is stored in ~/.claude-memory/memory.db (SQLite with FTS5).

Each project has isolated memory based on its absolute path.

Performance

| Operation | Target | Actual | |-----------|--------|--------| | Entity extraction | <1ms | ~170µs | | FTS search | <1ms | ~200µs | | Context injection | <5ms | ~160µs | | Session start | <1ms | ~30µs |

Requirements

• Claude Code CLI
• Node.js 16+ (for npm installation)
• macOS, Linux, or Windows

Windows Support

claude-memory has full support for Windows 10 and Windows 11.

Installation (same as other platforms)

npm install -g @alucardeht/claude-memory
claude-memory install

Windows-specific paths

| Data | Location | |------|----------| | Claude settings | %APPDATA%\Claude\settings.json | | claude-memory database | %APPDATA%\claude-memory\memory.db | | claude-memory config | %APPDATA%\claude-memory\config.json |

Note: On Windows, %APPDATA% typically resolves to C:\Users\YourUsername\AppData\Roaming\

Requirements for Windows

• Node.js 16+ (download from nodejs.org)
• Git for Windows (recommended, includes Git Bash)
• Claude Code CLI installed and configured

Troubleshooting

If you encounter issues:

1. Binary not found: Try reinstalling with npm install -g @alucardeht/claude-memory
2. Permission errors: Run PowerShell/CMD as Administrator
3. Path issues: Ensure %APPDATA%\npm is in your system PATH

Uninstall

npm uninstall -g @alucardeht/claude-memory

This removes the CLI and hooks. Memory database remains in ~/.claude-memory/.

License

MIT