Claude Memory Manager

An automated, self-organizing memory system for Claude Code. Install once and Claude Code gains persistent, cross-session memory that works from any directory — no copy-paste, no manual tool calls, no reliance on Claude remembering to save.

The goal: after setup, Claude should always have relevant context from your past conversations, in every new session, without you thinking about it.

---

Screenshots

Home — topics grid with auto-organize status	Topic detail — markdown preview + edit mode
Search — FTS5 with highlighted snippets	Settings — per-config hook + MCP status

---

What it does

1. Ingests your existing Claude Code memory files (~/.claude*/projects/*/memory/) into a central SQLite store.
2. Injects relevant memories automatically into every Claude Code session via a UserPromptSubmit hook — Claude sees matching memories before it processes each message, ranked with project affinity so memories from the project you're in float to the top.
3. Nudges Claude to save — the same hook also emits a save-checklist on every prompt and a correction-detected block when your message looks like pushback, so corrections and preferences don't slip past unsaved.
4. Saves new memories when Claude decides to (via an MCP memory_add tool) or when you use a remember: directive in your prompt.
5. Organizes automatically — a 4-phase AI pass (classify → dedup → consolidate → split oversized topics) runs on launch to keep the store clean. Every destructive step is snapshotted to a history log so you can undo.
6. Updates itself — Settings → Updates checks GitHub Releases and installs signed updates with one click.
7. Exports / imports — back the whole store up to JSON, restore on a new machine in merge or replace mode.
8. Lives in your menu bar — runs as a macOS tray icon next to the clock. Right-click for "Open Dashboard" or "Quit". No Dock icon, no window clutter.
9. Provides a tiny UI for browsing, searching, and editing memories when you want to — the app is meant to be mostly invisible.

How it works

┌─────────────────────────────────────┐         ┌──────────────────────────┐
│  Your Claude Code session           │         │  Claude Memory Manager   │
│  (any directory, any project)       │         │  (Tauri desktop app)     │
└────────────────┬────────────────────┘         └────────────┬─────────────┘
                 │                                            │
                 │  1. You type a message                     │
                 │  ────────────────────────────────────▶     │
                 │                                            │
                 │  2. UserPromptSubmit hook runs             │
                 │     (claude-memory-manager --hook)         │
                 │  ◀────────────────────────────────────     │
                 │                                            ▼
                 │                               ┌──────────────────────┐
                 │                               │   SQLite + FTS5      │
                 │                               │   Full-text search   │
                 │                               │   ~5ms per query     │
                 │                               └──────────┬───────────┘
                 │                                           │
                 │  3. Top memories injected as context     │
                 │  ◀──────────────────────────────────     │
                 │                                           │
                 │  4. Claude replies — optionally           │
                 │     calling `memory_add` via MCP          │
                 │  ─────────────────────────────────▶      │

Two independent pathways feed into the store:

• UserPromptSubmit hook (reads + nudges) — fires on every user message and emits up to three blocks: a <memory-context> block (top hits from a hybrid search: FTS5 + 1-hop graph expansion + project-affinity re-ranking), a <memory-save-checklist> block (always, listing save-worthy signals so Claude self-checks before replying), and a <memory-correction-detected> block (when the prompt matches correction heuristics like "no", "actually", "wait", "you missed", etc.).
• MCP server (reads & writes) — exposes memory_search, memory_add, memory_get, memory_list, and memory_related tools for Claude to call when it needs targeted lookups or wants to save something new. Registered at user scope (claude mcp add --scope user).

Both are installed automatically when you click "Get started" the first time.

Key features

Automatic memory retrieval (the reason this exists)

Prior to this tool, Claude Code memories only help if Claude happens to call memory_search in a session. Most sessions don't. The UserPromptSubmit hook fixes that: every message Claude sees, it already has the relevant memories in context. No tool call overhead, no Claude forgetting.

Project-aware retrieval

The hook detects which project you're working in (transcript-inferred, with the cwd as a fallback) and re-ranks results so memories scoped to that project float to the top while cross-project results are slightly demoted. Project context is also passed through to memory_add and memory_search MCP calls so Claude saves new project memories with the right scope automatically. Retrieval itself is hybrid — FTS5 over-fetches candidates, then 1-hop graph expansion pulls in co-accessed neighbors before re-ranking.

Save-checklist + correction nudges

Reading memories isn't enough — Claude also has to save corrections, preferences, and project facts as it learns them. The hook appends a <memory-save-checklist> to every prompt listing the signals worth saving, and prepends a <memory-correction-detected> block whenever your message matches correction heuristics ("no", "don't", "actually", "wait", "you missed", etc.). The combination dramatically increases in-turn memory_add calls vs. relying on Claude to remember on its own.

AI-powered organization

On every launch (or manually), the organizer runs a 4-phase pass:

• Classify untopiced memories into topics via claude -p (batched, 25 at a time)
• Dedup within each topic — merges near-duplicates with full content reconciliation
• Consolidate overlapping topics — merges single-member or semantically-redundant topics into broader ones
• Split oversized topics — when a topic grows past a threshold (configurable in Settings → Organization), the AI evaluates whether to split it into narrower sub-topics, with a per-topic growth guard so it only re-evaluates after meaningful change

Every destructive operation is snapshotted to a history log, so you can undo.

remember: directive

Type remember: <anything> (or /remember ..., !remember ...) in any Claude Code session. The hook intercepts it, saves the text to the store as a new memory, and tells Claude not to bother calling memory_add. Instant deterministic save.

Multi-account support

Detects all ~/.claude* directories automatically (.claude, .claude-personal, .claude-work, etc.), installs the hook + MCP server + bootstrap prompt in each one. Works out of the box for people running multiple Claude Code profiles via CLAUDE_CONFIG_DIR.

Menu bar app

The app runs as a macOS menu bar icon (next to Wi-Fi, clock, etc.) — it doesn't appear in the Dock. Click the tray icon to open a context menu:

• Open Dashboard — shows the main window
• Quit — exits the app

Closing the dashboard window hides it back to the tray rather than quitting. The hook and MCP server work independently of the window — they're invoked by Claude Code directly via the binary, so memory injection works whether the dashboard is open or not.

In-app updates

Settings → Updates checks the latest GitHub release, shows release notes for any new version, and downloads + installs the signed .app.tar.gz over the running app with one click. Updates are minisign-signed and rejected if the signature doesn't match the embedded public key. The app relaunches into the new version automatically.

Export / import

Settings → Memory store → Export JSON dumps every memory (with topics, edges, and project scopes) to a JSON file. Import accepts the same format in two modes: merge (additive, no deletions) and replace (wipes the existing store first — confirmed twice in the UI). Useful for moving between machines or for ad-hoc backups before risky organizer runs.

Tiny UI

• Home: topics grid with counts, one-click organize, status ribbon
• Topic detail: list of memories, preview/edit mode (markdown rendering), inline delete
• Search: FTS5 search across everything with highlighted snippets
• Settings: General · Updates · Claude Code integration (per-config hook + MCP status table) · Memory store (DB path, ingest, export/import) · Organization (auto-organize, split threshold, undo last) · Danger zone (clean uninstall)

Most users should rarely need to open the dashboard — it's the settings/maintenance panel for an otherwise invisible system.

Performance

Measured on an Apple M-series Mac, 42 memories in the store, release build:

Metric	Value
Hook invocation (per user message)	48–54 ms
FTS5 search over 42 memories	~5 ms
Token cost per turn	140–220 tokens
Dollar cost per turn (Sonnet)	~$0.0006
MCP server cold start	<100 ms
Settings page load	~40 ms

Latency stays flat as the store grows — FTS5 + WAL mode handles 10K+ memories comfortably. Short prompts (< 4 chars) short-circuit without running a query.

Versus the alternative (Claude calling memory_search as a tool): the hook is roughly 60× faster per turn and always runs, whereas tool calls require Claude to decide it needs context (which it often doesn't).

Architecture

• Rust (Tauri 2) backend
  • src-tauri/src/store/ — SQLite with FTS5 (porter tokenizer); memories / topics / edges / history / settings tables; WAL mode
  • src-tauri/src/services/hook.rs — UserPromptSubmit hook handler (stdin JSON in; emits <memory-context> + <memory-save-checklist> + <memory-correction-detected> blocks)
  • src-tauri/src/services/project.rs — Active-project detection (transcript-inferred → cwd fallback) and project-affinity scoring
  • src-tauri/src/services/mcp_server.rs — Minimal stdio MCP server (JSON-RPC, no heavy SDK)
  • src-tauri/src/services/organizer.rs — 4-phase pass: classify / dedup / consolidate / split-oversized
  • src-tauri/src/services/bootstrap.rs — Manages ~/.claude*/CLAUDE.md + settings.json
  • src-tauri/src/services/ingestion.rs — One-shot import of existing memory files
  • src-tauri/src/services/claude_api.rs — claude -p subprocess wrapper (with --strict-mcp-config to prevent MCP recursion)
• Vue 3 frontend
  • Single Pinia store (stores/app.ts)
  • 4 views: Home, Topic, Search, Settings
  • Markdown rendering via marked

The same binary has three modes, selected by command-line flag:

Mode	How invoked	What it does
UI (default)	claude-memory-manager	Menu bar tray icon + dashboard window
MCP server	claude-memory-manager --mcp-server	stdio JSON-RPC MCP protocol
Hook	claude-memory-manager --hook	Reads JSON from stdin, writes context to stdout

Install

Prerequisites

• macOS (arm64 prebuilt binary currently available — see Releases; other platforms need a source build)
• Claude Code CLI installed and authenticated (claude auth must work)
• Rust toolchain + Node.js 20+ (only needed for building from source)

From a release (recommended)

1. Grab the latest .dmg (or .zip) from Releases.
2. Move Claude Memory Manager.app to /Applications/.
3. Strip the macOS quarantine flag (one-time, see Troubleshooting if double-clicking shows "damaged"):

   xattr -dr com.apple.quarantine "/Applications/Claude Memory Manager.app"
   

4. Launch the app, click the menu-bar icon → Open Dashboard → Get started.

Future versions install themselves via Settings → Updates — see Updating.

From source

git clone https://github.com/byronfichardt/claude-memory-manager
cd claude-memory-manager

# Install frontend deps
npm install

# Build the release binary (takes ~1 minute)
cd src-tauri
cargo build --release
cd ..

# Run the UI
./src-tauri/target/release/claude-memory-manager

On first launch, the app appears as a small icon in your menu bar (top-right of the screen, next to the clock). Click it and select "Open Dashboard", then click Get started. The app will:

1. Scan ~/.claude*/projects/*/memory/ for existing memory files
2. Ingest them into ~/.claude-memory-manager/memories.db
3. Write a managed section to each ~/.claude*/CLAUDE.md
4. Register the MCP server in each Claude config (claude mcp add --scope user)
5. Install the UserPromptSubmit hook in each Claude config's settings.json
6. Auto-run an organize pass (if there are memories to classify)

After setup, open any Claude Code session — the hook will start injecting relevant memories automatically.

Dev mode

npm run tauri:dev

Spawns Vite + Tauri in watch mode. Frontend hot-reloads automatically; Rust changes require closing the app window so the dev process re-spawns the binary.

Build targets

Currently prebuilt:

Platform	Binary
macOS 15+ arm64 (Apple Silicon)	See Releases

Other platforms are source-buildable via cargo build --release, but untested.

Configuration

Everything is stored in ~/.claude-memory-manager/:

~/.claude-memory-manager/
├── memories.db         # SQLite database
├── memories.db-wal     # write-ahead log
└── memories.db-shm     # shared memory

If your endpoint protection tool watches dot-folders in $HOME and prompts on every access, you can override the DB location via the CLAUDE_MEMORY_DB_DIR environment variable — set it in Settings → Memory store, and the MCP server will be re-registered with the env var.

Per-Claude-config files the app writes to:

~/.claude/
├── CLAUDE.md           # managed section between <!-- claude-memory-manager:start --> markers
├── settings.json       # hook entry + MCP permission grant
└── .claude.json        # MCP server registration (managed by `claude mcp add`)

Everything outside those markers/keys is left untouched.

Updating

From v0.2.2 onward, the app updates itself:

1. Open the dashboard → Settings → Updates.
2. Click Check for updates. The app reads latest.json from the latest GitHub release.
3. If a new version is available, the release notes show inline. Click Install vX.Y.Z to download and apply the signed bundle, then the app relaunches.

Updates are minisign-signed against a public key embedded at build time; mismatched signatures are rejected. If the updater can't reach GitHub or finds no newer version, it tells you in the same row.

If you're on v0.2.1 or earlier, the in-app updater isn't present yet — download v0.2.2 manually from Releases, drop the .app into /Applications/, strip quarantine (see Troubleshooting), and you're set for the rest.

Uninstall

macOS doesn't run any code when you drag an app to the Trash, so Claude Memory Manager can't clean up automatically. Use the in-app button before removing the app bundle.

Recommended: in-app "Uninstall cleanly"

1. Open the dashboard → Settings → scroll to Danger zone.
2. Click Uninstall..., then Yes, delete everything to confirm.
3. The app:
   • Removes the UserPromptSubmit hook from every ~/.claude*/settings.json
   • Removes the mcp__claude-memory-manager permission entry
   • Runs claude mcp remove claude-memory-manager --scope user per config dir
   • Strips the managed section from every ~/.claude*/CLAUDE.md
   • Deletes ~/.claude-memory-manager/
4. Quit the app and drag Claude Memory Manager.app to the Trash.

The uninstall is destructive — your memory database is deleted. Back it up first (cp -a ~/.claude-memory-manager ~/.claude-memory-manager.backup) if you might want to restore later.

Manual fallback

If you've already dragged the app to the Trash and want to clean up the orphans:

# 1. Unregister MCP server (one per Claude config dir)
CLAUDE_CONFIG_DIR=~/.claude claude mcp remove claude-memory-manager --scope user
CLAUDE_CONFIG_DIR=~/.claude-personal claude mcp remove claude-memory-manager --scope user  # if present

# 2. Remove the managed section from each ~/.claude*/CLAUDE.md
#    (edit by hand — delete the block between <!-- claude-memory-manager:start --> and :end -->)

# 3. Remove the hook entry from each ~/.claude*/settings.json
#    (edit by hand — remove the entry from hooks.UserPromptSubmit that references claude-memory-manager)

# 4. Remove the mcp__claude-memory-manager permission from each ~/.claude*/settings.json

# 5. Delete the database
rm -rf ~/.claude-memory-manager

Troubleshooting

"Claude Memory Manager is damaged and can't be opened" on first launch

macOS is not saying the file is actually corrupted — it's a quarantine flag that Apple added to unsigned apps downloaded from the internet. The fix is one command:

xattr -dr com.apple.quarantine "/Applications/Claude Memory Manager.app"

(If the app isn't in /Applications yet, point at wherever the .app bundle lives — the mounted DMG path, ~/Downloads/, etc.)

After running that once, the app launches normally on double-click forever after. The command strips the com.apple.quarantine extended attribute that was added at download time.

To verify you got the real file (not a tampered one), compare its SHA-256 against the values in the release checksums file:

shasum -a 256 ~/Downloads/Claude-Memory-Manager_*_aarch64.dmg
# should match the value in checksums.sha256 from the release

The long-term fix is code-signing + notarization with an Apple Developer certificate. That's not done yet — if you want to eliminate this prompt for users, add it to the build pipeline later.

"I don't see memories being injected"

• Open Settings → Claude Code integration and check the per-config status table — every row should show the hook installed and the MCP server registered.
• Verify the hook works: echo '{"prompt":"docker","session_id":"x","cwd":"/"}' | /path/to/claude-memory-manager --hook
• If you recently moved the binary, click Re-register in the same section to update the paths in every config.

"My endpoint protection keeps asking for permission"

The unsigned binary is the culprit — most endpoint protection tools prompt on every access from unknown/unsigned binaries, especially for dot-folders in $HOME. Options:

1. In your endpoint protection settings, add the binary path (or the .app bundle path) as trusted. The exact UI varies by product — look for "Application Control", "Folder Shield", "Trusted Applications", or similar.
2. Build a release binary (cargo build --release) — roughly 2× faster startup and sometimes recognized.
3. Move the DB to a location your tool doesn't watch by setting CLAUDE_MEMORY_DB_DIR in Settings.

"Organize picked bad topics / merged things I didn't want"

• Settings → Organization → Undo last reverts the most recent destructive operation (works for consolidate merges, dedup merges, and topic splits).
• Run "Organize now" again after editing memories manually.
• The consolidate and split prompts are tuned to be conservative but occasionally pick questionable merges or splits — adjust the split threshold in Settings → Organization if topics are being split too eagerly.

"The app slowed down during organize"

Fixed in current builds via --strict-mcp-config, which prevents claude -p from recursively spawning our own MCP server during the organize pass. If you see this on an older build, pull latest and cargo build --release.

License

MIT

Credits

• Tauri 2 — desktop shell
• Vue 3 + Pinia — frontend
• rusqlite + SQLite FTS5 — storage
• marked — markdown rendering
• Model Context Protocol — for MCP server integration
• Claude Code — the thing this is for