This repository has been archived on 2026-11-17. You can view files and clone it, but cannot push or open issues or pull requests.
gitgram-ai/aitimemachine/docs/HOW_IT_WORKS.md
caelum0x 49b183818c Unify gitgram + aitimemachine into the monorepo (de-submodule) and merge vendored engines
Convert gitgram/ and aitimemachine/ from embedded git repos (which showed as
opaque submodule gitlinks on GitHub) into fully-tracked first-party content.

AITM now merges its 7 vendored repos as first-party engines:
- memory: beads (Go task DAG) + context7 (docs SDK), unified into saved_contexts
- git: vendored C git (bundled binary) + gitnexus (in-process code intelligence)
- agentic: a2a (@a2a-js/sdk) + pal (AITM-managed Python subprocess)

Includes the full session's product build: Gitgram web/mobile/backend features,
AITM website/CLI/MCP, the unified memory layer, engine build tooling
(scripts/build-engines.sh, Dockerfile, CI), docs (README, ENGINES.md, ARCHITECTURE.md),
and extensive test suites.

Build artifacts, node_modules, external/, and gemini-cli are gitignored.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-23 14:14:09 +03:00

13 KiB

How AITimeMachine Achieves "Time Machine for AI"

Vision: Just like macOS Time Machine lets you restore your computer to before a virus, AITimeMachine lets you restore your code AND AI chat to before any mistake. Canonical reference: ../../NORTH_STAR_PRD_ARCHITECTURE_V1.md.

Architecture baseline used in this document:

  • Backend is the source of truth.
  • Local files are restored/materialized from canonical backend state.
  • Local storage is cache/offline buffer, not canonical state.

🎯 The 7 Goals Explained

Goal 1: Go Back in Time (Restore Files + Chat Context)

How it works:

User: "Go back to 2 hours ago"

MCP → Backend API → Neon Database
    ↓
Backend finds checkpoint from 2 hours ago
    ↓
Returns:
  - All file contents (exact state)
  - All chat messages (conversation history)
  - Context (what AI was working on)
    ↓
MCP restores files locally
    ↓
AI receives chat context and continues from that point

Technical Implementation:

// MCP Tool: tm_go_back
async tm_go_back(timeOrId: string) {
  // 1. Query backend for checkpoint
  const checkpoint = await backend.get('/api/time/restore', {
    time: '2 hours ago'
  });
  
  // 2. Restore all files
  for (const file of checkpoint.files) {
    await fs.writeFile(file.path, file.content);
  }
  
  // 3. Return chat context to AI
  return {
    messages: checkpoint.messages,  // All previous chat
    context: checkpoint.context,    // What AI was doing
    summary: "Restored to 2 hours ago. You were implementing the auth system."
  };
}

Database Query:

-- Find checkpoint from 2 hours ago
SELECT c.*, 
       array_agg(m.*) as messages,
       ctx.summary
FROM checkpoints c
LEFT JOIN messages m ON m.checkpoint_id = c.id
LEFT JOIN contexts ctx ON ctx.checkpoint_id = c.id
WHERE c.timestamp >= NOW() - INTERVAL '2 hours'
ORDER BY c.timestamp DESC
LIMIT 1;

Goal 2: See What Changed (Visual Diff)

How it works:

User: "What changed in the last hour?"

MCP → Backend API
    ↓
Backend queries pre-computed diffs
    ↓
Returns visual diff with:
  - Files added/modified/deleted
  - Line-by-line changes
  - Color-coded output

Technical Implementation:

// MCP Tool: tm_what_changed
async tm_what_changed(since: string) {
  const diff = await backend.get('/api/time/diff', {
    from: 'HEAD~1',
    to: 'HEAD'
  });
  
  return {
    summary: {
      added: ['src/api.ts', 'src/auth.ts'],
      modified: ['package.json'],
      deleted: []
    },
    diffs: [
      {
        file: 'src/api.ts',
        changes: '+50 lines',
        preview: '@@ -0,0 +1,50 @@\n+export const api = ...'
      }
    ]
  };
}

Database Storage:

-- Pre-computed diffs stored for instant retrieval
CREATE TABLE diffs (
  from_checkpoint_id TEXT,
  to_checkpoint_id TEXT,
  file_path TEXT,
  diff_content TEXT,  -- Full unified diff
  stats JSONB         -- {added: 50, removed: 0}
);

Goal 3: Go Back to Exact Time Before AI Error

How it works:

AI makes mistake in chat
    ↓
User: "Go back to before that error"
    ↓
MCP finds the checkpoint BEFORE the bad message
    ↓
Restores code + chat to that exact point

