Add development plan with 13 milestone specifications
- docs/plan.md: Master roadmap with phases and priorities - docs/milestones/01-13: Detailed specs for each feature - Updated CLAUDE.md with plan references and build commands Milestones cover: - Phase 1: Temporal versioning, auto-capture, context injection, codebase indexing - Phase 2: Daily journal, content ingestion, graph visualization, import/export - Phase 3: Multi-graph, smart retrieval, TUI dashboard, browser extension, shell completions
This commit is contained in:
212
docs/milestones/02-auto-capture.md
Normal file
212
docs/milestones/02-auto-capture.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user