Skillget

claude-memory-hub

skill
Security Audit
Fail
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Fail
  • fs module — File system access in .github/workflows/publish.yml
  • process.env — Environment variable access in dist/hooks/stop.js
  • fs module — File system access in dist/hooks/stop.js
  • rm -rf — Recursive force deletion command in push-private.sh
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Persistent memory layer for Claude Code. Zero API key. Zero config. The only tool that tells compact what to preserve.

README.md

claude-memory-hub

claude-memory-hub

Persistent memory for Claude Code. Survives compacts. Survives sessions.

npm version license 

bunx claude-memory-hub install

One command. Zero API key. Zero Python. Zero config. Done.

The Problem

Session 1: You spend 2 hours building an auth system
Session 2: Claude has no idea it exists

Long session: Hit 200K tokens → auto-compact fires
              → ~90% of your context gone
              → files, decisions, error trails — vaporized

Every Claude Code user hits this wall. memory-hub exists to fix it.

What You Get

Compact Interceptor — the thing no other tool does

When auto-compact fires, your context doesn't just disappear anymore:

BEFORE compact
  → PreCompact hook scores all entities by importance
  → Injects priority list as Additional Instructions
  → Compact engine now KNOWS what to preserve

AFTER compact
  → PostCompact hook captures the FULL summary
  → Saves to SQLite L3
  → Zero information loss

90% context loss → 90% context salvage. This is the core innovation.

Cross-Session Memory

Session ends → memory-hub parses the full transcript, summarizes, indexes.
Next session → the SessionStart hook injects the baseline once (recent memory,
CLAUDE.md summary, resource advice). Per-prompt injection is conditional: history
recall and fresh search results only, deduplicated against what the session already saw.

No manual prompting. No copy-pasting. No token waste. Claude just knows.

Token-Efficient by Design (v0.15)

Telemetry on 30 days of real usage showed the old design re-injected ~2,900 chars on
EVERY prompt (one session: 1,083 injections ≈ 790K tokens). v0.15 injects the baseline
once per session; later prompts measured at 0 extra chars unless you explicitly ask
about past work. injection_log tracks injected_at, dedup_skipped, and
memory_tool_used so effectiveness is measured, not guessed.

Knowledge Graph (v0.15)

Every session builds edges: which files change together (co_edited), where errors
happened (error_in), what decisions concern which files (decided_about), plus a
static import graph (graph scan). Ask memory_impact before touching a risky file
to see its blast radius: co-edit cluster, past errors, related decisions, sessions.

Obsidian Export (v0.15)

bunx claude-memory-hub obsidian sync exports sessions, decisions, and hot files as
markdown notes with [[wikilinks]] generated from the graph — Obsidian's graph view
becomes your coding memory graph. Incremental, idempotent, one-way.

Hybrid Search (3 engines)

FTS5 (keyword) + TF-IDF (term frequency) + semantic embeddings (384-dim, local).
Code-aware tokenizer: splits camelCase, snake_case, file paths into meaningful tokens.
Recency decay: recent sessions ranked higher (7d=1.5x, 30d=1.2x, >90d=0.8x).

Full Conversation Capture

Every user prompt + every assistant response saved via transcript parsing.
Searchable with FTS5. Not just tool observations — the actual conversation.

3-Layer Privacy

Layer 1: <private> tags        → stripped before storage
Layer 2: Auto secret detection → sk-, ghp_, Bearer, passwords auto-redacted
Layer 3: Path filtering        → .env, *.pem, *.key excluded from tracking

47 dedicated tests. Custom config via ~/.claude-memory-hub/privacy.json.

Everything Else

  • Slash commands — /mem-search, /mem-status, /mem-save
  • 13 MCP tools — progressive 3-layer search (50→200→500 tokens/result) + graph + resource matching
  • Proactive retrieval — detects topic shifts, injects relevant context mid-session
  • Maintenance daemon — daily launchd agent: retention, WAL checkpoint, Obsidian sync
  • Browser dashboard — bunx claude-memory-hub viewer at localhost:37888
  • JSONL export/import — full backup, incremental, per-table
  • Multi-agent ready — subagents share memory via MCP
  • 213 unit tests — privacy, search, capture, schema, graph, export, health

Quick Start

# Install (registers MCP server + 7 hooks + 3 slash commands)
bunx claude-memory-hub install

# Verify
bunx claude-memory-hub status

# That's it. Start a Claude Code session — memory is active.

Works on CLI, VS Code, JetBrains. Coming from claude-mem? Data migrates automatically.