Technical Implementation:

// MCP Tool: tm_before_error
async tm_before_error() {
  // 1. Find last checkpoint before error
  const checkpoint = await backend.get('/api/time/before-error');
  
  // 2. This checkpoint has:
  //    - linked_checkpoint_id pointing to "before_action"
  //    - All files from before the mistake
  //    - Chat history up to (but not including) the error
  
  // 3. Restore everything
  await this.restoreFiles(checkpoint.files);
  
  return {
    messages: checkpoint.messages,
    summary: "Restored to before the error. Last good state was: implementing auth."
  };
}

Database Linking:

-- Every AI action creates TWO checkpoints linked together
INSERT INTO checkpoints VALUES
  ('cp_before_abc', ..., trigger_type: 'before_action'),
  ('cp_after_abc', ..., trigger_type: 'after_action', 
   linked_checkpoint_id: 'cp_before_abc');  -- LINK!

-- To restore before error, just load the "before" checkpoint
SELECT * FROM checkpoints 
WHERE trigger_type = 'before_action' 
  AND linked_checkpoint_id IN (
    SELECT id FROM checkpoints WHERE description LIKE '%error%'
  );

Goal 4: Restore Specific Files (Not Everything)

How it works:

User: "Just restore src/api.ts from yesterday"

MCP → Backend
    ↓
Backend finds file content from yesterday's checkpoint
    ↓
Returns ONLY that file
    ↓
MCP restores only src/api.ts

Technical Implementation:

// MCP Tool: tm_restore_file
async tm_restore_file(path: string, checkpoint: string) {
  // 1. Get specific file from checkpoint
  const file = await backend.get('/api/files/at-checkpoint', {
    checkpoint: checkpoint,
    path: 'src/api.ts'
  });
  
  // 2. Restore only this file
  await fs.writeFile(path, file.content);
  
  return {
    restored: [path],
    size: file.size,
    from: checkpoint
  };
}

Database Query:

-- Get specific file from specific checkpoint
SELECT b.content, cf.size
FROM checkpoint_files cf
JOIN blobs b ON cf.blob_hash = b.hash
WHERE cf.checkpoint_id = 'cp_yesterday_abc'
  AND cf.file_path = 'src/api.ts';

Goal 5: Restore Entire Folder/File/Project

How it works:

User: "Restore the entire src/ folder from last week"

MCP → Backend
    ↓
Backend finds all files in src/ from last week
    ↓
Returns entire directory tree
    ↓
MCP restores all files in src/

Technical Implementation:

// MCP Tool: tm_restore_folder
async tm_restore_folder(pattern: string, checkpoint: string) {
  // 1. Get all files matching pattern
  const files = await backend.get('/api/files/tree', {
    checkpoint: checkpoint,
    pattern: 'src/**'  // Glob pattern
  });
  
  // 2. Restore all files
  for (const file of files) {
    await fs.writeFile(file.path, file.content);
  }
  
  return {
    restored: files.map(f => f.path),
    totalFiles: files.length,
    totalSize: files.reduce((sum, f) => sum + f.size, 0)
  };
}

Database Query:

-- Get all files in a folder from checkpoint
SELECT cf.file_path, b.content, cf.size
FROM checkpoint_files cf
JOIN blobs b ON cf.blob_hash = b.hash
WHERE cf.checkpoint_id = 'cp_lastweek_xyz'
  AND cf.file_path LIKE 'src/%';

Goal 6: Capture Data for AI Model Training

How it works:

Every AI interaction is captured:
  ↓
User message → Saved
AI response → Saved
Tool calls → Saved
Code changes → Saved
Success/Failure → Saved
  ↓
All stored in Neon with metadata
  ↓
Can be exported for AI training

What Gets Captured:

interface TrainingData {
  // Conversation
  userMessage: string;
  aiResponse: string;
  aiThinking: string;  // Internal reasoning
  
  // Actions
  toolCalls: {
    name: string;
    arguments: any;
    result: any;
    success: boolean;
    error?: string;
  }[];
  
  // Code Changes
  before: {
    files: FileSnapshot[];
    context: string;
  };
  after: {
    files: FileSnapshot[];
    diff: string;
  };
  
  // Metadata
  timestamp: Date;
  sessionDuration: number;
  projectType: string;
  success: boolean;
}

Database Schema for Training Data:

