[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-92713":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":15,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":16,"rankGlobal":9,"rankLanguage":9,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":18,"hasPages":18,"topics":20,"createdAt":9,"pushedAt":9,"updatedAt":27,"readmeContent":28,"aiSummary":29,"trendingCount":14,"starSnapshotCount":14,"syncStatus":13,"lastSyncTime":30,"discoverSource":31},92713,"contextvc","HaochengLu\u002Fcontextvc","HaochengLu","Git-native context control plane for AI coding agents",null,"Rust",120,1,2,0,46,45.5,"Apache License 2.0",false,"main",[21,22,23,24,25,26],"ai-agents","cli","context-engineering","git-native","mcp","rust","2026-07-22 04:02:06","# ContextVC (`ctx`)\n\nContextVC is a Git-native context control plane for AI coding agents.\n\nIt stores project rules, decisions, failure memory, how-tos, preferences, and code maps inside `.context\u002F`, then renders them into the native files used by Claude Code, Cursor, Codex, GitHub Copilot, Gemini, and Cline.\n\nIn one line: **agent memory becomes repo-level infrastructure that can be versioned, reviewed, merged, checked in CI, and enforced before risky actions.**\n\n![ContextVC 1-minute demo](assets\u002Fdemo.gif)\n\n## Why This Exists\n\nAI coding tools already have many places to put memory: prompts, rule files, chat summaries, vector stores, local preferences, and session logs.\n\nThose systems help an agent remember, but they usually do not answer the engineering questions a repository needs:\n\n- Did this memory go through review?\n- Does it follow the branch and the pull request?\n- Is the generated agent-facing file still in sync?\n- Is the rule stale because the source file changed?\n- Can a known-bad command be stopped before the agent runs it again?\n- Can CI prove the context is healthy?\n- Can two branches merge context without silently losing semantics?\n\nContextVC is built for those questions.\n\n## Install\n\nInstall the tagged release from GitHub:\n\n```bash\ncargo install --locked --git https:\u002F\u002Fgithub.com\u002FHaochengLu\u002Fcontextvc.git --tag v0.1.0\nctx --help\n```\n\nOr clone and install from source:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FHaochengLu\u002Fcontextvc.git\ncd contextvc\ncargo install --locked --path .\nctx --help\n```\n\nYou need the Rust stable toolchain. If Rust is not installed, install it from [rustup.rs](https:\u002F\u002Frustup.rs\u002F).\n\n## Quick Start\n\nInside any repository:\n\n```bash\nctx init --install-hooks\nctx status\nctx check\n```\n\nThis creates `.context\u002F`, renders agent-facing files, installs local hook adapters, and writes MCP configuration.\n\nGenerated files can include:\n\n```text\n.context\u002F\nAGENTS.md\nCLAUDE.md\n.cursor\u002Frules\u002F*.mdc\n.github\u002Fcopilot-instructions.md\nGEMINI.md\n.cline\u002Fmemory-bank\u002Fcontextvc.md\n.mcp.json\n```\n\nContextVC is local-first:\n\n- no API key required\n- no hosted service required\n- no source upload\n- local stdio MCP server\n- long-lived context lives in the repo and can be reviewed with Git\n\n## What Traditional Memory Management Does Not Have\n\nTraditional 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.\n\n| Traditional memory usually lacks | ContextVC provides |\n| --- | --- |\n| Memory does not follow the repo | Durable objects live in `.context\u002Fobjects\u002F` and move with branches, pull requests, clones, and forks |\n| Memory can be recalled but not enforced | `ctx precheck`, MCP, and hooks return `warn`, `ask`, or `block` before risky actions |\n| Memory writes skip review | Runtime learning creates proposals; `ctx review accept` is required before formalizing them |\n| Memory does not know when code changed | file\u002Fsource bindings store hashes; `ctx check` detects stale bindings |\n| Every agent owns a separate rule file | `.context\u002F` is the source of truth; `ctx render` compiles native files for many agents |\n| Retrieval cannot prove generated files are current | `render.lock`, schema validation, and managed-block drift checks run in CI |\n| Branch conflicts are vague | `ctx merge` and `ctx harvest` persist semantic conflicts; conflicted constraints fail closed |\n| Rollback is manual | `ctx blame`, `ctx diff`, and `ctx revert` use Git semantics for context objects |\n| Clients can spoof event identity | MCP `context_log` rebuilds server-owned fields and redacts secrets |\n| It is hard to measure whether memory prevents repeats | RepeatBench verifies that known failures are caught while safe actions still pass |\n\n## Core Features\n\n| Capability | Command \u002F file | What it does |\n| --- | --- | --- |\n| Initialize context | `ctx init` | Creates `.context\u002F`, projection files, and lockfile |\n| Adopt existing rules | `ctx adopt` | Imports `AGENTS.md`, `CLAUDE.md`, and Cursor rules into objects |\n| Backfill codemap | `ctx backfill` | Builds codemap objects from Git history |\n| Render projections | `ctx render` | Generates native agent files while preserving human-written regions |\n| CI guard | `ctx check` | Detects projection drift, stale bindings, schema errors, conflicts, and bad events |\n| Project brief | `ctx brief` | Prints concise context for an agent task |\n| MCP runtime | `ctx serve-mcp` | Serves local tools for brief, search, precheck, log, propose, and status |\n| Hook install | `ctx install` | Installs Claude \u002F Cursor \u002F Codex hooks, MCP config, and Git hooks |\n| Pre-action gate | `ctx precheck` | Checks commands or paths against constraints and failure memory |\n| Gate snooze | `ctx snooze` | Locally suppresses a specific gate hit |\n| Failure writeback | `ctx log-event` \u002F `ctx hook stop` | Distills runtime failures into proposals |\n| Human review | `ctx review` | Accepts or rejects proposals before they enter the source of truth |\n| Staleness check | `ctx verify` | Validates object bindings against current file\u002Fsource hashes |\n| Semantic merge | `ctx merge` \u002F `ctx harvest` | Preserves semantic conflicts and blocks conflicted constraints |\n| Git history | `ctx log` \u002F `ctx blame` \u002F `ctx diff` \u002F `ctx revert` | Tracks and rolls back context objects with Git semantics |\n| Diagnostics | `ctx doctor` | Checks config, lockfile, hooks, schema, and possible secrets |\n| Schema | `ctx schema` | Prints or writes the OCL object JSON Schema |\n| Benchmark | `ctx repeatbench` | Runs repeat-failure gate scenarios |\n\n## Architecture\n\n![ContextVC architecture](assets\u002Farchitecture.png)\n\nThe same diagram is also available in [docs\u002Farchitecture.mmd](docs\u002Farchitecture.mmd).\n\n## Three Real Workflows\n\n### Workflow 1: Bootstrap an Existing Repository\n\nUse this when a repository already has agent rules spread across files.\n\n```bash\ncd your-repo\nctx init --skip-adopt\nctx adopt\nctx render --force\nctx check\nctx install all\n```\n\nWhat happens:\n\n- existing agent instructions are imported into `.context\u002Fobjects\u002F`\n- native projection files are regenerated from one source of truth\n- hooks and MCP config are installed locally\n- CI can run `ctx check` to detect drift\n\n### Workflow 2: Stop a Repeated Bad Command\n\nCreate a constraint once and let all supported agents consume it.\n\n```bash\nmkdir -p .context\u002Fobjects\u002Fconstraints\ncat > .context\u002Fobjects\u002Fconstraints\u002Fuse-pnpm.md \u003C\u003C'EOF'\n---\nid: c-usepnpm\ntype: constraint\ntitle: Use pnpm\nscope: [\"**\"]\nstatus: active\ntrust: human\nconfidence: 1.0\nevidence: []\nbindings:\n  - kind: command\n    pattern: \"npm install\"\n    enforcement: block\ncreated: init\n---\n\nUse `pnpm install`; do not run `npm install` in this repository.\nEOF\n\nctx render --force\nctx check\nctx precheck --command \"npm install\"\n```\n\nExpected behavior:\n\n- `ctx render` projects the constraint into agent-native files\n- `ctx precheck` returns a blocking gate hit for `npm install`\n- safe commands that do not match the constraint are not blocked\n\n### Workflow 3: Turn a Failure Into Reviewed Memory\n\nUse the review queue instead of letting runtime learning silently mutate the source of truth.\n\n```bash\nctx log-event \\\n  --event-type failure \\\n  --payload '{\"target\":\"src\u002Fparser.rs\",\"action\":\"cargo test parser\",\"outcome\":\"failed\",\"evidence\":\"parser fixture failed\"}'\n\nctx hook stop\nctx review list\nctx review accept \u003Cproposal-id>\nctx render --force\nctx check\n```\n\nWhat happens:\n\n- the failure event is appended locally\n- a proposal is generated from repeated or meaningful evidence\n- a human accepts or rejects it\n- accepted memory becomes a formal `.context\u002Fobjects\u002F` file\n- projections and lockfile are regenerated\n\n## RepeatBench Results\n\nRepeatBench checks whether known repeat failures are caught by the gate while false-positive actions remain safe.\n\nLatest committed summary: [benchmarks\u002Frepeatbench\u002Fresults\u002Flatest-summary.json](benchmarks\u002Frepeatbench\u002Fresults\u002Flatest-summary.json)\n\n```json\n{\n  \"scenarios\": 1,\n  \"gate_hits\": 1,\n  \"misses\": 0,\n  \"repeat_failure_rate\": 0.0\n}\n```\n\nRaw per-scenario output is stored at [benchmarks\u002Frepeatbench\u002Fresults\u002Flatest.json](benchmarks\u002Frepeatbench\u002Fresults\u002Flatest.json).\n\nRun it yourself:\n\n```bash\nctx repeatbench --json\nctx repeatbench --json --output benchmarks\u002Frepeatbench\u002Fresults\u002Flatest.json\n```\n\n## CI\n\nUse ContextVC as a repository health check:\n\n```bash\nctx check\n```\n\nThe included GitHub Actions workflow runs:\n\n```bash\ncargo fmt --all -- --check\ncargo test --all --locked\ncargo build --release --locked\ntarget\u002Frelease\u002Fctx repeatbench --json\ngit diff --check\n```\n\n`ctx check` fails on:\n\n- missing `.context\u002FVERSION` or `render.lock`\n- object changes that were not rendered\n- edited managed blocks\n- stale file\u002Fsource bindings\n- invalid object schema fields\n- corrupt event JSONL\n- conflicted constraints\n\n## Object Model\n\nContextVC stores durable knowledge as Markdown files with OCL frontmatter.\n\nObject types:\n\n- `constraint`: hard or soft rule, often enforced by path or command\n- `decision`: architectural or implementation decision\n- `failure`: repeated failure or known pitfall\n- `howto`: task recipe\n- `codemap`: important source area or high-churn file\n- `preference`: style, testing, formatting, or workflow preference\n\nManaged projection files use `ctx:begin` \u002F `ctx:end` blocks. Human-written text outside those blocks is preserved by `ctx render`.\n\n## Local Security Boundaries\n\n- ContextVC reads and writes the current repository and local config files.\n- Events and objects are redacted for common secret patterns before saving.\n- MCP `context_log` does not trust client-supplied actor\u002Fid fields.\n- Binding paths reject absolute paths, parent traversal, out-of-repo symlinks, and oversized files.\n- Review accept uses preflight checks and render rollback.\n- Conflicted constraints fail closed.\n\n## Development\n\n```bash\ncargo fmt --all\ncargo test --all\ncargo build --release\ntarget\u002Frelease\u002Fctx repeatbench --json --output target\u002Frepeatbench-results.jsonl\ngit diff --check\n```\n\n## Release\n\nThe first public tag is `v0.1.0`.\n\n```bash\ngit fetch --tags\ngit checkout v0.1.0\ncargo install --locked --path .\n```\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE).\n","ContextVC 是一个面向 AI 编程代理的 Git 原生上下文管控平面，将项目规则、决策记录、失败复盘、操作指南、偏好配置和代码映射等结构化上下文持久化存储于仓库内的 `.context\u002F` 目录，并自动渲染为 Claude Code、Cursor、GitHub Copilot 等主流 AI 编程工具可识别的本地配置文件。其核心特点是将 AI 代理的‘记忆’转化为可版本化、可审查、可合并、可 CI 验证且支持预执行拦截（warn\u002Fask\u002Fblock）的仓库基础设施。适用于需要在团队协作、多分支开发与 CI\u002FCD 流程中统一管控 AI 编程行为合规性与一致性的工程场景。","2026-07-10 02:30:15","CREATED_QUERY"]