tm-ai 1.1.5

Time Machine for AI Agents — Cognitive Version Control for LLM context

🧠 Cognitive Version Control

Git for the AI Mind

Save. Branch. Rewind. Merge. — Your AI agent just got an undo button.

pip install tm-ai

🤖 Agent CLI · ✨ Features · 🚀 Quick Start · 📖 CLI Reference · 🤝 Contributing

---

Your AI coding agent is brilliant — for about 20 minutes.

Then it forgets what it already fixed, contradicts its own plan, and loops on the same error for eternity.

Sound familiar?

---

🧠 What Is This?

CVC gives AI coding agents something they've never had: memory management that actually works.

Git, but for the AI's brain. Instead of versioning source code, CVC versions the agent's entire context — every thought, every decision, every conversation turn — as an immutable, cryptographic Merkle DAG.

The agent can checkpoint its reasoning, branch into risky experiments, rewind when stuck, and merge only the insights that matter.

💾 Save	🌿 Branch	🔀 Merge	⏪ Rewind
Checkpoint the agent's brain at any stable moment.	Explore risky ideas in isolation. Main context stays clean.	Merge learnings back — not raw logs. Semantic, not syntactic.	Stuck in a loop? Time-travel back instantly.

---

🤖 CVC Agent — Your Own AI Coding Assistant

Claude Code on steroids — with Time Machine built in.

Just type cvc and you're in. No setup menus, no extra commands.

cvc

That's it. One command. The agent launches.

CVC ships with a full agentic coding assistant directly in your terminal — like Claude Code, but with the ability to save, branch, rewind, and search through your entire conversation history. It's not just an AI chat — it's an AI with cognitive version control.

🔧 15 Built-in Tools

The agent has access to powerful tools that let it work directly on your codebase:

Icon	Tool	What It Does
📖	read_file	Read files with optional line ranges for large files
✏️	write_file	Create or overwrite files, auto-creates directories
🔧	edit_file	Precise find-and-replace edits with uniqueness validation
🖥️	bash	Run shell commands (PowerShell on Windows, bash on Unix)
🔍	glob	Find files by pattern (**/*.py, src/**/*.ts)
📝	grep	Search file contents with regex + include filters
📁	list_dir	List directory contents to explore project structure
📊	cvc_status	Show current branch, HEAD, and context state
📜	cvc_log	View commit history — snapshots of the conversation
💾	cvc_commit	Save a checkpoint of the current conversation state
🌿	cvc_branch	Create a branch to explore alternatives safely
⏪	cvc_restore	Time-travel back to any previous conversation state
🔀	cvc_merge	Merge insights from one branch into another
🔎	cvc_search	Search commit history for specific topics or discussions
📋	cvc_diff	Compare conversation states between commits

⌨️ Slash Commands

While chatting with the agent, use these slash commands for quick actions:

Command	Description
/help	Show all available slash commands
/status	View branch, HEAD, context size, provider & model
/log	Show last 20 conversation checkpoints
/commit <message>	Save a manual checkpoint of the conversation
/branch <name>	Create and switch to a new conversation branch
/restore <hash>	Time-travel back to a specific checkpoint
/search <query>	Search all commits for a topic (e.g., /search auth login)
/compact	Compress the conversation history, keeping recent context
/clear	Clear conversation history (CVC state preserved)
/model <name>	Switch LLM model mid-conversation
/exit	Save final checkpoint and exit cleanly

🧠 What Makes It Different

Claude Code / Codex	Aider / Cursor	🔥 CVC Agent
Great tools No memory across sessions No branching / rollback Single provider only Context lost on crash	Great IDE integration Session history is linear No context time-travel Can't search past chats Provider-locked	All of their tools, plus: ⏪ Time-travel to any point 🌿 Branch conversations 🔎 Search across all history 🔀 Merge insights 🤖 4 providers supported 💾 Auto-checkpoint every 5 turns 📱 Session persistence

🎨 Agent Options

