@jhizzard/termdeck 0.9.0 → 0.10.0

package/packages/server/src/rag.js

@@ -46,10 +46,28 @@ class RAGIntegration {
     this.db = db;
     this.supabaseUrl = config.rag?.supabaseUrl || null;
     this.supabaseKey = config.rag?.supabaseKey || null;
+    this.openaiApiKey = config.rag?.openaiApiKey || process.env.OPENAI_API_KEY || null;
     this.enabled = !!(config.rag?.enabled && this.supabaseUrl && this.supabaseKey);
     this.syncInterval = config.rag?.syncIntervalMs || 10000;
     this._syncTimer = null;
 
+    // Sprint 38 / T3 — graph-aware recall toggle. When true, the recall()
+    // method routes through the new memory_recall_graph RPC (vector seed +
+    // graph expansion + combined re-rank). When false (default), it
+    // delegates to the existing mnestra-bridge vector path. The half-life
+    // mirrors the SQL function default (30 days) but is exposed here so
+    // callers can override it without re-deploying the migration.
+    this.graphRecall = config.rag?.graphRecall === true;
+    this.graphRecallDepth = Math.max(1, Math.min(5, config.rag?.graphRecallDepth ?? 2));
+    this.graphRecallK = Math.max(1, Math.min(50, config.rag?.graphRecallK ?? 10));
+    this.graphRecallRecencyHalflifeDays = config.rag?.graphRecallRecencyHalflifeDays ?? 30;
+
+    // Bridge reference for the vector-only recall path. Wired in by index.js
+    // after the bridge is created so we avoid duplicating the embed → RPC
+    // plumbing here. Optional: if absent, recall() with graphRecall=false
+    // throws a helpful error instead of silently returning empty.
+    this._bridge = null;
+
     // Table configuration matching Josh's multi-layer schema
     this.tables = {
       sessionMemory: config.rag?.tables?.session || 'mnestra_session_memory',
@@ -374,6 +392,126 @@ class RAGIntegration {
     this._statusWriteAt.clear();
   }
 
+  // Sprint 38 / T3 — wire the mnestra-bridge so vector-only recall delegates
+  // to the existing direct/webhook/mcp path instead of duplicating the embed
+  // pipeline here.
+  setBridge(bridge) {
+    this._bridge = bridge || null;
+  }
+
+  // Sprint 38 / T3 — graph-aware recall entry point. Returns the same shape
+  // as bridge.queryMnestra: { memories: [...], total }. Routes through the
+  // memory_recall_graph RPC when graphRecall is enabled, otherwise falls
+  // back to the bridge's vector path.
+  //
+  // options: { project?, searchAll?, sessionContext?, cwd?, depth?, k? }
+  async recall(query, options = {}) {
+    if (this.graphRecall) {
+      return this._recallViaGraph(query, options);
+    }
+    return this._recallViaVectorOnly(query, options);
+  }
+
+  async _recallViaVectorOnly(query, options) {
+    if (!this._bridge) {
+      throw new Error('RAGIntegration.recall: no bridge wired (call setBridge first)');
+    }
+    return this._bridge.queryMnestra({
+      question: query,
+      project: options.project,
+      searchAll: !!options.searchAll,
+      sessionContext: options.sessionContext,
+      cwd: options.cwd
+    });
+  }
+
+  // Direct REST call to memory_recall_graph (migration 010). Mirrors the
+  // bridge.queryDirect pattern: OpenAI embedding → Supabase RPC. Stays in
+  // rag.js so callers don't need to know which mnestra mode the bridge is
+  // using; graph recall is always direct-against-Postgres because the RPC
+  // doesn't ship as a Mnestra MCP tool yet (Sprint 38 / T1 wires the
+  // related MCP tools — graph recall lives here for now).
+  async _recallViaGraph(query, options) {
+    if (!this.supabaseUrl || !this.supabaseKey) {
+      throw new Error('graphRecall: supabaseUrl/supabaseKey not configured');
+    }
+    if (!this.openaiApiKey) {
+      throw new Error('graphRecall: OPENAI_API_KEY not configured');
+    }
+
+    const project = options.searchAll ? null : (options.project || null);
+    const depth = options.depth ?? this.graphRecallDepth;
+    const k = options.k ?? this.graphRecallK;
+
+    const embeddingRes = await fetch('https://api.openai.com/v1/embeddings', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.openaiApiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        model: 'text-embedding-3-large',
+        input: query,
+        dimensions: 1536
+      })
+    });
+    if (!embeddingRes.ok) {
+      const err = await embeddingRes.text();
+      console.error('[rag:graph] embedding failed:', err);
+      throw new Error('graphRecall: embedding generation failed');
+    }
+    const embeddingData = await embeddingRes.json();
+    const embedding = embeddingData.data[0].embedding;
+
+    console.log(`[rag] using graph recall path project=${project ?? 'ALL'} depth=${depth} k=${k}`);
+
+    const rpcBody = {
+      query_embedding: `[${embedding.join(',')}]`,
+      project_filter: project,
+      max_depth: depth,
+      k
+    };
+    const rpcRes = await fetch(`${this.supabaseUrl}/rest/v1/rpc/memory_recall_graph`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'apikey': this.supabaseKey,
+        'Authorization': `Bearer ${this.supabaseKey}`
+      },
+      body: JSON.stringify(rpcBody)
+    });
+    if (!rpcRes.ok) {
+      const err = await rpcRes.text();
+      console.error(`[rag:graph] RPC failed ${rpcRes.status}:`, err);
+      throw new Error(`graphRecall: memory_recall_graph RPC failed (${rpcRes.status})`);
+    }
+    const rows = await rpcRes.json();
+    return {
+      memories: rows.map((m) => ({
+        content: m.content,
+        // graph recall doesn't return source_type; preserve the bridge's
+        // shape by returning null so consumers don't crash on chip render.
+        source_type: m.source_type ?? null,
+        project: m.project,
+        // The bridge consumers read `similarity`; pass final_score so they
+        // see the combined (vector × edge × recency) signal as the badge.
+        // Also expose the underlying scores for callers that want to split
+        // them out (graph viz, debugging).
+        similarity: m.final_score,
+        depth: m.depth,
+        vector_score: m.vector_score,
+        edge_weight: m.edge_weight,
+        recency_score: m.recency_score,
+        path: m.path,
+        // memory_recall_graph doesn't return created_at — depth-N neighbors
+        // come from the graph walk, not a direct timestamp pull. Caller can
+        // re-fetch via memory_get if they need it.
+        created_at: m.created_at ?? null
+      })),
+      total: rows.length
+    };
+  }
+
   // Live-toggle for the dashboard RAG settings panel (Sprint 36 T3 Deliverable A).
   // Re-evaluates eligibility — flipping `enabled: true` without configured
   // Supabase creds is a no-op so the live integration never claims to be on

