Claude Mnemonic

Give Claude Code a memory that actually remembers.

Claude Code forgets everything when your session ends. Claude Mnemonic fixes that.

It captures what Claude learns during your coding sessions - bug fixes, architecture decisions, patterns that work - and brings that knowledge back in future conversations. No more re-explaining your codebase.

What's New in v0.7

• Two-Stage Retrieval - Cross-encoder reranking for dramatically improved search relevance
• Knowledge Graph - Automatic relationship detection between observations with visual graph in dashboard
• Pattern Detection - Identifies recurring patterns across sessions and projects
• Importance Scoring - Time decay and voting system to surface the most valuable memories
• Query Expansion - Reformulates searches to find semantically related content
• Conflict Detection - Identifies and resolves contradictory observations
• Observation Lifecycle - Memories can be superseded when better information arrives

Requirements

That's it. No Python. No external services. Everything runs locally.

No API keys needed! Claude Mnemonic uses Claude Code CLI, which works with your existing Claude Pro or Max subscription. No separate API costs.

Install

One command. That's it.

curl -sSL https://raw.githubusercontent.com/lukaszraczylo/claude-mnemonic/main/scripts/install.sh | bash

irm https://raw.githubusercontent.com/lukaszraczylo/claude-mnemonic/main/scripts/install.ps1 | iex

git clone https://github.com/lukaszraczylo/claude-mnemonic.git
cd claude-mnemonic
make build && make install

After install, open http://localhost:37777 to see the dashboard. Start a new Claude Code session - memory is now active.

Verifying Release Signatures

All release checksums are signed with cosign using keyless signing. To verify:

# Download the checksum file and its sigstore bundle from the release
cosign verify-blob \
  --certificate-identity-regexp "https://github.com/lukaszraczylo/claude-mnemonic/.*" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  --bundle "checksums.txt.sigstore.json" \
  checksums.txt

What it does

How knowledge flows

You code with Claude
        ↓
Claude learns something useful
        ↓
Mnemonic captures it automatically
        ↓
Next session: Claude remembers

Behind the scenes: hooks capture Claude's observations → SQLite stores with full-text search → sqlite-vec enables semantic search with local embeddings (all-MiniLM-L6-v2) → relevant context is injected at session start.

Configuration

Config file: ~/.claude-mnemonic/settings.json

{
  "CLAUDE_MNEMONIC_WORKER_PORT": 37777,
  "CLAUDE_MNEMONIC_CONTEXT_OBSERVATIONS": 100,
  "CLAUDE_MNEMONIC_CONTEXT_FULL_COUNT": 25,
  "CLAUDE_MNEMONIC_RERANKING_ENABLED": true
}

Core Settings

Reranking Settings (Two-Stage Retrieval)

Embedding Settings

All variables are prefixed with CLAUDE_MNEMONIC_ in the config file.

Project vs Global scope

Observations are automatically scoped:

• Project scope (default) - stays within the project directory
• Global scope - shared everywhere

Global scope triggers on tags like: best-practice, security, architecture, pattern, performance

Example: A bug fix in your auth module stays local. "Always validate JWT server-side" goes global.

MCP Tools

Four tools are exposed via MCP:

• search - semantic search across all memories. Accepts obs_type (e.g. decision, code_change, architecture) plus filter params (concepts, files, type) - these replace the old per-type shortcut tools.
• timeline - browse observations around a point in time.
• observation - manage individual observations. Set action to one of: get, edit, delete, supersede, boost, merge, related, similar, quality, relationships, scoring, tag, by_tag, batch_tag.
• memory_admin - administration and analytics. Set action to one of: stats, health, maintenance_stats, run_maintenance, importance, search_patterns, explain_ranking, temporal_trends, data_quality, export, suggest_consolidations, patterns.

Slash Commands

Available commands within Claude Code:

Auto-Updates

Claude Mnemonic automatically checks for updates and applies them. Updates are downloaded in the background and applied on restart.

• Automatic update checks on startup
• Background downloads (up to 250MB)
• Seamless restart after update
• Manual trigger: curl -X POST http://127.0.0.1:37777/api/update/apply

Check update status: curl http://127.0.0.1:37777/api/update/status

Troubleshooting

Worker won't start?

lsof -i :37777              # check if port is in use
cat /tmp/claude-mnemonic-worker.log  # view logs

Database locked?

rm -f ~/.claude-mnemonic/*.db-wal ~/.claude-mnemonic/*.db-shm

Worker unresponsive?

# Restart via API
curl -X POST http://127.0.0.1:37777/api/restart

# Or use the slash command in Claude Code
/restart

Check health status:

curl http://127.0.0.1:37777/api/selfcheck

Uninstall

# Remove everything
curl -sSL https://raw.githubusercontent.com/lukaszraczylo/claude-mnemonic/main/scripts/uninstall.sh | bash

# Keep your data
curl -sSL https://raw.githubusercontent.com/lukaszraczylo/claude-mnemonic/main/scripts/uninstall.sh | bash -s -- --keep-data

Architecture

• SQLite + FTS5 - Full-text search for exact matches
• sqlite-vec - Vector database embedded in SQLite
• Two-Stage Retrieval - Bi-encoder (embedding) + cross-encoder (reranking) for high accuracy
• Local Models - all-MiniLM-L6-v2 for embeddings, BGE reranker for relevance scoring
• Go - Single binary, no external dependencies

Everything runs locally. No Python. No external vector database. No API calls.

Platform support

Development

make build          # build all
make test           # run tests
make dev            # dev mode with hot reload
make install        # install to Claude plugins

License

MIT

Links: Releases · Issues