claude-mem 3.9.14 → 9.0.7

package/README.md

@@ -1,470 +1,316 @@
-<div align="center">
+<p align="center">
+  Official $CMEM Links: 
+  <a href="https://bags.fm/2TsmuYUrsctE57VLckZBYEEzdokUF8j8e1GavekWBAGS">Bags.fm</a> •
+  <a href="https://jup.ag/tokens/2TsmuYUrsctE57VLckZBYEEzdokUF8j8e1GavekWBAGS">Jupiter</a> •
+  <a href="https://photon-sol.tinyastro.io/en/lp/6MzFAkWnac6GSK1EdFX93dZeukGfzrFq4UHWarhGSQyd">Photon</a> •
+  <a href="https://dexscreener.com/solana/6mzfakwnac6gsk1edfx93dzeukgfzrfq4uhwarhgsqyd">DEXScreener</a>
+</p>
 
-  <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" />
+<p align="center">Official CA: 2TsmuYUrsctE57VLckZBYEEzdokUF8j8e1GavekWBAGS (on Solana)</p>
 
-  <p>
-    Memory compression and persistence system for Claude Code conversations
-  </p>
+<h1 align="center">
+  <br>
+  <a href="https://github.com/thedotmack/claude-mem">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
+      <img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
+    </picture>
+  </a>
+  <br>
+</h1>
+
+<p align="center">
+  <a href="docs/i18n/README.zh.md">🇨🇳 中文</a> •
+  <a href="docs/i18n/README.ja.md">🇯🇵 日本語</a> •
+  <a href="docs/i18n/README.pt-br.md">🇧🇷 Português</a> •
+  <a href="docs/i18n/README.ko.md">🇰🇷 한국어</a> •
+  <a href="docs/i18n/README.es.md">🇪🇸 Español</a> •
+  <a href="docs/i18n/README.de.md">🇩🇪 Deutsch</a> •
+  <a href="docs/i18n/README.fr.md">🇫🇷 Français</a>
+  <a href="docs/i18n/README.he.md">🇮🇱 עברית</a> •
+  <a href="docs/i18n/README.ar.md">🇸🇦 العربية</a> •
+  <a href="docs/i18n/README.ru.md">🇷🇺 Русский</a> •
+  <a href="docs/i18n/README.pl.md">🇵🇱 Polski</a> •
+  <a href="docs/i18n/README.cs.md">🇨🇿 Čeština</a> •
+  <a href="docs/i18n/README.nl.md">🇳🇱 Nederlands</a> •
+  <a href="docs/i18n/README.tr.md">🇹🇷 Türkçe</a> •
+  <a href="docs/i18n/README.uk.md">🇺🇦 Українська</a> •
+  <a href="docs/i18n/README.vi.md">🇻🇳 Tiếng Việt</a> •
+  <a href="docs/i18n/README.id.md">🇮🇩 Indonesia</a> •
+  <a href="docs/i18n/README.th.md">🇹🇭 ไทย</a> •
+  <a href="docs/i18n/README.hi.md">🇮🇳 हिन्दी</a> •
+  <a href="docs/i18n/README.bn.md">🇧🇩 বাংলা</a> •
+  <a href="docs/i18n/README.ro.md">🇷🇴 Română</a> •
+  <a href="docs/i18n/README.sv.md">🇸🇪 Svenska</a> •
+  <a href="docs/i18n/README.it.md">🇮🇹 Italiano</a> •
+  <a href="docs/i18n/README.el.md">🇬🇷 Ελληνικά</a> •
+  <a href="docs/i18n/README.hu.md">🇭🇺 Magyar</a> •
+  <a href="docs/i18n/README.fi.md">🇫🇮 Suomi</a> •
+  <a href="docs/i18n/README.da.md">🇩🇰 Dansk</a> •
+  <a href="docs/i18n/README.no.md">🇳🇴 Norsk</a>
+</p>
 
+<h4 align="center">Persistent memory compression system built for <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
 
-<!-- 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" />
+<p align="center">
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
   </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 href="package.json">
+    <img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
   </a>
-  <a href="https://nodejs.org/">
-    <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="node version" />
+  <a href="package.json">
+    <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
   </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 href="https://github.com/thedotmack/awesome-claude-code">
+    <img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
   </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
+<p align="center">
+  <a href="https://trendshift.io/repositories/15496" target="_blank">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
+      <img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
+    </picture>
+  </a>
+</p>
 
