Skip to content

Auto Capture System

Jump to bottom
Zhafron Kautsar edited this page Jan 12, 2026 · 2 revisions

Auto-Capture System

Comprehensive guide to automatic memory extraction from conversations.

Overview

The auto-capture system automatically extracts important information from conversations using AI. Version 2.0 introduces a prompt-based system replacing the previous token-based approach.

Breaking Changes

Token-based auto-capture has been removed. The following configuration options are no longer supported:

  • autoCaptureTokenThreshold
  • autoCaptureMinTokens
  • autoCaptureMaxMemories
  • autoCaptureSummaryMaxLength
  • autoCaptureContextWindow

Migration required: Remove these options from your configuration file.

How It Works

Process Flow

  1. Session Idle Detection: Triggers when conversation pauses
  2. Prompt Analysis: Analyzes last uncaptured user prompt and AI response
  3. Memory Extraction: AI identifies important information
  4. Scope Assignment: Determines user vs project scope
  5. Prompt Linking: Creates bidirectional link between prompt and memory
  6. Skip Logic: Non-technical conversations are skipped and prompts deleted
  7. Context Continuity: Includes previous project memory for context
  8. Background Processing: Runs without blocking conversation

Prompt-Based Triggering

How It Differs from Token-Based:

  • Old: Monitored cumulative token count, triggered at threshold
  • New: Triggers on session idle, analyzes single prompt-response pair
  • Benefits: Simpler, more predictable, lower cost, better quality

Why Prompt-Based:

  • Ensures each prompt gets analyzed individually
  • Prevents missing important information between captures
  • Reduces API costs (analyzes less context)
  • Creates clear prompt-memory relationships
  • Easier to understand and debug

Skip Logic

The system automatically skips non-technical conversations:

  • AI returns type: "skip" for casual/non-technical content
  • Prompt is deleted from database
  • No memory is created
  • Keeps database clean and focused

Examples of Skipped Content:

  • Greetings and casual chat
  • Simple questions with no learning value
  • Off-topic discussions
  • Repetitive queries

Context Continuity

Each capture includes the previous project memory for context:

# Previous Project Memory

[Content of last project memory]

---

# Current Conversation

User: [prompt]
Assistant: [response]

Horizontal rules (---) separate sections for clear AI parsing.

Configuration

Required Settings

{
  "autoCaptureEnabled": true,
  "memoryProvider": "openai-chat",
  "memoryModel": "gpt-4",
  "memoryApiUrl": "https://api.openai.com/v1",
  "memoryApiKey": "sk-your-api-key-here"
}

Optional Settings

{
  "userMemoryAnalysisInterval": 10,
  "autoCaptureMaxIterations": 5,
  "autoCaptureIterationTimeout": 30000
}

Configuration Options

autoCaptureEnabled

Type: boolean
Default: true

Enable or disable auto-capture.

{
  "autoCaptureEnabled": true
}

memoryProvider

Type: string
Default: openai-chat

AI provider for memory extraction.

Supported Providers:

{
  "memoryProvider": "openai-chat"
}
{
  "memoryProvider": "anthropic"
}
{
  "memoryProvider": "openai-responses"
}

Provider Selection:

  • openai-chat: OpenAI Chat Completions API (GPT-4, GPT-3.5)
  • anthropic: Anthropic Messages API (Claude)
  • openai-responses: OpenAI Responses API (experimental)

memoryModel

Type: string
Required: Yes

AI model for memory extraction.

OpenAI Models:

{
  "memoryProvider": "openai-chat",
  "memoryModel": "gpt-4"
}

Supported: gpt-4, gpt-4-turbo, gpt-3.5-turbo

Anthropic Models:

{
  "memoryProvider": "anthropic",
  "memoryModel": "claude-3-5-sonnet-20241022"
}

Supported: claude-3-5-sonnet-20241022, claude-3-opus-20240229, claude-3-sonnet-20240229

Model Selection:

  • GPT-4: Best quality, higher cost
  • GPT-3.5-Turbo: Good balance, lower cost
  • Claude-3.5-Sonnet: Excellent quality, fast
  • Claude-3-Opus: Highest quality, highest cost

