c0ntextKeeper

The only automatic context preservation system for Claude Code
Zero configuration. Works out of the box. Never lose work to compaction again.

Quick Start • Use Cases • AI Search • How It Works • Docs

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.

Installation Options

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

All CLI Commands (30 total)

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 →

Storage Architecture

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)

Configuration

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

Security

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]
user@example.com      → ***@example.com
192.168.1.100         → 192.168.***.***

Troubleshooting

Common Issues

Hook not triggering:

c0ntextkeeper hooks health
c0ntextkeeper doctor

Search returns no results:

c0ntextkeeper rebuild-index
c0ntextkeeper status

MCP tools not available:

Verify c0ntextkeeper-server is running
Check Claude Code MCP configuration
Run c0ntextkeeper doctor

Debug Mode

C0NTEXTKEEPER_DEBUG=true c0ntextkeeper status

Frequently Asked Questions

Does this slow down Claude Code?

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

Is my data secure?

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.

Do I need to configure anything after installation?

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

What happens to my old archives?

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

Can I use this with other AI tools?

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
CI/CD & Contributing	docs/development/CI-CD-GUIDE.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.

Fork the repository
Create a feature branch
Make your changes
Run tests (npm test)
Open a Pull Request

Star History

License

MIT License - see LICENSE for details.

Made for the Claude Code community!

_SmB

Name		Name	Last commit message	Last commit date
Latest commit History 57 Commits
.claude/plugins/c0ntextkeeper-agents		.claude/plugins/c0ntextkeeper-agents
.github		.github
docs		docs
examples		examples
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.js		eslint.config.js
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
setup-env.sh		setup-env.sh
tsconfig.json		tsconfig.json

License

Capnjbrown/c0ntextKeeper

Folders and files

Latest commit

History

Repository files navigation

c0ntextKeeper

At a Glance

The Problem

Quick Start

What This Enables

Ask Claude Naturally

Why c0ntextKeeper

How It Compares

How It Works

CLI Tools

7 Supported Hooks

Search Algorithm Details

Tool Selection Guide

MCP Tools

fetch_context

search_archive

get_patterns

MCP Resources (Auto-Loaded)

Prerequisites

Global Installation (Recommended)

From Source

Verify Installation

Core Commands

Search & Discovery

Hook Management (7 subcommands)

Context Management (3 subcommands)

Storage & Maintenance

Development

Directory Structure

Key Features

Config File

Environment Variables

Protected Data

Redaction Examples

Common Issues

Debug Mode

Frequently Asked Questions

Documentation

Development

Contributing

Star History

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

`fetch_context`

`search_archive`

`get_patterns`

Packages