Requirements

  • Bun runtime
  • Claude Code
  • No API key needed

Deep Dive: How Each Layer Works

Layer 1 — Compact Interceptor (the core innovation)

The 200K threshold is where Claude Code's tool result budget gets cleared. When this happens, compaction fires — and everything not in the compressed summary is gone.

memory-hub intercepts this process at both ends:

BEFORE compact runs
       │
       ├── PreCompact hook fires
       │   1. Reads ALL entities from current session (files, errors, decisions, observations)
       │   2. Scores each by: importance (1-5) × recencyWeight
       │   3. Sorts by score, builds priority list
       │   4. Outputs as plain text → Claude Code appends to compact prompt
       │      as "Additional Instructions"
       │   Result: compact engine now KNOWS what to preserve
       │
AFTER compact runs
       │
       ├── PostCompact hook fires
       │   1. Receives FULL 9-section compact summary via stdin
       │   2. Parses sections: key_facts, open_tasks, current_state, etc.
       │   3. Saves directly to SQLite L3 (long_term_summaries table)
       │   4. FTS5 indexes the summary for future search
       │   Result: zero information loss — summary persists forever

Why this matters: Without PreCompact, the compact engine has no signal about what's important — it compresses blindly. Without PostCompact, the summary exists only in Claude's context and vanishes at session end. memory-hub closes both gaps.

Layer 2 — Cross-Session Memory

Session N ends:
  1. Stop hook fires → parse Claude Code's JSONL transcript
     → extract ALL user prompts + assistant responses
     → save to messages table (FTS5 indexed)
  2. 3-tier summarization:
     Tier 1: Use PostCompact summary if available (best quality, free)
     Tier 2: Run `claude -p --print` subprocess (good quality, free)
     Tier 3: Rule-based template extraction (fallback, always works)
  3. Summary enriched with conversation digest
  4. Generate 384-dim embedding vector (if @huggingface/transformers available)
  5. Save to L3: long_term_summaries + fts_memories + tfidf_index + embeddings

Session N+1 starts:
  1. UserPromptSubmit hook fires with user's first prompt
  2. Hybrid search against L3:
     FTS5 BM25 (keyword match) + TF-IDF (term frequency) + semantic cosine
  3. Recency decay applied: <7d=1.5x boost, <30d=1.2x, >90d=0.8x penalty
  4. RRF (Reciprocal Rank Fusion) merges results from all engines
  5. Top results injected as additionalContext (max 8,000 chars)
  6. Smart budget allocation: memory > CLAUDE.md > advice > overhead
  Result: Claude starts with relevant history, not from zero

Layer 3 — Entity + Conversation Capture

Every tool call triggers the PostToolUse hook. Entities are extracted from hook JSON metadata:

Claude reads a file     → file_read entity: path, code patterns, line count
Claude edits a file     → file_modified entity: path, old→new diff, change type
Claude runs a command   → command_run entity: command, exit code, stderr
Claude hits an error    → error entity: message, stack trace, file context
Claude makes a decision → decision entity: text, importance score (1-5)
Claude spawns an agent  → agent_result entity: agent type, prompt, summary

Events are batched via write-through queue (~3ms per event vs ~75ms direct write).
Mid-session topic shifts detected → proactive retrieval injects relevant past context.

Observation capture — 20+ heuristic patterns extract insights from tool output and user prompts:

Tool output patterns:
  IMPORTANT, CRITICAL, SECURITY, DEPRECATED, migration failed,
  decision:, discovered, root cause, switched to, refactored,
  TODO:, FIXME:, performance:, bottleneck, tests pass/fail, deployed

User prompt patterns:
  IMPORTANT, MUST, remember that, don't/never/avoid,
  fix/debug/investigate, implement/build/create, prefer/always use

Importance scoring: IMPORTANT/CRITICAL=4, decision:/NOTE:=3, TODO:/FIXME:=2
Max 1 observation per tool call, 300-char cap

Layer 4 — 3-Layer Progressive Search

Instead of dumping full records on every query, memory-hub progressively discloses:

Traditional:  query → ALL full records → 5,000+ tokens wasted

memory-hub:   query → Layer 1 (index)    → ~50 tokens/result
                      titles, dates, scores — scan 20+ results cheaply

              pick  → Layer 2 (timeline)  → ~200 tokens
                      what happened before/after a specific result

              drill → Layer 3 (full)      → ~500 tokens/result
                      complete record for specific IDs only

Token savings: 80-90% vs. traditional full-context search