memoryApiUrl

Type: string
Required: Yes

API endpoint for memory extraction.

Provider URLs:

OpenAI:

{
  "memoryApiUrl": "https://api.openai.com/v1"
}

Anthropic:

{
  "memoryApiUrl": "https://api.anthropic.com/v1"
}

OpenAI-compatible (Groq, etc.):

{
  "memoryApiUrl": "https://api.groq.com/openai/v1"
}

memoryApiKey

Type: string
Required: Yes

API key for authentication.

{
  "memoryApiKey": "sk-your-api-key-here"
}

Environment Variable:

Alternatively, set environment variable:

export OPENAI_API_KEY=sk-your-api-key-here

userMemoryAnalysisInterval

Type: number
Default: 10

Number of prompts between user learning analysis.

{
  "userMemoryAnalysisInterval": 10
}

Tuning:

  • Lower (5): More frequent analysis, higher cost
  • Default (10): Balanced
  • Higher (20): Less frequent, lower cost

See User Learning System below.

autoCaptureMaxIterations

Type: number
Default: 5

Maximum retry iterations for capture.

{
  "autoCaptureMaxIterations": 5
}

autoCaptureIterationTimeout

Type: number
Default: 30000

Timeout per iteration in milliseconds.

{
  "autoCaptureIterationTimeout": 30000
}

User Learning System

Separate from auto-capture, the user learning system analyzes batches of prompts to identify patterns.

How It Works

  1. Tracks prompts with user_learning_captured flag
  2. Triggers after N prompts (default: 10)
  3. Analyzes batch of prompts for patterns
  4. Generates user-scoped memories about:
    • Coding style preferences
    • Communication patterns
    • Tool preferences
    • Skill level indicators
  5. Independent from prompt-based auto-capture

Configuration

{
  "userMemoryAnalysisInterval": 10
}

Set to 0 to disable user learning analysis.

Why Separate?

  • User patterns require batch analysis, not per-conversation
  • Different tracking flag prevents data loss
  • Can be disabled independently
  • Different trigger mechanism

Usage

Automatic Operation

Once configured, auto-capture runs automatically:

  1. Have conversations with the AI agent
  2. System monitors session activity
  3. Captures trigger on idle
  4. Memories stored in background
  5. Prompts linked to memories
  6. No user interaction required

Manual Trigger

Force immediate capture:

memory({ mode: "capture-now" })

Useful for:

  • Capturing important conversation immediately
  • Testing auto-capture configuration
  • Forcing capture before session end

Toggle Auto-Capture

Enable or disable at runtime:

memory({ mode: "auto-capture-toggle" })

Returns new state:

Auto-capture is now: enabled

View Statistics

Check auto-capture performance:

memory({ mode: "auto-capture-stats" })

Returns:

  • Total captures performed
  • Total memories created
  • Last capture timestamp
  • Linked prompts count

Memory Extraction

What Gets Captured

User Scope:

  • Personal preferences
  • Coding style
  • Tool preferences
  • Communication patterns
  • General knowledge

Project Scope:

  • Architecture decisions
  • Technology choices
  • Implementation details
  • Bug fixes
  • Feature requirements

Extraction Quality

Factors Affecting Quality:

  1. Model Selection: Better models extract more accurately
  2. Conversation Quality: Clear discussions yield better memories
  3. Context Continuity: Previous memory provides better context
  4. Skip Logic: Prevents noise from casual conversations

Optimization:

For best results:

  • Use GPT-4 or Claude-3.5-Sonnet
  • Maintain clear, structured conversations
  • Provide explicit context when needed
  • Let skip logic filter out noise

Prompt-Memory Linking

How It Works

Each captured memory is linked to its source prompt:

  • Bidirectional relationship stored in database
  • user_prompts.linked_memory_id points to memory
  • Memory metadata includes prompt reference
  • Web interface shows visual link indicators

