claude-memory-hub 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -5,6 +5,48 @@ Format follows [Keep a Changelog](https://keepachangelog.com/).
 
 ---
 
+## [0.8.1] - 2026-04-02
+
+Token-budget-aware MCP tools + proactive mid-session memory retrieval.
+
+### Token Budget Management
+
+- **`max_tokens` parameter** — added to `memory_recall`, `memory_search`, `memory_fetch` MCP tools. When set, output is truncated to fit within the specified token budget (~4 chars/token). Helps Claude manage context window when many tools compete for space
+- **`truncateToTokenBudget()` utility** — shared truncation function with `[...truncated to fit ~N token budget]` suffix
+
+### Proactive Memory Retrieval
+
+- **Topic-shift detection** — PostToolUse hook now monitors file activity and detects when conversation drifts to a new domain (e.g., auth → payment → migration). Detection uses directory clustering + keyword matching across recent files
+- **Mid-session context injection** — when topic shift detected, hook searches L3 for relevant past context and returns `additionalContext` via stdout JSON. Claude Code injects this into the conversation automatically
+- **Trigger conditions:** every 15 tool calls OR on Bash errors after warmup (5+ calls)
+- **State tracking** — per-session state at `~/.claude-memory-hub/proactive/<session_id>.json`, cleaned up on session end
+- **Injection cap:** ~375 tokens (1500 chars) per injection, deduplicated by topic
+
+### Session End Improvements
+
+- **Batch queue flush on session end** — `tryFlush()` called during Stop hook to prevent data loss from unflushed batch events
+- **Proactive state cleanup** — per-session state files removed on session end
+
+### Research Findings (documented, no code changes needed)
+
+Based on deep Claude Code source analysis:
+- **Resource filtering:** Claude Code already defers MCP tools automatically via `isDeferredTool()`. Skill listings have budget system (`SKILL_BUDGET_CONTEXT_PERCENT=1%`). No external filtering needed
+- **Multi-agent sharing:** Subagents inherit parent MCP servers via `initializeAgentMcpServers()`. Memory sharing via `memory_recall` works out-of-box — zero implementation needed
+- **Permission-aware:** PostToolUse hook only fires for approved tools. Denied tools fire separate `PermissionDenied` hook. memory-hub is already permission-aware by design
+- **IDE context:** Available as attachments in conversation (ide_selection, ide_opened_file) but not in hook inputs directly. Entity extraction captures file activity indirectly
+
+### Modified Files
+
+```
+src/mcp/tool-definitions.ts           — max_tokens param on 3 tools
+src/mcp/tool-handlers.ts              — truncateToTokenBudget() utility
+src/retrieval/proactive-retrieval.ts   — NEW: topic detection + injection
+src/hooks-entry/post-tool-use.ts       — proactive retrieval integration
+src/hooks-entry/session-end.ts         — batch flush + proactive cleanup
+```
+
+---
+
 ## [0.8.0] - 2026-04-02
 
 Major release: test infrastructure, architectural fixes, hook performance, data portability.

package/README.md

@@ -19,7 +19,7 @@ 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. Search is keyword-only with no ranking.
+Claude Code forgets everything between sessions. Within long sessions, auto-compact destroys 90% of context. Search is keyword-only with no ranking.
 
 ```
 Session 1: You spend 2 hours building auth system
@@ -29,37 +29,31 @@ 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
-               → No external tool can prevent this (Claude Code limitation)
-               → But you CAN identify and remove unused resources
-
 Search:        Keyword-only, no semantic ranking
                → Irrelevant results, wasted tokens on full records
 ```
 
-**Four problems. memory-hub solves three directly and provides analysis for the fourth.**
-
 | Problem | Claude Code built-in | claude-mem | memory-hub |
 |---------|:-------------------:|:----------:|:----------:|
 | Cross-session memory | -- | Yes | **Yes** |
 | Influence what compact preserves | -- | -- | **Yes** |
-| Save compact output | -- | -- | **Yes** |
-| Token overhead analysis | -- | -- | **Yes** |
-| Semantic search (embeddings) | -- | Chroma (external) | **Yes (offline)** |
+| Save compact output to L3 | -- | -- | **Yes** |
 | Hybrid search (FTS5 + TF-IDF + semantic) | -- | Partial | **Yes** |
 | 3-layer progressive search | -- | Yes | **Yes** |
 | Resource overhead analysis | -- | -- | **Yes** |
 | CLAUDE.md rule tracking | -- | -- | **Yes** |
-| Free-form observation capture | -- | Yes | **Yes** |
+| Observation capture (14 patterns) | -- | Yes | **Yes** |
 | LLM summarization (3-tier) | -- | Yes (API) | **Yes (free)** |
+| Token-budget-aware tools (`max_tokens`) | -- | -- | **Yes** |
+| Proactive mid-session retrieval | -- | -- | **Yes** |
+| Multi-agent memory sharing | -- | -- | **Yes (free)** |
+| Permission-aware (approved only) | -- | -- | **Yes** |
+| Data export/import (JSONL) | -- | -- | **Yes** |
+| Hook batching (3ms vs 75ms) | -- | -- | **Yes** |
 | Browser UI | -- | Yes | **Yes** |
-| Health monitoring | -- | -- | **Yes** |
-| Migrate from claude-mem | N/A | N/A | **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** |
+| Health monitoring + auto-cleanup | -- | -- | **Yes** |
+| Unit tests (91 tests) | N/A | -- | **Yes** |
+| No API key / Python / Chroma | N/A | Partial | **Yes** |
 
 ---
 
@@ -75,6 +69,8 @@ Claude makes a decision → memory-hub records: decision text + importance score
 ```
 
 No XML. No special format. Extracted directly from hook JSON metadata.
+PostToolUse events are batched via write-through queue (~3ms per event vs ~75ms direct).
+Mid-session topic shifts auto-inject relevant past context (proactive retrieval).
 
 ### Layer 2 — Compact Interceptor (the key innovation)
 
@@ -99,41 +95,21 @@ No XML. No special format. Extracted directly from hook JSON metadata.
                       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**.
+**No other memory tool does this.** 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 ends  → 3-tier summarization: PostCompact > CLI claude > rule-based
+                → Summary saved to SQLite L3 with FTS5 indexing
 
 Session N+1     → UserPromptSubmit hook fires
-                → FTS5 + TF-IDF hybrid search: match user prompt
-                → inject relevant context automatically
+                → FTS5 + TF-IDF + semantic search: match user prompt
+                → Inject relevant past context automatically
                 → Claude starts with history, not from zero
 ```
 
-### Layer 4 — Resource Intelligence & Overhead Analysis
-
-```
-ResourceRegistry scans your setup:
-  58 skills, 36 agents, 65 commands, 10 workflows, CLAUDE.md chain
-
-ResourceTracker records actual usage per session:
-  "skill:mobile-development used 4/5 recent sessions"
-  "agent:veo3-prompt-expert used 0/5 recent sessions"
-
-OverheadReport identifies waste:
-  "42/58 skills never used → ~1500 listing tokens overhead"
-  "CLAUDE.md chain is 8200 tokens → consider consolidating"
-
-UserPromptSubmit injects priority hints:
-  "Frequently-used: skill:debugging, agent:planner, agent:tester"
-```
-
-> **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 actually reduce token overhead, remove or relocate unused skills/agents based on the overhead report.
-
-### Layer 5 — 3-Layer Progressive Search + Semantic (new in v0.5/v0.6)
+### Layer 4 — 3-Layer Progressive Search
 
 ```
 Traditional search: query → ALL full records → 5000+ tokens wasted
@@ -146,34 +122,33 @@ 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, v0.6). "debugging tips" now matches "error fixing" even without shared keywords.
+Hybrid ranking: FTS5 BM25 (keyword) + TF-IDF (term frequency) + semantic cosine similarity (384-dim embeddings). "debugging tips" matches "error fixing" even without shared keywords.
 
-### Layer 6 — Resource Intelligence (new in v0.6)
+### Layer 5 — Resource Intelligence
 
 ```
 ResourceRegistry scans ALL .claude locations:
-  ~/.claude/skills/          58 skills → listing + full + total tokens
-  ~/.claude/agents/          36 agents → frontmatter name: resolution
-  ~/.claude/agent_mobile/    ios-developer → agent_mobile/ios/AGENT.md
-  ~/.claude/commands/        65 commands → relative path naming
-  ~/.claude/workflows/       10 workflows
-  ~/.claude/CLAUDE.md        + project CLAUDE.md chain
-
-OverheadReport:
-  "56/64 skills unused in last 10 sessions → ~1033 listing tokens wasted"
-  "CLAUDE.md chain is 3222 tokens"
+  skills, agents, commands, workflows, CLAUDE.md chain
+  → 3-level token estimation: listing, full, total
+
+ResourceTracker records actual usage per session
+OverheadReport identifies unused resources + token waste
 ```
 
-### Layer 7 — Observation Capture (new in v0.6)
+> **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.
+
+### Layer 6 — Observation Capture
 
 ```
 Tool output contains "IMPORTANT: always pool DB connections"
   → observation entity (importance=4) saved to L2
-  → included in session summary
-  → searchable across sessions
 
 User prompt contains "remember that we use TypeScript strict"
   → observation entity (importance=3) saved to L2
+
+14 heuristic patterns: IMPORTANT, CRITICAL, SECURITY, DEPRECATED,
+  decision:, discovered, root cause, switched to, TODO:, FIXME:,
+  HACK:, performance:, bottleneck, OOM, don't, never, prefer, etc.
 ```
 
 ---
@@ -187,7 +162,7 @@ User prompt contains "remember that we use TypeScript strict"
 │  5 Lifecycle Hooks                                           │
 │  ┌───────────────┐  ┌──────────────┐  ┌──────────────┐      │
 │  │ PostToolUse   │  │ PreCompact   │  │ PostCompact  │      │
-│  │ entity capture│  │ inject       │  │ save summary │      │
+│  │ batch queue   │  │ inject       │  │ save summary │      │
 │  └──────┬────────┘  │ priorities   │  └──────┬───────┘      │
 │         │           └──────┬───────┘         │              │
 │  ┌──────┴───────┐          │          ┌──────┴───────┐      │
@@ -196,43 +171,32 @@ User prompt contains "remember that we use TypeScript strict"
 │  │past context  │          │          │ summarize    │      │
 │  └──────────────┘          │          └──────────────┘      │
 │                            │                                │
-│  MCP Server (stdio)        │   Health Monitor               │
-│  ┌─────────────────────┐   │   ┌────────────────────────┐   │
-│  │ memory_recall       │   │   │ sqlite, fts5, disk,    │   │
-│  │ memory_entities     │   │   │ integrity checks       │   │
-│  │ memory_session_notes│   │   └────────────────────────┘   │
-│  │ memory_store        │   │                                │
-│  │ memory_context_budget│  │   Smart Resource Loader        │
-│  │ memory_search  ←L1  │   │   ┌────────────────────────┐   │
-│  │ memory_timeline ←L2 │   │   │ track usage → predict  │   │
-│  │ memory_fetch   ←L3  │   │   │ → budget → recommend   │   │
-│  │ memory_health       │   │   └────────────────────────┘   │
-│  └─────────────────────┘   │                                │
-│                            │   Browser UI (:37888)          │
-│                            │   ┌────────────────────────┐   │
-│                            │   │ search, browse, stats  │   │
-│                            │   └────────────────────────┘   │
-│                            │                                │
-└────────────────────────────┼────────────────────────────────┘
+│  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_health                                        │    │
+│  │                                                      │    │
+│  │ L1 WorkingMemory: read-through cache over L2         │    │
+│  └─────────────────────────────────────────────────────┘    │
+│                                                              │
+│  Resource Intelligence    Browser UI (:37888)                │
+│  ┌──────────────────┐     ┌──────────────────┐              │
+│  │ scan → track →   │     │ search, browse,  │              │
+│  │ analyze overhead  │     │ stats, health    │              │
+│  └──────────────────┘     └──────────────────┘              │
+└──────────────────────────────────────────────────────────────┘
                              │
                    ┌─────────┴──────────┐
                    │   SQLite + FTS5    │
                    │   ~/.claude-       │
                    │   memory-hub/      │
-                   │   memory.db        │
                    │                    │
-                   │   sessions         │
-                   │   entities         │
-                   │   session_notes    │
-                   │   long_term_       │
-                   │    summaries       │
-                   │   resource_usage   │
-                   │   fts_memories     │
-                   │   tfidf_index      │
-                   │   embeddings       │
-                   │   claude_md_       │
-                   │    registry        │
-                   │   health_checks    │
+                   │   memory.db        │
+                   │   batch/queue.jsonl │
+                   │   logs/            │
                    └────────────────────┘
 ```
 
@@ -242,19 +206,20 @@ User prompt contains "remember that we use TypeScript strict"
 
 ```
 ┌─────────────────────────────────────────────────────┐
-│  L1: WorkingMemory          in-process Map          │
-│  Current session only       <1ms access             │
-│  Lives in MCP server        FIFO 50 entries/session │
+│  L1: WorkingMemory          Read-through cache      │
+│  Lives in MCP server        <1ms (cache hit)        │
+│  Backed by SessionStore     Auto-refresh on miss    │
+│  TTL: 5 minutes             Max 50 entries/session  │
 ├─────────────────────────────────────────────────────┤
 │  L2: SessionStore           SQLite                  │
 │  Entities + notes           <10ms access            │
-│  files_read, file_modified  Per-session scope       │
-│  errors, decisions          Importance scored       │
+│  files, errors, decisions   Per-session scope       │
+│  observations (14 patterns) Importance scored 1-5   │
 ├─────────────────────────────────────────────────────┤
 │  L3: LongTermStore          SQLite + FTS5 + TF-IDF │
 │  Cross-session summaries    <100ms access           │
 │  Hybrid ranked search       Persistent forever      │
-│  Auto-injected on start     3-layer progressive     │
+│  Semantic embeddings        3-layer progressive     │
 └─────────────────────────────────────────────────────┘
 ```
 
@@ -270,7 +235,7 @@ bunx claude-memory-hub install
 
 One command. Registers MCP server + 5 hooks 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. No manual steps needed.
+**Coming from claude-mem?** The installer auto-detects `~/.claude-mem/claude-mem.db` and migrates your data automatically.
 
 ### Update
 
@@ -278,24 +243,8 @@ One command. Registers MCP server + 5 hooks globally. Works on CLI, VS Code, Jet
 bunx claude-memory-hub@latest install
 ```
 
-Or if installed globally:
-
-```bash
-bun install -g claude-memory-hub@latest
-claude-memory-hub install
-```
-
 Your data at `~/.claude-memory-hub/` is preserved across updates. Schema migrations run automatically.
 
-### 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
-```
-
 ### All CLI commands
 
 ```bash
@@ -305,10 +254,10 @@ bunx claude-memory-hub status      # Check installation
 bunx claude-memory-hub migrate     # Import data from claude-mem
 bunx claude-memory-hub viewer      # Open browser UI at localhost:37888
 bunx claude-memory-hub health      # Run health diagnostics
-bunx claude-memory-hub reindex     # Rebuild TF-IDF search index
+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
-bunx claude-memory-hub cleanup     # Remove old data (default: 90 days)
+bunx claude-memory-hub import      # Import JSONL from stdin (--dry-run)
+bunx claude-memory-hub cleanup     # Remove old data (--days N, default 90)
 ```
 
 ### Requirements
@@ -327,13 +276,13 @@ 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_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 summary | Mid-session, checking what's been done |
+| `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 + recommendations | Optimizing which resources to load |
+| `memory_context_budget` | Analyze token costs + overhead report | Understanding resource usage |
 
-### 3-Layer Search (new in v0.5)
+### 3-Layer Search
 
 | Tool | Layer | Tokens/result | When to use |
 |------|-------|---------------|-------------|
@@ -345,7 +294,46 @@ Claude can call these tools directly during conversation:
 
 | Tool | What it does |
 |------|-------------|
-| `memory_health` | Check database, FTS5, disk, integrity status |
+| `memory_health` | Check database, FTS5, disk, embeddings, integrity status |
+
+---
+
+## Data Export/Import
+
+### Export
+
+```bash
+# Full export
+bunx claude-memory-hub export > backup.jsonl
+
+# Incremental (since timestamp)
+bunx claude-memory-hub export --since 1743580800000 > incremental.jsonl
+
+# Single table
+bunx claude-memory-hub export --table sessions > sessions.jsonl
+```
+
+### Import
+
+```bash
+# Import from file
+bunx claude-memory-hub import < backup.jsonl
+
+# Validate without writing
+bunx claude-memory-hub import --dry-run < backup.jsonl
+```
+
+### Cleanup
+
+```bash
+# Remove data older than 90 days (default)
+bunx claude-memory-hub cleanup
+
+# Custom retention
+bunx claude-memory-hub cleanup --days 30
+```
+
+Format: JSONL (one JSON object per line). Embedding BLOBs encoded as base64. Import uses UPSERT — safe to re-run.
 
 ---
 
@@ -366,20 +354,14 @@ Opens a dark-themed dashboard at `http://localhost:37888` with:
 
 ## Migrating from claude-mem
 
-If you're already using [claude-mem](https://github.com/nicobailey-llc/claude-mem), migration is seamless:
-
 ```bash
 # Automatic (during install)
 bunx claude-memory-hub install
-# → Detects ~/.claude-mem/claude-mem.db automatically
-# → Migrates sessions, observations, summaries
 
 # Manual
 bunx claude-memory-hub migrate
 ```
 
-### What gets migrated
-
 | claude-mem | → | memory-hub |
 |------------|---|------------|
 | `sdk_sessions` | → | `sessions` |
@@ -397,13 +379,14 @@ Migration is idempotent — safe to run multiple times with zero duplicates.
 | 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.2.0** | Compact interceptor (PreCompact/PostCompact), context enrichment, importance scoring |
 | **v0.3.0** | Removed API key requirement, 1-command install |
-| **v0.4.0** | Smart resource loading, token budget optimization |
+| **v0.4.0** | Resource usage tracking, token overhead analysis |
 | **v0.5.0** | Production hardening, hybrid search, 3-layer progressive search, browser UI, health monitoring, claude-mem migration |
-| **v0.6.0** | ResourceRegistry (170 resources), semantic search (384-dim embeddings), observation capture, CLAUDE.md tracking, 3-tier LLM summarization, overhead analysis |
+| **v0.6.0** | ResourceRegistry (170 resources), semantic search (384-dim embeddings), observation capture, CLAUDE.md tracking, 3-tier LLM summarization |
 | **v0.7.0** | Honest resource analysis, semantic search scaling, batch embeddings, 14 observation patterns, DB auto-cleanup, summarizer retry |
-| **v0.8.0** | 91 unit tests (was 0%), L1 WorkingMemory read-through cache, PostToolUse batch queue (75ms→3ms), JSONL export/import CLI, data cleanup command |
+| **v0.8.0** | 91 unit tests (was 0%), L1 read-through cache, PostToolUse batch queue (75ms→3ms), JSONL export/import, data cleanup CLI, CI/CD auto-publish |
+| **v0.8.1** | Token-budget-aware MCP tools (`max_tokens`), proactive mid-session memory retrieval (topic-shift detection), session-end batch flush |
 
 See [CHANGELOG.md](CHANGELOG.md) for full details.
 
@@ -437,7 +420,11 @@ All data stored locally at `~/.claude-memory-hub/`.
 
 ```
 ~/.claude-memory-hub/
-  ├── memory.db         # SQLite database (sessions, entities, summaries)
+  ├── memory.db           # SQLite database (all memory data)
+  ├── batch/
+  │   └── queue.jsonl     # PostToolUse batch queue (auto-flushed)
+  ├── proactive/
+  │   └── <session>.json  # Topic tracking state (auto-cleaned)
   └── logs/
       └── memory-hub.log  # Structured JSON logs (auto-rotated at 5MB)
 ```

package/dist/hooks/post-tool-use.js

@@ -1833,6 +1833,132 @@ function isBatchEnabled() {
   return mode !== "disabled";
 }
 
+// src/retrieval/proactive-retrieval.ts
+import { existsSync as existsSync6, readFileSync as readFileSync4, writeFileSync as writeFileSync2, mkdirSync as mkdirSync4 } from "fs";
+import { join as join6 } from "path";
+import { homedir as homedir5 } from "os";
+var log6 = createLogger("proactive-retrieval");
+var DATA_DIR2 = join6(homedir5(), ".claude-memory-hub");
+var PROACTIVE_DIR = join6(DATA_DIR2, "proactive");
+var TOOL_CALL_INTERVAL = 15;
+var MAX_INJECTION_CHARS = 1500;
+function evaluateProactiveInjection(sessionId, toolName, toolInput, toolResponse) {
+  const state = loadState(sessionId);
+  state.toolCallCount++;
+  const filePath = extractFilePath(toolName, toolInput);
+  if (filePath) {
+    state.recentFiles = [...new Set([filePath, ...state.recentFiles])].slice(0, 20);
+  }
+  const shouldTrigger = state.toolCallCount % TOOL_CALL_INTERVAL === 0 || toolName === "Bash" && typeof toolResponse.exit_code === "number" && toolResponse.exit_code !== 0 && state.toolCallCount > 5;
+  if (!shouldTrigger) {
+    saveState(sessionId, state);
+    return { shouldInject: false };
+  }
+  const currentTopic = detectTopic(state.recentFiles);
+  if (!currentTopic || state.injectedTopics.includes(currentTopic)) {
+    saveState(sessionId, state);
+    return { shouldInject: false };
+  }
+  const ltStore = new LongTermStore;
+  const results = ltStore.search(currentTopic, 2);
+  if (results.length === 0) {
+    state.injectedTopics.push(currentTopic);
+    saveState(sessionId, state);
+    return { shouldInject: false };
+  }
+  const lines = [`**Relevant past context** (topic: ${currentTopic}):`];
+  for (const r of results) {
+    const date = new Date(r.created_at).toLocaleDateString();
+    lines.push(`- [${date}] ${r.summary.slice(0, 200)}`);
+    const files = safeJson4(r.files_touched, []);
+    if (files.length > 0)
+      lines.push(`  Files: ${files.slice(0, 3).join(", ")}`);
+  }
+  let context = lines.join(`
+`);
+  if (context.length > MAX_INJECTION_CHARS) {
+    context = context.slice(0, MAX_INJECTION_CHARS) + `
+[...truncated]`;
+  }
+  state.injectedTopics.push(currentTopic);
+  state.lastInjectionAt = Date.now();
+  saveState(sessionId, state);
+  log6.info("proactive injection triggered", { sessionId, topic: currentTopic, results: results.length });
+  return { shouldInject: true, additionalContext: context };
+}
+function cleanupProactiveState(sessionId) {
+  const path = statePath(sessionId);
+  try {
+    if (existsSync6(path)) {
+      const { unlinkSync: unlinkSync2 } = __require("fs");
+      unlinkSync2(path);
+    }
+  } catch {}
+}
+function detectTopic(recentFiles) {
+  if (recentFiles.length < 3)
+    return null;
+  const dirs = recentFiles.map((f) => f.split("/").slice(0, -1).join("/")).filter(Boolean);
+  const dirCounts = new Map;
+  for (const d of dirs) {
+    const parts = d.split("/").filter(Boolean);
+    const leaf = parts[parts.length - 1];
+    if (leaf && leaf !== "src" && leaf !== "lib" && leaf !== "utils") {
+      dirCounts.set(leaf, (dirCounts.get(leaf) ?? 0) + 1);
+    }
+  }
+  let bestTopic = null;
+  let bestCount = 0;
+  for (const [topic, count] of dirCounts) {
+    if (count > bestCount) {
+      bestTopic = topic;
+      bestCount = count;
+    }
+  }
+  const fileNames = recentFiles.map((f) => f.split("/").pop() ?? "").filter(Boolean);
+  const keywords = ["auth", "payment", "user", "api", "database", "config", "test", "migration", "deploy", "search"];
+  for (const kw of keywords) {
+    const matches = fileNames.filter((f) => f.toLowerCase().includes(kw));
+    if (matches.length >= 2)
+      return kw;
+  }
+  return bestTopic;
+}
+function statePath(sessionId) {
+  return join6(PROACTIVE_DIR, `${sessionId.replace(/[^a-zA-Z0-9_-]/g, "_")}.json`);
+}
+function loadState(sessionId) {
+  const path = statePath(sessionId);
+  try {
+    if (existsSync6(path)) {
+      return JSON.parse(readFileSync4(path, "utf-8"));
+    }
+  } catch {}
+  return { toolCallCount: 0, lastInjectionAt: 0, injectedTopics: [], recentFiles: [] };
+}
+function saveState(sessionId, state) {
+  try {
+    if (!existsSync6(PROACTIVE_DIR)) {
+      mkdirSync4(PROACTIVE_DIR, { recursive: true, mode: 448 });
+    }
+    writeFileSync2(statePath(sessionId), JSON.stringify(state), "utf-8");
+  } catch {}
+}
+function extractFilePath(toolName, toolInput) {
+  if (toolName === "Read" || toolName === "Write" || toolName === "Edit" || toolName === "MultiEdit") {
+    const fp = toolInput.file_path;
+    return typeof fp === "string" ? fp : undefined;
+  }
+  return;
+}
+function safeJson4(text, fallback) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return fallback;
+  }
+}
+
 // src/hooks-entry/post-tool-use.ts
 async function main() {
   if (process.env["CLAUDE_MEMORY_HUB_SKIP_HOOKS"] === "1")
@@ -1871,9 +1997,18 @@ async function main() {
         timestamp: Date.now()
       });
       tryFlush();
