Alex Newman
f5b25e8fc4
- Updated version badge in README.md to 6.0.0 - Updated 'What's New' sections in README.md and introduction.mdx - Highlighted major session management and transcript processing improvements - Removed restrictive permissions from .claude/settings.json 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
110 lines
6.1 KiB
Plaintext
110 lines
6.1 KiB
Plaintext
---
|
|
title: "Introduction"
|
|
description: "Persistent memory compression system for Claude Code"
|
|
---
|
|
|
|
# Claude-Mem
|
|
|
|
**Persistent memory compression system for Claude Code**
|
|
|
|
Claude-Mem seamlessly preserves context across sessions by automatically capturing tool usage observations, generating semantic summaries, and making them available to future sessions. This enables Claude to maintain continuity of knowledge about projects even after sessions end or reconnect.
|
|
|
|
## Quick Start
|
|
|
|
Start a new Claude Code session in the terminal and enter the following commands:
|
|
|
|
```bash
|
|
/plugin marketplace add thedotmack/claude-mem
|
|
/plugin install claude-mem
|
|
```
|
|
|
|
Restart Claude Code. Context from previous sessions will automatically appear in new sessions.
|
|
|
|
## Key Features
|
|
|
|
- 🧠 **Persistent Memory** - Context survives across sessions
|
|
- 🔍 **mem-search Skill** - Query your project history with natural language (~2,250 token savings)
|
|
- 🌐 **Web Viewer UI** - Real-time memory stream visualization at http://localhost:37777
|
|
- 🎨 **Theme Toggle** - Light, dark, and system preference themes
|
|
- 🤖 **Automatic Operation** - No manual intervention required
|
|
- 📊 **FTS5 Search** - Fast full-text search across observations
|
|
- 🔗 **Citations** - Reference past decisions with `claude-mem://` URIs
|
|
|
|
## How It Works
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Session Start → Inject context from last 10 sessions │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ User Prompts → Create session, save user prompts │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Tool Executions → Capture observations (Read, Write, etc.) │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Worker Processes → Extract learnings via Claude Agent SDK │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Session Ends → Generate summary, ready for next session │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
**Core Components:**
|
|
1. **6 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd, UserMessage
|
|
2. **Smart Install** - Cached dependency checker (pre-hook script)
|
|
3. **Worker Service** - HTTP API on port 37777 managed by PM2
|
|
4. **SQLite Database** - Stores sessions, observations, summaries with FTS5 search
|
|
5. **mem-search Skill** - Query historical context with natural language
|
|
6. **Web Viewer UI** - Real-time visualization with SSE and infinite scroll
|
|
|
|
See [Architecture Overview](architecture/overview) for details.
|
|
|
|
## System Requirements
|
|
|
|
- **Node.js**: 18.0.0 or higher
|
|
- **Claude Code**: Latest version with plugin support
|
|
- **PM2**: Process manager (bundled - no global install required)
|
|
- **SQLite 3**: For persistent storage (bundled)
|
|
|
|
## What's New in v6.0.0
|
|
|
|
**🚀 Major Session Management & Transcript Processing Improvements:**
|
|
|
|
- **Enhanced Session Initialization**: Accept userPrompt and promptNumber for better context tracking
|
|
- **Live UserPrompt Updates**: Multi-turn conversation support with real-time prompt tracking
|
|
- **Improved SessionManager**: Better context handling and observation processing
|
|
- **Comprehensive Transcript Processing**: New scripts and utilities for analyzing Claude Code transcripts
|
|
- **Rich Context Extraction**: Advanced parsing utilities for extracting meaningful context from sessions
|
|
- **Refactored Architecture**: Improved hooks and SDKAgent for more reliable observation handling
|
|
- **Silent Debug Logging**: Better debugging capabilities without cluttering output
|
|
- **Enhanced Error Handling**: More robust error recovery and debugging tools
|
|
|
|
**Breaking Changes**: Significant architectural changes in session management and observation handling. Existing sessions continue to work, but internal APIs have evolved.
|
|
|
|
**Previous Highlights:**
|
|
- **v5.5.0**: mem-search skill enhancement with 100% effectiveness rate
|
|
- **v5.4.0**: Skill-based search architecture (~2,250 tokens saved per session)
|
|
- **v5.1.2**: Theme toggle for light/dark mode in viewer UI
|
|
|
|
## Next Steps
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Installation" icon="download" href="/installation">
|
|
Quick start & advanced installation
|
|
</Card>
|
|
<Card title="Getting Started" icon="rocket" href="/usage/getting-started">
|
|
Learn how Claude-Mem works automatically
|
|
</Card>
|
|
<Card title="Architecture" icon="sitemap" href="/architecture/overview">
|
|
System components & data flow
|
|
</Card>
|
|
<Card title="Search Tools" icon="magnifying-glass" href="/usage/search-tools">
|
|
Query your project history
|
|
</Card>
|
|
</CardGroup>
|