ai-change-vault 0.3.0

Local snapshots, turn indexing, and configurable semantic embeddings for AI-assisted coding.

AI Change Vault

AI Change Vault (aicv) is a local-first CLI for saving, indexing, and reverting AI-assisted code changes. Its main job is to keep each turn searchable, compact, and recoverable without depending on Git or GitHub.

At a glance, aicv:

• creates local backups before and after a change
• indexes the turn, changed files, and validation result
• can generate embeddings with a configurable model for semantic search
• restores a whole project or a single file when a turn goes wrong

What it solves

When an AI changes code, the result is not always what the user expected. aicv gives every turn a local backup, a structured index entry, searchable metadata, and a reversible snapshot.

Install

aicv is a Python CLI for any repository type, including Node.js repos. Install it into a Python environment on your machine, then point it at the project you want to track.

pip install ai-change-vault

Local embeddings for that same Python environment:

pip install "ai-change-vault[embeddings-local]"

OpenAI embeddings:

pip install "ai-change-vault[embeddings-openai]"

If your Python environment is system-managed, you may need --break-system-packages, or you can use a virtual environment instead.

Core flow

1. Create a snapshot before touching files.
2. Make the AI-driven code changes.
3. Validate with tests, lint, or build.
4. Create a second snapshot after validation.
5. Index the turn with request, changed files, and validation result.
6. Search later by turn, file, or request.
7. Revert the full project or a single file if needed.

Commands

aicv init .
aicv --version
aicv doctor
aicv backup --message "before refactor navbar"
aicv index --turn 1 --request "Change login button color" --files "src/components/Navbar.tsx" --validation "lint + tests OK"
aicv list
aicv search "navbar login"
aicv search --turn turn-1
aicv search --file Navbar.tsx
aicv revert --turn turn-1
aicv revert --turn turn-1 --file src/components/Navbar.tsx
aicv config
aicv embeddings status
aicv embeddings rebuild

What it stores

• Deduplicated snapshot manifests in .aicv/backups/
• Shared file contents in .aicv/objects/
• Turn documents in .aicv/rag/turns/
• Keyword index in .aicv/rag/index.json
• Optional turn, diff, and snippet embedding vectors in .aicv/rag/embeddings.json
• Human-readable session log in AI_SESSION_LOG.md
• Compact turn backups in .aicv/backups/ when both before and after snapshots are indexed

By default, snapshots are content-addressed: each backup stores a manifest and each unique file content is written once under .aicv/objects/. This keeps later backups close to the size of the files that changed instead of copying the whole project every time.

Search modes

aicv uses a hybrid retrieval model:

• Keyword search is always available.
• Embeddings are optional and only used when configured.

Keyword search is exact and fast. Embeddings improve semantic recall, for example when the user asks for "header spacing" and the turn was indexed as "navbar layout". If a local embedding model cannot be downloaded, aicv keeps the rest of the workflow usable and falls back to keyword-only behavior.

Indexing And Embeddings

Each turn stores a canonical document with the request, changed files, validation result, and backup references. When embeddings are enabled, aicv also generates vectors for the turn summary and for changed-file diffs/snippets using the configured model.

Embeddings

Embeddings are opt-in. The default install uses keyword search only.

Providers

• none: keyword-only mode
• sentence-transformers: local semantic embeddings
• openai: hosted embeddings
• ollama: local HTTP embedding endpoint

Recommended models

Use the model name configured in .aicv.config.yaml or AICV_EMBEDDING_MODEL. Good starting points are modern retrieval-oriented models from the BGE, E5, or OpenAI embeddings families.

Example config

backup_dir: .aicv/backups
backup_retention: 20
backup_storage: deduplicated
object_dir: .aicv/objects
rag_dir: .aicv/rag
embedding_provider: sentence-transformers
embedding_model: BAAI/bge-base-en-v1.5
embedding_weight: 0.7
keyword_weight: 0.3
auto_index: false
excludes:
  - .git/
  - .aicv/
  - node_modules/
  - dist/
  - build/

Behavior

• Each turn stores a canonical text representation in the embedding index.
• Changed files also generate diff and snippet payloads when a before snapshot is available.
• Search ranks results using keywords first and semantic similarity second.
• If embeddings are misconfigured or unavailable, aicv falls back to keyword search.
• aicv embeddings rebuild reports model download or provider errors without crashing the rest of the CLI.

Reverting

Full project:

aicv revert --turn turn-1

Single file:

aicv revert --turn turn-1 --file src/components/Navbar.tsx

Use --state after to restore the post-change backup when available.

Configuration

Create .aicv.config.yaml in the project root:

backup_dir: .aicv/backups
backup_retention: 20
backup_storage: deduplicated
object_dir: .aicv/objects
rag_dir: .aicv/rag
embedding_provider: none
embedding_model: sentence-transformers/all-MiniLM-L6-v2
embedding_base_url: http://localhost:11434
embedding_endpoint: /api/embed
embedding_batch_size: 16
embedding_weight: 0.65
keyword_weight: 0.35
auto_index: false

Environment variables with the AICV_ prefix override config values:

AICV_BACKUP_DIR=.vault/backups aicv backup "custom dir"

Use backup_storage: copy or AICV_BACKUP_STORAGE=copy to keep the legacy full-directory snapshot behavior.

If you are migrating an older project, .aicv.yaml is still accepted as a legacy fallback.

List stored data

aicv list
aicv list --kind turns
aicv list --kind backups
aicv list --json

Migrate old backups

If a project already has legacy full-copy backups, convert them to deduplicated manifests:

aicv backups migrate --yes

Existing compact or deduplicated backups are skipped. Legacy backups are rewritten as manifests and their file contents are stored once in .aicv/objects/.