cvc                                     # Launch agent with saved config
cvc agent                               # Same thing — explicit subcommand
cvc agent --provider anthropic          # Force a specific provider
cvc agent --model claude-sonnet-4-5     # Override the model
cvc agent --api-key sk-ant-...          # Pass API key directly

🔄 Auto-Commit

The agent automatically saves checkpoints every 5 assistant turns (CVC_AGENT_AUTO_COMMIT=5). When you exit with /exit, a final checkpoint is saved. You never lose context.

---

🔥 The Problem We're Solving

The industry keeps making context windows bigger — 4K → 32K → 128K → 1M+ tokens

It's not progress.

Research shows that after ~60% context utilisation, LLM reasoning quality falls off a cliff. One hallucination poisons everything that follows. Error cascades compound. The agent starts fighting itself.

A bigger window doesn't fix context rot. It just gives it more room to spread.

The Real Issue

AI agents have zero ability to manage their own cognitive state. They can't save their work. They can't explore safely. They can't undo mistakes. They're solving a 500-piece puzzle while someone keeps removing pieces from the table.

📊 What the Research Shows

58.1% Context reduction via branching	3.5× Success rate improvement with rollback	~90% Cost reduction through caching	~85% Latency reduction
ContextBranch paper	GCC paper	Prompt caching	Cached tokens skip processing

---

⚙️ How It Works

CVC operates in two modes: as a standalone agent (just type cvc) or as a proxy between your favourite AI tool and the LLM provider.

%%{init: {'theme': 'dark', 'themeVariables': { 'fontSize': '14px', 'primaryColor': '#2C0000', 'primaryTextColor': '#E8D0D0', 'primaryBorderColor': '#8B0000', 'lineColor': '#CC3333', 'secondaryColor': '#5C1010', 'tertiaryColor': '#3D0000', 'edgeLabelBackground': '#2C0000'}}}%%

flowchart LR
    subgraph LOCAL["🖥️  YOUR MACHINE"]
        direction TB

        subgraph AGENT_MODE["  CVC Agent (cvc)  "]
            AG["🤖 Terminal Agent\n15 tools · 4 providers"]
        end

        subgraph PROXY_MODE["  CVC Proxy · localhost:8000  "]
            direction TB
            R["⚡ LangGraph Router"]
            R -->|CVC ops| E["🧠 Cognitive Engine"]
            R -->|passthrough| FWD["📡 Forward to LLM"]
        end

        subgraph STORAGE["  .cvc/ directory  "]
            direction LR
            S1["🗄️ SQLite\nCommit Graph"]
            S2["📦 CAS Blobs\nZstandard"]
            S3["🔍 Chroma\nVectors"]
        end

        AG -- "direct API" --> CLOUD
        AG --> E
        R -- "HTTP" --> CLOUD
        E --> S1 & S2 & S3
    end

    subgraph CLOUD["  ☁️ LLM Provider  "]
        direction TB
        C1["Claude"]
        C2["GPT-5.2"]
        C3["Gemini 3 Pro"]
        C4["Ollama 🏠"]
    end

    style LOCAL fill:#1a0505,stroke:#8B0000,stroke-width:2px,color:#E8D0D0
    style AGENT_MODE fill:#2C0000,stroke:#CC3333,stroke-width:2px,color:#E8D0D0
    style PROXY_MODE fill:#2C0000,stroke:#8B0000,stroke-width:1px,color:#E8D0D0
    style STORAGE fill:#1a0505,stroke:#5C1010,stroke-width:1px,color:#E8D0D0
    style CLOUD fill:#1a0505,stroke:#CC3333,stroke-width:2px,color:#E8D0D0
    style AG fill:#8B0000,stroke:#CC3333,color:#ffffff
    style R fill:#5C1010,stroke:#CC3333,color:#ffffff
    style E fill:#3D5C10,stroke:#55AA55,color:#ffffff
    style FWD fill:#5C1010,stroke:#CC3333,color:#ffffff
    style S1 fill:#2C0000,stroke:#BB8844,color:#E8D0D0
    style S2 fill:#2C0000,stroke:#BB8844,color:#E8D0D0
    style S3 fill:#2C0000,stroke:#BB8844,color:#E8D0D0
    style C1 fill:#8B0000,stroke:#CC3333,color:#ffffff
    style C2 fill:#5C1010,stroke:#CC3333,color:#ffffff
    style C3 fill:#3D5C10,stroke:#55AA55,color:#ffffff
    style C4 fill:#444444,stroke:#888888,color:#ffffff

