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
- Create a snapshot before touching files.
- Make the AI-driven code changes.
- Validate with tests, lint, or build.
- Create a second snapshot after validation.
- Index the turn with request, changed files, and validation result.
- Search later by turn, file, or request.
- 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 modesentence-transformers: local semantic embeddingsopenai: hosted embeddingsollama: 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,
aicvfalls back to keyword search. aicv embeddings rebuildreports 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.