# CVC (Cognitive Version Control) - Agent Instructions

## 📌 Project Overview
CVC (Time Machine for AI Agents) is a cognitive version control system designed to save, branch, rewind, and merge LLM context. It acts as "Git for context," providing AI agents with state management and an undo mechanism. 

**Note: This is a strictly private and confidential repository.**

## 🛠 Tech Stack
- **Language**: Python 3.11+
- **Core Frameworks**: FastAPI, Pydantic, Click (CLI), Rich (Terminal UI)
- **AI/LLM**: LangChain, LangGraph, ChromaDB, Anthropic/OpenAI/Google SDKs
- **Storage/State**: aiosqlite, GitPython, zstandard
- **Build/Tooling**: Hatchling, Ruff, Pytest (Asyncio)

## 📐 Key Conventions
- **Formatting & Linting**: Managed by Ruff. Target version `py311`, max line length `100`. Rule sets: `E`, `F`, `I`, `W`.
- **Async First**: Use asynchronous programming where applicable (e.g., `aiosqlite`, async test execution).
- **Type Hinting**: Use strict Pydantic models for validation and comprehensive type hints across all Python functions.
- **Security & Privacy**: Do not hardcode API keys. Treat all context states and vector data as sensitive.

## 💻 Common Commands
- **Install (Dev)**: `pip install -e ".[all,dev]"`
- **Build**: `hatch build`
- **Lint**: `ruff check .` (and `ruff format .` for styling)
- **Test**: `pytest` (uses auto asyncio mode)
- **Run CLI**: `cvc <command>`

## 📁 Important Directories & Files
- `cvc/` - Main package source code.
  - `cvc/cli.py` - Primary command-line interface logic.
  - `cvc/core/` - Core business logic for versioning and state management.
  - `cvc/agent/` - Agent interaction and LangGraph implementations.
  - `cvc/operations/` - CVC context operations (branching, merging, restoring).
  - `cvc/adapters/` - External LLM and tool adapter integrations.
  - `cvc/mcp_server.py` - Model Context Protocol implementation.
- `pyproject.toml` - Project configuration and dependencies.
- `docs/` - Extensive documentation, including CLI guides, MCP docs, and tool references.
