helm/home/profiles/opencode/skill/session-search/SKILL.md

name, description

name	description
session-search	Advanced strategies for searching OpenCode session history. Restricted to the archivist agent.

Session Search Skill

This skill provides advanced strategies for searching through OpenCode's session history storage.

Storage Structure

OpenCode stores data in ~/.local/share/opencode/storage/:

storage/
├── session/           # Session metadata by project
│   └── {projectHash}/
│       └── ses_*.json # Session info (title, directory, timestamps)
├── message/           # Messages organized by session
│   └── ses_*/
│       └── msg_*.json # Message metadata (role, agent, model)
├── part/              # Actual message content
│   └── msg_*/
│       └── prt_*.json # Content parts (text, tool calls)
└── project/           # Project metadata
    └── {hash}.json    # Worktree path, timestamps

Search Tool Usage

The search-history tool accepts:

• query: Text pattern to search for (searches message content)
• directory: Optional filter by project path (partial match)
• limit: Max results (default 30)

Examples

// Find all sessions mentioning "authentication"
search-history({ query: "authentication" })

// Find sessions in a specific project
search-history({ query: "database", directory: "myproject" })

// List recent sessions (empty query)
search-history({ query: "", limit: 20 })

Search Strategies

1. Keyword Expansion

Don't just search for the exact term. Try synonyms and related concepts:

• "auth" → also try "login", "authentication", "jwt", "token"
• "database" → also try "postgres", "sqlite", "db", "migration"
• "api" → also try "endpoint", "route", "handler"

2. Code Pattern Search

Search for code-specific patterns:

• Function names: handleAuth, validateToken
• File paths: src/auth, lib/database
• Import statements: import.*prisma
• Error messages: specific error text

3. Tool Usage Search

Find when specific tools were used:

• Edit operations: search for file paths that were edited
• Bash commands: search for command names
• Specific operations: "git push", "npm install"

4. Directory Filtering

Use the directory parameter to scope searches:

• Filter by project name: directory: "myapp"
• Filter by path segment: directory: "usr/projects"

5. Iterative Refinement

1. Start with broad search
2. If too many results, add specificity
3. If no results, broaden or try alternative terms
4. Cross-reference multiple searches

Understanding Results

Session Info

• id: Unique session identifier (can be used to reference)
• title: Auto-generated session title
• directory: Project worktree path
• updated: Last activity timestamp

Content Matches

• sessionID: Which session contains this match
• snippet: Context around the match (±100 chars)
• role: user/assistant/tool

Tips

1. Recent vs Relevant: The tool returns recent sessions first. Older but more relevant sessions may be further in results.

2. Title Search: Session titles are auto-generated from the conversation and can be good search targets.

3. Multiple Searches: Don't hesitate to run multiple searches with different terms to build a complete picture.

4. Context Matters: The snippet provides limited context. Session titles and directories help understand the broader context.

5. No Results: If no results found, the pattern may be too specific. Try shorter or more general terms.