Core Concepts

Shadow .mem Timeline

MemoV maintains a parallel version control system in

code
.mem/memov.git

, a bare Git repository that operates independently from standard

code
.git

. This architecture ensures zero pollution of production Git history while capturing complete AI interaction context.

Diagram Preview
Click anywhere on the diagram to open interactive canvas

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

code
snap

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

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

Three-Tier File Handling

Diagram Preview
Click anywhere on the diagram to open interactive canvas

Prompt-Only Interactions - When
```
code
files_changed
```
is empty, MemoV records interaction metadata without file modifications
Manual Edit Detection - Comparing actual modifications against declared
```
code
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	code `track()` operation
Clean	Blob hash matches HEAD tree	No action needed
Modified	Blob hash differs from HEAD	code `snapshot()` operation
Deleted	In HEAD but missing from workspace	Handled by snapshot

State Transitions

Diagram Preview
Click anywhere on the diagram to open interactive canvas

Branch Management and Jump

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

Automatic Branch Logic

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

Diagram Preview
Click anywhere on the diagram to open interactive canvas

Jump Operation

The

code
mem_jump

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

bash
# 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

code
.memignore

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

Default Exclusions:

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

Example Configuration:

gitignore
# 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:

code
[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
code `SUCCESS`	Operation completed successfully
code `PROJECT_NOT_FOUND`	Project path invalid
code `BARE_REPO_NOT_FOUND`	code `.mem/memov.git` missing (run code `init()` first)
code `FAILED_TO_COMMIT`	Commit creation failed
code `UNKNOWN_ERROR`	Unexpected error during operation