# CVC — Frequently Asked Questions (FAQ)

> **60+ answers to everything developers, teams, and enterprises ask about Cognitive Version Control.**

---

## Table of Contents

- [General Questions](#general-questions)
- [Installation & Setup](#installation--setup)
- [How CVC Works](#how-cvc-works)
- [The CVC Agent](#the-cvc-agent)
- [Context & Memory](#context--memory)
- [Branching, Merging & Time Travel](#branching-merging--time-travel)
- [Providers & Models](#providers--models)
- [IDE & Tool Integration](#ide--tool-integration)
- [MCP Server](#mcp-server)
- [Proxy Mode](#proxy-mode)
- [Cost & Performance](#cost--performance)
- [Security & Privacy](#security--privacy)
- [Enterprise & Teams](#enterprise--teams)
- [Technical Architecture](#technical-architecture)
- [Comparisons](#comparisons)
- [Troubleshooting](#troubleshooting)
- [Roadmap & Future](#roadmap--future)

---

## General Questions

### 1. What is CVC?

**CVC (Cognitive Version Control)** is an open-source middleware that gives AI coding agents a memory that actually works. Think of it as **Git, but for the AI's brain instead of your source code**. It saves, branches, rewinds, and merges the AI agent's entire cognitive state — every thought, every decision, every conversation turn.

### 2. Why is it called "Cognitive Version Control"?

Because it applies the same version control concepts that transformed software development (Git) to AI cognition. Instead of versioning lines of code, CVC versions the AI's context — its "cognitive state." The word "cognitive" reflects that we're managing thinking, not code.

### 3. What does "Time Machine for AI Agents" mean?

It means your AI agent can travel through its own history. Made a wrong decision 30 minutes ago? Rewind. Want to try a risky approach? Branch — if it fails, go back. Crash after 2 hours of work? Restore from the last checkpoint. The AI's memory is no longer ephemeral.

### 4. Is CVC free?

Yes. CVC is free and open-source under the MIT license. You still pay for the LLM provider's API costs (Anthropic, OpenAI, Google), but CVC itself is completely free. With Ollama, you can even run CVC with zero API costs using local models.

### 5. Who created CVC?

CVC was created by the Jaimeena team. It is developed openly on GitHub at [github.com/mannuking/cvc](https://github.com/mannuking/cvc) and published on PyPI as `tm-ai`.

### 6. What problem does CVC solve?

AI agents are brilliant for about 20 minutes. Then they forget what they fixed, contradict their own plans, and loop on the same error. Research shows that after ~60% context window utilization, reasoning quality drops off a cliff. CVC solves this with cognitive state management — save before degradation, rewind when needed, branch to avoid context pollution.

### 7. Does CVC replace my current AI tool?

**No.** CVC is middleware, not a replacement. It wraps around the tools you already love — Claude Code, Cursor, Copilot, Aider, VS Code — transparently. One configuration change and your existing tool gets time-travel capabilities. Zero workflow disruption.

### 8. Can I use CVC without any AI tool?

Yes! CVC ships with its own built-in AI coding agent called **Sofia**. Just type `cvc` in your terminal and you get a full-featured AI assistant with 17 tools, 31 slash commands, and built-in time travel.

### 9. What programming languages does CVC support?

CVC is language-agnostic. It works with any programming language because it versions the AI's conversation context, not the code itself. The built-in agent can work with Python, JavaScript, TypeScript, Rust, Go, Java, C++, and any other language your chosen LLM supports.

### 10. Is CVC production-ready?

CVC is currently in Alpha (v1.8.x) and is actively used in real-world development workflows. The core versioning engine is stable and reliable. Enterprise features like cloud sync are on the roadmap.

---

## Installation & Setup

### 11. How do I install CVC?

```bash
# Recommended: one-line installer
# macOS / Linux / WSL
curl -fsSL https://jaimeena.com/cvc/install.sh | bash

# Windows PowerShell
irm https://jaimeena.com/cvc/install.ps1 | iex

# Or via pip
pip install "tm-ai[all]"

# Or via uv (faster)
uv tool install "tm-ai[all]"
```

### 12. What are the system requirements?

- **Python 3.11+** (3.12 or 3.13 recommended)
- Any operating system: Windows, macOS, Linux, WSL
- An API key from Anthropic, OpenAI, or Google (or Ollama for free local models)
- Git (optional, for VCS bridge features)

### 13. How do I set up CVC for the first time?

Just type `cvc` in your terminal. The interactive setup wizard will guide you through picking your provider, model, and API key. Or run `cvc setup` explicitly.

### 14. How do I update CVC?

```bash
pip install -U tm-ai
# or
uv tool upgrade tm-ai
```

### 15. Can I install CVC for a specific provider only?

Yes. Install only the provider you need:
```bash
pip install "tm-ai[anthropic]"   # Claude only
pip install "tm-ai[openai]"      # GPT only
pip install "tm-ai[google]"      # Gemini only
pip install tm-ai                # Core only (Ollama works with core)
```

### 16. Do I need Docker?

No. CVC runs natively on your system with zero Docker requirements. Everything is Python.

### 17. How do I verify my installation works?

```bash
cvc doctor
```

This health check verifies Python version, configuration, `.cvc/` directory, Git, API keys, and Ollama connectivity.

---

## How CVC Works

### 18. How does CVC save the AI's context?

Every conversation turn (user message + AI response) is captured and stored as a compressed, content-addressed blob. These blobs are linked together in a Merkle DAG (Directed Acyclic Graph) — the same cryptographic structure Git uses. Each "cognitive commit" is a snapshot of the AI's entire context at that moment.

### 19. What is a "cognitive commit"?

A cognitive commit is a snapshot of the AI agent's full context — every message, every decision, every conversation turn — saved at a specific point in time. It's the AI equivalent of a `git commit`, but instead of saving code, it saves the AI's thinking.

### 20. What is the Merkle DAG?

A Merkle DAG (Directed Acyclic Graph) is a data structure where each node is identified by a cryptographic hash of its content. Each commit points to its parent, forming an auditable chain. This means:
- You cannot tamper with history without detection
- Every snapshot is deduplicated automatically
- The entire history is cryptographically verifiable

### 21. Where is my data stored?

Everything is stored locally in a `.cvc/` directory inside your project folder. No cloud, no remote servers, no telemetry. Your AI's reasoning stays on your machine.

### 22. What's inside the `.cvc/` folder?

```
.cvc/
├── cvc.db              # SQLite database (commit graph, branches, metadata)
├── objects/            # Compressed context snapshots (CAS blobs)
├── context_cache.json  # Crash recovery cache
├── chroma/             # Optional vector embeddings
├── pageindex/          # Optional document indices
├── lessons.md          # Agent self-improvement patterns
├── memory.md           # Cross-session memory
├── settings.toml       # User preferences
└── agents/             # Custom agent definitions
```

### 23. Is the `.cvc/` folder large?

No. Context snapshots are Zstandard-compressed and delta-encoded against anchor commits. A typical project's `.cvc/` folder stays under 50MB even after weeks of heavy usage.

### 24. Can I delete `.cvc/` and start fresh?

Yes. Deleting `.cvc/` removes all CVC history for that project. Run `cvc init` to start fresh. Your code is never affected.

---

## The CVC Agent

### 25. What is Sofia?

Sofia is CVC's built-in AI coding assistant. She runs in your terminal and combines the capabilities of a modern AI coding agent (like Claude Code or Cursor) with built-in version control for the conversation. She has 17 tools, 31 slash commands, and full time-travel capabilities.

### 26. How do I launch the CVC agent?

```bash
cvc           # Quickest way
cvc agent     # Explicit
```

### 27. What can the CVC agent do?

- Read, write, and edit files with intelligent find-and-replace
- Run shell commands (with trust-based permission system)
- Search files and directories
- Search the web for documentation and error solutions
- Analyze images (screenshots, UI mockups)
- Save cognitive checkpoints, branch, rewind, merge
- Search past conversations semantically
- Track costs per session and per turn
- Spawn specialized sub-agents for security, AI/ML, UI, data, and orchestration tasks

### 28. What are the sub-agents?

CVC has 7 built-in sub-agents that the main agent can delegate to:

| Agent | Purpose |
|---|---|
| **Explore** | Fast codebase exploration (read-only, cheapest model) |
| **Plan** | Produce implementation plans without modifying anything |
| **Security** | Vulnerability scanning, OWASP Top 10, CVE auditing |
| **AI** | AI/ML engineering, LLM integration, RAG pipelines |
| **UI** | UI/UX design, frontend development, accessibility |
| **Data** | Analytics, SQL, ETL, visualization |
| **Orchestrator** | Coordinate multiple agents for complex tasks |

### 29. Can I create custom agents?

Yes! Create `.cvc/agents/<name>/agent.md` with YAML frontmatter defining the agent's name, description, tools, max_turns, and system prompt.

### 30. What is the trust mode system?

Three modes control how the agent handles potentially risky operations:

- **`strict`** — Always prompt before risky commands
- **`smart`** (default) — Auto-allow safe commands (ls, cat, npm test), prompt for risky ones (rm, sudo, git push)
- **`yolo`** — Trust everything without prompting

Toggle with `/trust` or `/trust strict|smart|yolo`.

---

## Context & Memory

### 31. Does CVC remember previous sessions?

Yes. CVC has a multi-layered memory system:
1. **Auto-restore** — loads the last session on startup
2. **Persistent cache** — survives crashes (`.cvc/context_cache.json`)
3. **Session memory** — summarized and stored in `~/.cvc/memory.md`
4. **Lessons learned** — patterns from corrections stored in `.cvc/lessons.md`

### 32. What is the persistent cache?

Every message is saved to `.cvc/context_cache.json` as it arrives. If CVC crashes or is force-quit before a commit, the cache provides full recovery on next startup. It's your safety net.

### 33. How does auto-commit work?

The agent automatically saves a cognitive checkpoint every N assistant turns:
- **Agent mode**: Every 2 turns (configurable via `CVC_AGENT_AUTO_COMMIT`)
- **Proxy Time Machine mode**: Every 1 turn
- **Proxy normal mode**: Every 3 turns

### 34. What is context autopilot?

CVC automatically manages context window utilization:
- **40%** — Progressive thinning (remove less important early context)
- **60%** — Smart compaction (AI-powered summarization)
- **80%** — Aggressive compaction (with CVC checkpoint saved first)

### 35. Can I search through old conversations?

Yes! Use `cvc recall "query"` or `/search <query>` inside the agent. CVC supports:
- **Text search** — keyword matching across all commits
- **Semantic search** — meaning-based search using vector embeddings (Chroma)
- **Smart search** — filters by date, branch, type, provider, model, or tags

---

## Branching, Merging & Time Travel

### 36. How do branches work in CVC?

Just like Git branches, but for conversation context. Create a branch to explore a risky idea without polluting your main conversation:

```bash
cvc branch experiment       # or /branch experiment
# Try something risky...
cvc restore <main-commit>   # Go back if it doesn't work
cvc merge experiment        # Or merge the good parts
```

### 37. What is a semantic merge?

Unlike Git which merges lines of code, CVC performs semantic merging — it intelligently combines the AI's learnings from two branches rather than raw text concatenation. The result is a coherent context that captures insights from both branches.

### 38. Can I rewind to any point in history?

Yes. Every commit has a unique hash. Use `cvc restore <hash>` or `/restore <hash>` to time-travel the AI's brain to that exact state. All messages, decisions, and reasoning are perfectly restored.

### 39. What happens to branches I don't merge?

They persist in the `.cvc/` database. You can switch to them anytime with `/checkout <name>` or merge them later. They don't consume significant storage.

### 40. Can I diff between two cognitive states?

Yes. `cvc diff <hash1> [hash2]` shows what changed in the AI's understanding between two commits — messages added, decisions made, topics discussed.

---

## Providers & Models

### 41. Which LLM providers does CVC support?

- **Anthropic** — Claude Opus 4.6, Opus 4.5, Sonnet 4.5, Haiku 4.5
- **OpenAI** — GPT-5.2, GPT-5.2-Codex, GPT-5-mini, GPT-4.1
- **Google** — Gemini 3.1 Pro, Gemini 3 Pro, Gemini 3 Flash
- **Ollama** — Any local model (Qwen, Devstral, DeepSeek, etc.)

### 42. Can I switch providers mid-session?

Yes! Use `/provider` inside the agent or `/model <name>`. Your conversation history and CVC state persist across provider switches.

### 43. Can I use CVC with local models?

Absolutely. Install Ollama, run `ollama serve`, and choose `ollama` as your provider in CVC setup. Everything runs 100% locally — zero cloud dependencies, zero API costs, complete privacy.

### 44. Does CVC work offline?

Yes, with Ollama. Use any local model (Qwen2.5 Coder, Devstral, DeepSeek R1) and CVC works completely offline. No internet required.

### 45. Am I locked into one provider?

**Never.** CVC is provider-agnostic by design. Switch providers at any time without losing your AI's memory. The cognitive state transcends the model.

---

## IDE & Tool Integration

### 46. Which IDEs does CVC support?

CVC works with 14 AI coding tools: VS Code, Cursor, Windsurf, Claude Code, Aider, Codex CLI, Gemini CLI, Kiro CLI, Continue.dev, Cline/Roo, Open WebUI, Antigravity, Firebase Studio, and GitHub Copilot (BYOK mode).

### 47. How does CVC integrate with VS Code?

Via the MCP (Model Context Protocol) server. Add CVC to your VS Code MCP configuration, and GitHub Copilot can call CVC tools natively — commit, branch, restore, search — all from within the Copilot chat.

### 48. How does CVC integrate with Cursor?

Via MCP server. Add CVC to Cursor's `mcp.json` and the AI assistant gets full time-travel capabilities.

### 49. How does CVC integrate with Claude Code?

Via the Cognitive Proxy. Run `cvc launch claude` and Claude Code automatically gets time-travel. One command, zero configuration.

### 50. Can I use CVC with multiple IDE tools at the same time?

Yes. All three modes share the same `.cvc/` database. Use MCP in VS Code while simultaneously running the CLI agent in your terminal — they see the same conversation history.

---

## MCP Server

### 51. What is MCP?

MCP (Model Context Protocol) is an open standard by Anthropic that lets AI assistants interact with external tools. CVC implements MCP so IDEs can call CVC's version control operations natively.

### 52. Do I need to run `cvc mcp` manually?

No. Your IDE spawns the MCP server automatically as a background process. Running `cvc mcp` manually is only for testing. The IDE handles everything.

### 53. How many MCP tools does CVC expose?

20 tools: 6 core operations, 3 context management, 7 power user, and 4 enterprise tools.

---

## Proxy Mode

### 54. What is the Cognitive Proxy?

A FastAPI server that sits between your AI tool and the LLM provider. It intercepts every message, versions it in CVC, and forwards it transparently. Your tool doesn't know CVC exists.

### 55. What API formats does the proxy support?

- **OpenAI-compatible API** at `/v1/chat/completions`
- **Anthropic Messages API** at `/v1/messages`

### 56. Which port does the proxy use?

Default: `localhost:8000`. Configurable with `--port`.

---

## Cost & Performance

### 57. How does CVC save money on LLM costs?

Through **prompt caching**. When you restore a checkpoint, the LLM provider recognizes the cached context prefix and charges ~90% less for those tokens. Instead of re-processing the entire conversation from scratch, you pay pennies.

### 58. How much does CVC reduce costs?

Research shows ~90% cost reduction through prompt caching integration. A session that would cost $10 in re-prompting costs ~$1 with CVC restores.

### 59. Does CVC add latency?

Minimal. The proxy adds <5ms per request. Restores actually reduce latency by ~85% thanks to prompt caching — the LLM doesn't need to re-process cached context.

### 60. How do I track my spending?

Use `/cost` in the agent for session cost, or `/analytics` for detailed breakdowns. CVC tracks per-turn and per-session costs with cache-aware pricing.

---

## Security & Privacy

### 61. Where does CVC send my data?

**Nowhere.** Everything stays in `.cvc/` on your machine. CVC has zero telemetry, zero cloud sync (unless you explicitly use `cvc sync`), and zero data collection. The only network calls are to the LLM provider you chose.

### 62. Is CVC safe for proprietary code?

Yes. Your conversation with the AI (including any code discussed) is stored locally. CVC doesn't transmit anything beyond what your AI tool already sends to the LLM provider.

### 63. Can I audit what the AI did?

Yes. `cvc audit` provides a compliance-ready security dashboard with event filtering, risk levels (Low/Medium/High/Critical), compliance scoring (0–100%), and JSON/CSV export.

### 64. Is the commit history tamper-proof?

Yes. The Merkle DAG structure means every commit is content-addressed — modifying any past commit changes its hash, which breaks the chain. This is the same cryptographic guarantee Git provides.

---

## Enterprise & Teams

### 65. Can teams share CVC history?

Yes. Use `cvc sync push` and `cvc sync pull` to share cognitive commits between team members via a shared remote repository.

### 66. Can I transfer context between projects?

Yes. `cvc inject <project>` pulls conversations and decisions from another project into your current one. Cross-project knowledge sharing.

### 67. Does CVC work in CI/CD pipelines?

CVC is primarily designed for interactive AI development, but its CLI commands (`commit`, `branch`, `restore`) can be scripted in automation workflows.

### 68. Is there a CVC Cloud?

Not yet. CVC Cloud (planned for Q3 2026) will provide team sync, shared memory, cloud backup, and metrics dashboards.

---

## Technical Architecture

### 69. What language is CVC written in?

Python 3.11+, using FastAPI, Pydantic, Click, Rich, LangGraph, aiosqlite, and Zstandard.

### 70. What database does CVC use?

SQLite for the commit graph and metadata (via aiosqlite for async access). ChromaDB for optional vector embeddings.

### 71. Is CVC async?

Yes. CVC uses async programming throughout — aiosqlite for database access, httpx for HTTP, and async tool execution in the agent.

### 72. What's the difference between CAS blobs and regular file storage?

CAS (Content-Addressable Storage) means each blob is identified by the hash of its content. Identical contexts share the same blob automatically. Blobs are immutable — once written, never modified. This is the same principle Git uses for its object store.

### 73. How does delta compression work?

CVC creates full "anchor" snapshots every N commits. Intermediate commits store only the changes (deltas) relative to the nearest anchor, compressed with Zstandard. This dramatically reduces storage while maintaining instant access to any commit.

---

## Comparisons

### 74. How is CVC different from just saving chat history?

Chat history is a flat text log. CVC is a Merkle DAG with cryptographic linking, content addressing, delta compression, and semantic search. You can branch, merge, and rewind. You can't do any of that with a log file. It's the difference between a diary and Git.

### 75. How is CVC different from Claude's Projects or memory features?

Claude's memory is cloud-stored, locked to Anthropic, and linear — you can't branch or rewind. CVC is local, provider-agnostic, and gives full Git-style version control. Plus, CVC works with Claude AND GPT AND Gemini AND Ollama.

### 76. How is CVC different from Cursor or Copilot?

Cursor and Copilot are AI coding tools. CVC is infrastructure that gives those tools (and any other AI tool) something they don't have: persistent, versionable, branchable memory. CVC wraps around them as middleware.

### 77. How is CVC different from Antigravity?

Antigravity is a Google AI coding tool. CVC is provider-agnostic middleware that adds time-travel to any tool. CVC supports branching, merging, semantic search, and works with 4 providers + 14 tools.

### 78. Can CVC and Git coexist?

Yes! CVC complements Git perfectly. Git versions your code, CVC versions your AI's thinking. The VCS Bridge (`cvc install-hooks`) keeps them synchronized — every Git commit links to the corresponding CVC state.

---

## Troubleshooting

### 79. CVC shows "no API key found." How do I fix it?

Set the API key for your provider:
```bash
export ANTHROPIC_API_KEY="sk-ant-..."     # Anthropic
export OPENAI_API_KEY="sk-..."            # OpenAI
export GOOGLE_API_KEY="AIza..."           # Google
```
Or run `cvc setup` to configure interactively.

### 80. The proxy server won't start. What's wrong?

Run `cvc doctor` to check for issues. Common causes: port 8000 already in use (try `--port 8001`), missing API key, or Python version too old.

### 81. My conversation was lost. Can I recover it?

Try these steps in order:
1. `cvc log` — check if commits exist
2. The persistent cache at `.cvc/context_cache.json` may have your latest messages
3. `cvc restore <hash>` to go back to a saved checkpoint

### 82. The agent is slow. How do I speed it up?

- Use `/fast` for a faster model on the current turn
- Use `--no-think` flag to disable extended thinking
- Switch to a faster model: `/model claude-haiku-4-5` or `/model gpt-5-mini`
- Use Gemini Flash for the fastest responses

### 83. How do I reset CVC completely?

Delete the `.cvc/` folder and the global config:
```bash
rm -rf .cvc/                              # Project CVC data
rm -rf ~/.config/cvc/                     # Global config (Linux/macOS)
# On Windows: Remove %APPDATA%\cvc\
cvc setup                                  # Reconfigure
```

---

## Roadmap & Future

### 84. What's coming in CVC Cloud?

Team sync, shared cognitive memories, cloud backup, collaboration dashboards, and enterprise SSO. Planned for Q3 2026.

### 85. Will CVC have a web UI?

Yes. A browser-based CVC management interface is planned for exploring commit history, branches, and analytics visually.

### 86. Will CVC have a VS Code extension?

Yes. A native VS Code sidebar panel for CVC is on the roadmap — visual commit history, branch management, and one-click time travel.

### 87. Will CVC support more LLM providers?

Yes. Community contributions for additional providers are welcome. The adapter architecture makes adding new providers straightforward.

### 88. Is CVC accepting contributions?

Yes! CVC is open source under MIT license. Contributions are welcome on [GitHub](https://github.com/mannuking/cvc).

---

## Bonus: Quick Reference

### 89. What's the fastest way to get started?

```bash
pip install tm-ai && cvc
```

Two commands. That's it.

### 90. What's the one-line pitch?

> **Git for code. CVC for context. Your AI agent just got an undo button.**

### 91. What's the website URL?

[jaimeena.com/cvc](https://jaimeena.com/cvc)

### 92. What's the PyPI package name?

`tm-ai` — install with `pip install tm-ai`

### 93. What's the GitHub repository?

[github.com/mannuking/cvc](https://github.com/mannuking/cvc)

### 94. What license is CVC under?

MIT License — free for personal and commercial use.

### 95. What's the minimum Python version?

Python 3.11+

---

<div align="center">

**Still have questions?** Open an issue on [GitHub](https://github.com/mannuking/cvc/issues) or visit [jaimeena.com/cvc](https://jaimeena.com/cvc).

</div>
