Skip to content

User Profile

Jump to bottom
Zhafron Kautsar edited this page Jan 12, 2026 · 1 revision

User Profile System

The User Profile System is a structured learning mechanism that builds a comprehensive understanding of your preferences, patterns, workflows, and skill level from your conversation history.

Overview

Starting in v2.2, OpenCode Memory replaces user-scoped memories with a structured profile system. Instead of storing individual memory items, the system analyzes batches of prompts to build and maintain a unified profile.

Key Benefits

  • Structured Data: Organized into preferences, patterns, workflows, and skill assessment
  • Confidence Scoring: Preferences tracked with confidence levels (0.0-1.0)
  • Frequency Tracking: Patterns and workflows ranked by occurrence
  • Versioning: Full changelog with snapshot support
  • Automatic Decay: Unused preferences gradually lose confidence
  • Evidence-Based: Preferences backed by example prompts

Profile Structure

Preferences

User preferences with confidence scores and evidence.

Structure:

{
  category: string        // e.g., "Code Style", "Communication"
  description: string     // e.g., "Prefers code without comments"
  confidence: number      // 0.0-1.0, based on evidence strength
  evidence: string[]      // 1-3 example prompts
  lastUpdated: number     // Timestamp
}

Examples:

  • [Code Style] Prefers TypeScript over JavaScript (confidence: 0.9)
  • [Communication] Likes concise responses (confidence: 0.8)
  • [Tools] Prefers Bun over npm (confidence: 0.7)

Limits: Max 20 preferences (configurable via userProfileMaxPreferences)

Patterns

Recurring topics and interests with frequency tracking.

Structure:

{
  category: string        // e.g., "Technical Domain", "Problem Type"
  description: string     // e.g., "Often asks about database optimization"
  frequency: number       // Number of occurrences
  lastSeen: number        // Timestamp
}

Examples:

  • [Technical Domain] Frequently works on authentication (frequency: 15)
  • [Problem Type] Often debugs async/await issues (frequency: 8)
  • [Technology] Regular questions about Docker (frequency: 12)

Limits: Max 15 patterns (configurable via userProfileMaxPatterns)

Workflows

Development sequences and habits.

Structure:

{
  description: string     // Workflow description
  steps: string[]         // Sequence of steps
  frequency: number       // Number of times observed
}

Examples:

  • Usually asks for tests after implementation (frequency: 10)
    • Steps: ["Implement feature", "Request tests", "Review coverage"]
  • Always requests code review before committing (frequency: 8)
    • Steps: ["Complete code", "Ask for review", "Apply feedback"]

Limits: Max 10 workflows (configurable via userProfileMaxWorkflows)

Skill Level

Overall and per-domain skill assessment.

Structure:

{
  overall: "beginner" | "intermediate" | "advanced"
  domains: {
    [domain: string]: "beginner" | "intermediate" | "advanced"
  }
}

Example:

{
  "overall": "intermediate",
  "domains": {
    "typescript": "advanced",
    "docker": "beginner",
    "database": "intermediate",
    "testing": "intermediate"
  }
}

How It Works

Analysis Trigger

Profile analysis triggers every N prompts (default: 10, configurable via userMemoryAnalysisInterval).

Process:

  1. System accumulates uncaptured prompts
  2. When threshold reached, AI analyzes batch
  3. Profile created (first time) or updated (subsequent)
  4. Changelog entry created
  5. Prompts marked as analyzed

Profile Creation

On first analysis:

  1. AI analyzes prompt batch
  2. Identifies preferences, patterns, workflows, skill level
  3. Assigns initial confidence scores (conservative)
  4. Creates profile with version 1
  5. Stores changelog snapshot

Profile Updates

On subsequent analyses:

  1. AI receives existing profile + new prompts
  2. Merges new insights with existing data
  3. Updates confidence scores for reinforced preferences
  4. Increments frequency for recurring patterns
  5. Adds new items if space available
  6. Removes low-confidence/low-frequency items if limits exceeded
  7. Increments version number
  8. Creates changelog entry

Confidence Decay

Preferences automatically decay over time if not reinforced.

Mechanism:

  • Decay threshold: 30 days (configurable via userProfileConfidenceDecayDays)
  • After threshold, confidence gradually decreases
  • Preferences below 0.3 confidence are removed
  • Decay factor: max(0.5, 1 - (age - threshold) / threshold)

Example:

  • Preference at confidence 0.8
  • Not seen for 45 days (threshold: 30)
  • Age beyond threshold: 15 days
  • Decay factor: 1 - 15/30 = 0.5
  • New confidence: 0.8 * 0.5 = 0.4

Merging Logic

When updating profile:

Preferences:

  • Existing preference reinforced → increase confidence by 0.1 (max 1.0)
  • New preference → add with initial confidence from AI
  • Sort by confidence, keep top N

Patterns:

  • Existing pattern seen → increment frequency
  • New pattern → add with frequency 1
  • Sort by frequency, keep top N

Workflows:

  • Existing workflow observed → increment frequency
  • New workflow → add with frequency 1
  • Sort by frequency, keep top N

Skill Level:

  • Overall: Take higher of existing vs new
  • Domains: Merge, taking higher level per domain

Changelog & Versioning

Every profile update creates a changelog entry.

Changelog Entry:

