# Continuity

> Durable project-state manager for AI sessions that tracks decisions, constraints, and rejected paths in git-backed markdown files across Claude Code, Cursor, and any MCP host.

Continuity is an open-source Claude Code plugin and MCP server that preserves project state across AI sessions — not as a conversation log, but as a structured, git-versioned record of decisions, constraints, rejected alternatives, and open questions. Built by Vikash and released under the MIT license, it targets developers running long-running AI-assisted projects in Claude Code, Cursor, or any tool that speaks MCP.

## What It Is

Continuity solves a specific problem: when a new AI session starts, the model has no memory of what was decided, what was ruled out, or why. Rather than replaying chat history, Continuity maintains a set of plain markdown "claim" files under `.continuity/claims/` (or a named central directory for tools without a project working directory). Each claim carries a type, status, confidence level, and provenance, and the entire store is committed to git on every change — making `git log` the event log, `git revert` the rollback mechanism, and `git blame` the audit trail.

The README explicitly distinguishes Continuity from memory tools: *"A memory tool answers 'what did we talk about?' Continuity answers a different question: 'what is true about this project now, and what must not be touched?'"*

## How the Two Storage Modes Work

Continuity ships two storage modes behind a single API:

- **Repo mode** — state lives at `<repo>/.continuity/`, discovered by walking up from the working directory. Suited for editor and agent tools like Claude Code that have a project `cwd`.
- **Central mode** — state lives at `~/.continuity/projects/<name>/`, addressed by project name. Suited for hosts like plain Claude Desktop that have no project `cwd`.

Both modes expose the same CLI verbs and MCP tools, so the workflow is identical regardless of host.

## The Claim Model and CLI

Claims are short, typeable IDs (e.g., `d1k3`, `c2m9`) composed of a type prefix, sequence number, and two-character collision-safe suffix. The suffix prevents merge conflicts when two developers record the same-numbered claim concurrently. Key CLI verbs include:

- `continuity init` — start a project with a mission statement
- `continuity record-decision / record-constraint / reject` — capture state
- `continuity freeze` — lock an invariant; overriding a frozen claim requires a second deliberate `--unfreeze`
- `continuity resume` — emit the compact state a new session receives (a deterministic projection, no LLM in the read path)
- `continuity why` — show what a decision replaced and why
- `continuity resolve` — the only way to close a claim; reason is mandatory
- `continuity review` — semantic diff of what was autonomously captured, with `--accept` to mark it reviewed

## Claude Code Plugin Capabilities

When installed as a Claude Code plugin, Continuity adds capabilities beyond the base MCP server:

- A **SessionStart hook** that auto-injects `resume_context` on new, resumed, or post-compact sessions — no manual prompt needed
- A **Stop hook** that runs an end-of-turn capture check so decisions are recorded without anyone remembering to ask; two independent guards prevent hook loops
- Slash commands `/resume`, `/freeze`, `/why`

The repo also ships `.claude/settings.json` registering these hooks against the committed `dist/`, so a collaborator who clones the repo gets auto-resume and auto-capture without installing anything separately.

## Architecture and Trust Model

The resume context is a deterministic projection of the claim files — no LLM is involved in the read path. Every claim carries `confidence` (confirmed / tentative / unverified) and `provenance` (manual vs. auto-captured), so a fresh session can calibrate trust rather than accepting all state blindly. A reconciler behind every batch capture handles deduplication, lineage-preserving supersession, and a frozen-guard that parks contradicting claims as `needs_review` instead of silently applying them.

The claim-file schema is versioned (`schema: 1`). Older claims without a schema field are treated as version 1 and migrated forward in memory without rewriting files. Claims written by a newer, unknown schema version are refused loudly rather than half-parsed.

## Current Status: v1.5

The README describes the current release as **v1.5**, featuring a deterministic core, CLI, MCP server, Claude Code plugin, versioned claim files, collision-safe IDs, fuzzy lookup, a budgeted resume projection, git-backed event log, and 211 assertions across eleven test suites. The repository was last pushed in September 2026. Known open limits tracked as claims in the repo's own `.continuity/` include: the Stop-hook capture check is throttled to at most once per 10 seconds (so a decision settled in a very fast exchange can be missed), and reliable status extraction from messy sessions remains an open technical risk.

## Features
- Git-backed project state in plain markdown files
- Two storage modes: repo mode and central/named-project mode
- Deterministic resume context projection (no LLM in read path)
- Claim confidence and provenance tracking
- Frozen invariants with deliberate unfreeze requirement
- Autonomous capture via Claude Code Stop hook
- SessionStart hook for auto-resume on new/resumed/post-compact sessions
- Slash commands: /resume, /freeze, /why
- Collision-safe short claim IDs with type prefix and suffix
- Reconciler with deduplication and lineage-preserving supersession
- Versioned claim-file schema with forward migration
- CLI verbs: init, record-decision, record-constraint, reject, freeze, resume, why, resolve, review
- MCP server with named-project support for Claude Desktop
- Zero runtime dependencies
- 211 assertions across eleven test suites

## Integrations
Claude Code, Claude Desktop, Cursor, Any MCP-compatible host, Git

## Platforms
CLI, API

## Pricing
Open Source

## Version
1.5

## Links
- Website: https://github.com/vikcena01/ai-continuity-plugin
- Documentation: https://github.com/vikcena01/ai-continuity-plugin/blob/main/DESIGN.md
- Repository: https://github.com/vikcena01/ai-continuity-plugin
- EveryDev.ai: https://www.everydev.ai/tools/ai-continuity-plugin