-      return;
-    } catch {}
+    } catch {
+      await handlePostToolUse(hook, project);
+    }
+  } else {
+    await handlePostToolUse(hook, project);
   }
-  await handlePostToolUse(hook, project);
+  try {
+    const result = evaluateProactiveInjection(hook.session_id, hook.tool_name, hook.tool_input ?? {}, hook.tool_response ?? {});
+    if (result.shouldInject && result.additionalContext) {
+      process.stdout.write(JSON.stringify({ additionalContext: result.additionalContext }) + `
+`);
+    }
+  } catch {}
 }
 main().catch(() => {}).finally(() => process.exit(0));

package/dist/hooks/session-end.js

@@ -2021,6 +2021,250 @@ async function indexEmbedding(docType, docId, text, db) {
        created_at = excluded.created_at`, [docType, docId, blob, Date.now()]);
 }
 
+// src/retrieval/proactive-retrieval.ts
+import { existsSync as existsSync5, readFileSync as readFileSync3, writeFileSync, mkdirSync as mkdirSync3 } from "fs";
+import { join as join5 } from "path";
+import { homedir as homedir4 } from "os";
+var log9 = createLogger("proactive-retrieval");
+var DATA_DIR = join5(homedir4(), ".claude-memory-hub");
+var PROACTIVE_DIR = join5(DATA_DIR, "proactive");
+var TOOL_CALL_INTERVAL = 15;
+var MAX_INJECTION_CHARS = 1500;
+function evaluateProactiveInjection(sessionId, toolName, toolInput, toolResponse) {
+  const state = loadState(sessionId);
+  state.toolCallCount++;
+  const filePath = extractFilePath(toolName, toolInput);
+  if (filePath) {
+    state.recentFiles = [...new Set([filePath, ...state.recentFiles])].slice(0, 20);
+  }
+  const shouldTrigger = state.toolCallCount % TOOL_CALL_INTERVAL === 0 || toolName === "Bash" && typeof toolResponse.exit_code === "number" && toolResponse.exit_code !== 0 && state.toolCallCount > 5;
+  if (!shouldTrigger) {
+    saveState(sessionId, state);
+    return { shouldInject: false };
+  }
+  const currentTopic = detectTopic(state.recentFiles);
+  if (!currentTopic || state.injectedTopics.includes(currentTopic)) {
+    saveState(sessionId, state);
+    return { shouldInject: false };
+  }
+  const ltStore = new LongTermStore;
+  const results = ltStore.search(currentTopic, 2);
+  if (results.length === 0) {
+    state.injectedTopics.push(currentTopic);
+    saveState(sessionId, state);
+    return { shouldInject: false };
+  }
+  const lines = [`**Relevant past context** (topic: ${currentTopic}):`];
+  for (const r of results) {
+    const date = new Date(r.created_at).toLocaleDateString();
+    lines.push(`- [${date}] ${r.summary.slice(0, 200)}`);
+    const files = safeJson4(r.files_touched, []);
+    if (files.length > 0)
+      lines.push(`  Files: ${files.slice(0, 3).join(", ")}`);
+  }
+  let context = lines.join(`
+`);
+  if (context.length > MAX_INJECTION_CHARS) {
+    context = context.slice(0, MAX_INJECTION_CHARS) + `
+[...truncated]`;
+  }
+  state.injectedTopics.push(currentTopic);
+  state.lastInjectionAt = Date.now();
+  saveState(sessionId, state);
+  log9.info("proactive injection triggered", { sessionId, topic: currentTopic, results: results.length });
+  return { shouldInject: true, additionalContext: context };
+}
+function cleanupProactiveState(sessionId) {
+  const path = statePath(sessionId);
+  try {
+    if (existsSync5(path)) {
+      const { unlinkSync } = __require("fs");
+      unlinkSync(path);
+    }
+  } catch {}
+}
+function detectTopic(recentFiles) {
+  if (recentFiles.length < 3)
+    return null;
+  const dirs = recentFiles.map((f) => f.split("/").slice(0, -1).join("/")).filter(Boolean);
+  const dirCounts = new Map;
+  for (const d of dirs) {
+    const parts = d.split("/").filter(Boolean);
+    const leaf = parts[parts.length - 1];
+    if (leaf && leaf !== "src" && leaf !== "lib" && leaf !== "utils") {
+      dirCounts.set(leaf, (dirCounts.get(leaf) ?? 0) + 1);
+    }
+  }
+  let bestTopic = null;
+  let bestCount = 0;
+  for (const [topic, count] of dirCounts) {
+    if (count > bestCount) {
+      bestTopic = topic;
+      bestCount = count;
+    }
+  }
+  const fileNames = recentFiles.map((f) => f.split("/").pop() ?? "").filter(Boolean);
+  const keywords = ["auth", "payment", "user", "api", "database", "config", "test", "migration", "deploy", "search"];
+  for (const kw of keywords) {
+    const matches = fileNames.filter((f) => f.toLowerCase().includes(kw));
+    if (matches.length >= 2)
+      return kw;
+  }
+  return bestTopic;
+}
+function statePath(sessionId) {
+  return join5(PROACTIVE_DIR, `${sessionId.replace(/[^a-zA-Z0-9_-]/g, "_")}.json`);
+}
+function loadState(sessionId) {
+  const path = statePath(sessionId);
+  try {
+    if (existsSync5(path)) {
+      return JSON.parse(readFileSync3(path, "utf-8"));
+    }
+  } catch {}
+  return { toolCallCount: 0, lastInjectionAt: 0, injectedTopics: [], recentFiles: [] };
+}
+function saveState(sessionId, state) {
+  try {
+    if (!existsSync5(PROACTIVE_DIR)) {
+      mkdirSync3(PROACTIVE_DIR, { recursive: true, mode: 448 });
+    }
+    writeFileSync(statePath(sessionId), JSON.stringify(state), "utf-8");
+  } catch {}
+}
+function extractFilePath(toolName, toolInput) {
+  if (toolName === "Read" || toolName === "Write" || toolName === "Edit" || toolName === "MultiEdit") {
+    const fp = toolInput.file_path;
+    return typeof fp === "string" ? fp : undefined;
+  }
+  return;
+}
+function safeJson4(text, fallback) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return fallback;
+  }
+}
+
+// src/capture/batch-queue.ts
+import { existsSync as existsSync6, mkdirSync as mkdirSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync2, appendFileSync as appendFileSync2, unlinkSync, statSync as statSync2 } from "fs";
+import { join as join6 } from "path";
+import { homedir as homedir5 } from "os";
+var log10 = createLogger("batch-queue");
+var DATA_DIR2 = join6(homedir5(), ".claude-memory-hub");
+var BATCH_DIR = join6(DATA_DIR2, "batch");
+var QUEUE_PATH = join6(BATCH_DIR, "queue.jsonl");
+var LOCK_PATH = join6(BATCH_DIR, "queue.lock");
+var MAX_QUEUE_SIZE = 100 * 1024;
+var LOCK_STALE_MS = 30000;
+function enqueueEvent(event) {
+  try {
+    ensureBatchDir();
+    const line = JSON.stringify(event) + `
+`;
+    appendFileSync2(QUEUE_PATH, line, "utf-8");
+  } catch (err) {
+    log10.error("enqueue failed", { error: String(err) });
+    throw err;
+  }
+}
+function tryFlush() {
+  try {
+    if (!existsSync6(QUEUE_PATH))
+      return false;
+    const stat = statSync2(QUEUE_PATH);
+    if (stat.size === 0)
+      return false;
+    if (!tryAcquireLock())
+      return false;
+    try {
+      flushQueue();
+      return true;
+    } finally {
+      releaseLock();
+    }
+  } catch (err) {
+    log10.error("flush failed", { error: String(err) });
+    return false;
+  }
+}
+function flushQueue() {
+  const content = readFileSync4(QUEUE_PATH, "utf-8").trim();
+  if (!content)
+    return;
+  const events = [];
+  for (const line of content.split(`
+`)) {
+    try {
+      events.push(JSON.parse(line));
+    } catch {
+      log10.warn("skipping malformed queue line");
+    }
+  }
+  if (events.length === 0)
+    return;
+  const store = new SessionStore;
+  const tracker = new ResourceTracker;
+  const registry = getResourceRegistry();
+  const db = store["db"];
+  db.transaction(() => {
+    for (const event of events) {
+      store.upsertSession({
+        id: event.session.id,
+        project: event.session.project,
+        started_at: event.session.started_at,
+        status: "active"
+      });
+      for (const entity of event.entities) {
+        store.insertEntity({ ...entity, project: event.session.project });
+      }
+      if (event.resources) {
+        for (const r of event.resources) {
+          const resource = registry.resolve(r.type, r.name);
+          tracker.trackUsage(event.session.id, event.session.project, r.type, r.name, r.tokenCost ?? resource?.full_tokens ?? 0);
+        }
+      }
+    }
+  })();
+  writeFileSync2(QUEUE_PATH, "", "utf-8");
+  log10.info("batch flushed", { events: events.length });
+}
+function tryAcquireLock() {
+  try {
+    if (existsSync6(LOCK_PATH)) {
+      const lockContent = readFileSync4(LOCK_PATH, "utf-8").trim();
+      const [pidStr, timestampStr] = lockContent.split(":");
+      const lockTime = Number(timestampStr);
+      if (Date.now() - lockTime < LOCK_STALE_MS) {
+        const pid = Number(pidStr);
+        try {
+          process.kill(pid, 0);
+          return false;
+        } catch {}
+      }
+    }
+    writeFileSync2(LOCK_PATH, `${process.pid}:${Date.now()}`, "utf-8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+function releaseLock() {
+  try {
+    unlinkSync(LOCK_PATH);
+  } catch {}
+}
+function ensureBatchDir() {
+  if (!existsSync6(BATCH_DIR)) {
+    mkdirSync4(BATCH_DIR, { recursive: true, mode: 448 });
+  }
+}
+function isBatchEnabled() {
+  const mode = process.env["CLAUDE_MEMORY_HUB_BATCH"] ?? "auto";
+  return mode !== "disabled";
+}
+
 // src/hooks-entry/session-end.ts
 async function main() {
   if (process.env["CLAUDE_MEMORY_HUB_SKIP_HOOKS"] === "1")
@@ -2036,6 +2280,10 @@ async function main() {
   }
   const project = projectFromCwd(hook.cwd ?? process.env["CLAUDE_CWD"] ?? process.cwd());
   await handleSessionEnd(hook, project);
+  try {
+    tryFlush();
+  } catch {}
+  cleanupProactiveState(hook.session_id);
   const store = new SessionStore;
   if (store.getSession(hook.session_id)) {
     await new SessionSummarizer().summarize(hook.session_id, project).catch(() => {});

package/dist/index.js

@@ -15593,8 +15593,17 @@ function sanitizeFtsQuery2(query) {
 }
 
 // src/mcp/tool-handlers.ts
+function truncateToTokenBudget(text, maxTokens) {
+  if (!maxTokens || maxTokens <= 0)
+    return text;
+  const maxChars = maxTokens * 4;
+  if (text.length <= maxChars)
+    return text;
+  return text.slice(0, maxChars) + `
+[...truncated to fit ~` + maxTokens + " token budget]";
+}
 async function handleMemoryRecall(args) {
-  const { query, limit = 5 } = args;
+  const { query, limit = 5, max_tokens } = args;
   if (!query?.trim())
     return "No query provided.";
   const builder = new ContextBuilder;
@@ -15604,9 +15613,10 @@ async function handleMemoryRecall(args) {
 
 This appears to be a new topic with no prior history.`;
   }
-  return `Found ${ctx.resultCount} relevant memory(ies) (~${ctx.tokenEstimate} tokens):
+  const output = `Found ${ctx.resultCount} relevant memory(ies) (~${ctx.tokenEstimate} tokens):
 
 ${ctx.text}`;
+  return truncateToTokenBudget(output, max_tokens);
 }
 async function handleMemoryEntities(args) {
   const { file_path } = args;
@@ -15648,11 +15658,11 @@ async function handleMemoryStore(args) {
   return `Note saved to session ${session_id}.`;
 }
 async function handleMemorySearch(args) {
-  const { query, limit = 20, offset = 0, project } = args;
+  const { query, limit = 20, offset = 0, project, max_tokens } = args;
   if (!query?.trim())
     return "No query provided.";
   const results = await searchIndex(query, { limit: Math.min(limit, 50), offset, ...project ? { project } : {} });
-  return formatSearchIndex(results);
+  return truncateToTokenBudget(formatSearchIndex(results), max_tokens);
 }
 async function handleMemoryTimeline(args) {
   const { id, type, depth = 3 } = args;
@@ -15662,11 +15672,11 @@ async function handleMemoryTimeline(args) {
   return formatTimeline(entries);
 }
 async function handleMemoryFetch(args) {
-  const { ids } = args;
+  const { ids, max_tokens } = args;
   if (!ids?.length)
     return "No IDs provided.";
   const records = fetchFullRecords(ids.slice(0, 20));
-  return formatFullRecords(records);
+  return truncateToTokenBudget(formatFullRecords(records), max_tokens);
 }
 async function handleMemoryHealth() {
   const report = runHealthCheck();
@@ -15741,7 +15751,8 @@ var TOOL_DEFINITIONS = [
       type: "object",
       properties: {
         query: { type: "string", description: "Natural language search query" },
-        limit: { type: "number", description: "Max results (default 5, max 10)" }
+        limit: { type: "number", description: "Max results (default 5, max 10)" },
+        max_tokens: { type: "number", description: "Max output tokens. Results truncated to fit budget. Default: unlimited" }
       },
       required: ["query"]
     }
@@ -15800,7 +15811,8 @@ var TOOL_DEFINITIONS = [
         query: { type: "string", description: "Search query" },
         limit: { type: "number", description: "Max results (default 20)" },
         offset: { type: "number", description: "Pagination offset (default 0)" },
-        project: { type: "string", description: "Filter by project" }
+        project: { type: "string", description: "Filter by project" },
+        max_tokens: { type: "number", description: "Max output tokens. Results truncated to fit budget" }
       },
       required: ["query"]
     }
@@ -15835,7 +15847,8 @@ var TOOL_DEFINITIONS = [
             required: ["id", "type"]
           },
           description: "Array of {id, type} from search results"
-        }
+        },
+        max_tokens: { type: "number", description: "Max output tokens. Records truncated to fit budget" }
       },
       required: ["ids"]
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-memory-hub",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Persistent memory system for Claude Code. Zero API key. Zero Python. 5 hooks + MCP server + SQLite FTS5 + semantic search.",
   "type": "module",
   "main": "dist/index.js",