codex-dev-mcp-suite 1.0.0

package/devjournal/server.js

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+
+/**
+ * Dev Journal MCP Server for Codex
+ *
+ * Per-project session timeline + handoff so you never lose your place when a
+ * session hits "input too long" / gets compacted / you start fresh.
+ *
+ * Core idea:
+ *   - journal_handoff: at end of a work block, store "what I did + open
+ *     questions + next steps + active files". One canonical resume point.
+ *   - journal_resume: at start of a new session, get the latest handoff +
+ *     recent entries, so you (or the agent) can continue immediately.
+ *
+ * Storage: append-only JSONL per project (default
+ *   ~/.codex/memories/journal/<project-slug>/journal.jsonl) + a
+ *   handoff.json for the latest canonical resume state. Human-readable
+ *   journal.md mirror is also maintained.
+ *
+ * Tools: journal_log, journal_handoff, journal_resume,
+ *        journal_timeline, journal_clear_handoff
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+import crypto from "crypto";
+import { rerank, rerankConfig } from "./rerank.js";
+
+const ROOT =
+  process.env.JOURNAL_DIR ||
+  path.join(os.homedir(), ".codex", "memories", "journal");
+
+const MAX_TEXT = 20_000;
+
+function slug(dir) {
+  const resolved = path.resolve(dir || process.cwd());
+  const base = path.basename(resolved) || "root";
+  const hash = crypto.createHash("sha1").update(resolved).digest("hex").slice(0, 8);
+  return `${base.replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 40)}-${hash}`;
+}
+function nowIso() { return new Date().toISOString(); }
+function clip(v, name, max, req = true) {
+  const t = String(v ?? "");
+  if (req && !t.trim()) throw new Error(`${name} is required`);
+  if (t.length > max) throw new Error(`${name} exceeds ${max} chars`);
+  return t;
+}
+function asList(v) {
+  if (Array.isArray(v)) return v.map((x) => String(x).trim()).filter(Boolean);
+  if (typeof v === "string" && v.trim()) return v.split("\n").map((s) => s.replace(/^[-*]\s*/, "").trim()).filter(Boolean);
+  return [];
+}
+
+class DevJournalServer {
+  constructor() {
+    this.server = new Server({ name: "devjournal", version: "1.0.0" }, { capabilities: { tools: {} } });
+    this.setup();
+  }
+
+  paths(dir) {
+    const s = slug(dir);
+    const d = path.join(ROOT, s);
+    return {
+      slug: s,
+      root: path.resolve(dir || process.cwd()),
+      dir: d,
+      jsonl: path.join(d, "journal.jsonl"),
+      md: path.join(d, "journal.md"),
+      handoff: path.join(d, "handoff.json"),
+    };
+  }
+
+  async append(p, entry) {
+    await fs.mkdir(p.dir, { recursive: true });
+    await fs.appendFile(p.jsonl, JSON.stringify(entry) + "\n");
+    const md = `\n## ${entry.ts} — ${entry.type}${entry.title ? `: ${entry.title}` : ""}\n${entry.body || ""}\n`;
+    await fs.appendFile(p.md, md);
+  }
+
+  async readEntries(p, limit = 50) {
+    try {
+      const raw = await fs.readFile(p.jsonl, "utf8");
+      const rows = raw.split("\n").filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+      return rows.slice(-limit);
+    } catch { return []; }
+  }
+
+  setup() {
+    this.server.setRequestHandler(ListToolsRequestSchema, () => ({
+      tools: [
+        {
+          name: "journal_log",
+          description: "Append a quick timestamped entry (note/decision/blocker/done) to the project journal.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              title: { type: "string", description: "Short summary" },
+              body: { type: "string", description: "Details (Markdown ok)" },
+              type: { type: "string", description: "note | decision | blocker | done | idea", default: "note" },
+              ts: { type: "string", description: "Optional ISO timestamp to backdate the entry" },
+              dir: { type: "string", description: "Project directory (defaults to CWD)" },
+            },
+            required: ["title"],
+          },
+        },
+        {
+          name: "journal_handoff",
+          description: "Save the canonical resume point for this project: what was done, open questions, next steps, and active files. Call before ending a session or when context is about to be compacted.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              summary: { type: "string", description: "What was accomplished this session" },
+              next_steps: { type: "array", items: { type: "string" }, description: "Ordered next actions" },
+              open_questions: { type: "array", items: { type: "string" }, description: "Unresolved questions" },
+              active_files: { type: "array", items: { type: "string" }, description: "Files currently in focus" },
+              dir: { type: "string", description: "Project directory (defaults to CWD)" },
+            },
+            required: ["summary"],
+          },
+        },
+        {
+          name: "journal_resume",
+          description: "Get the latest handoff plus recent journal entries to resume work in a fresh session. Call this FIRST in a new session instead of re-pasting context.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              dir: { type: "string", description: "Project directory (defaults to CWD)" },
+              recent: { type: "number", description: "How many recent entries to include", default: 8 },
+            },
+          },
+        },
+        {
+          name: "journal_timeline",
+          description: "Show recent journal entries (newest last) for the project.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              dir: { type: "string", description: "Project directory (defaults to CWD)" },
+              limit: { type: "number", description: "Max entries", default: 20 },
+              type: { type: "string", description: "Filter by type (optional)" },
+            },
+          },
+        },
+        {
+          name: "journal_search",
+          description: "Find the most relevant journal entries for a query. Uses keyword prefilter + LLM rerank (9router Kiro) when available, else keyword scoring. Use to recall what you did about a topic across past sessions.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              query: { type: "string", description: "What you're looking for" },
+              dir: { type: "string", description: "Project directory (defaults to CWD)" },
+              limit: { type: "number", description: "Max entries", default: 5 },
+            },
+            required: ["query"],
+          },
+        },
+        {
+          name: "journal_clear_handoff",
+          description: "Clear the current canonical handoff (e.g., after fully resuming).",
+          inputSchema: {
+            type: "object",
+            properties: { dir: { type: "string", description: "Project directory (defaults to CWD)" } },
+          },
+        },
+      ],
+    }));
+
+    this.server.setRequestHandler(CallToolRequestSchema, async (req) => {
+      const { name, arguments: args } = req.params;
+      try {
+        switch (name) {
+          case "journal_log": return await this.log(args || {});
+          case "journal_handoff": return await this.doHandoff(args || {});
+          case "journal_resume": return await this.resume(args || {});
+          case "journal_timeline": return await this.timeline(args || {});
+          case "journal_search": return await this.search(args || {});
+          case "journal_clear_handoff": return await this.clearHandoff(args || {});
+          default: throw new Error(`Unknown tool: ${name}`);
+        }
+      } catch (e) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
+      }
+    });
+  }
+
+  async log({ title, body, type = "note", dir, ts: tsArg }) {
+    title = clip(title, "title", 500);
+    body = clip(body, "body", MAX_TEXT, false);
+    const p = this.paths(dir);
+    const ts = (tsArg && /^\d{4}-\d{2}-\d{2}/.test(String(tsArg))) ? String(tsArg) : nowIso();
+    const entry = { ts, type, title, body };
+    await this.append(p, entry);
+    return { content: [{ type: "text", text: `Logged [${type}] "${title}" to ${p.slug}` }] };
+  }
+
+  async doHandoff({ summary, next_steps, open_questions, active_files, dir }) {
+    summary = clip(summary, "summary", MAX_TEXT);
+    const p = this.paths(dir);
+    const handoff = {
+      ts: nowIso(),
+      summary,
+      next_steps: asList(next_steps),
+      open_questions: asList(open_questions),
+      active_files: asList(active_files),
+    };
+    await fs.mkdir(p.dir, { recursive: true });
+    await fs.writeFile(p.handoff, JSON.stringify(handoff, null, 2));
+    await this.append(p, { ts: handoff.ts, type: "handoff", title: "Session handoff", body: summary });
+    return { content: [{ type: "text", text: `Handoff saved for ${p.slug}\nNext steps: ${handoff.next_steps.length}, open questions: ${handoff.open_questions.length}, active files: ${handoff.active_files.length}` }] };
+  }
+
+  async resume({ dir, recent = 8 }) {
+    const p = this.paths(dir);
+    let handoff = null;
+    try { handoff = JSON.parse(await fs.readFile(p.handoff, "utf8")); } catch { /* none */ }
+    const entries = await this.readEntries(p, Math.max(1, Math.min(50, recent)));
+
+    if (!handoff && entries.length === 0) {
+      return { content: [{ type: "text", text: `No journal for ${p.slug} yet. Use journal_handoff / journal_log to start.` }] };
+    }
+
+    const out = [`# Resume: ${p.slug}`, `Project path: ${p.root}`];
+    if (handoff) {
+      out.push(`\n## Latest handoff (${handoff.ts})`);
+      out.push(handoff.summary);
+      if (handoff.next_steps?.length) out.push(`\n### Next steps\n` + handoff.next_steps.map((s, i) => `${i + 1}. ${s}`).join("\n"));
+      if (handoff.open_questions?.length) out.push(`\n### Open questions\n` + handoff.open_questions.map((s) => `- ${s}`).join("\n"));
+      if (handoff.active_files?.length) out.push(`\n### Active files\n` + handoff.active_files.map((s) => `- ${s}`).join("\n"));
+    } else {
+      out.push(`\n(No canonical handoff saved — showing recent entries only.)`);
+    }
+    if (entries.length) {
+      out.push(`\n## Recent entries`);
+      out.push(entries.map((e) => `- ${e.ts} [${e.type}] ${e.title}`).join("\n"));
+    }
+    return { content: [{ type: "text", text: out.join("\n") }] };
+  }
+
+  async timeline({ dir, limit = 20, type }) {
+    const p = this.paths(dir);
+    let entries = await this.readEntries(p, 200);
+    if (type) entries = entries.filter((e) => e.type === type);
+    entries = entries.slice(-Math.max(1, Math.min(200, limit)));
+    if (!entries.length) return { content: [{ type: "text", text: `No journal entries for ${p.slug}${type ? ` of type ${type}` : ""}.` }] };
+    const lines = entries.map((e) => `- ${e.ts} [${e.type}] ${e.title}${e.body ? `\n    ${e.body.split("\n")[0].slice(0, 120)}` : ""}`);
+    return { content: [{ type: "text", text: `Timeline for ${p.slug} (${entries.length}):\n${lines.join("\n")}` }] };
+  }
+
+  async search({ query, dir, limit = 5 }) {
+    query = clip(query, "query", 2000);
+    const p = this.paths(dir);
+    const entries = await this.readEntries(p, 200);
+    if (!entries.length) return { content: [{ type: "text", text: `No journal entries for ${p.slug}.` }] };
+
+    const want = Math.max(1, Math.min(20, limit));
+    const q = new Set((query.toLowerCase().match(/[a-z0-9_./-]{2,}/g) || []));
+    const score = (e) => {
+      let sc = 0;
+      const hay = `${e.title || ""} ${e.body || ""} ${e.type || ""}`.toLowerCase();
+      const toks = new Set(hay.match(/[a-z0-9_./-]{2,}/g) || []);
+      for (const t of q) if (toks.has(t)) sc += 1;
+      return sc;
+    };
+
+    let ranked = entries.map((e, i) => ({ e, i, sc: score(e) }))
+      .sort((a, b) => b.sc - a.sc || b.i - a.i);
+    let pool = ranked.filter((x) => x.sc > 0).slice(0, 20);
+    let mode = "keyword";
+    if (pool.length === 0 && rerankConfig().enabled) {
+      pool = ranked.slice(0, 20); // fall back to recent for semantic-style queries
+    }
+
+    let result = pool.slice(0, want).map((x) => x.e);
+    if (rerankConfig().enabled && pool.length > 1) {
+      const cands = pool.map((x) => ({ id: String(x.i), title: x.e.title || "(no title)", snippet: x.e.body || x.e.type || "" }));
+      const order = await rerank(query, cands, want);
+      if (order) {
+        mode = "rerank";
+        const byId = new Map(pool.map((x) => [String(x.i), x.e]));
+        const picked = order.map((id) => byId.get(id)).filter(Boolean).slice(0, want);
+        if (picked.length) result = picked;
+      }
+    }
+
+    if (!result.length) return { content: [{ type: "text", text: `No relevant journal entries for "${query}" in ${p.slug}.` }] };
+    const lines = result.map((e) => `- ${e.ts} [${e.type}] ${e.title}${e.body ? `\n    ${e.body.split("\n")[0].slice(0, 160)}` : ""}`);
+    return { content: [{ type: "text", text: `Journal search for "${query}" in ${p.slug} [${mode}]:\n${lines.join("\n")}` }] };
+  }
+
+  async clearHandoff({ dir }) {
+    const p = this.paths(dir);
+    await fs.unlink(p.handoff).catch(() => {});
+    return { content: [{ type: "text", text: `Cleared handoff for ${p.slug}` }] };
+  }
+
+  async run() {
+    const t = new StdioServerTransport();
+    await this.server.connect(t);
+    console.error(`Dev Journal MCP server running on stdio (store: ${ROOT})`);
+  }
+}
+
+new DevJournalServer().run().catch(console.error);