Benefits

  • Trace memory origin
  • Cascade delete support
  • Timeline view with context
  • Better debugging and auditing

Cascade Delete

Delete memory and linked prompt together:

DELETE /api/memories/:id?cascade=true

Delete prompt and linked memory together:

DELETE /api/prompts/:id?cascade=true

Cost Management

Estimating Costs

Per Capture:

  • Single prompt-response pair: ~500-1000 tokens
  • Model call: ~$0.005-0.015 per capture (GPT-4)
  • Frequency: Per conversation session

Monthly Estimate:

  • Active usage: 50 conversations/day
  • Captures: ~50 per day
  • Cost: ~$7.50-22.50/month (GPT-4)

Cost Reduction

Use Cheaper Models:

{
  "memoryModel": "gpt-3.5-turbo"
}

Reduces cost by 90% with slight quality decrease.

Use Claude:

{
  "memoryProvider": "anthropic",
  "memoryModel": "claude-3-5-sonnet-20241022"
}

Good balance of quality and cost.

Disable User Learning:

{
  "userMemoryAnalysisInterval": 0
}

Reduces batch analysis costs.

Monitoring

Check Status

View auto-capture statistics:

memory({ mode: "auto-capture-stats" })

Web Interface

Access statistics in web interface:

  1. Open http://127.0.0.1:4747
  2. View timeline with linked prompts
  3. See capture statistics

Logs

Check OpenCode logs for capture events:

[AutoCapture] Triggered on session idle
[AutoCapture] Analyzing prompt: <prompt_id>
[AutoCapture] Extracted memory: <memory_id>
[AutoCapture] Linked prompt to memory

Troubleshooting

Auto-Capture Not Working

Verify Configuration:

{
  "autoCaptureEnabled": true,
  "memoryProvider": "openai-chat",
  "memoryModel": "gpt-4",
  "memoryApiUrl": "https://api.openai.com/v1",
  "memoryApiKey": "sk-..."
}

Check API Key:

Test API key:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer sk-your-api-key"

Check Logs:

Look for errors in OpenCode logs.

No Memories Extracted

Check Skip Logic:

System may be skipping non-technical conversations. This is expected behavior.

Check Conversation Quality:

Ensure conversations contain extractable technical information.

Force Capture:

memory({ mode: "capture-now" })

Prompts Not Linked

Check Database:

Verify user_prompts.linked_memory_id is populated.

Check Web Interface:

Timeline should show link indicators.

Check Logs:

Look for linking errors in logs.

Best Practices

Configuration

Start with Defaults:

{
  "autoCaptureEnabled": true,
  "memoryProvider": "openai-chat",
  "memoryModel": "gpt-4",
  "userMemoryAnalysisInterval": 10
}

Monitor and Adjust:

Check statistics regularly and tune based on results.

Use Appropriate Model:

Balance cost and quality based on needs.

Conversation

Be Explicit:

State important information clearly.

Provide Context:

Explain decisions and reasoning.

Structured Discussions:

Organize conversations logically.

Maintenance

Review Captured Memories:

Periodically check quality of auto-captured memories.

Run Deduplication:

Remove duplicate memories created by auto-capture.

Monitor Costs:

Track API usage and adjust settings if needed.

Migration from Token-Based

Remove Deprecated Options

Delete these from your config:

{
  "autoCaptureTokenThreshold": 10000,
  "autoCaptureMinTokens": 20000,
  "autoCaptureMaxMemories": 10,
  "autoCaptureSummaryMaxLength": 0,
  "autoCaptureContextWindow": 3
}

Add New Options

Add these to your config:

{
  "memoryProvider": "openai-chat",
  "userMemoryAnalysisInterval": 10,
  "autoCaptureMaxIterations": 5,
  "autoCaptureIterationTimeout": 30000
}

Behavior Changes

  • Old: Captured multiple memories at token threshold
  • New: Captures single memory per prompt on session idle
  • Old: No prompt tracking
  • New: Full prompt-memory linking
  • Old: No skip logic
  • New: Automatic skip for non-technical content

Next Steps

Clone this wiki locally