claude-memory-hub 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,98 @@ Format follows [Keep a Changelog](https://keepachangelog.com/).
 
 ---
 
+## [0.6.0] - 2026-04-01
+
+Major release: semantic search, resource intelligence, observation capture, CLAUDE.md tracking, LLM summarization.
+
+### Phase 1 — ResourceRegistry + Entity Coverage
+
+- **ResourceRegistry** — unified scanner for ALL `.claude` locations: skills (58), agents (36), commands (65), workflows (10), CLAUDE.md. Parses agent frontmatter `name:` for correct resolution (e.g., `ios-developer` → `~/.claude/agent_mobile/ios/AGENT.md`). 3-level token estimation: listing (~50-200), full (200-8000), total (all files on disk)
+- **OverheadReport** — `memory_context_budget` MCP tool now shows: fixed token overhead breakdown, unused skill/agent detection, potential savings recommendations
+- **InjectionValidator** — sanitizes context before `UserPromptSubmit` injection. Strips HTML comments, caps at 4500 chars, filters dead resource recommendations via `filterAliveRecommendations()`
+- **Agent/Skill entities** — `Agent` and `Skill` tool calls now produce `entity_type="decision"` entities (importance 3/2), visible in summarization and compact scoring
+- **Expanded resource types** — `resource_usage` table tracks 8 types: skill, agent, command, workflow, claude_md, memory, mcp_tool, hook (was 5)
+- **Real token costs** — `SmartResourceLoader` uses ResourceRegistry for actual file-size-based estimates instead of hardcoded 500 fallback
+
+### Phase 2 — Schema v3 + Observations + CLAUDE.md Tracking
+
+- **Schema migration v3** — entities table rebuilt with `observation` type in CHECK constraint + new `claude_md_registry` table
+- **Observation extractor** — heuristic-based free-form capture from tool output and user prompts. Keywords: IMPORTANT/CRITICAL (importance 4), decision:/NOTE: (3), TODO:/FIXME: (2). Max 1 observation per tool call, capped at 300 chars
+- **CLAUDE.md tracker** — walks from `cwd` to root, finds all CLAUDE.md files, extracts `## sections` + 200-char previews, content-hash change detection (only re-parses on change), injects rule summary into context
+- **Session summarizer** includes top 5 observations in L3 summaries
+- **Vector search** reindexes observation entities alongside decisions and errors
+
+### Phase 3 — LLM Summarization Pipeline
+
+- **3-tier fallback** — Tier 1: PostCompact summary (free, already existed). Tier 2: `claude -p ... --print` subprocess with 30s timeout. Tier 3: Rule-based (always available)
+- **Hook recursion guard** — `CLAUDE_MEMORY_HUB_SKIP_HOOKS=1` env var set on CLI subprocess, checked by all 5 hook entry scripts. Prevents infinite loop when CLI summarizer triggers hooks
+- **Configurable** — `CLAUDE_MEMORY_HUB_LLM=auto|cli-only|rule-based` env var. `CLAUDE_MEMORY_HUB_LLM_TIMEOUT_MS` for custom timeout
+
+### Phase 4 — Semantic Search
+
+- **Embedding model** — `@huggingface/transformers` with `all-MiniLM-L6-v2` (384-dim, 90MB cached, 9ms warm inference). Lazy-loaded: only imports when first embedding requested. Graceful degradation if package not installed
+- **Pure JS cosine similarity** — no native sqlite-vec binary needed. Fast enough for <1000 docs. Embeddings stored as BLOBs in new `embeddings` table (schema v4)
+- **Hybrid search** — `searchIndex()` now merges FTS5 BM25 + TF-IDF + semantic cosine similarity. Deduplicates by id+type, keeps highest score
+- **Auto-indexing** — session-end hook generates embedding for new summaries automatically
+- **Opt-in** — `CLAUDE_MEMORY_HUB_EMBEDDINGS=auto|disabled` env var. `@huggingface/transformers` is `optionalDependencies` — install failure doesn't break anything
+
+### New Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAUDE_MEMORY_HUB_LLM` | `auto` | Summarization mode: auto, cli-only, rule-based |
+| `CLAUDE_MEMORY_HUB_LLM_TIMEOUT_MS` | `30000` | CLI summarizer timeout in ms |
+| `CLAUDE_MEMORY_HUB_EMBEDDINGS` | `auto` | Embedding mode: auto, disabled |
+| `CLAUDE_MEMORY_HUB_SKIP_HOOKS` | — | Set to `1` to suppress hooks (internal use) |
+
+### New/Modified Files
+
+```
+NEW:
+  src/context/resource-registry.ts      — unified resource scanner
+  src/context/injection-validator.ts    — context sanitization
+  src/capture/observation-extractor.ts  — free-form observation capture
+  src/context/claude-md-tracker.ts      — CLAUDE.md scanning + tracking
+  src/summarizer/cli-summarizer.ts      — Tier 2 CLI summarization
+  src/search/embedding-model.ts         — lazy @huggingface/transformers
+  src/search/semantic-search.ts         — cosine similarity search
+
+MODIFIED:
+  src/db/schema.ts                      — migrations v3 + v4
+  src/types/index.ts                    — EntityType += observation
+  src/capture/entity-extractor.ts       — Agent/Skill + observation extraction
+  src/capture/hook-handler.ts           — registry + validator + CLAUDE.md + observations
+  src/context/smart-resource-loader.ts  — uses ResourceRegistry
+  src/context/resource-tracker.ts       — 8 resource types
+  src/mcp/tool-handlers.ts             — overhead report in context_budget
+  src/summarizer/session-summarizer.ts  — 3-tier pipeline
+  src/search/search-workflow.ts         — hybrid FTS5+TF-IDF+semantic
+  src/search/vector-search.ts           — reindex includes observations+embeddings
+  src/db/session-store.ts               — getSessionObservations()
+  src/hooks-entry/*.ts                  — SKIP_HOOKS recursion guard
+```
+
+### Dependencies
+
+```
+KEPT:     @modelcontextprotocol/sdk
+ADDED:    @huggingface/transformers (optional — semantic search)
+```
+
+---
+
+## [0.5.2] - 2026-04-01
+
+### Fixed
+- **Viewer JS broken after bundle** — inline `onclick` handlers lost reference when Bun bundled template literal into `cli.js`. Rewrote all JS to IIFE + `addEventListener` pattern
+- **Escaped quotes in template literal** — `this.classList.toggle('expanded')` caused `SyntaxError: Unexpected identifier` after bundle. Switched to double quotes and event delegation
+- **push-private.sh deletes source** — `git checkout main` removed untracked `src/` directory. Added backup/restore of source dirs around branch switch
+
+### Changed
+- **push-public.sh** — fixed version extraction in commit message (`node -p` with proper quoting)
+
+---
+
 ## [0.5.1] - 2026-04-01
 
 ### Fixed

package/README.md

@@ -45,8 +45,13 @@ Search:        Keyword-only, no semantic ranking
 | Influence what compact preserves | -- | -- | **Yes** |
 | Save compact output | -- | -- | **Yes** |
 | Token budget optimization | -- | -- | **Yes** |
-| Hybrid search (FTS5 + TF-IDF) | -- | Partial | **Yes** |
+| Semantic search (embeddings) | -- | Chroma (external) | **Yes (offline)** |
+| 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** |
+| LLM summarization (3-tier) | -- | Yes (API) | **Yes (free)** |
 | Browser UI | -- | Yes | **Yes** |
 | Health monitoring | -- | -- | **Yes** |
 | Migrate from claude-mem | N/A | N/A | **Yes** |
@@ -127,7 +132,7 @@ Session N+1     → UserPromptSubmit hook fires
 
 memory-hub tracks which skills/agents/tools you **actually use**, then recommends only those for future sessions. Rare resources load on demand via SkillTool.
 
-### Layer 5 — 3-Layer Progressive Search (new in v0.5)
+### Layer 5 — 3-Layer Progressive Search + Semantic (new in v0.5/v0.6)
 
 ```
 Traditional search: query → ALL full records → 5000+ tokens wasted
@@ -140,7 +145,35 @@ memory-hub search:  query → Layer 1 (index)    → ~50 tokens/result
                     Token savings: ~80-90% vs. full context
 ```
 
-Hybrid ranking: FTS5 BM25 for keyword matches + TF-IDF cosine similarity for semantic ranking. Zero external dependencies — pure TypeScript implementation.
+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.
+
+### Layer 6 — Resource Intelligence (new in v0.6)
+
+```
+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"
+```
+
+### Layer 7 — Observation Capture (new in v0.6)
+
+```
+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
+```
 
 ---
 
@@ -195,6 +228,9 @@ Hybrid ranking: FTS5 BM25 for keyword matches + TF-IDF cosine similarity for sem
                    │   resource_usage   │
                    │   fts_memories     │
                    │   tfidf_index      │
+                   │   embeddings       │
+                   │   claude_md_       │
+                   │    registry        │
                    │   health_checks    │
                    └────────────────────┘
 ```
@@ -235,6 +271,21 @@ One command. Registers MCP server + 5 hooks globally. Works on CLI, VS Code, Jet
 
 **Coming from claude-mem?** The installer auto-detects `~/.claude-mem/claude-mem.db` and migrates your data automatically. No manual steps needed.
 
+### Update
+
+```bash
+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
@@ -346,6 +397,7 @@ Migration is idempotent — safe to run multiple times with zero duplicates.
 | **v0.3.0** | Removed API key requirement, 1-command install |
 | **v0.4.0** | Smart resource loading, token budget optimization |
 | **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 |
 
 See [CHANGELOG.md](CHANGELOG.md) for full details.
 
@@ -354,13 +406,21 @@ See [CHANGELOG.md](CHANGELOG.md) for full details.
 ## Dependencies
 
 ```
-@modelcontextprotocol/sdk    MCP stdio server
-bun:sqlite                   Built-in, zero install
+@modelcontextprotocol/sdk          MCP stdio server (required)
+bun:sqlite                         Built-in, zero install
+@huggingface/transformers          Semantic search embeddings (optional)
 ```
 
-That's it. **One npm package.** The other is built into Bun.
+**Two npm packages + one optional.** No Python. No Chroma. No HTTP server. No API key. No Docker.
+
+### Environment Variables
 
-No Python. No Chroma. No HTTP server. No API key. No Docker.
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAUDE_MEMORY_HUB_LLM` | `auto` | Summarization: auto, cli-only, rule-based |
+| `CLAUDE_MEMORY_HUB_LLM_TIMEOUT_MS` | `30000` | CLI summarizer timeout |
+| `CLAUDE_MEMORY_HUB_EMBEDDINGS` | `auto` | Embeddings: auto, disabled |
+| `CMH_LOG_LEVEL` | `info` | Log level: debug, info, warn, error |
 
 ---