Storage Architecture

MemoV organizes its storage in a

code
.mem/

directory parallel to the project's

code
.git/

folder.

Directory Structure

code
.mem/
├── memov.git/          # Bare Git repository (shadow timeline)
│   ├── objects/        # Git blobs, trees, commits
│   ├── refs/memov/     # MemoV-specific refs
│   └── notes/          # Git notes with prompt/response metadata
├── branches.json       # Branch metadata and labels
├── jump.json          # Jump history tracking
├── .memignore         # Files to exclude from tracking
├── pending_writes.json # RAG mode: pending VectorDB writes
└── vectordb/          # Optional ChromaDB for semantic search

Core Storage Components

Bare Git Repository

MemoV uses a bare Git repository at

code
.mem/memov.git/

as its "source of truth."

Diagram Preview
Click anywhere on the diagram to open interactive canvas

Advantages:

Benefit	Description
No working directory conflicts	Bare repository never interferes with project workspace
Explicit snapshot control	Users choose when to snapshot
Separation of concerns	Clear boundary between storage and working files
Custom refs	Uses code `refs/memov/HEAD` without Git conflicts

Metadata Files

File	Purpose	Update Pattern
code `branches.json`	Branch metadata and exploration history	Write after commit
code `jump.json`	Exploration timeline of time-travel operations	Append after jump
code `.memignore`	Pathspec patterns for exclusion	User edited
code `pending_writes.json`	RAG mode pending VectorDB writes	Write after operation

Git Notes for Context

MemoV attaches AI interaction metadata using Git notes:

Diagram Preview
Click anywhere on the diagram to open interactive canvas

Note Structure:

json
{
  "user_prompt": "Add error handling to the API",
  "original_response": "I'll add try-catch blocks...",
  "agent_plan": ["1. Add try-catch in api.py", "2. Create custom exceptions"],
  "by_user": false
}

Storage Consistency Model

Component	Write Pattern	Read Pattern	Consistency
code `.mem/memov.git/`	Write-through via GitManager	Read-through	Strong (Git ACID)
code `branches.json`	Write after commit	Load on demand	Eventual
code `jump.json`	Append after jump	Load on demand	Eventual
code `pending_writes.json`	Write after operation	Load at init	Eventual
code `.memignore`	User edited	Load on demand	Eventual
code `vectordb/`	Batch write via sync	Query via ChromaDB	Eventual

VectorDB Storage (RAG Mode)

When RAG mode is enabled, MemoV maintains a ChromaDB instance for semantic search:

Diagram Preview
Click anywhere on the diagram to open interactive canvas

Collections:

```
code
prompts
```
- User prompt embeddings
```
code
responses
```
- AI response embeddings
```
code
code_changes
```
- Code diff embeddings

Design Decisions

Why Subprocess over GitPython?

MemoV invokes Git CLI rather than using Python libraries:

Exact Git behavior guaranteed
Direct access to low-level plumbing commands
Full compatibility with bare repositories
No library version conflicts

Why Content-Addressable Storage?

Git's content-addressable model provides:

Automatic deduplication of identical files
Integrity verification via SHA hashes
Efficient storage of similar content
Proven reliability at scale

Storage Operations

Initialization

bash
mem init

Creates:

```
code
.mem/
```
directory
Bare Git repository at
```
code
.mem/memov.git/
```
Default
```
code
.memignore
```
file
Empty
```
code
branches.json
```

Snapshot Flow

Diagram Preview
Click anywhere on the diagram to open interactive canvas