Skip to main content
Glama

Portable, git-backed project-state for long-running AI work — in Claude Code, Cursor, or anything that speaks MCP.

It is not a memory tool. 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?"

Why it's built this way

  • State lives as plain markdown files, tracked by git. Git is the event log: history = git log, rollback = git revert, audit = git blame. Every claim is human-readable, diffable, and hand-editable. You review what the AI captured the same way you review generated code — as a diff, whenever you want. There is no approval gate at capture time.

  • Two storage modes, one API. Repo mode (<repo>/.continuity/, found by walking up from the working dir) suits editor/agent tools with a project cwd like Claude Code. Central mode (~/.continuity/projects/<name>/, named projects) suits tools with no project cwd like Claude Desktop — you just refer to a project by name.

  • The resume context is a deterministic projection of those files (no LLM in the read path) — frozen constraints, active decisions with the reasons they superseded older ones, rejected paths you shouldn't re-propose, open questions, and the next step.

  • Trust comes from honesty, not blind faith. Every claim carries confidence + provenance, so a fresh session knows what's confirmed vs. AI-inferred and calibrates instead of trusting everything.

See DESIGN.md for the full architecture and poc/ for the validation that motivated it.

Related MCP server: context-fabric

Install (as a Claude plugin)

Continuity is a Claude Code plugin, distributed as its own plugin marketplace — this repo is the marketplace. It runs everywhere Claude Code runs: the terminal, the desktop app, and web. In Claude Code:

/plugin marketplace add vikcena01/ai-continuity-plugin
/plugin install continuity@continuity-marketplace

That's it — the bundled MCP server, the continuity skill (auto-resume + auto-capture), the SessionStart hook, and the /resume /freeze /why commands all install together. dist/ is committed and dependency-free, so there's no build step on install.

Local development

npm install
npm run build   # typecheck + bundle to dist/
npm test        # build + 211 assertions across eleven suites

The loop (CLI)

continuity init "Build Snip, an internal URL shortener"
continuity record-decision "PostgreSQL is the source of truth" --body "ops knows it; volume is modest"
continuity reject "DynamoDB as primary store" --reason "KV overhead unjustified at our volume"
continuity record-constraint "Short codes are exactly 7-char base62" --body "printed in marketing + partner contract"
continuity freeze "7-char base62"     # lock an invariant — fuzzy: id OR title substring
continuity resume                     # <- the compact state a new session gets
continuity why "301"                  # <- what a decision replaced, and why
continuity resolve "8-char codes" --reject --reason "separate namespace"
continuity mission "..." --reason "why it changed"   # replacing one needs a reason
continuity list --query "base62"      # search id, title AND body
continuity list                       # ids are short: d1k3, c2m9, x1p4, ...
continuity log                        # the git-backed event log

Claims get short, typeable ids — a type prefix, a sequence number, and a two-char suffix: d1k3, c2m9, x1p4. The suffix is what makes concurrent work safe: without it, two developers who each record the 16th decision both write claims/d16.md and collide on merge. freeze / why / supersede / resolve accept an id or a title substring. State is written under claims/ and auto-committed to git on every change — but never auto-pushed, so resume warns you when captured commits are sitting unpushed.

Closing a claim

resolve is the only way a claim reaches a terminal status, and the reason is mandatory — a claim that just disappears teaches the next session nothing:

continuity resolve <id-or-text> --accept --reason "..."   # a parked conflict wins
continuity resolve <id-or-text> --reject --reason "..."   # it becomes a guardrail
continuity resolve <id-or-text> --close  --reason "..."   # a settled risk/question

Accepting a claim parked against a frozen one additionally requires --unfreeze. Freezing is the single human act in the model, so overriding it has to be a second deliberate one.

Use it in Claude Desktop (MCP)

Any host that speaks MCP but has no project cwd can use the MCP server with named projects. (Note: the Claude desktop app runs Claude Code inside it, so the full plugin — hooks, commands, skill — works there; this path is for plain-MCP hosts.) Build (npm run build), then add to claude_desktop_config.json:

{
  "mcpServers": {
    "continuity": {
      "command": "node",
      "args": ["/absolute/path/to/ai-continuity-plugin/dist/mcp.js"],
      "env": { "CONTINUITY_HOME": "/Users/you/.continuity/projects" }
    }
  }
}

Then in chat: "create a continuity project called snip" → create_project; "resume snip" → resume_context; the model records decisions/constraints/rejections as you go. A user-invokable resume prompt is the Desktop substitute for Claude Code's auto-resume hook. Tools: list_projects, create_project, resume_context, search_claims, record_decision, record_constraint, record_rejection, record_open, record_mission, capture, resolve_claim, freeze_claim, why.

As a Claude Code plugin (bonus)

This repo is also a Claude Code plugin (manifest at .claude-plugin/plugin.json). There, on top of the MCP server, you get things Claude Desktop can't do:

  • a SessionStart hook (hooks/hooks.json) that auto-injects resume_context on new / resumed / post-compact sessions — you never have to ask;

  • a Stop hook that runs an end-of-turn capture check, so decisions get recorded without anyone remembering to ask. Two independent guards (stop_hook_active plus a time throttle) make a loop impossible;

  • slash commands /resume, /freeze, /why.

The repo also ships .claude/settings.json, which registers the same hooks against its own committed dist/. A collaborator who just runs git clone therefore gets auto-resume and auto-capture without installing anything. Both hooks de-duplicate per session, so having the plugin installed and cloning the repo is harmless.

Claim format

Each .continuity/claims/<id>.md:

---
id: d4k7
type: decision            # decision | constraint | rejected_alternative | mission | milestone | question | next_action | ...
status: accepted          # accepted | frozen | superseded | rejected | open | needs_review | resolved | done
resolution:               # set by `resolve`: why this claim was closed
confidence: confirmed     # confirmed | tentative | unverified
provenance:
  origin: manual
  created: 2026-08-04T00:00:00.000Z
supersedes: []
superseded_by: null
depends_on: []
tags: []
---
Postgres is the primary datastore; a Redis read cache may come later.

The claim format (a contract)

Once anyone else's repo holds claims, the file format is a contract — so it carries a version:

---
schema: 1              # absent means 1
id: d16k3              # <type prefix><n><2-char suffix>; the suffix keeps concurrent clones from colliding
type: decision         # mission requirement decision constraint architecture milestone
                       # hypothesis experiment risk question next_action rejected_alternative
title: One crisp fact
status: accepted       # accepted active frozen open superseded invalidated rejected
                       # needs_review completed done resolved
confidence: confirmed  # unverified tentative confirmed
provenance: { origin: auto, created: ... }
supersedes: []
superseded_by: null
superseded_reason: ""  # why the replacement happened — travels with the claim
resolution: ""         # why it was closed, set by `continuity resolve`
---

Prose body. The reason, the context, whatever a future session needs.

Stability promise. A claim written by an older Continuity always reads: absent schema means 1, and older shapes migrate forward in memory without rewriting your files. A claim written by a newer Continuity is refused by name, loudly, rather than half-parsed — guessing at a shape we do not understand is how state degrades silently. continuity migrate rewrites files at the current schema when you want the version explicit on disk.

Reviewing what was captured

Capture is autonomous, so the safeguard is that you can see what it wrote:

continuity review            # semantic diff: what appeared, changed status, or was edited — and why
continuity review --accept   # mark it reviewed

It catches hand edits as well as tool writes, and the resume context tells you when changes are waiting.

Changelog

See CHANGELOG.md. Claim-file schema has remained 1 across every release.

Status

v1.5 — 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 suites (npm test).

Working today:

  • Autonomous capture, driven by a Stop hook at the end of each turn — not by the model remembering to.

  • A reconciler behind every batch capture: dedupe, lineage-preserving supersession, and a frozen-guard that parks anything contradicting a frozen claim as needs_review instead of applying it.

  • A resolve verb to close what the reconciler parks, and to close risks/questions once they are settled.

Known limits, tracked as claims in this repo's own .continuity/: the Stop-hook capture check is throttled to at most once per 10s, so a decision settled in a very fast exchange can still be missed (q3); and reliable status extraction from messy sessions remains the open technical risk (q2).

Listed on

The mark

A C drawn as one unbroken arc — the thread that survives between sessions — terminating in a node, a single captured claim. assets/icon.svg is the same mark on a rounded tile for an avatar or favicon; assets/logo-light.svg and assets/logo-dark.svg are the wordmark lockups, picked by prefers-color-scheme so both GitHub themes work.

License

