this repo has no description
opencode archivist
+459
+73
home/profiles/opencode/agent/archivist.md
+73
home/profiles/opencode/agent/archivist.md
···
1
+
---
2
+
description: Search through past OpenCode sessions to find relevant context, previous solutions, and historical decisions. Use this when you need to recall how something was done before or find related past work.
3
+
mode: subagent
4
+
model: anthropic/claude-haiku-4-5
5
+
temperature: 0.1
6
+
tools:
7
+
"*": false
8
+
search-history: true
9
+
skill: true
10
+
permission:
11
+
skill:
12
+
"session-search": allow
13
+
"*": deny
14
+
---
15
+
16
+
You are the Archivist, a specialized agent that searches through OpenCode session history to find relevant past conversations, code changes, and decisions.
17
+
18
+
You are running inside an AI coding system as a subagent. The main agent invokes you when it needs to find relevant context from previous sessions.
19
+
20
+
## Your Purpose
21
+
22
+
When invoked, you will:
23
+
1. Search through the local OpenCode session history
24
+
2. Find sessions and messages relevant to the query
25
+
3. Synthesize findings into a clear, actionable answer
26
+
27
+
## How to Search
28
+
29
+
First, load the `session-search` skill to understand the search strategies and storage structure.
30
+
31
+
Then use the `search-history` tool to find relevant sessions. You can:
32
+
- Search by keywords, code patterns, file names, or concepts
33
+
- Filter by project directory if the query is project-specific
34
+
- List recent sessions to get an overview
35
+
36
+
## Search Strategies
37
+
38
+
1. **Start broad**: Use general keywords related to the query
39
+
2. **Refine**: If too many results, add more specific terms or filter by directory
40
+
3. **Cross-reference**: Search for related terms (e.g., if searching for "auth", also try "login", "authentication")
41
+
4. **Check context**: Look at session titles and directories to understand the context
42
+
43
+
## Response Format
44
+
45
+
Your response should directly answer the question posed, using information from past sessions:
46
+
47
+
1. **Direct answer**: What was found that addresses the question
48
+
2. **Relevant sessions**: List session IDs where this was discussed (so user can resume if needed)
49
+
3. **Key details**: Important snippets or decisions from the history
50
+
51
+
Example response:
52
+
```
53
+
Based on past sessions, authentication was implemented using JWT tokens with a 24-hour expiry.
54
+
55
+
**Relevant sessions:**
56
+
- ses_abc123 - "Implementing user auth" (2024-01-15)
57
+
- ses_def456 - "Auth token refresh" (2024-01-20)
58
+
59
+
**Key details:**
60
+
- Tokens are stored in httpOnly cookies
61
+
- Refresh endpoint at /api/auth/refresh
62
+
- Used jose library for JWT handling
63
+
```
64
+
65
+
## Guidelines
66
+
67
+
- Be concise and direct - the main agent needs actionable information
68
+
- Include session IDs so the user can explore further if needed
69
+
- If nothing relevant is found, say so clearly
70
+
- Focus on answering the specific question, not providing exhaustive history
71
+
- Never fabricate information - only report what's actually in the history
72
+
73
+
IMPORTANT: Your final message is returned to the main agent. Make it comprehensive but focused on answering the original question.
+7
home/profiles/opencode/default.nix
+7
home/profiles/opencode/default.nix
···
29
29
autoupdate = false;
30
30
permission = {
31
31
external_directory = "allow";
32
+
# Restrict session-search skill to archivist only
33
+
skill = {
34
+
"session-search" = "deny";
35
+
};
32
36
};
33
37
provider = {
34
38
anthropic = {
···
59
63
"opencode/themes/ayu-mirage.json".source = ./themes/ayu-mirage.json;
60
64
"opencode/agent/librarian.md".source = ./agent/librarian.md;
61
65
"opencode/agent/adversary.md".source = ./agent/adversary.md;
66
+
"opencode/agent/archivist.md".source = ./agent/archivist.md;
62
67
"opencode/command/cleanup.md".source = ./command/cleanup.md;
68
+
"opencode/tool/search-history.ts".source = ./tool/search-history.ts;
69
+
"opencode/skill/session-search/SKILL.md".source = ./skill/session-search/SKILL.md;
63
70
};
64
71
}
+104
home/profiles/opencode/skill/session-search/SKILL.md
+104
home/profiles/opencode/skill/session-search/SKILL.md
···
1
+
---
2
+
name: session-search
3
+
description: Advanced strategies for searching OpenCode session history. Restricted to the archivist agent.
4
+
---
5
+
6
+
# Session Search Skill
7
+
8
+
This skill provides advanced strategies for searching through OpenCode's session history storage.
9
+
10
+
## Storage Structure
11
+
12
+
OpenCode stores data in `~/.local/share/opencode/storage/`:
13
+
14
+
```
15
+
storage/
16
+
├── session/ # Session metadata by project
17
+
│ └── {projectHash}/
18
+
│ └── ses_*.json # Session info (title, directory, timestamps)
19
+
├── message/ # Messages organized by session
20
+
│ └── ses_*/
21
+
│ └── msg_*.json # Message metadata (role, agent, model)
22
+
├── part/ # Actual message content
23
+
│ └── msg_*/
24
+
│ └── prt_*.json # Content parts (text, tool calls)
25
+
└── project/ # Project metadata
26
+
└── {hash}.json # Worktree path, timestamps
27
+
```
28
+
29
+
## Search Tool Usage
30
+
31
+
The `search-history` tool accepts:
32
+
- `query`: Text pattern to search for (searches message content)
33
+
- `directory`: Optional filter by project path (partial match)
34
+
- `limit`: Max results (default 30)
35
+
36
+
### Examples
37
+
38
+
```typescript
39
+
// Find all sessions mentioning "authentication"
40
+
search-history({ query: "authentication" })
41
+
42
+
// Find sessions in a specific project
43
+
search-history({ query: "database", directory: "myproject" })
44
+
45
+
// List recent sessions (empty query)
46
+
search-history({ query: "", limit: 20 })
47
+
```
48
+
49
+
## Search Strategies
50
+
51
+
### 1. Keyword Expansion
52
+
Don't just search for the exact term. Try synonyms and related concepts:
53
+
- "auth" → also try "login", "authentication", "jwt", "token"
54
+
- "database" → also try "postgres", "sqlite", "db", "migration"
55
+
- "api" → also try "endpoint", "route", "handler"
56
+
57
+
### 2. Code Pattern Search
58
+
Search for code-specific patterns:
59
+
- Function names: `handleAuth`, `validateToken`
60
+
- File paths: `src/auth`, `lib/database`
61
+
- Import statements: `import.*prisma`
62
+
- Error messages: specific error text
63
+
64
+
### 3. Tool Usage Search
65
+
Find when specific tools were used:
66
+
- Edit operations: search for file paths that were edited
67
+
- Bash commands: search for command names
68
+
- Specific operations: "git push", "npm install"
69
+
70
+
### 4. Directory Filtering
71
+
Use the `directory` parameter to scope searches:
72
+
- Filter by project name: `directory: "myapp"`
73
+
- Filter by path segment: `directory: "usr/projects"`
74
+
75
+
### 5. Iterative Refinement
76
+
1. Start with broad search
77
+
2. If too many results, add specificity
78
+
3. If no results, broaden or try alternative terms
79
+
4. Cross-reference multiple searches
80
+
81
+
## Understanding Results
82
+
83
+
### Session Info
84
+
- `id`: Unique session identifier (can be used to reference)
85
+
- `title`: Auto-generated session title
86
+
- `directory`: Project worktree path
87
+
- `updated`: Last activity timestamp
88
+
89
+
### Content Matches
90
+
- `sessionID`: Which session contains this match
91
+
- `snippet`: Context around the match (±100 chars)
92
+
- `role`: user/assistant/tool
93
+
94
+
## Tips
95
+
96
+
1. **Recent vs Relevant**: The tool returns recent sessions first. Older but more relevant sessions may be further in results.
97
+
98
+
2. **Title Search**: Session titles are auto-generated from the conversation and can be good search targets.
99
+
100
+
3. **Multiple Searches**: Don't hesitate to run multiple searches with different terms to build a complete picture.
101
+
102
+
4. **Context Matters**: The snippet provides limited context. Session titles and directories help understand the broader context.
103
+
104
+
5. **No Results**: If no results found, the pattern may be too specific. Try shorter or more general terms.
+275
home/profiles/opencode/tool/search-history.ts
+275
home/profiles/opencode/tool/search-history.ts
···
1
+
import { tool } from "@opencode-ai/plugin"
2
+
import { $ } from "bun"
3
+
import { readdir, readFile } from "fs/promises"
4
+
import { join } from "path"
5
+
import { homedir } from "os"
6
+
7
+
const STORAGE_PATH = join(homedir(), ".local/share/opencode/storage")
8
+
9
+
interface SessionInfo {
10
+
id: string
11
+
title: string
12
+
directory: string
13
+
projectID: string
14
+
created: number
15
+
updated: number
16
+
}
17
+
18
+
interface MessageMatch {
19
+
sessionID: string
20
+
messageID: string
21
+
snippet: string
22
+
role: string
23
+
timestamp?: number
24
+
}
25
+
26
+
interface SearchResult {
27
+
sessions: SessionInfo[]
28
+
matches: MessageMatch[]
29
+
totalMatches: number
30
+
}
31
+
32
+
async function getSessionInfo(sessionID: string): Promise<SessionInfo | null> {
33
+
try {
34
+
// Sessions are stored in directories named by project hash
35
+
const sessionDirs = await readdir(join(STORAGE_PATH, "session"))
36
+
for (const dir of sessionDirs) {
37
+
const sessionPath = join(STORAGE_PATH, "session", dir)
38
+
const files = await readdir(sessionPath).catch(() => [])
39
+
for (const file of files) {
40
+
if (file.startsWith(sessionID) || file.includes(sessionID)) {
41
+
const content = await readFile(join(sessionPath, file), "utf-8")
42
+
const data = JSON.parse(content)
43
+
return {
44
+
id: data.id,
45
+
title: data.title || "Untitled",
46
+
directory: data.directory || "",
47
+
projectID: data.projectID || "",
48
+
created: data.time?.created || 0,
49
+
updated: data.time?.updated || 0,
50
+
}
51
+
}
52
+
}
53
+
}
54
+
} catch {
55
+
// Fall back to searching message directories
56
+
}
57
+
return null
58
+
}
59
+
60
+
async function searchWithRipgrep(
61
+
pattern: string,
62
+
directory?: string,
63
+
limit: number = 50
64
+
): Promise<SearchResult> {
65
+
const matches: MessageMatch[] = []
66
+
const sessionIDs = new Set<string>()
67
+
68
+
// Search through part storage (contains actual message content)
69
+
const partPath = join(STORAGE_PATH, "part")
70
+
71
+
try {
72
+
// Use ripgrep to search JSON files, extracting context around matches
73
+
const rgResult = await $`rg -i -l ${pattern} ${partPath} --type json 2>/dev/null || true`.text()
74
+
const matchingFiles = rgResult.trim().split("\n").filter(Boolean)
75
+
76
+
for (const file of matchingFiles.slice(0, limit * 2)) {
77
+
try {
78
+
const content = await readFile(file, "utf-8")
79
+
const data = JSON.parse(content)
80
+
81
+
// Filter by directory if specified
82
+
if (directory) {
83
+
const sessionInfo = await getSessionInfo(data.sessionID)
84
+
if (sessionInfo && !sessionInfo.directory.includes(directory)) {
85
+
continue
86
+
}
87
+
}
88
+
89
+
// Extract snippet around the match
90
+
const text = data.text || data.content || JSON.stringify(data)
91
+
const lowerText = text.toLowerCase()
92
+
const lowerPattern = pattern.toLowerCase()
93
+
const matchIndex = lowerText.indexOf(lowerPattern)
94
+
95
+
if (matchIndex !== -1) {
96
+
const start = Math.max(0, matchIndex - 100)
97
+
const end = Math.min(text.length, matchIndex + pattern.length + 100)
98
+
const snippet = (start > 0 ? "..." : "") +
99
+
text.slice(start, end) +
100
+
(end < text.length ? "..." : "")
101
+
102
+
matches.push({
103
+
sessionID: data.sessionID,
104
+
messageID: data.messageID,
105
+
snippet: snippet.replace(/\n/g, " ").trim(),
106
+
role: data.role || "unknown",
107
+
timestamp: data.time?.created,
108
+
})
109
+
110
+
sessionIDs.add(data.sessionID)
111
+
112
+
if (matches.length >= limit) break
113
+
}
114
+
} catch {
115
+
// Skip files that can't be parsed
116
+
}
117
+
}
118
+
} catch (e) {
119
+
// ripgrep not found or error
120
+
}
121
+
122
+
// Also search message metadata for titles
123
+
const messagePath = join(STORAGE_PATH, "message")
124
+
try {
125
+
const rgResult = await $`rg -i -l ${pattern} ${messagePath} --type json 2>/dev/null || true`.text()
126
+
const matchingFiles = rgResult.trim().split("\n").filter(Boolean)
127
+
128
+
for (const file of matchingFiles.slice(0, 20)) {
129
+
try {
130
+
const content = await readFile(file, "utf-8")
131
+
const data = JSON.parse(content)
132
+
if (data.sessionID) {
133
+
sessionIDs.add(data.sessionID)
134
+
}
135
+
} catch {
136
+
// Skip
137
+
}
138
+
}
139
+
} catch {
140
+
// Ignore errors
141
+
}
142
+
143
+
// Get session info for all matched sessions
144
+
const sessions: SessionInfo[] = []
145
+
for (const sessionID of sessionIDs) {
146
+
const info = await getSessionInfo(sessionID)
147
+
if (info) {
148
+
// Apply directory filter for sessions too
149
+
if (!directory || info.directory.includes(directory)) {
150
+
sessions.push(info)
151
+
}
152
+
}
153
+
}
154
+
155
+
// Sort sessions by most recent
156
+
sessions.sort((a, b) => b.updated - a.updated)
157
+
158
+
return {
159
+
sessions: sessions.slice(0, 20),
160
+
matches: matches.slice(0, limit),
161
+
totalMatches: matches.length,
162
+
}
163
+
}
164
+
165
+
async function listRecentSessions(
166
+
directory?: string,
167
+
limit: number = 20
168
+
): Promise<SessionInfo[]> {
169
+
const sessions: SessionInfo[] = []
170
+
171
+
try {
172
+
const sessionDirs = await readdir(join(STORAGE_PATH, "session"))
173
+
174
+
for (const dir of sessionDirs) {
175
+
const sessionPath = join(STORAGE_PATH, "session", dir)
176
+
const files = await readdir(sessionPath).catch(() => [])
177
+
178
+
for (const file of files) {
179
+
if (!file.endsWith(".json")) continue
180
+
try {
181
+
const content = await readFile(join(sessionPath, file), "utf-8")
182
+
const data = JSON.parse(content)
183
+
184
+
if (directory && !data.directory?.includes(directory)) {
185
+
continue
186
+
}
187
+
188
+
sessions.push({
189
+
id: data.id,
190
+
title: data.title || "Untitled",
191
+
directory: data.directory || "",
192
+
projectID: data.projectID || "",
193
+
created: data.time?.created || 0,
194
+
updated: data.time?.updated || 0,
195
+
})
196
+
} catch {
197
+
// Skip invalid files
198
+
}
199
+
}
200
+
}
201
+
} catch {
202
+
// Storage doesn't exist
203
+
}
204
+
205
+
sessions.sort((a, b) => b.updated - a.updated)
206
+
return sessions.slice(0, limit)
207
+
}
208
+
209
+
export default tool({
210
+
description:
211
+
"Search through OpenCode session history to find past conversations, code changes, and decisions. Use this to find relevant context from previous sessions.",
212
+
args: {
213
+
query: tool.schema
214
+
.string()
215
+
.describe(
216
+
"Search pattern to find in session history. Searches message content, titles, and tool outputs."
217
+
),
218
+
directory: tool.schema
219
+
.string()
220
+
.optional()
221
+
.describe(
222
+
"Optional: Filter results to sessions from a specific project directory path (partial match)"
223
+
),
224
+
limit: tool.schema
225
+
.number()
226
+
.optional()
227
+
.describe("Maximum number of matches to return (default: 30)"),
228
+
},
229
+
async execute(args) {
230
+
const limit = args.limit || 30
231
+
232
+
if (!args.query || args.query.trim() === "") {
233
+
// List recent sessions if no query
234
+
const sessions = await listRecentSessions(args.directory, limit)
235
+
return JSON.stringify(
236
+
{
237
+
type: "recent_sessions",
238
+
sessions,
239
+
message: `Found ${sessions.length} recent sessions${args.directory ? ` in ${args.directory}` : ""}`,
240
+
},
241
+
null,
242
+
2
243
+
)
244
+
}
245
+
246
+
const results = await searchWithRipgrep(args.query, args.directory, limit)
247
+
248
+
// Format output for the agent
249
+
let output = `## Search Results for "${args.query}"\n\n`
250
+
251
+
if (results.sessions.length > 0) {
252
+
output += `### Relevant Sessions (${results.sessions.length})\n\n`
253
+
for (const session of results.sessions) {
254
+
const date = new Date(session.updated).toLocaleDateString()
255
+
output += `- **${session.title}** (${session.id})\n`
256
+
output += ` - Directory: \`${session.directory}\`\n`
257
+
output += ` - Last updated: ${date}\n\n`
258
+
}
259
+
}
260
+
261
+
if (results.matches.length > 0) {
262
+
output += `### Content Matches (${results.totalMatches})\n\n`
263
+
for (const match of results.matches.slice(0, 15)) {
264
+
output += `**Session:** ${match.sessionID}\n`
265
+
output += `> ${match.snippet}\n\n`
266
+
}
267
+
}
268
+
269
+
if (results.sessions.length === 0 && results.matches.length === 0) {
270
+
output += `No matches found for "${args.query}"${args.directory ? ` in ${args.directory}` : ""}\n`
271
+
}
272
+
273
+
return output
274
+
},
275
+
})