-- All data needed for AI training
CREATE TABLE training_sessions (
  id UUID PRIMARY KEY,
  user_id UUID,
  project_id UUID,
  
  -- Conversation
  messages JSONB,  -- Full chat history
  
  -- Actions
  tool_calls JSONB,  -- All tools used
  
  -- Code
  checkpoints_before JSONB,  -- State before
  checkpoints_after JSONB,   -- State after
  diffs JSONB,               -- What changed
  
  -- Outcomes
  success BOOLEAN,
  error_messages TEXT[],
  
  -- Metadata
  session_duration INTEGER,
  project_type TEXT,
  ai_model TEXT,
  timestamp TIMESTAMP
);

-- Export for training
SELECT 
  messages,
  tool_calls,
  diffs,
  success
FROM training_sessions
WHERE success = true  -- Only successful sessions
  AND timestamp > NOW() - INTERVAL '30 days'
LIMIT 10000;

Goal 7: Git-Like Architecture with Full Capture

How it works:

┌─────────────────────────────────────────────────┐
│  User's Environment (VSCode/Claude/Cursor)      │
│                                                  │
│  ┌────────────────────────────────────────┐    │
│  │  AITM MCP Server (Thin Client)         │    │
│  │  • Captures every AI action            │    │
│  │  • Scans files before/after            │    │
│  │  • Sends everything to backend         │    │
│  └────────────┬───────────────────────────┘    │
└───────────────┼──────────────────────────────────┘
                │ HTTPS
                ▼
┌─────────────────────────────────────────────────┐
│  AITM Backend API Server                        │
│  • Receives all data                            │
│  • Computes diffs (Git algorithms)              │
│  • Generates embeddings                         │
│  • Stores in Neon                               │
└────────────┬────────────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────────────┐
│  Neon Database (Postgres)                       │
│                                                  │
│  Git-Like Storage:                              │
│  • Blobs (content-addressable)                  │
│  • Trees (directory structure)                  │
│  • Commits (checkpoints)                        │
│  • Diffs (pre-computed)                         │
│                                                  │
│  AI-Specific Storage:                           │
│  • Messages (all chats)                         │
│  • Tool Calls (all actions)                     │
│  • Contexts (mental states)                     │
│  • Embeddings (for search)                      │
└─────────────────────────────────────────────────┘

Complete Capture Flow:

1. User: "Create an API"
   → MCP captures message
   → POST /api/chats/messages
   
2. MCP: before_action
   → Scans all current files
   → Computes hashes
   → POST /api/actions/before
   → Backend creates checkpoint_before
   
3. AI: Creates src/api.ts
   → File written to disk
   
4. MCP: after_action
   → Scans all files again
   → Detects new file
   → POST /api/actions/after
   → Backend creates checkpoint_after
   
5. Backend Processing:
   → Computes diff (Git histogram algorithm)
   → Generates embeddings (OpenAI)
   → Links: message → before → after
   → Stores everything in Neon
   
6. Result:
   ✅ Full file content saved
   ✅ Diff computed and saved
   ✅ Chat history saved
   ✅ Tool call recorded
   ✅ Context captured
   ✅ Embeddings generated

🚀 The Complete System

MCP Tools (What AI Can Use)

// Time Travel
tm_go_back(time)           // "Go back 2 hours"
tm_undo_last()             // "Undo that"
tm_before_error()          // "Before the mistake"

// Inspection
tm_what_changed(since)     // "What changed?"
tm_diff(from, to)          // "Show me the diff"
tm_timeline()              // "Show history"

// Selective Restore
tm_restore_file(path, chk) // "Restore just api.ts"
tm_restore_folder(pattern) // "Restore src/ folder"

// Intelligence
tm_oracle_ask(question)    // "Where is the auth code?"
tm_search_code(query)      // "Find database connections"

CLI Commands (What Users Can Run)

# Time Travel
aitm back 2h
aitm undo
aitm before-error

# Inspection
aitm diff
aitm timeline
aitm changes

# Selective Restore
aitm restore src/api.ts --from abc123
aitm restore "src/**" --from yesterday

# Intelligence
aitm ask "Where is the auth logic?"
aitm search "database connection"

Backend API (What Stores Everything)

POST /api/chats/messages       # Save every message
POST /api/actions/before       # Before AI action
POST /api/actions/after        # After AI action
POST /api/checkpoints          # Create checkpoint
GET  /api/time/restore         # Restore to point
GET  /api/time/diff            # Get diff
POST /api/files                # Save file content
GET  /api/files/tree           # Get directory
POST /api/oracle/ask           # Ask Oracle

✅ Success: The Vision Realized

macOS Time Machine:

  • Computer got virus → Time Machine → Select date → Restore → Clean computer

AITimeMachine:

  • AI broke code → AITimeMachine → Select checkpoint → Restore → Clean code + chat

Both restore to exact state before the problem! 🎯