opencode-rag-plugin 2.4.1 → 2.4.3
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 +5 -5
- package/dist/core/config.d.ts +8 -7
- package/dist/embedder/factory.d.ts +1 -1
- package/dist/embedder/factory.js +80 -3
- package/dist/plugin.js +1 -1
- package/dist/quirks/quirk-store.d.ts +12 -2
- package/dist/quirks/quirk-store.js +29 -5
- package/package.json +1 -1
package/ReadMe.md
CHANGED
|
@@ -196,7 +196,7 @@ See [Plugin documentation](doc/plugin.md#6-wiki-mode--slash-command-wiki) for th
|
|
|
196
196
|
|
|
197
197
|
## Quirk Memory
|
|
198
198
|
|
|
199
|
-
OpenCodeRAG gives your agent **persistent, cross-session memory** of non-obvious facts
|
|
199
|
+
OpenCodeRAG gives your agent **persistent, cross-session memory** of non-obvious facts - gotchas, preferences, decisions, and environment constraints - that it can recall and extend over time. Quirks are embedded and stored in the same vector store as your code, then **automatically injected into the agent's context on every user message** when their relevance score exceeds the configured threshold. Recall is gated by raw vector similarity (0-1, cosine mapped to [0,1]): `recallMinScore` (default 0.72) for manual `recall_quirks` calls, and the stricter `autoInjectMinScore` (default 0.75) for automatic injection - set it high (e.g. 0.85) to keep only strongly related quirks out of unrelated tasks. This lets the agent avoid repeating mistakes and accumulate project knowledge across sessions without manual recall.
|
|
200
200
|
|
|
201
201
|
**Enabled by default.** Turn it on/off in `opencode-rag.json`:
|
|
202
202
|
|
|
@@ -206,9 +206,9 @@ OpenCodeRAG gives your agent **persistent, cross-session memory** of non-obvious
|
|
|
206
206
|
"enabled": true,
|
|
207
207
|
"autoInject": true,
|
|
208
208
|
"minConfidence": 0.5,
|
|
209
|
-
"recallMinScore": 0.
|
|
210
|
-
"autoInjectMinScore": 0.
|
|
211
|
-
"autoInjectTopK":
|
|
209
|
+
"recallMinScore": 0.72,
|
|
210
|
+
"autoInjectMinScore": 0.75,
|
|
211
|
+
"autoInjectTopK": 1,
|
|
212
212
|
"autoInjectLatencyBudgetMs": 2000,
|
|
213
213
|
"decay": { "enabled": false, "halfLifeDays": 30 }
|
|
214
214
|
}
|
|
@@ -238,7 +238,7 @@ opencode-rag quirk test "npm needs --legacy-peer-deps"
|
|
|
238
238
|
# 99% confidence
|
|
239
239
|
```
|
|
240
240
|
|
|
241
|
-
When `memory.autoInject` is `true`, the plugin checks for relevant quirks on every user message using the combined agent-response + user-query as the search query. Quirks are only injected when their
|
|
241
|
+
When `memory.autoInject` is `true`, the plugin checks for relevant quirks on every user message using the combined agent-response + user-query as the search query. Quirks are only injected when their raw vector similarity to that query clears `autoInjectMinScore` (default 0.75) - the same threshold for the user-message and system-prompt injections; `recallMinScore` (default 0.72) is the bar for manual `recall_quirks` calls. A latency budget (`autoInjectLatencyBudgetMs`, default 2000ms) prevents slow embedders from blocking message processing. To avoid polluting the context window, each quirk is injected **at most once per session** — once recalled, it is filtered out from all subsequent auto-injections. Every `add_quirk` and every content-changing `update_quirk` is vetted by an immutable trust monitor that rejects destructive patterns (e.g. `rm -rf`, `force push`, `bypass security`). Outdated or fixed quirks should be corrected with `update_quirk` / `delete_quirk` rather than left to contradict newer memory. See [Plugin documentation](doc/plugin.md#9-quirk-memory-experiential-memory) and [CLI Reference: `quirk`](doc/cli.md#quirk).
|
|
242
242
|
|
|
243
243
|
## MCP Server (Optional)
|
|
244
244
|
|
package/dist/core/config.d.ts
CHANGED
|
@@ -231,13 +231,14 @@ export interface MemoryConfig {
|
|
|
231
231
|
autoInject: boolean;
|
|
232
232
|
/** Minimum confidence (0-1) for a quirk to be returned. */
|
|
233
233
|
minConfidence: number;
|
|
234
|
-
/** Minimum
|
|
234
|
+
/** Minimum raw vector similarity (0-1, cosine mapped to [0,1]) for a quirk to be recalled by manual `recall_quirks` calls. */
|
|
235
235
|
recallMinScore: number;
|
|
236
|
-
/** Minimum
|
|
237
|
-
* (both the system-prompt transform and the
|
|
238
|
-
* high bar: injected quirks occupy context on
|
|
239
|
-
*
|
|
240
|
-
*
|
|
236
|
+
/** Minimum raw vector similarity (0-1, cosine mapped to [0,1]) for quirks to
|
|
237
|
+
* be AUTO-injected into the prompt (both the system-prompt transform and the
|
|
238
|
+
* user message). Deliberately a high bar: injected quirks occupy context on
|
|
239
|
+
* every turn, so only strongly related ones should reach the prompt - e.g.
|
|
240
|
+
* 0.85 admits only strongly related notes. Manual `recall_quirks` calls use
|
|
241
|
+
* `recallMinScore` instead. */
|
|
241
242
|
autoInjectMinScore: number;
|
|
242
243
|
/** Maximum latency budget (ms) for auto-inject quirk recall. If exceeded, injection is skipped. */
|
|
243
244
|
autoInjectLatencyBudgetMs: number;
|
|
@@ -266,7 +267,7 @@ export interface MemoryConfig {
|
|
|
266
267
|
* so recurring errors can become quirks.
|
|
267
268
|
*/
|
|
268
269
|
injectOnToolError: boolean;
|
|
269
|
-
/** Minimum
|
|
270
|
+
/** Minimum raw vector similarity (0-1, cosine mapped to [0,1]) for a quirk to be injected after a tool error (default 0.7). */
|
|
270
271
|
toolErrorMinScore: number;
|
|
271
272
|
/** Max quirks injected per tool error (default 2). */
|
|
272
273
|
toolErrorTopK: number;
|
|
@@ -64,4 +64,4 @@ export declare function probeEmbeddingDimension(embedder: EmbeddingProvider): Pr
|
|
|
64
64
|
* @returns A promise resolving to a flat array of embedding vectors (one per input text);
|
|
65
65
|
* failed batches return empty arrays
|
|
66
66
|
*/
|
|
67
|
-
export declare function embedBatch(embedder: EmbeddingProvider, texts: string[], batchSize?: number, purpose?: "query" | "document", concurrency?: number, onProgress?: (completed: number, total: number) => void, retryMax?: number, retryBaseDelayMs?: number): Promise<number[][]>;
|
|
67
|
+
export declare function embedBatch(embedder: EmbeddingProvider, texts: string[], batchSize?: number, purpose?: "query" | "document", concurrency?: number, onProgress?: (completed: number, total: number) => void, retryMax?: number, retryBaseDelayMs?: number, maxConsecutiveFailures?: number): Promise<number[][]>;
|
package/dist/embedder/factory.js
CHANGED
|
@@ -94,6 +94,29 @@ const TIMEOUT_RE = /timed out|timeout/i;
|
|
|
94
94
|
function isTimeoutError(err) {
|
|
95
95
|
return TIMEOUT_RE.test(err instanceof Error ? err.message : String(err));
|
|
96
96
|
}
|
|
97
|
+
/**
|
|
98
|
+
* HTTP 502/503/504 — the request never got a usable answer from the model
|
|
99
|
+
* backend. A reverse proxy or model router (llama-swap, nginx, …) returns these
|
|
100
|
+
* when the backend is down, over capacity, or crashing on the input — most
|
|
101
|
+
* commonly an embedding server whose context window is smaller than the chunk
|
|
102
|
+
* we send (it accepts a short probe, so preflight passes, then 502s on every
|
|
103
|
+
* real chunk). Unlike a per-text context rejection, shrinking the batch cannot
|
|
104
|
+
* help: the server itself is the problem. So gateway errors are retried at the
|
|
105
|
+
* top level (a brief blip recovers) but never split — splitting only multiplies
|
|
106
|
+
* load on an unhealthy backend — and repeated ones trip the circuit breaker.
|
|
107
|
+
*/
|
|
108
|
+
const GATEWAY_STATUS_RE = /\(?(502|503|504)\)?/;
|
|
109
|
+
function isGatewayError(err) {
|
|
110
|
+
return GATEWAY_STATUS_RE.test(err instanceof Error ? err.message : String(err));
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* How many CONSECUTIVELY failed batches stop all further embedding requests in a
|
|
114
|
+
* single `embedBatch` call (the counter is reset by any batch that succeeds).
|
|
115
|
+
* Bounds the damage when the provider is down or undersized so a run fails fast
|
|
116
|
+
* and reports the provider as unavailable, instead of silently grinding through
|
|
117
|
+
* every batch for minutes — which reads as a hang. `0` disables the breaker.
|
|
118
|
+
*/
|
|
119
|
+
const DEFAULT_MAX_CONSECUTIVE_BATCH_FAILURES = 6;
|
|
97
120
|
/** Resolve the workspace debug log file used for batch failure diagnostics. */
|
|
98
121
|
function getBatchLogFilePath() {
|
|
99
122
|
return path.resolve(process.cwd(), ".opencode", "opencode-rag.log");
|
|
@@ -127,7 +150,7 @@ function getBatchLogFilePath() {
|
|
|
127
150
|
* @returns A promise resolving to a flat array of embedding vectors (one per input text);
|
|
128
151
|
* failed batches return empty arrays
|
|
129
152
|
*/
|
|
130
|
-
export async function embedBatch(embedder, texts, batchSize = 10, purpose, concurrency = 1, onProgress, retryMax = 3, retryBaseDelayMs = 1000) {
|
|
153
|
+
export async function embedBatch(embedder, texts, batchSize = 10, purpose, concurrency = 1, onProgress, retryMax = 3, retryBaseDelayMs = 1000, maxConsecutiveFailures = DEFAULT_MAX_CONSECUTIVE_BATCH_FAILURES) {
|
|
131
154
|
if (texts.length === 0)
|
|
132
155
|
return [];
|
|
133
156
|
const batches = [];
|
|
@@ -184,8 +207,16 @@ export async function embedBatch(embedder, texts, batchSize = 10, purpose, concu
|
|
|
184
207
|
// counted by the caller. A context-limit rejection carries a permanent 400
|
|
185
208
|
// status, so it needs its own predicate; timeouts are already non-permanent
|
|
186
209
|
// (belt and braces). Genuine permanent errors never split — halving the
|
|
187
|
-
// batch would fail the same way, only slower.
|
|
188
|
-
|
|
210
|
+
// batch would fail the same way, only slower. Neither do gateway errors
|
|
211
|
+
// (502/503/504): they come from the SERVER (down, overloaded, or a context
|
|
212
|
+
// smaller than our chunks), not a bad text, so a smaller batch fails
|
|
213
|
+
// identically. Top-level retry already handles a transient one; a persistent
|
|
214
|
+
// one is left to the circuit breaker below rather than split into an
|
|
215
|
+
// exponential retry tree that looks exactly like a hang.
|
|
216
|
+
const splittable = (!isPermanentError(lastError) ||
|
|
217
|
+
isContextLimitError(lastError) ||
|
|
218
|
+
isTimeoutError(lastError)) &&
|
|
219
|
+
!isGatewayError(lastError);
|
|
189
220
|
if (batchTexts.length > 1 && splittable) {
|
|
190
221
|
const mid = Math.ceil(batchTexts.length / 2);
|
|
191
222
|
appendDebugLog(getBatchLogFilePath(), {
|
|
@@ -203,10 +234,50 @@ export async function embedBatch(embedder, texts, batchSize = 10, purpose, concu
|
|
|
203
234
|
}
|
|
204
235
|
return null;
|
|
205
236
|
}
|
|
237
|
+
// ── Circuit breaker ────────────────────────────────────────────────────
|
|
238
|
+
// A down / overloaded / undersized embedding server fails EVERY batch. Without
|
|
239
|
+
// a break we keep firing batch after batch at it for the whole run — a silent,
|
|
240
|
+
// minutes-long grind indistinguishable from a hang. After this many
|
|
241
|
+
// CONSECUTIVELY failed batches (reset by any success) we stop calling the
|
|
242
|
+
// provider entirely and short-circuit the rest to empty vectors, so the pass
|
|
243
|
+
// fails fast and the pipeline reports the provider as unavailable.
|
|
244
|
+
let consecutiveFailedBatches = 0;
|
|
245
|
+
let circuitTripped = false;
|
|
246
|
+
function recordBatchResult(succeeded) {
|
|
247
|
+
if (succeeded) {
|
|
248
|
+
consecutiveFailedBatches = 0;
|
|
249
|
+
return;
|
|
250
|
+
}
|
|
251
|
+
consecutiveFailedBatches++;
|
|
252
|
+
if (!circuitTripped &&
|
|
253
|
+
maxConsecutiveFailures > 0 &&
|
|
254
|
+
consecutiveFailedBatches >= maxConsecutiveFailures) {
|
|
255
|
+
circuitTripped = true;
|
|
256
|
+
appendDebugLog(getBatchLogFilePath(), {
|
|
257
|
+
scope: "embedder.batch",
|
|
258
|
+
severity: "warn",
|
|
259
|
+
message: `Embedding circuit breaker tripped after ${consecutiveFailedBatches} consecutive failed ` +
|
|
260
|
+
"batches — the embedding server is unavailable, overloaded, or rejecting the input (an " +
|
|
261
|
+
"over-large / too-small context is the usual cause). Stopping further requests; un-embedded " +
|
|
262
|
+
"chunks are kept for the next pass. Fix the provider (e.g. raise its context window) and " +
|
|
263
|
+
"run the index again.",
|
|
264
|
+
});
|
|
265
|
+
}
|
|
266
|
+
}
|
|
206
267
|
if (concurrency <= 1 || batches.length <= 1) {
|
|
207
268
|
const results = [];
|
|
208
269
|
for (const batch of batches) {
|
|
270
|
+
if (circuitTripped) {
|
|
271
|
+
// Breaker open: emit empty vectors so caller index→vector alignment is
|
|
272
|
+
// preserved, advance progress, and never touch the provider again.
|
|
273
|
+
for (let i = 0; i < batch.texts.length; i++) {
|
|
274
|
+
results.push([]);
|
|
275
|
+
}
|
|
276
|
+
onProgress?.(results.length, texts.length);
|
|
277
|
+
continue;
|
|
278
|
+
}
|
|
209
279
|
const embeddings = await embedWithRetry(batch.texts);
|
|
280
|
+
recordBatchResult(embeddings !== null);
|
|
210
281
|
if (embeddings) {
|
|
211
282
|
results.push(...embeddings);
|
|
212
283
|
}
|
|
@@ -222,7 +293,13 @@ export async function embedBatch(embedder, texts, batchSize = 10, purpose, concu
|
|
|
222
293
|
let completedCount = 0;
|
|
223
294
|
const limit = pLimit(concurrency);
|
|
224
295
|
const batchResults = await Promise.all(batches.map((batch) => limit(async () => {
|
|
296
|
+
if (circuitTripped) {
|
|
297
|
+
completedCount += batch.texts.length;
|
|
298
|
+
onProgress?.(completedCount, texts.length);
|
|
299
|
+
return { index: batch.index, embeddings: batch.texts.map(() => []) };
|
|
300
|
+
}
|
|
225
301
|
const embeddings = await embedWithRetry(batch.texts);
|
|
302
|
+
recordBatchResult(embeddings !== null);
|
|
226
303
|
const flatResult = embeddings ?? batch.texts.map(() => []);
|
|
227
304
|
// Count processed TEXTS (not returned vectors) so failed batches
|
|
228
305
|
// still advance progress towards the total.
|
package/dist/plugin.js
CHANGED
|
@@ -900,7 +900,7 @@ export function createRagHooks(options) {
|
|
|
900
900
|
const budgetMs = memCfg.autoInjectLatencyBudgetMs ?? 2000;
|
|
901
901
|
let timer;
|
|
902
902
|
let quirkResults = await Promise.race([
|
|
903
|
-
recallQuirks(quirkDeps, query, { topK: memCfg.autoInjectTopK ?? 1, minScore: memCfg.autoInjectMinScore })
|
|
903
|
+
recallQuirks(quirkDeps, query, { topK: memCfg.autoInjectTopK ?? 1, minScore: memCfg.autoInjectMinScore ?? 0.75 })
|
|
904
904
|
.then((r) => {
|
|
905
905
|
if (timer)
|
|
906
906
|
clearTimeout(timer);
|
|
@@ -76,12 +76,22 @@ export interface QuirkReconcileResult {
|
|
|
76
76
|
* @returns Counts of what changed (all zero when already consistent).
|
|
77
77
|
*/
|
|
78
78
|
export declare function reconcileQuirks(deps: QuirkReconcileDeps): Promise<QuirkReconcileResult>;
|
|
79
|
-
/**
|
|
79
|
+
/**
|
|
80
|
+
* Recall quirks matching a query, gated on raw vector similarity and ranked by
|
|
81
|
+
* confidence-weighted similarity.
|
|
82
|
+
*
|
|
83
|
+
* The threshold is compared against the quirk's raw vector similarity
|
|
84
|
+
* (`(cosine + 1) / 2`, the stores' native 0-1 domain) — never against the
|
|
85
|
+
* hybrid rank-fusion score, whose top candidate of a small list always scores
|
|
86
|
+
* ~0.6+ regardless of relevance.
|
|
87
|
+
*/
|
|
80
88
|
export declare function recallQuirks(deps: QuirkStoreDeps, query: string, options?: {
|
|
81
89
|
topK?: number;
|
|
82
90
|
quirkType?: string;
|
|
83
91
|
tags?: string[];
|
|
84
|
-
/** Override recallMinScore from config.
|
|
92
|
+
/** Override recallMinScore from config. Semantic similarity threshold (0-1,
|
|
93
|
+
* cosine mapped to [0,1] the same way the vector stores report raw scores).
|
|
94
|
+
* Auto-inject passes its own (usually higher) bar. */
|
|
85
95
|
minScore?: number;
|
|
86
96
|
}): Promise<SearchResult[]>;
|
|
87
97
|
/** Lint quirks for low confidence, staleness, duplicates, and orphan source refs. */
|
|
@@ -489,7 +489,15 @@ export async function reconcileQuirks(deps) {
|
|
|
489
489
|
}
|
|
490
490
|
return result;
|
|
491
491
|
}
|
|
492
|
-
/**
|
|
492
|
+
/**
|
|
493
|
+
* Recall quirks matching a query, gated on raw vector similarity and ranked by
|
|
494
|
+
* confidence-weighted similarity.
|
|
495
|
+
*
|
|
496
|
+
* The threshold is compared against the quirk's raw vector similarity
|
|
497
|
+
* (`(cosine + 1) / 2`, the stores' native 0-1 domain) — never against the
|
|
498
|
+
* hybrid rank-fusion score, whose top candidate of a small list always scores
|
|
499
|
+
* ~0.6+ regardless of relevance.
|
|
500
|
+
*/
|
|
493
501
|
export async function recallQuirks(deps, query, options) {
|
|
494
502
|
const topK = options?.topK ?? 10;
|
|
495
503
|
const minConfidence = deps.cfg.memory?.minConfidence ?? 0.5;
|
|
@@ -499,20 +507,32 @@ export async function recallQuirks(deps, query, options) {
|
|
|
499
507
|
// Type filtering happens in the post-filter below instead.
|
|
500
508
|
const filter = { kinds: ["quirk"] };
|
|
501
509
|
const recallMinScore = options?.minScore ?? deps.cfg.memory?.recallMinScore ?? 0.72;
|
|
510
|
+
// Fetch with the hybrid `minScore` gate disabled: the relevance decision is
|
|
511
|
+
// taken below against the RAW VECTOR SIMILARITY, not the rank-fusion score.
|
|
512
|
+
// The fused score is rank-based — the top quirk of a small candidate list
|
|
513
|
+
// always scores ~0.6+ no matter how unrelated it is — so a high threshold on
|
|
514
|
+
// it never filtered non-relevant quirks. `explain: true` exposes
|
|
515
|
+
// `rawVectorScore` for every fused candidate.
|
|
502
516
|
const raw = await retrieve(query, deps.embedder, deps.store, {
|
|
503
517
|
topK: topK * 3,
|
|
504
|
-
minScore:
|
|
518
|
+
minScore: 0,
|
|
519
|
+
explain: true,
|
|
505
520
|
keywordIndex: deps.keywordIndex,
|
|
506
521
|
keywordWeight: deps.cfg.retrieval.hybridSearch?.keywordWeight,
|
|
507
522
|
hybridEnabled: true,
|
|
508
523
|
queryPrefix: deps.cfg.embedding.queryPrefix,
|
|
509
524
|
filter,
|
|
510
525
|
});
|
|
511
|
-
// Confidence
|
|
526
|
+
// Confidence + semantic-similarity + type/tag filtering. The similarity gate
|
|
527
|
+
// is `(cosine + 1) / 2` in [0,1] — the same domain the vector stores report.
|
|
528
|
+
// A keyword-only candidate has rawVectorScore 0 and never passes minScore > 0.
|
|
512
529
|
const filtered = raw.filter((r) => {
|
|
513
530
|
const conf = r.chunk.metadata.confidence ?? 1;
|
|
514
531
|
if (conf < minConfidence)
|
|
515
532
|
return false;
|
|
533
|
+
const similarity = r.explanation?.scoreBreakdown?.rawVectorScore ?? 0;
|
|
534
|
+
if (similarity < recallMinScore)
|
|
535
|
+
return false;
|
|
516
536
|
if (options?.quirkType && r.chunk.metadata.quirkType !== options.quirkType)
|
|
517
537
|
return false;
|
|
518
538
|
if (options?.tags?.length) {
|
|
@@ -522,10 +542,14 @@ export async function recallQuirks(deps, query, options) {
|
|
|
522
542
|
}
|
|
523
543
|
return true;
|
|
524
544
|
});
|
|
525
|
-
//
|
|
545
|
+
// Rank by semantic similarity (confidence-weighted) and report that same
|
|
546
|
+
// signal as `score`, so top-K selection is relevance-ordered and callers
|
|
547
|
+
// display a meaningful number instead of the rank-fusion artifact.
|
|
526
548
|
for (const r of filtered) {
|
|
527
549
|
const conf = r.chunk.metadata.confidence ?? 1;
|
|
528
|
-
|
|
550
|
+
const similarity = r.explanation?.scoreBreakdown?.rawVectorScore ?? 0;
|
|
551
|
+
r.score = similarity * Math.min(1, Math.max(0.01, conf));
|
|
552
|
+
delete r.explanation;
|
|
529
553
|
}
|
|
530
554
|
filtered.sort((a, b) => b.score - a.score);
|
|
531
555
|
return filtered.slice(0, topK);
|