claude-mem

Persistent memory system for Claude Code - Transform your AI coding sessions from isolated conversations into continuous knowledge.

What is claude-mem?

claude-mem is a Claude Code plugin that captures, compresses, and recalls knowledge across sessions. It automatically:

• Extracts observations from every tool use (file reads, edits, searches)
• Generates summaries at session end
• Injects context into new sessions via CLAUDE.md files
• Enables semantic search across your project's history

Features

Feature	Description
Observation Extraction	AI-powered extraction of insights from tool outputs
Session Summaries	Compressed session history with request/learned/completed
Auto CLAUDE.md	Generates context files in your project directories
MCP Search Tools	Semantic search across observations and memories
Multi-Provider	Supports Anthropic, Mistral, OpenAI, Gemini for AI tasks
Web UI	Browse sessions, observations, and summaries
Document Caching	Caches Context7/WebFetch results for reuse
SSE Real-Time Updates	Live updates to CLAUDE.md files during sessions
Code Snippets	Automatic extraction and storage of code examples
Insights Dashboard	Daily stats, technology usage tracking, achievements
Auto-Spawn Workers	Automatic worker spawning on backend startup
Task Deduplication	Prevents duplicate task processing via SHA-256 hashing

Key Concepts

Observations

Observations are AI-extracted insights from tool usage. Each observation captures:

• Title & Text: Concise summary of what happened
• Type: One of 18 categories (see below)
• Facts: Extracted factual statements
• Concepts: Related patterns and ideas
• Files: Read and modified file paths

Observation Types:

Category	Types	Emoji
Work	bugfix, feature, refactor, change	🔴 🟣 🟠 🟢
Docs & Config	docs, config	📝 ⚙️
Quality	test, security, performance	🧪 🔒 ⚡
Infrastructure	deploy, infra, migration	🚀 🏗️ 📦
Knowledge	discovery, decision, research	🔵 💡 🔍
Integration	integration, dependency, api	🔗 📚 🌐

Session Lifecycle

session-start → user-prompt-submit → post-tool-use (repeated) → stop
     │                                      │                      │
     ▼                                      ▼                      ▼
 Inject context              Extract observations         Generate summary
 Spawn SSE writer           Queue AI extraction tasks     Update CLAUDE.md

Task Queue

Background workers process AI tasks with priority-based scheduling:

Task Type	Priority	Description
observation	50	Extract insights from tool output
summarize	40	Compress session observations
embedding	30	Generate vector embeddings
claude-md	20	Generate CLAUDE.md content

SSE Writer

The SSE Writer is a standalone Node.js process that handles real-time CLAUDE.md updates:

• Spawned per session at session-start hook
• Connects to /api/stream via EventSource API
• Validates session/project/directory before every write (security boundary)
• Listens for events: claudemd:ready, session:ended
• Preserves user content outside <claude-mem-context> tags
• Auto-exits after 10 minutes if no relevant events
• PID management for cleanup via ~/.claude-mem/sse-writer-*.pid

┌─────────────┐      SSE       ┌─────────────┐
│   Backend   │ ────────────▶  │ SSE Writer  │
│  (Express)  │  claudemd:ready│  (Node.js)  │
└─────────────┘                └──────┬──────┘
                                      │
                                      ▼
                               ┌─────────────┐
                               │ CLAUDE.md   │
                               │   files     │
                               └─────────────┘

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Claude Code                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │ SessionStart│  │PostToolUse  │  │    Stop     │          │
│  │    Hook     │  │    Hook     │  │    Hook     │          │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘          │
└─────────┼────────────────┼────────────────┼─────────────────┘
          │                │                │
          ▼                ▼                ▼
┌─────────────────────────────────────────────────────────────┐
│                       Backend (Express)                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   Session   │  │    Task     │  │     SSE     │          │
│  │   Service   │  │   Service   │  │ Broadcaster │          │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘          │
└─────────┼────────────────┼────────────────┼─────────────────┘
          │                │                │
          ▼                ▼                ▼
