Skip to main content

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

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/.

Metadata

Release files for ai-change-vault 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ai-change-vault 0.3.0
File Size Uploaded Provenance Actions
ai_change_vault-0.3.0.tar.gz 129.9 kB Without provenance Details for ai_change_vault-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ai-change-vault 0.3.0
File Interpreter ABI Platform Actions
ai_change_vault-0.3.0-py3-none-any.whl Python 3 none any Details for ai_change_vault-0.3.0-py3-none-any.whl

Total release size: 160.9 kB

Release files / ai_change_vault-0.3.0.tar.gz

Download URL ai_change_vault-0.3.0.tar.gz
Size 129.9 kB
Tags Source
SHA-256 checksum
How to use checksums
f61407c002e829b0094cc0c1d9493525081f6669a7fb3e7fa09cea9a784e5f9b
BLAKE2b-256 checksum
How to use checksums
a3d80cfbdfe27bae9d4b771b899585105aece2d2d4f9434ea69df165448b8eda
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.5

Release files / ai_change_vault-0.3.0-py3-none-any.whl

Download URL ai_change_vault-0.3.0-py3-none-any.whl
Size 31.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4fd4dbe6936cee743593d0bdc61830d237774925202835dda8b51c2c6dc9162a
BLAKE2b-256 checksum
How to use checksums
bd2aac6ada409259a6dd870400a1588a760e6c976312cf44e7e5cf896282b857
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.5

Security for ai-change-vault 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page