claude-memory-hub 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,140 @@
+# Changelog
+
+All notable changes to `claude-memory-hub` are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/).
+
+---
+
+## [0.4.0] - 2026-04-01
+
+### Problem
+Every Claude Code session loads ALL skills, agents, rules, and memory files into context regardless of relevance. Typical overhead: **23-51K tokens** before the user types anything.
+
+### Solution — Smart Resource Loader
+- **ResourceTracker** — new `resource_usage` SQLite table automatically tracks which skills, agents, and MCP tools are actually used per session
+- **SmartResourceLoader** — predicts relevant resources for new sessions based on usage frequency and prompt relevance, within a configurable token budget
+- **MCP tool: `memory_context_budget`** — lets Claude analyze token costs and get resource recommendations on demand
+- **PostToolUse auto-tracking** — Skill, Agent, and MCP tool invocations recorded automatically (zero config)
+- **UserPromptSubmit advice injection** — when resources are deferred for efficiency, injects a hint so Claude knows to use SkillTool/ToolSearch on demand
+
+### Impact
+```
+BEFORE: 23-51K tokens overhead (all resources loaded)
+AFTER:  Only frequently-used resources recommended
+        Rare resources loaded on demand via SkillTool
+        ~10-30K tokens saved per session on heavy setups
+```
+
+### Files
+- `src/context/resource-tracker.ts` — usage tracking + SQLite schema
+- `src/context/smart-resource-loader.ts` — prediction + budgeted context planning
+
+---
+
+## [0.3.0] - 2026-04-01
+
+### Problem
+v0.2.0 required `@anthropic-ai/sdk` + `ANTHROPIC_API_KEY` for rich session summaries. Users without API key got degraded rule-based summaries. Extra dependency, extra cost, extra friction.
+
+### Solution — Zero API Key Architecture
+- **Removed `@anthropic-ai/sdk`** entirely from dependencies
+- **Key insight:** PostCompact hook already receives Claude Code's own compact summary for free — no need to call the API again
+- **Two summarization paths, both free:**
+  - Short sessions (no compact) → rule-based summary from L2 entities
+  - Long sessions (compact fires) → PostCompact hook captures Claude's summary directly
+
+### Added
+- **install.sh** — 1-command installer: `bash install.sh` handles bun install, MCP registration via `claude mcp add -s user`, and hooks patching. Works on CLI, VS Code, JetBrains.
+
+### Breaking Changes
+- `@anthropic-ai/sdk` removed — re-run `bash install.sh` to update
+- `ANTHROPIC_API_KEY` env var no longer needed
+
+### Dependencies
+```
+KEPT:    @modelcontextprotocol/sdk, bun:sqlite (built-in)
+REMOVED: @anthropic-ai/sdk
+```
+
+---
+
+## [0.2.0] - 2026-04-01
+
+### Problem
+v0.1.0 could not intercept Claude Code's auto-compact. When compact ran, 90% of context was lost and memory-hub had no way to influence what survived. Entity extraction was metadata-only (file paths, exit codes) with no understanding of WHY actions were taken.
+
+### Solution — Compact Interceptor (Core Innovation)
+
+**PreCompact Hook** — fires BEFORE compact summarization:
+1. Reads all L2 entities (files, decisions, errors)
+2. Scores by `importance * recencyWeight`
+3. Outputs priority list as text
+4. Claude Code **APPENDS** this to the compact prompt as `Additional Instructions`
+5. Result: compact summarizer now **knows** what to preserve
+
+**PostCompact Hook** — fires AFTER compact:
+1. Receives the FULL 9-section compact summary via stdin
+2. Saves directly to L3 SQLite
+3. Zero additional information loss
+
+### Added — Contextual Entity Enrichment
+- File reads: captures first lines + code patterns (imports, class/function defs)
+- File edits: captures `old_string → new_string` delta
+- File writes: captures line count + content snippet
+- Errors: captures command + stderr + stdout
+- No XML required — parsed directly from tool response JSON
+
+### Added — Importance-Weighted Scoring
+| Entity Type | Importance | Example |
+|-------------|-----------|---------|
+| file_created | 4 | New file written |
+| file_modified | 4 | File edited |
+| error (fatal) | 5 | Non-zero exit, crash |
+| error (normal) | 3 | Build warning |
+| decision | 3 | TodoWrite task |
+| file_read | 1 | File opened |
+
+Score formula: `importance * (1 / (1 + hoursAgo))`
+
+### Breaking Changes
+- Entity extraction returns enriched `context` field — re-run `bash install.sh`
+- 5 hooks instead of 3 (added PreCompact, PostCompact)
+
+### Resolved Limitations from v0.1.0
+- ~~Cannot intercept compact~~ → PreCompact + PostCompact hooks
+- ~~No importance scoring~~ → Importance x recency in PreCompact
+- ~~Metadata only, no reasoning~~ → Context enricher with diffs, patterns, stderr
+
+---
+
+## [0.1.0] - 2026-04-01
+
+### Problem
+Claude Code's built-in memory has 7 critical gaps:
+1. Session memory triggers after 10K tokens — early context lost
+2. Auto-compact loses 90% of information (200K → 20K tokens)
+3. Memory selection is keyword-only (no ranking)
+4. No cross-session carry-over — each session starts from zero
+5. No entity tracking (files touched, decisions made, errors fixed)
+6. Existing solution (claude-mem) requires Claude to output fragile XML format
+7. claude-mem requires Python + Chroma subprocess — heavy operational overhead
+
+### Solution — Hierarchical Memory Hub
+- **L1: WorkingMemory** — in-process Map, current session, <1ms access
+- **L2: SessionStore** — SQLite: entities + notes, session-scoped, <10ms
+- **L3: LongTermStore** — SQLite FTS5: cross-session summaries, <100ms
+
+### Added
+- **Zero-XML entity extraction** — captures files, errors, decisions from Claude Code hook JSON (tool_name, file_path, exit_code). No special output format required.
+- **SQLite FTS5 search** — BM25-ranked full-text search with automatic LIKE fallback
+- **MCP Server (stdio)** — 4 tools: `memory_recall`, `memory_entities`, `memory_session_notes`, `memory_store`
+- **3 Claude Code hooks** — PostToolUse, UserPromptSubmit, Stop
+- **Progressive 3-layer disclosure** — index (~50 tok), summary (~300 tok), full (~800 tok)
+- **Cross-session carry-over** — past summaries auto-injected at session start
+
+### Known Limitations (addressed in later versions)
+- Cannot intercept compact (→ solved in v0.2.0)
+- Metadata only, no reasoning context (→ solved in v0.2.0)
+- Requires API key for rich summaries (→ solved in v0.3.0)
+- No token budget optimization (→ solved in v0.4.0)
+- FTS5 keyword-only search (no vector/semantic — intentional trade-off)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,281 @@
+<p align="center">
+  <img src="assets/logo.png" alt="claude-memory-hub" width="200" />
+</p>
+
+<h1 align="center">claude-memory-hub</h1>
+
+<p align="center">
+  <strong>The missing memory layer for Claude Code.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/claude-memory-hub"><img src="https://img.shields.io/npm/v/claude-memory-hub.svg" alt="npm version" /></a>
+  <a href="https://github.com/TranHoaiHung/claude-memory-hub/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/claude-memory-hub.svg" alt="license" /></a>
+</p>
+
+Zero API key. Zero Python. Zero config. One install command.
+
+---
+
+## The Problem
+
+Claude Code forgets everything between sessions. Within long sessions, auto-compact destroys 90% of context. Every session wastes tokens loading resources that aren't needed.
+
+```
+Session 1: You spend 2 hours building auth system
+Session 2: Claude has no idea what happened yesterday
+
+Long session: Claude auto-compacts at 200K tokens
+              → 180K tokens of context vaporized
+              → Claude loses track of files, decisions, errors
+
+Every session: ALL skills + agents + rules loaded
+               → 23-51K tokens consumed before you type anything
+               → Most of them never used
+```
+
+**Three problems. No existing tool solves all of them.**
+
+| Problem | Claude Code built-in | claude-mem | memory-hub |
+|---------|:-------------------:|:----------:|:----------:|
+| Cross-session memory | -- | Yes | **Yes** |
+| Influence what compact preserves | -- | -- | **Yes** |
+| Save compact output | -- | -- | **Yes** |
+| Token budget optimization | -- | -- | **Yes** |
+| No API key needed | N/A | Yes | **Yes** |
+| No Python/Chroma needed | N/A | -- | **Yes** |
+| No XML format required | N/A | -- | **Yes** |
+| No HTTP server to manage | N/A | -- | **Yes** |
+
+---
+
+## How It Works
+
+### Layer 1 — Entity Capture (every tool call)
+
+```
+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
+```
+
+No XML. No special format. Extracted directly from hook JSON metadata.
+
+### Layer 2 — Compact Interceptor (the key innovation)
+
+```
+                    BEFORE compact runs
+                           |
+            +--------------+--------------+
+            |                             |
+     PreCompact hook               Claude Code's
+     reads all entities            compact engine
+     scores by importance          receives our output
+     outputs priority list    -->  as Additional Instructions
+            |                             |
+            |                     compact now KNOWS
+            |                     what to preserve
+            |                             |
+            |                    AFTER compact runs
+            |                             |
+            +-------- PostCompact hook ---+
+                      receives FULL summary
+                      saves to SQLite L3
+                      zero information loss
+```
+
+**This is something no other memory tool does.** claude-mem never sees the compact. Built-in session memory is supplementary, not directive. memory-hub is the only system that **tells the compact what matters**.
+
+### Layer 3 — Cross-Session Memory
+
+```
+Session N ends  → rule-based summary from entities → SQLite L3
+                  OR PostCompact summary (richer) → SQLite L3
+
+Session N+1     → UserPromptSubmit hook fires
+                → FTS5 search: match user prompt against past summaries
+                → inject relevant context automatically
+                → Claude starts with history, not from zero
+```
+
+### Layer 4 — Smart Resource Loading
+
+```
+                 Typical Claude Code session
+
+    BEFORE memory-hub          AFTER memory-hub
+    ┌──────────────────┐        ┌──────────────────┐
+    │ System prompt 8K │        │ System prompt 8K │
+    │ ALL skills  10K  │        │ Used skills  3K  │
+    │ ALL agents   5K  │        │ Used agents  1K  │
+    │ ALL rules   15K  │        │ Key rules    5K  │
+    │ ALL memory   5K  │        │ Relevant mem 2K  │
+    ├──────────────────┤        ├──────────────────┤
+    │ OVERHEAD:  ~43K  │        │ OVERHEAD:  ~19K  │
+    │                  │        │ SAVED:     ~24K  │
+    └──────────────────┘        └──────────────────┘
+```
+
+memory-hub tracks which skills/agents/tools you **actually use**, then recommends only those for future sessions. Rare resources load on demand via SkillTool.
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    Claude Code                           │
+│                                                          │
+│  5 Lifecycle Hooks                                       │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
+│  │ PostToolUse   │  │ PreCompact   │  │ PostCompact  │   │
+│  │ entity capture│  │ inject       │  │ save summary │   │
+│  └──────┬───────┘  │ priorities   │  └──────┬───────┘    │
+│         │          └──────┬───────┘         │            │
+│  ┌──────┴───────┐         │          ┌──────┴───────┐    │
+│  │UserPrompt    │         │          │ Stop         │    │
+│  │Submit: inject│         │          │ session end  │    │
+│  │past context  │         │          │ summarize    │    │
+│  └──────────────┘         │          └──────────────┘    │
+│                           │                              │
+│  MCP Server (stdio)       │                              │
+│  ┌─────────────────────┐  │                              │
+│  │ memory_recall       │  │                              │
+│  │ memory_entities     │  │  ┌────────────────────────┐  │
+│  │ memory_session_notes│  │  │ Smart Resource Loader  │  │
+│  │ memory_store        │  │  │ track usage → predict  │  │
+│  │ memory_context_budget│ │  │ → budget → recommend   │  │
+│  └─────────────────────┘  │  └────────────────────────┘  │
+│                           │                              │
+└───────────────────────────┼──────────────────────────────┘
+                            │
+                   ┌────────┴────────┐
+                   │  SQLite + FTS5  │
+                   │  ~/.claude-     │
+                   │  memory-hub/    │
+                   │  memory.db      │
+                   │                 │
+                   │  sessions       │
+                   │  entities       │
+                   │  session_notes  │
+                   │  long_term_     │
+                   │   summaries     │
+                   │  resource_usage │
+                   │  fts_memories   │
+                   └─────────────────┘
+```
+
+---
+
+## Memory Hierarchy
+
+```
+┌─────────────────────────────────────────────────────┐
+│  L1: WorkingMemory          in-process Map          │
+│  Current session only       <1ms access             │
+│  Lives in MCP server        FIFO 50 entries/session │
+├─────────────────────────────────────────────────────┤
+│  L2: SessionStore           SQLite                  │
+│  Entities + notes           <10ms access            │
+│  files_read, file_modified  Per-session scope       │
+│  errors, decisions          Importance scored       │
+├─────────────────────────────────────────────────────┤
+│  L3: LongTermStore          SQLite + FTS5           │
+│  Cross-session summaries    <100ms access           │
+│  BM25 ranked search         Persistent forever      │
+│  Auto-injected on start     LIKE fallback           │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## Install
+
+### From npm (recommended)
+
+```bash
+bunx claude-memory-hub install
+```
+
+One command. Registers MCP server + 5 hooks globally. Works on CLI, VS Code, JetBrains.
+
+### From source
+
+```bash
+git clone https://github.com/TranHoaiHung/claude-memory-hub.git ~/.claude-memory-hub
+cd ~/.claude-memory-hub
+bun install && bun run build:all
+bunx . install
+```
+
+### Other commands
+
+```bash
+bunx claude-memory-hub status      # Check installation
+bunx claude-memory-hub uninstall   # Clean removal
+```
+
+### Requirements
+
+- [Bun](https://bun.sh) runtime
+- Claude Code (CLI, VS Code, or JetBrains)
+- **No API key needed**
+
+---
+
+## MCP Tools
+
+Claude can call these tools directly during conversation:
+
+| Tool | What it does | When to use |
+|------|-------------|-------------|
+| `memory_recall` | FTS5 search past session summaries | Starting a task, looking for prior work |
+| `memory_entities` | Find all sessions that touched a file | Before editing a file, understanding history |
+| `memory_session_notes` | Current session activity summary | Mid-session, checking what's been done |
+| `memory_store` | Manually save a note or decision | Preserving important context |
+| `memory_context_budget` | Analyze token costs + recommendations | Optimizing which resources to load |
+
+---
+
+## Version History
+
+| Version | What it solved |
+|---------|---------------|
+| **v0.1.0** | Cross-session memory, entity tracking, FTS5 search |
+| **v0.2.0** | Compact interceptor (PreCompact/PostCompact hooks), context enrichment, importance scoring |
+| **v0.3.0** | Removed API key requirement, 1-command install |
+| **v0.4.0** | Smart resource loading, token budget optimization |
+
+See [CHANGELOG.md](CHANGELOG.md) for full details.
+
+---
+
+## Dependencies
+
+```
+@modelcontextprotocol/sdk    MCP stdio server
+bun:sqlite                   Built-in, zero install
+```
+
+That's it. **One npm package.** The other is built into Bun.
+
+No Python. No Chroma. No HTTP server. No API key. No Docker.
+
+---
+
+## Data & Privacy
+
+All data stored locally at `~/.claude-memory-hub/memory.db`.
+
+No cloud. No telemetry. No network calls. Your memory stays on your machine.
+
+---
+
+## Uninstall
+
+```bash
+claude mcp remove claude-memory-hub -s user
+# Remove hook entries containing "claude-memory-hub" from ~/.claude/settings.json
+rm -rf ~/.claude-memory-hub
+```

package/dist/cli.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env bun
+// @bun
+var __require = import.meta.require;
+
+// src/cli/main.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join, resolve, dirname } from "path";
+import { spawnSync } from "child_process";
+var CLAUDE_DIR = join(homedir(), ".claude");
+var SETTINGS_PATH = join(CLAUDE_DIR, "settings.json");
+var PKG_DIR = resolve(dirname(import.meta.dir));
+function getHookPath(hookName) {
+  return join(PKG_DIR, "dist", "hooks", `${hookName}.js`);
+}
+function getMcpServerPath() {
+  return join(PKG_DIR, "dist", "index.js");
+}
+function loadSettings() {
+  if (!existsSync(SETTINGS_PATH))
+    return {};
+  try {
+    return JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function saveSettings(settings) {
+  if (!existsSync(CLAUDE_DIR))
+    mkdirSync(CLAUDE_DIR, { recursive: true });
+  writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + `
+`);
+}
+function install() {
+  console.log(`claude-memory-hub \u2014 install
+`);
+  console.log("1. Registering MCP server...");
+  const mcpPath = getMcpServerPath();
+  const result = spawnSync("claude", ["mcp", "add", "claude-memory-hub", "-s", "user", "--", "bun", "run", mcpPath], {
+    stdio: "inherit"
+  });
+  if (result.status !== 0) {
+    console.log("   claude CLI not available \u2014 registering in settings.json directly");
+    const settings2 = loadSettings();
+    settings2.mcpServers ??= {};
+    settings2.mcpServers["claude-memory-hub"] = {
+      command: "bun",
+      args: ["run", mcpPath]
+    };
+    saveSettings(settings2);
+  }
+  console.log("   MCP server registered.");
+  console.log(`
+2. Registering hooks...`);
+  const settings = loadSettings();
+  settings.hooks ??= {};
+  const hookEntries = [
+    ["PostToolUse", getHookPath("post-tool-use")],
+    ["UserPromptSubmit", getHookPath("user-prompt-submit")],
+    ["PreCompact", getHookPath("pre-compact")],
+    ["PostCompact", getHookPath("post-compact")],
+    ["Stop", getHookPath("session-end")]
+  ];
+  let registered = 0;
+  for (const [event, scriptPath] of hookEntries) {
+    const hooks = settings.hooks;
+    hooks[event] ??= [];
+    const exists = hooks[event].some((e) => JSON.stringify(e).includes("claude-memory-hub"));
+    if (!exists) {
+      hooks[event].push({
+        matcher: "",
+        hooks: [{ type: "command", command: `bun run ${scriptPath}` }]
+      });
+      registered++;
+    }
+  }
+  saveSettings(settings);
+  console.log(`   ${registered} hook(s) registered. (${5 - registered} already existed)`);
+  const dataDir = join(homedir(), ".claude-memory-hub");
+  if (!existsSync(dataDir)) {
+    mkdirSync(dataDir, { recursive: true, mode: 448 });
+    console.log(`
+3. Created data directory: ${dataDir}`);
+  } else {
+    console.log(`
+3. Data directory exists: ${dataDir}`);
+  }
+  console.log(`
+========================================`);
+  console.log("Installation complete!");
+  console.log("");
+  console.log("  MCP:   claude-memory-hub");
+  console.log("  Hooks: PostToolUse, UserPromptSubmit, PreCompact, PostCompact, Stop");
+  console.log("  Data:  ~/.claude-memory-hub/memory.db");
+  console.log("  Key:   not needed");
+  console.log("");
+  console.log("  Restart Claude Code to activate.");
+  console.log("========================================");
+}
+function uninstall() {
+  console.log(`claude-memory-hub \u2014 uninstall
+`);
+  spawnSync("claude", ["mcp", "remove", "claude-memory-hub", "-s", "user"], {
+    stdio: "inherit"
+  });
+  const settings = loadSettings();
+  if (settings.hooks) {
+    const hooks = settings.hooks;
+    for (const event of Object.keys(hooks)) {
+      hooks[event] = hooks[event].filter((e) => !JSON.stringify(e).includes("claude-memory-hub"));
+      if (hooks[event].length === 0)
+        delete hooks[event];
+    }
+  }
+  if (settings.mcpServers) {
+    delete settings.mcpServers["claude-memory-hub"];
+  }
+  saveSettings(settings);
+  console.log("Removed MCP server and hooks from settings.json.");
+  console.log("Data at ~/.claude-memory-hub/ preserved. Delete manually if desired.");
+}
+function status() {
+  console.log(`claude-memory-hub \u2014 status
+`);
+  const settings = loadSettings();
+  const hasMcp = !!settings.mcpServers?.["claude-memory-hub"];
+  const hookCount = Object.values(settings.hooks ?? {}).flat().filter((e) => JSON.stringify(e).includes("claude-memory-hub")).length;
+  const dataDir = join(homedir(), ".claude-memory-hub");
+  const hasData = existsSync(join(dataDir, "memory.db"));
+  console.log(`  MCP server:  ${hasMcp ? "registered" : "not registered"}`);
+  console.log(`  Hooks:       ${hookCount}/5 registered`);
+  console.log(`  Database:    ${hasData ? "exists" : "not created yet"}`);
+  if (hasData) {
+    const { statSync } = __require("fs");
+    const stats = statSync(join(dataDir, "memory.db"));
+    console.log(`  DB size:     ${(stats.size / 1024).toFixed(1)} KB`);
+  }
+  if (!hasMcp || hookCount < 5) {
+    console.log(`
+  Run: npx claude-memory-hub install`);
+  } else {
+    console.log(`
+  Everything looks good.`);
+  }
+}
+var command = process.argv[2];
+switch (command) {
+  case "install":
+    install();
+    break;
+  case "uninstall":
+    uninstall();
+    break;
+  case "status":
+    status();
+    break;
+  default:
+    console.log(`claude-memory-hub \u2014 persistent memory for Claude Code
+`);
+    console.log("Commands:");
+    console.log("  install     Register MCP server + hooks");
+    console.log("  uninstall   Remove MCP server + hooks");
+    console.log("  status      Check installation status");
+    console.log(`
+Usage: npx claude-memory-hub <command>`);
+    break;
+}