opencode archivist

2026-01-19 22:37:40 -08:00
parent d0cde973e7
commit 928a3f56ad
4 changed files with 459 additions and 0 deletions
@@ -0,0 +1,104 @@
+---
+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.