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

``bash
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 │
└─────────────────────────────────────────────────┘
`

$3

Both your messages AND Claude's responses are saved, including:
- Files and functions mentioned
- Errors discussed
- Decisions made

$3

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
`

$3

- 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

$3

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.

$3

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

Commands

`bash


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

`bash
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.

$3

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

$3

| 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\

$3

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

$3

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

`bash
npm uninstall -g @alucardeht/claude-memory
`

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

License

MIT