Hybrid ranking combines: FTS5 BM25 (exact keyword) + TF-IDF cosine (term frequency with code-aware tokenizer) + semantic cosine similarity (384-dim embeddings). Multi-source boost rewards results found by 2+ engines.

Layer 5 — Resource Intelligence

ResourceRegistry scans ALL .claude locations:
  skills/, agents/, commands/, workflows/, CLAUDE.md chain
  → Discovers 170+ resources across user/project/system scopes
  → 3-level token estimation per resource:
    listing_tokens (~50-200): system prompt listing cost
    full_tokens (~200-8000): cost when invoked
    total_tokens: all files on disk

ResourceTracker records actual usage per session (8 resource types)
OverheadReport identifies unused resources + token waste

Transparency note: Claude Code loads ALL resources into its system prompt — no external tool can prevent this. memory-hub provides analysis and prioritization, not filtering. To reduce token overhead, remove or relocate unused skills/agents based on the overhead report.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Claude Code                            │
│                                                             │
│  7 Lifecycle Hooks                                          │
│  ┌───────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ SessionStart  │  │ PreCompact   │  │ PostCompact  │      │
│  │ inject base-  │  │ inject       │  │ save summary │      │
│  │ line ONCE     │  │ priorities   │  └──────┬───────┘      │
│  └──────┬────────┘  └──────┬───────┘         │              │
│  ┌──────┴───────┐  ┌───────┴──────┐  ┌───────┴────────┐     │
│  │UserPrompt    │  │ PostToolUse  │  │ Stop: flush    │     │
│  │Submit: cond. │  │ batch queue +│  │ (~30ms)        │     │
│  │inject (dedup)│  │ feedback mark│  │ SessionEnd:    │     │
│  │+ save prompt │  └──────────────┘  │ parse+summarize│     │
│  └──────────────┘                    │ +graph+obsidian│     │
│                                      └────────────────┘     │
│  MCP Server (stdio, long-lived)                             │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ memory_recall        memory_search  (L1 index)      │    │
│  │ memory_entities      memory_timeline (L2 context)   │    │
│  │ memory_session_notes memory_fetch   (L3 full)       │    │
│  │ memory_store         memory_context_budget          │    │
│  │ memory_conversation  memory_health                  │    │
│  │ memory_graph         memory_impact                  │    │
│  │ memory_resources_for_prompt                         │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                             │
│  Resource Intelligence    Browser UI (:37888)               │
│  ┌──────────────────┐     ┌──────────────────┐              │
│  │ scan → track →   │     │ search, browse,  │              │
│  │ analyze overhead │     │ stats, health    │              │
│  └──────────────────┘     └──────────────────┘              │
└─────────────────────────────────────────────────────────────┘
                             │
                   ┌─────────┴──────────┐
                   │   SQLite + FTS5    │
                   │   ~/.claude-       │
                   │   memory-hub/      │
                   │   memory.db        │
                   └────────────────────┘

Memory Hierarchy

┌─────────────────────────────────────────────────────┐
│  L1: WorkingMemory          Read-through cache      │
│  Lives in MCP server        <1ms (cache hit)        │
│  TTL: 5 minutes             Max 50 entries/session  │
├─────────────────────────────────────────────────────┤
│  L2: SessionStore           SQLite                  │
│  Entities + messages        <10ms access            │
│  files, errors, decisions   Importance scored 1-5   │
│  observations (20+ patterns)FTS5 on conversations   │
├─────────────────────────────────────────────────────┤
│  L3: LongTermStore          SQLite + FTS5 + TF-IDF  │
│  Cross-session summaries    <100ms access           │
│  Hybrid ranked search       Persistent forever      │
│  Semantic embeddings (384d) 3-layer progressive     │
└─────────────────────────────────────────────────────┘

How Capture Works

Claude reads a file     → memory-hub records: which file, code patterns found
Claude edits a file     → memory-hub records: what changed (old → new diff)
Claude runs a command   → memory-hub records: command, exit code, stderr
Claude makes a decision → memory-hub records: decision text + importance score
Claude spawns an agent  → memory-hub records: agent type, prompt, result summary
User sends a prompt     → memory-hub records: full prompt text
Session ends            → memory-hub parses transcript: ALL user + assistant messages

Extracted from hook JSON metadata. No XML. No special format.
PostToolUse events batched via write-through queue (~3ms per event).
20+ heuristic patterns for observation capture (IMPORTANT, CRITICAL, decision:, root cause, etc.)

Slash Commands

Command What it does
/mem-search <query> 3-layer progressive search — finds past sessions by topic, file, or keyword
/mem-status [project] Health check + token budget analysis + current session activity
/mem-save <note> Save an important decision or finding to persistent memory 
/mem-search auth login bug
/mem-save Decided to use JWT refresh tokens with 15min expiry

