wyrm-mcp 7.3.2 → 7.3.3

package/dist/memory-artifacts.js

@@ -1,9 +1,68 @@
-import{emitEvent as b}from"./events.js";import{sanitizeFtsQuery as L,buildFtsMatchQuery as k}from"./security.js";import{getActor as I}from"./handlers/boundary.js";import{buildPage as T,DEFAULT_PAGE_SIZE as O}from"./keyset.js";import{rerankConfigured as F,rerankCandidates as $}from"./rerank.js";const w=40,H=10,x=.3;class j{db;vectorStore;setVectorStore(t){this.vectorStore=t}constructor(t){this.db=t}indexArtifact(t){if(!this.vectorStore)return;const e=`${t.problem}${t.validated_fix?" "+t.validated_fix:""}`.slice(0,2e3);this.vectorStore.addVector(e,"artifact",t.id,t.project_id).catch(()=>{})}add(t,e){const n=e.tags?.length?e.tags.join(","):null,s=I(),a=this.db.prepare(`
+/**
+ * Wyrm Memory Artifacts — Distilled knowledge for AI intelligence amplification.
+ *
+ * Stores problem-solution records, lessons, patterns, and anti-patterns that
+ * help AI models recall what worked in the past and apply it to new tasks.
+ *
+ * @copyright 2026 Ghost Protocol (Pvt) Ltd.
+ * @license Proprietary — (c) 2026 Ghost Protocol (Pvt) Ltd. All rights reserved. See LICENSE.
+ */
+import { emitEvent } from './events.js';
+import { sanitizeFtsQuery, buildFtsMatchQuery } from './security.js';
+import { getActor } from './handlers/boundary.js';
+import { buildPage, DEFAULT_PAGE_SIZE } from './keyset.js';
+import { rerankConfigured, rerankCandidates } from './rerank.js';
+/** Maximum artifacts returned from a recall query (before reranking) */
+const MAX_CANDIDATES = 40;
+/** Maximum artifacts included in a context brief */
+const MAX_BRIEF_ITEMS = 10;
+/** Minimum confidence to include in auto-generated briefs */
+const MIN_BRIEF_CONFIDENCE = 0.3;
+export class MemoryArtifacts {
+    db;
+    /** Optional dense-vector index — when set, `recallHybrid` fuses FTS + vectors (RRF). */
+    vectorStore;
+    setVectorStore(vs) { this.vectorStore = vs; }
+    constructor(db) {
+        this.db = db;
+    }
+    /** Best-effort dense-vector index of an ACTIVE artifact. Fire-and-forget: embedding
+     * is async + may be unavailable (Ollama down) — it must never block or break add(). */
+    indexArtifact(a) {
+        if (!this.vectorStore)
+            return;
+        const text = `${a.problem}${a.validated_fix ? ' ' + a.validated_fix : ''}`.slice(0, 2000);
+        void this.vectorStore.addVector(text, 'artifact', a.id, a.project_id).catch(() => { });
+    }
+    // ==================== CRUD ====================
+    add(projectId, opts) {
+        const tags = opts.tags?.length ? opts.tags.join(',') : null;
+        // v7 F2 (T009): stamp the writing actor (NULL outside a fleet context).
+        // `created_by` keeps its 6.x display semantics untouched.
+        const ambient = getActor();
+        const result = this.db.prepare(`
       INSERT INTO memory_artifacts
         (project_id, kind, problem, constraints, validated_fix, why_it_worked,
          outcome, source_session_id, tags, confidence, needs_review, created_by, agent_id, run_id)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(t,e.kind,e.problem.trim(),e.constraints?.trim()??null,e.validatedFix?.trim()??null,e.whyItWorked?.trim()??null,e.outcome??"neutral",e.sourceSessionId??null,n,e.confidence??1,e.needsReview??0,e.createdBy??"local",s.agent_id,s.run_id),i=this.get(a.lastInsertRowid);return e.needsReview||(b(this.db,{projectId:t,kind:"capture",refTable:"memory_artifacts",refId:i.id,isShared:!!i.is_shared}),this.indexArtifact(i)),i}get(t){return this.db.prepare("SELECT * FROM memory_artifacts WHERE id = ?").get(t)??null}update(t,e){return this.db.prepare(`
+    `).run(projectId, opts.kind, opts.problem.trim(), opts.constraints?.trim() ?? null, opts.validatedFix?.trim() ?? null, opts.whyItWorked?.trim() ?? null, opts.outcome ?? 'neutral', opts.sourceSessionId ?? null, tags, opts.confidence ?? 1.0, opts.needsReview ?? 0, opts.createdBy ?? 'local', ambient.agent_id, ambient.run_id);
+        const artifact = this.get(result.lastInsertRowid);
+        // Live Memory: emit ONLY for active memories. Review-queue candidates
+        // (harvest dumps 1000s with needsReview=1) must not flood the event log.
+        if (!opts.needsReview) {
+            emitEvent(this.db, {
+                projectId, kind: 'capture', refTable: 'memory_artifacts', refId: artifact.id,
+                isShared: !!artifact.is_shared,
+            });
+            this.indexArtifact(artifact); // best-effort dense index for hybrid recall
+        }
+        return artifact;
+    }
+    get(id) {
+        return this.db.prepare('SELECT * FROM memory_artifacts WHERE id = ?').get(id) ?? null;
+    }
+    update(id, updates) {
+        this.db.prepare(`
       UPDATE memory_artifacts SET
         confidence = COALESCE(?, confidence),
         validated_fix = COALESCE(?, validated_fix),
@@ -12,27 +71,336 @@ import{emitEvent as b}from"./events.js";import{sanitizeFtsQuery as L,buildFtsMat
         needs_review = COALESCE(?, needs_review),
         updated_at = datetime('now')
       WHERE id = ?
-    `).run(e.confidence??null,e.validated_fix??null,e.why_it_worked??null,e.last_validated_at??null,e.needs_review??null,t),this.get(t)}markSuperseded(t,e){this.db.prepare("UPDATE memory_artifacts SET supersedes_id = ?, updated_at = datetime('now') WHERE id = ?").run(e,t)}recordFeedback(t,e){const n=e?"reuse_success_count":"reuse_failure_count";this.db.prepare(`
+    `).run(updates.confidence ?? null, updates.validated_fix ?? null, updates.why_it_worked ?? null, updates.last_validated_at ?? null, updates.needs_review ?? null, id);
+        return this.get(id);
+    }
+    /** Mark an artifact as superseded by a newer/better one. */
+    markSuperseded(oldId, newId) {
+        this.db.prepare('UPDATE memory_artifacts SET supersedes_id = ?, updated_at = datetime(\'now\') WHERE id = ?').run(newId, oldId);
+    }
+    /** Record that an artifact was used and whether it helped. */
+    recordFeedback(id, success) {
+        const col = success ? 'reuse_success_count' : 'reuse_failure_count';
+        this.db.prepare(`
       UPDATE memory_artifacts SET
         reuse_count = reuse_count + 1,
-        ${n} = ${n} + 1,
+        ${col} = ${col} + 1,
         confidence = CASE
           WHEN ? THEN MIN(1.0, confidence + 0.05)
           ELSE MAX(0.0, confidence - 0.1)
         END,
         updated_at = datetime('now')
       WHERE id = ?
-    `).run(e?1:0,t)}recall(t,e,n={}){const s=n.limit??10,a=n.minConfidence??0,i=this.searchByFts(t,e,w,n.kind,a),l=this.searchByTags(t,e,w,n.kind,a),r=new Set,m=[];i.forEach((o,d)=>{r.add(o.id),m.push({artifact:o,inFts:!0,inTag:!1,ftsRank:d})});for(const o of l)if(!r.has(o.id))r.add(o.id),m.push({artifact:o,inFts:!1,inTag:!0});else{const d=m.find(N=>N.artifact.id===o.id);d&&(d.inTag=!0)}return m.filter(({artifact:o})=>o.confidence>=a).map(({artifact:o,inFts:d,inTag:N,ftsRank:S})=>{let f;if(d){const g=1-(S??0)/(i.length+1);f=(N?.7:.55)+.45*g}else f=.4;f*=o.confidence,o.outcome==="positive"&&(f*=1.1);const A=(Date.now()-new Date(o.last_validated_at).getTime())/(1e3*60*60*24),C=Math.max(.5,1-A/180);return f*=C,{artifact:o,relevance_score:Math.min(1,f),match_type:d&&N?"both":d?"fts":"tag"}}).sort((o,d)=>d.relevance_score-o.relevance_score).slice(0,s)}async recallHybrid(t,e,n={}){const s=n.limit??10,a=n.minConfidence??0,i=n.rerank===!0&&F(),l=Math.min(Math.max(s*2,20),50),r=i?l:s;if(!this.vectorStore)return this.recall(t,e,n);const m=Math.max(50,r*5),_=this.searchByFts(t,e,m,n.kind,a);let o=[];try{o=(await this.vectorStore.search(e,m,t,["artifact"])).map(p=>({id:p.content_id,s:p.similarity}))}catch{}if(o.length===0)return this.recall(t,e,n);const d=60,N=Number(process.env.WYRM_RERANK_ALPHA),S=Number.isFinite(N)?Math.max(0,Math.min(1,N)):.7,f=new Map;if(process.env.WYRM_RERANK_FUSION==="rrf")_.forEach((u,p)=>f.set(u.id,(f.get(u.id)??0)+1/(d+p+1))),o.forEach((u,p)=>f.set(u.id,(f.get(u.id)??0)+1/(d+p+1)));else{const u=_.length+1;_.forEach((y,M)=>f.set(y.id,(f.get(y.id)??0)+(1-S)*(1-M/u)));const p=o.map(y=>y.s),E=Math.min(...p),v=Math.max(...p),D=v-E;o.forEach(y=>f.set(y.id,(f.get(y.id)??0)+S*(D>1e-9?(y.s-E)/D:1)))}const A=new Set(_.map(u=>u.id)),C=new Set(o.map(u=>u.id)),g=new Map(_.map(u=>[u.id,u])),c=[...f.entries()].sort((u,p)=>p[1]-u[1]),h=c[0]?.[1]??1,R=[];for(const[u,p]of c){if(R.length>=r)break;const E=g.get(u)??this.get(u)??void 0;if(!E||E.confidence<a||E.needs_review===1||E.supersedes_id!=null||n.kind&&E.kind!==n.kind)continue;const v=A.has(u)&&C.has(u)?"hybrid":C.has(u)?"vector":"fts";R.push({artifact:E,relevance_score:Math.min(1,p/h),match_type:v})}return i&&R.length>0?(await this.rerankResults(e,R)).slice(0,s):R}async rerankResults(t,e){const n=e.map(r=>({id:r.artifact.id,text:`${r.artifact.problem}${r.artifact.validated_fix?" "+r.artifact.validated_fix:""}`.slice(0,2e3)})),s=await $(t,n);if(!s)return e;const a=new Map(e.map(r=>[r.artifact.id,r])),i=[],l=s.length;return s.forEach((r,m)=>{const _=a.get(r.id);_&&i.push({..._,relevance_score:l>0?(l-m)/l:_.relevance_score})}),i}async recallHybridGlobal(t,e={}){const n=e.limit??10,s=e.minConfidence??0,a=Math.max(50,n*5),i=this.searchByFtsGlobal(t,a,e.kind,s),l=()=>i.slice(0,n).map((c,h)=>({artifact:c,relevance_score:1-h/(i.length+1),match_type:"fts"}));if(!this.vectorStore)return l();let r=[];try{r=(await this.vectorStore.search(t,a,void 0,["artifact"])).map(h=>({id:h.content_id,s:h.similarity}))}catch{}if(r.length===0)return l();const m=60,_=Number(process.env.WYRM_RERANK_ALPHA),o=Number.isFinite(_)?Math.max(0,Math.min(1,_)):.7,d=new Map;if(process.env.WYRM_RERANK_FUSION==="rrf")i.forEach((c,h)=>d.set(c.id,(d.get(c.id)??0)+1/(m+h+1))),r.forEach((c,h)=>d.set(c.id,(d.get(c.id)??0)+1/(m+h+1)));else{const c=i.length+1;i.forEach((E,v)=>d.set(E.id,(d.get(E.id)??0)+(1-o)*(1-v/c)));const h=r.map(E=>E.s),R=Math.min(...h),u=Math.max(...h),p=u-R;r.forEach(E=>d.set(E.id,(d.get(E.id)??0)+o*(p>1e-9?(E.s-R)/p:1)))}const N=new Set(i.map(c=>c.id)),S=new Set(r.map(c=>c.id)),f=new Map(i.map(c=>[c.id,c])),A=[...d.entries()].sort((c,h)=>h[1]-c[1]),C=A[0]?.[1]??1,g=[];for(const[c,h]of A){if(g.length>=n)break;const R=f.get(c)??this.get(c)??void 0;if(!R||R.confidence<s||R.needs_review===1||R.supersedes_id!=null||e.kind&&R.kind!==e.kind)continue;const u=N.has(c)&&S.has(c)?"hybrid":S.has(c)?"vector":"fts";g.push({artifact:R,relevance_score:Math.min(1,h/C),match_type:u})}return g}searchByFtsGlobal(t,e,n,s=0){if(!this.db)return[];let a="";try{const r=L(t);a=r?k(r):""}catch{return[]}if(!a)return[];const i=n?"AND a.kind = ?":"",l=[a,s];n&&l.push(n),l.push(e);try{return this.db.prepare(`
+    `).run(success ? 1 : 0, id);
+    }
+    // ==================== RETRIEVAL ====================
+    /**
+     * 2-stage retrieval: FTS candidates → sort by weighted relevance.
+     * Excludes superseded artifacts and those below minConfidence.
+     */
+    recall(projectId, query, opts = {}) {
+        const limit = opts.limit ?? 10;
+        const minConf = opts.minConfidence ?? 0.0;
+        // Stage 1: FTS candidates
+        const ftsCandidates = this.searchByFts(projectId, query, MAX_CANDIDATES, opts.kind, minConf);
+        // Stage 2: Tag candidates (exact tag matches not covered by FTS)
+        const tagCandidates = this.searchByTags(projectId, query, MAX_CANDIDATES, opts.kind, minConf);
+        // Merge and dedupe by id
+        const seen = new Set();
+        const merged = [];
+        // ftsCandidates arrive in bm25 order (best first) — keep the rank so the score
+        // below preserves it instead of flattening every FTS hit to one value.
+        ftsCandidates.forEach((a, i) => {
+            seen.add(a.id);
+            merged.push({ artifact: a, inFts: true, inTag: false, ftsRank: i });
+        });
+        for (const a of tagCandidates) {
+            if (!seen.has(a.id)) {
+                seen.add(a.id);
+                merged.push({ artifact: a, inFts: false, inTag: true });
+            }
+            else {
+                const existing = merged.find(m => m.artifact.id === a.id);
+                if (existing)
+                    existing.inTag = true;
+            }
+        }
+        // Score and rerank — also enforce minConf as a safety net
+        const results = merged
+            .filter(({ artifact }) => artifact.confidence >= minConf)
+            .map(({ artifact, inFts, inTag, ftsRank }) => {
+            // bm25 rank is the PRIMARY signal: earlier FTS candidates (lower rank) score
+            // higher, so the query's relevance ordering survives the merge/re-sort.
+            let relevance;
+            if (inFts) {
+                const rankScore = 1 - (ftsRank ?? 0) / (ftsCandidates.length + 1); // ~1.0 best → ~0 worst
+                relevance = (inTag ? 0.7 : 0.55) + 0.45 * rankScore; // 0.55..1.0 for FTS hits
+            }
+            else {
+                relevance = 0.4; // tag-only match
+            }
+            // Boost by confidence
+            relevance *= artifact.confidence;
+            // Boost positive outcomes slightly
+            if (artifact.outcome === 'positive')
+                relevance *= 1.1;
+            // Freshness: decay slowly over 180 days
+            const daysSinceValidated = (Date.now() - new Date(artifact.last_validated_at).getTime()) / (1000 * 60 * 60 * 24);
+            const freshnessScore = Math.max(0.5, 1.0 - daysSinceValidated / 180);
+            relevance *= freshnessScore;
+            return {
+                artifact,
+                relevance_score: Math.min(1.0, relevance),
+                match_type: (inFts && inTag ? 'both' : inFts ? 'fts' : 'tag'),
+            };
+        });
+        return results.sort((a, b) => b.relevance_score - a.relevance_score).slice(0, limit);
+    }
+    /**
+     * Hybrid recall: FTS (bm25) ⊕ dense vectors (cosine), fused by convex score-blend
+     * (default, α=0.7) or RRF (WYRM_RERANK_FUSION=rrf). Gracefully degrades to lexical
+     * `recall()` when no vector store is wired or the embedding provider is unavailable.
+     * Async (embedding the query is async). Measured on real LoCoMo (nomic-embed-text,
+     * local): FTS recall@10 59.9% → hybrid+RRF 72.2% → hybrid+convex recall@5 62.1% / @10 72.7%.
+     */
+    async recallHybrid(projectId, query, opts = {}) {
+        const limit = opts.limit ?? 10;
+        const minConf = opts.minConfidence ?? 0.0;
+        // Rerank stage (subsystem wyrm-routing-rerank): opt-in AND model-configured.
+        // When active, fuse a DEEPER top-K so the cross-encoder has real candidates
+        // to reorder, then keep the top-N (limit) after reranking. DEFAULT false +
+        // no model ⇒ identical to the historic fusion-only path (no behavior drift).
+        const doRerank = opts.rerank === true && rerankConfigured();
+        // Feed the cross-encoder a genuinely DEEPER candidate set than `limit`: 2× depth
+        // at every limit, floor 20 for small limits, hard cap 50 for latency. (A plain
+        // max(limit, min(20, limit*4)) collapsed to `limit` for limit>=20, giving the
+        // reranker nothing extra to reorder.)
+        const RERANK_K = Math.min(Math.max(limit * 2, 20), 50); // top-K fed to the cross-encoder
+        const fuseLimit = doRerank ? RERANK_K : limit;
+        if (!this.vectorStore)
+            return this.recall(projectId, query, opts); // no vectors → lexical
+        // Candidate depth 50 (LoCoMo-grid-tuned): convex fusion tolerates depth where
+        // RRF dilutes — raising RRF's depth actually regressed recall@10 in the sweep.
+        const CAND = Math.max(50, fuseLimit * 5);
+        const ftsCands = this.searchByFts(projectId, query, CAND, opts.kind, minConf);
+        let vecScored = [];
+        try {
+            const hits = await this.vectorStore.search(query, CAND, projectId, ['artifact']);
+            vecScored = hits.map((h) => ({ id: h.content_id, s: h.similarity })); // keep cosine for convex fusion
+        }
+        catch { /* provider down → fall through to FTS-only */ }
+        if (vecScored.length === 0)
+            return this.recall(projectId, query, opts); // nothing indexed yet
+        // Fusion. DEFAULT = convex score-blend: α·(min-max-normalized cosine) +
+        // (1-α)·(rank-normalized FTS). Won the LoCoMo grid (recall@5 60.3%→62.1%,
+        // recall@10 →72.7% at α=0.7, cand=50) vs RRF. WYRM_RERANK_FUSION=rrf falls back.
+        const RRF_K = 60;
+        const rawAlpha = Number(process.env.WYRM_RERANK_ALPHA); // dense-vector weight
+        const ALPHA = Number.isFinite(rawAlpha) ? Math.max(0, Math.min(1, rawAlpha)) : 0.7; // NaN / out-of-range / "0.7x" → 0.7
+        const score = new Map();
+        if (process.env.WYRM_RERANK_FUSION === 'rrf') {
+            ftsCands.forEach((a, r) => score.set(a.id, (score.get(a.id) ?? 0) + 1 / (RRF_K + r + 1)));
+            vecScored.forEach((x, r) => score.set(x.id, (score.get(x.id) ?? 0) + 1 / (RRF_K + r + 1)));
+        }
+        else {
+            const fn = ftsCands.length + 1; // FTS has no bm25 score exposed here → rank-normalize
+            ftsCands.forEach((a, r) => score.set(a.id, (score.get(a.id) ?? 0) + (1 - ALPHA) * (1 - r / fn)));
+            const ss = vecScored.map((x) => x.s), lo = Math.min(...ss), hi = Math.max(...ss), span = hi - lo;
+            vecScored.forEach((x) => score.set(x.id, (score.get(x.id) ?? 0) + ALPHA * (span > 1e-9 ? (x.s - lo) / span : 1)));
+        }
+        const ftsIds = new Set(ftsCands.map((a) => a.id));
+        const vecIds = new Set(vecScored.map((x) => x.id));
+        const byId = new Map(ftsCands.map((a) => [a.id, a]));
+        const ranked = [...score.entries()].sort((a, b) => b[1] - a[1]);
+        const top = ranked[0]?.[1] ?? 1;
+        const out = [];
+        for (const [id, s] of ranked) {
+            // Build up to fuseLimit candidates: == limit on the fusion-only path
+            // (unchanged), == the deeper top-K when the rerank stage will reorder.
+            if (out.length >= fuseLimit)
+                break;
+            const art = byId.get(id) ?? this.get(id) ?? undefined;
+            if (!art)
+                continue;
+            // Vector-only hits bypass the FTS WHERE-clause, so enforce the same filters here.
+            if (art.confidence < minConf || art.needs_review === 1 || art.supersedes_id != null)
+                continue;
+            if (opts.kind && art.kind !== opts.kind)
+                continue;
+            const match_type = ftsIds.has(id) && vecIds.has(id) ? 'hybrid' : vecIds.has(id) ? 'vector' : 'fts';
+            out.push({ artifact: art, relevance_score: Math.min(1, s / top), match_type });
+        }
+        // Optional cross-encoder rerank → top-N. Graceful: rerankCandidates returns
+        // null on any reranker error (model unset/endpoint down/timeout/malformed),
+        // in which case the fusion order is kept verbatim. Never throws, never hangs.
+        if (doRerank && out.length > 0) {
+            const reordered = await this.rerankResults(query, out);
+            return reordered.slice(0, limit);
+        }
+        return out;
+    }
+    /**
+     * Apply the optional cross-encoder rerank stage to a fused result set.
+     * Re-scores each artifact against the query with bge-reranker-v2-m3 (via
+     * rerank.ts) and returns the results best-first. Falls back to the input
+     * order (unchanged) on ANY reranker failure — the rerank.ts resilience
+     * contract: this is strictly no-worse-than-fusion and never throws/hangs.
+     * The returned `relevance_score`s are renormalized to [0,1] best-first so
+     * downstream consumers keep their monotone ordering semantics.
+     */
+    async rerankResults(query, fused) {
+        const candidates = fused.map((r) => ({
+            id: r.artifact.id,
+            // Match the bi-encoder index text (indexArtifact): problem [+ fix].
+            text: `${r.artifact.problem}${r.artifact.validated_fix ? ' ' + r.artifact.validated_fix : ''}`.slice(0, 2000),
+        }));
+        const reranked = await rerankCandidates(query, candidates);
+        if (!reranked)
+            return fused; // reranker unavailable/errored → fusion order
+        const byId = new Map(fused.map((r) => [r.artifact.id, r]));
+        const out = [];
+        const n = reranked.length;
+        reranked.forEach((c, i) => {
+            const r = byId.get(c.id);
+            if (!r)
+                return;
+            // Renormalize to a strictly-descending [0,1] score so the rerank order
+            // is reflected in relevance_score (the raw cross-encoder scores are
+            // unbounded/logit-scale and not comparable to the fusion scale).
+            out.push({ ...r, relevance_score: n > 0 ? (n - i) / n : r.relevance_score });
+        });
+        return out;
+    }
+    /**
+     * GLOBAL hybrid recall — the same convex FTS⊕vector fusion as {@link recallHybrid}
+     * but across EVERY project (no project scope), for cross-fleet surfaces that must
+     * "think with all of Wyrm" (e.g. the phone launcher's Ember grounding). The lexical
+     * leg uses the OR-joined {@link buildFtsMatchQuery} so a natural-language question
+     * returns relevant rows instead of the empty set an AND-joined MATCH produces.
+     * Degrades to global lexical recall when no vector store is wired or the provider
+     * is unavailable. Async (embedding the query is async).
+     */
+    async recallHybridGlobal(query, opts = {}) {
+        const limit = opts.limit ?? 10;
+        const minConf = opts.minConfidence ?? 0.0;
+        const CAND = Math.max(50, limit * 5);
+        const ftsCands = this.searchByFtsGlobal(query, CAND, opts.kind, minConf);
+        const lexicalOnly = () => ftsCands.slice(0, limit).map((art, i) => ({
+            artifact: art,
+            relevance_score: 1 - i / (ftsCands.length + 1),
+            match_type: 'fts',
+        }));
+        if (!this.vectorStore)
+            return lexicalOnly();
+        let vecScored = [];
+        try {
+            const hits = await this.vectorStore.search(query, CAND, undefined, ['artifact']); // projectId omitted → global
+            vecScored = hits.map((h) => ({ id: h.content_id, s: h.similarity }));
+        }
+        catch { /* provider down → FTS-only */ }
+        if (vecScored.length === 0)
+            return lexicalOnly();
+        // Convex score-blend — identical fusion/α to recallHybrid, just project-agnostic.
+        const RRF_K = 60;
+        const rawAlpha = Number(process.env.WYRM_RERANK_ALPHA);
+        const ALPHA = Number.isFinite(rawAlpha) ? Math.max(0, Math.min(1, rawAlpha)) : 0.7;
+        const score = new Map();
+        if (process.env.WYRM_RERANK_FUSION === 'rrf') {
+            ftsCands.forEach((a, r) => score.set(a.id, (score.get(a.id) ?? 0) + 1 / (RRF_K + r + 1)));
+            vecScored.forEach((x, r) => score.set(x.id, (score.get(x.id) ?? 0) + 1 / (RRF_K + r + 1)));
+        }
+        else {
+            const fn = ftsCands.length + 1;
+            ftsCands.forEach((a, r) => score.set(a.id, (score.get(a.id) ?? 0) + (1 - ALPHA) * (1 - r / fn)));
+            const ss = vecScored.map((x) => x.s), lo = Math.min(...ss), hi = Math.max(...ss), span = hi - lo;
+            vecScored.forEach((x) => score.set(x.id, (score.get(x.id) ?? 0) + ALPHA * (span > 1e-9 ? (x.s - lo) / span : 1)));
+        }
+        const ftsIds = new Set(ftsCands.map((a) => a.id));
+        const vecIds = new Set(vecScored.map((x) => x.id));
+        const byId = new Map(ftsCands.map((a) => [a.id, a]));
+        const ranked = [...score.entries()].sort((a, b) => b[1] - a[1]);
+        const top = ranked[0]?.[1] ?? 1;
+        const out = [];
+        for (const [id, s] of ranked) {
+            if (out.length >= limit)
+                break;
+            const art = byId.get(id) ?? this.get(id) ?? undefined;
+            if (!art)
+                continue;
+            if (art.confidence < minConf || art.needs_review === 1 || art.supersedes_id != null)
+                continue;
+            if (opts.kind && art.kind !== opts.kind)
+                continue;
+            const match_type = ftsIds.has(id) && vecIds.has(id) ? 'hybrid' : vecIds.has(id) ? 'vector' : 'fts';
+            out.push({ artifact: art, relevance_score: Math.min(1, s / top), match_type });
+        }
+        return out;
+    }
+    /** Global (cross-project) lexical FTS candidate fetch — like {@link searchByFts}
+     *  without the `project_id` filter. OR-joins terms so conversational queries match. */
+    searchByFtsGlobal(query, limit, kind, minConf = 0.0) {
+        if (!this.db)
+            return [];
+        let match = '';
+        try {
+            const sanitized = sanitizeFtsQuery(query);
+            match = sanitized ? buildFtsMatchQuery(sanitized) : '';
+        }
+        catch {
+            return [];
+        }
+        if (!match)
+            return [];
+        const kindClause = kind ? 'AND a.kind = ?' : '';
+        const params = [match, minConf];
+        if (kind)
+            params.push(kind);
+        params.push(limit);
+        try {
+            return this.db.prepare(`
         SELECT a.* FROM memory_artifacts a
         JOIN memory_artifacts_fts ON a.id = memory_artifacts_fts.rowid
         WHERE memory_artifacts_fts MATCH ?
           AND a.confidence >= ?
           AND a.supersedes_id IS NULL
           AND a.needs_review = 0
-          ${i}
+          ${kindClause}
         ORDER BY rank, a.confidence DESC
         LIMIT ?
-      `).all(...l)}catch{return[]}}searchByFts(t,e,n,s,a=0){let i="";try{const m=L(e);i=m?k(m):""}catch{return this.listRecent(t,n,s)}if(!i)return this.listRecent(t,n,s);const l=s?"AND a.kind = ?":"",r=[i,t,a];s&&r.push(s),r.push(n);try{return this.db.prepare(`
+      `).all(...params);
+        }
+        catch {
+            return [];
+        }
+    }
+    searchByFts(projectId, query, limit, kind, minConf = 0.0) {
+        // Build a SAFE FTS5 MATCH query (OR-joined quoted terms). The old code passed
+        // the raw natural-language query — punctuation like "?" made FTS5 throw, so EVERY
+        // recall silently fell back to listRecent() (recency, not relevance). Use the same
+        // helpers the rest of the search surface uses; ORDER BY rank gives bm25 ranking.
+        // sanitizeFtsQuery THROWS on an empty-after-sanitization query (e.g. an
+        // operator-/punctuation-only input). That must degrade to recency, never
+        // throw out of recall()/context_build() — guard it.
+        let match = '';
+        try {
+            const sanitized = sanitizeFtsQuery(query);
+            match = sanitized ? buildFtsMatchQuery(sanitized) : '';
+        }
+        catch {
+            return this.listRecent(projectId, limit, kind);
+        }
+        if (!match)
+            return this.listRecent(projectId, limit, kind);
+        const kindClause = kind ? 'AND a.kind = ?' : '';
+        const params = [match, projectId, minConf];
+        if (kind)
+            params.push(kind);
+        params.push(limit);
+        try {
+            // NB: reference the FTS table by its FULL NAME in MATCH, not an alias —
+            // `<alias> MATCH ?` throws "no such column" in SQLite FTS5, which is what sent
+            // every recall into the listRecent() fallback (recency instead of relevance).
+            return this.db.prepare(`
         SELECT a.* FROM memory_artifacts a
         JOIN memory_artifacts_fts ON a.id = memory_artifacts_fts.rowid
         WHERE memory_artifacts_fts MATCH ?
@@ -40,53 +408,249 @@ import{emitEvent as b}from"./events.js";import{sanitizeFtsQuery as L,buildFtsMat
           AND a.confidence >= ?
           AND a.supersedes_id IS NULL
           AND a.needs_review = 0
-          ${l}
+          ${kindClause}
         ORDER BY rank, a.confidence DESC
         LIMIT ?
-      `).all(...r)}catch{return this.listRecent(t,n,s)}}searchByTags(t,e,n,s,a=0){const i=e.toLowerCase().split(/\s+/).filter(d=>d.length>2);if(!i.length)return[];const l=d=>d.replace(/[%_\\]/g,"\\$&"),r=i.map(()=>"LOWER(tags) LIKE ? ESCAPE '\\'").join(" OR "),m=i.map(d=>`%${l(d)}%`),_=s?"AND kind = ?":"",o=[t,a,...m];return s&&o.push(s),o.push(n),this.db.prepare(`
+      `).all(...params);
+        }
+        catch {
+            return this.listRecent(projectId, limit, kind);
+        }
+    }
+    searchByTags(projectId, query, limit, kind, minConf = 0.0) {
+        // Match any word in the query against tags
+        const words = query.toLowerCase().split(/\s+/).filter(w => w.length > 2);
+        if (!words.length)
+            return [];
+        // Escape LIKE wildcards in user input to prevent injection
+        const escapeLike = (s) => s.replace(/[%_\\]/g, '\\$&');
+        const likeClause = words.map(() => "LOWER(tags) LIKE ? ESCAPE '\\'").join(' OR ');
+        const likeParams = words.map(w => `%${escapeLike(w)}%`);
+        const kindClause = kind ? 'AND kind = ?' : '';
+        const params = [projectId, minConf, ...likeParams];
+        if (kind)
+            params.push(kind);
+        params.push(limit);
+        return this.db.prepare(`
       SELECT * FROM memory_artifacts
       WHERE project_id = ? AND confidence >= ? AND supersedes_id IS NULL
         AND needs_review = 0
-        AND (${r})
-        ${_}
+        AND (${likeClause})
+        ${kindClause}
       ORDER BY confidence DESC, reuse_success_count DESC
       LIMIT ?
-    `).all(...o)}listRecent(t,e=20,n){const s=n?"AND kind = ?":"",a=[t];return n&&a.push(n),a.push(e),this.db.prepare(`
+    `).all(...params);
+    }
+    listRecent(projectId, limit = 20, kind) {
+        const kindClause = kind ? 'AND kind = ?' : '';
+        const params = [projectId];
+        if (kind)
+            params.push(kind);
+        params.push(limit);
+        return this.db.prepare(`
       SELECT * FROM memory_artifacts
       WHERE project_id = ? AND supersedes_id IS NULL AND needs_review = 0
-        ${s}
+        ${kindClause}
       ORDER BY confidence DESC, created_at DESC
       LIMIT ?
-    `).all(...a)}buildContextBrief(t,e,n={}){const s=n.kinds??["pattern","heuristic","reasoning_trace","lesson","anti_pattern"],a=n.maxItems??H,i=n.minConfidence??x,l=this.recall(t,e,{limit:a*2,minConfidence:i}),r=new Map;for(const f of l){if(!s.includes(f.artifact.kind))continue;const A=r.get(f.artifact.kind)??[];A.push(f),r.set(f.artifact.kind,A)}const m={pattern:"\u2705 Proven Patterns",heuristic:"\u{1F4A1} Heuristics",reasoning_trace:"\u{1F9E0} Past Reasoning",lesson:"\u{1F4DA} Lessons Learned",anti_pattern:"\u26A0\uFE0F Anti-Patterns to Avoid"},_=["pattern","heuristic","reasoning_trace","lesson","anti_pattern"],o=[],d=[];let N=0;for(const f of _){if(!s.includes(f))continue;const A=r.get(f)??[];if(!A.length)continue;const C=[];for(const g of A){if(N>=a)break;const c=g.artifact;let h=`**Problem:** ${c.problem}`;c.constraints&&(h+=`
-  _Constraints:_ ${c.constraints}`),c.validated_fix&&(h+=`
-  _Solution:_ ${c.validated_fix}`),c.why_it_worked&&(h+=`
-  _Why it worked:_ ${c.why_it_worked}`),c.outcome==="negative"&&(h+=`
-  _Note: This approach failed \u2014 avoid it_`),C.push(h),d.push(c.id),N++}C.length&&o.push({heading:m[f],items:C,source:f})}let S="";if(o.length>0){S+=`---
-## \u{F115D} Memory Brief
-_Relevant past knowledge from Wyrm:_
-
-`;for(const f of o){S+=`### ${f.heading}
-`;for(const A of f.items)S+=`- ${A}
-`;S+=`
-`}S+=`---
-`}return{sections:o,text:S,sourceIds:d}}getStats(t){const e=this.db.prepare("SELECT COUNT(*) as n FROM memory_artifacts WHERE project_id = ? AND supersedes_id IS NULL").get(t).n,n=this.db.prepare("SELECT COUNT(*) as n FROM memory_artifacts WHERE project_id = ? AND supersedes_id IS NOT NULL").get(t).n,s=this.db.prepare("SELECT AVG(confidence) as v FROM memory_artifacts WHERE project_id = ? AND supersedes_id IS NULL").get(t).v??0,a=this.db.prepare("SELECT kind, COUNT(*) as cnt FROM memory_artifacts WHERE project_id = ? AND supersedes_id IS NULL GROUP BY kind").all(t),i={};for(const l of a)i[l.kind]=l.cnt;return{total:e,byKind:i,avgConfidence:Math.round(s*100)/100,supersededCount:n}}listAll(t,e={}){const n=e.kind?"AND kind = ?":"",s=e.includeSuperseded?"":"AND supersedes_id IS NULL",a=[t];return e.kind&&a.push(e.kind),a.push(e.limit??50),this.db.prepare(`
+    `).all(...params);
+    }
+    // ==================== CONTEXT BRIEF ====================
+    /**
+     * Assemble an optimized memory brief for injection into an AI model's context.
+     * Excludes credentials/sensitive content. Groups by kind. Deduplicates.
+     * Returns sections with headings + items, plus raw text for direct injection.
+     */
+    buildContextBrief(projectId, task, opts = {}) {
+        const kinds = opts.kinds ?? ['pattern', 'heuristic', 'reasoning_trace', 'lesson', 'anti_pattern'];
+        const maxItems = opts.maxItems ?? MAX_BRIEF_ITEMS;
+        const minConf = opts.minConfidence ?? MIN_BRIEF_CONFIDENCE;
+        // Recall relevant artifacts
+        const recalled = this.recall(projectId, task, { limit: maxItems * 2, minConfidence: minConf });
+        // Group by kind, pick top items per kind
+        const byKind = new Map();
+        for (const r of recalled) {
+            if (!kinds.includes(r.artifact.kind))
+                continue;
+            const existing = byKind.get(r.artifact.kind) ?? [];
+            existing.push(r);
+            byKind.set(r.artifact.kind, existing);
+        }
+        const KIND_LABELS = {
+            pattern: '✅ Proven Patterns',
+            heuristic: '💡 Heuristics',
+            reasoning_trace: '🧠 Past Reasoning',
+            lesson: '📚 Lessons Learned',
+            anti_pattern: '⚠️ Anti-Patterns to Avoid',
+        };
+        // Prioritize: patterns > heuristics > reasoning_traces > lessons > anti_patterns
+        const kindOrder = ['pattern', 'heuristic', 'reasoning_trace', 'lesson', 'anti_pattern'];
+        const sections = [];
+        const sourceIds = [];
+        let totalItems = 0;
+        for (const kind of kindOrder) {
+            if (!kinds.includes(kind))
+                continue;
+            const items = byKind.get(kind) ?? [];
+            if (!items.length)
+                continue;
+            const sectionItems = [];
+            for (const r of items) {
+                if (totalItems >= maxItems)
+                    break;
+                const a = r.artifact;
+                let line = `**Problem:** ${a.problem}`;
+                if (a.constraints)
+                    line += `\n  _Constraints:_ ${a.constraints}`;
+                if (a.validated_fix)
+                    line += `\n  _Solution:_ ${a.validated_fix}`;
+                if (a.why_it_worked)
+                    line += `\n  _Why it worked:_ ${a.why_it_worked}`;
+                if (a.outcome === 'negative')
+                    line += `\n  _Note: This approach failed — avoid it_`;
+                sectionItems.push(line);
+                sourceIds.push(a.id);
+                totalItems++;
+            }
+            if (sectionItems.length) {
+                sections.push({ heading: KIND_LABELS[kind], items: sectionItems, source: kind });
+            }
+        }
+        // Build formatted text
+        let text = '';
+        if (sections.length > 0) {
+            text += '---\n## 󱅝 Memory Brief\n_Relevant past knowledge from Wyrm:_\n\n';
+            for (const section of sections) {
+                text += `### ${section.heading}\n`;
+                for (const item of section.items) {
+                    text += `- ${item}\n`;
+                }
+                text += '\n';
+            }
+            text += '---\n';
+        }
+        return { sections, text, sourceIds };
+    }
+    // ==================== STATS ====================
+    getStats(projectId) {
+        const total = this.db.prepare('SELECT COUNT(*) as n FROM memory_artifacts WHERE project_id = ? AND supersedes_id IS NULL').get(projectId).n;
+        const supersededCount = this.db.prepare('SELECT COUNT(*) as n FROM memory_artifacts WHERE project_id = ? AND supersedes_id IS NOT NULL').get(projectId).n;
+        const avgConfidence = this.db.prepare('SELECT AVG(confidence) as v FROM memory_artifacts WHERE project_id = ? AND supersedes_id IS NULL').get(projectId).v ?? 0;
+        const kindRows = this.db.prepare('SELECT kind, COUNT(*) as cnt FROM memory_artifacts WHERE project_id = ? AND supersedes_id IS NULL GROUP BY kind').all(projectId);
+        const byKind = {};
+        for (const r of kindRows)
+            byKind[r.kind] = r.cnt;
+        return { total, byKind, avgConfidence: Math.round(avgConfidence * 100) / 100, supersededCount };
+    }
+    listAll(projectId, opts = {}) {
+        const kindClause = opts.kind ? 'AND kind = ?' : '';
+        const supersededClause = opts.includeSuperseded ? '' : 'AND supersedes_id IS NULL';
+        const params = [projectId];
+        if (opts.kind)
+            params.push(opts.kind);
+        params.push(opts.limit ?? 50);
+        return this.db.prepare(`
       SELECT * FROM memory_artifacts
-      WHERE project_id = ? ${n} ${s}
+      WHERE project_id = ? ${kindClause} ${supersededClause}
       ORDER BY confidence DESC, created_at DESC
       LIMIT ?
-    `).all(...a)}listPage(t,e={pageSize:O}){const n=e.kind?"AND kind = ?":"",s=e.includeSuperseded?"":"AND supersedes_id IS NULL",a="AND needs_review = 0",i=[t];e.kind&&i.push(e.kind);let l="";if(e.after){const _=Number(e.after.sortKey);Number.isFinite(_)&&(l="AND (confidence < ? OR (confidence = ? AND id < ?))",i.push(_,_,e.after.id))}const r=e.pageSize+1;i.push(r);const m=this.db.prepare(`
+    `).all(...params);
+    }
+    /**
+     * Keyset-paginated sibling of `listAll` (v7 F4 T035). Orders by
+     * `(confidence DESC, id DESC)` — a TOTAL order (id is the unique tiebreak),
+     * so a page boundary that falls inside a run of tied-confidence artifacts
+     * drops nothing and repeats nothing (the bare-sortKey bug the cloud-sync
+     * keyset cursor taught us). The composite cursor `(confidence, id)` is opaque
+     * on the wire; a malformed cursor degrades to "first page" upstream.
+     *
+     * Over-fetches by one (`pageSize + 1`) so the caller can tell "is there more"
+     * without a COUNT. `pageSize` is already clamped to `[1, MAX_PAGE_SIZE]` by
+     * the keyset helper before it reaches here.
+     */
+    listPage(projectId, opts = { pageSize: DEFAULT_PAGE_SIZE }) {
+        const kindClause = opts.kind ? 'AND kind = ?' : '';
+        const supersededClause = opts.includeSuperseded ? '' : 'AND supersedes_id IS NULL';
+        // The wyrm://project/{id}/memory resource is advertised as a project's
+        // "validated memory artifacts" (handlers/resources.ts), and every other
+        // validated read path here enforces needs_review = 0 (searchByTags,
+        // listRecent, the FTS recall). Match that contract so the resource never
+        // surfaces unreviewed/quarantined rows (security pass #2, finding #2).
+        const reviewedClause = 'AND needs_review = 0';
+        const params = [projectId];
+        if (opts.kind)
+            params.push(opts.kind);
+        // Keyset predicate for a (confidence DESC, id DESC) total order: resume
+        // strictly AFTER the anchor row. `confidence` is bound as a number, the id
+        // as the unique tiebreak. Confidence is stored as a REAL so the cursor's
+        // string sortKey is parsed back to a float here (the encode round-trips it).
+        let keysetClause = '';
+        if (opts.after) {
+            const afterConf = Number(opts.after.sortKey);
+            if (Number.isFinite(afterConf)) {
+                keysetClause = 'AND (confidence < ? OR (confidence = ? AND id < ?))';
+                params.push(afterConf, afterConf, opts.after.id);
+            }
+        }
+        const fetch = opts.pageSize + 1;
+        params.push(fetch);
+        const rows = this.db.prepare(`
       SELECT * FROM memory_artifacts
-      WHERE project_id = ? ${n} ${s} ${a} ${l}
+      WHERE project_id = ? ${kindClause} ${supersededClause} ${reviewedClause} ${keysetClause}
       ORDER BY confidence DESC, id DESC
       LIMIT ?
-    `).all(...i);return T(m,e.pageSize,_=>({sortKey:String(_.confidence),id:_.id}))}pruneStale(t={}){const e=t.minConfidence??.3,n=t.olderThanDays??90,s=t.dryRun??!0,a=t.projectId!=null,i=[e,`-${n} days`];a&&i.push(t.projectId);const l=this.db.prepare(`
+    `).all(...params);
+        return buildPage(rows, opts.pageSize, (r) => ({ sortKey: String(r.confidence), id: r.id }));
+    }
+    /**
+     * Find (and optionally delete) stale, low-confidence artifacts safe to prune.
+     *
+     * A candidate must be: strictly below `minConfidence`, untouched for at least
+     * `olderThanDays` (or never accessed), already reviewed (needs_review = 0),
+     * and not superseding another artifact. When `projectId` is supplied the
+     * sweep is scoped to that project via an exact equality bind, so a prune can
+     * never reach into another project's rows; omit it for a global prune. The
+     * candidate set is capped at 500 per call. When `dryRun` is false the matched
+     * rows are deleted and the delete re-asserts needs_review = 0 as a final
+     * guard. Returns the candidates plus the number actually deleted.
+     */
+    pruneStale(opts = {}) {
+        const minConfidence = opts.minConfidence ?? 0.3;
+        const olderThanDays = opts.olderThanDays ?? 90;
+        const dryRun = opts.dryRun ?? true;
+        const scoped = opts.projectId != null;
+        const params = [minConfidence, `-${olderThanDays} days`];
+        if (scoped)
+            params.push(opts.projectId);
+        const candidates = this.db.prepare(`
       SELECT id, kind, problem, confidence, last_accessed_at
       FROM memory_artifacts
       WHERE confidence < ?
         AND (last_accessed_at IS NULL OR last_accessed_at < datetime('now', ?))
         AND needs_review = 0
         AND supersedes_id IS NULL
-        ${a?"AND project_id = ?":""}
+        ${scoped ? 'AND project_id = ?' : ''}
       ORDER BY confidence ASC
       LIMIT 500
-    `).all(...i);return s||l.length===0?{candidates:l,deleted:0,dryRun:s}:{candidates:l,deleted:this.deleteArtifacts(l.map(r=>r.id)),dryRun:s}}deleteArtifacts(t){if(t.length===0)return 0;const e=t.map(()=>"?").join(",");return this.db.prepare(`DELETE FROM memory_artifacts WHERE id IN (${e}) AND needs_review = 0`).run(...t).changes}}export{j as MemoryArtifacts};
+    `).all(...params);
+        if (dryRun || candidates.length === 0) {
+            return { candidates, deleted: 0, dryRun };
+        }
+        return { candidates, deleted: this.deleteArtifacts(candidates.map(c => c.id)), dryRun };
+    }
+    /**
+     * Delete artifacts by id, refusing any still flagged needs_review (a final
+     * guard so a stale id list can never remove a row that has since been queued
+     * for review). Returns the number of rows actually deleted. The CLI uses this
+     * to delete exactly the candidate set it showed the operator, so the confirmed
+     * set and the deleted set are always identical (no re-select in between).
+     */
+    deleteArtifacts(ids) {
+        if (ids.length === 0)
+            return 0;
+        const placeholders = ids.map(() => '?').join(',');
+        const result = this.db.prepare(`DELETE FROM memory_artifacts WHERE id IN (${placeholders}) AND needs_review = 0`).run(...ids);
+        return result.changes;
+    }
+}
+//# sourceMappingURL=memory-artifacts.js.map