🎯 Three-Tiered Storage (All Local)

Tier	What	Why
🗄️ SQLite	Commit graph, branch pointers, metadata	Fast traversal, zero-config, works everywhere
📦 CAS Blobs	Compressed context snapshots (Zstandard)	Content-addressable, deduplicated, efficient
🔍 Chroma	Semantic embeddings (optional)	"Have I solved this before?" — search by meaning

✨ Everything stays in .cvc/ inside your project 🔒 No cloud • No telemetry • Your agent's thoughts are yours

---

🚀 Get Started

Prerequisites

Python 3.11+ • Git (for VCS bridge features)

📦 Install

Available on PyPI — install in one command, no cloning required.

pip install tm-ai

That's it. The cvc command is now available globally.

🔧 More install options

# With uv (faster)
uv pip install tm-ai

# As an isolated uv tool (always on PATH, no venv needed)
uv tool install tm-ai

# With provider extras
pip install "tm-ai[anthropic]"     # Anthropic (Claude)
pip install "tm-ai[openai]"        # OpenAI (GPT)
pip install "tm-ai[google]"        # Google (Gemini)
pip install "tm-ai[all]"           # Everything

🛠️ For contributors / local development

git clone https://github.com/mannuking/AI-Cognitive-Version-Control.git
cd AI-Cognitive-Version-Control
uv sync --extra dev           # or: pip install -e ".[dev]"

▶️ Run

The simplest way — just type cvc:

cvc

This launches the CVC Agent directly. If it's your first time, you'll be guided through setup first (pick your provider, model, and API key).

Or use specific commands:

# Launch the agent explicitly
cvc agent
cvc agent --provider openai --model gpt-5.2

# Launch external AI tools through CVC's proxy
cvc launch claude          # Claude Code CLI
cvc launch aider           # Aider
cvc launch codex           # OpenAI Codex CLI
cvc launch cursor          # Cursor IDE
cvc launch code            # VS Code

# One-command start (setup + init + serve proxy)
cvc up

Cross-platform: Works on Windows, macOS, and Linux. Global config is stored in the platform-appropriate location:

• Windows: %LOCALAPPDATA%\cvc\config.json
• macOS: ~/Library/Application Support/cvc/config.json
• Linux: ~/.config/cvc/config.json

🔑 Set Your API Key

Provider	Bash / Linux / macOS	PowerShell
Anthropic	export ANTHROPIC_API_KEY="sk-ant-..."	$env:ANTHROPIC_API_KEY = "sk-ant-..."
OpenAI	export OPENAI_API_KEY="sk-..."	$env:OPENAI_API_KEY = "sk-..."
Google	export GOOGLE_API_KEY="AIza..."	$env:GOOGLE_API_KEY = "AIza..."
Ollama	No key needed — just run ollama serve and ollama pull qwen2.5-coder:7b

Or save your keys via cvc setup — they're stored securely on your machine.

🔌 Connect External AI Tools (Proxy Mode)

If you prefer to use your own AI tool instead of the built-in agent, CVC runs as a transparent proxy that time-machines every conversation:

API-Based Tools (Proxy Mode)

Point your AI agent's API base URL to http://127.0.0.1:8000

CVC exposes OpenAI-compatible (/v1/chat/completions) AND Anthropic-native (/v1/messages) endpoints.

Auth-Based Tools (MCP Mode)

For IDEs that use login authentication (Antigravity, Windsurf, native Copilot), CVC runs as an MCP server:

cvc mcp                 # Start MCP server (stdio transport)
cvc mcp --transport sse # Start MCP server (HTTP/SSE transport)