MCP Tools

Tool What it does Tokens
memory_recall FTS5 + semantic search past sessions (AUTO-USE) varies
memory_entities Find sessions that touched a file (AUTO-USE) varies
memory_session_notes Current session activity (L1 cache) ~100
memory_store Save note/decision to persistent memory ~50
memory_search Layer 1: index search ~50/result
memory_timeline Layer 2: context around a result ~200
memory_fetch Layer 3: full record by ID ~500/result
memory_conversation Retrieve/search conversation messages varies
memory_context_budget Token overhead analysis ~200
memory_health Database + FTS5 + disk + embeddings status ~150
memory_graph Knowledge-graph neighbors: co_edited, error_in, decided_about, imports varies
memory_impact Blast-radius view for a file: co-edit cluster + errors + decisions + sessions ~300
memory_resources_for_prompt Best skills/agents/commands for a prompt (semantic + usage) varies

CLI Reference

bunx claude-memory-hub install     # Register MCP + hooks + slash commands
bunx claude-memory-hub uninstall   # Clean removal
bunx claude-memory-hub status      # Check installation
bunx claude-memory-hub migrate     # Import data from claude-mem
bunx claude-memory-hub viewer      # Browser UI at localhost:37888
bunx claude-memory-hub health      # Run health diagnostics
bunx claude-memory-hub reindex     # Rebuild TF-IDF + embedding indexes
bunx claude-memory-hub export      # Export data as JSONL to stdout
bunx claude-memory-hub import      # Import JSONL from stdin (--dry-run)
bunx claude-memory-hub cleanup     # Remove old data (--days N, default 90)
bunx claude-memory-hub prune       # Remove low-quality summaries (--dry-run)
bunx claude-memory-hub doctor      # Diagnose install: 7 hooks, dist files, embeddings (--fix)
bunx claude-memory-hub stats       # Memory report (--injections: telemetry + effectiveness)
bunx claude-memory-hub graph       # Knowledge graph: graph build | graph scan [repo]
bunx claude-memory-hub obsidian sync  # Export memory to Obsidian vault [--project X]
bunx claude-memory-hub maintenance # Retention + WAL checkpoint + Obsidian sync now
bunx claude-memory-hub install-daemon # Daily 03:30 launchd maintenance agent (macOS)

Privacy Configuration

Create ~/.claude-memory-hub/privacy.json to extend defaults:

{
  "tag_stripping": true,
  "auto_detect_secrets": true,
  "ignored_paths": ["my-secrets.yaml", "**/vault/**"],
  "custom_patterns": ["INTERNAL_TOKEN_[A-Z0-9]{20,}"]
}

Custom paths and patterns are added to defaults, not replacing them.

Data Export/Import

# Full export
bunx claude-memory-hub export > backup.jsonl

# Incremental
bunx claude-memory-hub export --since 1743580800000 > incremental.jsonl

# Import (idempotent, UPSERT)
bunx claude-memory-hub import < backup.jsonl

# Validate first
bunx claude-memory-hub import --dry-run < backup.jsonl

Data & Privacy

All data stored locally at ~/.claude-memory-hub/. No cloud. No telemetry. No network calls.

~/.claude-memory-hub/
  ├── memory.db           # SQLite database
  ├── privacy.json        # Custom privacy rules (optional)
  ├── batch/queue.jsonl   # PostToolUse batch queue (auto-flushed)
  └── logs/memory-hub.log # Structured JSON logs (auto-rotated 5MB)

Dependencies

@modelcontextprotocol/sdk          MCP stdio server (required)
bun:sqlite                         Built-in, zero install
@huggingface/transformers          Semantic embeddings (optional, ~90MB model on first use)
sharp                              Image preprocessing for transformers (optional)

Two npm packages + two optional. No Python. No Chroma. No Docker. No API key.

Enabling semantic search

By default, only FTS5 keyword search is active (zero-install). To enable semantic embeddings:

claude-memory-hub doctor --fix

This installs @huggingface/transformers + sharp into ~/.claude-memory-hub/node_modules/
without polluting your project deps. To verify everything is healthy:

claude-memory-hub doctor

To disable semantic search at runtime: export CLAUDE_MEMORY_HUB_EMBEDDINGS=disabled.

Smart resource matching (v0.13.0+)

Memory hub does not just remember past sessions — it also matches your prompts to the right skill, agent, or CLAUDE.md by meaning, not just by name or recency.

