At a Glance

npm install -g c0ntextkeeper && c0ntextkeeper setup

| | | |---|---| | 🤖 Automatic | Captures on both /compact and auto-compaction | | 🧠 AI-Powered Search | Ask naturally: What auth did I build last week? | | 🔍 Searchable | Find past solutions via 3 MCP tools or 30 CLI commands | | 🔒 Secure | Auto-redacts API keys, credentials, and PII | | ⚡ Fast | <10ms operations, zero performance impact | | 📊 Comprehensive | 7 hooks, 187 semantic patterns, 3 MCP tools | | ✅ Production Ready | 483 tests passing, TypeScript, MIT licensed |

The Problem

When Claude Code compacts your conversation, valuable context disappears:

• Solutions you discussed but haven't implemented
• Decisions about architecture and design patterns
• Problems you identified and their fixes
• Implementation details and code patterns

The cost? You waste 30+ minutes rediscovering solutions. You repeat past mistakes. You lose architectural consistency across sessions.

c0ntextKeeper preserves everything automatically—and makes it searchable.

Quick Start

# Install globally
npm install -g c0ntextkeeper

# Run setup (configures Claude Code hooks)
c0ntextkeeper setup

# Verify it's working
c0ntextkeeper status

That's it. c0ntextKeeper now automatically preserves your context.

Note: The CLI command is c0ntextkeeper (all lowercase with zero). The project name is c0ntextKeeper (capital K), but commands are always lowercase.

What This Enables

| Use Case | Without c0ntextKeeper | With c0ntextKeeper | |----------|----------------------|-------------------| | Starting a new feature | Re-explore old solutions from scratch | Ask: What auth did I implement? | | Debugging an error | Search files manually for past fixes | Ask: How did I fix this before? | | Architecture decisions | Forget why you chose a pattern | Instant access to reasoning | | Onboarding teammates | Explain everything verbally | Share searchable context archive |

Try it now:

c0ntextkeeper search "authentication"
c0ntextkeeper patterns --type command

Ask Claude Naturally

No regex. No exact keywords. Just ask:

What did I implement for authentication last week? How did I fix that database connection error? What commands do I run most often?

Claude uses c0ntextKeeper's 3 MCP tools automatically. Your queries are processed with word expansion, stop word filtering, and 60-day temporal decay scoring.

📖 Full MCP Guide →

Why c0ntextKeeper

| Feature | Description | |---------|-------------| | Zero Configuration | Install and immediately start preserving context | | Fully Automatic | Works with both /compact and auto-compaction | | Intelligent Extraction | 187 semantic patterns detect problems, solutions, decisions | | MCP Integration | 3 tools + 3 resources for instant context retrieval | | Security First | Automatic redaction of API keys, credentials, PII | | Production Ready | 483 tests passing, <10ms operations |

How It Compares

| Feature | c0ntextKeeper | Manual Notes | Other MCP Servers | |---------|:-------------:|:------------:|:-----------------:| | Automatic Capture | ✅ Both manual & auto | ❌ Manual only | ⚠️ Manual trigger | | Zero Configuration | ✅ Works out of box | ❌ Requires discipline | ❌ Complex setup | | 7 Claude Code Hooks | ✅ All events | ❌ N/A | ⚠️ Partial support | | 187 Semantic Patterns | ✅ Intelligent extraction | ❌ Manual categorization | ⚠️ Basic patterns | | Searchable Archive | ✅ MCP tools + CLI | ❌ File searching | ⚠️ Limited search | | Security Filtering | ✅ Auto-redact secrets | ❌ Manual redaction | ❌ None | | Performance | ✅ <10ms operations | N/A | ⚠️ Varies | | Test Coverage | ✅ 483 tests | N/A | ⚠️ Unknown |

How It Works

You work in Claude Code
        ↓
Context accumulates from conversations
        ↓
Compaction triggers (manual or automatic)
        ↓
c0ntextKeeper captures context via hooks
        ↓
Archive created with searchable index
        ↓
Retrieve via CLI or MCP tools

CLI Tools

c0ntextKeeper provides 30 CLI commands:

• 20 top-level commands (setup, status, doctor, search, etc.)
• 7 hook management subcommands (hooks list, hooks enable, hooks disable, etc.)
• 3 context management subcommands (context preview, context test, context configure)

