nlm-memory 0.15.0 → 0.18.0

package/dist/ports/code-exemplar-store.d.ts

@@ -7,7 +7,15 @@
  * vec lane is optional — inserts succeed without an embedding; search
  * requires one.
  */
-import type { CodeExemplar, CodeExemplarHit, CodeExemplarInput } from "../shared/types.js";
+import type { CodeExemplar, CodeExemplarHit, CodeExemplarInput, CodeExemplarOutcome } from "../shared/types.js";
+export type ExemplarVerdictSource = "llm" | "human";
+export interface ExemplarVerdictPatch {
+    readonly retired?: boolean;
+    readonly outcome?: CodeExemplarOutcome;
+}
+export interface ExemplarVerdictResult {
+    readonly status: "applied" | "not_found" | "human_locked";
+}
 export interface CodeExemplarSearchFilter {
     readonly installScope: string;
     readonly repo?: string;
@@ -42,4 +50,10 @@ export interface CodeExemplarStore {
     pruneReverted(installScope: string): Promise<number>;
     /** Delete exemplars with ts < olderThanTs (optional clock-based escape hatch). */
     pruneOlderThan(olderThanTs: string): Promise<number>;
+    /**
+     * Apply an operator/LLM verdict (retire/un-retire and/or relabel outcome).
+     * Human-wins: a `source: "llm"` call is a no-op when the row is already
+     * `label_source: "human"`. Returns the outcome so callers can surface it.
+     */
+    setVerdict(id: string, patch: ExemplarVerdictPatch, source: ExemplarVerdictSource): Promise<ExemplarVerdictResult>;
 }

package/dist/shared/types.d.ts

@@ -77,6 +77,14 @@ export interface RecallQuery {
      * via NLM_HOOK_INJECT_FACTS=false. Spec G.2.
      */
     readonly withRelatedFacts?: boolean;
+    /**
+     * If true, RecallService attaches a `relatedExemplars` array of nearest
+     * code exemplars from the CodeRankEmbed space. Allows the recall block
+     * to include concrete code examples as a third dimension alongside
+     * session pointers and facts. Off by default; the HTTP hook caller may
+     * set this true to inject code examples into the pointer block.
+     */
+    readonly withRelatedExemplars?: boolean;
     /**
      * If true, superseded sessions are included in recall results, down-ranked
      * and carrying a `supersededBy` pointer to their successor. Replaced
@@ -125,6 +133,13 @@ export interface RecallResult {
      * "Known facts" section beneath the session pointer list.
      */
     readonly relatedFacts?: ReadonlyArray<RelatedFact>;
+    /**
+     * Optional array of nearest code exemplars matched via CodeRankEmbed.
+     * Present only when the caller requested `withRelatedExemplars`.
+     * Provides concrete code examples as a third dimension of context
+     * alongside session pointers and facts.
+     */
+    readonly relatedExemplars?: ReadonlyArray<RelatedExemplar>;
 }
 /**
  * Fact — a single normalized claim derived from a session.
@@ -262,6 +277,8 @@ export interface CodeExemplarInput {
 export interface CodeExemplar extends CodeExemplarInput {
     readonly id: string;
     readonly createdAt: string;
+    readonly retiredAt: string | null;
+    readonly labelSource: "llm" | "human";
 }
 /** One result row from recall_code. */
 export interface CodeExemplarHit {
@@ -276,3 +293,16 @@ export interface CodeExemplarHit {
     readonly gitSha: string | null;
     readonly distance: number;
 }
+/**
+ * Lean pointer to a related code exemplar, returned by `pickRelatedExemplars`.
+ * Carries just the metadata needed for the recall block to reference the example
+ * without embedding the full code (which is retrieved on demand via `recall_code`).
+ */
+export interface RelatedExemplar {
+    readonly id: string;
+    readonly outcome: CodeExemplarOutcome;
+    readonly lang: string | null;
+    readonly repo: string;
+    readonly taskContext: string;
+    readonly distance: number;
+}

package/migrations/023_code_exemplars_supersedence.sql

@@ -0,0 +1,10 @@
+-- Migration 023: code_exemplars supersedence — operator/LLM verdict on exemplars.
+--
+-- retired_at: non-null = excluded from recall (the "verdict"), like facts.retired_at.
+-- label_source: who last set the verdict/outcome ('llm' at capture; 'human' on
+-- operator override). A human verdict is sticky — see CodeExemplarStore.setVerdict.
+
+ALTER TABLE code_exemplars ADD COLUMN retired_at TEXT;
+ALTER TABLE code_exemplars ADD COLUMN label_source TEXT NOT NULL DEFAULT 'llm';
+
+INSERT OR IGNORE INTO schema_migrations (version, name) VALUES (23, '023_code_exemplars_supersedence');

package/migrations/pg/001_initial.sql

@@ -237,7 +237,9 @@ CREATE TABLE IF NOT EXISTS code_exemplars (
   git_sha       TEXT,
   survived      INTEGER,
   ts            TEXT NOT NULL,
-  created_at    TEXT NOT NULL DEFAULT (now()::text)
+  created_at    TEXT NOT NULL DEFAULT (now()::text),
+  retired_at    TEXT,
+  label_source  TEXT NOT NULL DEFAULT 'llm'
 );
 CREATE INDEX IF NOT EXISTS idx_exemplars_scope_repo ON code_exemplars(install_scope, repo, outcome);
 CREATE INDEX IF NOT EXISTS idx_exemplars_ts ON code_exemplars(ts);

package/nlm/index.js

@@ -193,9 +193,9 @@ var RECALL_LIMIT = 5;
 var RECALL_TIMEOUT_MS = 2e3;
 async function recallOverHttp(prompt, runtime, conversationId) {
   const query = extractRecallQuery(prompt);
-  if (query === null) return { hits: [], facts: [] };
+  if (query === null) return { hits: [], facts: [], exemplars: [] };
   const portValue = process.env["NLM_PORT"] ?? "3940";
-  const url = `http://localhost:${portValue}/api/recall?q=${encodeURIComponent(query)}&mode=keyword&limit=${RECALL_LIMIT}&withFacts=true` + (conversationId ? `&conversation_id=${encodeURIComponent(conversationId)}` : "");
+  const url = `http://localhost:${portValue}/api/recall?q=${encodeURIComponent(query)}&mode=keyword&limit=${RECALL_LIMIT}&withFacts=true&withExemplars=true` + (conversationId ? `&conversation_id=${encodeURIComponent(conversationId)}` : "");
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), RECALL_TIMEOUT_MS);
   try {
@@ -205,12 +205,12 @@ async function recallOverHttp(prompt, runtime, conversationId) {
       headers: hookAuthHeaders(extra),
       signal: controller.signal
     });
-    if (!res.ok) return { hits: [], facts: [] };
+    if (!res.ok) return { hits: [], facts: [], exemplars: [] };
     let body;
     try {
       body = await res.json();
     } catch {
-      return { hits: [], facts: [] };
+      return { hits: [], facts: [], exemplars: [] };
     }
     const hits = (body.results ?? []).map((r) => ({
       id: r.id,
@@ -225,7 +225,13 @@ async function recallOverHttp(prompt, runtime, conversationId) {
       value: f.value,
       corroborationCount: f.corroborationCount
     }));
-    return { hits, facts };
+    const exemplars = (body.relatedExemplars ?? []).map((e) => ({
+      outcome: e.outcome,
+      lang: e.lang,
+      repo: e.repo,
+      taskContext: e.taskContext
+    }));
+    return { hits, facts, exemplars };
   } finally {
     clearTimeout(timer);
   }
@@ -295,8 +301,8 @@ function recordSurfaced(conversationId, ids) {
 }
 
 // src/core/hook/pointer-block.ts
-function formatPointerBlock(hits, facts = []) {
-  if (hits.length === 0 && facts.length === 0) return "";
+function formatPointerBlock(hits, facts = [], exemplars = []) {
+  if (hits.length === 0 && facts.length === 0 && exemplars.length === 0) return "";
   const out = [];
   if (hits.length > 0) {
     out.push("## Possibly-relevant prior sessions (nlm-memory)");
@@ -317,9 +323,16 @@ function formatPointerBlock(hits, facts = []) {
       out.push(`- ${f.subject} ${f.predicate}: ${f.value}${tag}`);
     }
   }
-  out.push(
-    "NLM tools: recall_sessions (search), get_session (full transcript), recall_facts (prior decisions), get_fact_history (how a decision evolved)."
-  );
+  if (exemplars.length > 0) {
+    if (out.length > 0) out.push("");
+    out.push("## Related code exemplars (nlm-memory)");
+    for (const e of exemplars) {
+      const langPart = e.lang ? `${e.lang} \xB7 ` : "";
+      out.push(`- [${e.outcome}] ${langPart}${e.repo} - ${e.taskContext.slice(0, 120)}`);
+    }
+  }
+  const tools = exemplars.length > 0 ? "NLM tools: recall_sessions (search), get_session (full transcript), recall_facts (prior decisions), get_fact_history (how a decision evolved), recall_code (pull the full code for a related exemplar)." : "NLM tools: recall_sessions (search), get_session (full transcript), recall_facts (prior decisions), get_fact_history (how a decision evolved).";
+  out.push(tools);
   return out.join("\n");
 }
 
@@ -378,7 +391,7 @@ async function runHook(input, deps) {
     perFireCap: PER_FIRE_CAP,
     perConversationCap: PER_CONVERSATION_CAP
   });
-  const block = formatPointerBlock(selected, fetched.facts);
+  const block = formatPointerBlock(selected, fetched.facts, fetched.exemplars);
   const estTokens = Math.ceil(block.length / 4);
   appendHookLog({
     ts: (/* @__PURE__ */ new Date()).toISOString(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nlm-memory",
-  "version": "0.15.0",
+  "version": "0.18.0",
   "description": "Local-first non-linear memory operating system for AI operators.",
   "type": "module",
   "license": "Apache-2.0",

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nlm-memory",
-  "version": "0.15.0",
+  "version": "0.18.0",
   "description": "Local-first persistent memory for AI coding agents. Recalls relevant prior sessions on every prompt; learns which sessions actually get cited. Owner-edited timeline beats append-only memory layers.",
   "author": {
     "name": "Edward Chalupa",

package/plugin/scripts/prompt-recall-hook.mjs

@@ -64,8 +64,8 @@ function recordSurfaced(conversationId, ids) {
 }
 
 // src/core/hook/pointer-block.ts
-function formatPointerBlock(hits, facts = []) {
-  if (hits.length === 0 && facts.length === 0) return "";
+function formatPointerBlock(hits, facts = [], exemplars = []) {
+  if (hits.length === 0 && facts.length === 0 && exemplars.length === 0) return "";
   const out = [];
   if (hits.length > 0) {
     out.push("## Possibly-relevant prior sessions (nlm-memory)");
@@ -86,9 +86,16 @@ function formatPointerBlock(hits, facts = []) {
       out.push(`- ${f.subject} ${f.predicate}: ${f.value}${tag}`);
     }
   }
-  out.push(
-    "NLM tools: recall_sessions (search), get_session (full transcript), recall_facts (prior decisions), get_fact_history (how a decision evolved)."
-  );
+  if (exemplars.length > 0) {
+    if (out.length > 0) out.push("");
+    out.push("## Related code exemplars (nlm-memory)");
+    for (const e of exemplars) {
+      const langPart = e.lang ? `${e.lang} \xB7 ` : "";
+      out.push(`- [${e.outcome}] ${langPart}${e.repo} - ${e.taskContext.slice(0, 120)}`);
+    }
+  }
+  const tools = exemplars.length > 0 ? "NLM tools: recall_sessions (search), get_session (full transcript), recall_facts (prior decisions), get_fact_history (how a decision evolved), recall_code (pull the full code for a related exemplar)." : "NLM tools: recall_sessions (search), get_session (full transcript), recall_facts (prior decisions), get_fact_history (how a decision evolved).";
+  out.push(tools);
   return out.join("\n");
 }
 
@@ -298,9 +305,9 @@ var RECALL_LIMIT = 5;
 var RECALL_TIMEOUT_MS = 2e3;
 async function recallOverHttp(prompt, runtime, conversationId) {
   const query = extractRecallQuery(prompt);
-  if (query === null) return { hits: [], facts: [] };
+  if (query === null) return { hits: [], facts: [], exemplars: [] };
   const portValue = process.env["NLM_PORT"] ?? "3940";
-  const url = `http://localhost:${portValue}/api/recall?q=${encodeURIComponent(query)}&mode=keyword&limit=${RECALL_LIMIT}&withFacts=true` + (conversationId ? `&conversation_id=${encodeURIComponent(conversationId)}` : "");
+  const url = `http://localhost:${portValue}/api/recall?q=${encodeURIComponent(query)}&mode=keyword&limit=${RECALL_LIMIT}&withFacts=true&withExemplars=true` + (conversationId ? `&conversation_id=${encodeURIComponent(conversationId)}` : "");
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), RECALL_TIMEOUT_MS);
   try {
@@ -310,12 +317,12 @@ async function recallOverHttp(prompt, runtime, conversationId) {
       headers: hookAuthHeaders(extra),
       signal: controller.signal
     });
-    if (!res.ok) return { hits: [], facts: [] };
+    if (!res.ok) return { hits: [], facts: [], exemplars: [] };
     let body;
     try {
       body = await res.json();
     } catch {
-      return { hits: [], facts: [] };
+      return { hits: [], facts: [], exemplars: [] };
     }
     const hits = (body.results ?? []).map((r) => ({
       id: r.id,
@@ -330,7 +337,13 @@ async function recallOverHttp(prompt, runtime, conversationId) {
       value: f.value,
       corroborationCount: f.corroborationCount
     }));
-    return { hits, facts };
+    const exemplars = (body.relatedExemplars ?? []).map((e) => ({
+      outcome: e.outcome,
+      lang: e.lang,
+      repo: e.repo,
+      taskContext: e.taskContext
+    }));
+    return { hits, facts, exemplars };
   } finally {
     clearTimeout(timer);
   }
@@ -380,7 +393,7 @@ async function runHook(input, deps) {
     perFireCap: PER_FIRE_CAP,
     perConversationCap: PER_CONVERSATION_CAP
   });
-  const block = formatPointerBlock(selected, fetched.facts);
+  const block = formatPointerBlock(selected, fetched.facts, fetched.exemplars);
   const estTokens = Math.ceil(block.length / 4);
   appendHookLog({
     ts: (/* @__PURE__ */ new Date()).toISOString(),

package/plugin/scripts/session-start-hook.mjs

@@ -53,8 +53,8 @@ function recordSurfaced(conversationId, ids) {
 }
 
 // src/core/hook/pointer-block.ts
-function formatPointerBlock(hits, facts = []) {
-  if (hits.length === 0 && facts.length === 0) return "";
+function formatPointerBlock(hits, facts = [], exemplars = []) {
+  if (hits.length === 0 && facts.length === 0 && exemplars.length === 0) return "";
   const out = [];
   if (hits.length > 0) {
     out.push("## Possibly-relevant prior sessions (nlm-memory)");
@@ -75,9 +75,16 @@ function formatPointerBlock(hits, facts = []) {
       out.push(`- ${f.subject} ${f.predicate}: ${f.value}${tag}`);
     }
   }
-  out.push(
-    "NLM tools: recall_sessions (search), get_session (full transcript), recall_facts (prior decisions), get_fact_history (how a decision evolved)."
-  );
+  if (exemplars.length > 0) {
+    if (out.length > 0) out.push("");
+    out.push("## Related code exemplars (nlm-memory)");
+    for (const e of exemplars) {
+      const langPart = e.lang ? `${e.lang} \xB7 ` : "";
+      out.push(`- [${e.outcome}] ${langPart}${e.repo} - ${e.taskContext.slice(0, 120)}`);
+    }
+  }
+  const tools = exemplars.length > 0 ? "NLM tools: recall_sessions (search), get_session (full transcript), recall_facts (prior decisions), get_fact_history (how a decision evolved), recall_code (pull the full code for a related exemplar)." : "NLM tools: recall_sessions (search), get_session (full transcript), recall_facts (prior decisions), get_fact_history (how a decision evolved).";
+  out.push(tools);
   return out.join("\n");
 }
 

package/migrations/pg/018_repair_self_supersede.sql

@@ -1,16 +0,0 @@
--- PG parity for SQLite migration 018: repair self-supersedence damage.
---
--- One-shot repair, applied manually by an operator against a PG canonical
--- store (PgStorage.init only runs 001_initial.sql, there is no version-gated
--- runner on the PG side). Mirrors migrations/018_repair_self_supersede.sql.
---
--- Removes self-loop 'supersedes' edges (id -> id) written by the unguarded
--- scan path, then restores sessions wrongly marked superseded — those left
--- without any real incoming 'supersedes' edge.
-
-DELETE FROM session_edges WHERE from_session = to_session AND kind = 'supersedes';
-
-UPDATE sessions
-SET status = 'closed', updated_at = NOW()
-WHERE status = 'superseded'
-  AND id NOT IN (SELECT to_session FROM session_edges WHERE kind = 'supersedes');

package/migrations/pg/020_collapse_duplicate_active_facts.sql

@@ -1,46 +0,0 @@
--- PG parity for SQLite migration 020: collapse duplicate active facts (#301).
---
--- One-shot repair, applied manually by an operator against a PG canonical store
--- (PgStorage.init only runs 001_initial.sql; there is no version-gated runner on
--- the PG side). Mirrors migrations/020_collapse_duplicate_active_facts.sql.
---
--- Within each conflicting (subject, predicate) group, the newest active fact
--- (created_at, then id) stays active; the older actives get superseded_by set
--- to that newest fact's id. The PG ingest path already collapsed all priors
--- set-wise, so this only repairs rows the SQLite-era single-prior loop stranded
--- in a corpus migrated to PG.
-
-BEGIN;
-
-WITH winners AS (
-  SELECT subject, predicate, id AS winner_id
-  FROM (
-    SELECT
-      subject, predicate, id,
-      ROW_NUMBER() OVER (
-        PARTITION BY subject, predicate
-        ORDER BY created_at DESC, id DESC
-      ) AS rn
-    FROM facts
-    WHERE superseded_by IS NULL
-  ) ranked
-  WHERE rn = 1
-),
-conflicts AS (
-  SELECT subject, predicate
-  FROM facts
-  WHERE superseded_by IS NULL
-  GROUP BY subject, predicate
-  HAVING COUNT(*) > 1
-)
-UPDATE facts f
-SET superseded_by = w.winner_id
-FROM winners w, conflicts c
-WHERE f.subject = w.subject
-  AND f.predicate = w.predicate
-  AND f.subject = c.subject
-  AND f.predicate = c.predicate
-  AND f.superseded_by IS NULL
-  AND f.id != w.winner_id;
-
-COMMIT;

package/migrations/pg/021_code_exemplars.sql

@@ -1,45 +0,0 @@
--- PG parity for SQLite migration 021: code_exemplars lane.
---
--- Mirrors migrations/021_code_exemplars.sql. Uses pgvector `vector(768)`
--- instead of sqlite-vec `vec0`. Applied manually by an operator.
-
-BEGIN;
-
-CREATE TABLE IF NOT EXISTS code_exemplars (
-  id            TEXT PRIMARY KEY,
-  install_scope TEXT NOT NULL,
-  signal_id     TEXT,
-  session_id    TEXT,
-  repo          TEXT NOT NULL,
-  model         TEXT NOT NULL,
-  lang          TEXT,
-  task_context  TEXT NOT NULL,
-  code          TEXT NOT NULL,
-  code_hash     TEXT NOT NULL,
-  outcome       TEXT NOT NULL CHECK (outcome IN ('pass','fail','fix','exhausted')),
-  git_sha       TEXT,
-  survived      SMALLINT,
-  ts            TEXT NOT NULL,
-  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-
-CREATE INDEX IF NOT EXISTS idx_exemplars_scope_repo
-  ON code_exemplars(install_scope, repo, outcome);
-
-CREATE INDEX IF NOT EXISTS idx_exemplars_ts
-  ON code_exemplars(ts);
-
-CREATE INDEX IF NOT EXISTS idx_exemplars_code_hash
-  ON code_exemplars(install_scope, code_hash);
-
--- Vector lane. 768 dims matches CodeRankEmbed-137M output.
-CREATE TABLE IF NOT EXISTS code_exemplars_vec (
-  exemplar_id  TEXT PRIMARY KEY,
-  embedding    vector(768) NOT NULL
-);
-
-CREATE INDEX IF NOT EXISTS code_exemplars_vec_embedding_idx
-  ON code_exemplars_vec USING ivfflat (embedding vector_l2_ops)
-  WITH (lists = 10);
-
-COMMIT;

package/migrations/pg/022_facts_retired_at.sql

@@ -1,12 +0,0 @@
--- PG parity for SQLite migration 022: facts.retired_at.
---
--- Mirrors migrations/022_facts_retired_at.sql. Distinct nullable marker for
--- operator retirement of incorrect facts (NLM #326). Recall excludes retired
--- facts; getHistory / includeSuperseded still surface them. Applied manually
--- by an operator.
-
-BEGIN;
-
-ALTER TABLE facts ADD COLUMN IF NOT EXISTS retired_at TEXT;
-
-COMMIT;