package/devjournal/test.mjs

@@ -0,0 +1,68 @@
+import { McpClient, describe, it, assert, assertIncludes, run, tmpDir, rmrf } from "../_testkit/harness.mjs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SERVER = path.join(__dirname, "server.js");
+const STORE = tmpDir("jrnl-");
+const PROJ = "/tmp/jrnl-demo-project";
+
+const client = new McpClient(SERVER, { JOURNAL_DIR: STORE });
+
+describe("devjournal", () => {
+  it("lists expected tools", async () => {
+    const tools = await client.listTools();
+    for (const t of ["journal_log", "journal_handoff", "journal_resume", "journal_timeline", "journal_search", "journal_clear_handoff"])
+      assert(tools.includes(t), `missing ${t}`);
+  });
+
+  it("logs entries", async () => {
+    const r1 = await client.callTool("journal_log", { dir: PROJ, title: "Set up auth", type: "done", body: "login + AuthService" });
+    assertIncludes(r1.text, "Logged [done]");
+    const r2 = await client.callTool("journal_log", { dir: PROJ, title: "Refresh undecided", type: "blocker" });
+    assertIncludes(r2.text, "Logged [blocker]");
+  });
+
+  it("saves a handoff", async () => {
+    const r = await client.callTool("journal_handoff", {
+      dir: PROJ, summary: "Auth scaffolding done; wiring refresh next.",
+      next_steps: ["Implement refresh", "Add tests"],
+      open_questions: ["Cookie or header?"], active_files: ["src/auth.ts"],
+    });
+    assertIncludes(r.text, "Handoff saved");
+    assertIncludes(r.text, "Next steps: 2");
+  });
+
+  it("resume returns handoff + recent entries", async () => {
+    const r = await client.callTool("journal_resume", { dir: PROJ });
+    assertIncludes(r.text, "Latest handoff");
+    assertIncludes(r.text, "Implement refresh");
+    assertIncludes(r.text, "Cookie or header?");
+    assertIncludes(r.text, "Recent entries");
+  });
+
+  it("timeline filters by type", async () => {
+    const r = await client.callTool("journal_timeline", { dir: PROJ, type: "blocker" });
+    assertIncludes(r.text, "Refresh undecided");
+    assert(!r.text.includes("Set up auth"), "should not include done entries when filtering blocker");
+  });
+
+  it("search finds entries by keyword (offline mode)", async () => {
+    const r = await client.callTool("journal_search", { dir: PROJ, query: "auth login refresh" });
+    assertIncludes(r.text, "[keyword]");
+    assertIncludes(r.text, "Set up auth");
+  });
+
+  it("clears handoff", async () => {
+    const r = await client.callTool("journal_clear_handoff", { dir: PROJ });
+    assertIncludes(r.text, "Cleared handoff");
+    const r2 = await client.callTool("journal_resume", { dir: PROJ });
+    assert(!r2.text.includes("Latest handoff"), "handoff should be gone");
+  });
+});
+
+await client.start();
+const { fail } = await run();
+await client.stop();
+rmrf(STORE);
+process.exit(fail > 0 ? 1 : 0);

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "codex-dev-mcp-suite",
+  "version": "1.0.0",
+  "description": "Four local, file-based MCP servers for solo devs/vibecoders: persistent project memory, session handoff/resume, git-independent file checkpoints, and token-efficient project briefings. Works with any MCP client.",
+  "type": "module",
+  "license": "MIT",
+  "author": "maximalabs",
+  "homepage": "https://github.com/verrysimatupang99/codex-dev-mcp-suite#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/verrysimatupang99/codex-dev-mcp-suite.git"
+  },
+  "bugs": {
+    "url": "https://github.com/verrysimatupang99/codex-dev-mcp-suite/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "codex",
+    "claude-code",
+    "cursor",
+    "ai-memory",
+    "developer-tools",
+    "llm",
+    "context",
+    "vibecoding"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "project-memory-mcp": "bin/project-memory.mjs",
+    "devjournal-mcp": "bin/devjournal.mjs",
+    "checkpoint-mcp": "bin/checkpoint.mjs",
+    "context-pack-mcp": "bin/context-pack.mjs"
+  },
+  "scripts": {
+    "test": "node run-tests.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "files": [
+    "bin/*.mjs",
+    "project-memory/*.js",
+    "project-memory/*.mjs",
+    "project-memory/package.json",
+    "devjournal/*.js",
+    "devjournal/*.mjs",
+    "devjournal/package.json",
+    "checkpoint/*.js",
+    "checkpoint/*.mjs",
+    "checkpoint/package.json",
+    "context-pack/*.js",
+    "context-pack/*.mjs",
+    "context-pack/package.json",
+    "_testkit/*.mjs",
+    "run-tests.mjs",
+    "backfill-sessions-v2.mjs",
+    "CODEX_DEV_MCP_GUIDE.md",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ]
+}