package/packages/server/src/setup/mnestra-migrations/009_memory_relationship_metadata.sql

@@ -0,0 +1,126 @@
+-- 009_memory_relationship_metadata.sql
+--
+-- Sprint 38 (T1) — Knowledge graph substrate.
+-- Adds graph-edge metadata columns to memory_relationships, expands the
+-- relationship_type vocabulary from 5 to 8 values, and ships a recursive-CTE
+-- traversal function (expand_memory_neighborhood) for N-hop neighborhood
+-- queries.
+--
+-- Idempotent: safe to re-run.
+--
+-- Pre-existing state (verified against petvetbid 2026-04-27 17:25 ET):
+--   memory_relationships has 749 live edges. The migration adds nullable
+--   columns and a wider CHECK; no existing row violates the new constraint.
+--
+-- The original CHECK on relationship_type is anonymous (defined inline in
+-- migration 001), so its name is auto-generated (e.g., memory_relationships_check1).
+-- We can't rely on a known name for DROP CONSTRAINT; the DO block below
+-- introspects pg_constraint and drops any CHECK on this table whose
+-- definition references "relationship_type IN" — preserving the separate
+-- (source_id <> target_id) CHECK.
+
+-- ── 1. Metadata columns ──────────────────────────────────────────────────
+
+alter table memory_relationships
+  add column if not exists weight       float,
+  add column if not exists inferred_at  timestamptz,
+  add column if not exists inferred_by  text;
+
+-- ── 2. Expand relationship_type CHECK vocabulary ─────────────────────────
+
+do $$
+declare
+  c record;
+begin
+  for c in
+    select con.conname
+    from pg_constraint con
+    join pg_class cls on cls.oid = con.conrelid
+    where cls.relname = 'memory_relationships'
+      and con.contype = 'c'
+      and pg_get_constraintdef(con.oid) ilike '%relationship_type%'
+  loop
+    execute format('alter table memory_relationships drop constraint %I', c.conname);
+  end loop;
+end
+$$;
+
+alter table memory_relationships
+  add constraint memory_relationships_relationship_type_check
+  check (relationship_type in (
+    'supersedes',
+    'relates_to',
+    'contradicts',
+    'elaborates',
+    'caused_by',
+    'blocks',
+    'inspired_by',
+    'cross_project_link'
+  ));
+
+-- ── 3. Indexes for graph traversal ───────────────────────────────────────
+
+create index if not exists memory_relationships_weight_idx
+  on memory_relationships(weight)
+  where weight is not null;
+
+create index if not exists memory_relationships_inferred_at_idx
+  on memory_relationships(inferred_at)
+  where inferred_at is not null;
+
+-- ── 4. expand_memory_neighborhood — recursive-CTE N-hop traversal ────────
+--
+-- Returns one row per (memory_id, depth) reachable from start_id within
+-- max_depth hops. Edges are undirected for traversal purposes (source_id
+-- and target_id treated symmetrically) — agents linking memories don't
+-- always think directionally, and graph-aware recall benefits from
+-- bidirectional reachability.
+--
+-- Cycle-safe: the path[] array tracks visited nodes; we only follow an
+-- edge if its other endpoint is not already in path. Without this check,
+-- the CTE would loop indefinitely on any cycle in the graph.
+--
+-- edge_kinds[] mirrors path: position i in edge_kinds is the relationship_type
+-- of the edge that brought us to position i+1 in path. Caller can filter
+-- downstream by inspecting edge_kinds (e.g., drop rows whose path traversed
+-- a 'contradicts' edge).
+--
+-- Performance note: with ~5K memory_items and ~750 edges (current scale),
+-- recursive expansion to depth 2 returns in <50ms unsharded. At >50K edges
+-- consider materializing precomputed neighborhoods.
+
+create or replace function expand_memory_neighborhood(
+  start_id  uuid,
+  max_depth int default 2
+)
+returns table (
+  memory_id  uuid,
+  depth      int,
+  path       uuid[],
+  edge_kinds text[]
+)
+language sql stable
+as $$
+  with recursive neighborhood as (
+    select
+      start_id                  as memory_id,
+      0                         as depth,
+      array[start_id]           as path,
+      array[]::text[]           as edge_kinds
+    union all
+    select
+      case when r.source_id = n.memory_id then r.target_id else r.source_id end,
+      n.depth + 1,
+      n.path || (case when r.source_id = n.memory_id then r.target_id else r.source_id end),
+      n.edge_kinds || r.relationship_type
+    from neighborhood n
+    join memory_relationships r
+      on (r.source_id = n.memory_id or r.target_id = n.memory_id)
+    where n.depth < max_depth
+      and not (
+        case when r.source_id = n.memory_id then r.target_id else r.source_id end
+        = any (n.path)
+      )
+  )
+  select memory_id, depth, path, edge_kinds from neighborhood;
+$$;