# Quick health check
c0ntextkeeper status           # See automation status
c0ntextkeeper doctor           # Full diagnostics

# Search your history
c0ntextkeeper search "auth"    # Find past work
c0ntextkeeper patterns         # View recurring patterns

# Manage hooks
c0ntextkeeper hooks list       # See all 7 hooks
c0ntextkeeper hooks health     # Check data health

📖 Full CLI Reference with 30 Commands →

7 Supported Hooks

| Hook | Purpose | |------|---------| | PreCompact | Captures full context before compaction | | PostToolUse | Tracks tool execution patterns | | UserPromptSubmit | Preserves user prompts | | Stop | Captures Q&A exchanges | | Notification | Tracks notifications | | SessionStart | Records session metadata | | SessionEnd | Captures session summaries |

Search Algorithm Details

How the AI-powered search works under the hood:

| Feature | Description | |---------|-------------| | Word Expansion | "fix" matches "fixed", "fixes", "fixing" automatically | | Stop Word Filtering | Removes 32 noise words for precision | | Temporal Decay | Recent content scores higher (60-day half-life) | | Multi-Field Search | Searches problems, solutions, decisions, patterns | | Relevance Scoring | Weighted by field: problems (0.3), solutions (0.2), implementations (0.2) |

Tool Selection Guide

| You Want To... | Claude Uses | Example Query | |----------------|-------------|---------------| | Start a new feature | fetch_context | "What auth implementations exist?" | | Find specific work | search_archive | "Find Redis config in TypeScript files" | | Filter by date | search_archive | "What did I work on last week?" | | See your patterns | get_patterns | "What commands do I use most?" |

📖 Full MCP Guide → - Complete documentation with all parameters, examples, and troubleshooting.

MCP Tools

fetch_context

Retrieve relevant archived context for your current task:

"Use fetch_context to find previous authentication implementations"

Parameters:

• query (required) - What you're looking for
• limit - Maximum results (default: 5)
• minRelevance - Minimum score 0-1 (default: 0.5)
• scope - "session", "project", or "global"

search_archive

Search with advanced filters:

"Search the archive for Redis configuration decisions"

Parameters:

• query (required) - Search query
• filePattern - Filter by pattern (e.g., "*.ts")
• dateRange - Filter by date
• sortBy - "relevance", "date", or "frequency"

get_patterns

Identify recurring patterns and solutions:

"Show me recurring error patterns in this project"

Parameters:

• type - "code", "command", "architecture", or "all"
• minFrequency - Minimum occurrences
• limit - Maximum patterns to return

MCP Resources (Auto-Loaded)

c0ntextKeeper automatically loads context at session start - Claude begins each conversation already aware of your project history:

| Resource | Content | |----------|---------| | context://project/{name}/current | Recent sessions, decisions, implementations | | context://project/{name}/patterns | Your recurring patterns and workflows | | context://project/{name}/knowledge | Q&A knowledge base |

Full MCP documentation: MCP Guide - includes search algorithm details, configuration, and troubleshooting.

Prerequisites

• Node.js 18.0.0 or higher
• Claude Code CLI installed

Global Installation (Recommended)

npm install -g c0ntextkeeper
c0ntextkeeper setup

From Source

git clone https://github.com/Capnjbrown/c0ntextKeeper.git
cd c0ntextKeeper
npm install
npm run build
npm link

Verify Installation

c0ntextkeeper --version
c0ntextkeeper doctor

Core Commands

| Command | Description | |---------|-------------| | setup | Configure Claude Code hooks | | status | Check automation status | | doctor | Health diagnostics | | validate | Verify configuration |

Search & Discovery

| Command | Description | |---------|-------------| | search <query> | Search archived context | | patterns | View recurring patterns | | stats | Storage statistics |

Hook Management (7 subcommands)

| Command | Description | |---------|-------------| | hooks list | List all 7 hooks | | hooks health | Check hook data health | | hooks enable/disable | Toggle hooks | | hooks config | Configure hook settings | | hooks test | Test specific hook | | hooks stats | View hook statistics |

Context Management (3 subcommands)

| Command | Description | |---------|-------------| | context preview | Preview auto-load content | | context test | Test loading strategies | | context configure | Configuration wizard |

Storage & Maintenance

