Release v3.9.13
Published from npm package build Source: https://github.com/thedotmack/claude-mem-source
This commit is contained in:
Alex Newman
@@ -1,248 +1,470 @@
|
|||||||
# 🧠 Claude Memory System (claude-mem)
|
<div align="center">
|
||||||
|
|
||||||
A real-time memory system for Claude Code that captures, compresses, and retrieves conversation context across sessions using semantic search and vector embeddings.
|
<img src="claude-mem-logo-lm.webp#gh-light-mode-only" alt="claude-mem logo" width="360" height="auto" />
|
||||||
|
<img src="claude-mem-logo-dm.webp#gh-dark-mode-only" alt="claude-mem logo" width="360" height="auto" />
|
||||||
|
|
||||||
## ⚡️ Quick Start
|
<p>
|
||||||
|
Memory compression and persistence system for Claude Code conversations
|
||||||
|
</p>
|
||||||
|
|
||||||
|
|
||||||
|
<!-- Badges -->
|
||||||
|
<p>
|
||||||
|
<a href="https://www.npmjs.com/package/claude-mem">
|
||||||
|
<img src="https://img.shields.io/npm/v/claude-mem.svg" alt="npm version" />
|
||||||
|
</a>
|
||||||
|
<a href="https://github.com/thedotmack/claude-mem/graphs/contributors">
|
||||||
|
<img src="https://img.shields.io/github/contributors/thedotmack/claude-mem" alt="contributors" />
|
||||||
|
</a>
|
||||||
|
<a href="">
|
||||||
|
<img src="https://img.shields.io/github/last-commit/thedotmack/claude-mem" alt="last update" />
|
||||||
|
</a>
|
||||||
|
<a href="https://github.com/thedotmack/claude-mem/network/members">
|
||||||
|
<img src="https://img.shields.io/github/forks/thedotmack/claude-mem" alt="forks" />
|
||||||
|
</a>
|
||||||
|
<a href="https://github.com/thedotmack/claude-mem/stargazers">
|
||||||
|
<img src="https://img.shields.io/github/stars/thedotmack/claude-mem" alt="stars" />
|
||||||
|
</a>
|
||||||
|
<a href="https://github.com/thedotmack/claude-mem/issues/">
|
||||||
|
<img src="https://img.shields.io/github/issues/thedotmack/claude-mem" alt="open issues" />
|
||||||
|
</a>
|
||||||
|
<a href="https://github.com/thedotmack/claude-mem/blob/main/LICENSE">
|
||||||
|
<img src="https://img.shields.io/badge/license-AGPL--3.0-blue.svg" alt="license" />
|
||||||
|
</a>
|
||||||
|
<a href="https://nodejs.org/">
|
||||||
|
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="node version" />
|
||||||
|
</a>
|
||||||
|
<a href="https://modelcontextprotocol.io">
|
||||||
|
<img src="https://img.shields.io/badge/MCP-compatible-purple.svg" alt="MCP compatible" />
|
||||||
|
</a>
|
||||||
|
<a href="https://claude.com/claude-code">
|
||||||
|
<img src="https://img.shields.io/badge/Claude%20Code-enabled-orange.svg" alt="Claude Code enabled" />
|
||||||
|
</a>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<h4>
|
||||||
|
<a href="https://github.com/thedotmack/claude-mem">Documentation</a>
|
||||||
|
<span> · </span>
|
||||||
|
<a href="https://github.com/thedotmack/claude-mem/issues/">Report Bug</a>
|
||||||
|
<span> · </span>
|
||||||
|
<a href="https://github.com/thedotmack/claude-mem/issues/">Request Feature</a>
|
||||||
|
</h4>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<br />
|
||||||
|
|
||||||
|
<!-- Table of Contents -->
|
||||||
|
# :notebook_with_decorative_cover: Table of Contents
|
||||||
|
|
||||||
|
- [About the Project](#star2-about-the-project)
|
||||||
|
* [Tech Stack](#space_invader-tech-stack)
|
||||||
|
* [Features](#dart-features)
|
||||||
|
- [Getting Started](#toolbox-getting-started)
|
||||||
|
* [Prerequisites](#bangbang-prerequisites)
|
||||||
|
* [Installation](#gear-installation)
|
||||||
|
* [Running Tests](#test_tube-running-tests)
|
||||||
|
- [Usage](#eyes-usage)
|
||||||
|
* [Basic Commands](#basic-commands)
|
||||||
|
* [Hook System](#hook-system)
|
||||||
|
* [Memory Operations](#memory-operations)
|
||||||
|
* [ChromaDB MCP Tools](#chromadb-mcp-tools)
|
||||||
|
* [Advanced Usage](#advanced-usage)
|
||||||
|
- [Architecture](#building_construction-architecture)
|
||||||
|
- [Configuration](#wrench-configuration)
|
||||||
|
- [Roadmap](#compass-roadmap)
|
||||||
|
- [Contributing](#wave-contributing)
|
||||||
|
- [License](#warning-license)
|
||||||
|
- [Contact](#handshake-contact)
|
||||||
|
- [Acknowledgements](#gem-acknowledgements)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
<!-- About the Project -->
|
||||||
|
## :star2: About the Project
|
||||||
|
|
||||||
|
claude-mem automatically captures, compresses, and retrieves context across Claude Code sessions, enabling true long-term memory through semantic search and intelligent compression.
|
||||||
|
|
||||||
|
Perfect for developers who want their AI assistant to remember project context, past decisions, and conversation history across sessions without manual context management.
|
||||||
|
|
||||||
|
<!-- TechStack -->
|
||||||
|
### :space_invader: Tech Stack
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>Core Technologies</summary>
|
||||||
|
<ul>
|
||||||
|
<li><a href="https://www.typescriptlang.org/">TypeScript</a></li>
|
||||||
|
<li><a href="https://nodejs.org/">Node.js</a></li>
|
||||||
|
<li><a href="https://bun.sh/">Bun</a></li>
|
||||||
|
</ul>
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>Storage & Memory</summary>
|
||||||
|
<ul>
|
||||||
|
<li><a href="https://www.trychroma.com/">ChromaDB</a> - Vector database for semantic search</li>
|
||||||
|
<li><a href="https://www.sqlite.org/">SQLite</a> - Metadata and session tracking</li>
|
||||||
|
<li><a href="https://github.com/WiseLibs/better-sqlite3">better-sqlite3</a> - Fast SQLite bindings</li>
|
||||||
|
</ul>
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>AI & Integration</summary>
|
||||||
|
<ul>
|
||||||
|
<li><a href="https://github.com/anthropics/anthropic-sdk-typescript">Anthropic Agent SDK</a> - Async compression</li>
|
||||||
|
<li><a href="https://modelcontextprotocol.io">Model Context Protocol (MCP)</a> - Tool integration</li>
|
||||||
|
<li><a href="https://claude.com/claude-code">Claude Code</a> - Streaming hooks</li>
|
||||||
|
</ul>
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<!-- Features -->
|
||||||
|
### :dart: Features
|
||||||
|
|
||||||
|
- :brain: **Automatic Memory Compression** - Real-time conversation capture and intelligent summarization
|
||||||
|
- :mag: **Semantic Search** - ChromaDB-powered vector search for intelligent context retrieval
|
||||||
|
- :package: **Project Isolation** - Memories segregated by project with multi-project support
|
||||||
|
- :arrows_counterclockwise: **Session Persistence** - Context loads automatically at session start and `/clear` command
|
||||||
|
- :dart: **MCP Integration** - 15+ ChromaDB tools via Model Context Protocol
|
||||||
|
- :floppy_disk: **SQLite Storage** - Fast metadata and session tracking with embedded database
|
||||||
|
- :wastebasket: **Smart Trash** - Safe file deletion with recovery capabilities
|
||||||
|
- :zap: **Streaming Hooks** - Sub-50ms overhead for real-time event capture
|
||||||
|
- :robot: **Agent SDK Compression** - Async transcript processing without blocking conversations
|
||||||
|
- :bar_chart: **Session Overviews** - Automatic session summaries with temporal context
|
||||||
|
|
||||||
|
<!-- Getting Started -->
|
||||||
|
## :toolbox: Getting Started
|
||||||
|
|
||||||
|
<!-- Prerequisites -->
|
||||||
|
### :bangbang: Prerequisites
|
||||||
|
|
||||||
|
This project requires Node.js and works best with Claude Code
|
||||||
|
|
||||||
|
- Node.js >= 18.0.0
|
||||||
|
- Claude Code with MCP support
|
||||||
|
- macOS/Linux (POSIX-compliant system)
|
||||||
|
- Bun >= 1.0.0 (optional, for development)
|
||||||
|
|
||||||
|
<!-- Installation -->
|
||||||
|
### :gear: Installation
|
||||||
|
|
||||||
|
Install claude-mem globally via npm
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm install -g claude-mem
|
npm install -g claude-mem
|
||||||
claude-mem install
|
claude-mem install
|
||||||
```
|
```
|
||||||
|
|
||||||
Restart Claude Code. Memory capture starts automatically.
|
The interactive installer will guide you through three installation scopes:
|
||||||
|
|
||||||
## ✨ What It Does
|
- **User** - Install for current user (default, recommended)
|
||||||
|
- **Project** - Install for current project only
|
||||||
|
- **Local** - Install to custom directory
|
||||||
|
|
||||||
**Real-Time Memory Capture**
|
<!-- Running Tests -->
|
||||||
- Captures every conversation turn as it happens via streaming hooks
|
### :test_tube: Running Tests
|
||||||
- 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**
|
To run tests, use the following commands
|
||||||
- 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
|
```bash
|
||||||
# Setup & Status
|
# Run all tests
|
||||||
claude-mem install # Install/repair hooks and MCP integration
|
bun test
|
||||||
claude-mem status # Check installation and memory stats
|
|
||||||
claude-mem doctor # Run environment and pipeline diagnostics
|
|
||||||
claude-mem uninstall # Remove all hooks
|
|
||||||
|
|
||||||
# Memory Operations
|
# Run integration tests
|
||||||
claude-mem load-context # View current session context
|
npm run test:integration
|
||||||
claude-mem logs # View operation logs
|
|
||||||
claude-mem changelog # Generate CHANGELOG.md from memories
|
|
||||||
|
|
||||||
# Storage Operations (Used by hooks/SDK)
|
# Run with coverage
|
||||||
claude-mem store-memory # Store a memory to ChromaDB + SQLite
|
npm run test:coverage
|
||||||
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
|
<!-- Usage -->
|
||||||
|
## :eyes: Usage
|
||||||
|
|
||||||
|
### Basic Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Check installation status
|
||||||
|
claude-mem status
|
||||||
|
|
||||||
|
# View operation logs
|
||||||
|
claude-mem logs
|
||||||
|
|
||||||
|
# Load context for current project
|
||||||
|
claude-mem load-context --project my-project
|
||||||
|
|
||||||
|
# View compressed memories (interactive)
|
||||||
|
claude-mem restore
|
||||||
|
|
||||||
|
# Manage trash bin
|
||||||
|
claude-mem trash view
|
||||||
|
claude-mem restore
|
||||||
|
claude-mem trash empty
|
||||||
|
```
|
||||||
|
|
||||||
|
### Hook System
|
||||||
|
|
||||||
|
claude-mem integrates with Claude Code via streaming hooks that capture conversation events:
|
||||||
|
|
||||||
|
- **user-prompt-submit** - Captures user prompts in real-time
|
||||||
|
- **post-tool-use** - Spawns Agent SDK for async compression
|
||||||
|
- **stop-streaming** - Generates session overview and cleanup
|
||||||
|
- **session-start** - Loads relevant context automatically
|
||||||
|
|
||||||
|
Hooks are configured during installation with a 180-second timeout and run transparently in the background.
|
||||||
|
|
||||||
|
### Memory Operations
|
||||||
|
|
||||||
|
#### Manual Compression
|
||||||
|
|
||||||
|
```bash
|
||||||
|
claude-mem compress
|
||||||
|
```
|
||||||
|
|
||||||
|
Compress Claude Code transcripts into searchable memories with semantic embeddings.
|
||||||
|
|
||||||
|
#### Context Loading
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Load last 10 memories for current project
|
||||||
|
claude-mem load-context
|
||||||
|
|
||||||
|
# Load specific number of memories
|
||||||
|
claude-mem load-context --count 20
|
||||||
|
|
||||||
|
# Filter by project
|
||||||
|
claude-mem load-context --project my-app
|
||||||
|
|
||||||
|
# Output raw JSON
|
||||||
|
claude-mem load-context --raw
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Trash Management
|
||||||
|
|
||||||
|
claude-mem includes Smart Trash for safe file operations:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Move files to trash
|
||||||
|
claude-mem trash file.txt
|
||||||
|
claude-mem trash -r directory/
|
||||||
|
|
||||||
|
# View trash contents
|
||||||
|
claude-mem trash view
|
||||||
|
|
||||||
|
# Restore files interactively
|
||||||
|
claude-mem restore
|
||||||
|
|
||||||
|
# Empty trash permanently
|
||||||
|
claude-mem trash empty
|
||||||
|
```
|
||||||
|
|
||||||
|
### ChromaDB MCP Tools
|
||||||
|
|
||||||
|
claude-mem exposes 15+ ChromaDB operations via MCP:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# List collections
|
||||||
|
claude-mem chroma-list-collections
|
||||||
|
|
||||||
|
# Create collection
|
||||||
|
claude-mem chroma-create-collection --collection-name memories
|
||||||
|
|
||||||
|
# Query documents semantically
|
||||||
|
claude-mem chroma-query-documents \
|
||||||
|
--collection-name memories \
|
||||||
|
--query-texts '["authentication implementation"]' \
|
||||||
|
--n-results 5
|
||||||
|
|
||||||
|
# Add documents
|
||||||
|
claude-mem chroma-add-documents \
|
||||||
|
--collection-name memories \
|
||||||
|
--documents '["content here"]' \
|
||||||
|
--ids '["mem-001"]'
|
||||||
|
|
||||||
|
# Get documents by ID
|
||||||
|
claude-mem chroma-get-documents \
|
||||||
|
--collection-name memories \
|
||||||
|
--ids '["mem-001"]'
|
||||||
|
|
||||||
|
# Update documents
|
||||||
|
claude-mem chroma-update-documents \
|
||||||
|
--collection-name memories \
|
||||||
|
--ids '["mem-001"]' \
|
||||||
|
--documents '["updated content"]'
|
||||||
|
|
||||||
|
# Delete documents
|
||||||
|
claude-mem chroma-delete-documents \
|
||||||
|
--collection-name memories \
|
||||||
|
--ids '["mem-001"]'
|
||||||
|
```
|
||||||
|
|
||||||
|
See all available Chroma MCP commands with `claude-mem --help`.
|
||||||
|
|
||||||
|
### Advanced Usage
|
||||||
|
|
||||||
|
#### Session Title Generation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Generate title and subtitle from prompt
|
||||||
|
claude-mem generate-title "implemented authentication with OAuth"
|
||||||
|
|
||||||
|
# Output as JSON
|
||||||
|
claude-mem generate-title "fixed bug in checkout" --json
|
||||||
|
|
||||||
|
# Save to database
|
||||||
|
claude-mem generate-title "added feature" --session-id abc123 --save
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Diagnostics
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run environment diagnostics
|
||||||
|
claude-mem doctor
|
||||||
|
|
||||||
|
# Output as JSON
|
||||||
|
claude-mem doctor --json
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Changelog Generation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Generate changelog from memories
|
||||||
|
claude-mem changelog
|
||||||
|
|
||||||
|
# Preview without saving
|
||||||
|
claude-mem changelog --preview
|
||||||
|
|
||||||
|
# Generate for specific version
|
||||||
|
claude-mem changelog --generate 3.9.0
|
||||||
|
|
||||||
|
# Search historical versions
|
||||||
|
claude-mem changelog --historical 5
|
||||||
|
```
|
||||||
|
|
||||||
|
## :building_construction: Architecture
|
||||||
|
|
||||||
|
### Storage Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
~/.claude-mem/
|
~/.claude-mem/
|
||||||
|
├── archives/ # Compressed transcript backups
|
||||||
├── chroma/ # ChromaDB vector database
|
├── chroma/ # ChromaDB vector database
|
||||||
├── archives/ # Compressed transcript backups
|
├── trash/ # Smart Trash with recovery
|
||||||
├── index/ # Legacy JSONL memory indices
|
├── hooks/ # Hook configurations
|
||||||
├── hooks/ # Hook configuration files
|
|
||||||
├── trash/ # Smart Trash™ with recovery
|
|
||||||
├── logs/ # Operation logs
|
├── logs/ # Operation logs
|
||||||
└── claude-mem.db # SQLite metadata database
|
└── claude-mem.db # SQLite metadata database
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🏗️ Architecture
|
### Memory System
|
||||||
|
|
||||||
**Storage Layers**
|
**Rolling Memory** - Real-time conversation turn capture via hooks with immediate ChromaDB storage
|
||||||
- **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/`)
|
**TranscriptCompressor** - Intelligent chunking and compression of large conversations
|
||||||
- `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/`)
|
**MCP Server** - 15+ ChromaDB tools for memory operations and semantic search
|
||||||
- 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 Backend** - Session tracking, metadata management, and diagnostics storage
|
||||||
- SQLite stores: Session, Memory, Overview, Diagnostics, TranscriptEvent
|
|
||||||
- Path discovery for project detection
|
|
||||||
- Rolling settings and logs
|
|
||||||
|
|
||||||
## 🔍 How Memory Search Works
|
### Hook Integration
|
||||||
|
|
||||||
**Semantic Search Best Practices**:
|
Hooks communicate via JSON stdin/stdout and run with minimal overhead:
|
||||||
```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)
|
1. **user-prompt-submit** - Stores user prompt immediately in ChromaDB
|
||||||
mcp__claude-mem__chroma_query_documents({
|
2. **post-tool-use** - Spawns Agent SDK subprocess for async compression
|
||||||
collection_name: "claude_memories",
|
3. **stop-streaming** - Generates session overview, deletes SDK transcript
|
||||||
query_texts: ["project-name 2025-10-02 feature implementation"],
|
4. **session-start** - Loads project-specific context invisibly
|
||||||
n_results: 5
|
|
||||||
})
|
|
||||||
|
|
||||||
// Intent-based queries work better than keyword matching
|
### Project Structure
|
||||||
mcp__claude-mem__chroma_query_documents({
|
|
||||||
collection_name: "claude_memories",
|
```
|
||||||
query_texts: ["implementing oauth flow"],
|
src/
|
||||||
n_results: 10
|
├── bin/ # CLI entry point
|
||||||
})
|
├── commands/ # Command implementations
|
||||||
|
├── core/ # Core compression logic
|
||||||
|
├── services/ # SQLite, ChromaDB, path discovery
|
||||||
|
├── shared/ # Configuration and utilities
|
||||||
|
└── mcp-server.ts # MCP server implementation
|
||||||
|
|
||||||
|
hook-templates/ # Hook source files
|
||||||
|
dist/ # Minified production bundle
|
||||||
|
test/ # Unit and integration tests
|
||||||
```
|
```
|
||||||
|
|
||||||
**What Doesn't Work** (Avoid These!)
|
## :wrench: Configuration
|
||||||
- ❌ 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`
|
### Hook Timeout
|
||||||
- Metadata: `project`, `session_id`, `date`, `type`, `concepts`, `files`
|
|
||||||
- Embeddings: Semantic vectors for similarity search
|
|
||||||
- Documents: Atomic facts + full narrative with hierarchical structure
|
|
||||||
|
|
||||||
## ✅ Requirements
|
Default hook timeout is 180 seconds. Configure during installation:
|
||||||
|
|
||||||
- Node.js >= 18.0.0
|
|
||||||
- Bun >= 1.0.0 (for development)
|
|
||||||
- Claude Code with MCP support
|
|
||||||
- macOS/Linux (POSIX-compliant)
|
|
||||||
|
|
||||||
## 🛠️ Development
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Development mode
|
claude-mem install --timeout 300000 # 5 minutes
|
||||||
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
|
### MCP Server
|
||||||
|
|
||||||
Real-time slideshow of memories with SSE streaming:
|
Skip MCP server installation if needed:
|
||||||
|
|
||||||
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
|
```bash
|
||||||
claude-mem status # Check installation health
|
claude-mem install --skip-mcp
|
||||||
claude-mem doctor # Run full diagnostics
|
|
||||||
claude-mem install --force # Repair installation
|
|
||||||
claude-mem logs # View recent operations
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 📄 License
|
### Force Reinstall
|
||||||
|
|
||||||
AGPL-3.0 - See LICENSE file for details
|
```bash
|
||||||
|
claude-mem install --force
|
||||||
|
```
|
||||||
|
|
||||||
|
<!-- Roadmap -->
|
||||||
|
## :compass: Roadmap
|
||||||
|
|
||||||
|
* [x] Real-time conversation capture with streaming hooks
|
||||||
|
* [x] ChromaDB vector storage for semantic search
|
||||||
|
* [x] SQLite metadata and session tracking
|
||||||
|
* [x] MCP server with 15+ ChromaDB tools
|
||||||
|
* [x] Smart Trash for safe file deletion
|
||||||
|
* [x] Automatic session overviews
|
||||||
|
* [ ] Web UI for memory visualization
|
||||||
|
* [ ] Cross-platform Windows support
|
||||||
|
* [ ] Memory analytics and insights
|
||||||
|
|
||||||
|
<!-- Contributing -->
|
||||||
|
## :wave: Contributing
|
||||||
|
|
||||||
|
<a href="https://github.com/thedotmack/claude-mem/graphs/contributors">
|
||||||
|
<img src="https://contrib.rocks/image?repo=thedotmack/claude-mem" />
|
||||||
|
</a>
|
||||||
|
|
||||||
|
Contributions are always welcome!
|
||||||
|
|
||||||
|
1. Fork the repository
|
||||||
|
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
|
||||||
|
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
|
||||||
|
4. Push to the branch (`git push origin feature/AmazingFeature`)
|
||||||
|
5. Open a Pull Request
|
||||||
|
|
||||||
|
<!-- License -->
|
||||||
|
## :warning: License
|
||||||
|
|
||||||
|
Distributed under the AGPL-3.0 License. See [LICENSE](LICENSE) for more information.
|
||||||
|
|
||||||
|
<!-- Contact -->
|
||||||
|
## :handshake: Contact
|
||||||
|
|
||||||
|
Alex Newman - [@thedotmack](https://github.com/thedotmack)
|
||||||
|
|
||||||
|
Project Link: [https://github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
|
||||||
|
|
||||||
|
NPM Package: [https://www.npmjs.com/package/claude-mem](https://www.npmjs.com/package/claude-mem)
|
||||||
|
|
||||||
|
<!-- Acknowledgments -->
|
||||||
|
## :gem: Acknowledgements
|
||||||
|
|
||||||
|
- [ChromaDB](https://www.trychroma.com/) - Vector database for AI applications
|
||||||
|
- [Anthropic](https://www.anthropic.com/) - Claude AI and Agent SDK
|
||||||
|
- [Model Context Protocol](https://modelcontextprotocol.io) - Standardized AI tool integration
|
||||||
|
- [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) - Fast SQLite bindings
|
||||||
|
- [Shields.io](https://shields.io/) - Beautiful README badges
|
||||||
|
- [Awesome README Template](https://github.com/Louis3797/awesome-readme-template) - Template inspiration
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Remember more. Repeat less.** 🧠✨
|
**Philosophy**: claude-mem follows the **Make It Work First** approach - direct execution over defensive validation, natural failures instead of artificial guards, and memory as a living, evolving system. Context improves with use through semantic search, project isolation, and temporal relevance.
|
||||||
|
|
||||||
|
**Built with TypeScript, ChromaDB, SQLite, and the Anthropic Agent SDK**
|
||||||
|
|||||||
Vendored
+2
-2
File diff suppressed because one or more lines are too long
+1
-1
@@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"name": "claude-mem",
|
"name": "claude-mem",
|
||||||
"version": "3.9.12",
|
"version": "3.9.13",
|
||||||
"description": "Memory compression system for Claude Code - persist context across sessions",
|
"description": "Memory compression system for Claude Code - persist context across sessions",
|
||||||
"keywords": [
|
"keywords": [
|
||||||
"claude",
|
"claude",
|
||||||
|
|||||||
Reference in New Issue
Block a user