package/project-memory/embedding.js

@@ -0,0 +1,80 @@
+/**
+ * Embedding helper for 9router (OpenAI-compatible /v1/embeddings).
+ * Degrades gracefully: returns null on any failure so callers fall back
+ * to keyword search. Never throws.
+ */
+import http from "http";
+import https from "https";
+import { URL } from "url";
+
+const BASE = process.env.LLM_BASE_URL || process.env.EMBED_URL || process.env.NINEROUTER_URL || "http://localhost:20128";
+const KEY = process.env.LLM_API_KEY || process.env.EMBED_KEY || process.env.NINEROUTER_KEY || "";
+const MODEL = process.env.EMBED_MODEL || "bm/baai/bge-m3";
+const TIMEOUT_MS = Number(process.env.EMBED_TIMEOUT_MS || 15000);
+
+export function embeddingConfig() {
+  return { base: BASE, model: MODEL, enabled: Boolean(KEY) };
+}
+
+function postJson(urlStr, payload) {
+  return new Promise((resolve) => {
+    let u;
+    try { u = new URL("/v1/embeddings", urlStr); } catch { return resolve(null); }
+    const data = Buffer.from(JSON.stringify(payload));
+    const lib = u.protocol === "https:" ? https : http;
+    const req = lib.request(
+      {
+        hostname: u.hostname,
+        port: u.port || (u.protocol === "https:" ? 443 : 80),
+        path: u.pathname,
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": data.length,
+          Authorization: `Bearer ${KEY}`,
+        },
+        timeout: TIMEOUT_MS,
+      },
+      (res) => {
+        let body = "";
+        res.on("data", (c) => (body += c));
+        res.on("end", () => {
+          if (res.statusCode !== 200) return resolve(null);
+          try { resolve(JSON.parse(body)); } catch { resolve(null); }
+        });
+      }
+    );
+    req.on("error", () => resolve(null));
+    req.on("timeout", () => { req.destroy(); resolve(null); });
+    req.write(data);
+    req.end();
+  });
+}
+
+/** Returns array of vectors aligned to inputs, or null if unavailable. */
+export async function embed(inputs) {
+  if (!KEY) return null;
+  const arr = Array.isArray(inputs) ? inputs : [inputs];
+  if (arr.length === 0) return [];
+  const json = await postJson(BASE, { model: MODEL, input: arr });
+  if (!json || !Array.isArray(json.data)) return null;
+  try {
+    const sorted = json.data.slice().sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+    const vecs = sorted.map((d) => d.embedding);
+    if (vecs.some((v) => !Array.isArray(v) || v.length === 0)) return null;
+    return vecs;
+  } catch { return null; }
+}
+
+export async function embedOne(text) {
+  const v = await embed([text]);
+  return v ? v[0] : null;
+}
+
+export function cosine(a, b) {
+  if (!a || !b || a.length !== b.length) return 0;
+  let dot = 0, na = 0, 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]; }
+  if (na === 0 || nb === 0) return 0;
+  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}

