opencode-session-recall 0.6.0 → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +88 -57
- package/dist/opencode-session-recall.js +9 -9
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,26 +1,77 @@
|
|
|
1
1
|
# opencode-session-recall
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Everything your agent ever did is already in the database. It's just not looking.**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
OpenCode stores the full conversation history your agent worked through — messages, tool calls, tool outputs, reasoning traces — even after compaction removes them from the active context window. As conversations get long, OpenCode shrinks what the model can see. The old content is still stored, just no longer visible to the agent.
|
|
6
6
|
|
|
7
|
-
This plugin
|
|
7
|
+
This plugin gives the agent five tools to search and retrieve all of it on demand — within the current session, across every session in the project, or across every project on the machine.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
[OpenCode](https://github.com/opencode-ai/opencode) is an open-source AI coding agent that runs in your terminal.
|
|
10
10
|
|
|
11
|
-
No
|
|
11
|
+
**No new database.**
|
|
12
|
+
**No embeddings.**
|
|
13
|
+
**No summarization.**
|
|
14
|
+
**No duplication.**
|
|
15
|
+
**No overhead.**
|
|
12
16
|
|
|
13
|
-
|
|
17
|
+
Just install the plugin. The agent can search its own history.
|
|
14
18
|
|
|
15
|
-
|
|
19
|
+
## The problem is absurd when you think about it
|
|
16
20
|
|
|
17
|
-
|
|
21
|
+
Your agent solves a tricky build error. Twenty minutes later, compaction runs. An hour later, the same error shows up. The agent starts from zero — debugging something it already figured out, while the answer sits in the database it's connected to.
|
|
18
22
|
|
|
19
|
-
|
|
23
|
+
You're 200 tool calls and 3 compactions deep. The agent has drifted from your original request. Your exact words are gone from context. But they're not gone — they're in the database. The agent just can't see them.
|
|
20
24
|
|
|
21
|
-
|
|
25
|
+
The data already exists. This plugin removes the blindfold.
|
|
22
26
|
|
|
23
|
-
|
|
27
|
+
## What it looks like
|
|
28
|
+
|
|
29
|
+
**"We already fixed this."**
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
recall({ query: "ECONNREFUSED retry", scope: "session" })
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Agent finds its own solution from 2 hours ago. Doesn't re-derive it.
|
|
36
|
+
|
|
37
|
+
**"It was in that other project."**
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
recall_sessions({ scope: "global", search: "rate limit" })
|
|
41
|
+
recall_get({ sessionID: "...", messageID: "..." })
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Finds the implementation from your API project. Reuses it instead of reinventing it.
|
|
45
|
+
|
|
46
|
+
**"What did I originally ask for?"**
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
recall_messages({ limit: 5, role: "user" })
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Pulls up exact original requirements after 3 compactions. Checks its own work against what you actually said.
|
|
53
|
+
|
|
54
|
+
**"What was that error?"**
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
recall({ query: "TypeError", type: "tool", scope: "session" })
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Gets the full stack trace from a tool output that got pruned. Doesn't re-run the failing command.
|
|
61
|
+
|
|
62
|
+
**"Why did we decide on that approach?"**
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
recall({ query: "chose postgres over", scope: "project", type: "reasoning" })
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Recovers the reasoning behind an architectural decision from three sessions ago. Context that no summary captures.
|
|
69
|
+
|
|
70
|
+
## Recall is not memory
|
|
71
|
+
|
|
72
|
+
This is not a memory system. Memory is selective and curated. Recall is raw history retrieval — verbatim, exhaustive, on demand.
|
|
73
|
+
|
|
74
|
+
If you use a persistent memory system alongside this plugin, recall gives it source material. The agent searches history, finds something useful, and stores it deliberately. Discovery first, then permanent memory.
|
|
24
75
|
|
|
25
76
|
## Install
|
|
26
77
|
|
|
@@ -28,16 +79,19 @@ No embeddings. No vector store. No data duplication. No setup. Just install the
|
|
|
28
79
|
opencode plugin opencode-session-recall
|
|
29
80
|
```
|
|
30
81
|
|
|
31
|
-
Or add it to your `opencode.json
|
|
82
|
+
Or add it to your `opencode.json`:
|
|
32
83
|
|
|
33
84
|
```jsonc
|
|
34
85
|
{
|
|
35
|
-
"plugin": [
|
|
36
|
-
|
|
86
|
+
"plugin": ["opencode-session-recall"],
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
To disable cross-project search:
|
|
37
91
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
],
|
|
92
|
+
```jsonc
|
|
93
|
+
{
|
|
94
|
+
"plugin": [["opencode-session-recall", { "global": false }]],
|
|
41
95
|
}
|
|
42
96
|
```
|
|
43
97
|
|
|
@@ -47,25 +101,25 @@ Five tools, designed around how agents actually navigate conversation history:
|
|
|
47
101
|
|
|
48
102
|
### `recall` — Search
|
|
49
103
|
|
|
50
|
-
The primary tool. Full-text search across
|
|
104
|
+
The primary tool. Full-text search across messages, tool outputs, tool inputs, reasoning, and subtask descriptions. Searches globally by default, or narrow to the current project or session.
|
|
51
105
|
|
|
52
106
|
```
|
|
53
107
|
recall({ query: "authentication", scope: "project" })
|
|
54
|
-
recall({ query: "error",
|
|
108
|
+
recall({ query: "error", type: "tool", scope: "session" })
|
|
55
109
|
recall({ query: "JWT", sessionID: "ses_from_another_project" })
|
|
56
110
|
```
|
|
57
111
|
|
|
58
|
-
| Param | Default
|
|
59
|
-
| ---------------- |
|
|
60
|
-
| `query` | required
|
|
61
|
-
| `scope` | `"
|
|
62
|
-
| `sessionID` | —
|
|
63
|
-
| `type` | `"all"`
|
|
64
|
-
| `role` | `"all"`
|
|
65
|
-
| `before`/`after` | —
|
|
66
|
-
| `width` | `200`
|
|
67
|
-
| `sessions` | `10`
|
|
68
|
-
| `results` | `10`
|
|
112
|
+
| Param | Default | Description |
|
|
113
|
+
| ---------------- | ---------- | --------------------------------------------- |
|
|
114
|
+
| `query` | required | Text to search for (case-insensitive) |
|
|
115
|
+
| `scope` | `"global"` | `"session"`, `"project"`, or `"global"` |
|
|
116
|
+
| `sessionID` | — | Target a specific session (overrides scope) |
|
|
117
|
+
| `type` | `"all"` | `"text"`, `"tool"`, `"reasoning"`, or `"all"` |
|
|
118
|
+
| `role` | `"all"` | `"user"`, `"assistant"`, or `"all"` |
|
|
119
|
+
| `before`/`after` | — | Timestamp filters (ms epoch) |
|
|
120
|
+
| `width` | `200` | Snippet size (50–1000 chars) |
|
|
121
|
+
| `sessions` | `10` | Max sessions to scan |
|
|
122
|
+
| `results` | `10` | Max results to return |
|
|
69
123
|
|
|
70
124
|
### `recall_get` — Retrieve
|
|
71
125
|
|
|
@@ -107,29 +161,6 @@ recall_sessions({ scope: "project", search: "auth" })
|
|
|
107
161
|
recall_sessions({ scope: "global", search: "deployment" })
|
|
108
162
|
```
|
|
109
163
|
|
|
110
|
-
## Real-world workflow
|
|
111
|
-
|
|
112
|
-
This is what it actually looks like when an agent uses these tools to answer "what have we been doing with our UniFi network?" across a 3-week, 600+ message session in a different project:
|
|
113
|
-
|
|
114
|
-
```
|
|
115
|
-
1. recall_sessions({ scope: "global", search: "unifi" })
|
|
116
|
-
→ discovers the ubiopti project session
|
|
117
|
-
|
|
118
|
-
2. recall_messages({ sessionID: "...", limit: 5, role: "user", reverse: true })
|
|
119
|
-
→ reads the most recent user messages to understand current state
|
|
120
|
-
|
|
121
|
-
3. recall({ query: "kickout threshold", sessionID: "...", width: 500 })
|
|
122
|
-
→ finds the technical root cause analysis in tool outputs
|
|
123
|
-
|
|
124
|
-
4. recall_context({ sessionID: "...", messageID: "...", window: 3 })
|
|
125
|
-
→ expands around the Ubiquiti support chat to see the full interaction
|
|
126
|
-
|
|
127
|
-
5. recall({ query: "iwpriv", sessionID: "...", after: <recent timestamp> })
|
|
128
|
-
→ finds only recent mentions, not the whole session history
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
Five tool calls, complete narrative reconstructed across projects.
|
|
132
|
-
|
|
133
164
|
## Options
|
|
134
165
|
|
|
135
166
|
| Option | Type | Default | Description |
|
|
@@ -139,13 +170,13 @@ Five tool calls, complete narrative reconstructed across projects.
|
|
|
139
170
|
|
|
140
171
|
## How it works
|
|
141
172
|
|
|
142
|
-
|
|
173
|
+
When OpenCode compacts a session, it doesn't delete anything. Tool outputs get a `compacted` timestamp and are replaced with placeholder text in the LLM's context — but the original data stays in the database. Messages before a compaction boundary are skipped when building the LLM context — but they're still there.
|
|
143
174
|
|
|
144
|
-
|
|
175
|
+
This plugin reads all of it through the OpenCode SDK:
|
|
145
176
|
|
|
146
|
-
-
|
|
177
|
+
- No direct database queries, no separate storage
|
|
147
178
|
- Zero setup — no embeddings to generate, no indexes to build, no data to sync
|
|
148
|
-
- Sessions
|
|
179
|
+
- Sessions scanned newest-first with bounded concurrency
|
|
149
180
|
- Respects abort signals for long-running searches
|
|
150
181
|
- Cross-project search enabled by default (disable with `global: false`)
|
|
151
182
|
|
|
@@ -40,9 +40,9 @@ function errmsg(e) {
|
|
|
40
40
|
// src/sessions.ts
|
|
41
41
|
function sessions(client, unscoped, global, limits) {
|
|
42
42
|
return tool({
|
|
43
|
-
description: `List sessions from the opencode database.
|
|
43
|
+
description: `List sessions from the opencode database. Returns session titles, directories, and timestamps. For cross-project discovery, use scope "global" (enabled by default, disable with plugin option global: false).
|
|
44
44
|
|
|
45
|
-
|
|
45
|
+
This is a metadata-only listing tool, NOT a content search. Session titles are usually auto-generated timestamps and won't match topic keywords. To find prior work on a topic, use recall (content search) instead \u2014 it searches inside actual messages and tool outputs. Use recall_sessions to browse recent sessions by project, check session recency, or get session IDs for recall_messages.
|
|
46
46
|
|
|
47
47
|
Returns { ok, sessions: [{ id, title, directory, time, archived }], returned, scope }. All tools return JSON with ok: true on success or ok: false with error on failure.`,
|
|
48
48
|
args: {
|
|
@@ -312,33 +312,33 @@ function scan(messages2, session, query, type, role, limit, before, after, width
|
|
|
312
312
|
}
|
|
313
313
|
function search(client, unscoped, global, limits) {
|
|
314
314
|
return tool2({
|
|
315
|
-
description: `Search your conversation history in the opencode database.
|
|
315
|
+
description: `Search your conversation history in the opencode database. This is the primary discovery tool \u2014 use it before recall_sessions, which only searches titles. Before debugging an issue or implementing a feature, check whether prior sessions already tackled it \u2014 the history shows whether an approach succeeded or was abandoned. If you have access to a memory system, add useful findings to memory so they're available directly next time without searching history.
|
|
316
316
|
|
|
317
317
|
Searches text content, tool inputs/outputs, and reasoning via case-insensitive substring matching. Returns matching snippets with session/message IDs you can pass to recall_get for full content, or recall_context if you need surrounding messages.
|
|
318
318
|
|
|
319
|
-
|
|
319
|
+
Searches globally by default \u2014 this is fast and finds results across all projects. Results are ordered by session recency (newest first). Try multiple query terms before concluding no prior work exists. Use role "user" to find original requirements.
|
|
320
320
|
|
|
321
|
-
Scope costs:
|
|
321
|
+
Scope costs: all scopes scan up to \`sessions\` sessions (default 10). "session" scans 1. "project" and "global" scan up to 10 newest. Increase \`sessions\` if nothing found.
|
|
322
322
|
|
|
323
323
|
Returns { ok, results: [{ sessionID, messageID, role, time, partID, partType, pruned, snippet, toolName? }], scanned, total, truncated }. Each result includes a pruned flag \u2014 if true, the content was compacted from your context window and recall_get will return the original full output. Check truncated to know if more matches exist beyond your results limit.
|
|
324
324
|
|
|
325
325
|
This tool's own outputs are excluded from search results to prevent recursive noise; use recall_get or recall_context to retrieve any message directly.`,
|
|
326
326
|
args: {
|
|
327
327
|
query: tool2.schema.string().min(1).describe("Text to search for (case-insensitive substring match)"),
|
|
328
|
-
scope: tool2.schema.enum(["session", "project", "global"]).default("
|
|
329
|
-
"
|
|
328
|
+
scope: tool2.schema.enum(["session", "project", "global"]).default("global").describe(
|
|
329
|
+
"global = all projects (default), project = current project, session = current only. Searching broadly is fast."
|
|
330
330
|
),
|
|
331
331
|
sessionID: tool2.schema.string().optional().describe("Search a specific session (overrides scope)"),
|
|
332
332
|
type: tool2.schema.enum(["text", "tool", "reasoning", "all"]).default("all").describe("Filter by part type"),
|
|
333
333
|
role: tool2.schema.enum(["user", "assistant", "all"]).default("all").describe("Filter by message role"),
|
|
334
334
|
sessions: tool2.schema.number().min(1).max(limits.maxSessions).default(Math.min(10, limits.maxSessions)).describe(
|
|
335
|
-
"Max sessions to scan
|
|
335
|
+
"Max sessions to scan. Increase if nothing found \u2014 default 10 may miss older sessions."
|
|
336
336
|
),
|
|
337
337
|
results: tool2.schema.number().min(1).max(limits.maxResults).default(Math.min(10, limits.maxResults)).describe(
|
|
338
338
|
"Max results to return. Check truncated in response for more."
|
|
339
339
|
),
|
|
340
340
|
title: tool2.schema.string().optional().describe(
|
|
341
|
-
"Filter sessions by title before scanning (
|
|
341
|
+
"Filter sessions by title before scanning (rarely useful \u2014 titles are usually auto-generated)"
|
|
342
342
|
),
|
|
343
343
|
before: tool2.schema.number().optional().describe("Only match messages before this timestamp (ms epoch)"),
|
|
344
344
|
after: tool2.schema.number().optional().describe("Only match messages after this timestamp (ms epoch)"),
|
package/package.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json.schemastore.org/package.json",
|
|
3
3
|
"name": "opencode-session-recall",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.7.1",
|
|
5
5
|
"type": "module",
|
|
6
|
-
"description": "
|
|
6
|
+
"description": "Everything your agent ever did is already in the database — this plugin lets it look",
|
|
7
7
|
"main": "./dist/opencode-session-recall.js",
|
|
8
8
|
"exports": {
|
|
9
9
|
".": {
|