haiyuan-ai-cc-mem

CC-mem

English | 中文

Lightweight memory management system for Claude Code

Tests: ✅ Full regression passed | License: MIT

---

Overview

CC-mem is a local-first, rule-driven, tiered-storage, explainable-injection memory system for Claude Code.

Target Users: Individual developers, technical bloggers, heavy AI assistant users

Core Values:

• 🪶 Lightweight - Pure Bash scripts, core dependency on SQLite only, no Node runtime required
• 🔒 Local-first - All data stored locally, no cloud dependencies, privacy controlled
• 📦 Ready to use - Install and run, no complex configuration
• 🧪 Well tested - Full regression coverage for storage, CLI, hooks, and edge cases

Ideal For:

• ✅ Personal knowledge management and session memory
• ✅ Cross-session context retention
• ✅ Technical decision and solution documentation
• ✅ Project-level memory isolation

Not Suitable For:

• ❌ Enterprise multi-user collaboration
• ❌ Complex scenarios requiring vector search
• ❌ Graph-based knowledge representation

---

Features

• Automatic Capture: PostToolUse / UserPromptSubmit / Stop / SessionEnd continuously capture work progress
• Real-time Injection: SessionStart preloads context + UserPromptSubmit query-aware recall
• Tiered Memory: Organized by source, lifecycle, and auto-inject eligibility
• Cross-project Linking: Controlled related project memory supplementation via project_links
• Smart Truncation: Stop / SessionEnd locally truncate overly long responses and logs
• Preview Compression: content_preview generates tiered previews based on durable / working / temporary, balancing fidelity and storage efficiency
• Rule-based Classification: Automatic capture paths share a unified local classifier, generating category, confidence, and reasoning to inform tiering decisions
• Prompt Reuse Detection: user_prompt_submit prioritizes extracting reusable preferences, constraints, rules, and decisions, skipping one-time confirmation phrases
• Tool Signal Extraction: post_tool_use focuses on extracting error, fix, verification, and file change signals rather than elevating entire outputs to memory
• Persistent Storage: SQLite local database
• Tiered Retrieval: FTS, Chinese fallback, timeline, related project recall
• Failure Recovery: Hooks write failures are queued locally for retry, preventing data loss
• MCP Tools: Exposes capture/search/get/timeline/inject-context/recall via MCP
• Markdown Export: Export to standard Markdown files
• Hooks Integration: SessionStart / UserPromptSubmit auto-injection, PostToolUse / Stop / SessionEnd auto-capture
• Memory History: Track memory events and change history
• Content Deduplication: Automatic duplicate detection based on content hash
• Concept Tags: Predefined concept auto-recognition

Installation

Requirements

• macOS 10.15+ - Built-in Bash and SQLite
• Linux Ubuntu 18.04+ / Debian 10+ - Requires sqlite3 installation
• Windows Windows 10/11 + WSL2

See Compatibility Guide for detailed requirements.

Additional notes:

• Recommended: git, sqlite3, jq
• Hooks auto-injection/capture functionality works best with jq
• MCP server requires python3

Option 1: One-line Install (Recommended)

curl -sSL https://raw.githubusercontent.com/haiyuan-ai/cc-mem/main/install.sh | bash

Restart Claude Code after installation:

exit
# restart claude

Option 2: Let Claude Code Install (Easiest)

Simply tell Claude Code:

Install https://github.com/haiyuan-ai/cc-mem

Claude Code will automatically:

1. Clone the repository to the correct directory
2. Register marketplace configuration
3. Register as installed plugin
4. Initialize the database

After installation, restart Claude Code:

exit
# restart claude

Then enable the plugin:

/plugin install cc-mem@haiyuan-ai-cc-mem

Restart Claude Code once more to activate hooks.

Option 3: Manual Installation

Step 1: Clone Repository

git clone https://github.com/haiyuan-ai/cc-mem.git ~/.claude/plugins/marketplaces/haiyuan-ai-cc-mem

Step 2: Register Marketplace

Edit ~/.claude/plugins/known_marketplaces.json, add:

{
  "haiyuan-ai-cc-mem": {
    "source": {
      "source": "github",
      "repo": "haiyuan-ai/cc-mem"
    },
    "installLocation": "/ABSOLUTE/PATH/TO/.claude/plugins/marketplaces/haiyuan-ai-cc-mem",
    "lastUpdated": "2026-03-07T00:00:00.000Z"
  }
}

Use absolute paths, do not use $HOME or ~. Examples:

• macOS: /Users/yourname/.claude/plugins/marketplaces/haiyuan-ai-cc-mem
• Linux/WSL: /home/yourname/.claude/plugins/marketplaces/haiyuan-ai-cc-mem

Step 3: Register Installed Plugin

Edit ~/.claude/plugins/installed_plugins.json, add to the plugins object: