ContextVC (ctx)

ContextVC is a Git-native context control plane for AI coding agents.

It stores project rules, decisions, failure memory, how-tos, preferences, and code maps inside .context/, then renders them into the native files used by Claude Code, Cursor, Codex, GitHub Copilot, Gemini, and Cline.

In one line: agent memory becomes repo-level infrastructure that can be versioned, reviewed, merged, checked in CI, and enforced before risky actions.

Why This Exists

AI coding tools already have many places to put memory: prompts, rule files, chat summaries, vector stores, local preferences, and session logs.

Those systems help an agent remember, but they usually do not answer the engineering questions a repository needs:

• Did this memory go through review?
• Does it follow the branch and the pull request?
• Is the generated agent-facing file still in sync?
• Is the rule stale because the source file changed?
• Can a known-bad command be stopped before the agent runs it again?
• Can CI prove the context is healthy?
• Can two branches merge context without silently losing semantics?

ContextVC is built for those questions.

Install

Install the tagged release from GitHub:

cargo install --locked --git https://github.com/HaochengLu/contextvc.git --tag v0.1.0
ctx --help

Or clone and install from source:

git clone https://github.com/HaochengLu/contextvc.git
cd contextvc
cargo install --locked --path .
ctx --help

You need the Rust stable toolchain. If Rust is not installed, install it from rustup.rs.

Quick Start

Inside any repository:

ctx init --install-hooks
ctx status
ctx check

This creates .context/, renders agent-facing files, installs local hook adapters, and writes MCP configuration.

Generated files can include:

.context/
AGENTS.md
CLAUDE.md
.cursor/rules/*.mdc
.github/copilot-instructions.md
GEMINI.md
.cline/memory-bank/contextvc.md
.mcp.json

ContextVC is local-first:

• no API key required
• no hosted service required
• no source upload
• local stdio MCP server
• long-lived context lives in the repo and can be reviewed with Git

What Traditional Memory Management Does Not Have

Traditional memory management usually treats memory as a summary, a vector record, a user preference, or a private agent history. ContextVC treats memory as a repository control plane.

Traditional memory usually lacks	ContextVC provides
Memory does not follow the repo	Durable objects live in .context/objects/ and move with branches, pull requests, clones, and forks
Memory can be recalled but not enforced	ctx precheck, MCP, and hooks return warn, ask, or block before risky actions
Memory writes skip review	Runtime learning creates proposals; ctx review accept is required before formalizing them
Memory does not know when code changed	file/source bindings store hashes; ctx check detects stale bindings
Every agent owns a separate rule file	.context/ is the source of truth; ctx render compiles native files for many agents
Retrieval cannot prove generated files are current	render.lock, schema validation, and managed-block drift checks run in CI
Branch conflicts are vague	ctx merge and ctx harvest persist semantic conflicts; conflicted constraints fail closed
Rollback is manual	ctx blame, ctx diff, and ctx revert use Git semantics for context objects
Clients can spoof event identity	MCP context_log rebuilds server-owned fields and redacts secrets
It is hard to measure whether memory prevents repeats	RepeatBench verifies that known failures are caught while safe actions still pass

Core Features

Capability	Command / file	What it does
Initialize context	ctx init	Creates .context/, projection files, and lockfile
Adopt existing rules	ctx adopt	Imports AGENTS.md, CLAUDE.md, and Cursor rules into objects
Backfill codemap	ctx backfill	Builds codemap objects from Git history
Render projections	ctx render	Generates native agent files while preserving human-written regions
CI guard	ctx check	Detects projection drift, stale bindings, schema errors, conflicts, and bad events
Project brief	ctx brief	Prints concise context for an agent task
MCP runtime	ctx serve-mcp	Serves local tools for brief, search, precheck, log, propose, and status
Hook install	ctx install	Installs Claude / Cursor / Codex hooks, MCP config, and Git hooks
Pre-action gate	ctx precheck	Checks commands or paths against constraints and failure memory
Gate snooze	ctx snooze	Locally suppresses a specific gate hit
Failure writeback	ctx log-event / ctx hook stop	Distills runtime failures into proposals
Human review	ctx review	Accepts or rejects proposals before they enter the source of truth
Staleness check	ctx verify	Validates object bindings against current file/source hashes
Semantic merge	ctx merge / ctx harvest	Preserves semantic conflicts and blocks conflicted constraints
Git history	ctx log / ctx blame / ctx diff / ctx revert	Tracks and rolls back context objects with Git semantics
Diagnostics	ctx doctor	Checks config, lockfile, hooks, schema, and possible secrets
Schema	ctx schema	Prints or writes the OCL object JSON Schema
Benchmark	ctx repeatbench	Runs repeat-failure gate scenarios

Architecture

The same diagram is also available in docs/architecture.mmd.

Three Real Workflows

Workflow 1: Bootstrap an Existing Repository

Use this when a repository already has agent rules spread across files.

cd your-repo
ctx init --skip-adopt
ctx adopt
ctx render --force
ctx check
ctx install all

What happens:

• existing agent instructions are imported into .context/objects/
• native projection files are regenerated from one source of truth
• hooks and MCP config are installed locally
• CI can run ctx check to detect drift

Workflow 2: Stop a Repeated Bad Command

Create a constraint once and let all supported agents consume it.

mkdir -p .context/objects/constraints
cat > .context/objects/constraints/use-pnpm.md <<'EOF'
---
id: c-usepnpm
type: constraint
title: Use pnpm
scope: ["**"]
status: active
trust: human
confidence: 1.0
evidence: []
bindings:
  - kind: command
    pattern: "npm install"
    enforcement: block
created: init
---

Use `pnpm install`; do not run `npm install` in this repository.
EOF

ctx render --force
ctx check
ctx precheck --command "npm install"

Expected behavior:

• ctx render projects the constraint into agent-native files
• ctx precheck returns a blocking gate hit for npm install
• safe commands that do not match the constraint are not blocked

Workflow 3: Turn a Failure Into Reviewed Memory

Use the review queue instead of letting runtime learning silently mutate the source of truth.

ctx log-event \
  --event-type failure \
  --payload '{"target":"src/parser.rs","action":"cargo test parser","outcome":"failed","evidence":"parser fixture failed"}'

ctx hook stop
ctx review list
ctx review accept <proposal-id>
ctx render --force
ctx check

What happens:

• the failure event is appended locally
• a proposal is generated from repeated or meaningful evidence
• a human accepts or rejects it
• accepted memory becomes a formal .context/objects/ file
• projections and lockfile are regenerated

RepeatBench Results

RepeatBench checks whether known repeat failures are caught by the gate while false-positive actions remain safe.

Latest committed summary: benchmarks/repeatbench/results/latest-summary.json

{
  "scenarios": 1,
  "gate_hits": 1,
  "misses": 0,
  "repeat_failure_rate": 0.0
}

Raw per-scenario output is stored at benchmarks/repeatbench/results/latest.json.

Run it yourself:

ctx repeatbench --json
ctx repeatbench --json --output benchmarks/repeatbench/results/latest.json

CI

Use ContextVC as a repository health check:

ctx check

The included GitHub Actions workflow runs:

cargo fmt --all -- --check
cargo test --all --locked
cargo build --release --locked
target/release/ctx repeatbench --json
git diff --check

ctx check fails on:

• missing .context/VERSION or render.lock
• object changes that were not rendered
• edited managed blocks
• stale file/source bindings
• invalid object schema fields
• corrupt event JSONL
• conflicted constraints

Object Model

ContextVC stores durable knowledge as Markdown files with OCL frontmatter.

Object types:

• constraint: hard or soft rule, often enforced by path or command
• decision: architectural or implementation decision
• failure: repeated failure or known pitfall
• howto: task recipe
• codemap: important source area or high-churn file
• preference: style, testing, formatting, or workflow preference

Managed projection files use ctx:begin / ctx:end blocks. Human-written text outside those blocks is preserved by ctx render.

Local Security Boundaries

• ContextVC reads and writes the current repository and local config files.
• Events and objects are redacted for common secret patterns before saving.
• MCP context_log does not trust client-supplied actor/id fields.
• Binding paths reject absolute paths, parent traversal, out-of-repo symlinks, and oversized files.
• Review accept uses preflight checks and render rollback.
• Conflicted constraints fail closed.

Development

cargo fmt --all
cargo test --all
cargo build --release
target/release/ctx repeatbench --json --output target/repeatbench-results.jsonl
git diff --check

Release

The first public tag is v0.1.0.

git fetch --tags
git checkout v0.1.0
cargo install --locked --path .

License

Apache-2.0. See LICENSE.