@traqr/memory 0.1.0

package/dist/lib/quality-gate.js

@@ -0,0 +1,158 @@
+/**
+ * Quality Gate v2 — Domain-Agnostic Memory Validation
+ *
+ * Three-layer architecture:
+ *   Layer 1: Universal rejection (42 banned phrase regexes)
+ *   Layer 2: Universal specificity (16 domain-agnostic markers)
+ *   Layer 3: Code-specific boost (6 additive code markers)
+ *
+ * Three gate modes:
+ *   - Strict gate: LLM extraction pipeline (≥3 markers, ≥80 chars, confidence ≥0.85)
+ *   - Ingestion gate: MCP tools / agent writes (≥2 markers, ≥30 chars)
+ *   - Light gate: Life Import bulk (≥20 chars, banned phrases only)
+ *
+ * ADR: [[MCP Redesign — Quality Gate v2]]
+ */
+// ============================================================
+// Layer 1: Banned Phrases — content matching any is rejected
+// ============================================================
+export const BANNED_PHRASES = [
+    /\bbe careful\b/i,
+    /\bremember to\b/i,
+    /\balways make sure\b/i,
+    /\bconsider /i,
+    /\bthink about\b/i,
+    /\bdon't forget\b/i,
+    /\bpromoting\b.*\bseparation of concerns\b/i,
+    /\bcleaner\b.*\barchitecture\b/i,
+    /\bbest practice/i,
+    /\bensur(?:es?|ing)\b.*\bmaintainab/i,
+    /\bimportant to\b/i,
+    /\bkeep in mind\b/i,
+    /\bworth noting\b/i,
+    /\bhelps with\b/i,
+    /\bimproves?\b.*\breadability\b/i,
+    /\b(demonstrates?|suggests?|indicates?)\s+a\s+preference\b/i,
+    /\b(promoting|enhancing|improving)\s+(readability|maintainability)\b/i,
+    /\bcognitive load\b/i,
+    /\bindicating\b.*\b(value|preference|focus)\b/i,
+    /\bhighlighting\b.*\b(importance|value|preference)\b/i,
+    /\breflecting\b.*\b(design choice|preference|value)\b/i,
+    /\bfacilitating\b.*\b(easier|better|improved)\b/i,
+    /\b(this|the)\s+(approach|modification|update|change)\s+(aids?|revealed?)\b/i,
+    /\binforms?\s+future\s+developers?\b/i,
+    /\baids?\s+future\s+developers?\b/i,
+    /\bsave\s+time\s+for\s+future\b/i,
+];
+// ============================================================
+// Layer 2: Universal Specificity Markers (16 patterns)
+// Fire on ANY domain — dev, health, finance, cooking, personal.
+// ============================================================
+export const UNIVERSAL_SPECIFICITY_MARKERS = [
+    // Identity + judgment (existing, reclassified)
+    /\bSean\b/,
+    /\b(prefers?|prioritizes?|values?|avoids?|hates?|loves?)\b/i,
+    /\b(decided|chose|picked|rejected|ruled out)\b/i,
+    /\b(because|reason|rationale|motivation|why)\b/i,
+    /\b(goal|vision|strategy|roadmap|north star)\b/i,
+    // Quantitative + structural (existing, reclassified)
+    /\b\d{2,}\b/,
+    // NEW universal markers
+    /\b(always|never|every time|mandatory)\b/i,
+    /\b(instead of|rather than|not|unlike)\b/i,
+    /\b(discovered|learned|realized|found out)\b/i,
+    /\b(broke|failed|crashed|bug|error)\b/i,
+    /"[^"]{3,}"/,
+    /\b[A-Z]{2,}\b/,
+    /\b(recipe|ingredient|medication|dosage|blood|allergy|diagnosis|symptom|weight|calories)\b/i,
+    /\b(company|stock|portfolio|invest)\b/i,
+    /\b(deadline|meeting|project|sprint)\b/i,
+    /\w+\.\w+/,
+];
+// ============================================================
+// Layer 3: Code-Specific Markers (6 patterns, additive boost)
+// Only fire on content with code artifacts. Never required.
+// ============================================================
+export const CODE_SPECIFICITY_MARKERS = [
+    /`[^`]+`/,
+    /\.(ts|tsx|js|jsx|md|json|sql|sh|py|rs|go)/,
+    /[A-Z][a-z]+[A-Z]/,
+    /\b(src|lib|app|api|components|packages)\//,
+    /\w+\([^)]*\)/,
+    /\b(function|const|export|import|interface|type)\b/i,
+];
+// Backward-compatible union export
+export const SPECIFICITY_MARKERS = [...UNIVERSAL_SPECIFICITY_MARKERS, ...CODE_SPECIFICITY_MARKERS];
+// ============================================================
+// Fluff Patterns — generic LLM-speak that adds no value
+// ============================================================
+export const FLUFF_PATTERNS = [
+    /\b(promotes?|ensures?|improves?|enables?|facilitates?|leverages?)\b.*\b(cleaner|better|proper|good|robust|maintainable|scalable|readable|modular)\b/i,
+    /\b(this|the)\s+(approach|pattern|modification|change|update)\b.*\b(helps?|allows?|supports?|shows? how)\b/i,
+    /\badopt the pattern\b/i,
+    /\b(demonstrates?|suggests?|indicates?|showcases?|illustrates?|highlights?|reveals?)\s+(a\s+)?(preference|value|focus|priority)\s+(for|on|in)\b/i,
+    /\b(modular|scalable|maintainable|readable)\b.*\b(code|design|architecture)\b/i,
+    /\b(separation of concerns|single responsibility|DRY principle)\b/i,
+    /\b(enhancing|improving|promoting)\s+(readability|maintainability|scalability|reusability)\b/i,
+    /\bthe\s+(drastic|extensive|deliberate|significant|major)\s+(reduction|insertion|removal|update|change)\b.*\b(indicates?|suggests?|shows?)\b/i,
+    /\bensuring\s+(comprehensive|thorough|complete)\s+(testing|coverage|validation)\b/i,
+    /\b(extensive|significant|large)\s+(insertion|addition|deletion|removal)\s+of\s+\d+/i,
+];
+// ============================================================
+// Scoring
+// ============================================================
+function countSpecificityMarkers(content) {
+    const universal = UNIVERSAL_SPECIFICITY_MARKERS.filter(p => p.test(content)).length;
+    const code = CODE_SPECIFICITY_MARKERS.filter(p => p.test(content)).length;
+    return universal + code;
+}
+// ============================================================
+// Strict Gate — LLM extraction pipeline
+// ============================================================
+export function passesQualityGate(learning) {
+    if (learning.confidence < 0.85)
+        return false;
+    if (learning.content.length < 80)
+        return false;
+    if (countSpecificityMarkers(learning.content) < 3)
+        return false;
+    if (BANNED_PHRASES.some(r => r.test(learning.content)))
+        return false;
+    if (FLUFF_PATTERNS.some(r => r.test(learning.content)))
+        return false;
+    return true;
+}
+// ============================================================
+// Ingestion Gate — MCP tools, agent writes, pulse
+// ============================================================
+export function passesIngestionGate(content) {
+    if (content.length < 30) {
+        return { passes: false, reason: 'Content too short (min 30 chars)' };
+    }
+    const hasBannedPhrase = BANNED_PHRASES.some(r => r.test(content));
+    if (hasBannedPhrase) {
+        return { passes: false, reason: 'Content contains generic/advisory phrasing' };
+    }
+    const hasFluff = FLUFF_PATTERNS.some(r => r.test(content));
+    if (hasFluff) {
+        return { passes: false, reason: 'Content is too generic — add specific details (file paths, function names, concrete decisions)' };
+    }
+    if (countSpecificityMarkers(content) < 2) {
+        return { passes: false, reason: 'Content lacks specificity — include at least 2 of: file paths, function names, code refs, concrete decisions, or rationale' };
+    }
+    return { passes: true };
+}
+// ============================================================
+// Light Gate — Life Import bulk ingestion
+// ============================================================
+export function passesLightGate(content) {
+    if (content.length < 20) {
+        return { passes: false, reason: 'Content too short (min 20 chars)' };
+    }
+    const hasBannedPhrase = BANNED_PHRASES.some(r => r.test(content));
+    if (hasBannedPhrase) {
+        return { passes: false, reason: 'Content contains generic/advisory phrasing' };
+    }
+    return { passes: true };
+}
+//# sourceMappingURL=quality-gate.js.map

package/dist/lib/quality-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality-gate.js","sourceRoot":"","sources":["../../src/lib/quality-gate.ts"],"names":[],"mappings":"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"}

package/dist/lib/quality-gate.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Quality Gate v2 — Verification Script
+ *
+ * Tests MUST PASS and MUST FAIL cases from [[MCP Redesign -- Quality Gate v2]] ADR.
+ * Run: npx ts-node packages/memory/src/lib/quality-gate.test.ts
+ */
+export {};

package/dist/lib/quality-gate.test.js

@@ -0,0 +1,75 @@
+/**
+ * Quality Gate v2 — Verification Script
+ *
+ * Tests MUST PASS and MUST FAIL cases from [[MCP Redesign -- Quality Gate v2]] ADR.
+ * Run: npx ts-node packages/memory/src/lib/quality-gate.test.ts
+ */
+import { passesIngestionGate, passesLightGate, passesQualityGate } from './quality-gate.js';
+let passed = 0;
+let failed = 0;
+function assert(label, actual, expected) {
+    if (actual === expected) {
+        console.log(`  PASS  ${label}`);
+        passed++;
+    }
+    else {
+        console.log(`  FAIL  ${label} (got ${actual}, expected ${expected})`);
+        failed++;
+    }
+}
+// ============================================================
+// Ingestion Gate — MUST PASS
+// ============================================================
+console.log('\n--- Ingestion Gate: MUST PASS ---');
+assert('Personal health: "Sean\'s blood type is O+ and he discovered this at age 28"', passesIngestionGate("Sean's blood type is O+ and he discovered this at age 28").passes, true);
+assert('Work fact with numbers: "The deadline for Q2 sprint is March 30"', passesIngestionGate('The deadline for Q2 sprint is March 30').passes, true);
+assert('Health discovery: "Discovered that BMI above 25 increases risk"', passesIngestionGate('Discovered that BMI above 25 increases risk').passes, true);
+assert('API error: "The API returns 429 when rate-limited"', passesIngestionGate('The API returns 429 when rate-limited').passes, true);
+assert('Finance decision: "Sean decided to invest in AAPL instead of GOOG"', passesIngestionGate('Sean decided to invest in AAPL instead of GOOG').passes, true);
+assert('Finance numbers: "Portfolio target is 60% stocks, 40% bonds"', passesIngestionGate('Portfolio target is 60% stocks, 40% bonds').passes, true);
+assert('Dev content still passes: "The `searchMemories` function in src/lib/memory.ts handles vector search"', passesIngestionGate('The `searchMemories` function in src/lib/memory.ts handles vector search').passes, true);
+assert('Preference with reasoning: "Sean prefers TypeScript because it catches errors at compile time"', passesIngestionGate('Sean prefers TypeScript because it catches errors at compile time').passes, true);
+// ============================================================
+// Ingestion Gate — MUST FAIL
+// ============================================================
+console.log('\n--- Ingestion Gate: MUST FAIL ---');
+assert('Banned: "Remember to always be careful"', passesIngestionGate('Remember to always be careful').passes, false);
+assert('Banned: "This is a best practice for clean code"', passesIngestionGate('This is a best practice for clean code').passes, false);
+assert('Too short: "ok"', passesIngestionGate('ok').passes, false);
+assert('No markers: "I did some stuff today and it was interesting overall"', passesIngestionGate('I did some stuff today and it was interesting overall').passes, false);
+assert('Fluff: "The approach demonstrates a preference for clean architecture"', passesIngestionGate('The approach demonstrates a preference for clean architecture').passes, false);
+// ============================================================
+// Light Gate — MUST PASS
+// ============================================================
+console.log('\n--- Light Gate: MUST PASS ---');
+assert('Casual content: "I had pasta for dinner last night"', passesLightGate('I had pasta for dinner last night').passes, true);
+assert('Short but valid: "This is a valid memory entry"', passesLightGate('This is a valid memory entry').passes, true);
+// ============================================================
+// Light Gate — MUST FAIL
+// ============================================================
+console.log('\n--- Light Gate: MUST FAIL ---');
+assert('Too short: "hi"', passesLightGate('hi').passes, false);
+assert('Banned phrase: "Remember to always be careful with authentication"', passesLightGate('Remember to always be careful with authentication').passes, false);
+// ============================================================
+// Strict Gate — spot checks
+// ============================================================
+console.log('\n--- Strict Gate: spot checks ---');
+assert('High confidence dev content passes strict', passesQualityGate({
+    content: 'The `searchMemories` function in packages/memory/src/lib/memory.ts uses a cosine similarity threshold of 0.35 because lower values return too much noise',
+    confidence: 0.9
+}), true);
+assert('Low confidence rejected', passesQualityGate({ content: 'Some important learning about code', confidence: 0.5 }), false);
+assert('Short content rejected', passesQualityGate({ content: 'Short', confidence: 0.9 }), false);
+// ============================================================
+// Summary
+// ============================================================
+console.log(`\n${'='.repeat(50)}`);
+console.log(`Results: ${passed} passed, ${failed} failed`);
+if (failed > 0) {
+    console.log('QUALITY GATE TESTS FAILED');
+    process.exit(1);
+}
+else {
+    console.log('All quality gate tests passed!');
+}
+//# sourceMappingURL=quality-gate.test.js.map

package/dist/lib/quality-gate.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality-gate.test.js","sourceRoot":"","sources":["../../src/lib/quality-gate.test.ts"],"names":[],"mappings":"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"}

package/dist/lib/rerank.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Cohere Rerank Integration
+ *
+ * Optional final retrieval stage. Takes RRF-fused candidates + query,
+ * returns reranked results with 0-1 relevance scores.
+ * Graceful degradation: returns null if COHERE_API_KEY not set or on any error.
+ */
+export interface RerankResult {
+    id: string;
+    relevanceScore: number;
+    index: number;
+}
+export interface RerankDocument {
+    id: string;
+    content: string;
+}
+/**
+ * Rerank documents using Cohere Rerank v3.5.
+ * Returns null if COHERE_API_KEY is not set or on any error.
+ * Caller should fall back to existing RRF scores.
+ */
+export declare function cohereRerank(query: string, documents: RerankDocument[], topN?: number): Promise<RerankResult[] | null>;

package/dist/lib/rerank.js

@@ -0,0 +1,61 @@
+/**
+ * Cohere Rerank Integration
+ *
+ * Optional final retrieval stage. Takes RRF-fused candidates + query,
+ * returns reranked results with 0-1 relevance scores.
+ * Graceful degradation: returns null if COHERE_API_KEY not set or on any error.
+ */
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+let missingKeyLogged = false;
+// ---------------------------------------------------------------------------
+// Cohere Rerank
+// ---------------------------------------------------------------------------
+/**
+ * Rerank documents using Cohere Rerank v3.5.
+ * Returns null if COHERE_API_KEY is not set or on any error.
+ * Caller should fall back to existing RRF scores.
+ */
+export async function cohereRerank(query, documents, topN = 20) {
+    const apiKey = process.env.COHERE_API_KEY;
+    if (!apiKey) {
+        if (!missingKeyLogged) {
+            console.info('[rerank] COHERE_API_KEY not set — skipping rerank, using RRF scores');
+            missingKeyLogged = true;
+        }
+        return null;
+    }
+    if (documents.length === 0)
+        return null;
+    try {
+        const response = await fetch('https://api.cohere.com/v2/rerank', {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                model: 'rerank-v3.5',
+                query,
+                documents: documents.map((d) => d.content),
+                top_n: Math.min(topN, documents.length),
+            }),
+        });
+        if (!response.ok) {
+            console.warn(`[rerank] Cohere API error: ${response.status} ${response.statusText}`);
+            return null;
+        }
+        const data = await response.json();
+        return (data.results || []).map((r) => ({
+            id: documents[r.index].id,
+            relevanceScore: r.relevance_score,
+            index: r.index,
+        }));
+    }
+    catch (err) {
+        console.warn('[rerank] Cohere rerank failed:', err instanceof Error ? err.message : err);
+        return null;
+    }
+}
+//# sourceMappingURL=rerank.js.map

package/dist/lib/rerank.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rerank.js","sourceRoot":"","sources":["../../src/lib/rerank.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAiBH,8EAA8E;AAC9E,QAAQ;AACR,8EAA8E;AAE9E,IAAI,gBAAgB,GAAG,KAAK,CAAA;AAE5B,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAa,EACb,SAA2B,EAC3B,OAAe,EAAE;IAEjB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAA;IACzC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACtB,OAAO,CAAC,IAAI,CAAC,qEAAqE,CAAC,CAAA;YACnF,gBAAgB,GAAG,IAAI,CAAA;QACzB,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAEvC,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,kCAAkC,EAAE;YAC/D,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,eAAe,EAAE,UAAU,MAAM,EAAE;gBACnC,cAAc,EAAE,kBAAkB;aACnC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,KAAK,EAAE,aAAa;gBACpB,KAAK;gBACL,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;gBAC1C,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC;aACxC,CAAC;SACH,CAAC,CAAA;QAEF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,OAAO,CAAC,IAAI,CAAC,8BAA8B,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAA;YACpF,OAAO,IAAI,CAAA;QACb,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAE/B,CAAA;QAED,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACtC,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE;YACzB,cAAc,EAAE,CAAC,CAAC,eAAe;YACjC,KAAK,EAAE,CAAC,CAAC,KAAK;SACf,CAAC,CAAC,CAAA;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,IAAI,CAAC,gCAAgC,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;QACxF,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC"}

package/dist/lib/retrieval.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Multi-Strategy Retrieval + RRF Fusion
+ *
+ * SearchOrchestrator for Memory Engine v2.
+ * Combines semantic, BM25, temporal, and graph search via
+ * Reciprocal Rank Fusion. Replaces single-strategy semantic search.
+ */
+import { SupabaseVectorProvider } from '../vectordb/supabase.js';
+import type { MemorySearchResult, SearchOptions } from '../vectordb/types.js';
+export type SearchStrategy = 'semantic' | 'bm25' | 'temporal' | 'graph';
+export interface StrategyResult {
+    strategy: string;
+    items: {
+        id: string;
+        rank: number;
+    }[];
+}
+export interface FusedItem {
+    id: string;
+    rrfScore: number;
+    normalizedScore: number;
+    strategies: string[];
+}
+export interface DetectedStrategies {
+    strategies: SearchStrategy[];
+    temporalRange?: {
+        start: Date;
+        end: Date;
+    };
+    graphSeedIds?: string[];
+}
+export interface SearchV2Options extends SearchOptions {
+    entityIds?: string[];
+    strategies?: SearchStrategy[];
+    rrfK?: number;
+}
+/**
+ * Fuse ranked results from multiple search strategies via RRF.
+ *
+ * For each item across all strategies: score += 1/(k + rank)
+ * Items appearing in multiple strategies accumulate higher scores.
+ *
+ * @param strategyResults - Ranked results from each strategy
+ * @param k - RRF constant (default 60, standard in literature)
+ * @param topN - Max results to return
+ */
+export declare function reciprocalRankFusion(strategyResults: StrategyResult[], k?: number, topN?: number): FusedItem[];
+/**
+ * Detect which search strategies should be activated for a query.
+ * Semantic + BM25 always run. Temporal activates on date patterns.
+ * Graph activates when entity seed IDs are provided.
+ */
+export declare function detectStrategies(query: string, entityIds?: string[]): DetectedStrategies;
+/**
+ * Parse temporal references in a query to a date range.
+ * Falls back to 30-day lookback for ambiguous patterns.
+ */
+export declare function parseTemporalRange(query: string): {
+    start: Date;
+    end: Date;
+};
+/**
+ * Find known entities mentioned in a search query.
+ * Tokenizes the query, filters stopwords, looks up against memory_entities.
+ * Returns entity IDs for graph search activation.
+ */
+export declare function findEntitiesInQuery(query: string, provider: SupabaseVectorProvider): Promise<string[]>;
+/**
+ * Multi-strategy search with RRF fusion.
+ *
+ * Runs semantic + BM25 in parallel (always), plus temporal and graph
+ * when detected. Fuses results via Reciprocal Rank Fusion.
+ * Returns MemorySearchResult[] for backward compatibility.
+ */
+export declare function searchMemoriesV2(query: string, options?: SearchV2Options): Promise<MemorySearchResult[]>;