A complete context management ecosystem for Claude Code that provides:
- Smart Forking - Semantic search to find and fork relevant historical sessions
- Session Registry - Track all sessions with summaries, topics, and continuation chains
- Skill Architecture - Meta-skill system for context preservation between sessions
- Semantic Memory - Store and recall learnings across all projects
- Pre/Post Compact Hooks - Automatic transcript capture and session handoff
Claude Code sessions lose context when compacted or ended. This toolkit gives Claude persistent memory across sessions:
- Before: Start fresh every session, repeat context, lose project knowledge
- After: Fork from relevant sessions, skills preserve domain knowledge, learnings auto-inject
┌─────────────────────────────────────────────────────────────────────────────────┐
│ CLAUDE CODE SESSION LIFECYCLE │
└─────────────────────────────────────────────────────────────────────────────────┘
┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ START │────▶│ WORK │────▶│ COMPACTION │────▶│ END │
│ SESSION │ │ (prompts) │ │ (context │ │ SESSION │
└────┬─────┘ └──────┬───────┘ │ shrinks) │ └──────┬───────┘
│ │ └──────┬───────┘ │
▼ ▼ ▼ ▼
┌─────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Hook: │ │ Hook: │ │ Hook: │ │ Hook: │
│ session │ │ user-prompt │ │ pre-compact │ │ stop │
│ -start │ │ -submit │ │ │ │ │
└────┬────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │ │
▼ ▼ ▼ ▼
┌───────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Register │ │ Query │ │ Save │ │ Finalize │
│ in │ │ memories, │ │ transcript │ │ session, │
│ registry │ │ inject │ │ for handoff │ │ update │
│ │ │ context │ │ │ │ registry │
└───────────┘ └─────────────┘ └─────────────┘ └─────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ SEMANTIC MEMORY SYSTEM │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────┐
│ /learn │
│ (user stores │
│ knowledge) │
└────────┬────────┘
│
▼
┌──────────────┐ ┌─────────────────────┐ ┌──────────────┐
│ │ │ │ │ │
│ Transcript │───────────▶│ SEMANTIC MEMORY │◀───────────│ Prompts │
│ Chunks │ embed │ DAEMON │ query │ (user) │
│ │ │ (Flask + SQLite) │ │ │
└──────────────┘ │ │ └──────────────┘
│ ┌───────────────┐ │
│ │ Embeddings │ │
│ │ (Nomic/ │ │
│ │ MiniLM) │ │
│ └───────────────┘ │
│ │
│ ┌───────────────┐ │
│ │ Memories DB │ │
│ │ (solutions, │ │
│ │ gotchas, │ │
│ │ patterns) │ │
│ └───────────────┘ │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ <recalled- │
│ learnings> │
│ injected into │
│ Claude context │
└─────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ SMART FORKING WORKFLOW │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────┐
│ /fork-detect │
│ "implement │
│ auth system" │
└────────┬────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 1. Embed query │─────▶│ 2. Search all │─────▶│ 3. Rank by │
│ with model │ │ session │ │ similarity │
│ │ │ chunks │ │ (cosine) │
└─────────────────┘ └─────────────────┘ └────────┬────────┘
│
┌─────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ COMPOSITE RELEVANCY SCORE │
│ ═════════════════════════════ │
│ │
│ score = (best_similarity × 0.40) ← Strongest chunk match │
│ + (avg_similarity × 0.20) ← Overall topic alignment │
│ + (chunk_ratio × 0.05) ← Breadth of matching content │
│ + (recency × 0.25) ← How recent the session is │
│ + (chain_quality × 0.10) ← Position in continuation chain │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ RECENCY DECAY │ CHAIN QUALITY │ │
│ │ ───────────── │ ───────────── │ │
│ │ < 1 day → 1.0 │ Chain head → 1.0 │ │
│ │ 1-7 days → 0.8 │ Chain middle → 0.7 │ │
│ │ 7-30 days → 0.5 │ Chain tail → 0.5 │ │
│ │ 30-90 days→ 0.3 │ Unknown → 0.3 │ │
│ │ > 90 days → 0.1 │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ CHUNK DOWNWEIGHTING (applied before scoring) │ │
│ │ ───────────────────────────────────────────── │ │
│ │ Bare command invocations (short + <command-name> + no │ │
│ │ substance) are multiplied by 0.5x to deprioritize │ │
│ │ testing/usage sessions over implementation sessions. │ │
│ │ │ │
│ │ Example: "## User\n<command-name>/fork</command-name>" │ │
│ │ → similarity × 0.5 (downweighted) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ Threshold: minSimilarity = 0.40 (falls back to 0.30 if no hits) │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 📊 Results: │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ [0.72] Session abc123 - "Built OAuth flow for dashboard" │ │
│ │ [0.65] Session def456 - "Added JWT token handling" │ │
│ │ [0.58] Session ghi789 - "User registration with validation" │ │
│ └─────────────────────────────────────────────────────────────┘ │
└──────────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────┐
│ /prime-fork abc123 │
│ Load session │
│ context into │
│ current chat │
└────────┬────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ FORK CONTEXT PRIMING (/prime-fork skill) │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────┐
│ 1. DETECT TYPE │
│ ────────────── │
│ COMPACTED? │───┬─── Yes ──▶ Continue to Step 2
│ (structured │ │
│ summary only) │ └─── No ───▶ Skip to Step 4 (full context available)
└─────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ 2. GAP ANALYSIS (Compacted sessions only) │
│ ────────────────────────────────────────── │
│ │
│ CLEAR (remember well): "Built OAuth flow, used passport.js" │
│ FUZZY (need specifics): "Fixed some CORS error... details?" │
│ GAPS (likely missing): "Exact config values, error messages" │
│ QUANTITATIVE UNKNOWNS: "Port numbers, timeout values, paths" │
│ │
└─────────────────────────────────────────────────────────────────────┘
│
│ (If gaps exist and transcript available)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 3. TRANSCRIPT RECOVERY (2 parallel agents) │
│ ────────────────────────────────────────── │
│ │
│ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ AGENT 1 │ │ AGENT 2 │ │
│ │ Files & Problems │ │ Decisions & Reqs │ │
│ │ ──────────────── │ │ ──────────────── │ │
│ │ • File paths changed │ │ • Technical choices │ │
│ │ • Code snippets │ │ • Why decided X vs Y │ │
│ │ • Exact error msgs │ │ • User quotes/prefs │ │
│ │ • What fixed it │ │ • Constraints given │ │
│ └──────────────────────┘ └──────────────────────┘ │
│ │ │ │
│ └──────────┬───────────────┘ │
│ ▼ │
│ Merge results │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 4. CONTEXT REPORT │
│ ───────────────── │
│ │
│ ## Fork Context Loaded │
│ **Source:** abc123 **Type:** COMPACTED **Recovery:** Completed │
│ │
│ ### Key Knowledge Available │
│ • Built OAuth flow using passport.js │
│ • Configured CORS for cross-origin requests │
│ │
│ ### Files Modified: src/auth/*, src/middleware/cors.ts │
│ ### Problems Solved: CORS 403 error, session persistence │
│ ### Key Decisions: passport.js over Auth0 (simpler, self-hosted) │
│ │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 5. READY FOR USER │
│ ───────────────── │
│ │
│ ⚠️ CONTEXT PRESERVATION, NOT TASK CONTINUATION │
│ │
│ • Do NOT auto-execute any "next steps" from original session │
│ • Do NOT assume original work is incomplete │
│ • WAIT for user to provide new direction │
│ │
│ > "Context loaded from forked session. What would you like │
│ > to work on?" │
│ │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ SESSION CONTINUATION CHAINS │
└─────────────────────────────────────────────────────────────────────────────────┘
Session A Session B Session C
(original) (resumed A) (resumed B)
┌──────────┐ ┌──────────┐ ┌──────────┐
│ │ │ │ │ │
│ Work on │──────────▶│ Continue │──────────▶│ Complete │
│ feature │ /resume │ feature │ /resume │ feature │
│ │ │ │ │ │
└──────────┘ └──────────┘ └──────────┘
│ │ │
└──────────────────────┴──────────────────────┘
│
▼
┌─────────────────┐
│ Session Registry│
│ tracks chain: │
│ A → B → C │
│ (continued_as/ │
│ continued_from)│
└─────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ SKILL SYSTEM │
└─────────────────────────────────────────────────────────────────────────────────┘
/create-skill Claude loads
│ skill on context
▼ │
┌─────────────────┐ ┌───────┴───────┐
│ Analyze session │ │ │
│ Extract: │ ▼ │
│ • Decisions │ ┌─────────────────────────────────┐ │
│ • Patterns │──────▶│ .claude/skills/my-project/ │─────┘
│ • Solutions │ │ ├── SKILL.md (entry point) │
│ • Architecture │ │ ├── Reference/ │
└─────────────────┘ │ │ ├── skill-maintenance.md │
│ │ ├── architecture.md │
/update-skill │ │ └── gotchas.md │
│ │ └── Templates/ │
▼ │ └── component.md │
┌─────────────────┐ └─────────────────────────────────┘
│ Read existing │ │
│ Classify change │ │
│ • NEW │ ▼
│ • UPDATE │ ┌─────────────────────────────────┐
│ • CORRECTION │ │ Skill survives compaction! │
│ Mark superseded │ │ New sessions auto-load project │
│ Add changelog │ │ knowledge from SKILL.md │
└─────────────────┘ └─────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ COMPLETE DATA FLOW │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Claude │ │ Hooks │ │ Daemon │ │ Storage │
│ Code │ │ (bash/ps1) │ │ (Python) │ │ (SQLite) │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │ │
│ SessionStart │ │ │
│────────────────▶│ Register │ │
│ │────────────────▶│ Store │
│ │ │────────────────▶│
│ │ │ │
│ UserPrompt │ │ │
│────────────────▶│ Query │ │
│ │────────────────▶│ Search │
│ │ │────────────────▶│
│ │◀────────────────│◀────────────────│
│◀────────────────│ Inject memories│ │
│ │ │ │
│ PreCompact │ │ │
│────────────────▶│ Save handoff │ │
│ │────────────────▶│ Index chunks │
│ │ │────────────────▶│
│ │ │ │
│ /fork-detect │ │ │
│────────────────▶│ Embed + search │ │
│ │────────────────▶│ Similarity │
│ │ │────────────────▶│
│ │◀────────────────│◀────────────────│
│◀────────────────│ Return matches │ │
│ │ │ │
▼ ▼ ▼ ▼
- Node.js 18+
- Python 3.8+
- Claude Code CLI installed
# Clone the repository
git clone https://github.com/zaccook/claude-context-kit.git
cd claude-context-kit
# Run the installer
node install.jsThe installer will:
- Detect your platform (Windows/Mac/Linux)
- Check GPU availability and select optimal embedding model
- Install hooks, commands, and skills
- Set up the semantic memory daemon
- Merge with any existing Claude Code hooks (non-destructive)
Find semantically relevant sessions from your history:
/fork-detect implement user authentication
📊 Found 5 relevant sessions:
1. [0.72] Session abc123 - "Built OAuth flow for dashboard"
2. [0.65] Session def456 - "Added JWT token handling"
...
To fork: /prime-fork abc123
Automatic tracking of all Claude Code sessions:
- Session summaries and topics (generated by Claude)
- Continuation chains (knows when sessions resumed others)
- Categories for filtering (feature, bugfix, refactor, etc.)
A local Flask server that:
- Stores learnings as embeddings (solutions, gotchas, patterns)
- Auto-injects relevant memories when you start working
- GPU-accelerated with CUDA/Metal, CPU fallback available
Persistent project knowledge that survives compaction:
.claude/skills/my-project/
├── SKILL.md # Core knowledge (~400 lines)
├── Reference/
│ ├── implementation-status.md
│ └── architecture.md
└── Templates/
└── component-template.md
Create skills with /create-skill and update with /update-skill.
Pre-configured hooks for Claude Code events:
| Hook | Purpose |
|---|---|
session-start |
Register session, inject relevant memories |
pre-compact |
Capture transcript before compaction |
user-prompt-submit |
Inject semantic memories into context |
stop |
Save session state for continuation |
| Command | Purpose |
|---|---|
/fork-detect <task> |
Find semantically similar sessions |
/prime-fork <session-id> |
Load context from a session |
/resume <session-id> |
Continue from a session |
/post-compact |
Preserve context after compaction |
/sync-registry |
Update session summaries |
/learn |
Store learnings to semantic memory |
/create-skill |
Create new project skill |
/update-skill |
Update existing skill |
/migrate-sessions |
Import existing sessions |
Config file: ~/.claude/context-kit/config.json
{
"embedding": {
"model": "nomic-ai/nomic-embed-text-v1.5",
"dimensions": 768,
"device": "cuda"
},
"daemon": {
"port": 8741,
"autoStart": true
},
"forkDetect": {
"minSimilarity": 0.40,
"maxResults": 20
}
}The installer auto-selects based on hardware:
| Hardware | Model | Dimensions | Performance |
|---|---|---|---|
| NVIDIA GPU (4GB+ VRAM) | Nomic Embed v1.5 | 768 | Fast |
| Apple Silicon | Nomic Embed v1.5 | 768 | Fast |
| CPU Only | MiniLM-L6-v2 | 384 | Good |
The semantic search automatically deprioritizes "bare command invocation" chunks to surface implementation content over testing/usage sessions.
The Problem: When searching for "modify the /fork command", raw semantic similarity would rank sessions that ran /fork higher than sessions that implemented /fork, because the word "fork" appears more frequently in testing sessions.
The Solution: Chunks are analyzed and downweighted if they meet ALL THREE conditions:
- Short (< 300 characters)
- Contains command tags (
<command-name>) - Lacks substance (no code blocks, thinking blocks, or paragraphs > 100 chars)
┌─────────────────────────────────────────────────────────────────────────────────┐
│ SURGICAL NEGATIVE BOOSTING │
│ ═══════════════════════════ │
│ │
│ if (isShort && hasCommandTags && !hasSubstance): │
│ adjusted_similarity = raw_similarity × 0.5 │
│ else: │
│ adjusted_similarity = raw_similarity │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ BEFORE │ AFTER │ │
│ │ ────── │ ───── │ │
│ │ 1. b006dbc7 (0.74) testing │ 1. d64cee2c (0.69) implementation │ │
│ │ 2. e7939068 (0.71) testing │ 2. 050ec18b (0.67) implementation │ │
│ │ 3. c7bcbcd7 (0.71) testing │ 3. 23aedbbe (0.66) implementation │ │
│ │ 4. d64cee2c (0.69) impl │ 4. b006dbc7 (0.65) different chunk │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
│ Key: Testing sessions with bare command invocations are deprioritized, │
│ surfacing sessions with actual implementation discussion. │
└─────────────────────────────────────────────────────────────────────────────────┘
Configurable Constants (in server.py):
COMMAND_CHUNK_MAX_LENGTH = 300 # Max chars for "short" classification
SUBSTANCE_MIN_PARAGRAPH = 100 # Min chars for a paragraph to count as substance
COMMAND_INVOCATION_WEIGHT = 0.5 # Multiplier for bare command chunksProtected Content: The following are never downweighted:
- Code blocks (``` fences)
- Thinking blocks (
<details>tags) - Long paragraphs (> 100 chars after stripping
<command-args>)
~/.claude/
├── hooks/ # Event hooks
├── commands/ # Slash commands
├── skills/ # Project knowledge
├── memory/
│ ├── daemon/ # Semantic memory server
│ └── semantic-memory.db # Embeddings database
├── session-registry.json # Session tracking
└── context-kit/
└── config.json # Configuration
If you have existing Claude Code sessions:
/migrate-sessions
This will:
- Scan existing transcripts
- Register them in the session registry
- Generate summaries
- Index for semantic search
- Quick Start Guide
- Architecture Overview
- Commands Reference
- Skills Guide
- Configuration Options
- VS Code Automation
- Troubleshooting
See CONTRIBUTING.md for guidelines.
MIT License - see LICENSE for details.
Built with ❤️ for the Claude Code community