┌─────────────────┐ ┌─────────────┐ ┌─────────────────────────┐
│    Database     │ │   Worker    │ │      SSE Writer         │
│(SQLite/Postgres)│ │  (AI Agent) │ │   (CLAUDE.md files)     │
└─────────────────┘ └─────────────┘ └─────────────────────────┘

Installation

As Claude Code Plugin

# Install from Claude Code marketplace
claude mcp install claude-mem

Development Setup

# Clone the repository
git clone https://git.customable.host/customable/claude-mem.git
cd claude-mem

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Build plugin for marketplace
pnpm build:plugin

# Sync to Claude installations
pnpm sync-marketplace

Project Structure

packages/
├── types/          # Shared TypeScript types
├── shared/         # Utilities, logging, settings
├── database/       # SQLite/PostgreSQL + MikroORM repositories
├── backend/        # Express API server
├── worker/         # AI agents for observation extraction
├── hooks/          # Claude Code hook handlers
└── ui/             # React web interface

Configuration

Settings are stored in ~/.claude-mem/settings.json:

{
  "BACKEND_PORT": 37777,
  "AI_PROVIDER": "anthropic",
  "ANTHROPIC_API_KEY": "sk-ant-...",
  "CLAUDEMD_ENABLED": true,
  "CLAUDEMD_OBSERVATION_INTERVAL": 10,
  "LOG_LEVEL": "info"
}

MCP Tools

claude-mem exposes search tools via MCP:

// Search observations
mcp__plugin_claude-mem_mcp-search__search({
  query: "authentication implementation",
  limit: 10
})

// Get observation details
mcp__plugin_claude-mem_mcp-search__get_observations({
  ids: [123, 456]
})

// Save a memory
mcp__plugin_claude-mem_mcp-search__save_memory({
  text: "Important decision about architecture",
  type: "decision"
})

Development

# Restart dev server (backend + UI)
pnpm run dev:restart

# Type check all packages
pnpm run typecheck

# Build plugin
pnpm run build:plugin

Database

SQLite (default) or PostgreSQL database, managed by MikroORM. See docs/DATABASE.md for detailed setup instructions.

# Default (SQLite)
claude-mem-backend start

# With PostgreSQL
claude-mem-backend start --db postgres://user:pass@localhost:5432/claudemem
# Or via environment variable
DATABASE_URL=postgres://user:pass@localhost:5432/claudemem claude-mem-backend start

SQLite database at ~/.claude-mem/claude-mem.db:

Table	Description
sessions	Claude Code sessions with metadata
observations	AI-extracted insights from tool use
summaries	Compressed session summaries
claudemd	Generated CLAUDE.md content
tasks	Worker task queue with deduplication
documents	Cached external documentation (Context7/WebFetch)
prompts	User prompts with urgency tracking
code_snippets	Extracted code examples from sessions
achievements	User achievements and milestones
daily_stats	Aggregated daily statistics
technology_usage	Technology usage tracking
observation_links	Links between related observations
repositories	Git repository metadata

Roadmap

Current high-priority items:

• Endless Mode (#109) - Real-time context compression for unlimited session length

Recently Completed

• ✅ Documents Search (#115) - MCP tool for searching cached documentation
• ✅ Process/Memory Leaks (#101) - Fix orphaned worker processes
• ✅ Database Schema Redesign (#197) - Modernized table structure with MikroORM

See all open issues for the full list.

Acknowledgments

Originally based on thedotmack/claude-mem. This project has since evolved into an independent implementation with:

• Modular monorepo architecture
• Multi-provider AI support (Anthropic, Mistral, OpenAI)
• Auto-generated CLAUDE.md files per subdirectory
• Document caching for Context7/WebFetch
• Forgejo integration

Related

• Claude Code - Anthropic's agentic coding tool

License

MIT