Skip to content

Web Interface

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

Web Interface

Complete guide to the OpenCode Memory web interface for visual memory management.

Accessing the Interface

Default URL: http://127.0.0.1:4747

Custom port (if configured):

{
  "webServerPort": 4748
}

Then access: http://127.0.0.1:4748

Interface Overview

The web interface provides:

  • Unified timeline of memories and prompts
  • User profile viewer with changelog
  • Prompt-memory linking with visual indicators
  • Memory browser with search and filters
  • Memory editor for inline editing
  • Bulk operations for multiple items
  • Cascade delete for linked items
  • Maintenance tools (cleanup, deduplication, migration)
  • Statistics dashboard
  • Real-time updates

Main Features

Unified Timeline

New in v2.0: Browse memories and prompts together in a single timeline.

Tab System:

  • Project Timeline: Project-scoped memories + all prompts
  • User Timeline: User-scoped memories only (deprecated in v2.2+)
  • Profile: User profile viewer (new in v2.2)

Visual Distinction:

  • Memory cards: Green border (#00ff00)
  • Prompt cards: Blue border (#00ccff)
  • Linked badge: Magenta with pulse animation (#ff00ff)

Link Indicators:

  • Arrow shows prompt→memory relationship
  • Click linked badge to navigate to linked item
  • Cascade delete option for linked pairs

Timeline Sorting (improved in v2.2):

  • Linked prompt-memory pairs grouped together
  • Pairs sorted by memory creation time
  • Standalone items sorted separately
  • Maintains chronological context

User Profile Viewer

New in v2.2: View structured user profile with changelog.

Profile Display:

  • Preferences: With confidence scores and evidence
  • Patterns: With frequency tracking
  • Workflows: With step sequences
  • Skill Level: Overall and per-domain assessment
  • Metadata: Version, last analyzed, total prompts

Changelog:

  • View profile version history
  • See what changed in each update
  • Access previous profile snapshots
  • Track learning progress over time

Actions:

  • Refresh profile (force analysis)
  • View changelog entries
  • Inspect profile snapshots
  • Export profile data

See User Profile System for complete details.

Memory Browser

View All Memories:

  • Paginated list of all memories
  • Sort by date (newest first)
  • Filter by scope, type, or tags
  • Search by keyword or similarity

Memory Cards:

Each memory displays:

  • Content preview (markdown rendered)
  • Scope badge (user/project)
  • Type label
  • Creation date
  • Pin status
  • Linked prompt indicator (if linked)
  • Action buttons (edit, delete, pin)

Prompt Cards:

Each prompt displays:

  • Prompt text preview
  • Captured status badge
  • Creation date
  • Linked memory indicator (if linked)
  • Action buttons (delete)

Search

Text Search:

Enter keywords to search memory content:

authentication JWT

Searches for memories containing "authentication" or "JWT".

Clear Search:

Click "Clear" button to reset search.

Search Options:

  • Scope filter (all, user, project)
  • Real-time search as you type

Filters

By Scope:

  • All memories
  • User scope only
  • Project scope only

By Type:

  • All types
  • Specific type (preference, architecture, etc.)

By Tags:

  • Filter by custom tags
  • Multiple tag selection

By Status:

  • All items
  • Pinned only
  • Linked only

Memory Editor

Edit Memory:

  1. Click memory card
  2. Edit modal opens
  3. Modify content, scope, type, or tags
  4. Click "Save" to update

Editable Fields:

  • Content (text area with markdown support)
  • Scope (dropdown: user/project)
  • Type (text input)
  • Tags (comma-separated)
  • Pinned status (checkbox)

Validation:

  • Content cannot be empty
  • Scope must be user or project
  • Changes saved immediately

Bulk Operations

Select Multiple Items:

  1. Click checkbox on memory/prompt cards
  2. Select multiple items (mixed types supported)
  3. Choose bulk action

Available Actions:

  • Delete selected (with cascade option)
  • Export selected (JSON)

Select All:

Click "Select All" to select all visible items on current page.

Pin Memories

Pin Important Memories:

Click pin icon on memory card to mark as important.

Pinned Behavior:

  • Appear at top of list
  • Highlighted with pin icon
  • Excluded from auto-cleanup
  • Protected from deletion during cleanup

Unpin:

Click pin icon again to unpin.

Delete Operations

Delete Single Memory:

Click delete icon on memory card.

Delete Single Prompt:

Click delete icon on prompt card.

Cascade Delete:

When deleting a memory or prompt that has a link:

  • Option to delete linked item together
  • Checkbox: "Also delete linked prompt/memory"
  • Prevents orphaned data

Delete Multiple:

  1. Select items using checkboxes
  2. Click "Delete Selected"
  3. Choose cascade option (if applicable)
  4. Confirm deletion

Confirmation:

Deletion requires confirmation to prevent accidents.

Pagination

Top and Bottom Controls:

  • Previous/Next buttons
  • Page number display
  • Jump to page input
  • Items per page selector

Default: 20 items per page

Auto-Refresh

Automatic Updates:

  • Refreshes every 30 seconds
  • Updates timeline without page reload
  • Preserves current page and filters

Manual Refresh:

Click refresh button to update immediately.

Maintenance Tools

Cleanup

Remove old memories based on retention period.

Access: Click "Maintenance" tab, then "Cleanup"

Options:

  • Retention days (default: 30)
  • Dry run mode (preview without deleting)
  • Exclude pinned memories
  • Exclude linked memories

Process:

  1. Set retention days
  2. Enable dry run (optional)
  3. Click "Run Cleanup"
  4. Review results
  5. Run again without dry run to delete

Results:

  • Total memories scanned
  • Memories to delete
  • Memories deleted (if not dry run)
  • Pinned memories skipped
  • Linked memories skipped

Protection:

  • Pinned memories are never deleted
  • Memories linked to prompts are protected
  • User confirmation required

Deduplication

Find and remove similar duplicate memories.

Access: Click "Maintenance" tab, then "Deduplication"

Options:

  • Similarity threshold (default: 0.9)
  • Dry run mode
  • Keep newest/oldest

Process:

  1. Set similarity threshold
  2. Enable dry run (optional)
  3. Click "Run Deduplication"
  4. Review duplicate groups
  5. Run again without dry run to delete

Results:

  • Duplicate groups found
  • Memories to delete
  • Memories deleted (if not dry run)
  • Space saved

Threshold Guide:

  • 0.95+: Very conservative, only exact duplicates
  • 0.90: Default, similar duplicates
  • 0.85: Aggressive, may remove related memories

Migration

Change embedding model dimensions.

Access: Click "Maintenance" tab, then "Migration"

When to Use:

  • Switching embedding models
  • Changing vector dimensions
  • Upgrading to better model

Options:

  • New model name
  • New dimensions
  • Batch size

Process:

  1. Select new model
  2. Enter new dimensions
  3. Click "Start Migration"
  4. Monitor progress
  5. Wait for completion

Progress:

  • Total memories
  • Processed memories
  • Percentage complete
  • Estimated time remaining

Warning: Migration can take time for large databases.

Statistics Dashboard

Access: View statistics in sidebar

Metrics Displayed:

Memory Counts:

  • Total memories
  • User scope memories (deprecated in v2.2+)
  • Project scope memories
  • Pinned memories

Prompt Counts:

  • Total prompts
  • Captured prompts
  • Linked prompts

User Profile (new in v2.2):

  • Profile version
  • Total prompts analyzed
  • Last analysis timestamp

Storage:

  • Database size
  • Number of shards
  • Average memory size

Auto-Capture:

  • Total captures
  • Memories created
  • Last capture time

Markdown Rendering

GitHub-Flavored Markdown:

  • Headers, lists, code blocks
  • Tables, links, images
  • Syntax highlighting for code
  • XSS protection with DOMPurify

Code Blocks:

function example() {
  return "Syntax highlighted";
}

Tables:

Feature Status
Linking ✓
Timeline ✓

Keyboard Shortcuts

Navigation:

  • Ctrl+F or /: Focus search
  • Esc: Close modal
  • Ctrl+A: Select all

Actions:

  • Delete: Delete selected
  • Ctrl+E: Edit selected (single)
  • Ctrl+P: Pin/unpin selected

Pagination:

  • ←: Previous page
  • →: Next page

Mobile Support

The interface is responsive and works on mobile devices:

  • Touch-friendly buttons
  • Swipe gestures
  • Optimized layout
  • Mobile search

API Integration

The web interface uses REST API endpoints:

GET /api/memories:

  • List memories with filters
  • includePrompts=true for unified timeline

POST /api/memories:

  • Create new memory

PUT /api/memories/:id:

  • Update memory

DELETE /api/memories/:id:

  • Delete memory
  • cascade=true to delete linked prompt

DELETE /api/prompts/:id:

  • Delete prompt
  • cascade=true to delete linked memory

POST /api/search:

  • Vector search

GET /api/stats:

  • Statistics

POST /api/cleanup:

  • Run cleanup

POST /api/deduplicate:

  • Run deduplication

POST /api/migrate:

  • Run migration

See API Reference for details.

Troubleshooting

Interface Not Loading

Check Server Status:

curl http://127.0.0.1:4747/api/stats

Verify Configuration:

{
  "webServerEnabled": true,
  "webServerPort": 4747
}

Check Logs:

Look for errors in OpenCode logs.

Slow Performance

Reduce Result Limit:

Lower the number of items displayed per page.

Increase Similarity Threshold:

Filter out less relevant results.

Run Cleanup:

Remove old memories to reduce database size.

Run Deduplication:

Remove duplicate memories.

Search Not Working

Check Embedding Model:

Ensure embedding model is loaded:

{
  "embeddingModel": "Xenova/nomic-embed-text-v1"
}

Verify Database:

Check database file exists:

ls -la ~/.opencode-mem/data/

Restart Server:

Restart OpenCode to reload configuration.

Links Not Showing

Check Database Schema:

Ensure user_prompts.linked_memory_id column exists.

Check API Response:

Verify includePrompts=true parameter is set.

Refresh Page:

Hard refresh (Ctrl+Shift+R) to clear cache.

Best Practices

Organization

Use Tags:

Add tags to memories for better organization:

react, frontend, component

Pin Important:

Pin critical memories to keep them accessible.

Regular Cleanup:

Run cleanup monthly to remove outdated memories.

Search

Use Filters:

Combine search with filters for precise results.

Adjust Threshold:

Lower threshold for broader results, higher for precision.

Save Searches:

Bookmark common searches in browser.

Maintenance

Dry Run First:

Always use dry run mode before actual cleanup or deduplication.

Backup Before Migration:

Export memories before running migration.

Monitor Statistics:

Check statistics regularly to track growth.

Linking

Review Links:

Periodically check prompt-memory links for accuracy.

Use Cascade Delete:

Delete linked pairs together to maintain consistency.

Timeline View:

Use timeline to understand conversation context.

Next Steps

Clone this wiki locally