-```bash
-npm install -g claude-mem
-claude-mem install
-```
+<br>
 
-The interactive installer will guide you through three installation scopes:
+<p align="center">
+  <a href="https://github.com/thedotmack/claude-mem">
+    <picture>
+      <img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
+    </picture>
+  </a>
+</p>
 
-- **User** - Install for current user (default, recommended)
-- **Project** - Install for current project only
-- **Local** - Install to custom directory
+<p align="center">
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#how-it-works">How It Works</a> •
+  <a href="#mcp-search-tools">Search Tools</a> •
+  <a href="#documentation">Documentation</a> •
+  <a href="#configuration">Configuration</a> •
+  <a href="#troubleshooting">Troubleshooting</a> •
+  <a href="#license">License</a>
+</p>
 
-<!-- Running Tests -->
-### :test_tube: Running Tests
+<p align="center">
+  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.
+</p>
 
-To run tests, use the following commands
+---
 
-```bash
-# Run all tests
-bun test
+## Quick Start
 
-# Run integration tests
-npm run test:integration
+Start a new Claude Code session in the terminal and enter the following commands:
 
-# Run with coverage
-npm run test:coverage
 ```
+> /plugin marketplace add thedotmack/claude-mem
 
-<!-- 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
+> /plugin install claude-mem
 ```
 
-### Hook System
+Restart Claude Code. Context from previous sessions will automatically appear in new sessions.
 
-claude-mem integrates with Claude Code via streaming hooks that capture conversation events:
+**Key Features:**
 
-- **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
+- 🧠 **Persistent Memory** - Context survives across sessions
+- 📊 **Progressive Disclosure** - Layered memory retrieval with token cost visibility
+- 🔍 **Skill-Based Search** - Query your project history with mem-search skill
+- 🖥️ **Web Viewer UI** - Real-time memory stream at http://localhost:37777
+- 💻 **Claude Desktop Skill** - Search memory from Claude Desktop conversations
+- 🔒 **Privacy Control** - Use `<private>` tags to exclude sensitive content from storage
+- ⚙️ **Context Configuration** - Fine-grained control over what context gets injected
+- 🤖 **Automatic Operation** - No manual intervention required
+- 🔗 **Citations** - Reference past observations with IDs (access via http://localhost:37777/api/observation/{id} or view all in the web viewer at http://localhost:37777)
+- 🧪 **Beta Channel** - Try experimental features like Endless Mode via version switching
 
-Hooks are configured during installation with a 180-second timeout and run transparently in the background.
+---
 
-### Memory Operations
+## Documentation
 
-#### Manual Compression
+📚 **[View Full Documentation](docs/)** - Browse markdown docs on GitHub
 
-```bash
-claude-mem compress
-```
+### Getting Started
 
-Compress Claude Code transcripts into searchable memories with semantic embeddings.
+- **[Installation Guide](https://docs.claude-mem.ai/installation)** - Quick start & advanced installation
+- **[Usage Guide](https://docs.claude-mem.ai/usage/getting-started)** - How Claude-Mem works automatically
+- **[Search Tools](https://docs.claude-mem.ai/usage/search-tools)** - Query your project history with natural language
+- **[Beta Features](https://docs.claude-mem.ai/beta-features)** - Try experimental features like Endless Mode
 
-#### Context Loading
+### Best Practices
 
-```bash
-# Load last 10 memories for current project
-claude-mem load-context
+- **[Context Engineering](https://docs.claude-mem.ai/context-engineering)** - AI agent context optimization principles
+- **[Progressive Disclosure](https://docs.claude-mem.ai/progressive-disclosure)** - Philosophy behind Claude-Mem's context priming strategy
 
-# Load specific number of memories
-claude-mem load-context --count 20
+### Architecture
 
-# Filter by project
-claude-mem load-context --project my-app
+- **[Overview](https://docs.claude-mem.ai/architecture/overview)** - System components & data flow
+- **[Architecture Evolution](https://docs.claude-mem.ai/architecture-evolution)** - The journey from v3 to v5
+- **[Hooks Architecture](https://docs.claude-mem.ai/hooks-architecture)** - How Claude-Mem uses lifecycle hooks
+- **[Hooks Reference](https://docs.claude-mem.ai/architecture/hooks)** - 7 hook scripts explained
+- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API & Bun management
+- **[Database](https://docs.claude-mem.ai/architecture/database)** - SQLite schema & FTS5 search
+- **[Search Architecture](https://docs.claude-mem.ai/architecture/search-architecture)** - Hybrid search with Chroma vector database
 
-# Output raw JSON
-claude-mem load-context --raw
-```
+### Configuration & Development
 
-#### Trash Management
+- **[Configuration](https://docs.claude-mem.ai/configuration)** - Environment variables & settings
+- **[Development](https://docs.claude-mem.ai/development)** - Building, testing, contributing
+- **[Troubleshooting](https://docs.claude-mem.ai/troubleshooting)** - Common issues & solutions
 
-claude-mem includes Smart Trash for safe file operations:
+---
 
-```bash
-# Move files to trash
-claude-mem trash file.txt
-claude-mem trash -r directory/
+## How It Works
 
-# View trash contents
-claude-mem trash view
+**Core Components:**
 
-# Restore files interactively
-claude-mem restore
+1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
+2. **Smart Install** - Cached dependency checker (pre-hook script, not a lifecycle hook)
+3. **Worker Service** - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by Bun
+4. **SQLite Database** - Stores sessions, observations, summaries
+5. **mem-search Skill** - Natural language queries with progressive disclosure
+6. **Chroma Vector Database** - Hybrid semantic + keyword search for intelligent context retrieval
 
-# Empty trash permanently
-claude-mem trash empty
-```
+See [Architecture Overview](https://docs.claude-mem.ai/architecture/overview) for details.
 
-### ChromaDB MCP Tools
+---
 
-claude-mem exposes 15+ ChromaDB operations via MCP:
+## MCP Search Tools
 
-```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"]'
-```
+Claude-Mem provides intelligent memory search through **4 MCP tools** following a token-efficient **3-layer workflow pattern**:
 
-See all available Chroma MCP commands with `claude-mem --help`.
+**The 3-Layer Workflow:**
 
-### Advanced Usage
+1. **`search`** - Get compact index with IDs (~50-100 tokens/result)
+2. **`timeline`** - Get chronological context around interesting results
+3. **`get_observations`** - Fetch full details ONLY for filtered IDs (~500-1,000 tokens/result)
 
-#### Session Title Generation
+**How It Works:**
+- Claude uses MCP tools to search your memory
+- Start with `search` to get an index of results
+- Use `timeline` to see what was happening around specific observations
+- Use `get_observations` to fetch full details for relevant IDs
+- **~10x token savings** by filtering before fetching details
 
-```bash
-# Generate title and subtitle from prompt
-claude-mem generate-title "implemented authentication with OAuth"
+**Available MCP Tools:**
 
-# Output as JSON
-claude-mem generate-title "fixed bug in checkout" --json
+1. **`search`** - Search memory index with full-text queries, filters by type/date/project
+2. **`timeline`** - Get chronological context around a specific observation or query
+3. **`get_observations`** - Fetch full observation details by IDs (always batch multiple IDs)
+4. **`__IMPORTANT`** - Workflow documentation (always visible to Claude)
 
-# Save to database
-claude-mem generate-title "added feature" --session-id abc123 --save
-```
+**Example Usage:**
 
-#### Diagnostics
+```typescript
+// Step 1: Search for index
+search(query="authentication bug", type="bugfix", limit=10)
 
-```bash
-# Run environment diagnostics
-claude-mem doctor
+// Step 2: Review index, identify relevant IDs (e.g., #123, #456)
 
-# Output as JSON
-claude-mem doctor --json
+// Step 3: Fetch full details
+get_observations(ids=[123, 456])
 ```
 
-#### Changelog Generation
+See [Search Tools Guide](https://docs.claude-mem.ai/usage/search-tools) for detailed examples.
 
-```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
-```
+## Beta Features
 
-## :building_construction: Architecture
+Claude-Mem offers a **beta channel** with experimental features like **Endless Mode** (biomimetic memory architecture for extended sessions). Switch between stable and beta versions from the web viewer UI at http://localhost:37777 → Settings.
 
-### Storage Structure
+See **[Beta Features Documentation](https://docs.claude-mem.ai/beta-features)** for details on Endless Mode and how to try it.
 
-```
-~/.claude-mem/
-├── archives/           # Compressed transcript backups
-├── chroma/            # ChromaDB vector database
-├── trash/             # Smart Trash with recovery
-├── hooks/             # Hook configurations
-├── logs/              # Operation logs
-└── claude-mem.db      # SQLite metadata database
-```
+---
 
-### Memory System
+## System Requirements
 
-**Rolling Memory** - Real-time conversation turn capture via hooks with immediate ChromaDB storage
+- **Node.js**: 18.0.0 or higher
+- **Claude Code**: Latest version with plugin support
+- **Bun**: JavaScript runtime and process manager (auto-installed if missing)
+- **uv**: Python package manager for vector search (auto-installed if missing)
+- **SQLite 3**: For persistent storage (bundled)
 
-**TranscriptCompressor** - Intelligent chunking and compression of large conversations
+---
 
-**MCP Server** - 15+ ChromaDB tools for memory operations and semantic search
+## Configuration
 
-**SQLite Backend** - Session tracking, metadata management, and diagnostics storage
+Settings are managed in `~/.claude-mem/settings.json` (auto-created with defaults on first run). Configure AI model, worker port, data directory, log level, and context injection settings.
 
-### Hook Integration
+See the **[Configuration Guide](https://docs.claude-mem.ai/configuration)** for all available settings and examples.
 
-Hooks communicate via JSON stdin/stdout and run with minimal overhead:
+---
 
-1. **user-prompt-submit** - Stores user prompt immediately in ChromaDB
-2. **post-tool-use** - Spawns Agent SDK subprocess for async compression
-3. **stop-streaming** - Generates session overview, deletes SDK transcript
-4. **session-start** - Loads project-specific context invisibly
+## Development
 
-### Project Structure
+See the **[Development Guide](https://docs.claude-mem.ai/development)** for build instructions, testing, and contribution workflow.
 
-```
-src/
-├── 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
-```
+---
 
-## :wrench: Configuration
+## Troubleshooting
 
-### Hook Timeout
+If experiencing issues, describe the problem to Claude and the troubleshoot skill will automatically diagnose and provide fixes.
 
-Default hook timeout is 180 seconds. Configure during installation:
+See the **[Troubleshooting Guide](https://docs.claude-mem.ai/troubleshooting)** for common issues and solutions.
 
-```bash
-claude-mem install --timeout 300000  # 5 minutes
-```
+---
 
-### MCP Server
+## Bug Reports
 
-Skip MCP server installation if needed:
+Create comprehensive bug reports with the automated generator:
 
 ```bash
-claude-mem install --skip-mcp
+cd ~/.claude/plugins/marketplaces/thedotmack
+npm run bug-report
 ```
 
-### Force Reinstall
+## Contributing
 
-```bash
-claude-mem install --force
-```
+Contributions are welcome! Please:
 
-<!-- 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
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes with tests
+4. Update documentation
+5. Submit a Pull Request
 
-<!-- Contributing -->
-## :wave: Contributing
+See [Development Guide](https://docs.claude-mem.ai/development) for contribution workflow.
 
-<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!
+## License
 
-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
+This project is licensed under the **GNU Affero General Public License v3.0** (AGPL-3.0).
 
-<!-- License -->
-## :warning: License
+Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.
 
-Distributed under the AGPL-3.0 License. See [LICENSE](LICENSE) for more information.
+See the [LICENSE](LICENSE) file for full details.
 
-<!-- Contact -->
-## :handshake: Contact
+**What This Means:**
 
-Alex Newman - [@thedotmack](https://github.com/thedotmack)
+- You can use, modify, and distribute this software freely
+- If you modify and deploy on a network server, you must make your source code available
+- Derivative works must also be licensed under AGPL-3.0
+- There is NO WARRANTY for this software
 
-Project Link: [https://github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
+**Note on Ragtime**: The `ragtime/` directory is licensed separately under the **PolyForm Noncommercial License 1.0.0**. See [ragtime/LICENSE](ragtime/LICENSE) for details.
 
-NPM Package: [https://www.npmjs.com/package/claude-mem](https://www.npmjs.com/package/claude-mem)
+---
 
-<!-- Acknowledgments -->
-## :gem: Acknowledgements
+## Support
 
- - [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
+- **Documentation**: [docs/](docs/)
+- **Issues**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
+- **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
+- **Official X Account**: [@Claude_Memory](https://x.com/Claude_Memory)
+- **Official Discord**: [Join Discord](https://discord.com/invite/J4wttp9vDu)
+- **Author**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
 
 ---
 
-**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**
+**Built with Claude Agent SDK** | **Powered by Claude Code** | **Made with TypeScript**