opencode-rag-plugin 2.4.2 → 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 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 — 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. Injection uses two thresholds: the stricter `recallMinScore` (0.72) for the user message context, and the more permissive `autoInjectMinScore` (0.45) for the system prompt. This lets the agent avoid repeating mistakes and accumulate project knowledge across sessions without manual recall.
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.8,
210
- "autoInjectMinScore": 0.6,
211
- "autoInjectTopK": 2,
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 relevance score exceeds the threshold — `recallMinScore` (default 0.72) for the user message, `autoInjectMinScore` (default 0.45) for the system prompt. 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).
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
 
@@ -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 query-relevance score (0-1) for a quirk to be recalled. */
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 relevance score for quirks to be AUTO-injected into the prompt
237
- * (both the system-prompt transform and the user message). Deliberately a
238
- * high bar: injected quirks occupy context on every turn, so only strongly
239
- * relevant ones should reach the prompt. Manual `recall_quirks` calls use
240
- * the lower `recallMinScore`. */
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 relevance score (0-1) for a quirk to be injected after a tool error (default 0.7). */
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;
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
- /** Recall quirks matching a query, with confidence re-weighting. */
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. Used by auto-inject for a lower threshold. */
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
- /** Recall quirks matching a query, with confidence re-weighting. */
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: recallMinScore,
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 re-weighting + type/tag filtering
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
- // Re-weight score by confidence, re-sort
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
- r.score = r.score * Math.min(1, Math.max(0.01, conf));
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);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-rag-plugin",
3
- "version": "2.4.2",
3
+ "version": "2.4.3",
4
4
  "description": "OpenCode plugin for local-first RAG-based semantic code search",
5
5
  "type": "module",
6
6
  "main": "./dist/plugin-entry.js",