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.

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

### 2.2 Smart Summarization

Don't store raw conversations — summarize and extract:

```typescript
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

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

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

## Implementation

### Hook Handler

```typescript
// 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

```typescript
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

```typescript
// 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](https://github.com/supermemoryai/claude-supermemory)
- [Claude Code Hooks](https://docs.anthropic.com/claude-code/hooks)