| Command | Description | |---------|-------------| | init | Initialize storage | | archive | Manual archive | | cleanup | Clean old archives | | rebuild-index | Rebuild search indexes | | migrate | Migrate old formats | | migrate:restore | Restore from backup |

Development

| Command | Description | |---------|-------------| | debug | Verbose debug mode | | benchmark | Performance testing | | test-hook | Test hook integration | | test-mcp | Test MCP tools | | server | Start MCP server |

📖 Full CLI Reference with examples →

Directory Structure

~/.c0ntextkeeper/
├── config.json                     # Global configuration
└── archive/
    └── projects/
        └── [project-name]/         # Human-readable names
            ├── sessions/           # Full session context
            ├── knowledge/          # Q&A pairs
            ├── patterns/           # Tool usage patterns
            ├── prompts/            # User prompts
            ├── notifications/      # Notifications
            ├── sessions-meta/      # Session lifecycle
            ├── search-index.json   # Inverted index
            └── index.json          # Project stats

Key Features

• Per-Session Files - Unique timestamped files per hook event
• Atomic Writes - No race conditions or data corruption
• JSON Format - Human-readable storage
• Hybrid Storage - Project-local or global (configurable)

Config File

Located at ~/.c0ntextkeeper/config.json:

{
  "storage": {
    "location": "global",
    "path": "~/.c0ntextkeeper"
  },
  "autoLoad": {
    "enabled": true,
    "strategy": "smart",
    "maxTokens": 50000
  },
  "hooks": {
    "precompact": { "enabled": true },
    "posttool": { "enabled": true },
    "stop": { "enabled": true },
    "userprompt": { "enabled": true },
    "notification": { "enabled": true },
    "sessionstart": { "enabled": true },
    "sessionend": { "enabled": true }
  }
}

Environment Variables

| Variable | Description | |----------|-------------| | CONTEXTKEEPER_HOME | Override storage location | | C0NTEXTKEEPER_DEBUG | Enable debug logging |

c0ntextKeeper automatically protects sensitive information:

Protected Data

• API Keys - OpenAI, Anthropic, AWS, GitHub
• Credentials - Passwords, secrets, connection strings
• Private Keys - RSA, SSH keys
• PII - Emails (masked), IPs, phone numbers
• Tokens - JWT, bearer, session tokens

Redaction Examples

API_KEY=sk-1234...    → API_KEY=[REDACTED]
[email protected]      → ***@example.com
192.168.1.100         → 192.168.***.***

Common Issues

Hook not triggering:

c0ntextkeeper hooks health
c0ntextkeeper doctor

Search returns no results:

c0ntextkeeper rebuild-index
c0ntextkeeper status

MCP tools not available:

1. Verify c0ntextkeeper-server is running
2. Check Claude Code MCP configuration
3. Run c0ntextkeeper doctor

Debug Mode

C0NTEXTKEEPER_DEBUG=true c0ntextkeeper status

Frequently Asked Questions

No. All operations average <10ms and hooks run asynchronously without blocking your workflow.

Yes. c0ntextKeeper automatically redacts API keys, credentials, PII, and other sensitive data before archiving. All archives are stored locally on your machine—nothing is sent externally.

No. Run c0ntextkeeper setup once and it works automatically forever. Zero ongoing maintenance required.

Archives are preserved indefinitely by default. Use c0ntextkeeper cleanup to remove old archives if needed, or c0ntextkeeper stats to see storage usage.

Currently, c0ntextKeeper is designed specifically for Claude Code's hook system. Support for other tools is being considered for future releases.

Documentation

| Topic | Location | |-------|----------| | Quick Start | docs/guides/quickstart.md | | User Guide | docs/guides/user-guide.md | | CLI Reference | docs/guides/cli-reference.md | | MCP Guide | docs/guides/mcp-guide.md | | Hooks Reference | docs/technical/hooks-reference.md | | MCP Tools (Technical) | docs/technical/mcp-tools.md | | Configuration | docs/technical/configuration.md | | Troubleshooting | docs/guides/troubleshooting.md |

Development

git clone https://github.com/Capnjbrown/c0ntextKeeper.git
cd c0ntextKeeper
npm install

npm run dev          # Development server
npm run build        # Production build
npm test             # Run tests (483 tests)
npm run lint         # Lint code
npm run typecheck    # Type check

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests (npm test)
5. Open a Pull Request

Star History

License

MIT License - see LICENSE for details.