cortex/docs/milestones/02-auto-capture.md

Milestone 2: Auto-Capture System

Overview

Automatically capture Claude Code conversations as memory nodes. Every significant interaction becomes searchable knowledge without manual effort.

Motivation

• Manual memory creation is friction that prevents adoption
• Conversations contain valuable context that's lost after the session
• Supermemory's killer feature is invisible capture
• "Just works" experience is essential for daily use

Features

2.1 Conversation Hooks

Integrate with Claude Code's hook system to capture interactions.

// .claude/settings.json
{
  "hooks": {
    "post_response": {
      "command": "cortex capture-hook",
      "timeout": 5000
    }
  }
}

2.2 Smart Summarization

Don't store raw conversations — summarize and extract:

interface CapturedMemory {
  summary: string;          // 1-2 sentence summary
  topics: string[];         // Extracted topics/tags
  decisions: string[];      // Any decisions made
  codeChanges: string[];    // Files modified
  relatedNodes: string[];   // Links to existing nodes
}

2.3 Deduplication

Prevent duplicate memories from similar conversations:

• Embedding similarity check before insert
• Merge into existing node if >0.90 similarity
• Link as "relates_to" if 0.75-0.90 similarity

2.4 Capture Modes

# Always capture (default when enabled)
cortex config set capture.mode always

# Only capture on explicit save
cortex config set capture.mode manual

# Capture decisions and code changes only
cortex config set capture.mode decisions

# Disable capture
cortex config set capture.mode off

2.5 MCP Notification

Add MCP tool for Claude to explicitly save memories:

memory_capture   // Explicitly capture current context
memory_remember  // "Remember this for later" - user triggered

Implementation

Hook Handler

// src/cli/commands/capture-hook.ts
export async function captureHook(input: HookInput): Promise<void> {
  const { conversation, files_changed, session_id } = input;

  // Skip if disabled or trivial interaction
  if (!shouldCapture(conversation)) return;

  // Summarize with Ollama
  const summary = await summarizeConversation(conversation);

  // Extract structured data
  const extracted = await extractMemory(conversation, summary);

  // Check for duplicates
  const existing = await findSimilar(extracted.embedding);

  if (existing && existing.similarity > 0.90) {
    // Merge into existing
    await mergeIntoNode(existing.id, extracted);
  } else {
    // Create new node
    await addNode({
      kind: 'memory',
      title: extracted.summary.slice(0, 100),
      content: extracted.fullSummary,
      tags: ['auto-capture', ...extracted.topics],
      metadata: {
        session_id,
        files_changed,
        captured_at: Date.now(),
        source: 'claude-code'
      }
    });
  }
}

Summarization Prompts

const SUMMARIZE_PROMPT = `
Summarize this Claude Code conversation in 1-2 sentences.
Focus on: what was accomplished, decisions made, problems solved.
Do NOT include greetings or meta-discussion.

Conversation:
{conversation}

Summary:`;

const EXTRACT_PROMPT = `
Extract from this conversation:
1. Main topics (as tags, lowercase, hyphenated)
2. Decisions made (if any)
3. Code files discussed or modified

Conversation:
{conversation}

Output as JSON:
{"topics": [], "decisions": [], "files": []}`;

Configuration

// src/core/config.ts
interface CaptureConfig {
  mode: 'always' | 'manual' | 'decisions' | 'off';
  minLength: number;        // Minimum conversation length to capture
  excludePatterns: string[]; // Regex patterns to skip
  autoTag: boolean;         // Auto-generate tags
  linkRelated: boolean;     // Auto-link to related nodes
}

CLI Commands

Command	Description
cortex capture-hook	Hook handler (called by Claude Code)
cortex capture <text>	Manually capture a thought
cortex capture --session	Capture current session summary
cortex config set capture.mode <mode>	Set capture mode

MCP Tools

Tool	Description
memory_capture	Explicitly capture current context
memory_remember	User-triggered "remember this"

Testing

• Hook receives conversation data correctly
• Summarization produces coherent summaries
• Deduplication prevents duplicate nodes
• Tags are extracted accurately
• Related nodes are linked
• Config modes work as expected

Acceptance Criteria

• Conversations auto-captured without user action
• Summaries are concise and useful
• No duplicate memories for repeated topics
• Can disable/configure capture behavior
• Works offline (queues for later if Ollama unavailable)
• <500ms latency (non-blocking)

Estimated Effort

• Hook integration: 3 hours
• Summarization pipeline: 4 hours
• Deduplication logic: 3 hours
• Configuration system: 2 hours
• MCP tools: 2 hours
• Testing: 3 hours
• Total: ~17 hours

Dependencies

• Ollama for summarization (graceful fallback if unavailable)
• Claude Code hooks system

References

• Claude-Supermemory
• Claude Code Hooks