package/project-memory/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "project-memory-mcp",
+  "version": "1.0.0",
+  "description": "Per-directory memory + indexing MCP server (Obsidian-style vault + Context7-style recall)",
+  "type": "module",
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js",
+    "test": "node test.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}

package/project-memory/rerank.js

@@ -0,0 +1,89 @@
+/**
+ * LLM reranker via 9router chat models (e.g. Kiro kr/claude-haiku-4.5).
+ * Used when embeddings are unavailable: keyword prefilter -> LLM picks the
+ * most relevant candidates. Degrades gracefully: returns null on any failure
+ * so callers fall back to keyword ordering. Never throws.
+ */
+import http from "http";
+import https from "https";
+import { URL } from "url";
+
+const BASE = process.env.LLM_BASE_URL || process.env.RERANK_URL || process.env.NINEROUTER_URL || "http://localhost:20128";
+const KEY = process.env.LLM_API_KEY || process.env.RERANK_KEY || process.env.NINEROUTER_KEY || "";
+const MODEL = process.env.RERANK_MODEL || "kr/claude-haiku-4.5";
+const TIMEOUT_MS = Number(process.env.RERANK_TIMEOUT_MS || 30000);
+const ENABLED = process.env.RERANK_ENABLED !== "0";
+
+export function rerankConfig() {
+  return { base: BASE, model: MODEL, enabled: Boolean(KEY) && ENABLED };
+}
+
+function chat(messages) {
+  return new Promise((resolve) => {
+    if (!KEY || !ENABLED) return resolve(null);
+    let u;
+    try { u = new URL("/v1/chat/completions", BASE); } catch { return resolve(null); }
+    const payload = Buffer.from(JSON.stringify({ model: MODEL, stream: false, temperature: 0, max_tokens: 200, messages }));
+    const lib = u.protocol === "https:" ? https : http;
+    const req = lib.request(
+      {
+        hostname: u.hostname,
+        port: u.port || (u.protocol === "https:" ? 443 : 80),
+        path: u.pathname,
+        method: "POST",
+        headers: { "Content-Type": "application/json", "Content-Length": payload.length, Authorization: `Bearer ${KEY}` },
+        timeout: TIMEOUT_MS,
+      },
+      (res) => {
+        let body = "";
+        res.on("data", (c) => (body += c));
+        res.on("end", () => {
+          if (res.statusCode !== 200) return resolve(null);
+          // handle plain JSON or SSE stream just in case
+          try {
+            const j = JSON.parse(body);
+            return resolve(j?.choices?.[0]?.message?.content ?? null);
+          } catch { /* maybe SSE */ }
+          try {
+            let acc = "";
+            for (const line of body.split("\n")) {
+              const t = line.trim();
+              if (!t.startsWith("data:")) continue;
+              const d = t.slice(5).trim();
+              if (d === "[DONE]") break;
+              const j = JSON.parse(d);
+              acc += j?.choices?.[0]?.delta?.content || j?.choices?.[0]?.message?.content || "";
+            }
+            return resolve(acc || null);
+          } catch { return resolve(null); }
+        });
+      }
+    );
+    req.on("error", () => resolve(null));
+    req.on("timeout", () => { req.destroy(); resolve(null); });
+    req.write(payload);
+    req.end();
+  });
+}
+
+/**
+ * Given a query and candidates [{id, title, snippet}], ask the model to return
+ * the ids ordered by relevance. Returns an array of ids, or null on failure.
+ */
+export async function rerank(query, candidates, topK = 5) {
+  if (!KEY || !ENABLED || !candidates || candidates.length === 0) return null;
+  const list = candidates.map((c, i) => `[${i + 1}] (id:${c.id}) ${c.title}\n    ${String(c.snippet || "").replace(/\s+/g, " ").slice(0, 200)}`).join("\n");
+  const sys = "You are a search reranker. Given a user query and a numbered list of notes, return the most relevant notes ordered best-first. Respond with ONLY a comma-separated list of the bracket numbers, e.g. 3,1,5. No prose.";
+  const user = `Query: ${query}\n\nNotes:\n${list}\n\nReturn the top ${topK} bracket numbers, best first, comma-separated:`;
+  const out = await chat([{ role: "system", content: sys }, { role: "user", content: user }]);
+  if (!out) return null;
+  const nums = (out.match(/\d+/g) || []).map(Number).filter((n) => n >= 1 && n <= candidates.length);
+  if (nums.length === 0) return null;
+  const seen = new Set();
+  const ordered = [];
+  for (const n of nums) {
+    const id = candidates[n - 1]?.id;
+    if (id && !seen.has(id)) { seen.add(id); ordered.push(id); }
+  }
+  return ordered.length ? ordered : null;
+}