Tool	Auth Type	How to Connect
💎 VS Code + Copilot	GitHub Login	BYOK: Ctrl+Shift+P → Manage Models → OpenAI Compatible or MCP: cvc mcp
🚀 Antigravity	Google Login	MCP only: add cvc in MCP settings → cvc mcp
🖱️ Cursor	API Key Override	Settings → Models → Override Base URL → http://127.0.0.1:8000/v1
🏄 Windsurf	Account Login	MCP only: add cvc in Cascade MCP settings → cvc mcp
🟠 Claude Code CLI	API Key	export ANTHROPIC_BASE_URL=http://127.0.0.1:8000 — native /v1/messages
⌨️ Codex CLI	API Key	model_provider = "cvc" in ~/.codex/config.toml
🔄 Continue.dev / 🤖 Cline	API Key	Base URL → http://127.0.0.1:8000/v1, API Key → cvc
🛠️ Aider / 🌐 Open WebUI	API Key	Standard OpenAI-compatible endpoint
🦜 LangChain / CrewAI / AutoGen	API Key	Use CVC's function-calling tools (GET /cvc/tools)

Auth pass-through: When Claude Code or Codex CLI sends its own API key, CVC forwards it to the upstream provider. No need to store API keys in CVC for these tools.

Run cvc connect for interactive, tool-specific setup instructions.

---

📟 CLI Reference

Command	Description
cvc	Launch the CVC Agent — interactive AI coding assistant
cvc agent	Same as above (explicit subcommand)
cvc agent --provider <p>	Agent with a specific provider (anthropic, openai, google, ollama)
cvc agent --model <m>	Agent with a model override
──── Launch External Tools ────
cvc launch <tool>	Zero-config — auto-launch any AI tool through CVC
cvc up	One command: setup + init + serve proxy
──── Setup & Configuration ────
cvc setup	Interactive setup wizard (choose provider & model)
cvc init	Initialize .cvc/ in your project
cvc serve	Start the Cognitive Proxy (API-based tools)
cvc mcp	Start MCP server (auth-based IDEs)
cvc connect	Interactive tool connection wizard
──── Time Machine ────
cvc status	Show branch, HEAD, context size
cvc log	View commit history
cvc commit -m "message"	Create a cognitive checkpoint
cvc branch <name>	Create an exploration branch
cvc merge <branch>	Semantic merge into active branch
cvc restore <hash>	Time-travel to a previous state
cvc sessions	View Time Machine session history
──── Utilities ────
cvc install-hooks	Install Git ↔ CVC sync hooks
cvc capture-snapshot	Link current Git commit to CVC state
cvc doctor	Health check your environment

---

🔗 Git Integration

CVC doesn't replace Git — it bridges with it.

Feature	What It Does
🌲 Shadow Branches	CVC state lives on cvc/main, keeping your main branch clean
📝 Git Notes	Every git commit is annotated with the CVC hash — "What was the AI thinking when it wrote this?"
🔄 post-commit hook	Auto-captures cognitive state after every git commit
⏰ post-checkout hook	Auto-restores the agent's brain when you git checkout an old commit

📜 When you check out an old version of your code, CVC automatically restores the agent's context to what it was when that code was written.

✨ True cognitive time-travel.

---

⏱️ Time Machine Mode

Like macOS Time Machine, but for AI agent conversations.

Every conversation is automatically saved. Nothing is ever lost.

When you use cvc (the agent) or cvc launch, Time Machine mode is enabled by default:

Feature	Description
Auto-commit	Every 5 assistant turns (agent) or 3 turns (proxy), configurable
Session tracking	Detects which tool is connected, tracks start/end, message counts
Smart messages	Auto-commits include turn number and conversation summary
Zero friction	Just cvc and go — or cvc launch claude for external tools
Session persistence	Context restored from CVC on next launch

# View session history
cvc sessions

# Customize auto-commit interval (agent)
CVC_AGENT_AUTO_COMMIT=3 cvc agent    # Commit every 3 turns