{
  id: string
  profileId: string
  version: number
  changeType: "create" | "update"
  changeSummary: string       // e.g., "+3 preferences, +2 patterns"
  profileDataSnapshot: string // Full profile JSON
  createdAt: number
}

Retention: Last 5 versions kept (configurable via userProfileChangelogRetentionCount)

Use Cases:

  • Debug profile evolution
  • Rollback to previous version
  • Audit what changed
  • Track learning progress

API Usage

Get Profile

memory({ mode: "profile" })

Response:

{
  "success": true,
  "profile": {
    "preferences": [...],
    "patterns": [...],
    "workflows": [...],
    "skillLevel": {...},
    "version": 5,
    "lastAnalyzed": "2026-01-12T10:30:00Z",
    "totalPromptsAnalyzed": 50
  }
}

REST API

Get Profile:

GET /api/profile

Get Changelog:

GET /api/profile/changelog?limit=5

Get Snapshot:

GET /api/profile/snapshot/:changelogId

Force Refresh:

POST /api/profile/refresh

Configuration

{
  // Analysis trigger
  "userMemoryAnalysisInterval": 10,
  
  // Profile limits
  "userProfileMaxPreferences": 20,
  "userProfileMaxPatterns": 15,
  "userProfileMaxWorkflows": 10,
  
  // Decay settings
  "userProfileConfidenceDecayDays": 30,
  
  // Changelog retention
  "userProfileChangelogRetentionCount": 5,
  
  // Inject profile into AI context
  "injectProfile": true
}

Migration from User-Scoped Memories

What Changed

Before (v2.1 and earlier):

  • User learning created individual memory items
  • Stored as user-scoped memories
  • No structure or organization
  • No confidence scoring
  • No versioning

After (v2.2+):

  • User learning creates/updates structured profile
  • Single profile per user
  • Organized into categories
  • Confidence and frequency tracking
  • Full versioning and changelog

Breaking Changes

  1. User-scoped addMemory deprecated:

    // ❌ No longer works
memory({ mode: "add", content: "...", scope: "user" })
// Returns error: "User-scoped memories are deprecated"

  2. Profile API changed:

    // ❌ Old structure (v2.1)
{
  profile: {
    static: ["fact1", "fact2"],
    dynamic: ["fact3", "fact4"]
  }
}

// ✅ New structure (v2.2)
{
  profile: {
    preferences: [{...}],
    patterns: [{...}],
    workflows: [{...}],
    skillLevel: {...}
  }
}

Migration Steps

  1. Update code using mode: "profile":

    • Handle new structure (preferences/patterns/workflows/skillLevel)
    • Remove references to static and dynamic fields

  2. Remove user-scoped add calls:

    • Delete any code calling memory({ mode: "add", scope: "user" })
    • Profile is now built automatically from prompts

  3. Add new config options (optional):

    {
  "userProfileMaxPreferences": 20,
  "userProfileMaxPatterns": 15,
  "userProfileMaxWorkflows": 10,
  "userProfileConfidenceDecayDays": 30,
  "userProfileChangelogRetentionCount": 5
}

  4. Existing user memories:

    • Remain readable in database
    • No longer created or updated
    • Will be used for search if queried
    • Consider exporting if needed

Web Interface

The web UI includes a dedicated Profile Viewer:

Features:

  • View current profile (preferences/patterns/workflows/skill level)
  • Browse changelog history
  • View snapshots of previous versions
  • See confidence scores and frequencies
  • Track profile evolution over time

Access: Navigate to "Profile" tab in web UI at http://127.0.0.1:4747

Best Practices

For Accurate Profiles

  1. Consistent interaction: Regular usage improves accuracy
  2. Clear communication: Explicit preferences are captured better
  3. Varied topics: Diverse prompts reveal more patterns
  4. Feedback loop: Review profile periodically

For Performance

  1. Adjust interval: Lower userMemoryAnalysisInterval for faster learning (higher cost)
  2. Tune limits: Reduce max items if profile too large
  3. Disable if unused: Set userMemoryAnalysisInterval: 0 to disable

For Privacy

  1. Review profile: Check what's captured via web UI
  2. Manual cleanup: Delete profile if needed (via database)
  3. Disable injection: Set injectProfile: false to exclude from context

Troubleshooting

Profile Not Created

Symptoms: mode: "profile" returns no profile

Causes:

  • Not enough prompts analyzed yet (need at least userMemoryAnalysisInterval)
  • User learning disabled (userMemoryAnalysisInterval: 0)
  • AI provider not configured

Solutions:

  • Wait for threshold to be reached
  • Check config: userMemoryAnalysisInterval > 0
  • Verify memoryProvider, memoryModel, memoryApiKey configured

Profile Not Updating

Symptoms: Profile version not incrementing

Causes:

  • Prompts not accumulating
  • Analysis failing silently
  • AI returning no changes

Solutions:

  • Check logs for errors
  • Verify API key valid
  • Try POST /api/profile/refresh to force update

Low Confidence Scores

Symptoms: All preferences have low confidence

Causes:

  • Inconsistent behavior
  • Insufficient evidence
  • Conflicting preferences

Solutions:

  • Be more consistent in requests
  • Explicitly state preferences
  • Review and remove conflicting items

Next Steps

Clone this wiki locally