Storage Architecture

MemoV organizes its storage in a .mem/ directory parallel to the project's .git/ folder.

Directory Structure

.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 .mem/memov.git/ as its "source of truth."

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 `refs/memov/HEAD` without Git conflicts

Metadata Files

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

Git Notes for Context

MemoV attaches AI interaction metadata using Git notes:

Note Structure:

{
  "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
`.mem/memov.git/`	Write-through via GitManager	Read-through	Strong (Git ACID)
`branches.json`	Write after commit	Load on demand	Eventual
`jump.json`	Append after jump	Load on demand	Eventual
`pending_writes.json`	Write after operation	Load at init	Eventual
`.memignore`	User edited	Load on demand	Eventual
`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:

Collections:

prompts - User prompt embeddings
responses - AI response embeddings
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

mem init

Creates:

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

Snapshot Flow

Architecture MCP Tools