ClaudeContext

Persistent memory for Claude Code. When the context window compacts, your session state survives.

ClaudeContext gives Claude a two-part memory system: a hierarchical level cache that guarantees deterministic context from day one, and an association graph that discovers related context you never knew to ask for. Together, they solve the compaction problem without requiring a larger context window.

The Problem

Claude Code sessions are bounded. When the context window fills up, Claude Code compacts — summarizing recent history and starting fresh. That compaction event destroys:

• Which files you were editing and why
• What decisions were made two hours ago
• Which architectural patterns you established earlier
• The thread of reasoning connecting your current branch to past work

Every compaction forces you to manually re-explain your intent. On long-running features, multi-branch projects, or codebases with deep architectural context, that overhead compounds into hours of lost productivity per week.

ClaudeContext intercepts that compaction, stores the important state, and rebuilds it automatically at the start of every session.

Quick Install

Prerequisites: Node.js 22 or later, Claude Code installed.

npm install -g @exero1/claudecontext

Per-project setup (run inside your project directory):

claudecontext init

This runs an interactive wizard that:

• Detects your project structure and identifies main subsystems (auth, api, db, etc.)
• Generates a populated CLAUDE.md with your project description and conventions
• Creates .claudecontext/state.db (SQLite, WAL mode)
• Installs four hook scripts into .claude/hooks/
• Writes .mcp.json pointing to the MCP server via npx
• Creates a tasks/ directory for per-branch task files

Global install for all projects:

claudecontext global-install

Registers ClaudeContext as a global MCP server across all Claude Code projects.

How It Works

ClaudeContext combines two systems that work together to give Claude the right context at the right time.

System 1: Hierarchical Cache Levels

Five levels of storage, each with a defined budget and purpose:

| Level | Name | Storage | Token Budget | Purpose | |-------|------|---------|-------------|---------| | L0 | Working set | .claudecontext/l0.log | 3,000 | Recent tool calls, errors, file writes — append-only, recovered on restart | | L1 | Task cache | tasks/<branch-slug>.md | 8,000 | Current task: goal, decisions, files touched, open questions | | L2 | Area docs | docs/context/<area>.md | 10,000 | Subsystem architecture, API contracts — matched by file path | | L3 | Project cache | CLAUDE.md | — | Rules, conventions, invariants — NOT in bundle (auto-loaded by Claude Code) | | L4 | Decision archive | .claudecontext/archive/ | 2,000 | Historical decisions, session summaries |

At session start, context_get_bundle assembles these levels into a single markdown document injected as additionalContext. Unused budget from any level flows to the graph discovery budget.

System 2: Association Graph

A SQLite-backed directed graph that learns which files and concepts belong together. Graph edges are created and reinforced automatically during normal coding:

| Edge Type | Direction | How Created | V1/V2 | |-----------|-----------|-------------|-------| | imports | file → file | AST analysis (acorn) on every file write | V1 | | subsystem_of | file → area | File path matches area glob pattern | V1 | | co_modified | file ↔ file | Two files written in the same session | V1 | | always_with | file ↔ file | Statistical co-occurrence across 3+ sessions | V2 | | informed_by | task → archive | Keyword match to archived decisions | V2 | | caused_by | task → archive | Error in session matches archived decision | V2 | | breaks_with | file → file | File change causes test failure for another file | V2 |

During bundle assembly, the graph is traversed starting from the files listed in your active task (L1). In V1, direct neighbors (1 hop) are loaded in weight-descending order until the token budget is exhausted. In V2, a priority-queue BFS expands up to 3 hops.

Edge weights start at 1.0 and decay exponentially (half-life ~70 days). Reinforcement adds 0.1, capped at 1.0. Edges below weight 0.1 and unreinforced for 90 days are pruned.

Day 1: graph is empty — bundle is levels only. Fully functional immediately. Day 30: graph has hundreds of weighted edges — bundle discovers context you never knew to ask for.

MCP Tools Reference

Claude Code can call these six tools directly. The CLAUDE.md generated by claudecontext init instructs Claude to use them automatically.

| Tool | Read-Only | Purpose | |------|-----------|---------| | context_detect_task | Yes | Infer active task from git branch and database | | context_get_bundle | Yes | Build unified context bundle: levels + graph-discovered files | | context_update_task | No | Patch the active task file (L1) with new decisions or files | | context_update_project | No | Patch CLAUDE.md (L3) with project-wide conventions | | context_search_codebase | Yes | Search indexed files by query, boosted by graph neighbor relationships | | context_status | Yes | Show token breakdown per level, edge counts, active task, graph age |

Full parameter reference: docs/API.md

CLI Reference

The claudecontext-cli binary is used internally by hooks and is also useful for inspection:

| Command | Purpose | |---------|---------| | claudecontext init | Interactive project setup wizard | | claudecontext global-install | Register as global MCP server | | claudecontext remove | Remove hooks and .mcp.json (preserves state DB) | | claudecontext migrate | Apply schema migrations for version upgrades | | claudecontext doctor | Check Node version, DB integrity, hook permissions, .mcp.json | | claudecontext-cli status | Print current task, edge counts, file index size | | claudecontext-cli graph-inspect <file> | Show all incoming and outgoing edges for a file | | claudecontext-cli gate-check <input> | Test gate rules against a command string | | claudecontext-cli ingest-diff <file...> | Record file touches and create/reinforce edges | | claudecontext-cli hydrate | Build bundle and output additionalContext JSON |

Bundle Format

When context_get_bundle runs, it returns a markdown document with this structure:

<!-- CLAUDECONTEXT BUNDLE (L0=847 L1=3.2k L2=6.1k L4=1.8k Graph=4.3k | Total=16.2k) -->
<!-- Task: feature-add-auth | Branch: feature/add-auth | Graph depth: 1 hop(s) -->

---

## Task Context (L1 — tasks/feature-add-auth.md)
<!-- CONTENT START -->
# Task: feature-add-auth
**Branch:** feature/add-auth
**Created:** 2026-02-20T09:00:00.000Z
**Status:** active

## Goal
Add JWT-based authentication to the API layer.

## Files touched
- src/auth.ts
- src/db/users.ts

## Decisions
- Use RS256 over HS256 for cross-service token validation
<!-- CONTENT END -->

---

## Working Set (L0 — recent activity)
<!-- CONTENT START -->
[2026-02-20T10:12:00Z] WRITE src/auth.ts
[2026-02-20T10:13:45Z] WRITE src/db/users.ts
[2026-02-20T10:14:01Z] Tool error in context_get_bundle: ...
<!-- CONTENT END -->

---

## Area Documentation (L2)
<!-- CONTENT START -->
### auth
[Contents of docs/context/auth.md — subsystem architecture, API contracts]
<!-- CONTENT END -->

---

## Decision Archive (L4)
<!-- CONTENT START -->
**[2026-02-15] feature-jwt-refresh:** Decided to store refresh tokens in HttpOnly cookies, not localStorage, due to XSS risk discovered in security review.
<!-- CONTENT END -->

---

## Graph-Discovered Context
### `src/auth/jwt_handler.ts` [via imports from src/auth.ts (weight=0.91)]
<!-- FILE CONTENT START -->
[contents of jwt_handler.ts]
<!-- FILE CONTENT END -->

---

<!-- END CLAUDECONTEXT BUNDLE -->

All file content is wrapped in <!-- FILE CONTENT START --> delimiters to prevent prompt injection from file contents.

Configuration

CLAUDECONTEXT_PROJECT_ROOT

By default, ClaudeContext uses the current working directory as the project root. Override it with:

export CLAUDECONTEXT_PROJECT_ROOT=/path/to/your/project

This is useful when running Claude Code from a directory other than your project root, or when managing multiple projects.

areas.json

The file .claudecontext/areas.json defines your project's subsystems. Generated by claudecontext init, but editable manually:

[
  {
    "name": "auth",
    "globs": ["src/auth/**", "src/middleware/auth*"],
    "docPath": "docs/context/auth.md"
  },
  {
    "name": "database",
    "globs": ["src/db/**", "src/models/**"],
    "docPath": "docs/context/database.md"
  }
]

When a file matches a glob, a subsystem_of edge is created linking the file to its area. The area's docPath is loaded as L2 area documentation whenever that area is relevant to the active task.

.mcp.json

Created by claudecontext init. Uses npx — never absolute paths, so it works across machines and npm updates:

{
  "mcpServers": {
    "claudecontext": {
      "command": "npx",
      "args": ["--yes", "-p", "@exero1/claudecontext", "claudecontext-mcp"],
      "env": {
        "CLAUDECONTEXT_PROJECT_ROOT": "/path/to/your/project",
        "NODE_OPTIONS": "--no-warnings"
      }
    }
  }
}

Prerequisites

• Node.js 22 or later — required for node:sqlite (built-in SQLite, no native addon)
• Claude Code — the MCP server connects via stdio transport; requires Claude Code as the host
• Git (optional) — branch detection uses simple-git; falls back to default task if not a git repo

Contributing

ClaudeContext is built with TypeScript + Node.js ESM. Every import must use .js extensions (NodeNext module resolution).

git clone https://github.com/your-org/claudecontext
cd claudecontext
npm install
npm run build
npm run test

Before submitting a PR:

• Run npm run build && npm run typecheck && npm run test
• Add unit tests for any new functions
• Never console.log() — use process.stderr.write() in the MCP server, process.stdout.write() in the CLI
• See .cursorrules for full coding guidelines
• See docs/ARCHITECTURE.md for system design

Phase tracker: docs/PHASES.md API reference: docs/API.md Product requirements: docs/PRD.md

License: MIT