Each prompt triggers an injection like:

**Suggested resources for this prompt:**
  - skill: `veo3-prompt-expert` (68% — 68% match)
  - agent: `ios-developer` (52% — fits cwd)
  - skill: `mobile-development-skill` (41% — used in this project)

The score combines four signals:

Signal Weight What it captures
Semantic match 50% Prompt embedding ↔ resource description embedding
Frequency 20% How often this resource was used in this project recently
Project context 20% cwd has .swift → boost ios-developer, pubspec.yaml → boost flutter-developer, etc.
Recency 10% Used at all recently

To enable, run once:

claude-memory-hub doctor --fix --backfill

This installs the embedding model + indexes all your skills/agents/CLAUDE.md files. After that, every prompt automatically gets the right resources surfaced.

For ad-hoc lookup from inside a Claude session:

/mcp call memory_resources_for_prompt prompt="design a landing page for SaaS"

Migrating from claude-mem

bunx claude-memory-hub install   # auto-detects and migrates
claude-mem → memory-hub
sdk_sessions → sessions
observations (files) → entities (file_read/file_modified)
observations (narrative) → entities (decision) + session_notes
session_summaries → long_term_summaries (FTS5 indexed)

Idempotent — safe to run multiple times.

Version History

Version Highlight
v0.11.4 Search quality — pruned garbage summaries, guided Claude to use specific keywords instead of generic phrases
v0.11.3 MCP registration fix — installer now writes to ~/.claude.json (correct config), troubleshooting guide
v0.11.2 Critical fix — context injection null crash, slash commands install fallback, null-safe budget
v0.11.1 Quality hardening — clock skew guard, 155 unit tests (+44%)
v0.11.0 3-layer privacy, code-aware search, recency ranking, slash commands
v0.10.0 Full conversation capture (user + assistant), memory_conversation tool
v0.9.x Smart budget allocation, stable install paths, agent/skill capture
v0.8.x 91 unit tests, L1 cache, batch queue (75ms→3ms), export/import
v0.7.0 Semantic search scaling, 14 observation patterns, auto-cleanup
v0.6.0 ResourceRegistry, semantic embeddings, CLAUDE.md tracking
v0.5.0 Hybrid search, browser UI, health monitoring, claude-mem migration
v0.2.0 Compact Interceptor (PreCompact/PostCompact)
v0.1.0 Cross-session memory, entity tracking, FTS5 search

See CHANGELOG.md for full details.

Troubleshooting

MCP server not connecting (most common issue)

Claude Code stores MCP config in ~/.claude.json (not ~/.claude/settings.json). If memory tools aren't available after install:

1. Check MCP status:

claude mcp list

If claude-memory-hub shows ✗ Failed to connect or is missing:

2. Register directly via Claude CLI:

claude mcp add claude-memory-hub -s user -- bun run ~/.claude-memory-hub/dist/index.js

3. If CLI fails (e.g., hook blocking dist/ paths), edit ~/.claude.json manually. Find the top-level "mcpServers" object and add:

"claude-memory-hub": {
  "type": "stdio",
  "command": "/path/to/bun",
  "args": ["run", "/Users/YOU/.claude-memory-hub/dist/index.js"]
}

4. Restart Claude Code — MCP servers only load at startup.

How to verify it works

After restart, check if memory tools appear:

  • Type /mem-status — should run health check
  • Or ask: "Search my memory for recent sessions" — Claude should call memory_search

If Claude reads MEMORY.md instead of calling MCP tools, the MCP server is not connected.

Common issues

Symptom Cause Fix
"No memories found" on new session MCP server not registered in ~/.claude.json Run claude mcp add (see above)
bunx install shows old version bunx cache bunx claude-memory-hub@latest install
Hooks registered but no context injected Dist files outdated in ~/.claude-memory-hub/dist/ Re-run install to copy latest dist
Memory tools not in tool list MCP server failed to start Check claude mcp list for connection status

Config file locations

File What it stores
~/.claude.json MCP server registrations (user-level) — Claude Code reads this
~/.claude/settings.json Hooks registration + fallback MCP config
~/.claude-memory-hub/memory.db All memory data (sessions, entities, summaries)
~/.claude-memory-hub/dist/ Compiled hook + MCP server scripts
~/.claude/commands/ Slash commands (/mem-search, /mem-status, /mem-save)

Uninstall

bunx claude-memory-hub uninstall
rm -rf ~/.claude-memory-hub    # optional: remove data

Built for developers who use Claude Code daily and are tired of starting from zero.

Reviews (0)

No results found