---
name: session-search
description: 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

```typescript
// 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.