Core Concepts

Shadow .mem Timeline

MemoV maintains a parallel version control system in .mem/memov.git, a bare Git repository that operates independently from standard .git. This architecture ensures zero pollution of production Git history while capturing complete AI interaction context.

Key Design Principle: The shadow timeline stores commits with enhanced metadata via Git notes, preserving standard Git content-addressing while adding conversational context that traditional commits cannot capture.

Context Capture with snap

The snap tool is the primary integration point between AI agents and MemoV's versioning system. It captures four essential parameters:

Parameter	Type	Purpose
`user_prompt`	string	Original user request
`original_response`	string	AI's complete explanation
`agent_plan`	list[str]	High-level change summary by file
`files_changed`	string	Comma-separated modified file paths

Three-Tier File Handling

Prompt-Only Interactions - When files_changed is empty, MemoV records interaction metadata without file modifications
Manual Edit Detection - Comparing actual modifications against declared files_changed identifies user edits
AI File Classification - Files are categorized as untracked, modified, or clean

File States and Lifecycle

MemoV tracks files through four distinct states:

State	Detection Method	Action Required
Untracked	Not in tracked files dictionary	`track()` operation
Clean	Blob hash matches HEAD tree	No action needed
Modified	Blob hash differs from HEAD	`snapshot()` operation
Deleted	In HEAD but missing from workspace	Handled by snapshot

State Transitions

Branch Management and Jump

MemoV implements automatic branch creation to organize development history without requiring explicit user commands.

Automatic Branch Logic

First commit creates main branch
Current branch updates when new commits occur at branch tip
When HEAD matches existing branch, that branch updates
Otherwise, creates next available develop/N branch

Jump Operation

The mem_jump command enables time-travel by restoring file snapshots from historical commits:

# Jump to a specific commit
mem jump abc1234
 
# This will:
# 1. Restore files from that commit
# 2. Create a new branch from that point
# 3. Track the jump in jump.json

.memignore Configuration

The .memignore file uses Git-compatible wildmatch patterns to exclude files from tracking.

Default Exclusions:

.mem/ (MemoV's own directory)
.git/ (standard Git repository)

Example Configuration:

# Ignore dotfiles
.*

# Ignore dependencies
node_modules/
__pycache__/
venv/

# Ignore build artifacts
*.log
dist/
build/

# Ignore sensitive files
.env
*.key
credentials.json

Commit Metadata Structure

Each MemoV commit contains enhanced metadata:

[Operation Type]
Files: file1.py, file2.py

---
Prompt: [user's exact request]
Response: [AI's response with agent plan]
Source: User|AI

Component	Storage	Purpose
Tree objects	Git standard	File snapshots
Commit message	Git standard	User prompt and file list
Git notes	Git notes ref	Full AI response and agent plan
by_user flag	Git notes	Attribution indicator

Status Indicators

All operations return status indicators:

Status	Meaning
`SUCCESS`	Operation completed successfully
`PROJECT_NOT_FOUND`	Project path invalid
`BARE_REPO_NOT_FOUND`	`.mem/memov.git` missing (run `init()` first)
`FAILED_TO_COMMIT`	Commit creation failed
`UNKNOWN_ERROR`	Unexpected error during operation

About Architecture