relaybrain 0.0.0-stage → 0.2.0

package/backend/lib/falkor/project.js

@@ -0,0 +1,307 @@
+// Pure: memory.history → row batches for write.js. No I/O, no database.
+const path = require("path");
+const { relativeEditPath } = require("../transcripts/sync");
+const keys = require("./keys");
+const { storedText, clip, redact } = require("./redact");
+
+const TURN_TEXT_MAX = 2000;
+const DIFF_HEAD_MAX = 1000;
+const INTENT_MAX = 280;
+const TITLE_MAX = 120;
+const STALE_PROMPT_MS = 30 * 60 * 1000;
+const DUPLICATE_WINDOW_MS = 2 * 60 * 1000;
+// "continue"-style nudges say nothing about intent; the request they continue does.
+const FILLER = /^(please\s+)?(continue|go(\s+on|\s+ahead)?|yes|yep|yeah|y|ok(ay)?|sure|proceed|do\s+it|keep\s+going|carry\s+on|next|try\s+again|retry|go\s+for\s+it|sounds\s+good|lgtm|done\??)[\s.!]*$/i;
+
+const GREETING = /^(hi+|hello|hey+|yo|sup|wassup|hola|thanks|thank\s+you|thx|ty)(\s+(there|wassup|sup|man|bro|all|claude|cursor|again|so\s+much))*[\s.!?,]*$/i;
+
+function isFiller(text) {
+  const s = String(text || "").trim();
+  return s.length <= 30 && (FILLER.test(s) || GREETING.test(s));
+}
+
+function diffStats(diff) {
+  let added = 0;
+  let removed = 0;
+  for (const line of String(diff || "").split("\n")) {
+    if (line.startsWith("+") && !line.startsWith("+++")) added += 1;
+    else if (line.startsWith("-") && !line.startsWith("---")) removed += 1;
+  }
+  return { added, removed };
+}
+
+function toolOf(text) {
+  const word = String(text || "").trim().split(/\s+/)[0] || "";
+  return word.slice(0, 40) || null;
+}
+
+function sessionOf(event) {
+  const real = keys.sessionKey(event.agent, event.sessionId);
+  if (real) return { key: real, bucket: false };
+  return { key: keys.bucketSessionKey(event.agent, event.ownerLogin, event.ts), bucket: true };
+}
+
+function oneLine(text, max) {
+  return clip(redact(String(text || "").replace(/\s+/g, " ").trim()), max);
+}
+
+/**
+ * @param {object[]} history unified events (sync.js unifyEvent), ordered by compareEvents
+ * @param {object} opts
+ * @param {string} opts.workspacePath used to make edit paths repo-relative
+ * @param {(id: string) => boolean} [opts.isNew] events not yet ingested; default: all
+ * @param {boolean} [opts.storeText]
+ */
+function projectHistory(history, opts = {}) {
+  const { workspacePath, isNew = () => true, storeText = true } = opts;
+  const groups = new Map();
+  let dropped = 0;
+
+  for (const event of history || []) {
+    if (!event || !event.id || !event.agent) {
+      dropped += 1;
+      continue;
+    }
+    const { key, bucket } = sessionOf(event);
+    if (!groups.has(key)) groups.set(key, { key, bucket, events: [] });
+    groups.get(key).events.push(event);
+  }
+
+  const sessions = [];
+  const turns = [];
+  const edits = [];
+  const intents = new Map();
+
+  for (const group of groups.values()) {
+    const first = group.events[0];
+    const login = keys.loginKey(first.ownerLogin);
+    const agentKey = keys.agentKey(first.ownerLogin, first.agent);
+    let lastUser = null;
+    let lastMeaningful = null;
+    let lastAssistant = null;
+    let firstUser = null;
+    let thinking = 0;
+    let fresh = false;
+    let seq = 0;
+    const recent = new Map();
+    let startedAt = Infinity;
+    let lastAt = 0;
+
+    for (const event of group.events) {
+      const ts = Number(event.ts) || 0;
+      startedAt = Math.min(startedAt, ts);
+      lastAt = Math.max(lastAt, ts);
+      const isFresh = isNew(event.id);
+      if (isFresh) fresh = true;
+
+      if (event.kind === "thinking") {
+        thinking += 1;
+        continue;
+      }
+
+      if (event.kind === "message" && (event.role === "user" || event.role === "assistant")) {
+        if (!String(event.text || "").trim()) continue;
+        // One conversation can be recorded twice (Copilot writes chatSessions and a transcript
+        // for the same session); a repeat of the same message moments later is the same turn.
+        const dupKey = `${event.role}|${String(event.text).replace(/\s+/g, " ").trim().slice(0, 200)}`;
+        const prevTs = recent.get(dupKey);
+        if (prevTs != null && Math.abs(ts - prevTs) <= DUPLICATE_WINDOW_MS) continue;
+        recent.set(dupKey, ts);
+        const turn = {
+          sessionKey: group.key,
+          turnKey: keys.turnKey({
+            login: event.ownerLogin,
+            label: event.agent,
+            sessionId: event.sessionId,
+            ts: event.ts,
+            role: event.role,
+            kind: event.kind,
+            text: event.text,
+          }),
+          ts,
+          role: event.role,
+          kind: "message",
+          text: storedText(event.text, TURN_TEXT_MAX, storeText),
+          seq: seq++,
+          tsSynthetic: keys.tsSynthetic(event.ts, event.tsSynthetic),
+        };
+        if (event.role === "user") {
+          lastUser = { ...turn, raw: event.text };
+          if (!isFiller(event.text)) {
+            lastMeaningful = lastUser;
+            if (!firstUser) firstUser = lastUser;
+          }
+        } else {
+          lastAssistant = turn;
+        }
+        if (isFresh) turns.push(turn);
+        continue;
+      }
+
+      if (event.kind === "code_edit") {
+        const hasPath = Boolean(event.path || event.file);
+        const rel = hasPath ? relativeEditPath(event, workspacePath) : null;
+        // Matches sync.js buildViews: an edit outside the workspace is not this project's activity.
+        if (hasPath && !rel) continue;
+        if (!isFresh) continue;
+        const fk = keys.fileKey(rel);
+        const stats = diffStats(event.diff);
+        const prompt = lastMeaningful || lastUser;
+        const promptGap = prompt ? ts - prompt.ts : null;
+        edits.push({
+          sessionKey: group.key,
+          agentKey,
+          login,
+          loginRaw: String(first.ownerLogin || "local"),
+          label: first.agent,
+          editKey: `e_${event.id}`,
+          fileKey: fk,
+          path: fk ? keys.displayPath(rel) : null,
+          ext: fk ? path.posix.extname(fk).slice(1) || null : null,
+          orphan: !fk,
+          ts,
+          tool: toolOf(event.text),
+          diffHead: storeText ? clip(redact(event.diff || ""), DIFF_HEAD_MAX) : null,
+          added: stats.added,
+          removed: stats.removed,
+          tsSynthetic: keys.tsSynthetic(event.ts, event.tsSynthetic),
+          promptKey: prompt ? prompt.turnKey : null,
+          promptGap,
+          promptStale: promptGap != null && promptGap > STALE_PROMPT_MS,
+          promptConfidence: group.bucket ? "low" : "high",
+          promptVia: lastUser && prompt !== lastUser ? oneLine(lastUser.raw, 40) : null,
+          explainKey: lastAssistant ? lastAssistant.turnKey : null,
+          explainGap: lastAssistant ? ts - lastAssistant.ts : null,
+        });
+      }
+    }
+
+    const intentSource = lastMeaningful || lastUser;
+    const intentText = intentSource ? oneLine(intentSource.raw, INTENT_MAX) : null;
+    const info = {
+      sessionKey: group.key,
+      agentKey,
+      label: first.agent,
+      login,
+      loginRaw: String(first.ownerLogin || "local"),
+      sessionId: group.bucket ? null : String(first.sessionId),
+      bucket: group.bucket,
+      startedAt: Number.isFinite(startedAt) ? startedAt : 0,
+      lastAt,
+      thinkingCount: thinking,
+      title: storeText && firstUser ? oneLine(firstUser.raw, TITLE_MAX) : null,
+      intent: storeText ? intentText : null,
+      intentAt: intentSource ? intentSource.ts : null,
+    };
+    // The cache only lives in this process (deny-reason hints), so it keeps text even when the graph doesn't.
+    intents.set(group.key, { ...info, intent: intentText });
+    if (fresh) sessions.push(info);
+  }
+
+  return { sessions, turns, edits, intents, dropped };
+}
+
+const AGENT_LABELS = new Set(["Claude Code", "Cursor", "Codex", "Copilot", "Antigravity"]);
+// Watcher patches from bulk tree copies are not anyone's edit.
+const BULK_PATCH_AGENTS = new Set(["seed", "snapshot"]);
+const UNATTRIBUTED = "Editor";
+// Files `relay init/clone/add` writes itself; an unattributed change to them is relay, not a person.
+const RELAY_MANAGED = /^(\.claude\/|\.cursor\/|\.codex\/|\.agents\/|\.relay\/|\.github\/hooks\/|\.github\/mcp\.json$|\.github\/copilot-instructions\.md$|\.cursorrules$|claude\.md$|agents\.md$)/;
+
+function patchRow(patch, { storeText = true } = {}) {
+  if (!patch?.id || !patch.file || BULK_PATCH_AGENTS.has(patch.agent)) return null;
+  const fk = keys.fileKey(patch.file);
+  if (!fk) return null;
+  // patch.agent is just "fs.watch"; the lock holder that triggered the flush is the real author.
+  const origin = keys.parseLockAgentId(patch.originAgentId);
+  const labelFromAgent = AGENT_LABELS.has(patch.agent) ? patch.agent : null;
+  const label = AGENT_LABELS.has(origin.label) ? origin.label : labelFromAgent || UNATTRIBUTED;
+  if (label === UNATTRIBUTED && RELAY_MANAGED.test(fk)) return null;
+  const sk = label === origin.label && origin.sessionKnown ? keys.sessionKey(label, origin.session) : null;
+  const diff = String(patch.diff || "");
+  const stats = diffStats(diff);
+  return {
+    sessionKey: sk,
+    agentKey: keys.agentKey(patch.ownerLogin, label),
+    login: keys.loginKey(patch.ownerLogin),
+    loginRaw: String(patch.ownerLogin || "local"),
+    label,
+    editKey: String(patch.id),
+    source: "patch",
+    fileKey: fk,
+    path: keys.displayPath(patch.file),
+    ext: path.posix.extname(fk).slice(1) || null,
+    orphan: false,
+    ts: Number(patch.ts) || Date.now(),
+    tool: "patch",
+    diffHead: storeText && !diff.startsWith("sha256:") ? clip(redact(diff), DIFF_HEAD_MAX) : null,
+    added: stats.added,
+    removed: stats.removed,
+    tsSynthetic: false,
+    lamport: Number.isFinite(Number(patch.lamport)) ? Number(patch.lamport) : null,
+    sha256: patch.sha256 || null,
+    promptKey: null,
+    explainKey: null,
+  };
+}
+
+function projectPatches(patches, opts = {}) {
+  return { sessions: [], turns: [], edits: patches.map((p) => patchRow(p, opts)).filter(Boolean), intents: new Map(), dropped: 0 };
+}
+
+/**
+ * A room peer's snapshot (roomSync.sanitize shape) → the same rows as local history.
+ * Peers ship threads + edit rows but no raw history, and their edit rows carry no
+ * session, so each edit is re-attached to its thread's code_edit message.
+ */
+function projectPeer(snapshot, { login, trustRowOwners = false, isNew = () => true, storeText = true } = {}) {
+  const events = [];
+  const edits = [...(snapshot?.edits || [])];
+  const used = new Set();
+  const ownerOf = (row) => (trustRowOwners ? row?.ownerLogin || login : login);
+
+  for (const thread of snapshot?.chats || []) {
+    if (!thread?.agent) continue;
+    const owner = ownerOf(thread);
+    for (const m of thread.messages || []) {
+      if (!m) continue;
+      const base = { agent: thread.agent, ownerLogin: owner, sessionId: thread.sessionId, ts: Number(m.ts) || 0 };
+      if (m.kind === "code_edit") {
+        const base2 = path.posix.basename(String(m.file || "").replace(/\\/g, "/")).toLowerCase();
+        const idx = edits.findIndex(
+          (e, i) =>
+            !used.has(i) &&
+            e.agent === thread.agent &&
+            Number(e.ts) === base.ts &&
+            path.posix.basename(String(e.file || "").replace(/\\/g, "/")).toLowerCase() === base2
+        );
+        if (idx < 0) continue;
+        used.add(idx);
+        const edit = edits[idx];
+        events.push({ ...base, id: String(edit.id).replace(/^e_/, ""), role: "tool", kind: "code_edit", text: m.text, file: m.file, path: edit.file, diff: edit.diff });
+        continue;
+      }
+      if (m.role !== "user" && m.role !== "assistant") continue;
+      const tk = keys.turnKey({ login: owner, label: thread.agent, sessionId: thread.sessionId, ts: m.ts, role: m.role, kind: "message", text: m.text });
+      events.push({ ...base, id: `peer_${tk}`, role: m.role, kind: "message", text: m.text });
+    }
+  }
+  events.sort((a, b) => a.ts - b.ts);
+  const projection = projectHistory(events, { workspacePath: null, isNew, storeText });
+
+  // Edits whose thread message was trimmed away still count; they just lose their session.
+  for (let i = 0; i < edits.length; i++) {
+    if (used.has(i)) continue;
+    const e = edits[i];
+    const owner = ownerOf(e);
+    const row = String(e.id || "").startsWith("patch_")
+      ? patchRow({ ...e, ownerLogin: owner }, { storeText })
+      : patchRow({ ...e, id: e.id, ownerLogin: owner, originAgentId: null }, { storeText });
+    if (!row || !isNew(row.editKey)) continue;
+    if (!String(e.id || "").startsWith("patch_")) row.source = "transcript";
+    projection.edits.push(row);
+  }
+  return projection;
+}
+
+module.exports = { projectHistory, projectPatches, projectPeer, patchRow, diffStats, TURN_TEXT_MAX, INTENT_MAX, UNATTRIBUTED };

