# Migration Guide: Foundation v1.x → v2.0

This guide helps you upgrade from Foundation v1.x to v2.0 with **Gaia's advanced memory system**.

**Good news:** v2.0 is **100% backward compatible**. All v1.x tools work identically. The new memory features are additive, not breaking.

---

## Table of Contents

- [Quick Summary](#quick-summary)
- [What Changed](#what-changed)
- [Upgrade Steps](#upgrade-steps)
- [New Features](#new-features)
- [Code Migration Examples](#code-migration-examples)
- [Performance Improvements](#performance-improvements)
- [Breaking Changes](#breaking-changes)
- [Troubleshooting](#troubleshooting)

---

## Quick Summary

### v1.x → v2.0 Changes

| Area | v1.x | v2.0 | Impact |
|------|------|------|--------|
| **Checkpoint tools** | 9 tools | 9 tools + handoff + observe + migrate | ✅ 3 new tools |
| **Learning tools** | 3 tools | Same 3 tools | ✅ No changes |
| **Memory system** | None | 7 new tools | ✅ Additive only |
| **Database** | JSON files | SQLite + FTS5 | ✅ Auto-migrated |
| **Tool prefixes** | `gaia_*` | `gaia_*` | ✅ No changes |
| **Breaking changes** | - | - | ✅ None! |

**TL;DR:** Update the package, restart, start using new memory tools. All existing code works unchanged.

---

## What Changed

### Architecture Evolution

```
Foundation v1.x
├─ Demerzel (9 tools) - Codebase intelligence
├─ Seldon (12 tools) - Multi-agent orchestration
└─ Gaia (9 tools) - Workflow patterns
   ├─ Checkpoints (session state)
   ├─ Learning system (CLAUDE.md)
   └─ JSON file storage

Foundation v2.0
├─ Demerzel (9 tools) - Codebase intelligence
├─ Seldon (12 tools) - Multi-agent orchestration
└─ Gaia (19 tools) - Workflow patterns + Advanced memory
   ├─ Workflow (12 tools) - Same as v1.x + handoff + observe + migrate ⭐
   ├─ Memory (5 tools) - NEW: SQLite + FTS5 + BM25 ⭐
   └─ Linking (2 tools) - NEW: Cross-prompt dependency graphs ⭐
```

### Gaia v2.0 Upgrades

1. **SQLite + FTS5 Backend**
   - Replaces JSON file storage
   - Full-text search with BM25 ranking
   - Production-grade persistence

2. **5-Tier Memory Hierarchy**
   - session (ephemeral)
   - project (cwd-scoped)
   - global (user-wide)
   - note (manual KB)
   - observation (auto-learned)

3. **Cross-Prompt Linking**
   - `depends_on`, `extends`, `reverts`, `related`, `contradicts`
   - Build dependency graphs
   - Trace decision chains

4. **Composite Scoring**
   - BM25 relevance (40%)
   - Recency (25%)
   - Tier priority (15%)
   - File proximity (10%)
   - Access frequency (10%)

5. **Performance**
   - 0.1ms inserts (110x target)
   - 2ms search (25x target)
   - ~1ms get by ID (5x target)

---

## Upgrade Steps

### Step 1: Update Package

```bash
npm install -g @sashabogi/foundation@latest
```

### Step 2: Verify Version

```bash
foundation status
```

Should output:
```
🏛️  Foundation v2.0.0
   Modules: Demerzel (codebase) | Seldon (agents) | Gaia (workflow + memory)
```

### Step 3: Restart Claude Code

```bash
# Restart Claude Code to reload the MCP server
# No configuration changes needed
```

### Step 4: Test Existing Tools

```typescript
// v1.x checkpoint tools still work identically
gaia_checkpoint({
  summary: "Test upgrade",
  decisions: [{ topic: "test", decision: "works", rationale: "testing" }]
})

// Should return success
```

### Step 5: Start Using New Tools

```typescript
// Save a memory
gaia_save({
  tier: "project",
  content: "Successfully upgraded to Foundation v2.0",
  tags: ["upgrade", "milestone"]
})

// Search memories
gaia_search({ query: "upgrade" })
```

**Done!** Your v1.x tools still work, plus you have 11 new memory tools.

---

## New Features

### 1. Persistent Memory with gaia_save

**v1.x approach:**
```typescript
// Only checkpoints - not searchable
gaia_checkpoint({
  summary: "Implemented auth with JWT",
  decisions: [{
    topic: "Authentication",
    decision: "Use JWT with RS256",
    rationale: "Industry standard, secure"
  }]
})
```

**v2.0 approach (recommended):**
```typescript
// Searchable, linkable, persistent
gaia_save({
  tier: "project",
  content: "Decision: Use JWT with RS256 for authentication. Industry standard, secure.",
  tags: ["decision", "auth", "jwt", "security"],
  related_files: ["src/auth/jwt.ts"],
  metadata: { decision_type: "technical", impact: "high" }
})
```

**Benefits:**
- ✅ Full-text search across all decisions
- ✅ Links to related decisions
- ✅ Survives session restarts
- ✅ Ranked by relevance + recency

### 2. Search with gaia_search

```typescript
// Find all authentication-related decisions
gaia_search({
  query: "authentication JWT security",
  tiers: ["project", "global"],
  limit: 10,
  current_file: "src/auth/verify.ts"  // Boosts related memories
})

// Returns ranked results with scores
```

**Search supports:**
- FTS5 syntax: `"exact phrase"`, `word*` (wildcard)
- Tier filtering
- File proximity boosting
- Composite scoring

### 3. Link Memories with gaia_link

```typescript
// Day 1: Make a decision
const decision = gaia_save({
  tier: "project",
  content: "Decision: Use React 18 with TypeScript",
  tags: ["decision", "react"]
})

// Day 2: Implement it
const impl = gaia_save({
  tier: "project",
  content: "Set up React 18 + Vite + TypeScript",
  tags: ["implementation"]
})

// Link them
gaia_link({
  from_memory_id: impl.memory.id,
  to_memory_id: decision.memory.id,
  link_type: "depends_on"
})

// Later: trace dependencies
gaia_graph({ memory_id: impl.memory.id })
// Shows: implementation → depends_on → decision
```

**Link types:**
- `depends_on` - Requires/builds on
- `extends` - Enhances/extends
- `reverts` - Undoes/reverses
- `related` - Associated
- `contradicts` - Conflicts with

### 4. Memory Statistics with gaia_stats

```typescript
gaia_stats()

// Returns:
{
  "total_memories": 247,
  "by_tier": {
    "session": 5,
    "project": 89,
    "global": 42,
    "note": 111,
    "observation": 0
  },
  "total_links": 34,
  "database_size_mb": 0.18,
  "age_range_days": 127
}
```

### 5. Session Handoff with gaia_handoff

**NEW in v2.0:** Create comprehensive handoff documents for session transitions.

```typescript
// At session end - create checkpoint + handoff
gaia_checkpoint({
  summary: "Implemented auth system",
  purpose: "Build secure authentication",
  decisions: [/* ... */],
  progress: [/* ... */],
  changes: [/* ... */]
})

// Generate handoff document
gaia_handoff({
  next_steps: [
    "Implement refresh token rotation",
    "Add rate limiting to login endpoint",
    "Write integration tests for auth flow"
  ],
  context_notes: "Auth system 80% complete. Main work remaining is refresh token security.",
  include_memories: true,
  memory_query: "authentication JWT"
})

// Saves to: ~/.foundation/handoffs/handoff-2026-02-16T10-30-00.md
```

**Handoff document includes:**
- ✅ Current session state from checkpoint
- ✅ Recent decisions with rationales
- ✅ Task progress (completed/in_progress/blocked)
- ✅ Files changed in session
- ✅ Open questions for next session
- ✅ Relevant memories (BM25 ranked)
- ✅ Next steps (user-provided)
- ✅ Additional context notes

**Use cases:**
- Transitioning between work sessions
- Handing off work to team members
- Documenting project state at milestones
- Creating context for future AI sessions

### 6. Autonomous Observation with gaia_observe

**NEW in v2.0:** Automatically detect patterns and anti-patterns from session activity.

```typescript
// Analyze current session for patterns
gaia_observe({
  lookback_days: 30,
  auto_save: true,
  min_confidence: "medium"
})

// Returns detected patterns like:
// 1. 🔴 Repeated decision-making on: Authentication (high confidence)
// 2. 🔴 Task blockers detected (high confidence)
// 3. 🟡 Frequent modifications to: src/auth/jwt.ts (medium)
// 4. 🟡 Multiple open questions - potential knowledge gaps (medium)
// 5. 🔴 High activity in areas: authentication, security (high)
// 6. 🟡 File created and deleted: src/temp/test.ts (medium)
```

**Pattern types detected:**
- ✅ Repeated topics (same decisions multiple times)
- ✅ Task blockers (blocked status in progress tracking)
- ✅ Frequent file changes (same file modified 3+ times)
- ✅ Knowledge gaps (multiple unresolved questions)
- ✅ Activity hotspots (frequent tags in recent memories)
- ✅ Anti-patterns (created then deleted files)

**How it works:**
1. Analyzes latest checkpoint (decisions, progress, changes)
2. Scans recent memories for tag frequency patterns
3. Detects patterns with confidence scoring (low/medium/high)
4. Auto-saves to `observation` tier in memory system
5. Enriches with metadata for future pattern analysis

**Complements manual learning:**
- `gaia_learn` - Manual corrections for CLAUDE.md
- `gaia_observe` - Automatic pattern detection for observations

---

## Code Migration Examples

### Example 1: Architecture Decisions

**v1.x:**
```typescript
// Save decision in checkpoint
gaia_checkpoint({
  summary: "Chose PostgreSQL",
  decisions: [{
    topic: "Database",
    decision: "PostgreSQL with Drizzle ORM",
    rationale: "Type safety, migrations"
  }]
})

// Later - retrieve decisions
gaia_get_decisions()
// Returns all decisions from latest checkpoint
```

**v2.0 (recommended):**
```typescript
// Save as searchable memory
gaia_save({
  tier: "project",
  content: "Database decision: PostgreSQL with Drizzle ORM for type safety and migrations",
  tags: ["decision", "database", "postgresql", "drizzle"],
  related_files: ["drizzle.config.ts", "src/db/schema.ts"],
  metadata: { decision_type: "technical", confidence: "high" }
})

// Later - search decisions
gaia_search({
  query: "database PostgreSQL",
  tiers: ["project"],
  limit: 5
})
// Returns ranked results across all sessions
```

**Benefits:**
- Survives session restarts
- Searchable across all time
- Linkable to implementations
- File-scoped proximity

### Example 2: Session Workflow

**v1.x:**
```typescript
// Session checkpoint
gaia_checkpoint({
  summary: "Fixed login bug",
  changes: [{
    file: "src/auth/login.ts",
    action: "modified",
    summary: "Fixed token validation"
  }]
})
```

**v2.0 (hybrid approach):**
```typescript
// Use both: checkpoint for session state + memory for knowledge
gaia_checkpoint({
  summary: "Fixed login bug",
  changes: [...]
})

// ALSO save as searchable memory
gaia_save({
  tier: "project",
  content: "Bug fix: Token validation was failing on expired tokens. Now returns 401 with clear error message.",
  tags: ["bugfix", "auth", "tokens", "validation"],
  related_files: ["src/auth/login.ts"]
})
```

**Why both?**
- **Checkpoint**: Session-specific state (progress, changes)
- **Memory**: Long-term searchable knowledge

### Example 3: Learning from Mistakes

**v1.x:**
```typescript
// Capture learning
gaia_learn({
  mistake: "Hardcoded API URL",
  correction: "Use environment variables",
  category: "architecture",
  scope: "global"
})

// Apply to CLAUDE.md
gaia_apply()
```

**v2.0 (enhanced):**
```typescript
// Still use v1.x learning tools for CLAUDE.md
gaia_learn({
  mistake: "Hardcoded API URL",
  correction: "Use environment variables",
  category: "architecture",
  scope: "global"
})

gaia_apply()

// ALSO save as searchable memory
gaia_save({
  tier: "global",
  content: "Best practice: Always use environment variables for API URLs. Never hardcode configuration.",
  tags: ["best-practice", "configuration", "environment-variables"],
  metadata: { learned_from: "mistake", severity: "medium" }
})
```

**Benefits:**
- CLAUDE.md gets updated (v1.x behavior)
- Memory is searchable (v2.0 feature)
- Applies globally across projects

---

## Performance Improvements

### Storage Performance

| Operation | v1.x (JSON) | v2.0 (SQLite) | Improvement |
|-----------|-------------|---------------|-------------|
| Save memory | ~5ms | 0.1ms | **50x faster** |
| Search | N/A | 2ms | **NEW** |
| Get by ID | ~2ms | ~1ms | **2x faster** |
| List all | ~10ms | ~3ms | **3x faster** |

### Database Size

| Memories | v1.x (JSON) | v2.0 (SQLite) | Efficiency |
|----------|-------------|---------------|------------|
| 100 | ~0.8 MB | ~0.04 MB | **20x smaller** |
| 1000 | ~8 MB | ~0.43 MB | **18x smaller** |
| 10000 | ~80 MB | ~4.3 MB | **18x smaller** |

### Search Capabilities

| Feature | v1.x | v2.0 |
|---------|------|------|
| Full-text search | ❌ | ✅ FTS5 + BM25 |
| Ranked results | ❌ | ✅ Composite scoring |
| Wildcard search | ❌ | ✅ `word*` |
| Phrase search | ❌ | ✅ `"exact phrase"` |
| Tier filtering | ❌ | ✅ Filter by scope |
| File proximity | ❌ | ✅ Boost by current file |

---

## Breaking Changes

### None!

Foundation v2.0 has **zero breaking changes**. All v1.x code works identically.

### Module Renaming (Informational Only)

Internal module names changed for clarity, but **tool names are unchanged**:

| v1.x Internal | v2.0 Internal | Tool Prefix | Change Impact |
|---------------|---------------|-------------|---------------|
| Argus | Demerzel | `demerzel_*` | ❌ Tool names unchanged |
| Orchestrator | Gaia | `gaia_*` | ❌ Tool names unchanged |
| Seldon | Seldon | `seldon_*` | ❌ No change |

**You don't need to update any code.** The module renames are internal only.

---

## Troubleshooting

### Issue: "Database locked"

**Cause:** Multiple Foundation instances running

**Solution:**
```bash
# Kill all Foundation processes
pkill -f foundation

# Restart Claude Code
```

### Issue: "Memory not found"

**Cause:** Looking for v1.x checkpoint data in v2.0 memory

**Solution:**
```typescript
// v1.x checkpoints still use:
gaia_get_decisions()  // Works in v2.0

// v2.0 memories use:
gaia_search({ query: "..." })  // New in v2.0
```

**They're separate systems** - checkpoints vs. memories.

### Issue: "FTS5 syntax error"

**Cause:** Invalid search query

**Solution:**
```typescript
// ✅ Valid queries
gaia_search({ query: "JWT authentication" })
gaia_search({ query: "auth*" })
gaia_search({ query: '"exact phrase"' })

// ❌ Invalid queries
gaia_search({ query: 'unclosed "quote' })  // Syntax error
```

### Issue: "Slow search performance"

**Cause:** Too many results, no tier filtering

**Solution:**
```typescript
// ❌ Slow (searches all tiers, all time)
gaia_search({ query: "auth", limit: 1000 })

// ✅ Fast (filter by tier, reasonable limit)
gaia_search({
  query: "auth",
  tiers: ["project"],
  limit: 20
})
```

### Issue: "Database file too large"

**Cause:** Too many session-tier memories not cleaned up

**Solution:**
```typescript
// Delete old session memories
gaia_search({ tiers: ["session"] })
// Review results, then:
gaia_delete({ id: "mem_old_session_123" })
```

**Prevention:** Use `tier: "session"` only for truly ephemeral data.

---

## Data Migration

### Automatic Migration

Foundation v2.0 automatically creates the SQLite database on first use. No migration needed.

### Manual Data Preservation

If you want to preserve v1.x checkpoint data:

```bash
# v1.x checkpoints are stored here:
~/.foundation/sessions/

# They still work in v2.0!
# No migration needed.
```

### Migrating v1.x Checkpoints to v2.0 Memories (Automated)

**NEW in v2.0:** Use `gaia_migrate` to automatically convert v1 checkpoint data to v2 memories.

```typescript
// Step 1: Preview what will be migrated (dry run)
gaia_migrate({
  dry_run: true,
  include_checkpoints: true,
  sessions_limit: 10  // Preview first 10 sessions
})

// Returns:
// ## Gaia v1 → v2 Migration (DRY RUN)
//
// ### Checkpoint Migration
// Found 15 session(s)
// Processing 10 session(s)
//
// #### Session: ckpt_abc123
// Project: acme-auth
// Purpose: Build authentication system
//
//   • Decision: Authentication
//   • Decision: Token Storage
//   • Progress: Implement JWT generation
//   • Progress: Add token validation middleware
//
// ---
// ### Migration Summary
// Sessions processed: 10
// Decisions: 23
// Completed tasks: 15
// Total items: 38
//
// ⚠️ DRY RUN MODE - No data was saved

// Step 2: Perform actual migration
gaia_migrate({
  dry_run: false,
  include_checkpoints: true
})

// Returns:
// ✓ Migrated 38 memories to v2 system
//
// Next steps:
// 1. Search migrated data: gaia_search({ query: "migrated-v1", tags: ["migrated-v1"] })
// 2. Verify decisions: gaia_search({ query: "decision", tiers: ["project"] })
// 3. Review in context: Use current_file parameter for proximity boosting

// Step 3: Search your migrated data
gaia_search({
  query: "authentication decision",
  tiers: ["project"],
  limit: 10
})
```

**What gets migrated:**
- ✅ Decisions → `project` tier with tags: `["migrated-v1", "decision", topic-tag]`
- ✅ Completed tasks → `session` tier with tags: `["migrated-v1", "completed", "progress"]`
- ✅ Metadata preserved: original checkpoint ID, timestamps, topics
- ✅ Files linked: relevant_files from checkpoint context
- ✅ Searchable: Full FTS5 + BM25 ranking immediately available

---

## Best Practices for v2.0

### 1. Choose the Right Tier

```typescript
// ✅ Good tier usage
gaia_save({ tier: "session", content: "TODO: Review PR #123" })
gaia_save({ tier: "project", content: "Decision: Use tRPC" })
gaia_save({ tier: "global", content: "Best practice: Always validate input" })
gaia_save({ tier: "note", content: "Tutorial: How to use React Query" })
gaia_save({ tier: "observation", content: "User often forgets to commit .env.example" })

// ❌ Bad tier usage
gaia_save({ tier: "global", content: "TODO: Fix bug" })  // Should be session
gaia_save({ tier: "session", content: "Best practice: ..." })  // Should be global
```

### 2. Tag Strategically

```typescript
// ✅ Good tags (3-5, specific)
tags: ["decision", "database", "postgresql", "architecture"]

// ❌ Bad tags (too many, too generic)
tags: ["tech", "dev", "code", "work", "project", "database", "sql", "data", ...]
```

### 3. Link Related Memories

```typescript
// Save decision
const decision = gaia_save({ tier: "project", content: "..." })

// Save implementation
const impl = gaia_save({ tier: "project", content: "..." })

// Link them
gaia_link({
  from_memory_id: impl.memory.id,
  to_memory_id: decision.memory.id,
  link_type: "depends_on"
})
```

### 4. Use Both Checkpoints and Memories

```typescript
// Checkpoint: Session state
gaia_checkpoint({
  summary: "Implemented feature X",
  progress: [...],
  changes: [...]
})

// Memory: Long-term knowledge
gaia_save({
  tier: "project",
  content: "Feature X uses pattern Y because Z",
  tags: ["implementation", "pattern"]
})
```

---

## Summary

Foundation v2.0 is a **non-breaking upgrade** that adds powerful memory features while preserving all v1.x functionality.

**Upgrade checklist:**
- ✅ Update package: `npm install -g @sashabogi/foundation@latest`
- ✅ Restart Claude Code
- ✅ Test existing tools (they work unchanged)
- ✅ Start using `gaia_save`, `gaia_search`, `gaia_link`
- ✅ Read [README.md](../README.md) for deep dive

**Questions?** Open an issue on [GitHub](https://github.com/sashabogi/foundation/issues).

---

**Welcome to Foundation v2.0!** 🎉