package/packages/server/src/setup/mnestra-migrations/010_memory_recall_graph.sql

@@ -0,0 +1,147 @@
+-- Mnestra v0.3 — memory_recall_graph (Sprint 38 / T3)
+--
+-- Graph-aware recall. Two-stage retrieval:
+--
+--   Stage 1: vector recall via match_memories() — top-K nearest neighbors
+--            in embedding space (existing RPC; tombstone filters inherited).
+--   Stage 2: graph expansion via expand_memory_neighborhood() — for each
+--            stage-1 seed, walk the relationship graph to max_depth.
+--
+-- Re-rank the union of (stage 1 ∪ stage 2) by a combined signal:
+--
+--   final_score = vector_score × edge_weight × recency_score
+--
+-- where:
+--   vector_score  = cosine similarity of seed memory to query (0..1)
+--   edge_weight   = mean of memory_relationships.weight along the path,
+--                   defaulting to 0.5 for edges T2 hasn't classified yet
+--                   (the 749 pre-T2 edges all start with weight = NULL).
+--   recency_score = exp(-age_seconds / (30 × 86400))  (30-day half-life)
+--
+-- Initial (depth=0) results are seeded with edge_weight = 1.0 (no path).
+--
+-- Hard dependencies:
+--   • migration 009 must have run (introduces memory_relationships.weight
+--     and the expand_memory_neighborhood function).
+--   • migration 001 (match_memories, memory_items, memory_relationships).
+--
+-- Rerun-safe: CREATE OR REPLACE.
+
+create or replace function memory_recall_graph (
+  query_embedding   vector(1536),
+  project_filter    text default null,
+  max_depth         int default 2,
+  k                 int default 10
+)
+returns table (
+  memory_id      uuid,
+  content        text,
+  project        text,
+  depth          int,
+  vector_score   float,
+  edge_weight    float,
+  recency_score  float,
+  final_score    float,
+  path           uuid[]
+)
+language sql stable
+as $$
+  with initial as (
+    -- Stage 1: top-K vector recall. match_memories already filters
+    -- is_active / archived / superseded_by / project, so depth-0 hits
+    -- are tombstone-clean. match_threshold=0.0 returns the full top-K
+    -- (we rank by combined signal, not by raw similarity threshold).
+    select
+      mm.id          as memory_id,
+      mm.content,
+      mm.project,
+      0              as depth,
+      mm.similarity  as vector_score,
+      mi.created_at,
+      array[mm.id]   as path
+    from match_memories(query_embedding, 0.0, k, project_filter) mm
+    join memory_items mi on mi.id = mm.id
+  ),
+  expanded as (
+    -- Stage 2: graph expansion. For each stage-1 seed, walk the graph to
+    -- max_depth via T1's expand_memory_neighborhood RPC. Carry the seed's
+    -- vector_score forward (we do NOT re-embed neighbors — the assumption
+    -- is "if A is relevant to the query and B is connected to A, then B
+    -- inherits some of A's relevance, attenuated by the path weight").
+    select
+      n.memory_id,
+      mi.content,
+      mi.project,
+      n.depth,
+      i.vector_score,
+      mi.created_at,
+      n.path,
+      coalesce(
+        (
+          -- Average of edge weights along the path (cycle-safe: T1's CTE
+          -- guarantees no repeats). Pairwise lookup over consecutive path
+          -- elements, treating the relationship as undirected so A→B and
+          -- B→A both count.
+          select avg(coalesce(r.weight, 0.5))
+          from generate_series(1, array_length(n.path, 1) - 1) as g
+          join memory_relationships r
+            on (r.source_id = n.path[g] and r.target_id = n.path[g + 1])
+            or (r.source_id = n.path[g + 1] and r.target_id = n.path[g])
+        ),
+        0.5
+      ) as edge_weight
+    from initial i
+    cross join lateral expand_memory_neighborhood(i.memory_id, max_depth) n
+    join memory_items mi
+      on mi.id = n.memory_id
+     and mi.is_active = true
+     and mi.archived = false
+     and mi.superseded_by is null
+    where n.depth > 0
+      and (project_filter is null or mi.project = project_filter)
+  ),
+  unioned as (
+    -- depth-0 seeds get edge_weight = 1.0 (no path traversed).
+    select memory_id, content, project, depth, vector_score,
+           1.0::float as edge_weight, created_at, path
+    from initial
+    union all
+    select memory_id, content, project, depth, vector_score,
+           edge_weight, created_at, path
+    from expanded
+  ),
+  scored as (
+    -- Same memory may be reached via multiple paths (vector seed AND graph
+    -- expansion, or two different seeds). Keep the strongest path: highest
+    -- final_score wins, with depth-0 (vector hit) preferred on ties.
+    select distinct on (memory_id)
+      memory_id,
+      content,
+      project,
+      depth,
+      vector_score,
+      edge_weight,
+      exp(-extract(epoch from (now() - created_at))::float / (30.0 * 86400.0))
+        as recency_score,
+      vector_score * edge_weight
+        * exp(-extract(epoch from (now() - created_at))::float / (30.0 * 86400.0))
+        as final_score,
+      path
+    from unioned
+    order by memory_id, final_score desc, depth asc
+  )
+  select
+    memory_id, content, project, depth, vector_score,
+    edge_weight, recency_score, final_score, path
+  from scored
+  order by final_score desc
+  limit 50;
+$$;
+
+-- Lightweight grant convention follows existing match_memories. Service-role
+-- and authenticated callers should already have execute by inheritance, but
+-- be explicit for the new function so PostgREST surfaces it without a manual
+-- dashboard step.
+
+grant execute on function memory_recall_graph(vector, text, int, int)
+  to authenticated, service_role, anon;

package/packages/server/src/setup/rumen/migrations/003_graph_inference_schedule.sql

@@ -0,0 +1,49 @@
+-- Sprint 38 T2 — Graph-inference cron schedule.
+-- Schedules the graph-inference Supabase Edge Function to run daily at
+-- 03:00 UTC (≈ 23:00 ET, after typical work hours). The Edge Function
+-- scans memory_items for pairs above GRAPH_INFERENCE_THRESHOLD (default
+-- 0.85 cosine similarity), inserts edges into memory_relationships with
+-- inferred_by = 'cron-YYYY-MM-DD' for audit trail, and optionally
+-- classifies edge types via Haiku 4.5 (gated by GRAPH_LLM_CLASSIFY=1).
+--
+-- Coexists with the existing rag-system MCP-side ingest classifier:
+-- this cron handles backfill + cross-project + stale-edge refresh; the
+-- ingest classifier handles fresh per-memory edges in the 0.75-0.92
+-- window.  See Sprint 38 T2 FINDING for the full coexistence design.
+--
+-- Before applying:
+--   1. The pg_cron and pg_net extensions must already be enabled
+--      (rumen migration 002 enables them; 003 assumes that prereq).
+--   2. Add a Vault secret named 'graph_inference_service_role_key'
+--      containing the project's service-role JWT.  Separate from
+--      'rumen_service_role_key' so a key rotation on one cron doesn't
+--      affect the other.
+--   3. Replace <project-ref> below with the project's Supabase ref
+--      (stack-installer substitutes this at apply-time, same as 002).
+--
+-- Apply with:
+--   psql "$DIRECT_URL" -f migrations/003_graph_inference_schedule.sql
+
+-- Idempotent unschedule.
+SELECT cron.unschedule('graph-inference-tick')
+  WHERE EXISTS (SELECT 1 FROM cron.job WHERE jobname = 'graph-inference-tick');
+
+-- Schedule daily at 03:00 UTC.
+SELECT cron.schedule(
+  'graph-inference-tick',
+  '0 3 * * *',
+  $$
+    SELECT net.http_post(
+      url     := 'https://<project-ref>.supabase.co/functions/v1/graph-inference',
+      headers := jsonb_build_object(
+        'Content-Type',  'application/json',
+        'Authorization', 'Bearer ' || (SELECT decrypted_secret FROM vault.decrypted_secrets WHERE name = 'graph_inference_service_role_key')
+      ),
+      body    := '{}'::jsonb
+    );
+  $$
+);
+
+-- Verify:
+-- SELECT jobname, schedule, active FROM cron.job WHERE jobname = 'graph-inference-tick';
+-- SELECT * FROM cron.job_run_details WHERE jobname = 'graph-inference-tick' ORDER BY start_time DESC LIMIT 5;