Release v3.9.9

Published from npm package build Source: https://github.com/thedotmack/claude-mem-source
2025-10-03 18:20:47 -04:00
parent 4d5b307a74
commit 85ed7c3d2f
85 changed files with 11156 additions and 7458 deletions
@@ -1,86 +1,248 @@
 # 🧠 Claude Memory System (claude-mem)

-## Remember that one thing? Neither do we… but `claude-mem` does! 😵‍💫
+A real-time memory system for Claude Code that captures, compresses, and retrieves conversation context across sessions using semantic search and vector embeddings.

-Stop repeating yourself. `claude-mem` remembers what you and Claude Code figure out, so every new chat starts smarter than the last.
-
-## ⚡️ 10‑Second Setup
-
-```bash
-npm install -g claude-mem && claude-mem install
-```
-
-That’s it. Restart Claude Code and you’re good. No config. No tedious setup or dependencies.
-
-## ✨ What You Get
-
- Remembers key insights from your chats with Claude Code
- Starts new sessions with the right context
- Works quietly in the background
- One-command install and status check
-
-## 🗑️ Smart Trash™ (Your Panic Button)
-
-Delete something by accident? It’s not gone.
- Everything goes to `~/.claude-mem/trash/`
- Restore with a single command: `claude-mem restore`
- Timestamped so you can see when things moved
-
-## 🎯 Why It’s Useful
-
- No more re-explaining your project over and over
- Pick up exactly where you left off
- Find past solutions fast when you face a familiar bug
- Your knowledge compounds the more you use it
-
-## 🧭 Minimal Commands You’ll Ever Need
-
-```bash
-claude-mem install          # Set up/repair integration
-claude-mem status           # Check everything’s working
-claude-mem load-context     # Peek at what it remembers
-claude-mem logs             # If you’re curious
-claude-mem uninstall        # Remove hooks
-
-# Extras
-claude-mem trash-view       # See what’s in Smart Trash™
-claude-mem restore          # Restore deleted items
-```
-
-## 📁 Where Stuff Lives (super simple)
-
-```
-~/.claude-mem/
-├── index/      # memory index
-├── archives/   # transcripts
-├── hooks/      # integration bits
-├── trash/      # Smart Trash™
-└── logs/       # diagnostics
-```
-
-## ✅ Requirements
-
- Node.js 18+
- Claude Code
-
-## 🆘 If Something’s Weird
-
-```bash
-claude-mem status           # quick health check
-claude-mem install --force  # fixes most issues
-```
-
-## 📄 License
-
-Licensed under AGPL-3.0. See `LICENSE`.
-
---
-
-## Ready to remember more and repeat less?
+## ⚡️ Quick Start

 ```bash
 npm install -g claude-mem
 claude-mem install
 ```

