@exero1/claudecontext 0.1.0

package/README.md

@@ -0,0 +1,286 @@
+# 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.
+
+```bash
+npm install -g claudecontext
+```
+
+**Per-project setup** (run inside your project directory):
+
+```bash
+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:**
+
+```bash
+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](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:
+
+```markdown
+<!-- 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:
+
+```bash
+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:
+
+```json
+[
+  {
+    "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:
+
+```json
+{
+  "mcpServers": {
+    "claudecontext": {
+      "command": "npx",
+      "args": ["--node-options=--no-warnings", "claudecontext-mcp"],
+      "env": {
+        "CLAUDECONTEXT_PROJECT_ROOT": "${workspaceFolder}"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 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).
+
+```bash
+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](.cursorrules) for full coding guidelines
+- See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for system design
+
+Phase tracker: [docs/PHASES.md](docs/PHASES.md)
+API reference: [docs/API.md](docs/API.md)
+Product requirements: [docs/PRD.md](docs/PRD.md)
+
+**License:** MIT

package/dist/installer/install.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * ClaudeContext installer.
+ *
+ * Commands:
+ *   claudecontext init [--project-root <path>]   Install in a project
+ *   claudecontext remove                          Remove hooks/config (preserves state.db)
+ *   claudecontext migrate                         Migrate schema for upgrades
+ *   claudecontext doctor                          Check installation health
+ */
+export {};
+//# sourceMappingURL=install.d.ts.map

package/dist/installer/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../installer/install.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG"}