# Customize auto-commit interval (proxy)
CVC_TIME_MACHINE_INTERVAL=5 cvc up   # Commit every 5 turns

# Disable time machine for external tools
cvc launch claude --no-time-machine

Supported External Tools

Tool	Launch Command	How It Connects
Claude Code CLI	cvc launch claude	Sets ANTHROPIC_BASE_URL → native /v1/messages
Aider	cvc launch aider	Sets OPENAI_API_BASE + model flag
OpenAI Codex CLI	cvc launch codex	Sets OPENAI_API_BASE
Gemini CLI	cvc launch gemini	Sets GEMINI_API_BASE_URL
Kiro CLI	cvc launch kiro	Sets OPENAI_API_BASE
Cursor	cvc launch cursor	Writes .cursor/mcp.json + opens IDE
VS Code	cvc launch code	Writes .vscode/mcp.json + configures BYOK
Windsurf	cvc launch windsurf	Writes MCP config + opens IDE

---

⚡ Why It's Cheap

CVC structures prompts so committed history becomes a cacheable prefix. When you rewind to a checkpoint, the model doesn't reprocess anything it's already seen.

Metric	❌ Without CVC	✅ With CVC
💰 Cost per restore	Full price	~90% cheaper
⚡ Latency per restore	Full processing	~85% faster
🔄 Checkpoint frequency	Impractical	Economically viable

🔥 Works today with Anthropic, OpenAI, Google Gemini, and Ollama 💡 Prompt caching optimised per provider

---

🤖 Supported Providers

Pick your provider. CVC handles the rest.

Provider	Default Model	Alternatives	Notes
Anthropic	claude-opus-4-6	claude-opus-4-5, claude-sonnet-4-5, claude-haiku-4-5	Prompt caching with cache_control
OpenAI	gpt-5.2	gpt-5.2-codex, gpt-5-mini, gpt-4.1	Automatic prefix caching
Google	gemini-3-pro-preview	gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite	OpenAI-compatible endpoint
Ollama	qwen2.5-coder:7b	qwen3-coder:30b, devstral:24b, deepseek-r1:8b	100% local, no API key needed

---

⚙️ Configuration

All via environment variables — no config files to manage

Variable	Default	What It Does
CVC_AGENT_ID	sofia	Agent identifier
CVC_DEFAULT_BRANCH	main	Default branch
CVC_ANCHOR_INTERVAL	10	Full snapshot every N commits (others are delta-compressed)
CVC_PROVIDER	anthropic	LLM provider
CVC_MODEL	auto	Model name (auto-detected per provider)
CVC_AGENT_AUTO_COMMIT	5	Agent auto-checkpoint interval (turns)
CVC_TIME_MACHINE_INTERVAL	3	Proxy auto-commit interval (turns)
ANTHROPIC_API_KEY	—	Required for anthropic provider
OPENAI_API_KEY	—	Required for openai provider
GOOGLE_API_KEY	—	Required for google provider
CVC_HOST	127.0.0.1	Proxy host
CVC_PORT	8000	Proxy port
CVC_VECTOR_ENABLED	false	Enable semantic search (Chroma)

---

🏗️ Architecture

cvc/
├── __init__.py            # Package root, version
├── __main__.py            # python -m cvc entry point
├── cli.py                 # Click CLI — all commands, setup wizard, dark red theme
├── proxy.py               # FastAPI proxy — intercepts LLM API calls
├── launcher.py            # Zero-config auto-launch for AI tools
├── mcp_server.py          # Model Context Protocol server
│
├── agent/                 # ★ Built-in AI coding agent (v0.6.0)
│   ├── __init__.py        # Exports run_agent()
│   ├── chat.py            # AgentSession REPL loop, slash commands, auto-commit
│   ├── llm.py             # Unified LLM client — tool calling for all 4 providers
│   ├── tools.py           # 15 tool definitions in OpenAI function-calling schema
│   ├── executor.py        # Tool execution engine — file ops, shell, CVC operations
│   ├── system_prompt.py   # Dynamic Claude Code-style system prompt builder
│   └── renderer.py        # Rich terminal rendering with #2C0000 dark red theme
│
├── adapters/              # Provider-specific prompt formatting
│   ├── base.py            # Abstract BaseAdapter
│   ├── anthropic.py       # Anthropic adapter (prompt caching)
│   ├── openai.py          # OpenAI adapter
│   ├── google.py          # Google adapter
│   └── ollama.py          # Ollama adapter
│
├── core/                  # Data layer
│   ├── models.py          # Pydantic schemas, config, Merkle DAG
│   └── database.py        # SQLite + CAS + Chroma storage
│
├── operations/            # CVC engine
│   ├── engine.py          # Commit, branch, merge, restore
│   └── state_machine.py   # LangGraph command routing
│
└── vcs/                   # Git bridge
    └── bridge.py          # Shadow branches, Git notes, hooks

