claude-memory-hub 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -5,6 +5,82 @@ Format follows [Keep a Changelog](https://keepachangelog.com/).
 
 ---
 
+## [0.11.0] - 2026-04-03
+
+Privacy-first memory, smarter search, and slash commands. Three features the community asked for most.
+
+### New Feature: Privacy Protection (3-layer)
+
+- **`<private>` tag stripping** — wrap sensitive content in `<private>API_KEY=sk-xxx</private>` and it's replaced with `[REDACTED]` before reaching the database. Works across all capture points: entity extraction, observations, user prompts, transcript parsing
+- **Auto secret detection** — built-in regex patterns catch API keys (`sk-`, `ghp_`, `gho_`, `AKIA`), Bearer tokens, passwords, private key blocks, and hex/base64 secrets. Keeps first 12 chars for identification, redacts the rest
+- **Path-based filtering** — files matching `.env`, `.env.*`, `*.pem`, `*.key`, `*.p12`, `credentials.*`, `**/secrets/**`, `**/private/**` are completely excluded from entity tracking. No file_read/file_modified entities created for these paths
+- **Custom configuration** — create `~/.claude-memory-hub/privacy.json` to add your own ignored paths and regex patterns. Custom rules are added to defaults, not replacing them
+- **New file: `src/capture/privacy-filter.ts`** — self-contained privacy engine with `sanitize()` and `isIgnoredPath()` APIs. Called at every capture point. <1ms overhead (regex-only, no I/O)
+
+#### Files changed
+
+| File | Change |
+|------|--------|
+| `src/capture/privacy-filter.ts` | **New** — 3-layer privacy engine (230 LOC) |
+| `src/capture/entity-extractor.ts` | `isIgnoredPath()` on file entities + `sanitize()` on all values/context |
+| `src/capture/observation-extractor.ts` | `sanitize()` input before heuristic matching |
+| `src/capture/hook-handler.ts` | `sanitize()` user prompts before saving to messages table |
+| `src/capture/transcript-parser.ts` | `sanitize()` all messages before returning |
+
+### New Feature: Enhanced Semantic Search
+
+- **Code-aware tokenizer** — TF-IDF tokenizer now splits camelCase (`getUserName` → `get`, `user`, `name`), snake_case (`user_auth_service` → `user`, `auth`, `service` + full compound), and file paths (`/src/hooks/auth.ts` → `src`, `hooks`, `auth`, `ts`). Dramatically improves search for code-heavy memory content
+- **Expanded stop words (100+)** — added code keywords (`const`, `let`, `var`, `function`, `return`, `class`, `import`, `export`, `async`, `await`, etc.) and CLI noise words (`file`, `line`, `error`, `warning`, `info`, `debug`, `log`). Reduces false matches on high-frequency, low-signal terms
+- **Recency decay** — search results from recent sessions are boosted: <7 days = 1.5x, <30 days = 1.2x, 30-90 days = 1.0x, >90 days = 0.8x. Yesterday's work ranks higher than last quarter's
+- **RRF multi-source fusion** — results found by 2+ search engines (FTS5, TF-IDF, semantic) get a boost: 2 engines = 1.2x, 3 engines = 1.4x. Cross-validated results are more likely relevant
+- **Score combination** — deduplication now properly combines scores across engines instead of just keeping max. RRF + recency + multi-source = significantly better ranking
+
+#### Files changed
+
+| File | Change |
+|------|--------|
+| `src/search/vector-search.ts` | Code-aware tokenizer, 100+ stop words, `tokenize()` now exported |
+| `src/search/search-workflow.ts` | RRF fusion, recency decay, multi-source boost in `searchIndex()` |
+
+### New Feature: Slash Commands
+
+- **`/mem-search <query>`** — 3-layer progressive memory search. Guides Claude through the index → timeline → fetch workflow automatically
+- **`/mem-status [project]`** — runs health check + token budget analysis + current session activity in one command
+- **`/mem-save <note>`** — saves an important decision or finding to persistent memory via `memory_store`
+- **Auto-install** — commands are copied to `~/.claude/commands/` during `bunx claude-memory-hub install` and removed on `uninstall`
+- **Improved MCP tool descriptions** — all 10 tool descriptions rewritten with AUTO-USE hints, workflow guidance, and clearer parameter docs. `memory_recall` and `memory_entities` now suggest proactive usage
+
+#### Files changed
+
+| File | Change |
+|------|--------|
+| `commands/mem-search.md` | **New** — `/mem-search` slash command |
+| `commands/mem-status.md` | **New** — `/mem-status` slash command |
+| `commands/mem-save.md` | **New** — `/mem-save` slash command |
+| `src/cli/main.ts` | `installCommands()` + `uninstallCommands()` + install output updated |
+| `src/mcp/tool-definitions.ts` | All 10 tool descriptions rewritten with AUTO-USE and workflow hints |
+
+### Before vs After
+
+```
+Before (0.10.x):
+  Privacy:  None — API keys, tokens, passwords stored in plain text
+  Search:   "getUserName" only matches exact term; 3-month-old results rank same as today's
+  Commands: None — must know MCP tool names and call manually
+
+After (0.11.0):
+  Privacy:  <private> tags + auto-detect sk-/ghp_/Bearer/AKIA + .env/.pem excluded
+  Search:   "getUserName" matches "get", "user", "name"; today's work ranks 1.5x higher
+  Commands: /mem-search, /mem-status, /mem-save — Claude knows the workflow
+```
+
+### Documentation
+
+- **README.md** — added Privacy Protection section, Slash Commands section, updated comparison table (4 new rows), updated Data & Privacy section, updated Version History
+- **CLAUDE.md** — added `privacy-filter.ts` to project structure, updated search descriptions, added 4 new key patterns
+
+---
+
 ## [0.10.0] - 2026-04-03
 
 Full conversation capture — memory-hub now remembers what you said AND what Claude said.

package/README.md

@@ -13,7 +13,7 @@
   <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.
+Zero API key. Zero Python. Zero config. One install command. Privacy-first.
 
 ---
 
@@ -28,7 +28,9 @@ What makes it different? **The Compact Interceptor** — something no other memo
 But it doesn't stop there:
 - **Full conversation capture** — every user prompt + assistant response saved via transcript parsing
 - **Cross-session memory** — past work auto-injected when you start a new session
-- **3-engine hybrid search** — FTS5 + TF-IDF + semantic embeddings (384-dim, offline)
+- **3-engine hybrid search** — FTS5 + TF-IDF + semantic embeddings with recency-aware ranking
+- **Privacy-first** — `<private>` tags, auto secret detection, path-based filtering
+- **Slash commands** — `/mem-search`, `/mem-status`, `/mem-save` built-in
 - **Proactive retrieval** — detects topic shifts mid-session, injects relevant context automatically
 - **100+ unit tests**, batch queue (75ms→3ms), JSONL export/import, browser UI
 - **Multi-agent ready** — subagents share memory for free via MCP
@@ -64,6 +66,10 @@ Search:        Keyword-only, no semantic ranking
 | Cross-session memory | -- | Yes | **Yes** |
 | Full conversation capture (user+assistant) | -- | -- | **Yes** |
 | Conversation search (FTS5) | -- | -- | **Yes** |
+| Privacy filtering (`<private>` tags + secret detection) | -- | Partial | **Yes** |
+| Slash commands (`/mem-search`, `/mem-status`, `/mem-save`) | -- | Yes | **Yes** |
+| Code-aware search (camelCase, snake_case, paths) | -- | -- | **Yes** |
+| Recency-aware ranking (recent sessions boosted) | -- | -- | **Yes** |
 | Influence what compact preserves | -- | -- | **Yes** |
 | Save compact output to L3 | -- | -- | **Yes** |
 | Hybrid search (FTS5 + TF-IDF + semantic) | -- | Partial | **Yes** |
@@ -158,7 +164,7 @@ memory-hub search:  query → Layer 1 (index)    → ~50 tokens/result
                     Token savings: ~80-90% vs. full context
 ```
 
-Hybrid ranking: FTS5 BM25 (keyword) + TF-IDF (term frequency) + semantic cosine similarity (384-dim embeddings). "debugging tips" matches "error fixing" even without shared keywords.
+Hybrid ranking: FTS5 BM25 (keyword) + TF-IDF (term frequency) + semantic cosine similarity (384-dim embeddings). Code-aware tokenizer splits camelCase, snake_case, and file paths into meaningful tokens. Recency decay boosts recent sessions (7d=1.5x, 30d=1.2x, >90d=0.8x). Multi-source boost rewards results found by 2+ engines. "debugging tips" matches "error fixing" even without shared keywords.
 
 ### Layer 5 — Resource Intelligence
 
@@ -266,6 +272,80 @@ User prompt contains "remember that we use TypeScript strict"
 
 ---
 
+## Privacy Protection
+
+3-layer privacy system — sensitive data never reaches the database.
+
+### Layer 1: `<private>` Tags
+
+Wrap sensitive content in `<private>` tags — stripped before storage:
+
+```
+<private>API_KEY=sk-abc123def456</private>
+→ stored as: [REDACTED]
+```
+
+### Layer 2: Auto Secret Detection
+
+Built-in patterns catch common secrets automatically:
+
+```
+sk-proj-abc123...          → sk-proj-abc1[REDACTED]
+Bearer eyJhbGci...         → Bearer eyJhb[REDACTED]
+password: "hunter2"        → password: "h[REDACTED]
+AKIAIOSFODNN7...           → AKIAIOSFODNN[REDACTED]
+-----BEGIN PRIVATE KEY---- → [REDACTED]
+```
+
+Detected: API keys (`sk-`, `ghp_`, `gho_`, `AKIA`), Bearer tokens, passwords, private keys, hex/base64 secrets.
+
+### Layer 3: Path Filtering
+
+Sensitive files are completely excluded from entity tracking:
+
+```
+.env, .env.*, *.pem, *.key, *.p12
+credentials.*, **/secrets/**, **/private/**
+```
+
+### Custom Configuration
+
+Create `~/.claude-memory-hub/privacy.json` to extend:
+
+```json
+{
+  "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.
+
+---
+
+## Slash Commands
+
+Installed automatically with `bunx claude-memory-hub install`. Available as `/mem-*` in Claude Code.
+
+| 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 |
+
+```bash
+# Examples
+/mem-search auth login bug
+/mem-status claude-memory-hub
+/mem-save Decided to use JWT refresh tokens with 15min expiry
+```
+
+Commands are copied to `~/.claude/commands/` during install and removed on uninstall.
+
+---
+
 ## Install
 
 ### From npm (recommended)
@@ -274,7 +354,7 @@ User prompt contains "remember that we use TypeScript strict"
 bunx claude-memory-hub install
 ```
 
-One command. Registers MCP server + 5 hooks globally. Works on CLI, VS Code, JetBrains.
+One command. Registers MCP server + 5 hooks + 3 slash commands globally. Works on CLI, VS Code, JetBrains.
 
 **Coming from claude-mem?** The installer auto-detects `~/.claude-mem/claude-mem.db` and migrates your data automatically.
 
@@ -318,11 +398,11 @@ Claude can call these tools directly during conversation:
 
 | Tool | What it does | When to use |
 |------|-------------|-------------|
-| `memory_recall` | FTS5 search past sessions (supports `max_tokens`) | 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 (L1 cache) | Mid-session, checking what's been done |
-| `memory_store` | Manually save a note or decision | Preserving important context |
-| `memory_context_budget` | Analyze token costs + overhead report | Understanding resource usage |
+| `memory_recall` | FTS5 + semantic search past sessions (AUTO-USE) | Starting any task — proactively checks for prior work |
+| `memory_entities` | Find all sessions that touched a file (AUTO-USE) | Before editing any file — understand its history |
+| `memory_session_notes` | Current session activity (L1 cache) | Mid-session review of files, decisions, errors |
+| `memory_store` | Save a note/decision to persistent memory | Architectural decisions, key findings, workarounds |
+| `memory_context_budget` | Token overhead analysis + recommendations | When sessions feel slow or context seems bloated |
 
 ### 3-Layer Search
 
@@ -439,6 +519,7 @@ Migration is idempotent — safe to run multiple times with zero duplicates.
 | **v0.9.5** | Stable install path — hooks no longer break after reboot or bunx cache cleanup |
 | **v0.9.6** | Agent/Skill result capture, higher summary limits, IDE tag stripping, PostCompact cap, broader observation patterns (20+) |
 | **v0.10.0** | **Full conversation capture** — all user prompts + assistant responses via transcript parsing, `messages` table with FTS5, `memory_conversation` MCP tool, conversation-enriched summaries |
+| **v0.11.0** | **Privacy + Search + Commands** — 3-layer privacy filtering (`<private>` tags, auto secret detection, path filtering), code-aware tokenizer (camelCase/snake_case/path splitting), recency-aware ranking (7d/30d/90d decay), RRF multi-source fusion, slash commands (`/mem-search`, `/mem-status`, `/mem-save`), improved MCP tool descriptions with AUTO-USE hints |
 
 See [CHANGELOG.md](CHANGELOG.md) for full details.
 
@@ -468,11 +549,12 @@ bun:sqlite                         Built-in, zero install
 
 ## Data & Privacy
 
-All data stored locally at `~/.claude-memory-hub/`.
+All data stored locally at `~/.claude-memory-hub/`. **Privacy-first by design.**
 
 ```
 ~/.claude-memory-hub/
   ├── memory.db           # SQLite database (all memory data)
+  ├── privacy.json        # Privacy config (optional — custom patterns/paths)
   ├── batch/
   │   └── queue.jsonl     # PostToolUse batch queue (auto-flushed)
   ├── proactive/
@@ -481,6 +563,11 @@ All data stored locally at `~/.claude-memory-hub/`.
       └── memory-hub.log  # Structured JSON logs (auto-rotated at 5MB)
 ```
 
+**3-layer privacy protection** (see [Privacy Protection](#privacy-protection)):
+- `<private>` tags stripped before storage
+- API keys, tokens, passwords auto-detected and redacted
+- Sensitive file paths (`.env`, `*.pem`, `*.key`) excluded from tracking
+
 No cloud. No telemetry. No network calls. Your memory stays on your machine.
 
 ---

package/dist/cli.js

@@ -852,12 +852,42 @@ var init_semantic_search = __esm(() => {
 var exports_vector_search = {};
 __export(exports_vector_search, {
   vectorSearch: () => vectorSearch,
+  tokenize: () => tokenize,
   reindexAll: () => reindexAll,
   rebuildIDF: () => rebuildIDF,
   indexDocument: () => indexDocument
 });
 function tokenize(text) {
-  return text.toLowerCase().replace(/[^a-z0-9_./\-]/g, " ").split(/\s+/).filter((w) => w.length > 1 && !STOP_WORDS.has(w));
+  const tokens = [];
+  const camelSplit = text.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2");
+  const words = camelSplit.toLowerCase().replace(/[^a-z0-9_./\-]/g, " ").split(/\s+/).filter(Boolean);
+  for (const word of words) {
+    if (word.includes("/") && word.length > 3) {
+      const parts = word.split("/").filter((p) => p.length > 1);
+      for (const part of parts) {
+        const subparts = part.split(".").filter((s) => s.length > 1);
+        for (const sp of subparts) {
+          if (!STOP_WORDS.has(sp))
+            tokens.push(sp);
+        }
+      }
+      continue;
+    }
+    if (word.includes("_") && word.length > 3) {
+      const parts = word.split("_").filter((p) => p.length > 1);
+      for (const part of parts) {
+        if (!STOP_WORDS.has(part))
+          tokens.push(part);
+      }
+      if (!STOP_WORDS.has(word))
+        tokens.push(word);
+      continue;
+    }
+    if (word.length > 1 && !STOP_WORDS.has(word)) {
+      tokens.push(word);
+    }
+  }
+  return tokens;
 }
 function computeTF(tokens) {
   const freq = new Map;
@@ -1056,7 +1086,63 @@ var init_vector_search = __esm(() => {
     "her",
     "they",
     "them",
-    "their"
+    "their",
+    "const",
+    "let",
+    "var",
+    "function",
+    "return",
+    "class",
+    "new",
+    "true",
+    "false",
+    "null",
+    "undefined",
+    "void",
+    "type",
+    "interface",
+    "export",
+    "import",
+    "from",
+    "default",
+    "async",
+    "await",
+    "try",
+    "catch",
+    "throw",
+    "if",
+    "else",
+    "for",
+    "while",
+    "switch",
+    "case",
+    "break",
+    "continue",
+    "public",
+    "private",
+    "protected",
+    "static",
+    "readonly",
+    "extends",
+    "implements",
+    "super",
+    "this",
+    "typeof",
+    "instanceof",
+    "file",
+    "line",
+    "error",
+    "warning",
+    "info",
+    "debug",
+    "log",
+    "true",
+    "false",
+    "yes",
+    "no",
+    "ok",
+    "done",
+    "success"
   ]);
 });
 
@@ -1127,10 +1213,32 @@ async function searchIndex(query, opts = {}, db) {
   for (const r of filtered) {
     const key = `${r.type}:${r.id}`;
     const existing = deduped.get(key);
-    if (!existing || r.score > existing.score)
-      deduped.set(key, r);
+    if (!existing) {
+      deduped.set(key, { ...r, sourceCount: 1 });
+    } else {
+      existing.score = Math.max(existing.score, r.score);
+      existing.sourceCount++;
+    }
   }
-  const merged = [...deduped.values()];
+  const now = Date.now();
+  const merged = [...deduped.values()].map((r) => {
+    let score = r.score;
+    const ageMs = now - r.created_at;
+    const ageDays = ageMs / (1000 * 60 * 60 * 24);
+    if (ageDays < 7)
+      score *= 1.5;
+    else if (ageDays < 30)
+      score *= 1.2;
+    else if (ageDays < 90)
+      score *= 1;
+    else
+      score *= 0.8;
+    if (r.sourceCount >= 3)
+      score *= 1.4;
+    else if (r.sourceCount >= 2)
+      score *= 1.2;
+    return { ...r, score };
+  });
   merged.sort((a, b) => b.score - a.score);
   return merged.slice(0, limit);
 }
@@ -2009,6 +2117,7 @@ function buildSummaryText(s) {
 import { spawnSync } from "child_process";
 var CLAUDE_DIR = join5(homedir5(), ".claude");
 var SETTINGS_PATH = join5(CLAUDE_DIR, "settings.json");
+var COMMANDS_DIR = join5(CLAUDE_DIR, "commands");
 var PKG_DIR = resolve(dirname(import.meta.dir));
 var STABLE_DIR = join5(homedir5(), ".claude-memory-hub");
 function shellPath(p) {
@@ -2079,6 +2188,32 @@ function saveSettings(settings) {
   writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + `
 `);
 }
+function installCommands() {
+  const srcCommands = join5(PKG_DIR, "commands");
+  if (!existsSync5(srcCommands))
+    return 0;
+  mkdirSync3(COMMANDS_DIR, { recursive: true });
+  let count = 0;
+  for (const file of readdirSync(srcCommands)) {
+    if (!file.endsWith(".md"))
+      continue;
+    const src = join5(srcCommands, file);
+    const dest = join5(COMMANDS_DIR, file);
+    writeFileSync(dest, readFileSync(src));
+    count++;
+  }
+  return count;
+}
+function uninstallCommands() {
+  const memCommands = ["mem-search.md", "mem-status.md", "mem-save.md"];
+  for (const file of memCommands) {
+    const p = join5(COMMANDS_DIR, file);
+    try {
+      if (existsSync5(p))
+        __require("fs").unlinkSync(p);
+    } catch {}
+  }
+}
 function install() {
   console.log(`claude-memory-hub \u2014 install
 `);
@@ -2142,13 +2277,18 @@ function install() {
 3. Data directory exists: ${dataDir}`);
   }
   console.log(`
+4. Installing slash commands...`);
+  const cmdCount = installCommands();
+  console.log(`   ${cmdCount} command(s) installed to ~/.claude/commands/`);
+  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("  MCP:      claude-memory-hub");
+  console.log("  Hooks:    PostToolUse, UserPromptSubmit, PreCompact, PostCompact, Stop");
+  console.log("  Commands: /mem-search, /mem-status, /mem-save");
+  console.log("  Data:     ~/.claude-memory-hub/memory.db");
+  console.log("  Key:      not needed");
   console.log("");
   console.log("  Restart Claude Code to activate.");
   console.log("========================================");
@@ -2171,6 +2311,8 @@ function install() {
 function uninstall() {
   console.log(`claude-memory-hub \u2014 uninstall
 `);
+  uninstallCommands();
+  console.log("Removed slash commands from ~/.claude/commands/");
   spawnSync("claude", ["mcp", "remove", "claude-memory-hub", "-s", "user"], {
     stdio: "inherit"
   });