@mnemai/memory-server 0.1.0

package/dist/index.js

@@ -0,0 +1,1765 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/tools/createNode.ts
+import { z } from "zod";
+
+// ../shared-types/dist/index.js
+var MEMORY_NODE_TYPES = [
+  "preference",
+  "architecture_decision",
+  "incident",
+  "constraint",
+  "repo_landmark",
+  "tool_outcome",
+  "general"
+];
+var MEMORY_SCOPES = ["session", "project", "team"];
+var RELATION_TYPES = [
+  "supports",
+  "contradicts",
+  "depends_on",
+  "supersedes",
+  "related_to",
+  "caused_by",
+  "blocks"
+];
+
+// src/trustPolicy.ts
+var HIGH_CONFIDENCE_MIN = 0.7;
+var MAX_CONFIDENCE_WITHOUT_EVIDENCE = 0.69;
+
+// src/graph/node.ts
+import { v4 as uuidv4 } from "uuid";
+
+// src/graph/store.ts
+import initSqlJs from "sql.js";
+import { homedir } from "os";
+import { join } from "path";
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "fs";
+
+// src/retrieval/tokenize.ts
+var STOPWORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "and",
+  "or",
+  "but",
+  "in",
+  "on",
+  "at",
+  "to",
+  "for",
+  "of",
+  "as",
+  "by",
+  "is",
+  "it",
+  "be",
+  "we",
+  "you",
+  "they",
+  "this",
+  "that",
+  "with",
+  "from",
+  "are",
+  "was",
+  "were",
+  "has",
+  "have",
+  "had",
+  "not"
+]);
+var MAX_TOKENS_PER_FIELD = 256;
+function normalizeWord(raw) {
+  const w = raw.toLowerCase().replace(/[^a-z0-9_]/g, "");
+  if (w.length < 2 || STOPWORDS.has(w)) return null;
+  return w;
+}
+function tokenFrequenciesFromText(text) {
+  const out = /* @__PURE__ */ new Map();
+  const words = text.toLowerCase().split(/[\s/.,;:!?()[\]{}'"`]+/g);
+  let added = 0;
+  for (const raw of words) {
+    const w = normalizeWord(raw);
+    if (!w) continue;
+    out.set(w, (out.get(w) ?? 0) + 1);
+    added++;
+    if (added >= MAX_TOKENS_PER_FIELD) break;
+  }
+  return out;
+}
+function mergeTokenMaps(a, b) {
+  const out = new Map(a);
+  for (const [k, v] of b) {
+    out.set(k, (out.get(k) ?? 0) + v);
+  }
+  return out;
+}
+function queryTermsFromString(query) {
+  const freq = tokenFrequenciesFromText(query);
+  return [...freq.keys()];
+}
+
+// src/retrieval/tokenIndex.ts
+function replaceSearchIndexForNode(database, nodeId, content, tagsJson) {
+  deleteSearchIndexForNode(database, nodeId);
+  let tagsText = "";
+  try {
+    const tags = JSON.parse(tagsJson);
+    if (Array.isArray(tags)) {
+      tagsText = tags.filter((t) => typeof t === "string").join(" ");
+    }
+  } catch {
+    tagsText = "";
+  }
+  const contentFreq = tokenFrequenciesFromText(content);
+  const tagFreq = tokenFrequenciesFromText(tagsText);
+  const merged = mergeTokenMaps(contentFreq, tagFreq);
+  database.run("BEGIN");
+  try {
+    for (const [token, count] of merged) {
+      const tf = 1 + Math.log(1 + count);
+      database.run("INSERT INTO node_search_tokens (token, node_id, tf) VALUES (?, ?, ?)", [token, nodeId, tf]);
+    }
+    database.run("COMMIT");
+  } catch (err) {
+    database.run("ROLLBACK");
+    throw err;
+  }
+}
+function deleteSearchIndexForNode(database, nodeId) {
+  database.run("DELETE FROM node_search_tokens WHERE node_id = ?", [nodeId]);
+}
+function backfillSearchIndex(database) {
+  const stmt = database.prepare("SELECT node_id, content, tags FROM nodes");
+  while (stmt.step()) {
+    const row = stmt.getAsObject();
+    replaceSearchIndexForNode(database, row.node_id, row.content, row.tags);
+  }
+  stmt.free();
+}
+function countMemoryNodes(database) {
+  const s = database.prepare("SELECT COUNT(*) as c FROM nodes");
+  s.step();
+  const row = s.getAsObject();
+  s.free();
+  return Number(row.c ?? 0);
+}
+function documentFrequency(database, token) {
+  const s = database.prepare(
+    "SELECT COUNT(DISTINCT node_id) as df FROM node_search_tokens WHERE token = ?"
+  );
+  s.bind([token]);
+  s.step();
+  const row = s.getAsObject();
+  s.free();
+  return Math.max(0, Number(row.df ?? 0));
+}
+function computeLexicalIndexRawScores(database, queryTokens) {
+  const scores = /* @__PURE__ */ new Map();
+  if (queryTokens.length === 0) return scores;
+  const N = Math.max(1, countMemoryNodes(database));
+  const idfByToken = /* @__PURE__ */ new Map();
+  for (const t of queryTokens) {
+    const df = documentFrequency(database, t);
+    const idf = Math.log(1 + (N - df + 0.5) / (df + 0.5));
+    idfByToken.set(t, Math.max(0, idf));
+  }
+  const placeholders = queryTokens.map(() => "?").join(",");
+  const sql = `SELECT node_id, token, tf FROM node_search_tokens WHERE token IN (${placeholders})`;
+  const stmt = database.prepare(sql);
+  stmt.bind(queryTokens);
+  while (stmt.step()) {
+    const row = stmt.getAsObject();
+    const idf = idfByToken.get(row.token) ?? 0;
+    const contrib = idf * Number(row.tf ?? 0);
+    const id = row.node_id;
+    scores.set(id, (scores.get(id) ?? 0) + contrib);
+  }
+  stmt.free();
+  return scores;
+}
+function normalizeScores(raw) {
+  let max = 0;
+  for (const v of raw.values()) {
+    if (v > max) max = v;
+  }
+  const out = /* @__PURE__ */ new Map();
+  if (max <= 0) return out;
+  for (const [k, v] of raw) {
+    out.set(k, Math.min(1, v / max));
+  }
+  return out;
+}
+function searchIndexTableExists(database) {
+  const s = database.prepare(
+    "SELECT name FROM sqlite_master WHERE type='table' AND name='node_search_tokens'"
+  );
+  const ok = s.step();
+  s.free();
+  return ok;
+}
+
+// src/graph/store.ts
+var db = null;
+var dbPath = null;
+var saveTimer = null;
+var SYNC_WRITES = process.env.TENGU_MEMORY_SYNC_WRITES === "1";
+function getDbPath() {
+  const envPath = process.env.TENGU_MEMORY_DB;
+  if (envPath) return envPath;
+  const dir = join(homedir(), ".tengu");
+  mkdirSync(dir, { recursive: true });
+  return join(dir, "memory.db");
+}
+async function initDb() {
+  if (db) return db;
+  const SQL = await initSqlJs();
+  dbPath = getDbPath();
+  if (existsSync(dbPath)) {
+    const buffer = readFileSync(dbPath);
+    db = new SQL.Database(buffer);
+  } else {
+    db = new SQL.Database();
+  }
+  initSchema(db);
+  return db;
+}
+function getDb() {
+  if (!db) throw new Error("Database not initialized. Call initDb() first.");
+  return db;
+}
+function saveDb() {
+  if (!db || !dbPath) return;
+  const data = db.export();
+  const buffer = Buffer.from(data);
+  writeFileSync(dbPath, buffer);
+}
+function scheduleSave() {
+  if (SYNC_WRITES) {
+    saveDb();
+    return;
+  }
+  if (saveTimer) clearTimeout(saveTimer);
+  saveTimer = setTimeout(() => saveDb(), 500);
+}
+function flushDb() {
+  if (saveTimer) {
+    clearTimeout(saveTimer);
+    saveTimer = null;
+  }
+  saveDb();
+}
+function initSchema(database) {
+  database.run(`
+    CREATE TABLE IF NOT EXISTS nodes (
+      node_id TEXT PRIMARY KEY,
+      node_type TEXT NOT NULL,
+      content TEXT NOT NULL,
+      confidence REAL NOT NULL DEFAULT 0.5,
+      freshness_score REAL NOT NULL DEFAULT 1.0,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      source_scope TEXT NOT NULL DEFAULT 'session',
+      tags TEXT NOT NULL DEFAULT '[]',
+      metadata TEXT NOT NULL DEFAULT '{}'
+    )
+  `);
+  database.run(`
+    CREATE TABLE IF NOT EXISTS edges (
+      edge_id TEXT PRIMARY KEY,
+      from_node_id TEXT NOT NULL,
+      to_node_id TEXT NOT NULL,
+      relation_type TEXT NOT NULL,
+      weight REAL NOT NULL DEFAULT 1.0,
+      created_at INTEGER NOT NULL,
+      FOREIGN KEY (from_node_id) REFERENCES nodes(node_id) ON DELETE CASCADE,
+      FOREIGN KEY (to_node_id) REFERENCES nodes(node_id) ON DELETE CASCADE
+    )
+  `);
+  database.run(`
+    CREATE TABLE IF NOT EXISTS evidence_refs (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      node_id TEXT NOT NULL,
+      type TEXT NOT NULL,
+      uri TEXT NOT NULL,
+      label TEXT,
+      timestamp INTEGER,
+      FOREIGN KEY (node_id) REFERENCES nodes(node_id) ON DELETE CASCADE
+    )
+  `);
+  database.run("CREATE INDEX IF NOT EXISTS idx_nodes_type ON nodes(node_type)");
+  database.run("CREATE INDEX IF NOT EXISTS idx_nodes_scope ON nodes(source_scope)");
+  database.run("CREATE INDEX IF NOT EXISTS idx_nodes_freshness ON nodes(freshness_score)");
+  database.run("CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(from_node_id)");
+  database.run("CREATE INDEX IF NOT EXISTS idx_edges_to ON edges(to_node_id)");
+  database.run("CREATE INDEX IF NOT EXISTS idx_evidence_node ON evidence_refs(node_id)");
+  database.run("PRAGMA foreign_keys = ON");
+  runMigrations(database);
+  saveDb();
+}
+function readUserVersion(database) {
+  const stmt = database.prepare("PRAGMA user_version");
+  stmt.step();
+  const row = stmt.getAsObject();
+  stmt.free();
+  return Number(row.user_version ?? 0);
+}
+function setUserVersion(database, v) {
+  database.run(`PRAGMA user_version = ${v}`);
+}
+function tableColumns(database, table) {
+  const cols = /* @__PURE__ */ new Set();
+  const stmt = database.prepare(`PRAGMA table_info(${table})`);
+  while (stmt.step()) {
+    const row = stmt.getAsObject();
+    if (row.name) cols.add(row.name);
+  }
+  stmt.free();
+  return cols;
+}
+function runMigrations(database) {
+  let v = readUserVersion(database);
+  if (v < 1) {
+    const cols = tableColumns(database, "nodes");
+    if (!cols.has("review_interval_ms")) {
+      database.run(
+        "ALTER TABLE nodes ADD COLUMN review_interval_ms INTEGER NOT NULL DEFAULT 604800000"
+      );
+    }
+    if (!cols.has("next_review_at")) {
+      database.run("ALTER TABLE nodes ADD COLUMN next_review_at INTEGER");
+    }
+    if (!cols.has("last_verified_at")) {
+      database.run("ALTER TABLE nodes ADD COLUMN last_verified_at INTEGER");
+    }
+    database.run(
+      `UPDATE nodes SET next_review_at = updated_at + COALESCE(review_interval_ms, 604800000)
+       WHERE next_review_at IS NULL`
+    );
+    v = 1;
+    setUserVersion(database, v);
+  }
+  if (v < 2) {
+    database.run(`
+      CREATE TABLE IF NOT EXISTS node_search_tokens (
+        token TEXT NOT NULL,
+        node_id TEXT NOT NULL,
+        tf REAL NOT NULL,
+        PRIMARY KEY (token, node_id),
+        FOREIGN KEY (node_id) REFERENCES nodes(node_id) ON DELETE CASCADE
+      )
+    `);
+    database.run(
+      "CREATE INDEX IF NOT EXISTS idx_node_search_tokens_token ON node_search_tokens(token)"
+    );
+    database.run(`
+      CREATE TABLE IF NOT EXISTS node_embeddings (
+        node_id TEXT PRIMARY KEY,
+        model TEXT NOT NULL,
+        dims INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        vector BLOB NOT NULL,
+        FOREIGN KEY (node_id) REFERENCES nodes(node_id) ON DELETE CASCADE
+      )
+    `);
+    backfillSearchIndex(database);
+    v = 2;
+    setUserVersion(database, v);
+  }
+}
+function closeDb() {
+  flushDb();
+  if (db) {
+    db.close();
+    db = null;
+  }
+}
+
+// src/freshness/scorer.ts
+var DEFAULT_CONFIG = {
+  halfLifeMs: 7 * 24 * 60 * 60 * 1e3,
+  minScore: 0.05,
+  decayFunction: "exponential",
+  refreshBoost: 0.3
+};
+var config = { ...DEFAULT_CONFIG };
+function computeFreshness(updatedAt, now = Date.now()) {
+  const ageMs = now - updatedAt;
+  if (ageMs <= 0) return 1;
+  let score;
+  switch (config.decayFunction) {
+    case "exponential":
+      score = Math.pow(0.5, ageMs / config.halfLifeMs);
+      break;
+    case "linear":
+      score = Math.max(0, 1 - ageMs / (config.halfLifeMs * 2));
+      break;
+    case "step": {
+      const steps = Math.floor(ageMs / config.halfLifeMs);
+      score = Math.pow(0.5, steps);
+      break;
+    }
+  }
+  return Math.max(config.minScore, score);
+}
+function computeDecayedFreshness(baseFreshness, updatedAt, now = Date.now()) {
+  const boundedBase = Math.min(1, Math.max(config.minScore, baseFreshness));
+  const decay = computeFreshness(updatedAt, now);
+  return Math.max(config.minScore, Math.min(1, boundedBase * decay));
+}
+function refreshNode(nodeId) {
+  const db2 = getDb();
+  const now = Date.now();
+  const stmt = db2.prepare("SELECT freshness_score FROM nodes WHERE node_id = ?");
+  stmt.bind([nodeId]);
+  if (!stmt.step()) {
+    stmt.free();
+    return 0;
+  }
+  const row = stmt.getAsObject();
+  stmt.free();
+  const currentScore = row.freshness_score;
+  const newScore = Math.min(1, currentScore + config.refreshBoost);
+  db2.run("UPDATE nodes SET freshness_score = ?, updated_at = ? WHERE node_id = ?", [newScore, now, nodeId]);
+  scheduleSave();
+  return newScore;
+}
+
+// src/graph/node.ts
+var DEFAULT_REVIEW_INTERVAL_MS = 7 * 24 * 60 * 60 * 1e3;
+function createNode(params) {
+  const db2 = getDb();
+  const now = Date.now();
+  const nodeId = uuidv4();
+  let confidence = params.confidence ?? 0.5;
+  const hasEvidence = Boolean(params.evidenceRefs?.length);
+  if (!hasEvidence && confidence >= HIGH_CONFIDENCE_MIN) {
+    confidence = MAX_CONFIDENCE_WITHOUT_EVIDENCE;
+  }
+  const reviewIntervalMs = params.reviewIntervalMs ?? DEFAULT_REVIEW_INTERVAL_MS;
+  const nextReviewAt = now + reviewIntervalMs;
+  const tagsJson = JSON.stringify(params.tags ?? []);
+  db2.run(
+    `INSERT INTO nodes (node_id, node_type, content, confidence, freshness_score, created_at, updated_at, source_scope, tags, metadata,
+      review_interval_ms, next_review_at, last_verified_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)`,
+    [
+      nodeId,
+      params.nodeType,
+      params.content,
+      confidence,
+      1,
+      now,
+      now,
+      params.sourceScope ?? "session",
+      tagsJson,
+      JSON.stringify(params.metadata ?? {}),
+      reviewIntervalMs,
+      nextReviewAt
+    ]
+  );
+  if (searchIndexTableExists(db2)) {
+    replaceSearchIndexForNode(db2, nodeId, params.content, tagsJson);
+  }
+  if (params.evidenceRefs?.length) {
+    for (const ref of params.evidenceRefs) {
+      db2.run(
+        "INSERT INTO evidence_refs (node_id, type, uri, label, timestamp) VALUES (?, ?, ?, ?, ?)",
+        [nodeId, ref.type, ref.uri, ref.label ?? null, ref.timestamp ?? null]
+      );
+    }
+  }
+  scheduleSave();
+  return getNode(nodeId);
+}
+function getNode(nodeId) {
+  const db2 = getDb();
+  const stmt = db2.prepare("SELECT * FROM nodes WHERE node_id = ?");
+  stmt.bind([nodeId]);
+  if (!stmt.step()) {
+    stmt.free();
+    return null;
+  }
+  const row = stmt.getAsObject();
+  stmt.free();
+  const evidenceRows = queryAll(db2, "SELECT * FROM evidence_refs WHERE node_id = ?", [nodeId]);
+  return rowToNode(row, evidenceRows);
+}
+function patchNodeMetadata(nodeId, patch) {
+  const node = getNode(nodeId);
+  if (!node) return null;
+  const db2 = getDb();
+  const metadata = { ...node.metadata, ...patch };
+  db2.run("UPDATE nodes SET metadata = ?, updated_at = ? WHERE node_id = ?", [
+    JSON.stringify(metadata),
+    Date.now(),
+    nodeId
+  ]);
+  scheduleSave();
+  return getNode(nodeId);
+}
+function listNodes(params) {
+  const db2 = getDb();
+  const conditions = [];
+  const values = [];
+  if (params?.nodeType) {
+    conditions.push("node_type = ?");
+    values.push(params.nodeType);
+  }
+  if (params?.sourceScope) {
+    conditions.push("source_scope = ?");
+    values.push(params.sourceScope);
+  }
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const limit = params?.limit ?? 100;
+  const offset = params?.offset ?? 0;
+  const rows = queryAll(
+    db2,
+    `SELECT * FROM nodes ${where} ORDER BY updated_at DESC LIMIT ? OFFSET ?`,
+    [...values, limit, offset]
+  );
+  return rows.map((row) => {
+    const evidenceRows = queryAll(db2, "SELECT * FROM evidence_refs WHERE node_id = ?", [row.node_id]);
+    return rowToNode(row, evidenceRows);
+  });
+}
+function listRecentNodeIds(params) {
+  const db2 = getDb();
+  const conditions = [];
+  const values = [];
+  if (params.nodeType) {
+    conditions.push("node_type = ?");
+    values.push(params.nodeType);
+  }
+  if (params.sourceScope) {
+    conditions.push("source_scope = ?");
+    values.push(params.sourceScope);
+  }
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const rows = queryAll(
+    db2,
+    `SELECT node_id FROM nodes ${where} ORDER BY updated_at DESC LIMIT ?`,
+    [...values, params.limit]
+  );
+  return rows.map((r) => r.node_id);
+}
+function getNodesByIds(nodeIds) {
+  if (nodeIds.length === 0) return [];
+  const db2 = getDb();
+  const out = [];
+  const chunkSize = 80;
+  for (let i = 0; i < nodeIds.length; i += chunkSize) {
+    const chunk = nodeIds.slice(i, i + chunkSize);
+    const ph = chunk.map(() => "?").join(",");
+    const rows = queryAll(db2, `SELECT * FROM nodes WHERE node_id IN (${ph})`, chunk);
+    for (const row of rows) {
+      const evidenceRows = queryAll(db2, "SELECT * FROM evidence_refs WHERE node_id = ?", [row.node_id]);
+      out.push(rowToNode(row, evidenceRows));
+    }
+  }
+  return out;
+}
+function queryAll(db2, sql, params = []) {
+  const results = [];
+  const stmt = db2.prepare(sql);
+  stmt.bind(params);
+  while (stmt.step()) {
+    results.push(stmt.getAsObject());
+  }
+  stmt.free();
+  return results;
+}
+function rowToNode(row, evidenceRows) {
+  const reviewIntervalRaw = row.review_interval_ms;
+  const nextReviewRaw = row.next_review_at;
+  const lastVerifiedRaw = row.last_verified_at;
+  return {
+    nodeId: row.node_id,
+    nodeType: row.node_type,
+    content: row.content,
+    confidence: row.confidence,
+    freshnessScore: computeDecayedFreshness(row.freshness_score, row.updated_at),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    sourceScope: row.source_scope,
+    tags: JSON.parse(row.tags),
+    metadata: JSON.parse(row.metadata),
+    evidenceRefs: evidenceRows.map((e) => ({
+      type: e.type,
+      uri: e.uri,
+      label: e.label ?? void 0,
+      timestamp: e.timestamp ?? void 0
+    })),
+    reviewIntervalMs: reviewIntervalRaw != null ? Number(reviewIntervalRaw) : void 0,
+    nextReviewAt: nextReviewRaw != null ? Number(nextReviewRaw) : null,
+    lastVerifiedAt: lastVerifiedRaw != null ? Number(lastVerifiedRaw) : null
+  };
+}
+
+// src/tools/createNode.ts
+var createNodeSchema = z.object({
+  nodeType: z.enum(MEMORY_NODE_TYPES),
+  content: z.string().min(1).describe("The memory content to store"),
+  confidence: z.number().min(0).max(1).optional().describe(
+    `Initial confidence (0\u20131), default 0.5. Without evidenceRefs, values \u2265${HIGH_CONFIDENCE_MIN} are capped (RFC \xA76.3).`
+  ),
+  sourceScope: z.enum(MEMORY_SCOPES).optional().describe("Scope: session, project, or team"),
+  tags: z.array(z.string()).optional().describe("Tags for categorization"),
+  metadata: z.record(z.unknown()).optional().describe("Arbitrary metadata"),
+  evidenceRefs: z.array(z.object({
+    type: z.enum(["transcript", "tool_result", "verification", "code_anchor", "decision_record", "external"]),
+    uri: z.string(),
+    label: z.string().optional(),
+    timestamp: z.number().int().optional()
+  })).optional().describe("Evidence references backing this memory"),
+  reviewIntervalDays: z.number().min(1).max(365).optional().describe(
+    "Days until first scheduled verification (spaced review); default 7."
+  )
+});
+function handleCreateNode(args) {
+  const requestedConfidence = args.confidence ?? 0.5;
+  const hadEvidence = Boolean(args.evidenceRefs?.length);
+  const reviewIntervalMs = args.reviewIntervalDays != null ? args.reviewIntervalDays * 24 * 60 * 60 * 1e3 : void 0;
+  const node = createNode({
+    nodeType: args.nodeType,
+    content: args.content,
+    confidence: args.confidence,
+    sourceScope: args.sourceScope,
+    tags: args.tags,
+    metadata: args.metadata,
+    evidenceRefs: args.evidenceRefs,
+    reviewIntervalMs
+  });
+  const confidenceCappedForMissingEvidence = !hadEvidence && requestedConfidence >= HIGH_CONFIDENCE_MIN && node.confidence < requestedConfidence;
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(
+          {
+            node,
+            trustPolicy: { confidenceCappedForMissingEvidence }
+          },
+          null,
+          2
+        )
+      }
+    ]
+  };
+}
+
+// src/tools/queryMemory.ts
+import { z as z2 } from "zod";
+
+// src/graph/edge.ts
+import { v4 as uuidv42 } from "uuid";
+function createEdge(params) {
+  const db2 = getDb();
+  const edgeId = uuidv42();
+  const now = Date.now();
+  db2.run(
+    `INSERT INTO edges (edge_id, from_node_id, to_node_id, relation_type, weight, created_at)
+     VALUES (?, ?, ?, ?, ?, ?)`,
+    [
+      edgeId,
+      params.fromNodeId,
+      params.toNodeId,
+      params.relationType,
+      params.weight ?? 1,
+      now
+    ]
+  );
+  scheduleSave();
+  return {
+    edgeId,
+    fromNodeId: params.fromNodeId,
+    toNodeId: params.toNodeId,
+    relationType: params.relationType,
+    weight: params.weight ?? 1,
+    createdAt: now
+  };
+}
+function getEdgesForNode(nodeId) {
+  const db2 = getDb();
+  return queryEdges(db2, "SELECT * FROM edges WHERE from_node_id = ? OR to_node_id = ?", [nodeId, nodeId]);
+}
+function getContradictions(nodeId) {
+  const db2 = getDb();
+  return queryEdges(
+    db2,
+    `SELECT * FROM edges WHERE (from_node_id = ? OR to_node_id = ?) AND relation_type = 'contradicts'`,
+    [nodeId, nodeId]
+  );
+}
+function queryEdges(db2, sql, params) {
+  const results = [];
+  const stmt = db2.prepare(sql);
+  stmt.bind(params);
+  while (stmt.step()) {
+    const row = stmt.getAsObject();
+    results.push({
+      edgeId: row.edge_id,
+      fromNodeId: row.from_node_id,
+      toNodeId: row.to_node_id,
+      relationType: row.relation_type,
+      weight: row.weight,
+      createdAt: row.created_at
+    });
+  }
+  stmt.free();
+  return results;
+}
+
+// src/freshness/policy.ts
+var STALE_THRESHOLD = 0.2;
+function isStale(freshnessScore) {
+  return freshnessScore < STALE_THRESHOLD;
+}
+function hasContradictions(nodeId) {
+  return getContradictions(nodeId).length > 0;
+}
+function getStaleNodeIds() {
+  const db2 = getDb();
+  const results = [];
+  const stmt = db2.prepare("SELECT node_id, freshness_score, updated_at FROM nodes");
+  while (stmt.step()) {
+    const row = stmt.getAsObject();
+    const freshness = computeDecayedFreshness(row.freshness_score, row.updated_at);
+    if (freshness < STALE_THRESHOLD) {
+      results.push(row.node_id);
+    }
+  }
+  stmt.free();
+  return results;
+}
+function getContradictionPairs() {
+  const db2 = getDb();
+  const results = [];
+  const stmt = db2.prepare(`SELECT from_node_id, to_node_id FROM edges WHERE relation_type = 'contradicts'`);
+  while (stmt.step()) {
+    const row = stmt.getAsObject();
+    results.push({
+      nodeA: row.from_node_id,
+      nodeB: row.to_node_id
+    });
+  }
+  stmt.free();
+  return results;
+}
+function countHighConfidenceWithoutEvidence() {
+  const db2 = getDb();
+  const stmt = db2.prepare(
+    `SELECT COUNT(*) as count FROM nodes n
+     WHERE n.confidence >= ? AND NOT EXISTS (SELECT 1 FROM evidence_refs e WHERE e.node_id = n.node_id)`
+  );
+  stmt.bind([HIGH_CONFIDENCE_MIN]);
+  stmt.step();
+  const row = stmt.getAsObject();
+  stmt.free();
+  return Number(row.count);
+}
+
+// src/retrieval/ranker.ts
+var DEFAULT_WEIGHTS = {
+  relevance: 0.3,
+  freshness: 0.25,
+  evidence: 0.25,
+  salience: 0.2
+};
+var INTENT_WEIGHTS = {
+  general: DEFAULT_WEIGHTS,
+  decision_recall: { relevance: 0.25, freshness: 0.2, evidence: 0.35, salience: 0.2 },
+  incident_triage: { relevance: 0.35, freshness: 0.35, evidence: 0.2, salience: 0.1 },
+  preference_personalization: { relevance: 0.35, freshness: 0.2, evidence: 0.15, salience: 0.3 }
+};
+function parseEnvWeight(name, fallback) {
+  const v = process.env[name];
+  if (v == null || v === "") return fallback;
+  const n = Number(v);
+  if (!Number.isFinite(n) || n < 0) return fallback;
+  return n;
+}
+function matchBlendWeights(useSemantic) {
+  let lex = parseEnvWeight("TENGU_MEMORY_MATCH_LEXICAL", 0.35);
+  let idx = parseEnvWeight("TENGU_MEMORY_MATCH_INDEX", 0.45);
+  let sem = parseEnvWeight("TENGU_MEMORY_MATCH_SEMANTIC", 0.2);
+  if (!useSemantic) {
+    const total = lex + idx;
+    if (total <= 0) return { lex: 0.55, idx: 0.45, sem: 0 };
+    return { lex: lex / total, idx: idx / total, sem: 0 };
+  }
+  const t = lex + idx + sem;
+  if (t <= 0) return { lex: 0.35, idx: 0.45, sem: 0.2 };
+  return { lex: lex / t, idx: idx / t, sem: sem / t };
+}
+function rankNodes(nodes, queryTerms, weights = {}, intent = "general", hybrid) {
+  const w = { ...INTENT_WEIGHTS[intent], ...weights };
+  const nodeById = new Map(nodes.map((n) => [n.nodeId, n]));
+  const useSemantic = Boolean(hybrid?.useSemanticInBlend && hybrid.semanticMatchByNodeId);
+  const blend = matchBlendWeights(useSemantic);
+  const indexActive = Boolean(hybrid?.indexMatchByNodeId != null && queryTerms.length > 0);
+  let wLex = blend.lex;
+  let wIdx = indexActive ? blend.idx : 0;
+  let wSem = useSemantic ? blend.sem : 0;
+  let sumChannels = wLex + wIdx + wSem;
+  if (sumChannels <= 0) {
+    wLex = 1;
+    wIdx = 0;
+    wSem = 0;
+    sumChannels = 1;
+  }
+  const nLex = wLex / sumChannels;
+  const nIdx = wIdx / sumChannels;
+  const nSem = wSem / sumChannels;
+  const results = nodes.map((node) => {
+    const substringScore = computeMatchScore(node, queryTerms);
+    const idxScore = hybrid?.indexMatchByNodeId?.get(node.nodeId) ?? 0;
+    const semScore = hybrid?.semanticMatchByNodeId?.get(node.nodeId) ?? 0;
+    const matchScore = nLex * substringScore + nIdx * idxScore + nSem * semScore;
+    const edges = getEdgesForNode(node.nodeId);
+    const conflict = computeConflict(node, edges, nodeById);
+    const evidenceQualityScore = computeEvidenceQualityScore(node, conflict.hasConflict);
+    const salienceScore = computeSalienceScore(node);
+    const evidenceStrength = evidenceQualityScore;
+    const compositeScore = matchScore * w.relevance + node.freshnessScore * w.freshness + evidenceStrength * w.evidence + salienceScore * w.salience;
+    const out = {
+      node,
+      matchScore,
+      compositeScore,
+      freshnessScore: node.freshnessScore,
+      evidenceStrength,
+      salienceScore,
+      evidenceQualityScore,
+      conflict,
+      edges
+    };
+    if (indexActive) out.indexMatchScore = idxScore;
+    if (useSemantic) out.semanticMatchScore = semScore;
+    return out;
+  });
+  results.sort((a, b) => b.compositeScore - a.compositeScore);
+  return results;
+}
+function computeMatchScore(node, queryTerms) {
+  if (queryTerms.length === 0) return 0.5;
+  const content = node.content.toLowerCase();
+  const tags = node.tags.map((t) => t.toLowerCase());
+  let matchCount = 0;
+  for (const term of queryTerms) {
+    const lower = term.toLowerCase();
+    if (content.includes(lower)) matchCount++;
+    if (tags.some((t) => t.includes(lower))) matchCount += 0.5;
+  }
+  return Math.min(1, matchCount / queryTerms.length);
+}
+function computeEvidenceQualityScore(node, hasConflict) {
+  if (node.evidenceRefs.length === 0) return 0;
+  const now = Date.now();
+  const weighted = node.evidenceRefs.map((ref) => {
+    const typeWeight = evidenceTypeWeight(ref.type);
+    const ts = ref.timestamp ?? now;
+    const ageDays = Math.max(0, (now - ts) / (1e3 * 60 * 60 * 24));
+    const recencyWeight = 1 / (1 + ageDays / 30);
+    return typeWeight * recencyWeight;
+  });
+  const avg = weighted.reduce((sum, v) => sum + v, 0) / weighted.length;
+  const volume = Math.min(1, node.evidenceRefs.length / 5);
+  const base = Math.min(1, avg * 0.7 + volume * 0.3);
+  return hasConflict ? base * 0.85 : base;
+}
+function evidenceTypeWeight(type) {
+  switch (type) {
+    case "verification":
+      return 1;
+    case "decision_record":
+      return 0.95;
+    case "tool_result":
+      return 0.85;
+    case "code_anchor":
+      return 0.8;
+    case "transcript":
+      return 0.65;
+    case "external":
+      return 0.6;
+    default:
+      return 0.5;
+  }
+}
+function computeSalienceScore(node) {
+  const metadata = node.metadata ?? {};
+  const reaffirmationCount = Number(metadata.reaffirmationCount ?? 0);
+  const outcomeImpact = Number(metadata.outcomeImpact ?? 0);
+  const userCorrected = Boolean(metadata.userCorrected);
+  let score = 0.2;
+  if (node.nodeType === "architecture_decision" || node.nodeType === "constraint" || node.nodeType === "incident") {
+    score += 0.2;
+  }
+  if (node.tags.some((tag) => ["critical", "decision", "incident", "blocker"].includes(tag.toLowerCase()))) {
+    score += 0.15;
+  }
+  if (userCorrected) {
+    score += 0.2;
+  }
+  score += Math.min(0.2, reaffirmationCount * 0.05);
+  score += Math.min(0.25, Math.max(0, outcomeImpact) * 0.25);
+  return Math.min(1, score);
+}
+function computeConflict(node, edges, nodeById) {
+  const contradicting = edges.filter((e) => e.relationType === "contradicts");
+  if (contradicting.length === 0) {
+    return { hasConflict: false, status: "none" };
+  }
+  let strongestOpponentScore = -1;
+  let winnerNodeId;
+  const selfScore = node.confidence * node.freshnessScore * Math.max(0.1, computeEvidenceQualityScore(node, false));
+  for (const edge of contradicting) {
+    const otherId = edge.fromNodeId === node.nodeId ? edge.toNodeId : edge.fromNodeId;
+    const other = nodeById.get(otherId);
+    if (!other) continue;
+    const otherScore = other.confidence * other.freshnessScore * Math.max(0.1, computeEvidenceQualityScore(other, false)) * edge.weight;
+    if (otherScore > strongestOpponentScore) {
+      strongestOpponentScore = otherScore;
+      winnerNodeId = otherId;
+    }
+  }
+  if (strongestOpponentScore < 0) {
+    return { hasConflict: true, status: "contested" };
+  }
+  const delta = Math.abs(selfScore - strongestOpponentScore);
+  if (delta < 0.1) {
+    return { hasConflict: true, status: "contested", winnerNodeId, confidenceDelta: Number(delta.toFixed(3)) };
+  }
+  const selfWins = selfScore > strongestOpponentScore;
+  return {
+    hasConflict: true,
+    status: "resolved",
+    winnerNodeId: selfWins ? node.nodeId : winnerNodeId,
+    confidenceDelta: Number(delta.toFixed(3))
+  };
+}
+
+// src/retrieval/embedding.ts
+var DEFAULT_MODEL = "text-embedding-3-small";
+function isEmbeddingsConfigured() {
+  return Boolean(process.env.TENGU_MEMORY_EMBED_URL?.trim() && process.env.TENGU_MEMORY_EMBED_KEY?.trim());
+}
+function getEmbeddingModel() {
+  return process.env.TENGU_MEMORY_EMBED_MODEL?.trim() || DEFAULT_MODEL;
+}
+async function embedText(text) {
+  if (!isEmbeddingsConfigured()) return null;
+  const url = process.env.TENGU_MEMORY_EMBED_URL.trim();
+  const key = process.env.TENGU_MEMORY_EMBED_KEY.trim();
+  const model = getEmbeddingModel();
+  const body = JSON.stringify({ model, input: text.slice(0, 8e3) });
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${key}`
+    },
+    body
+  });
+  if (!res.ok) {
+    const err = await res.text().catch(() => res.statusText);
+    throw new Error(`embedding_http_${res.status}: ${err.slice(0, 500)}`);
+  }
+  const json = await res.json();
+  const vec = json.data?.[0]?.embedding;
+  if (!vec?.length) return null;
+  return Float32Array.from(vec);
+}
+function cosineSimilarity(a, b) {
+  if (a.length !== b.length || a.length === 0) return 0;
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  const denom = Math.sqrt(na) * Math.sqrt(nb);
+  if (denom <= 0) return 0;
+  return Math.max(0, Math.min(1, dot / denom));
+}
+function embeddingsTableExists(database) {
+  const s = database.prepare(
+    "SELECT name FROM sqlite_master WHERE type='table' AND name='node_embeddings'"
+  );
+  const ok = s.step();
+  s.free();
+  return ok;
+}
+function upsertNodeEmbedding(database, nodeId, vector) {
+  const model = getEmbeddingModel();
+  const now = Date.now();
+  const u8 = new Uint8Array(vector.buffer, vector.byteOffset, vector.byteLength);
+  database.run(
+    "REPLACE INTO node_embeddings (node_id, model, dims, updated_at, vector) VALUES (?, ?, ?, ?, ?)",
+    [nodeId, model, vector.length, now, u8]
+  );
+  scheduleSave();
+}
+function loadEmbeddingsForNodes(nodeIds) {
+  const out = /* @__PURE__ */ new Map();
+  if (nodeIds.length === 0) return out;
+  const database = getDb();
+  if (!embeddingsTableExists(database)) return out;
+  const chunkSize = 80;
+  for (let i = 0; i < nodeIds.length; i += chunkSize) {
+    const chunk = nodeIds.slice(i, i + chunkSize);
+    const ph = chunk.map(() => "?").join(",");
+    const stmt = database.prepare(`SELECT node_id, vector, dims FROM node_embeddings WHERE node_id IN (${ph})`);
+    stmt.bind(chunk);
+    while (stmt.step()) {
+      const row = stmt.getAsObject();
+      const raw = row.vector;
+      if (!raw || !(raw instanceof Uint8Array)) continue;
+      const buf = Buffer.from(raw);
+      const dims = Number(row.dims);
+      if (buf.length < dims * 4) continue;
+      out.set(row.node_id, new Float32Array(buf.buffer, buf.byteOffset, dims));
+    }
+    stmt.free();
+  }
+  return out;
+}
+
+// src/retrieval/candidateSelection.ts
+function parseNonNegativeInt(raw, fallback) {
+  if (raw == null || raw === "") return fallback;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 0) return fallback;
+  return n;
+}
+function parseQueryRetrievalBudget() {
+  return {
+    fullScanMaxNodes: parseNonNegativeInt(process.env.TENGU_MEMORY_QUERY_FULL_SCAN_MAX_NODES, 1600),
+    indexCandidateCapFloor: Math.max(1, parseNonNegativeInt(process.env.TENGU_MEMORY_QUERY_INDEX_CANDIDATE_CAP, 600)),
+    recentSeedSize: parseNonNegativeInt(process.env.TENGU_MEMORY_QUERY_RECENT_SEED, 200)
+  };
+}
+function effectiveIndexHitCap(limit, capFloor) {
+  return Math.max(capFloor, limit * 25);
+}
+function selectIndexHitNodeIds(rawScores, cap) {
+  if (rawScores.size <= cap) {
+    return [...rawScores.keys()];
+  }
+  return [...rawScores.entries()].sort((a, b) => b[1] - a[1]).slice(0, cap).map(([id]) => id);
+}
+function mergeCandidateNodeIds(indexIds, recentIds) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const id of indexIds) {
+    const k = String(id);
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push(id);
+  }
+  for (const id of recentIds) {
+    const k = String(id);
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push(id);
+  }
+  return out;
+}
+
+// src/retrieval/query.ts
+function filterNodesByParams(nodes, params) {
+  return nodes.filter((n) => {
+    if (params.nodeType && n.nodeType !== params.nodeType) return false;
+    if (params.sourceScope && n.sourceScope !== params.sourceScope) return false;
+    return true;
+  });
+}
+async function queryMemory(params) {
+  const db2 = getDb();
+  const queryTerms = queryTermsFromString(params.query);
+  const budget = parseQueryRetrievalBudget();
+  const totalNodes = countMemoryNodes(db2);
+  const indexWanted = params.useLexicalIndex !== false && searchIndexTableExists(db2) && queryTerms.length > 0;
+  const rawIndex = indexWanted ? computeLexicalIndexRawScores(db2, queryTerms) : /* @__PURE__ */ new Map();
+  const indexNorm = indexWanted && rawIndex.size > 0 ? normalizeScores(rawIndex) : void 0;
+  const limit = params.limit ?? 20;
+  const useIndexedCandidates = params.forceFullScan !== true && indexWanted && rawIndex.size > 0 && (budget.fullScanMaxNodes === 0 || totalNodes > budget.fullScanMaxNodes);
+  let nodes;
+  if (!useIndexedCandidates) {
+    nodes = fetchAllNodes(params);
+  } else {
+    const cap = effectiveIndexHitCap(limit, budget.indexCandidateCapFloor);
+    const indexIds = selectIndexHitNodeIds(rawIndex, cap);
+    const recentIds = listRecentNodeIds({
+      nodeType: params.nodeType,
+      sourceScope: params.sourceScope,
+      limit: budget.recentSeedSize
+    });
+    const mergedIds = mergeCandidateNodeIds(indexIds, recentIds);
+    nodes = filterNodesByParams(getNodesByIds(mergedIds), params);
+    if (nodes.length === 0) {
+      nodes = fetchAllNodes(params);
+    }
+  }
+  const filtered = nodes.filter((node) => {
+    if (!params.includeStale && isStale(node.freshnessScore)) {
+      return false;
+    }
+    if (params.minFreshness !== void 0 && node.freshnessScore < params.minFreshness) {
+      return false;
+    }
+    if (params.minConfidence !== void 0 && node.confidence < params.minConfidence) {
+      return false;
+    }
+    return true;
+  });
+  let semanticByNode;
+  let useSemanticInBlend = false;
+  if (params.useSemantic !== false && isEmbeddingsConfigured()) {
+    try {
+      const qEmb = await embedText(params.query);
+      if (qEmb) {
+        semanticByNode = /* @__PURE__ */ new Map();
+        const embMap = loadEmbeddingsForNodes(filtered.map((n) => n.nodeId));
+        for (const n of filtered) {
+          const v = embMap.get(n.nodeId);
+          semanticByNode.set(n.nodeId, v ? cosineSimilarity(qEmb, v) : 0);
+        }
+        useSemanticInBlend = true;
+      }
+    } catch {
+    }
+  }
+  const ranked = rankNodes(
+    filtered,
+    queryTerms,
+    {},
+    params.intent ?? "general",
+    {
+      indexMatchByNodeId: indexNorm,
+      semanticMatchByNodeId: semanticByNode,
+      useSemanticInBlend
+    }
+  );
+  return ranked.slice(0, limit);
+}
+function fetchAllNodes(params) {
+  const pageSize = 500;
+  const all = [];
+  let offset = 0;
+  while (true) {
+    const page = listNodes({
+      nodeType: params.nodeType,
+      sourceScope: params.sourceScope,
+      limit: pageSize,
+      offset
+    });
+    all.push(...page);
+    if (page.length < pageSize) break;
+    offset += pageSize;
+  }
+  return all;
+}
+
+// src/tools/queryMemory.ts
+var queryMemorySchema = z2.object({
+  query: z2.string().min(1).describe("Search query \u2014 keywords or natural language"),
+  nodeType: z2.enum(MEMORY_NODE_TYPES).optional().describe("Filter by memory type"),
+  sourceScope: z2.enum(MEMORY_SCOPES).optional().describe("Filter by scope"),
+  limit: z2.number().min(1).max(100).optional().describe("Max results, default 20"),
+  includeStale: z2.boolean().optional().describe("Include stale memories, default false"),
+  minFreshness: z2.number().min(0).max(1).optional().describe("Min freshness score"),
+  minConfidence: z2.number().min(0).max(1).optional().describe("Min confidence score"),
+  intent: z2.enum(["general", "decision_recall", "incident_triage", "preference_personalization"]).optional().describe("Retrieval profile for weighting and ranking behavior"),
+  useLexicalIndex: z2.boolean().optional().describe(
+    "Include BM25-style portable token index in hybrid rank (default true when index exists)."
+  ),
+  useSemantic: z2.boolean().optional().describe(
+    "Allow query-time embedding call when TENGU_MEMORY_EMBED_* is configured (default true)."
+  ),
+  fullScan: z2.boolean().optional().describe(
+    "Load the entire filtered graph for ranking (slower, strongest recall). Default uses index-bounded candidates when the graph is larger than TENGU_MEMORY_QUERY_FULL_SCAN_MAX_NODES."
+  )
+});
+async function handleQueryMemory(args) {
+  const results = await queryMemory({
+    query: args.query,
+    nodeType: args.nodeType,
+    sourceScope: args.sourceScope,
+    limit: args.limit,
+    includeStale: args.includeStale ?? false,
+    minFreshness: args.minFreshness,
+    minConfidence: args.minConfidence,
+    intent: args.intent,
+    useLexicalIndex: args.useLexicalIndex,
+    useSemantic: args.useSemantic,
+    forceFullScan: args.fullScan
+  });
+  const enriched = results.map((r) => ({
+    ...r,
+    flags: {
+      stale: isStale(r.node.freshnessScore),
+      contradicted: hasContradictions(r.node.nodeId),
+      hasEvidence: r.node.evidenceRefs.length > 0
+    }
+  }));
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ count: enriched.length, results: enriched }, null, 2)
+      }
+    ]
+  };
+}
+
+// src/tools/addEdge.ts
+import { z as z3 } from "zod";
+var addEdgeSchema = z3.object({
+  fromNodeId: z3.string().describe("Source node ID"),
+  toNodeId: z3.string().describe("Target node ID"),
+  relationType: z3.enum(RELATION_TYPES).describe("Relationship type between nodes"),
+  weight: z3.number().min(0).max(1).optional().describe("Edge weight (0-1), default 1.0")
+});
+function handleAddEdge(args) {
+  const fromNode = getNode(args.fromNodeId);
+  if (!fromNode) {
+    return {
+      content: [{ type: "text", text: `Error: source node ${args.fromNodeId} not found` }],
+      isError: true
+    };
+  }
+  const toNode = getNode(args.toNodeId);
+  if (!toNode) {
+    return {
+      content: [{ type: "text", text: `Error: target node ${args.toNodeId} not found` }],
+      isError: true
+    };
+  }
+  const edge = createEdge({
+    fromNodeId: args.fromNodeId,
+    toNodeId: args.toNodeId,
+    relationType: args.relationType,
+    weight: args.weight
+  });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(edge, null, 2)
+      }
+    ]
+  };
+}
+
+// src/tools/attachEvidence.ts
+import { z as z4 } from "zod";
+
+// src/graph/evidence.ts
+function attachEvidence(nodeId, refs) {
+  const db2 = getDb();
+  const now = Date.now();
+  for (const ref of refs) {
+    db2.run(
+      "INSERT INTO evidence_refs (node_id, type, uri, label, timestamp) VALUES (?, ?, ?, ?, ?)",
+      [nodeId, ref.type, ref.uri, ref.label ?? null, ref.timestamp ?? now]
+    );
+  }
+  db2.run(
+    "UPDATE nodes SET updated_at = ?, confidence = MIN(1.0, confidence + 0.1) WHERE node_id = ?",
+    [now, nodeId]
+  );
+  scheduleSave();
+  return getEvidenceForNode(nodeId);
+}
+function getEvidenceForNode(nodeId) {
+  const db2 = getDb();
+  const results = [];
+  const stmt = db2.prepare("SELECT * FROM evidence_refs WHERE node_id = ?");
+  stmt.bind([nodeId]);
+  while (stmt.step()) {
+    const row = stmt.getAsObject();
+    results.push({
+      type: row.type,
+      uri: row.uri,
+      label: row.label ?? void 0,
+      timestamp: row.timestamp ?? void 0
+    });
+  }
+  stmt.free();
+  return results;
+}
+
+// src/tools/attachEvidence.ts
+var attachEvidenceSchema = z4.object({
+  nodeId: z4.string().describe("Node ID to attach evidence to"),
+  evidenceRefs: z4.array(z4.object({
+    type: z4.enum(["transcript", "tool_result", "verification", "code_anchor", "decision_record", "external"]),
+    uri: z4.string(),
+    label: z4.string().optional(),
+    timestamp: z4.number().int().optional()
+  })).min(1).describe("Evidence references to attach")
+});
+function handleAttachEvidence(args) {
+  const node = getNode(args.nodeId);
+  if (!node) {
+    return {
+      content: [{ type: "text", text: `Error: node ${args.nodeId} not found` }],
+      isError: true
+    };
+  }
+  const allEvidence = attachEvidence(args.nodeId, args.evidenceRefs);
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          nodeId: args.nodeId,
+          totalEvidenceCount: allEvidence.length,
+          attached: args.evidenceRefs.length,
+          evidence: allEvidence
+        }, null, 2)
+      }
+    ]
+  };
+}
+
+// src/tools/refreshNode.ts
+import { z as z5 } from "zod";
+var refreshNodeSchema = z5.object({
+  nodeId: z5.string().describe("Node ID to refresh/reaffirm"),
+  reaffirmationNote: z5.string().max(2e3).optional().describe("Optional provenance text for this explicit reaffirmation (RFC \xA77.2). Stored in node metadata.")
+});
+function handleRefreshNode(args) {
+  const node = getNode(args.nodeId);
+  if (!node) {
+    return {
+      content: [{ type: "text", text: `Error: node ${args.nodeId} not found` }],
+      isError: true
+    };
+  }
+  const previousFreshness = node.freshnessScore;
+  const newFreshness = refreshNode(args.nodeId);
+  const note = args.reaffirmationNote?.trim();
+  if (note) {
+    patchNodeMetadata(args.nodeId, {
+      lastReaffirmationNote: note,
+      lastReaffirmationAt: Date.now()
+    });
+  }
+  const reaffirmedNode = patchNodeMetadata(args.nodeId, {
+    reaffirmationCount: Number(node.metadata.reaffirmationCount ?? 0) + 1,
+    lastReaffirmationAt: Date.now()
+  });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          nodeId: args.nodeId,
+          previousFreshness,
+          newFreshness,
+          boosted: newFreshness > previousFreshness,
+          reaffirmationRecorded: Boolean(note),
+          reaffirmationCount: Number(reaffirmedNode?.metadata.reaffirmationCount ?? 0)
+        }, null, 2)
+      }
+    ]
+  };
+}
+
+// src/tools/getStats.ts
+function firstRow(db2, sql, bind = []) {
+  const stmt = db2.prepare(sql);
+  stmt.bind(bind);
+  if (!stmt.step()) {
+    stmt.free();
+    return null;
+  }
+  const row = stmt.getAsObject();
+  stmt.free();
+  return row;
+}
+function handleGetStats() {
+  const db2 = getDb();
+  const totalNodes = Number(firstRow(db2, "SELECT COUNT(*) as count FROM nodes")?.count ?? 0);
+  const totalEdges = Number(firstRow(db2, "SELECT COUNT(*) as count FROM edges")?.count ?? 0);
+  const nodesByType = {};
+  for (const nodeType of MEMORY_NODE_TYPES) {
+    const row = firstRow(db2, "SELECT COUNT(*) as count FROM nodes WHERE node_type = ?", [nodeType]);
+    nodesByType[nodeType] = Number(row?.count ?? 0);
+  }
+  const nodesByScope = {};
+  for (const scope of MEMORY_SCOPES) {
+    const row = firstRow(db2, "SELECT COUNT(*) as count FROM nodes WHERE source_scope = ?", [scope]);
+    nodesByScope[scope] = Number(row?.count ?? 0);
+  }
+  const avgFreshness = totalNodes > 0 ? Number(firstRow(db2, "SELECT AVG(freshness_score) as avg FROM nodes")?.avg ?? 0) : 0;
+  const avgConfidence = totalNodes > 0 ? Number(firstRow(db2, "SELECT AVG(confidence) as avg FROM nodes")?.avg ?? 0) : 0;
+  const lexicalIndexRowCount = Number(
+    firstRow(db2, "SELECT COUNT(*) as count FROM node_search_tokens")?.count ?? 0
+  );
+  const embeddedNodeCount = Number(
+    firstRow(db2, "SELECT COUNT(*) as count FROM node_embeddings")?.count ?? 0
+  );
+  const stats = {
+    totalNodes,
+    totalEdges,
+    nodesByType,
+    nodesByScope,
+    averageFreshness: Math.round(avgFreshness * 1e3) / 1e3,
+    averageConfidence: Math.round(avgConfidence * 1e3) / 1e3,
+    staleNodeCount: getStaleNodeIds().length,
+    contradictionCount: getContradictionPairs().length,
+    highConfidenceWithoutEvidenceCount: countHighConfidenceWithoutEvidence(),
+    lexicalIndexRowCount,
+    embeddedNodeCount
+  };
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(stats, null, 2)
+      }
+    ]
+  };
+}
+
+// src/tools/listReviewQueue.ts
+import { z as z6 } from "zod";
+
+// src/graph/review.ts
+var MAX_REVIEW_INTERVAL_MS = 365 * 24 * 60 * 60 * 1e3;
+function queryAll2(db2, sql, params = []) {
+  const results = [];
+  const stmt = db2.prepare(sql);
+  stmt.bind(params);
+  while (stmt.step()) {
+    results.push(stmt.getAsObject());
+  }
+  stmt.free();
+  return results;
+}
+function listReviewQueue(params) {
+  const db2 = getDb();
+  const asOf = params.asOf ?? Date.now();
+  const conditions = ["next_review_at IS NOT NULL"];
+  const values = [];
+  if (params.overdueOnly) {
+    conditions.push("next_review_at <= ?");
+    values.push(asOf);
+  }
+  if (params.sourceScope) {
+    conditions.push("source_scope = ?");
+    values.push(params.sourceScope);
+  }
+  const where = conditions.join(" AND ");
+  const sql = `SELECT node_id FROM nodes WHERE ${where} ORDER BY next_review_at ASC LIMIT ?`;
+  values.push(params.limit);
+  const rows = queryAll2(db2, sql, values);
+  const out = [];
+  for (const r of rows) {
+    const n = getNode(r.node_id);
+    if (n) out.push(n);
+  }
+  return out;
+}
+function verifyNode(nodeId, note) {
+  const node = getNode(nodeId);
+  if (!node) return null;
+  const db2 = getDb();
+  const now = Date.now();
+  const currentInterval = node.reviewIntervalMs ?? 7 * 24 * 60 * 60 * 1e3;
+  const nextInterval = Math.min(MAX_REVIEW_INTERVAL_MS, currentInterval * 2);
+  db2.run(
+    `UPDATE nodes SET last_verified_at = ?, review_interval_ms = ?, next_review_at = ?, updated_at = ?
+     WHERE node_id = ?`,
+    [now, nextInterval, now + nextInterval, now, nodeId]
+  );
+  scheduleSave();
+  refreshNode(nodeId);
+  if (note?.trim()) {
+    patchNodeMetadata(nodeId, {
+      lastVerificationNote: note.trim(),
+      lastVerificationAt: now
+    });
+  }
+  return getNode(nodeId);
+}
+
+// src/tools/listReviewQueue.ts
+var listReviewQueueSchema = z6.object({
+  limit: z6.number().min(1).max(200).optional().describe("Max nodes to return, default 50"),
+  overdueOnly: z6.boolean().optional().describe("Only nodes with next_review_at <= now (default false = upcoming queue sorted soonest)"),
+  asOf: z6.number().int().optional().describe("Reference time (ms epoch); default Date.now()"),
+  sourceScope: z6.enum(MEMORY_SCOPES).optional().describe("Filter by session / project / team")
+});
+function handleListReviewQueue(args) {
+  const nodes = listReviewQueue({
+    limit: args.limit ?? 50,
+    overdueOnly: args.overdueOnly ?? false,
+    asOf: args.asOf,
+    sourceScope: args.sourceScope
+  });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ count: nodes.length, nodes }, null, 2)
+      }
+    ]
+  };
+}
+
+// src/tools/verifyNode.ts
+import { z as z7 } from "zod";
+var verifyNodeToolSchema = z7.object({
+  nodeId: z7.string().min(1).describe("Memory node to mark verified"),
+  note: z7.string().max(2e3).optional().describe("Optional verification note (stored in metadata)")
+});
+function handleVerifyNode(args) {
+  const updated = verifyNode(args.nodeId, args.note);
+  if (!updated) {
+    return {
+      content: [{ type: "text", text: `Error: node ${args.nodeId} not found` }],
+      isError: true
+    };
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(
+          {
+            node: updated,
+            nextReviewAt: updated.nextReviewAt,
+            reviewIntervalMs: updated.reviewIntervalMs
+          },
+          null,
+          2
+        )
+      }
+    ]
+  };
+}
+
+// src/tools/embedNode.ts
+import { z as z8 } from "zod";
+var embedNodeSchema = z8.object({
+  nodeId: z8.string().min(1).describe("Node whose content + tags will be embedded and stored")
+});
+async function handleEmbedNode(args) {
+  if (!isEmbeddingsConfigured()) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: "embeddings_not_configured",
+            hint: "Set TENGU_MEMORY_EMBED_URL (OpenAI-compatible embeddings endpoint), TENGU_MEMORY_EMBED_KEY, and optionally TENGU_MEMORY_EMBED_MODEL."
+          }, null, 2)
+        }
+      ],
+      isError: true
+    };
+  }
+  const node = getNode(args.nodeId);
+  if (!node) {
+    return {
+      content: [{ type: "text", text: `Error: node ${args.nodeId} not found` }],
+      isError: true
+    };
+  }
+  const db2 = getDb();
+  if (!embeddingsTableExists(db2)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ error: "embeddings_table_missing", hint: "Re-open DB to run migrations." }, null, 2)
+        }
+      ],
+      isError: true
+    };
+  }
+  const text = `${node.content}
+${node.tags.join(" ")}`.slice(0, 8e3);
+  try {
+    const vec = await embedText(text);
+    if (!vec) {
+      return {
+        content: [{ type: "text", text: JSON.stringify({ error: "empty_embedding_response" }, null, 2) }],
+        isError: true
+      };
+    }
+    const dims = vec.length;
+    upsertNodeEmbedding(db2, node.nodeId, vec);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ nodeId: node.nodeId, dims, ok: true }, null, 2)
+        }
+      ]
+    };
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    return {
+      content: [{ type: "text", text: JSON.stringify({ error: "embed_failed", message }, null, 2) }],
+      isError: true
+    };
+  }
+}
+
+// src/index.ts
+var server = new McpServer({
+  name: "mnemai-memory",
+  version: "0.1.0"
+});
+server.tool(
+  "memory.create_node",
+  "Create a typed memory node with content, scope, and optional evidence links",
+  createNodeSchema.shape,
+  async (args) => handleCreateNode(args)
+);
+server.tool(
+  "memory.query",
+  "Retrieve ranked memory nodes by hybrid lexical (substring + BM25-style token index) and optional embeddings, plus freshness and evidence strength",
+  queryMemorySchema.shape,
+  async (args) => handleQueryMemory(args)
+);
+server.tool(
+  "memory.add_edge",
+  "Create a typed relationship (supports, contradicts, depends_on, etc.) between two memory nodes",
+  addEdgeSchema.shape,
+  async (args) => handleAddEdge(args)
+);
+server.tool(
+  "memory.attach_evidence",
+  "Attach evidence references (transcript, tool result, code anchor, etc.) to an existing memory node",
+  attachEvidenceSchema.shape,
+  async (args) => handleAttachEvidence(args)
+);
+server.tool(
+  "memory.refresh",
+  "Reaffirm a memory node (explicit reaffirmation per RFC \xA77.2), boosting freshness; optional reaffirmationNote for provenance",
+  refreshNodeSchema.shape,
+  async (args) => handleRefreshNode(args)
+);
+server.tool(
+  "memory.stats",
+  "Get memory graph statistics: node counts by type/scope, freshness distribution, contradictions",
+  {},
+  async () => handleGetStats()
+);
+server.tool(
+  "memory.list_review_queue",
+  "List memory nodes scheduled for spaced verification (next_review_at), overdue or full upcoming queue",
+  listReviewQueueSchema.shape,
+  async (args) => handleListReviewQueue(args)
+);
+server.tool(
+  "memory.verify_node",
+  "Mark a memory as verified: doubles review interval (capped), schedules next_review_at, boosts freshness",
+  verifyNodeToolSchema.shape,
+  async (args) => handleVerifyNode(args)
+);
+server.tool(
+  "memory.embed_node",
+  "Store an embedding vector for a node (requires TENGU_MEMORY_EMBED_URL + TENGU_MEMORY_EMBED_KEY); enables semantic channel in memory.query",
+  embedNodeSchema.shape,
+  async (args) => handleEmbedNode(args)
+);
+server.registerResource(
+  "memory_stats",
+  "memory://stats",
+  {
+    description: "Read-only graph statistics snapshot",
+    mimeType: "application/json"
+  },
+  async (uri) => {
+    const stats = handleGetStats();
+    return {
+      contents: [{
+        uri: uri.href,
+        mimeType: "application/json",
+        text: stats.content[0].text
+      }]
+    };
+  }
+);
+var memoryNodeTemplate = new ResourceTemplate("memory://node/{nodeId}", { list: void 0 });
+server.registerResource(
+  "memory_node",
+  memoryNodeTemplate,
+  {
+    description: "Read-only single memory node with edges (URI template memory://node/{nodeId})",
+    mimeType: "application/json"
+  },
+  async (uri, variables) => {
+    const raw = variables.nodeId;
+    const nodeId = Array.isArray(raw) ? raw[0] : raw;
+    if (!nodeId) {
+      return {
+        contents: [{
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify({ error: "Missing nodeId" })
+        }]
+      };
+    }
+    const node = getNode(nodeId);
+    if (!node) {
+      return {
+        contents: [{
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify({ error: "Node not found" })
+        }]
+      };
+    }
+    const edges = getEdgesForNode(nodeId);
+    return {
+      contents: [{
+        uri: uri.href,
+        mimeType: "application/json",
+        text: JSON.stringify({ node, edges }, null, 2)
+      }]
+    };
+  }
+);
+async function main() {
+  try {
+    await initDb();
+  } catch (error) {
+    console.error(
+      JSON.stringify({
+        error: "memory_db_unavailable",
+        message: error instanceof Error ? error.message : String(error)
+      })
+    );
+    process.exit(1);
+  }
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.on("SIGINT", () => {
+    closeDb();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    closeDb();
+    process.exit(0);
+  });
+}
+main().catch((error) => {
+  console.error("Fatal error starting memory server:", error);
+  process.exit(1);
+});