@sashabogi/foundation 0.1.13 → 2.0.0

package/dist/tools/gaia/index.js

@@ -1,39 +1,59 @@
 /**
- * Gaia Module Tools
+ * Gaia Module Tools v2.0
  *
- * Workflow patterns - shared memory and collective consciousness.
+ * Workflow patterns + Advanced memory - collective consciousness.
  * Named after Gaia from Foundation - "We are all one, and one is all."
  *
- * Preserves context across sessions, learns from mistakes, enables
- * seamless handoffs between Claude instances.
+ * v2: SQLite + FTS5 memory system with 5-tier hierarchy and BM25 ranking.
  *
- * Tools:
- * - gaia_worktree_create: Create git worktree with session
- * - gaia_worktree_list: List active worktrees
- * - gaia_worktree_switch: Navigate between worktrees
- * - gaia_worktree_cleanup: Remove stale worktrees
- * - gaia_session_register: Track Claude session purpose
- * - gaia_session_status: View active sessions
- * - gaia_session_handoff: Prepare context for handoff
- * - gaia_session_complete: Mark session as done
+ * Tools (19 total):
+ * Workflow Tools (12):
+ * - gaia_checkpoint: Save full structured state to disk
+ * - gaia_status: Return lightweight index card (~150 tokens)
+ * - gaia_query: Keyword search across checkpoint
+ * - gaia_get_decisions: List architectural decisions
+ * - gaia_get_progress: Task progress summary
+ * - gaia_get_changes: Files changed in session
+ * - gaia_handoff: Create session handoff document (NEW v2.0)
+ * - gaia_observe: Auto-detect patterns and observations (NEW v2.0)
+ * - gaia_migrate: Migrate v1 checkpoint data to v2 (NEW v2.0)
  * - gaia_learn: Record correction for CLAUDE.md
  * - gaia_apply: Write learnings to CLAUDE.md
  * - gaia_review: Review accumulated learnings
- * - gaia_remember: Save context state
- * - gaia_recall: Restore previous context
+ *
+ * Memory Tools (5):
+ * - gaia_save: Save a new memory (SQLite + FTS5)
+ * - gaia_search: Search memories with BM25 + composite scoring
+ * - gaia_get: Get memory by ID
+ * - gaia_delete: Delete memory + cascade links
+ * - gaia_stats: Get memory statistics
+ *
+ * Linking Tools (2):
+ * - gaia_link: Create typed link between memories
+ * - gaia_graph: Get link graph for a memory
  */
 import { z } from 'zod';
 import { nanoid } from 'nanoid';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
 import { StorageService } from '../../services/storage.service.js';
 import { GitService } from '../../services/git.service.js';
-const SessionTaskTypeSchema = z.enum([
-    'feature',
-    'bugfix',
-    'refactor',
-    'review',
-    'exploration',
-    'documentation',
-]);
+import { MemoriaStorage } from './storage.js';
+// =============================================================================
+// Memory Storage (v2.0)
+// =============================================================================
+let memoryStorage = null;
+function getMemoryStorage() {
+    if (!memoryStorage) {
+        const dbPath = join(homedir(), '.foundation', 'gaia-memory.db');
+        memoryStorage = new MemoriaStorage(dbPath);
+    }
+    return memoryStorage;
+}
+// =============================================================================
+// Zod Schemas
+// =============================================================================
 const LearningCategorySchema = z.enum([
     'code_style',
     'architecture',
@@ -46,236 +66,863 @@ const LearningCategorySchema = z.enum([
     'other',
 ]);
 const LearningScopeSchema = z.enum(['global', 'project']);
+const CheckpointDecisionSchema = z.object({
+    topic: z.string(),
+    decision: z.string(),
+    rationale: z.string(),
+    timestamp: z.number().optional(),
+});
+const CheckpointProgressSchema = z.object({
+    task: z.string(),
+    status: z.enum(['pending', 'in_progress', 'completed', 'blocked']),
+    details: z.string().optional(),
+});
+const CheckpointChangeSchema = z.object({
+    file: z.string(),
+    action: z.enum(['created', 'modified', 'deleted']),
+    summary: z.string(),
+});
+const CheckpointContextSchema = z.object({
+    branch: z.string().optional(),
+    openQuestions: z.array(z.string()).optional(),
+    relevantFiles: z.array(z.string()).optional(),
+    notes: z.string().optional(),
+});
+// =============================================================================
+// Helper Functions
+// =============================================================================
+function getSessionsDir() {
+    return join(process.cwd(), '.foundation', 'sessions');
+}
+function ensureDir(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+function generateIndexCard(checkpoint) {
+    const lines = [];
+    lines.push(`# ${checkpoint.purpose}`);
+    lines.push(`Project: ${checkpoint.project || 'unknown'} | Branch: ${checkpoint.sections.context.branch || '?'}`);
+    lines.push(`Saved: ${new Date(checkpoint.createdAt).toISOString().slice(0, 16)}`);
+    lines.push('');
+    lines.push(checkpoint.summary);
+    lines.push('');
+    const { decisions, progress, changes, context } = checkpoint.sections;
+    const completed = progress.filter(p => p.status === 'completed').length;
+    const total = progress.length;
+    lines.push(`Progress: ${completed}/${total} tasks | ${decisions.length} decisions | ${changes.length} files changed`);
+    if (context.openQuestions && context.openQuestions.length > 0) {
+        lines.push(`Open questions: ${context.openQuestions.length}`);
+    }
+    // Hard cap: keep under ~200 tokens (roughly 150 words / 800 chars)
+    const result = lines.join('\n');
+    if (result.length > 800) {
+        return result.slice(0, 797) + '...';
+    }
+    return result;
+}
+function readJsonFile(filePath) {
+    try {
+        if (!existsSync(filePath))
+            return null;
+        const raw = readFileSync(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+// =============================================================================
+// Tool Registration
+// =============================================================================
 export function registerGaiaTools(server) {
     const storage = StorageService.getInstance();
     const git = GitService.getInstance();
     // ===========================================================================
-    // Worktree Tools
+    // Checkpoint Tools (v2)
     // ===========================================================================
-    // gaia_worktree_create
-    server.tool('gaia_worktree_create', 'Create a git worktree for parallel Claude sessions. Returns shell alias for quick navigation.', {
-        branch: z.string().describe('Branch name for the worktree'),
-        alias: z.string().optional().describe('Single letter alias for quick switching (e.g., "a" for `za`)'),
-        purpose: z.string().optional().describe('Purpose of this worktree'),
-        baseBranch: z.string().optional().describe('Base branch (default: main)'),
-    }, async ({ branch, alias, purpose, baseBranch = 'main' }) => {
+    // gaia_checkpoint — Save full structured state to disk
+    server.tool('gaia_checkpoint', 'Save full session state to disk. The ONLY write operation. Creates checkpoint.json, index.txt, and decisions.json in .foundation/sessions/latest/.', {
+        summary: z.string().describe('One-line summary of current state (~20 words)'),
+        purpose: z.string().describe('What this session is working on'),
+        project: z.string().optional().describe('Project name'),
+        decisions: z.array(CheckpointDecisionSchema).optional().describe('Architectural decisions made'),
+        progress: z.array(CheckpointProgressSchema).optional().describe('Task progress'),
+        changes: z.array(CheckpointChangeSchema).optional().describe('Files changed'),
+        context: CheckpointContextSchema.optional().describe('Additional context (branch, questions, files)'),
+    }, async ({ summary, purpose, project, decisions = [], progress = [], changes = [], context = {} }) => {
         try {
-            const repoRoot = await git.getRepoRoot();
-            const worktreePath = `${repoRoot}-${alias || branch.split('/').pop()}`;
-            await git.createWorktree(worktreePath, branch, { baseBranch });
-            const worktree = {
-                id: `wt_${nanoid(8)}`,
-                path: worktreePath,
-                branch,
-                baseBranch,
-                alias,
-                purpose,
-                status: 'active',
+            // Auto-fill branch from git if not provided
+            let branch = context.branch;
+            if (!branch) {
+                try {
+                    branch = await git.getCurrentBranch();
+                }
+                catch {
+                    branch = undefined;
+                }
+            }
+            const sections = {
+                decisions: decisions.map(d => ({
+                    ...d,
+                    timestamp: d.timestamp || Date.now(),
+                })),
+                progress,
+                changes,
+                context: { ...context, branch },
+            };
+            const checkpoint = {
+                id: `ckpt_${nanoid(8)}`,
+                version: 1,
                 createdAt: Date.now(),
-                lastAccessedAt: Date.now(),
+                project,
+                summary,
+                purpose,
+                sections,
             };
-            storage.addWorktree(worktree);
-            let output = `✓ Created worktree at ${worktreePath}\n\n`;
-            if (alias) {
-                output += `Shell alias: \`alias z${alias}='cd ${worktreePath} && claude'\`\n`;
-            }
-            output += `\nTo navigate: \`cd ${worktreePath}\``;
+            // Write to .foundation/sessions/latest/
+            const latestDir = join(getSessionsDir(), 'latest');
+            ensureDir(latestDir);
+            // 1. Full checkpoint
+            writeFileSync(join(latestDir, 'checkpoint.json'), JSON.stringify(checkpoint, null, 2), 'utf-8');
+            // 2. Index card (~150 tokens)
+            const indexCard = generateIndexCard(checkpoint);
+            writeFileSync(join(latestDir, 'index.txt'), indexCard, 'utf-8');
+            // 3. Decisions extract
+            writeFileSync(join(latestDir, 'decisions.json'), JSON.stringify(sections.decisions, null, 2), 'utf-8');
+            // Also archive by ID
+            const archiveDir = join(getSessionsDir(), checkpoint.id);
+            ensureDir(archiveDir);
+            writeFileSync(join(archiveDir, 'checkpoint.json'), JSON.stringify(checkpoint, null, 2), 'utf-8');
+            writeFileSync(join(archiveDir, 'index.txt'), indexCard, 'utf-8');
+            writeFileSync(join(archiveDir, 'decisions.json'), JSON.stringify(sections.decisions, null, 2), 'utf-8');
             return {
-                content: [{ type: 'text', text: output }],
+                content: [{
+                        type: 'text',
+                        text: `✓ Checkpoint saved: ${checkpoint.id}\n\n${indexCard}`,
+                    }],
             };
         }
         catch (error) {
             return {
-                content: [{ type: 'text', text: `Error: ${error.message}` }],
+                content: [{ type: 'text', text: `Error saving checkpoint: ${error.message}` }],
             };
         }
     });
-    // gaia_worktree_list
-    server.tool('gaia_worktree_list', 'List all active worktrees with their status and session info.', {}, async () => {
-        const worktrees = storage.getWorktrees();
-        if (worktrees.length === 0) {
+    // gaia_status — Return lightweight index card only
+    server.tool('gaia_status', 'Return the index card for the latest checkpoint (~150 tokens). Use this at session start to understand context without loading full state.', {}, async () => {
+        const indexPath = join(getSessionsDir(), 'latest', 'index.txt');
+        if (!existsSync(indexPath)) {
             return {
-                content: [{ type: 'text', text: 'No active worktrees.' }],
+                content: [{ type: 'text', text: 'No checkpoint found. Use gaia_checkpoint to save session state.' }],
             };
         }
-        let output = '## Active Worktrees\n\n';
-        for (const wt of worktrees) {
-            output += `### ${wt.alias ? `[${wt.alias}] ` : ''}${wt.branch}\n`;
-            output += `- Path: \`${wt.path}\`\n`;
-            output += `- Status: ${wt.status}\n`;
-            if (wt.purpose)
-                output += `- Purpose: ${wt.purpose}\n`;
-            output += '\n';
-        }
+        const indexCard = readFileSync(indexPath, 'utf-8');
         return {
-            content: [{ type: 'text', text: output }],
+            content: [{ type: 'text', text: indexCard }],
         };
     });
-    // gaia_worktree_switch
-    server.tool('gaia_worktree_switch', 'Get the command to switch to a worktree by alias or branch.', {
-        target: z.string().describe('Worktree alias or branch name'),
-    }, async ({ target }) => {
-        const worktree = storage.getWorktreeByAlias(target) ||
-            storage.getWorktrees().find((w) => w.branch.includes(target));
-        if (!worktree) {
+    // gaia_query — Keyword search across checkpoint
+    server.tool('gaia_query', 'Search the latest checkpoint by keyword. Returns only matching sections to minimize token usage.', {
+        keyword: z.string().describe('Keyword or phrase to search for (case-insensitive)'),
+        section: z.enum(['decisions', 'progress', 'changes', 'context']).optional().describe('Limit search to a specific section'),
+    }, async ({ keyword, section }) => {
+        const checkpoint = readJsonFile(join(getSessionsDir(), 'latest', 'checkpoint.json'));
+        if (!checkpoint) {
+            return {
+                content: [{ type: 'text', text: 'No checkpoint found. Use gaia_checkpoint to save session state.' }],
+            };
+        }
+        const kw = keyword.toLowerCase();
+        const results = [];
+        const searchIn = section ? [section] : ['decisions', 'progress', 'changes', 'context'];
+        for (const s of searchIn) {
+            if (s === 'decisions') {
+                const matches = checkpoint.sections.decisions.filter(d => d.topic.toLowerCase().includes(kw) ||
+                    d.decision.toLowerCase().includes(kw) ||
+                    d.rationale.toLowerCase().includes(kw));
+                if (matches.length > 0) {
+                    results.push(`## Decisions (${matches.length} matches)`);
+                    for (const m of matches) {
+                        results.push(`- **${m.topic}**: ${m.decision}`);
+                        results.push(`  _Rationale_: ${m.rationale}`);
+                    }
+                }
+            }
+            if (s === 'progress') {
+                const matches = checkpoint.sections.progress.filter(p => p.task.toLowerCase().includes(kw) ||
+                    (p.details?.toLowerCase().includes(kw) ?? false));
+                if (matches.length > 0) {
+                    results.push(`## Progress (${matches.length} matches)`);
+                    for (const m of matches) {
+                        results.push(`- [${m.status}] ${m.task}${m.details ? `: ${m.details}` : ''}`);
+                    }
+                }
+            }
+            if (s === 'changes') {
+                const matches = checkpoint.sections.changes.filter(c => c.file.toLowerCase().includes(kw) ||
+                    c.summary.toLowerCase().includes(kw));
+                if (matches.length > 0) {
+                    results.push(`## Changes (${matches.length} matches)`);
+                    for (const m of matches) {
+                        results.push(`- ${m.action} \`${m.file}\`: ${m.summary}`);
+                    }
+                }
+            }
+            if (s === 'context') {
+                const ctx = checkpoint.sections.context;
+                const ctxMatches = [];
+                if (ctx.branch?.toLowerCase().includes(kw))
+                    ctxMatches.push(`Branch: ${ctx.branch}`);
+                if (ctx.notes?.toLowerCase().includes(kw))
+                    ctxMatches.push(`Notes: ${ctx.notes}`);
+                if (ctx.openQuestions) {
+                    const qMatches = ctx.openQuestions.filter(q => q.toLowerCase().includes(kw));
+                    if (qMatches.length > 0)
+                        ctxMatches.push(`Questions: ${qMatches.join('; ')}`);
+                }
+                if (ctx.relevantFiles) {
+                    const fMatches = ctx.relevantFiles.filter(f => f.toLowerCase().includes(kw));
+                    if (fMatches.length > 0)
+                        ctxMatches.push(`Files: ${fMatches.join(', ')}`);
+                }
+                if (ctxMatches.length > 0) {
+                    results.push(`## Context (${ctxMatches.length} matches)`);
+                    results.push(...ctxMatches.map(m => `- ${m}`));
+                }
+            }
+        }
+        if (results.length === 0) {
             return {
-                content: [{ type: 'text', text: `No worktree found for "${target}"` }],
+                content: [{ type: 'text', text: `No matches for "${keyword}" in checkpoint.` }],
             };
         }
-        storage.updateWorktree(worktree.id, { lastAccessedAt: Date.now() });
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `To switch: \`cd ${worktree.path} && claude\``,
-                },
-            ],
+            content: [{ type: 'text', text: results.join('\n') }],
         };
     });
-    // gaia_worktree_cleanup
-    server.tool('gaia_worktree_cleanup', 'Remove stale or completed worktrees.', {
-        target: z.string().optional().describe('Specific worktree ID or alias to remove'),
-        staleOnly: z.boolean().optional().describe('Only remove stale worktrees (default: false)'),
-    }, async ({ target, staleOnly = false }) => {
-        // TODO: Implement cleanup logic
+    // gaia_get_decisions — List architectural decisions
+    server.tool('gaia_get_decisions', 'Get all architectural decisions from the latest checkpoint. Reads decisions.json directly.', {}, async () => {
+        const decisions = readJsonFile(join(getSessionsDir(), 'latest', 'decisions.json'));
+        if (!decisions || decisions.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No decisions recorded. Use gaia_checkpoint to save decisions.' }],
+            };
+        }
+        let output = `## Decisions (${decisions.length})\n\n`;
+        for (const d of decisions) {
+            output += `### ${d.topic}\n`;
+            output += `**Decision**: ${d.decision}\n`;
+            output += `**Rationale**: ${d.rationale}\n`;
+            output += `_${new Date(d.timestamp).toISOString().slice(0, 16)}_\n\n`;
+        }
         return {
-            content: [{ type: 'text', text: '[Stub] Would cleanup worktrees' }],
+            content: [{ type: 'text', text: output }],
         };
     });
-    // ===========================================================================
-    // Session Tools
-    // ===========================================================================
-    // gaia_session_register
-    server.tool('gaia_session_register', 'Register a new Claude session with its purpose for tracking. "We are all one."', {
-        purpose: z.string().describe('What this session is working on'),
-        taskType: SessionTaskTypeSchema.describe('Type of task'),
-        project: z.string().optional().describe('Project name'),
-        worktreeId: z.string().optional().describe('Associated worktree ID'),
-    }, async ({ purpose, taskType, project, worktreeId }) => {
-        const session = {
-            id: `sess_${nanoid(8)}`,
-            purpose,
-            taskType,
-            project,
-            worktreeId,
-            status: 'active',
-            notes: [],
-            startedAt: Date.now(),
-            lastActivityAt: Date.now(),
-        };
-        storage.addSession(session);
+    // gaia_get_progress — Task progress summary
+    server.tool('gaia_get_progress', 'Get task progress from the latest checkpoint.', {}, async () => {
+        const checkpoint = readJsonFile(join(getSessionsDir(), 'latest', 'checkpoint.json'));
+        if (!checkpoint) {
+            return {
+                content: [{ type: 'text', text: 'No checkpoint found. Use gaia_checkpoint to save session state.' }],
+            };
+        }
+        const { progress } = checkpoint.sections;
+        if (progress.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No tasks tracked. Use gaia_checkpoint with progress data.' }],
+            };
+        }
+        const completed = progress.filter(p => p.status === 'completed').length;
+        const inProgress = progress.filter(p => p.status === 'in_progress').length;
+        const blocked = progress.filter(p => p.status === 'blocked').length;
+        const pending = progress.filter(p => p.status === 'pending').length;
+        let output = `## Progress: ${completed}/${progress.length} complete\n\n`;
+        output += `Completed: ${completed} | In progress: ${inProgress} | Blocked: ${blocked} | Pending: ${pending}\n\n`;
+        for (const p of progress) {
+            const icon = p.status === 'completed' ? '✓' : p.status === 'in_progress' ? '→' : p.status === 'blocked' ? '✗' : '○';
+            output += `${icon} [${p.status}] ${p.task}`;
+            if (p.details)
+                output += ` — ${p.details}`;
+            output += '\n';
+        }
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `✓ Session registered: ${session.id}\n\nPurpose: ${purpose}\nType: ${taskType}`,
-                },
-            ],
+            content: [{ type: 'text', text: output }],
         };
     });
-    // gaia_session_status
-    server.tool('gaia_session_status', 'View status of active sessions.', {
-        sessionId: z.string().optional().describe('Specific session ID (or show all active)'),
-    }, async ({ sessionId }) => {
-        if (sessionId) {
-            const session = storage.getSession(sessionId);
-            if (!session) {
-                return {
-                    content: [{ type: 'text', text: `Session not found: ${sessionId}` }],
-                };
-            }
+    // gaia_get_changes — Files changed in session
+    server.tool('gaia_get_changes', 'Get files changed from the latest checkpoint.', {}, async () => {
+        const checkpoint = readJsonFile(join(getSessionsDir(), 'latest', 'checkpoint.json'));
+        if (!checkpoint) {
             return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `## Session ${session.id}\n\n- Purpose: ${session.purpose}\n- Status: ${session.status}\n- Type: ${session.taskType}`,
-                    },
-                ],
+                content: [{ type: 'text', text: 'No checkpoint found. Use gaia_checkpoint to save session state.' }],
             };
         }
-        const sessions = storage.getActiveSessions();
-        if (sessions.length === 0) {
+        const { changes } = checkpoint.sections;
+        if (changes.length === 0) {
             return {
-                content: [{ type: 'text', text: 'No active sessions.' }],
+                content: [{ type: 'text', text: 'No changes tracked. Use gaia_checkpoint with changes data.' }],
             };
         }
-        let output = '## Active Sessions\n\n';
-        for (const s of sessions) {
-            output += `- **${s.id}**: ${s.purpose} (${s.status})\n`;
+        let output = `## Changes (${changes.length} files)\n\n`;
+        for (const c of changes) {
+            output += `- **${c.action}** \`${c.file}\`: ${c.summary}\n`;
         }
         return {
             content: [{ type: 'text', text: output }],
         };
     });
-    // gaia_session_handoff
-    server.tool('gaia_session_handoff', 'Generate a handoff document for transferring context to another session.', {
-        sessionId: z.string().describe('Session ID to create handoff for'),
-        includeGitStatus: z.boolean().optional().describe('Include git status (default: true)'),
-        includeChanges: z.boolean().optional().describe('Include recent changes (default: true)'),
-        nextSteps: z.array(z.string()).optional().describe('Next steps to include'),
-    }, async ({ sessionId, includeGitStatus = true, includeChanges = true, nextSteps = [] }) => {
-        const session = storage.getSession(sessionId);
-        if (!session) {
-            return {
-                content: [{ type: 'text', text: `Session not found: ${sessionId}` }],
-            };
-        }
-        let handoff = `# Session Handoff: ${session.id}\n\n`;
-        handoff += `## Purpose\n${session.purpose}\n\n`;
-        handoff += `## Type\n${session.taskType}\n\n`;
-        if (includeGitStatus) {
-            try {
-                const status = await git.getStatus();
-                handoff += `## Git Status\n`;
-                handoff += `- Branch: ${status.branch}\n`;
-                if (status.staged.length)
-                    handoff += `- Staged: ${status.staged.length} files\n`;
-                if (status.modified.length)
-                    handoff += `- Modified: ${status.modified.length} files\n`;
-                handoff += '\n';
+    // ===========================================================================
+    // Session Handoff Tool (v2)
+    // ===========================================================================
+    // gaia_handoff — Create session handoff document
+    server.tool('gaia_handoff', 'Create a comprehensive handoff document for transferring session context to the next session. Combines checkpoint data with relevant memories.', {
+        next_steps: z.array(z.string()).describe('List of next steps for the next session'),
+        context_notes: z.string().optional().describe('Additional context notes for the next session'),
+        include_memories: z.boolean().optional().describe('Include relevant memories from memory system (default: true)'),
+        memory_query: z.string().optional().describe('Query to find relevant memories (default: recent project memories)'),
+    }, async ({ next_steps, context_notes, include_memories = true, memory_query }) => {
+        try {
+            const handoffDir = join(homedir(), '.foundation', 'handoffs');
+            ensureDir(handoffDir);
+            // Read latest checkpoint if exists
+            const latestDir = join(getSessionsDir(), 'latest');
+            const checkpoint = readJsonFile(join(latestDir, 'checkpoint.json'));
+            // Build handoff document
+            const lines = [];
+            lines.push('# Session Handoff Document');
+            lines.push('');
+            lines.push(`Generated: ${new Date().toISOString()}`);
+            lines.push('');
+            lines.push('---');
+            lines.push('');
+            // Session state
+            if (checkpoint) {
+                lines.push('## Current Session State');
+                lines.push('');
+                lines.push(`**Project**: ${checkpoint.project || 'N/A'}`);
+                lines.push(`**Purpose**: ${checkpoint.purpose}`);
+                lines.push(`**Branch**: ${checkpoint.sections.context.branch || 'N/A'}`);
+                lines.push('');
+                lines.push(`**Summary**: ${checkpoint.summary}`);
+                lines.push('');
+                // Decisions
+                if (checkpoint.sections.decisions.length > 0) {
+                    lines.push('### Recent Decisions');
+                    lines.push('');
+                    checkpoint.sections.decisions.forEach(d => {
+                        lines.push(`**${d.topic}**`);
+                        lines.push(`- Decision: ${d.decision}`);
+                        lines.push(`- Rationale: ${d.rationale}`);
+                        lines.push('');
+                    });
+                }
+                // Progress
+                if (checkpoint.sections.progress.length > 0) {
+                    lines.push('### Task Progress');
+                    lines.push('');
+                    checkpoint.sections.progress.forEach(p => {
+                        const emoji = p.status === 'completed' ? '✓' : p.status === 'in_progress' ? '⏳' : p.status === 'blocked' ? '🚫' : '○';
+                        lines.push(`${emoji} **${p.task}** (${p.status})`);
+                        if (p.details)
+                            lines.push(`  ${p.details}`);
+                        lines.push('');
+                    });
+                }
+                // Changes
+                if (checkpoint.sections.changes.length > 0) {
+                    lines.push('### Files Changed');
+                    lines.push('');
+                    checkpoint.sections.changes.forEach(c => {
+                        const emoji = c.action === 'created' ? '+' : c.action === 'modified' ? '~' : '-';
+                        lines.push(`${emoji} \`${c.file}\`: ${c.summary}`);
+                    });
+                    lines.push('');
+                }
+                // Open questions
+                if (checkpoint.sections.context.openQuestions && checkpoint.sections.context.openQuestions.length > 0) {
+                    lines.push('### Open Questions');
+                    lines.push('');
+                    checkpoint.sections.context.openQuestions.forEach(q => {
+                        lines.push(`- ${q}`);
+                    });
+                    lines.push('');
+                }
+                // Relevant files
+                if (checkpoint.sections.context.relevantFiles && checkpoint.sections.context.relevantFiles.length > 0) {
+                    lines.push('### Relevant Files');
+                    lines.push('');
+                    checkpoint.sections.context.relevantFiles.forEach(f => {
+                        lines.push(`- \`${f}\``);
+                    });
+                    lines.push('');
+                }
+                // Context notes from checkpoint
+                if (checkpoint.sections.context.notes) {
+                    lines.push('### Context Notes');
+                    lines.push('');
+                    lines.push(checkpoint.sections.context.notes);
+                    lines.push('');
+                }
+            }
+            else {
+                lines.push('## Current Session State');
+                lines.push('');
+                lines.push('_No checkpoint found for current session._');
+                lines.push('');
             }
-            catch {
-                // Not in a git repo
+            // Relevant memories
+            if (include_memories) {
+                lines.push('---');
+                lines.push('');
+                lines.push('## Relevant Memories');
+                lines.push('');
+                try {
+                    const storage = getMemoryStorage();
+                    const query = memory_query || (checkpoint?.project || 'project');
+                    const memories = storage.search({
+                        query,
+                        tiers: ['project', 'session'],
+                        limit: 10,
+                    });
+                    if (memories.length > 0) {
+                        memories.forEach((result, idx) => {
+                            lines.push(`### ${idx + 1}. ${result.memory.content.substring(0, 100)}...`);
+                            lines.push('');
+                            lines.push(`- **Tier**: ${result.memory.tier}`);
+                            lines.push(`- **Tags**: ${result.memory.tags.join(', ')}`);
+                            lines.push(`- **Relevance**: ${result.score.toFixed(2)}`);
+                            if (result.memory.related_files.length > 0) {
+                                lines.push(`- **Files**: ${result.memory.related_files.join(', ')}`);
+                            }
+                            lines.push('');
+                            lines.push(result.memory.content);
+                            lines.push('');
+                        });
+                    }
+                    else {
+                        lines.push('_No relevant memories found._');
+                        lines.push('');
+                    }
+                }
+                catch (error) {
+                    lines.push('_Error retrieving memories._');
+                    lines.push('');
+                }
             }
+            // Next steps
+            lines.push('---');
+            lines.push('');
+            lines.push('## Next Steps');
+            lines.push('');
+            next_steps.forEach((step, idx) => {
+                lines.push(`${idx + 1}. ${step}`);
+            });
+            lines.push('');
+            // Additional context
+            if (context_notes) {
+                lines.push('---');
+                lines.push('');
+                lines.push('## Additional Context');
+                lines.push('');
+                lines.push(context_notes);
+                lines.push('');
+            }
+            // Footer
+            lines.push('---');
+            lines.push('');
+            lines.push('*Generated by Foundation Gaia v2.0*');
+            const handoffContent = lines.join('\n');
+            const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+            const filename = `handoff-${timestamp}.md`;
+            const filePath = join(handoffDir, filename);
+            writeFileSync(filePath, handoffContent, 'utf-8');
+            return {
+                content: [{
+                        type: 'text',
+                        text: `✓ Handoff document created: ${filename}\n\nPath: ${filePath}\n\n${handoffContent.substring(0, 500)}...\n\n[Full document saved to file]`,
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Error creating handoff: ${error.message}`,
+                    }],
+                isError: true,
+            };
         }
-        if (nextSteps.length > 0) {
-            handoff += `## Next Steps\n`;
-            for (const step of nextSteps) {
-                handoff += `- ${step}\n`;
+    });
+    // ===========================================================================
+    // Autonomous Observation System (v2)
+    // ===========================================================================
+    /**
+     * Analyze session patterns and detect observations
+     */
+    function analyzeSessionPatterns(options) {
+        const observations = [];
+        const { checkpoint, lookback_days = 30 } = options;
+        try {
+            const memStorage = getMemoryStorage();
+            const cutoffTime = Date.now() - (lookback_days * 24 * 60 * 60 * 1000);
+            // Pattern 1: Repeated topics in decisions
+            if (checkpoint && checkpoint.sections.decisions.length > 0) {
+                const topics = checkpoint.sections.decisions.map(d => d.topic);
+                const topicCounts = new Map();
+                topics.forEach(t => topicCounts.set(t, (topicCounts.get(t) || 0) + 1));
+                topicCounts.forEach((count, topic) => {
+                    if (count >= 2) {
+                        observations.push({
+                            pattern: `Repeated decision-making on: ${topic}`,
+                            evidence: `${count} decisions made about ${topic} in current session`,
+                            confidence: count >= 3 ? 'high' : 'medium',
+                        });
+                    }
+                });
+            }
+            // Pattern 2: Blocked tasks
+            if (checkpoint && checkpoint.sections.progress.length > 0) {
+                const blockedTasks = checkpoint.sections.progress.filter(p => p.status === 'blocked');
+                if (blockedTasks.length > 0) {
+                    const blockers = blockedTasks.map(t => `"${t.task}"`).join(', ');
+                    observations.push({
+                        pattern: 'Task blockers detected',
+                        evidence: `${blockedTasks.length} blocked task(s): ${blockers}`,
+                        confidence: 'high',
+                    });
+                }
+            }
+            // Pattern 3: Frequent file changes
+            if (checkpoint && checkpoint.sections.changes.length > 0) {
+                const files = checkpoint.sections.changes.map(c => c.file);
+                const fileCounts = new Map();
+                files.forEach(f => fileCounts.set(f, (fileCounts.get(f) || 0) + 1));
+                fileCounts.forEach((count, file) => {
+                    if (count >= 3) {
+                        observations.push({
+                            pattern: `Frequent modifications to: ${file}`,
+                            evidence: `${count} changes to ${file} in current session`,
+                            confidence: 'medium',
+                        });
+                    }
+                });
+            }
+            // Pattern 4: Open questions (knowledge gaps)
+            if (checkpoint && checkpoint.sections.context.openQuestions && checkpoint.sections.context.openQuestions.length > 0) {
+                const questions = checkpoint.sections.context.openQuestions;
+                if (questions.length >= 3) {
+                    observations.push({
+                        pattern: 'Multiple open questions - potential knowledge gaps',
+                        evidence: `${questions.length} unresolved questions: ${questions.slice(0, 2).join('; ')}${questions.length > 2 ? '...' : ''}`,
+                        confidence: 'medium',
+                    });
+                }
+            }
+            // Pattern 5: Frequent tags in recent memories
+            const allMemories = memStorage.search({
+                query: '*',
+                tiers: ['project', 'session'],
+                limit: 100,
+            });
+            const recentMemories = allMemories.filter(m => m.memory.created_at >= cutoffTime);
+            if (recentMemories.length >= 5) {
+                const tagCounts = new Map();
+                recentMemories.forEach(m => {
+                    m.memory.tags.forEach(tag => {
+                        tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
+                    });
+                });
+                const sortedTags = Array.from(tagCounts.entries())
+                    .sort((a, b) => b[1] - a[1])
+                    .slice(0, 3);
+                if (sortedTags.length > 0 && sortedTags[0][1] >= 5) {
+                    const topTags = sortedTags.map(([tag, count]) => `${tag} (${count}x)`).join(', ');
+                    observations.push({
+                        pattern: `High activity in areas: ${sortedTags.map(t => t[0]).join(', ')}`,
+                        evidence: `Frequent tags in recent memories: ${topTags}`,
+                        confidence: 'high',
+                    });
+                }
+            }
+            // Pattern 6: Reverted changes (created then deleted)
+            if (checkpoint && checkpoint.sections.changes.length >= 2) {
+                const fileActions = new Map();
+                checkpoint.sections.changes.forEach(c => {
+                    if (!fileActions.has(c.file))
+                        fileActions.set(c.file, []);
+                    fileActions.get(c.file).push(c.action);
+                });
+                fileActions.forEach((actions, file) => {
+                    if (actions.includes('created') && actions.includes('deleted')) {
+                        observations.push({
+                            pattern: `File created and deleted: ${file}`,
+                            evidence: 'May indicate trial-and-error or false start',
+                            confidence: 'medium',
+                        });
+                    }
+                });
             }
         }
-        return {
-            content: [{ type: 'text', text: handoff }],
-        };
+        catch (error) {
+            // Silently fail pattern analysis - don't break the tool
+        }
+        return observations;
+    }
+    // gaia_observe — Analyze patterns and auto-save observations
+    server.tool('gaia_observe', 'Analyze session patterns and automatically capture observations. Detects recurring patterns, blockers, knowledge gaps, and anti-patterns.', {
+        lookback_days: z.number().optional().describe('Days of history to analyze (default: 30)'),
+        auto_save: z.boolean().optional().describe('Automatically save observations to memory (default: true)'),
+        min_confidence: z.enum(['low', 'medium', 'high']).optional().describe('Minimum confidence level to save (default: medium)'),
+    }, async ({ lookback_days = 30, auto_save = true, min_confidence = 'medium' }) => {
+        try {
+            // Read latest checkpoint
+            const latestDir = join(getSessionsDir(), 'latest');
+            const checkpoint = readJsonFile(join(latestDir, 'checkpoint.json'));
+            // Analyze patterns
+            const patterns = analyzeSessionPatterns({ checkpoint, lookback_days });
+            if (patterns.length === 0) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: '✓ Analysis complete - no significant patterns detected.',
+                        }],
+                };
+            }
+            // Filter by confidence
+            const confidenceLevels = { low: 1, medium: 2, high: 3 };
+            const minLevel = confidenceLevels[min_confidence];
+            const filteredPatterns = patterns.filter(p => confidenceLevels[p.confidence] >= minLevel);
+            if (filteredPatterns.length === 0) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `✓ Analysis complete - ${patterns.length} pattern(s) found but none meet ${min_confidence} confidence threshold.`,
+                        }],
+                };
+            }
+            // Build response
+            const lines = [];
+            lines.push(`## Observations Detected (${filteredPatterns.length})`);
+            lines.push('');
+            const savedObservations = [];
+            // Auto-save observations if enabled
+            if (auto_save) {
+                const memStorage = getMemoryStorage();
+                filteredPatterns.forEach((obs, idx) => {
+                    const confidenceEmoji = obs.confidence === 'high' ? '🔴' : obs.confidence === 'medium' ? '🟡' : '🟢';
+                    lines.push(`${idx + 1}. ${confidenceEmoji} **${obs.pattern}**`);
+                    lines.push(`   - Evidence: ${obs.evidence}`);
+                    lines.push(`   - Confidence: ${obs.confidence}`);
+                    // Save to observation tier
+                    const memory = memStorage.saveMemory({
+                        tier: 'observation',
+                        content: `OBSERVATION: ${obs.pattern}. Evidence: ${obs.evidence}`,
+                        tags: ['auto-observed', `confidence-${obs.confidence}`, 'pattern-detection'],
+                        related_files: checkpoint?.sections.context.relevantFiles || [],
+                        metadata: {
+                            pattern_type: obs.pattern.split(':')[0].toLowerCase().replace(/\s+/g, '_'),
+                            confidence: obs.confidence,
+                            evidence: obs.evidence,
+                            detected_at: new Date().toISOString(),
+                            lookback_days,
+                        },
+                    });
+                    savedObservations.push(memory.id);
+                    lines.push(`   - Saved: ${memory.id}`);
+                    lines.push('');
+                });
+                lines.push('---');
+                lines.push('');
+                lines.push(`✓ Saved ${savedObservations.length} observation(s) to memory (tier: observation)`);
+            }
+            else {
+                filteredPatterns.forEach((obs, idx) => {
+                    const confidenceEmoji = obs.confidence === 'high' ? '🔴' : obs.confidence === 'medium' ? '🟡' : '🟢';
+                    lines.push(`${idx + 1}. ${confidenceEmoji} **${obs.pattern}**`);
+                    lines.push(`   - Evidence: ${obs.evidence}`);
+                    lines.push(`   - Confidence: ${obs.confidence}`);
+                    lines.push('');
+                });
+                lines.push('---');
+                lines.push('');
+                lines.push('💡 Set `auto_save: true` to save these observations to memory.');
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: lines.join('\n'),
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Error analyzing patterns: ${error.message}`,
+                    }],
+                isError: true,
+            };
+        }
     });
-    // gaia_session_complete
-    server.tool('gaia_session_complete', 'Mark a session as completed.', {
-        sessionId: z.string().describe('Session ID to complete'),
-        outcome: z.enum(['completed', 'abandoned']).optional().describe('Session outcome'),
-        notes: z.string().optional().describe('Final notes'),
-    }, async ({ sessionId, outcome = 'completed', notes }) => {
-        const session = storage.getSession(sessionId);
-        if (!session) {
-            return {
-                content: [{ type: 'text', text: `Session not found: ${sessionId}` }],
-            };
-        }
-        storage.updateSession(sessionId, {
-            status: outcome,
-            completedAt: Date.now(),
-            notes: notes ? [...session.notes, notes] : session.notes,
-        });
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `✓ Session ${sessionId} marked as ${outcome}`,
-                },
-            ],
-        };
+    // ===========================================================================
+    // Migration Tool (v1 → v2)
+    // ===========================================================================
+    // gaia_migrate — Migrate v1 checkpoint data to v2 memory system
+    server.tool('gaia_migrate', 'Migrate Gaia v1 checkpoint data to v2 memory system. Converts decisions, progress, and learnings to searchable memories.', {
+        dry_run: z.boolean().optional().describe('Preview migration without saving (default: true)'),
+        include_checkpoints: z.boolean().optional().describe('Migrate checkpoint decisions (default: true)'),
+        sessions_limit: z.number().optional().describe('Limit number of sessions to migrate (default: all)'),
+    }, async ({ dry_run = true, include_checkpoints = true, sessions_limit }) => {
+        try {
+            const lines = [];
+            lines.push(`## Gaia v1 → v2 Migration${dry_run ? ' (DRY RUN)' : ''}`);
+            lines.push('');
+            let totalDecisions = 0;
+            let totalProgress = 0;
+            let sessionsProcessed = 0;
+            const migratedMemories = [];
+            if (include_checkpoints) {
+                // Scan sessions directory for v1 checkpoints
+                const sessionsDir = getSessionsDir();
+                if (!existsSync(sessionsDir)) {
+                    lines.push('⚠️  No v1 sessions directory found');
+                    lines.push(`   Expected: ${sessionsDir}`);
+                    lines.push('');
+                    lines.push('Nothing to migrate.');
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: lines.join('\n'),
+                            }],
+                    };
+                }
+                // Read all session directories
+                const { readdirSync, statSync } = await import('fs');
+                const sessionDirs = readdirSync(sessionsDir)
+                    .filter(name => {
+                    const path = join(sessionsDir, name);
+                    return statSync(path).isDirectory() && name !== 'latest';
+                })
+                    .sort()
+                    .reverse(); // Most recent first
+                const dirsToProcess = sessions_limit
+                    ? sessionDirs.slice(0, sessions_limit)
+                    : sessionDirs;
+                lines.push(`### Checkpoint Migration`);
+                lines.push('');
+                lines.push(`Found ${sessionDirs.length} session(s)`);
+                lines.push(`Processing ${dirsToProcess.length} session(s)`);
+                lines.push('');
+                const memStorage = getMemoryStorage();
+                for (const sessionDir of dirsToProcess) {
+                    const checkpointPath = join(sessionsDir, sessionDir, 'checkpoint.json');
+                    const checkpoint = readJsonFile(checkpointPath);
+                    if (!checkpoint)
+                        continue;
+                    sessionsProcessed++;
+                    lines.push(`#### Session: ${sessionDir}`);
+                    lines.push(`Project: ${checkpoint.project || 'N/A'}`);
+                    lines.push(`Purpose: ${checkpoint.purpose}`);
+                    lines.push('');
+                    // Migrate decisions
+                    if (checkpoint.sections.decisions.length > 0) {
+                        totalDecisions += checkpoint.sections.decisions.length;
+                        for (const decision of checkpoint.sections.decisions) {
+                            const content = `DECISION (migrated from v1): ${decision.topic}. Decision: ${decision.decision}. Rationale: ${decision.rationale}`;
+                            if (!dry_run) {
+                                const memory = memStorage.saveMemory({
+                                    tier: 'project',
+                                    content,
+                                    tags: ['migrated-v1', 'decision', decision.topic.toLowerCase().replace(/\s+/g, '-')],
+                                    related_files: checkpoint.sections.context.relevantFiles || [],
+                                    metadata: {
+                                        migrated_from: 'v1',
+                                        original_checkpoint_id: checkpoint.id,
+                                        original_timestamp: decision.timestamp,
+                                        decision_topic: decision.topic,
+                                    },
+                                });
+                                migratedMemories.push(memory.id);
+                                lines.push(`  ✓ Decision: ${decision.topic} → ${memory.id}`);
+                            }
+                            else {
+                                lines.push(`  • Decision: ${decision.topic}`);
+                            }
+                        }
+                    }
+                    // Migrate completed progress items as observations
+                    const completedTasks = checkpoint.sections.progress.filter(p => p.status === 'completed');
+                    if (completedTasks.length > 0) {
+                        totalProgress += completedTasks.length;
+                        for (const task of completedTasks) {
+                            const content = `COMPLETED (migrated from v1): ${task.task}${task.details ? `. ${task.details}` : ''}`;
+                            if (!dry_run) {
+                                const memory = memStorage.saveMemory({
+                                    tier: 'session',
+                                    content,
+                                    tags: ['migrated-v1', 'completed', 'progress'],
+                                    related_files: [],
+                                    metadata: {
+                                        migrated_from: 'v1',
+                                        original_checkpoint_id: checkpoint.id,
+                                        task_status: task.status,
+                                    },
+                                });
+                                migratedMemories.push(memory.id);
+                                lines.push(`  ✓ Progress: ${task.task.substring(0, 50)} → ${memory.id}`);
+                            }
+                            else {
+                                lines.push(`  • Progress: ${task.task.substring(0, 50)}`);
+                            }
+                        }
+                    }
+                    lines.push('');
+                }
+            }
+            // Summary
+            lines.push('---');
+            lines.push('');
+            lines.push('### Migration Summary');
+            lines.push('');
+            lines.push(`Sessions processed: ${sessionsProcessed}`);
+            lines.push(`Decisions: ${totalDecisions}`);
+            lines.push(`Completed tasks: ${totalProgress}`);
+            lines.push(`Total items: ${totalDecisions + totalProgress}`);
+            if (dry_run) {
+                lines.push('');
+                lines.push('⚠️  **DRY RUN MODE** - No data was saved');
+                lines.push('   Set `dry_run: false` to perform actual migration');
+            }
+            else {
+                lines.push('');
+                lines.push(`✓ Migrated ${migratedMemories.length} memory/memories to v2 system`);
+                lines.push('');
+                lines.push('**Next steps:**');
+                lines.push('1. Search migrated data: `gaia_search({ query: "migrated-v1", tags: ["migrated-v1"] })`');
+                lines.push('2. Verify decisions: `gaia_search({ query: "decision", tiers: ["project"] })`');
+                lines.push('3. Review in context: Use `current_file` parameter for proximity boosting');
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: lines.join('\n'),
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Error during migration: ${error.message}`,
+                    }],
+                isError: true,
+            };
+        }
     });
     // ===========================================================================
-    // Learning Tools
+    // Learning Tools (unchanged from v1)
     // ===========================================================================
     // gaia_learn
     server.tool('gaia_learn', 'Capture a correction for CLAUDE.md. Gaia learns from mistakes so all future sessions benefit.', {
@@ -370,97 +1017,382 @@ export function registerGaiaTools(server) {
         };
     });
     // ===========================================================================
-    // Context Tools (Memory)
+    // Memory Tools (v2.0 - SQLite + FTS5)
     // ===========================================================================
-    // gaia_remember
-    server.tool('gaia_remember', 'Save current context state for later restoration. Gaia remembers everything.', {
-        name: z.string().describe('Name for this memory'),
-        description: z.string().optional().describe('Description of the context'),
-        includeGit: z.boolean().optional().describe('Include git info (default: true)'),
-        includeClaudeMd: z.boolean().optional().describe('Include CLAUDE.md (default: true)'),
-        notes: z.string().optional().describe('Additional notes'),
-    }, async ({ name, description, includeGit = true, includeClaudeMd = true, notes }) => {
-        const data = { notes };
-        if (includeGit) {
-            try {
-                const status = await git.getStatus();
-                const log = await git.getLog({ count: 5 });
-                data.gitBranch = status.branch;
-                data.gitStatus = JSON.stringify(status);
-                data.gitLog = log.map((l) => `${l.shortHash} ${l.message}`);
-            }
-            catch {
-                // Not in git repo
-            }
+    // gaia_save
+    server.tool('gaia_save', 'Save a new memory with tier, content, tags, and related files. Returns the created memory with ID.', {
+        tier: z.enum(['session', 'project', 'global', 'note', 'observation'])
+            .describe('Memory tier: session (ephemeral), project (cwd), global (user-wide), note (manual), observation (autonomous)'),
+        content: z.string().describe('Memory content (what to remember)'),
+        tags: z.array(z.string()).optional().describe('Tags for categorization (optional)'),
+        related_files: z.array(z.string()).optional().describe('Related file paths (optional)'),
+        session_id: z.string().optional().describe('Session ID for session-tier memories (optional)'),
+        project_path: z.string().optional().describe('Project path for project-tier memories (optional)'),
+        metadata: z.record(z.any()).optional().describe('Additional structured metadata (optional)'),
+    }, async ({ tier, content, tags = [], related_files = [], session_id, project_path, metadata }) => {
+        try {
+            const storage = getMemoryStorage();
+            const memory = storage.saveMemory({
+                tier,
+                content,
+                tags,
+                related_files,
+                session_id,
+                project_path,
+                metadata,
+            });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            memory: {
+                                id: memory.id,
+                                tier: memory.tier,
+                                content: memory.content,
+                                tags: memory.tags,
+                                related_files: memory.related_files,
+                                created_at: memory.created_at,
+                            },
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Error saving memory: ${error instanceof Error ? error.message : String(error)}`,
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // gaia_search
+    server.tool('gaia_search', 'Search memories using FTS5 full-text search with composite scoring (BM25 + recency + tier + proximity + frequency). Returns ranked results.', {
+        query: z.string().describe('Search query (supports FTS5 syntax: "word1 word2", "phrase", word*)'),
+        tiers: z.array(z.enum(['session', 'project', 'global', 'note', 'observation'])).optional()
+            .describe('Filter by tiers (optional)'),
+        limit: z.number().optional().describe('Maximum results to return (default: 20, max: 100)'),
+        current_file: z.string().optional().describe('Current file path for proximity scoring (optional)'),
+        project_path: z.string().optional().describe('Current project path for context (optional)'),
+    }, async ({ query, tiers, limit = 20, current_file, project_path }) => {
+        try {
+            const storage = getMemoryStorage();
+            const results = storage.search({
+                query,
+                tiers,
+                limit: Math.min(limit, 100),
+                context: current_file || project_path ? { current_file, project_path } : undefined,
+            });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            count: results.length,
+                            results: results.map(r => ({
+                                id: r.memory.id,
+                                tier: r.memory.tier,
+                                content: r.memory.content,
+                                tags: r.memory.tags,
+                                related_files: r.memory.related_files,
+                                created_at: r.memory.created_at,
+                                score: r.score,
+                                score_breakdown: {
+                                    relevance: r.relevance_score,
+                                    recency: r.recency_score,
+                                    tier: r.tier_score,
+                                    proximity: r.proximity_score,
+                                    frequency: r.frequency_score,
+                                },
+                            })),
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Error searching memories: ${error instanceof Error ? error.message : String(error)}`,
+                    }],
+                isError: true,
+            };
         }
-        if (includeClaudeMd) {
-            try {
-                data.claudeMd = await git.readClaudeMd();
+    });
+    // gaia_get
+    server.tool('gaia_get', 'Get a memory by ID. Increments access count and updates last accessed timestamp.', {
+        id: z.string().describe('Memory ID (starts with "mem_")'),
+    }, async ({ id }) => {
+        try {
+            const storage = getMemoryStorage();
+            const memory = storage.getMemory(id);
+            if (!memory) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                error: `Memory not found: ${id}`,
+                            }, null, 2),
+                        }],
+                };
             }
-            catch {
-                // No CLAUDE.md
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            memory: {
+                                id: memory.id,
+                                tier: memory.tier,
+                                content: memory.content,
+                                tags: memory.tags,
+                                related_files: memory.related_files,
+                                session_id: memory.session_id,
+                                project_path: memory.project_path,
+                                created_at: memory.created_at,
+                                accessed_at: memory.accessed_at,
+                                access_count: memory.access_count,
+                                metadata: memory.metadata,
+                            },
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Error getting memory: ${error instanceof Error ? error.message : String(error)}`,
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // gaia_delete
+    server.tool('gaia_delete', 'Delete a memory by ID. Automatically deletes all associated links (CASCADE).', {
+        id: z.string().describe('Memory ID to delete'),
+    }, async ({ id }) => {
+        try {
+            const storage = getMemoryStorage();
+            const result = storage.deleteMemory(id);
+            if (!result.success) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                error: `Memory not found: ${id}`,
+                            }, null, 2),
+                        }],
+                };
             }
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            deleted_memory_id: id,
+                            deleted_links: result.deleted_links,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Error deleting memory: ${error instanceof Error ? error.message : String(error)}`,
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // gaia_stats
+    server.tool('gaia_stats', 'Get Gaia memory statistics: total memories, breakdown by tier, links, database size, age range.', {}, async () => {
+        try {
+            const storage = getMemoryStorage();
+            const stats = storage.getStats();
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            stats: {
+                                total_memories: stats.total_memories,
+                                by_tier: stats.by_tier,
+                                total_links: stats.total_links,
+                                database_size_mb: parseFloat(stats.total_size_mb.toFixed(2)),
+                                oldest_memory: stats.oldest_memory,
+                                newest_memory: stats.newest_memory,
+                                age_range_days: stats.oldest_memory > 0
+                                    ? Math.floor((stats.newest_memory - stats.oldest_memory) / (1000 * 60 * 60 * 24))
+                                    : 0,
+                            },
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Error getting stats: ${error instanceof Error ? error.message : String(error)}`,
+                    }],
+                isError: true,
+            };
         }
-        const snapshot = {
-            id: `mem_${nanoid(8)}`,
-            name,
-            description,
-            data,
-            createdAt: Date.now(),
-        };
-        storage.addSnapshot(snapshot);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `✓ Memory saved: ${snapshot.id}\n\nName: ${name}`,
-                },
-            ],
-        };
     });
-    // gaia_recall
-    server.tool('gaia_recall', 'Restore a previously saved context. Gaia recalls everything.', {
-        memoryId: z.string().optional().describe('Memory ID to restore'),
-        name: z.string().optional().describe('Memory name to restore'),
-    }, async ({ memoryId, name }) => {
-        const snapshot = memoryId
-            ? storage.getSnapshot(memoryId)
-            : name
-                ? storage.getSnapshotByName(name)
-                : null;
-        if (!snapshot) {
-            // List available memories
-            const all = storage.getSnapshots();
-            if (all.length === 0) {
+    // ===========================================================================
+    // Cross-Prompt Linking Tools
+    // ===========================================================================
+    // gaia_link
+    server.tool('gaia_link', 'Create a typed link between two memories. Builds cross-prompt dependency graph.', {
+        from_memory_id: z.string().describe('Source memory ID'),
+        to_memory_id: z.string().describe('Target memory ID'),
+        link_type: z.enum(['depends_on', 'extends', 'reverts', 'related', 'contradicts'])
+            .describe('Link type: depends_on (requires), extends (builds on), reverts (undoes), related (associated), contradicts (conflicts)'),
+    }, async ({ from_memory_id, to_memory_id, link_type }) => {
+        try {
+            const storage = getMemoryStorage();
+            // Verify both memories exist
+            const fromMemory = storage.getMemory(from_memory_id);
+            const toMemory = storage.getMemory(to_memory_id);
+            if (!fromMemory) {
                 return {
-                    content: [{ type: 'text', text: 'No memories available.' }],
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                error: `Source memory not found: ${from_memory_id}`,
+                            }, null, 2),
+                        }],
                 };
             }
-            let output = '## Available Memories\n\n';
-            for (const s of all) {
-                output += `- **${s.name}** (${s.id}): ${s.description || 'No description'}\n`;
+            if (!toMemory) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                error: `Target memory not found: ${to_memory_id}`,
+                            }, null, 2),
+                        }],
+                };
             }
+            const link = storage.createLink({
+                from_memory_id,
+                to_memory_id,
+                link_type,
+            });
             return {
-                content: [{ type: 'text', text: output }],
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            link: {
+                                from_memory_id: link.from_memory_id,
+                                to_memory_id: link.to_memory_id,
+                                link_type: link.link_type,
+                                created_at: link.created_at,
+                            },
+                            from_memory_content: fromMemory.content.substring(0, 100),
+                            to_memory_content: toMemory.content.substring(0, 100),
+                        }, null, 2),
+                    }],
             };
         }
-        let output = `## Recalled: ${snapshot.name}\n\n`;
-        if (snapshot.data.gitBranch) {
-            output += `**Git Branch**: ${snapshot.data.gitBranch}\n\n`;
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Error creating link: ${error instanceof Error ? error.message : String(error)}`,
+                    }],
+                isError: true,
+            };
         }
-        if (snapshot.data.gitLog) {
-            output += `**Recent Commits**:\n`;
-            for (const log of snapshot.data.gitLog) {
-                output += `- ${log}\n`;
+    });
+    // gaia_graph
+    server.tool('gaia_graph', 'Get the link graph for a memory. Returns all linked memories grouped by link type.', {
+        memory_id: z.string().describe('Memory ID to get links for'),
+    }, async ({ memory_id }) => {
+        try {
+            const storage = getMemoryStorage();
+            // Verify memory exists
+            const memory = storage.getMemory(memory_id);
+            if (!memory) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                error: `Memory not found: ${memory_id}`,
+                            }, null, 2),
+                        }],
+                };
             }
-            output += '\n';
+            const links = storage.getLinks(memory_id);
+            // Count total links
+            const totalLinks = Object.values(links).reduce((sum, arr) => sum + arr.length, 0);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            memory_id,
+                            memory_content: memory.content.substring(0, 100),
+                            total_links: totalLinks,
+                            links: {
+                                depends_on: links.depends_on.map(m => ({
+                                    id: m.id,
+                                    content: m.content.substring(0, 100),
+                                    tier: m.tier,
+                                })),
+                                extends: links.extends.map(m => ({
+                                    id: m.id,
+                                    content: m.content.substring(0, 100),
+                                    tier: m.tier,
+                                })),
+                                reverts: links.reverts.map(m => ({
+                                    id: m.id,
+                                    content: m.content.substring(0, 100),
+                                    tier: m.tier,
+                                })),
+                                related: links.related.map(m => ({
+                                    id: m.id,
+                                    content: m.content.substring(0, 100),
+                                    tier: m.tier,
+                                })),
+                                contradicts: links.contradicts.map(m => ({
+                                    id: m.id,
+                                    content: m.content.substring(0, 100),
+                                    tier: m.tier,
+                                })),
+                            },
+                        }, null, 2),
+                    }],
+            };
         }
-        if (snapshot.data.notes) {
-            output += `**Notes**: ${snapshot.data.notes}\n`;
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Error getting graph: ${error instanceof Error ? error.message : String(error)}`,
+                    }],
+                isError: true,
+            };
         }
-        return {
-            content: [{ type: 'text', text: output }],
-        };
     });
 }
+/**
+ * Cleanup function to close database connection
+ */
+export function cleanupGaiaMemory() {
+    if (memoryStorage) {
+        memoryStorage.close();
+        memoryStorage = null;
+    }
+}
 //# sourceMappingURL=index.js.map