@sksoftofficial/mindroot 1.0.0

package/src/markdown.js

@@ -0,0 +1,72 @@
+export function parseMarkdown(raw) {
+  const lines = raw.split("\n");
+  let start = 0;
+  let frontmatter = null;
+  if ((lines[0] ?? "").trim() === "---") {
+    const end = lines.findIndex((l, j) => j > 0 && l.trim() === "---");
+    if (end !== -1) {
+      frontmatter = lines.slice(0, end + 1).join("\n");
+      start = end + 1;
+    }
+  }
+  const heads = [];
+  for (let j = start; j < lines.length; j++) {
+    const m = lines[j].match(/^(#{1,6})\s+(.+?)\s*#*\s*$/);
+    if (m) heads.push({ line: j, level: m[1].length, title: m[2].trim() });
+  }
+  const bounds = [...heads.map((h) => h.line), lines.length];
+  const sections = [];
+  if (!heads.length || heads[0].line > start) {
+    const endIdx = heads.length ? heads[0].line : lines.length;
+    const body = trimBlank(lines.slice(start, endIdx));
+    if (body.length) {
+      sections.push({
+        level: 0,
+        title: "",
+        path: "",
+        bodyStart: start,
+        bodyEnd: endIdx,
+        body: body.join("\n"),
+      });
+    }
+  }
+  const stack = [];
+  heads.forEach((h, k) => {
+    while (stack.length && stack[stack.length - 1].level >= h.level) stack.pop();
+    stack.push(h);
+    const bodyLines = trimBlank(lines.slice(h.line + 1, bounds[k + 1]));
+    sections.push({
+      level: h.level,
+      title: h.title,
+      path: stack.filter((s) => s.level > 1).map((s) => s.title).join("::"),
+      bodyStart: h.line + 1,
+      bodyEnd: bounds[k + 1],
+      body: bodyLines.join("\n"),
+    });
+  });
+  return { frontmatter, sections };
+}
+
+function trimBlank(arr) {
+  let a = 0;
+  let b = arr.length;
+  while (a < b && !arr[a].trim()) a++;
+  while (b > a && !arr[b - 1].trim()) b--;
+  return arr.slice(a, b);
+}
+
+export function docTitle(parsed, fileName) {
+  const h1 = parsed.sections.find((s) => s.level === 1);
+  if (h1) return h1.title;
+  if (parsed.frontmatter) {
+    const m = parsed.frontmatter.match(/^title:\s*(.+)$/m);
+    if (m) return m[1].trim().replace(/^["']|["']$/g, "");
+  }
+  return fileName.replace(/\.md$/, "");
+}
+
+export function replaceSectionBody(raw, sec, newBody) {
+  const lines = raw.split("\n");
+  const replacement = newBody.replace(/\n+$/, "").split("\n");
+  return [...lines.slice(0, sec.bodyStart), ...replacement, ...lines.slice(sec.bodyEnd)].join("\n");
+}

package/src/mcp.js

@@ -0,0 +1,216 @@
+const SERVER_INFO = { name: "mindroot", version: "0.2.0" };
+const PROTOCOL_VERSION = "2025-06-18";
+
+export function tools() {
+  return [
+    {
+      name: "mindroot_list_projects",
+      description: "List all projects known to mindroot with their note and memory counts. Use to discover valid project slugs before calling project-scoped tools.",
+      inputSchema: { type: "object", properties: {} },
+    },
+    {
+      name: "mindroot_search_projects",
+      description:
+        "Find projects by fuzzy name. Matches project slugs semantically and by token overlap (e.g. 'mem-agent-mcp' finds 'proper-agent-memory'). Use to discover the right project slug before calling project-scoped tools.",
+      inputSchema: {
+        type: "object",
+        properties: { query: { type: "string", description: "Project name, full or partial/fuzzy" } },
+        required: ["query"],
+      },
+    },
+    {
+      name: "mindroot_search_memories",
+      description:
+        "Search a project's memories — short, retrieval-optimized notes about durable facts, conventions, decisions, and gotchas. Hybrid semantic + keyword ranking. Use before exploring a codebase or asking the user things that may already be remembered. Hits include ids usable with mindroot_delete_memory.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          project: { type: "string", description: "Project slug to search in" },
+          query: { type: "string", description: "Natural language search query" },
+          limit: { type: "number", description: "Max results (default 8)" },
+        },
+        required: ["project", "query"],
+      },
+    },
+    {
+      name: "mindroot_search_notes",
+      description:
+        "Search a project's note sections — detailed markdown documentation parsed from headings. Hybrid semantic ranking. Returns the note path and section each hit comes from; follow up with mindroot_read_note for full content.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          project: { type: "string", description: "Project slug to search in" },
+          query: { type: "string", description: "Natural language search query" },
+          limit: { type: "number", description: "Max results (default 8)" },
+        },
+        required: ["project", "query"],
+      },
+    },
+    {
+      name: "mindroot_save_memory",
+      description:
+        "Save a memory — a short, retrieval-optimized text about a durable fact, convention, decision, or gotcha for a project. Optionally link it to a note path ('notes/foo.md') or section ('notes/foo.md::Heading::Subheading'). Write memories so they answer 'when would someone need this'.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          project: { type: "string" },
+          text: { type: "string" },
+          target_path: { type: "string", description: "Optional link target: 'path.md' or 'path.md::Heading'" },
+        },
+        required: ["project", "text"],
+      },
+    },
+    {
+      name: "mindroot_delete_memory",
+      description: "Delete a memory by id. Use to dedupe or remove stale entries. Ids come from mindroot_search_memories hits.",
+      inputSchema: {
+        type: "object",
+        properties: { project: { type: "string" }, id: { type: "number" } },
+        required: ["project", "id"],
+      },
+    },
+    {
+      name: "mindroot_list_notes",
+      description: "List all memory notes for a project with their titles and section paths.",
+      inputSchema: {
+        type: "object",
+        properties: { project: { type: "string" } },
+        required: ["project"],
+      },
+    },
+    {
+      name: "mindroot_read_note",
+      description:
+        "Read the full content of a memory note. Verifies file integrity first and re-indexes automatically if the file was edited externally.",
+      inputSchema: {
+        type: "object",
+        properties: { project: { type: "string" }, path: { type: "string", description: "Note path relative to the project, e.g. 'architecture.md'" } },
+        required: ["project", "path"],
+      },
+    },
+    {
+      name: "mindroot_save_note",
+      description:
+        "Create or fully overwrite a markdown memory note. Sections are parsed from headings (# .. ######) and become individually searchable via mindroot_search_notes. After saving, consider saving 1-3 linked memories (mindroot_save_memory with target_path) so key facts surface in memory searches.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          project: { type: "string" },
+          path: { type: "string", description: "Note path ending in .md" },
+          content: { type: "string", description: "Full markdown content" },
+        },
+        required: ["project", "path", "content"],
+      },
+    },
+    {
+      name: "mindroot_update_section",
+      description:
+        "Replace the body of one heading-section inside an existing note, leaving the rest of the file untouched.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          project: { type: "string" },
+          path: { type: "string" },
+          heading_path: { type: "string", description: "Section address like 'Architecture::Storage' (heading titles joined by ::)" },
+          content: { type: "string", description: "New body text for this section" },
+        },
+        required: ["project", "path", "heading_path", "content"],
+      },
+    },
+    {
+      name: "mindroot_delete_note",
+      description: "Delete a memory note and its sections index entries.",
+      inputSchema: {
+        type: "object",
+        properties: { project: { type: "string" }, path: { type: "string" } },
+        required: ["project", "path"],
+      },
+    },
+  ];
+}
+
+async function callTool(db, name, args) {
+  const core = await import("./core.js");
+  switch (name) {
+    case "mindroot_list_projects":
+      return core.listProjects(db);
+    case "mindroot_search_projects":
+      return core.searchProjects(db, args.query);
+    case "mindroot_search_memories":
+      return core.searchMemories(db, args.project, args.query, args.limit ?? 8);
+    case "mindroot_search_notes":
+      return core.searchNotes(db, args.project, args.query, args.limit ?? 8);
+    case "mindroot_save_memory":
+      return core.addMemory(db, args.project, args.text, args.target_path);
+    case "mindroot_delete_memory":
+      return core.deleteMemory(db, args.project, Number(args.id));
+    case "mindroot_list_notes":
+      return core.listDocs(db, args.project);
+    case "mindroot_read_note":
+      return core.readNote(db, args.project, args.path);
+    case "mindroot_save_note":
+      return core.saveNote(db, args.project, args.path, args.content);
+    case "mindroot_update_section":
+      return core.updateSection(db, args.project, args.path, args.heading_path, args.content);
+    case "mindroot_delete_note":
+      return core.deleteNote(db, args.project, args.path);
+    default:
+      throw new Error(`unknown tool: ${name}`);
+  }
+}
+
+export async function handleRpc(db, rpc) {
+  if (!rpc || typeof rpc !== "object") {
+    return { status: 400, body: jsonRpcError(null, -32600, "invalid request") };
+  }
+  if (rpc.id === undefined || rpc.id === null) {
+    return { status: 202, body: null };
+  }
+  try {
+    let result;
+    switch (rpc.method) {
+      case "initialize": {
+        result = {
+          protocolVersion: rpc.params?.protocolVersion ?? PROTOCOL_VERSION,
+          capabilities: { tools: {} },
+          serverInfo: SERVER_INFO,
+        };
+        break;
+      }
+      case "ping": {
+        result = {};
+        break;
+      }
+      case "tools/list": {
+        result = { tools: tools() };
+        break;
+      }
+      case "tools/call": {
+        const { name, arguments: args } = rpc.params ?? {};
+        try {
+          const data = await callTool(db, name, args ?? {});
+          result = { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        } catch (err) {
+          return {
+            status: 200,
+            body: {
+              jsonrpc: "2.0",
+              id: rpc.id,
+              result: { content: [{ type: "text", text: String(err.message) }], isError: true },
+            },
+          };
+        }
+        break;
+      }
+      default:
+        return { status: 200, body: jsonRpcError(rpc.id, -32601, `method not found: ${rpc.method}`) };
+    }
+    return { status: 200, body: { jsonrpc: "2.0", id: rpc.id, result } };
+  } catch (err) {
+    return { status: 200, body: jsonRpcError(rpc.id, -32603, String(err.message)) };
+  }
+}
+
+function jsonRpcError(id, code, message) {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}

package/src/paths.js

@@ -0,0 +1,38 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import crypto from "node:crypto";
+
+export const MINDROOT_DIR = process.env.MINDROOT_DIR ?? path.join(os.homedir(), ".mindroot");
+export const MODELS_DIR = path.join(MINDROOT_DIR, "models");
+export const NOTES_DIR = path.join(MINDROOT_DIR, "notes");
+export const DB_PATH = path.join(MINDROOT_DIR, "mindroot.db");
+export const CONFIG_PATH = path.join(MINDROOT_DIR, "config.json");
+
+export const ONNX_MODEL_ID = "onnx-community/embeddinggemma-300m-ONNX";
+export const EMBED_DIM = 768;
+export const DEFAULT_PORT = 7620;
+
+export function loadConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+export function saveConfig(cfg) {
+  fs.mkdirSync(MINDROOT_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n");
+}
+
+export function ensureConfig() {
+  const cfg = loadConfig();
+  const created = !cfg.apiKey;
+  if (created) {
+    cfg.apiKey = crypto.randomBytes(24).toString("hex");
+  }
+  cfg.port = cfg.port ?? DEFAULT_PORT;
+  if (created || !loadConfig().port) saveConfig(cfg);
+  return { cfg, created };
+}

package/src/search.js

@@ -0,0 +1,196 @@
+import { embedQuery, embedDoc } from "./embedder.js";
+import { ONNX_MODEL_ID } from "./paths.js";
+
+function toFloat32(buf) {
+  const ab = buf instanceof Uint8Array ? buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength) : buf;
+  return new Float32Array(ab);
+}
+
+function cosine(a, b) {
+  let dot = 0;
+  for (let i = 0; i < a.length; i++) dot += a[i] * b[i];
+  return dot;
+}
+
+function ftsQuery(query) {
+  const terms = query.trim().split(/\s+/).filter(Boolean).slice(0, 8);
+  if (!terms.length) return null;
+  return terms.map((t) => `"${t.replace(/"/g, '""')}"`).join(" OR ");
+}
+
+function tokenize(s) {
+  return s.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+}
+
+function slugBonus(slug, queryTokens) {
+  if (!queryTokens.length) return 0;
+  const slugTokens = tokenize(slug);
+  let matched = 0;
+  for (const qt of queryTokens) {
+    if (
+      slugTokens.some(
+        (st) =>
+          st === qt ||
+          (qt.length >= 3 && st.length >= 3 && (st.startsWith(qt) || qt.startsWith(st))),
+      )
+    )
+      matched++;
+  }
+  return matched / queryTokens.length;
+}
+
+export async function searchProjects(db, query) {
+  await backfillProjectVectors(db);
+  return rankProjects(db, await embedQuery(query), query);
+}
+
+export function rankProjects(db, qvec, query) {
+  const queryTokens = tokenize(query);
+
+  const projects = db
+    .prepare(
+      `SELECT p.id, p.slug, pe.vec
+       FROM projects p
+       LEFT JOIN project_embeddings pe ON pe.project_id = p.id`,
+    )
+    .all();
+
+  const hits = [];
+  for (const p of projects) {
+    const cos = p.vec ? cosine(qvec, toFloat32(p.vec)) : 0;
+    const bonus = slugBonus(p.slug, queryTokens);
+    const score = bonus > 0 ? Math.max(cos, 0.55 + 0.4 * bonus) : cos;
+    if (bonus > 0 || score >= 0.5) {
+      hits.push({ kind: "project", id: p.id, project: p.slug, score });
+    }
+  }
+  hits.sort((a, b) => b.score - a.score);
+  return hits;
+}
+
+export async function backfillProjectVectors(db) {
+  const projects = db
+    .prepare(
+      `SELECT p.id, p.slug FROM projects p
+       LEFT JOIN project_embeddings pe ON pe.project_id = p.id
+       WHERE pe.project_id IS NULL`,
+    )
+    .all();
+  for (const p of projects) {
+    const vec = await embedDoc(p.slug);
+    db.prepare(
+      "INSERT INTO project_embeddings (project_id, dim, model, vec) VALUES (?, ?, ?, ?)",
+    ).run(p.id, vec.length, ONNX_MODEL_ID, Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength));
+  }
+}
+
+export async function searchMemories(db, projectId, query, limit = 8) {
+  return rankMemories(db, projectId, await embedQuery(query), query, limit);
+}
+
+export function rankMemories(db, projectId, qvec, query, limit = 8) {
+  const rows = db
+    .prepare(
+      `SELECT e.owner_id, e.vec, m.text AS mtext, m.target_path, m.updated_at
+       FROM embeddings e
+       JOIN memories m ON m.id = e.owner_id
+       WHERE e.owner_type = 'memory' AND m.project_id = $pid`,
+    )
+    .all({ pid: projectId });
+
+  const byId = new Map();
+  for (const row of rows) {
+    const vec = toFloat32(row.vec);
+    if (vec.length !== qvec.length) continue;
+    byId.set(row.owner_id, {
+      kind: "memory",
+      id: row.owner_id,
+      text: row.mtext,
+      target: row.target_path,
+      doc_title: null,
+      score: cosine(qvec, vec),
+      updated_at: row.updated_at,
+    });
+  }
+
+  applyFts(db, projectId, query, byId);
+
+  return rank(byId, limit);
+}
+
+function applyFts(db, projectId, query, byId) {
+  const fq = ftsQuery(query);
+  if (!fq) return;
+  try {
+    const ftsRows = db
+      .prepare(
+        `SELECT rowid, bm25(memories_fts) AS rank FROM memories_fts WHERE memories_fts MATCH ? ORDER BY rank LIMIT 50`,
+      )
+      .all(fq);
+    const ranks = new Map();
+    let maxRank = 0;
+    for (const r of ftsRows) {
+      const norm = -r.rank;
+      if (norm > maxRank) maxRank = norm;
+      ranks.set(r.rowid, norm);
+    }
+    if (!ranks.size) return;
+    const allowed = new Set(
+      db
+        .prepare(`SELECT id FROM memories WHERE project_id = ? AND id IN (${[...ranks.keys()].map(() => "?").join(",")})`)
+        .all(projectId, ...ranks.keys())
+        .map((r) => r.id),
+    );
+    for (const [rid, rank] of ranks) {
+      if (!allowed.has(rid)) continue;
+      const hit = byId.get(rid);
+      if (hit) hit.fts = maxRank ? rank / maxRank : 1;
+    }
+  } catch {
+    // malformed query — keyword layer skipped, vector results still returned
+  }
+}
+
+export async function searchNotes(db, projectId, query, limit = 8) {
+  return rankNotes(db, projectId, await embedQuery(query), limit);
+}
+
+export function rankNotes(db, projectId, qvec, limit = 8) {
+  const rows = db
+    .prepare(
+      `SELECT e.owner_id, e.vec,
+              s.content AS scontent, s.heading_path, s.updated_at AS sut,
+              d.rel_path, d.title AS dtitle
+       FROM embeddings e
+       JOIN sections s ON s.id = e.owner_id
+       JOIN docs d ON d.id = s.doc_id
+       WHERE e.owner_type = 'section' AND d.project_id = $pid`,
+    )
+    .all({ pid: projectId });
+
+  const byId = new Map();
+  for (const row of rows) {
+    const vec = toFloat32(row.vec);
+    if (vec.length !== qvec.length) continue;
+    byId.set(row.owner_id, {
+      kind: "note_section",
+      id: row.owner_id,
+      text: row.scontent?.slice(0, 300),
+      target: `${row.rel_path}::${row.heading_path}`,
+      doc_title: row.dtitle,
+      score: cosine(qvec, vec),
+      updated_at: row.sut,
+    });
+  }
+
+  return rank(byId, limit);
+}
+
+function rank(byId, limit) {
+  const scored = [...byId.values()].map((h) => ({
+    ...h,
+    score: h.score * 0.75 + (h.fts ?? 0) * 0.25,
+  }));
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, limit);
+}