---

🎯 Who Is This For?

👤 Solo Developers	🏢 Teams & Organizations	🌐 Open Source
Your AI stops losing context mid-session. Explore multiple approaches. Undo mistakes. Never re-explain the same thing twice.	Review the AI's reasoning, not just its output. Cryptographic audit trails. Shared cognitive state across team members. Compliance-ready.	See how an AI-generated PR was produced. Inspect for hallucination patterns. Build project knowledge bases from commit embeddings.

---

🗺️ Roadmap

Feature	Status
🤖 Built-in Agent CLI	✅ Shipped in v0.6.0 — 15 tools, 4 providers, slash commands
☁️ Anthropic Adapter	✅ Claude Opus 4.6 / 4.5 / Sonnet / Haiku
☁️ OpenAI Adapter	✅ GPT-5.2 / GPT-5.2-Codex / GPT-5-mini
☁️ Google Gemini Adapter	✅ Gemini 3 Pro Preview / 2.5 Pro / 2.5 Flash
🏠 Ollama (Local)	✅ Qwen 2.5 Coder / Qwen 3 Coder / DeepSeek-R1 / Devstral
🔌 MCP Server	✅ Native Model Context Protocol (stdio + SSE)
🚀 Zero-config Launch	✅ cvc launch claude / aider / codex / cursor / etc.
🔗 Git Bridge	✅ Shadow branches, Git notes, auto-hooks
🎨 VS Code Extension	🔜 Visual commit graph and time-travel slider
👥 Multi-agent support	🔜 Shared CVC database with conflict resolution
☁️ Cloud sync	🔜 S3/MinIO for team collaboration
📊 Metrics dashboard	🔜 Cache hit rates, context utilisation, branch success rates

---

🤝 Contributing

This repo is public and open to collaboration.

Whether you're fixing a typo or building an entirely new provider adapter — contributions are welcome.

Fork → Branch → Commit → Push → PR

🎯 Areas Where Help Is Needed

Area	Difficulty
🔌 Additional Provider Adapters (Mistral, Cohere, etc.)	🟡 Medium
🧪 Tests & edge cases	🟢 Easy–Medium
🖥️ VS Code Extension (commit graph visualisation)	🔴 Hard
📊 Metrics & observability dashboard	🟡 Medium
🔒 Security audit	🟠 Medium–Hard

🛠️ Dev Setup

git clone https://github.com/YOUR_USERNAME/AI-Cognitive-Version-Control.git
cd AI-Cognitive-Version-Control
uv sync --extra dev

---

📚 Research

CVC is grounded in published research

Paper	Key Finding
ContextBranch	58.1% context reduction via branching
GCC	11.7% → 40.7% success with rollback
Merkle-CRDTs	Structural deduplication for DAGs
Prompt Caching	Anthropic/OpenAI/Google token reuse

---

📜 License

MIT — see LICENSE

---

✨ Because AI agents deserve an undo button. ✨

⭐ Star this repo if you believe in giving AI agents memory that actually works.

Made with ❤️ by developers who got tired of AI agents forgetting what they just did.

⭐ Star · 🐛 Bug · 💡 Feature · 🔀 PR