MIT — see LICENSE. Copyright (c) 2026 Vikash.

Available Tools

13 tools
captureCapture batchA

Apply a BATCH of claim operations in one call, through the reconciler. Prefer this over several record_* calls when a turn produced more than one thing. The reconciler enforces what you should not be trusted to enforce yourself: a near-identical claim is skipped rather than duplicated, superseding archives the old claim with the reason instead of deleting it, and anything that would contradict a FROZEN claim is parked as needs_review for a human rather than applied. Append-only: nothing is removed, so the worst case is a claim you later supersede. Call resume_context first so you know existing ids and which claims are frozen.

Inputs: ops (required), project.

create_projectCreate projectA
Idempotent

Create or initialize a named project in the central store. Creates a directory and an initial git commit. Safe to call on a name that already exists: existing claims are left untouched, so it is effectively idempotent. For central mode only — hosts with no project directory. Inside a git repo, state belongs in the repo instead, which the continuity init CLI sets up.

Inputs: name (required), mission.

freeze_claimFreeze claimA
Idempotent

Mark a claim frozen: an invariant that must never change. This is the one deliberate lock in the model, so call it ONLY when the user explicitly asks for something to be locked — never on your own initiative. Once frozen, autonomous capture can no longer supersede it: a contradicting claim is parked for human review instead. Overriding it later requires resolve_claim with unfreeze, which is also an explicit human decision. Idempotent: freezing an already-frozen claim changes nothing.

Inputs: id (required), project.

list_projectsList projectsA
Read-onlyIdempotent

List the named projects in the central store (~/.continuity/projects). Read-only; writes nothing. Use it when the user names a project you have not seen, or to check whether central mode holds any state at all. Inside a repo that has .continuity/ this is usually irrelevant — that state is found from the working directory.

Inputs: no named parameters.

record_constraintRecord constraintA

Append a constraint that future work must respect. Same persistence as record_decision: one file, one commit, append-only. A constraint is a boundary rather than a choice — 'ids stay short and typeable' rather than 'we chose X'. Use freeze_claim only if the user wants it to become unchangeable.

Inputs: title (required), body, project.

record_decisionRecord decisionA

Append a decision the user has settled. Writes one markdown file plus a git commit; nothing is overwritten or removed, so a mistaken entry is corrected by superseding it rather than by editing. Capture autonomously as you observe it — no permission needed — but only for things a future session could not re-derive; skip restatements and progress narration. How the parameters divide the work: title survives every future projection intact, while body is clipped and, under a tight budget, dropped entirely — so anything that MUST reach a future session belongs in the title, not the body. confidence is rendered beside the claim, so 'tentative' visibly flags an inference a later session should verify before relying on it; leave it unset and it defaults to tentative. One behavioural warning: this writes STRAIGHT to the store and does not go through the reconciler, so it neither de-duplicates nor parks conflicts with frozen claims. Calling it twice with the same title creates two claims. Prefer capture when a turn produced more than one thing, or when the claim might duplicate or contradict an existing one.

Inputs: title (required), body, project, confidence.

record_missionRecord missionA
Idempotent

Set or replace the project's mission — the single line rendered at the top of every resume context, which is what a fresh session reads first. Creates it if none exists. Replacing an existing mission REQUIRES a reason, and supersedes rather than overwrites: the previous mission is archived as a claim with the reason, because a strategic pivot is exactly what someone asks 'why did this change?' about later. Setting the identical text is a no-op. Use this rather than capture with type mission; use create_project instead only when the project does not exist yet.

Inputs: title (required), body, reason, project.

record_openRecord open itemA

Append an open question, risk, milestone or next action. These are recorded with status 'open', so they keep surfacing in the resume context until closed with resolve_claim. Only one milestone and one next_action show at a time — recording a new next_action does not retire the old one, so supersede it via capture when direction changes.

Inputs: type (required), title (required), body, project.

record_rejectionRecord rejectionA

Append an alternative that was considered and rejected, together with the reason. It is then listed under 'Do NOT revisit' in every future resume context, which is the point: it stops the same idea being re-proposed months later. Append-only, like the other record_* tools.

Inputs: title (required), reason (required), project.

resolve_claimResolve claimA
Destructive

