A standardized MCP server that provides Claude Code with persistent project memory and context-aware development assistance.

CCMem (Claude Code Memory) transforms Claude Code from a stateless assistant into a project-aware development partner by maintaining persistent memory across sessions. The system captures and stores project context, architectural decisions, development history, and accumulated knowledge.

• Project Settings Management: Stores and recalls start, test, build, and deployment commands
• Architecture Documentation: Maintains tech stack decisions, patterns, and design choices
• Development History: Tracks stories, tasks, bugs, and lessons learned
• Knowledge Accumulation: Builds context and insights over time
• Zero Token Cost: Uses local SQLite database instead of expensive embedding services
• Automatic Capture: Intelligent hooks capture development activity seamlessly

Use Claude's built-in MCP manager with NPM:

claude mcp add ccmem -- npx -y @adestefa/ccmem@latest

Automatic setup:

• Configures Claude Code MCP integration
• Sets up memory capture hooks
• Ready to use immediately

Install directly from GitHub repository:

claude mcp add ccmem -- uvx --from git+https://github.com/adestefa/ccmem ccmem-server

Benefits:

• Always uses latest code
• No NPM registry dependency
• Ideal for development and testing

npm install -g @adestefa/ccmem
cd /path/to/your/project
ccmem setup

curl -fsSL https://raw.githubusercontent.com/adestefa/ccmem/main/install.sh | bash

git clone https://github.com/adestefa/ccmem.git
cd ccmem
npm install -g .
ccmem setup

When using claude mcp add, configuration is handled automatically. The system will:

1. Install the MCP server
2. Configure Claude Code integration
3. Set up automatic memory capture hooks
4. Initialize project database on first use

If installing manually, add to your ~/.claude/mcp_servers.json:

{
  "mcpServers": {
    "ccmem": {
      "command": "npx",
      "args": ["-y", "@adestefa/ccmem@latest"],
      "description": "Project memory system for Claude Code"
    }
  }
}

CCMem provides a comprehensive CLI for project memory management:

# Initialize memory system in current project
ccmem setup

# View project status and memory
ccmem status

# Search project memory
ccmem search "authentication"

# Get project context
ccmem context

# Learn project settings
ccmem learn setting start command "npm start"
ccmem learn architecture "API Server" "REST API using Express" "Node.js,Express,PostgreSQL"

• ccmem setup - Initialize CCMem in current project
• ccmem status - Display project status and memory summary
• ccmem search <query> - Search across all project memory
• ccmem context [focus] - Get project context (all, settings, architecture, current, recent)
• ccmem learn setting <category> <key> <value> - Store project configuration
• ccmem learn architecture <component> <description> <tech> - Document architecture decisions

Once installed, CCMem operates transparently with Claude Code:

1. Session Initialization: Automatically loads project context when Claude starts
2. Active Development: Captures file modifications, command executions, and architectural insights
3. Knowledge Building: Extracts and stores development patterns and decisions
4. Context Provision: Provides relevant memory when Claude needs project information

CCMem uses a local SQLite database with the following core tables:

• settings - Project configuration and commands
• architecture - System design and technology decisions
• deployment - Release and deployment procedures
• story - User stories and feature development
• task - Development tasks and implementation notes
• defect - Bug reports and fixes
• lessons - Architectural decisions and learnings
• knowledge - General project context and notes

The system includes intelligent hooks that automatically capture:

• File Operations: Significant code modifications and their context
• Command Execution: Build, test, and deployment commands
• Architectural Insights: Technical decisions extracted from Claude's responses
• Development Milestones: Session summaries and progress markers

• Location: .claude/db/ccmem.sqlite in each project directory
• Isolation: Each project maintains its own separate database
• Performance: Optimized with indexes and prepared statements
• Portability: Standard SQLite format for easy backup and migration

CCMem provides the following MCP tools for Claude Code:

• ccmem_learn_setting - Store project configuration
• ccmem_learn_architecture - Document system architecture
• ccmem_learn_deployment - Record deployment procedures

• ccmem_create_story - Create user stories
• ccmem_create_task - Track development tasks
• ccmem_log_defect - Record bugs and fixes

• ccmem_record_lesson - Capture lessons learned
• ccmem_add_knowledge - Store general project knowledge
• ccmem_get_context - Retrieve project context
• ccmem_search - Search project memory

During active development, CCMem automatically:

• Captures file modifications and their significance
• Records command executions and their outcomes
• Extracts architectural insights from Claude's responses
• Documents development milestones and session summaries

When exploring existing projects, CCMem:

• Documents discovered project structure and technologies
• Maps configuration files and their purposes
• Captures existing workflows and development patterns
• Identifies knowledge gaps for future investigation

• Continuity: Maintain context across development sessions
• Learning: Build institutional knowledge about projects
• Efficiency: Eliminate need to re-explain project context

• Onboarding: Provide instant project context for new team members
• Knowledge Sharing: Centralize architectural decisions and patterns
• Consistency: Standardize development approaches across projects

• Context Awareness: Understand project history and decisions
• Intelligent Assistance: Provide relevant, project-specific guidance
• Reduced Repetition: Eliminate need to re-establish context each session

Option 1: Bun (Recommended)

• Installation: curl -fsSL https://bun.sh/install | bash
• Benefits: Native SQLite support, faster performance, zero external dependencies
• Platforms: macOS, Linux, Windows (WSL)

Option 2: Node.js (Fallback)

• Version: Node.js 18.0.0 or higher
• Installation: nodejs.org or brew install node
• Note: Uses JSON storage instead of SQLite for compatibility

Option 3: UV/UVX (For Direct GitHub)

• Installation: brew install uv (macOS) or winget install --id=astral-sh.uv (Windows)
• Use case: Direct GitHub repository installation

• Claude Code with MCP support
• Proper MCP server configuration (automatic with claude mcp add)

MIT License - see LICENSE file for details.

Contributions are welcome. Please see the repository for contribution guidelines.

For issues and support, please use the GitHub issue tracker at https://github.com/adestefa/ccmem/issues.