-Your future self will thank you. 🧠✨
+Restart Claude Code. Memory capture starts automatically.
+
+## ✨ What It Does
+
+**Real-Time Memory Capture**
+- Captures every conversation turn as it happens via streaming hooks
+- User prompts stored immediately in ChromaDB with atomic facts
+- Tool responses compressed asynchronously via Agent SDK
+- Project-based memory isolation with hierarchical metadata
+- Automatic context loading at session start and `/clear`
+
+**Semantic Search**
+- Vector embeddings for intelligent retrieval via ChromaDB
+- Find relevant context from past conversations
+- Project-aware memory queries with temporal filtering
+- Date-based search using query text (not metadata)
+- 15+ MCP tools for memory operations
+
+**Invisible Operation**
+- Zero user configuration required
+- Memory compression happens in background via SDK
+- SDK transcripts auto-deleted from UI history
+- Session overviews generated automatically
+- Live memory viewer with SSE streaming
+
+**Smart Trash™**
+- Safe deletion with easy recovery
+- Timestamped trash entries
+- One-command restore
+- Located at `~/.claude-mem/trash/`
+
+## 🎯 Core Features
+
+- **Streaming Hooks**: Real-time capture with minimal overhead (<50ms)
+- **Agent SDK Integration**: Async compression without blocking conversation
+- **MCP Server**: 15+ ChromaDB tools for memory operations
+- **Project Isolation**: Memories segregated by project context
+- **Zero Configuration**: Works out of the box after install
+- **Embedded Databases**: ChromaDB and SQLite, no external dependencies
+- **Invisible UX**: Memory operations don't pollute conversation UI
+- **Live Memory Viewer**: Real-time slideshow of memories via SSE
+
+## 🧭 Commands
+
+```bash
+# Setup & Status
+claude-mem install          # Install/repair hooks and MCP integration
+claude-mem status           # Check installation and memory stats
+claude-mem doctor           # Run environment and pipeline diagnostics
+claude-mem uninstall        # Remove all hooks
+
+# Memory Operations
+claude-mem load-context     # View current session context
+claude-mem logs             # View operation logs
+claude-mem changelog        # Generate CHANGELOG.md from memories
+
+# Storage Operations (Used by hooks/SDK)
+claude-mem store-memory     # Store a memory to ChromaDB + SQLite
+claude-mem store-overview   # Store a session overview
+
+# Smart Trash™
+claude-mem trash            # View trash contents
+claude-mem restore          # Restore from trash
+claude-mem trash-empty      # Permanently delete trash
+
+# ChromaDB Tools (15+ MCP tools available)
+claude-mem chroma_*         # Direct ChromaDB operations
+```
+
+## 📁 Storage Structure
+
+```
+~/.claude-mem/
+├── chroma/            # ChromaDB vector database
+├── archives/          # Compressed transcript backups
+├── index/             # Legacy JSONL memory indices
+├── hooks/             # Hook configuration files
+├── trash/             # Smart Trash™ with recovery
+├── logs/              # Operation logs
+└── claude-mem.db      # SQLite metadata database
+```
+
+## 🏗️ Architecture
+
+**Storage Layers**
+- **ChromaDB**: Vector database for semantic search with embeddings
+- **SQLite**: Metadata index (`~/.claude-mem/claude-mem.db`) with sessions, memories, overviews
+- **Archives**: Compressed transcript backups in `~/.claude-mem/archives/`
+
+**Hook System** (`hook-templates/`)
+- `user-prompt-submit.js`: Captures user prompts immediately, stores in ChromaDB
+- `post-tool-use.js`: Spawns Agent SDK for async compression of tool responses
+- `stop.js`: Generates session overview, cleans up SDK transcripts from UI
+- `session-start.js`: Loads relevant context on startup and `/clear`
+- Shared utilities: `hook-helpers.js`, `hook-prompt-renderer.js`, `config-loader.js`, `path-resolver.js`
+
+**CLI Commands** (`src/commands/`)
+- Installation, status, and diagnostics
+- Memory storage and retrieval
+- Changelog generation from memories
+- Smart Trash™ management
+- 15+ dynamic ChromaDB MCP tool wrappers
+
+**Services** (`src/services/`)
+- SQLite stores: Session, Memory, Overview, Diagnostics, TranscriptEvent
+- Path discovery for project detection
+- Rolling settings and logs
+
+## 🔍 How Memory Search Works
+
+**Semantic Search Best Practices**:
+```typescript
+// ALWAYS include project name to avoid cross-contamination
+mcp__claude-mem__chroma_query_documents({
+  collection_name: "claude_memories",
+  query_texts: ["claude-mem authentication bug"],
+  n_results: 10
+})
+
+// Include dates for temporal search (dates in query text, not metadata)
+mcp__claude-mem__chroma_query_documents({
+  collection_name: "claude_memories",
+  query_texts: ["project-name 2025-10-02 feature implementation"],
+  n_results: 5
+})
+
+// Intent-based queries work better than keyword matching
+mcp__claude-mem__chroma_query_documents({
+  collection_name: "claude_memories",
+  query_texts: ["implementing oauth flow"],
+  n_results: 10
+})
+```
+
+**What Doesn't Work** (Avoid These!)
+- ❌ Complex `where` filters with `$and`/`$or` - causes errors
+- ❌ Timestamp comparisons (`$gte`, `$lt`) - stored as strings
+- ❌ Mixing project filters in where clause - causes "Error finding id"
+
+**Storage Collection**: `claude_memories`
+- Metadata: `project`, `session_id`, `date`, `type`, `concepts`, `files`
+- Embeddings: Semantic vectors for similarity search
+- Documents: Atomic facts + full narrative with hierarchical structure
+
+## ✅ Requirements
+
+- Node.js >= 18.0.0
+- Bun >= 1.0.0 (for development)
+- Claude Code with MCP support
+- macOS/Linux (POSIX-compliant)
+
+## 🛠️ Development
+
+```bash
+# Development mode
+bun run dev
+
+# Build production bundle
+bun run build
+
+# Build and update hooks (RECOMMENDED for hook changes)
+bun run build && bun link && claude-mem install --force
+
+# Run tests
+bun test                    # All tests
+npm run test:integration    # Integration tests
+bun run test:unit           # Unit tests only
+
+# Install from source
+bun run dev:install
+
+# Live Memory Viewer
+npm run memory-stream:server  # Start SSE server on :3001
+
+# Code quality
+bun run lint
+bun run format
+```
+
+## 🎨 Live Memory Viewer
+
+Real-time slideshow of memories with SSE streaming:
+
+1. Start the server: `npm run memory-stream:server`
+2. Open the viewer at `src/ui/memory-stream/`
+3. Auto-connects to `~/.claude-mem/claude-mem.db`
+4. New memories appear instantly as they're created
+
+Features:
+- 📡 Live SSE streaming from SQLite WAL changes
+- 🎬 Auto-slideshow (5s intervals)
+- ⏸️ Pause/Resume with Space bar
+- ⌨️ Keyboard navigation (←/→)
+- 🎨 Cyberpunk neural network aesthetic
+
+## 🔑 Key Design Decisions
+
+**Storage Architecture**
+- Direct ChromaDB writes in `store-memory.ts` command (no async syncing)
+- Each atomic fact stored as separate document + full narrative document
+- Hierarchical metadata: project, session, date, type, concepts, files
+- SQLite for fast metadata queries, ChromaDB for semantic search
+
+**Hook Infrastructure**
+- Streaming hooks (<50ms overhead) capture real-time events
+- Shared utilities in `hook-templates/shared/` for consistency
+- Force overwrite on install to ensure latest hook code deploys
+- Milliseconds in `config.json`, seconds in Claude settings
+
+**Memory Compression**
+- Agent SDK spawned asynchronously for tool response compression
+- User prompts stored immediately without blocking
+- SDK transcripts auto-deleted to keep UI clean
+- 100:1 compression ratio maintained
+
+**Search Strategy**
+- Semantic search via query text (dates embedded in queries)
+- Avoid complex metadata filters (causes ChromaDB errors)
+- Always include project name in queries for isolation
+- Multiple query phrasings for better coverage
+
+## 🆘 Troubleshooting
+
+```bash
+claude-mem status           # Check installation health
+claude-mem doctor           # Run full diagnostics
+claude-mem install --force  # Repair installation
+claude-mem logs             # View recent operations
+```
+
+## 📄 License
+
+AGPL-3.0 - See LICENSE file for details
+
+---
+
+**Remember more. Repeat less.** 🧠✨