Close a claim, recording WHY. Two uses. (1) A claim parked as needs_review by the reconciler: action 'accept' makes it win, superseding whatever it conflicted with, or 'reject' turns it into a guardrail so it is never re-proposed. (2) An open risk, question or next_action that has been dealt with: action 'close' moves it to resolved, or done for a next_action or milestone. The reason is mandatory — a claim that simply vanishes from the resume context teaches a future session nothing. Nothing is deleted; closing archives. Accepting a claim parked against a FROZEN one additionally requires unfreeze, because breaking a frozen invariant is the user's decision: ask them first.

Inputs: claim (required), reason (required), action, project, +1 more.

resume_contextResume contextA
Read-onlyIdempotent

Return the current project state as a deterministic projection: mission, milestone, next step, frozen constraints, active decisions each annotated with the reason it replaced its predecessor, rejected alternatives, parked conflicts, and open questions. Read-only; writes nothing. Call this FIRST when starting work on an ongoing project and honour it — frozen items and rejected alternatives are authoritative, not suggestions. No model runs in this path, so the same state always yields the same text. Output is budgeted to roughly 16KB and states explicitly when it had to trim.

Inputs: project.

search_claimsSearch claimsA
Read-onlyIdempotent

List or search the claim set directly, bypassing the resume projection. Read-only. Returns one compact line per claim — status, type, id, title — without bodies, so it stays cheap to call; use why for one claim's detail. Reach for this when the projection is not enough: it is budgeted, so at tighter budgets bodies are dropped and open questions can be omitted entirely, and it never shows superseded, rejected or resolved claims at all. Those are exactly the ones worth checking before re-proposing something. With no arguments it lists everything, newest ids last; query matches case-insensitively against id, title AND body, since a claim is often remembered by a detail in its reasoning rather than its title.

Inputs: type, limit, query, status, +1 more.

whyWhyA
Read-onlyIdempotent

Explain a claim's history. Read-only; writes nothing. Returns the claim's current title and status, then one line per predecessor it replaced with the reason recorded at the time, then its closing reason if it has been resolved. A claim that replaced nothing says so explicitly ('supersedes nothing — original decision') rather than returning an empty result, so a blank answer always means the lookup failed, never that the history is empty. Accepts a claim id or a unique substring of its title; an ambiguous substring returns the candidate ids instead of guessing, and no match says so. Call it before re-opening anything that looks settled — the answer is often that it was already decided, reversed once, and why, which is the difference between a considered change and re-litigating a closed question.

Inputs: id (required), project.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 13 tools

    Disambiguation4/5

    Most tools target a distinct claim type or action, with record_constraint/decision/rejection/open/mission clearly scoped by their descriptions. The main ambiguities are record_open acting as a catch-all for four different item kinds (question, risk, milestone, next action) and capture partially overlapping with the individual record_* tools, though it is explicitly positioned as a batch reconciliation entry point.

    Naming Consistency4/5

    The record_* family gives a strong consistent prefix for append operations, and most other tools use verb_noun snake_case like resume_context, search_claims, freeze_claim, and list_projects. The outliers are 'capture' as a bare verb and 'why' as a question word, plus a slight singular/plural mismatch between freeze_claim, resolve_claim, and search_claims.

    Tool Count5/5

    At 13 tools, the surface is well-scoped for a persistent project-memory domain: every tool addresses a distinct part of the lifecycle including record, batch, query, freeze, resolve, explain, and project management. No tool feels redundant, and the count stays inside the ideal range.

    Completeness5/5

    The set covers the full lifecycle: project initialization, recording constraints, decisions, rejections, open items, and missions; batch capture with deduplication and conflict handling; freezing; resolving and archiving; and historical explanation. The append-only model deliberately omits destructive updates, but superseding via capture and unfreezing via resolve_claim fill those gaps without missing operations.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Provides AI coding assistants with persistent project memory by capturing development checkpoints during git commits, branch switches, and inactivity. It enables seamless task resumption through tools that retrieve session history, momentum, and synthesized re-entry briefings.
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to maintain Git-backed long-term project memory over MCP, supporting on-demand retrieval, curated writes, conflict-safe versioning, idempotency, and crash recovery so new sessions or machines can recover context and continue working.
      6
      Apache 2.0
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding assistants to persistently save, search, checkpoint, and restore project context across sessions, including decisions, progress, and file state. It supports shared channels, git-aware organization, and batch operations for long-running or parallel development workflows.
      243 npm
      MIT