package/backend/lib/falkor/query.js

@@ -0,0 +1,344 @@
+// Named, parameterized, read-only queries: the only way anything reads the graph.
+// No caller-supplied Cypher, so the surface is safe for room guests over the tunnel.
+const keys = require("./keys");
+
+const MAX_LIMIT = 50;
+const ACTIVE_MS = 15 * 60 * 1000;
+
+function limitOf(v, d = 10) {
+  const n = Number(v) || d;
+  return Math.max(1, Math.min(MAX_LIMIT, Math.floor(n)));
+}
+
+function requireFile(args) {
+  const fk = keys.fileKey(args.path);
+  if (!fk) throw Object.assign(new Error("`path` must be a repo-relative file path"), { status: 400 });
+  return fk;
+}
+
+function fileList(args) {
+  const raw = Array.isArray(args.paths) ? args.paths : String(args.paths || args.path || "").split(",");
+  const list = [...new Set(raw.map((p) => keys.fileKey(p)).filter(Boolean))].slice(0, 10);
+  if (!list.length) throw Object.assign(new Error("`paths` must list repo-relative files"), { status: 400 });
+  return list;
+}
+
+/** RediSearch syntax characters would turn user text into a query language; keep words only. */
+function searchTerms(q) {
+  const words = String(q || "")
+    .replace(/[^\p{L}\p{N}_\s]/gu, " ")
+    .split(/\s+/)
+    .filter((w) => w.length > 1)
+    .slice(0, 8);
+  return words.join(" ");
+}
+
+const Q = {
+  file_story: {
+    summary: "Every change to a file, newest first, with the prompt that caused it.",
+    cypher: `
+MATCH (f:File {key: $fileKey})<-[:MODIFIED]-(e:Edit)-[:BY]->(a:Agent)
+WHERE NOT (e)-[:SAME_CHANGE]->()
+OPTIONAL MATCH (e)-[p:PROMPTED_BY]->(u:Turn)
+OPTIONAL MATCH (e)-[:EXPLAINED_BY]->(x:Turn)
+OPTIONAL MATCH (s:Session)-[:MADE]->(e)
+RETURN e.ts AS ts, a.label AS agent, a.login AS person, e.source AS source, s.title AS session,
+       u.text AS prompt, p.via AS via, x.text AS agentSaid, e.added AS added, e.removed AS removed, e.diffHead AS diff
+ORDER BY ts DESC LIMIT $limit`,
+    params: (a) => ({ fileKey: requireFile(a), limit: limitOf(a.limit) }),
+  },
+
+  who_to_ask: {
+    summary: "People (and their agents) who know a file best, by recency and volume.",
+    cypher: `
+MATCH (p:Person)-[:RUNS]->(a:Agent)-[t:TOUCHED]->(f:File {key: $fileKey})
+WITH p, sum(t.count) AS edits, max(t.lastAt) AS lastAt, collect(DISTINCT a.label) AS via
+RETURN p.login AS person, edits, lastAt, via
+ORDER BY lastAt DESC, edits DESC LIMIT $limit`,
+    params: (a) => ({ fileKey: requireFile(a), limit: limitOf(a.limit, 5) }),
+  },
+
+  contention_trace: {
+    summary: "Why agents were blocked: who held the file, what they were doing, who wanted it.",
+    cypher: `
+MATCH (c:Contention)-[:ON]->(f:File)
+WHERE $fileKey IS NULL OR f.key = $fileKey
+OPTIONAL MATCH (c)-[:HELD_BY]->(hs:Session)
+OPTIONAL MATCH (ha:Agent)-[:RAN]->(hs)
+OPTIONAL MATCH (c)-[:WANTED_BY]->(ws:Session)
+OPTIONAL MATCH (wa:Agent)-[:RAN]->(ws)
+RETURN c.ts AS ts, c.lastTs AS lastTs, c.kind AS kind, c.attempts AS attempts, f.path AS file,
+       coalesce(ha.label, c.holderLabel) AS holder, ha.login AS holderPerson,
+       coalesce(c.holderIntent, hs.intent) AS holderWasDoing,
+       coalesce(wa.label, c.wanterLabel) AS wanter, wa.login AS wanterPerson, ws.intent AS wanterWasDoing,
+       c.reason AS reason
+ORDER BY ts DESC LIMIT $limit`,
+    params: (a) => ({ fileKey: a.path ? requireFile(a) : null, limit: limitOf(a.limit) }),
+  },
+
+  search_memory: {
+    summary: "Full-text search across every agent conversation in the project.",
+    cypher: `
+CALL db.idx.fulltext.queryNodes('Turn', $q) YIELD node, score
+MATCH (s:Session)-[:HAS_TURN]->(node)
+OPTIONAL MATCH (a:Agent)-[:RAN]->(s)
+RETURN node.text AS text, node.ts AS ts, node.role AS role, a.label AS agent, a.login AS person,
+       s.title AS session, s.key AS sessionKey, score
+ORDER BY score DESC LIMIT $limit`,
+    params: (a) => {
+      const q = searchTerms(a.q);
+      if (!q) throw Object.assign(new Error("`q` must contain words to search for"), { status: 400 });
+      return { q, limit: limitOf(a.limit) };
+    },
+  },
+
+  agent_activity: {
+    summary: "What an agent or person has been working on, session by session.",
+    cypher: `
+MATCH (a:Agent)-[:RAN]->(s:Session)
+WHERE ($label IS NULL OR a.label = $label) AND ($login IS NULL OR a.login = $login) AND s.lastAt >= $since
+OPTIONAL MATCH (s)-[:MADE]->(e:Edit)-[:MODIFIED]->(f:File)
+RETURN a.label AS agent, a.login AS person, s.title AS title, s.intent AS intent, s.lastAt AS lastAt,
+       s.turnCount AS turns, s.editCount AS edits, collect(DISTINCT f.path)[..15] AS files
+ORDER BY lastAt DESC LIMIT $limit`,
+    params: (a) => ({
+      label: a.agent ? String(a.agent) : null,
+      login: a.person ? keys.loginKey(a.person) : null,
+      since: Number(a.since) || 0,
+      limit: limitOf(a.limit),
+    }),
+  },
+
+  hotspots: {
+    summary: "Files where coordination matters most: PageRank over co-edits, plus overlaps and blocks.",
+    cypher: `
+MATCH (f:File) WHERE f.rank IS NOT NULL
+OPTIONAL MATCH (f)<-[:ON]-(c:Contention)
+OPTIONAL MATCH (f)<-[:ON]-(o:Overlap)
+OPTIONAL MATCH (a:Agent)-[:TOUCHED]->(f)
+RETURN f.path AS file, f.rank AS rank, f.community AS community, f.editCount AS edits,
+       count(DISTINCT c) AS contentions, count(DISTINCT o) AS overlaps, count(DISTINCT a) AS agents
+ORDER BY rank DESC LIMIT $limit`,
+    params: (a) => ({ limit: limitOf(a.limit) }),
+  },
+
+  decision_trace: {
+    summary: "Decisions about a file (or all), who made them and in which session.",
+    cypher: `
+MATCH (d:Decision)
+WHERE $fileKey IS NULL OR (d)-[:ABOUT]->(:File {key: $fileKey})
+OPTIONAL MATCH (a:Agent)-[:DECIDED]->(d)
+OPTIONAL MATCH (d)-[r:DURING]->(s:Session)
+OPTIONAL MATCH (d)-[:ABOUT]->(f:File)
+RETURN d.key AS id, d.content AS decision, d.status AS status, d.updatedAt AS updatedAt, d.revisions AS revisions,
+       a.label AS agent, a.login AS person, s.title AS session, r.confidence AS sessionConfidence,
+       collect(DISTINCT f.path) AS files
+ORDER BY updatedAt DESC LIMIT $limit`,
+    params: (a) => ({ fileKey: a.path ? requireFile(a) : null, limit: limitOf(a.limit) }),
+  },
+
+  overlaps: {
+    summary: "Places where two different agents changed the same file within minutes.",
+    cypher: `
+MATCH (o:Overlap)-[:ON]->(f:File)
+WHERE $fileKey IS NULL OR f.key = $fileKey
+MATCH (o)-[:BETWEEN]->(e:Edit)-[:BY]->(a:Agent)
+OPTIONAL MATCH (e)-[:PROMPTED_BY]->(u:Turn)
+WITH o, f, collect({agent: a.label, person: a.login, ts: e.ts, prompt: u.text}) AS sides
+RETURN o.ts AS ts, f.path AS file, o.gapMs AS gapMs, o.confidence AS confidence, sides
+ORDER BY ts DESC LIMIT $limit`,
+    params: (a) => ({ fileKey: a.path ? requireFile(a) : null, limit: limitOf(a.limit) }),
+  },
+
+  overview: {
+    summary: "Counts by node label and relationship type.",
+    cypher: `
+MATCH (n) WHERE NOT n:Meta
+RETURN labels(n)[0] AS label, count(n) AS count ORDER BY count DESC`,
+    params: () => ({}),
+  },
+};
+
+const NEIGHBORHOOD = `
+MATCH (f:File {key: $fileKey})
+OPTIONAL MATCH (f)<-[:MODIFIED]-(e:Edit)-[:BY]->(a:Agent)
+WHERE NOT (e)-[:SAME_CHANGE]->()
+OPTIONAL MATCH (s:Session)-[:MADE]->(e)
+OPTIONAL MATCH (e)-[:PROMPTED_BY]->(u:Turn)
+WITH f, e, a, s, u ORDER BY e.ts DESC LIMIT 25
+RETURN f.key AS fileKey, f.path AS filePath, f.rank AS rank,
+       collect({edit: e.key, ts: e.ts, agent: a.key, agentLabel: a.label, person: a.login,
+                session: s.key, sessionTitle: s.title, sessionIntent: s.intent, prompt: u.key, promptText: u.text}) AS rows`;
+
+const NEIGHBOR_EXTRAS = `
+MATCH (f:File {key: $fileKey})
+OPTIONAL MATCH (f)<-[:ON]-(c:Contention)
+OPTIONAL MATCH (c)-[:HELD_BY]->(hs:Session)
+OPTIONAL MATCH (c)-[:WANTED_BY]->(ws:Session)
+WITH f, collect(DISTINCT {key: c.key, kind: c.kind, attempts: c.attempts, ts: c.ts, holder: hs.key, holderLabel: hs.label,
+                           holderIntent: coalesce(c.holderIntent, hs.intent), wanter: ws.key, wanterLabel: ws.label}) AS contentions
+OPTIONAL MATCH (f)<-[:ABOUT]-(d:Decision)
+WITH f, contentions, collect(DISTINCT {key: d.key, content: d.content, status: d.status}) AS decisions
+OPTIONAL MATCH (f)-[x:CO_EDITED]->(g:File)
+WITH f, contentions, decisions, g, x ORDER BY x.weight DESC
+RETURN contentions, decisions, collect({key: g.key, path: g.path, weight: x.weight})[..8] AS coEdited`;
+
+const HOTSPOT_SEEDS = `MATCH (f:File) WHERE f.rank IS NOT NULL RETURN f.key AS k ORDER BY f.rank DESC LIMIT 1`;
+
+/** Small node/edge set around one file, shaped for the Mission Control canvas. */
+async function neighborhood(client, projectId, args) {
+  let fk = args.path ? requireFile(args) : null;
+  if (!fk) fk = (await client.read(projectId, HOTSPOT_SEEDS))[0]?.k || null;
+  if (!fk) return { nodes: [], edges: [], focus: null };
+  const [main] = await client.read(projectId, NEIGHBORHOOD, { fileKey: fk });
+  const [extra] = await client.read(projectId, NEIGHBOR_EXTRAS, { fileKey: fk });
+  if (!main) return { nodes: [], edges: [], focus: null };
+  const nodes = new Map();
+  const edges = [];
+  const node = (id, kind, label, props = {}) => {
+    if (id && !nodes.has(id)) nodes.set(id, { id, kind, label, props });
+  };
+  const seenEdges = new Set();
+  const edge = (from, to, type) => {
+    const k = `${from}|${to}|${type}`;
+    if (!from || !to || seenEdges.has(k)) return;
+    seenEdges.add(k);
+    edges.push({ from, to, type });
+  };
+  node(`file:${main.fileKey}`, "file", main.filePath, { rank: main.rank, focus: true });
+  for (const r of main.rows || []) {
+    if (!r.edit) continue;
+    node(`agent:${r.agent}`, "agent", `${r.agentLabel} · ${r.person}`, { person: r.person, label: r.agentLabel });
+    if (r.session) {
+      node(`session:${r.session}`, "session", r.sessionTitle || r.session.split("::")[1]?.slice(0, 8) || "session", { intent: r.sessionIntent });
+      edge(`agent:${r.agent}`, `session:${r.session}`, "RAN");
+      edge(`session:${r.session}`, `file:${main.fileKey}`, "EDITED");
+    } else {
+      edge(`agent:${r.agent}`, `file:${main.fileKey}`, "EDITED");
+    }
+    if (r.prompt && r.session) {
+      node(`turn:${r.prompt}`, "prompt", r.promptText ? String(r.promptText).slice(0, 80) : "prompt", { text: r.promptText });
+      edge(`turn:${r.prompt}`, `session:${r.session}`, "PROMPTED");
+    }
+  }
+  for (const c of extra?.contentions || []) {
+    if (!c.key) continue;
+    node(`contention:${c.key}`, "contention", `${c.kind === "claim_blocked" ? "blocked" : c.kind} ×${c.attempts || 1}`, c);
+    edge(`contention:${c.key}`, `file:${main.fileKey}`, "ON");
+    if (c.holder) {
+      node(`session:${c.holder}`, "session", c.holderLabel || "holder", { intent: c.holderIntent });
+      edge(`contention:${c.key}`, `session:${c.holder}`, "HELD_BY");
+    }
+    if (c.wanter) {
+      node(`session:${c.wanter}`, "session", c.wanterLabel || "wanter", {});
+      edge(`contention:${c.key}`, `session:${c.wanter}`, "WANTED_BY");
+    }
+  }
+  for (const d of extra?.decisions || []) {
+    if (!d.key) continue;
+    node(`decision:${d.key}`, "decision", String(d.content || "decision").slice(0, 60), d);
+    edge(`decision:${d.key}`, `file:${main.fileKey}`, "ABOUT");
+  }
+  for (const g of extra?.coEdited || []) {
+    if (!g.key) continue;
+    node(`file:${g.key}`, "file", g.path, { weight: g.weight });
+    edge(`file:${main.fileKey}`, `file:${g.key}`, "CO_EDITED");
+  }
+  return { focus: main.fileKey, nodes: [...nodes.values()].slice(0, 150), edges };
+}
+
+const BRIEF_EDITS = `
+MATCH (f:File {key: $fileKey})<-[:MODIFIED]-(e:Edit)-[:BY]->(a:Agent)
+WHERE NOT (e)-[:SAME_CHANGE]->()
+OPTIONAL MATCH (e)-[:PROMPTED_BY]->(u:Turn)
+RETURN e.ts AS ts, a.label AS agent, a.login AS person, u.text AS prompt
+ORDER BY ts DESC LIMIT 8`;
+const BRIEF_FILE = `MATCH (f:File {key: $fileKey}) RETURN f.path AS path, f.rank AS rank, f.community AS community, f.editCount AS edits`;
+const BRIEF_ACTIVE = `
+MATCH (s:Session)-[h:HELD]->(f:File {key: $fileKey})
+WHERE h.lastAt >= $activeSince
+OPTIONAL MATCH (a:Agent)-[:RAN]->(s)
+RETURN coalesce(a.label, s.label) AS agent, a.login AS person, s.intent AS intent, h.lastAt AS lastAt
+ORDER BY lastAt DESC LIMIT 3`;
+const BRIEF_NEIGHBORS = `
+MATCH (f:File {key: $fileKey})
+WHERE f.community IS NOT NULL
+MATCH (g:File) WHERE g.community = f.community AND g.key <> f.key
+MATCH (a:Agent)-[t:TOUCHED]->(g) WHERE t.lastAt >= $activeSince
+RETURN g.path AS file, a.label AS agent, a.login AS person, t.lastAt AS lastAt
+ORDER BY lastAt DESC LIMIT 3`;
+
+function ago(ts, now) {
+  if (!ts) return "";
+  const m = Math.round((now - ts) / 60000);
+  if (m < 60) return `${m}m ago`;
+  if (m < 48 * 60) return `${Math.round(m / 60)}h ago`;
+  return `${Math.round(m / 1440)}d ago`;
+}
+
+function clipLine(s, n = 140) {
+  const t = String(s || "").replace(/\s+/g, " ").trim();
+  return t.length > n ? `${t.slice(0, n)}…` : t;
+}
+
+/** Everything an agent should know before touching these files, as data and as markdown. */
+async function sessionBrief(client, projectId, args, run) {
+  const files = fileList(args);
+  const now = Date.now();
+  const activeSince = now - ACTIVE_MS;
+  const out = [];
+  for (const fileKey of files) {
+    const [info] = await client.read(projectId, BRIEF_FILE, { fileKey });
+    const recent = await client.read(projectId, BRIEF_EDITS, { fileKey });
+    const people = (await run("who_to_ask", { path: fileKey, limit: 3 })).rows;
+    const decisions = (await run("decision_trace", { path: fileKey, limit: 3 })).rows;
+    const blocks = (await run("contention_trace", { path: fileKey, limit: 3 })).rows;
+    const active = await client.read(projectId, BRIEF_ACTIVE, { fileKey, activeSince });
+    const nearby = await client.read(projectId, BRIEF_NEIGHBORS, { fileKey, activeSince });
+    out.push({ file: info?.path || fileKey, known: Boolean(info), rank: info?.rank ?? null, community: info?.community ?? null, edits: info?.edits || 0, recent, people, decisions, blocks, active, nearby });
+  }
+
+  const md = ["# Relay memory brief", ""];
+  for (const f of out) {
+    md.push(`## ${f.file}`);
+    if (!f.known) {
+      md.push("- No history in the project memory graph yet.", "");
+      continue;
+    }
+    if (f.active.length) for (const a of f.active) md.push(`- ⚠️ **In use right now** by ${a.agent}${a.person ? ` (${a.person})` : ""}${a.intent ? `: "${clipLine(a.intent)}"` : ""}`);
+    for (const b of f.blocks) md.push(`- Contention ${ago(b.ts, now)}: ${b.wanter} was blocked by ${b.holder}${b.holderWasDoing ? ` while it worked on "${clipLine(b.holderWasDoing, 90)}"` : ""}`);
+    for (const d of f.decisions) md.push(`- Decision (${d.status}): ${clipLine(d.decision)}${d.agent ? `, by ${d.agent}` : ""}`);
+    const why = new Map();
+    for (const r of f.recent) {
+      const k = `${r.agent}|${r.person}|${r.prompt || ""}`;
+      if (why.has(k)) why.get(k).n += 1;
+      else why.set(k, { ...r, n: 1 });
+    }
+    for (const r of why.values()) {
+      md.push(`- ${ago(r.ts, now)} ${r.agent} (${r.person}) changed it${r.n > 1 ? ` ${r.n}×` : ""} because: "${clipLine(r.prompt || "unknown")}"`);
+    }
+    if (f.people.length) md.push(`- Ask: ${f.people.map((p) => `${p.person} (${p.edits} edits via ${p.via.join("/")})`).join(", ")}`);
+    for (const n of f.nearby) md.push(`- Same work area: ${n.file} touched ${ago(n.lastAt, now)} by ${n.agent} (${n.person})`);
+    md.push("");
+  }
+  return { files: out, markdown: md.join("\n") };
+}
+
+function names() {
+  return [...Object.keys(Q), "session_brief", "neighborhood"];
+}
+
+/** Runs one named query. Throws a 400-style error on bad input. */
+async function runNamed(client, projectId, name, args = {}) {
+  if (!projectId) throw Object.assign(new Error("no project"), { status: 404 });
+  const run = (n, a) => runNamed(client, projectId, n, a);
+  if (name === "session_brief") return { query: name, ...(await sessionBrief(client, projectId, args, run)) };
+  if (name === "neighborhood") return { query: name, ...(await neighborhood(client, projectId, args)) };
+  const def = Q[name];
+  if (!def) throw Object.assign(new Error(`unknown query "${name}". Try: ${names().join(", ")}`), { status: 400 });
+  const params = def.params(args);
+  const rows = await client.read(projectId, def.cypher, params);
+  return { query: name, summary: def.summary, cypher: def.cypher.trim(), params, rows };
+}
+
+module.exports = { runNamed, names, searchTerms, Q };

package/backend/lib/falkor/redact.js

@@ -0,0 +1,30 @@
+const PATTERNS = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+  /\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{20,}/g,
+  /\bgh[pousr]_[A-Za-z0-9]{30,}/g,
+  /\bgithub_pat_[A-Za-z0-9_]{30,}/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}/g,
+  /\bAIza[0-9A-Za-z_-]{35}\b/g,
+  /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,
+];
+const ASSIGNMENT = /\b(password|passwd|secret|api[_-]?key|token)(\s*[:=]\s*)(["']?)[^\s"']{6,}\3/gi;
+
+function redact(text) {
+  let s = String(text ?? "");
+  for (const re of PATTERNS) s = s.replace(re, "[redacted]");
+  return s.replace(ASSIGNMENT, (_m, name, sep) => `${name}${sep}[redacted]`);
+}
+
+function clip(text, max) {
+  const s = String(text ?? "");
+  return s.length > max ? `${s.slice(0, max)}…` : s;
+}
+
+/** Text as stored in the graph: redacted, clipped, or dropped entirely when text storage is off. */
+function storedText(text, max, storeText = true) {
+  if (!storeText) return null;
+  return clip(redact(text), max);
+}
+
+module.exports = { redact, clip, storedText };