@sksoftofficial/mindroot 1.0.5 → 1.1.0

package/src/mcp.js

@@ -4,12 +4,12 @@ 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.",
+      name: "list_projects",
+      description: "List all projects known to mindroot with their note, memory, and skill counts. Use to discover valid project slugs before calling project-scoped tools.",
       inputSchema: { type: "object", properties: {} },
     },
     {
-      name: "mindroot_search_projects",
+      name: "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: {
@@ -19,7 +19,7 @@ export function tools() {
       },
     },
     {
-      name: "mindroot_rename_project",
+      name: "rename_project",
       description:
         "Rename a project by slug. Moves its notes directory and updates the slug; notes, memories, and search indexes are preserved under the internal project id. The fuzzy-search vector for the new slug is rebuilt automatically on the next project search.",
       inputSchema: {
@@ -32,7 +32,7 @@ export function tools() {
       },
     },
     {
-      name: "mindroot_search_memories",
+      name: "search_memories",
       description:
         "Search a project's memories — short, retrieval-optimized notes about durable facts, conventions, decisions, and gotchas. This is mindroot's primary semantic search layer (hybrid vector + keyword). Use before exploring a codebase or asking the user things that may already be remembered; mindroot_search_notes is only a literal string fallback. Hits include ids usable with mindroot_delete_memory.",
       inputSchema: {
@@ -46,7 +46,7 @@ export function tools() {
       },
     },
     {
-      name: "mindroot_search_notes",
+      name: "search_notes",
       description:
         "Literal case-insensitive string search over a project's note sections — no semantics. Memories are the semantic index: prefer mindroot_search_memories first and use this only as a fallback or to locate exact keywords/identifiers inside notes. Returns the note path and heading section per hit; fetch just that section with mindroot_read_note's section argument.",
       inputSchema: {
@@ -60,7 +60,7 @@ export function tools() {
       },
     },
     {
-      name: "mindroot_save_memory",
+      name: "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: {
@@ -74,7 +74,7 @@ export function tools() {
       },
     },
     {
-      name: "mindroot_delete_memory",
+      name: "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",
@@ -83,7 +83,7 @@ export function tools() {
       },
     },
     {
-      name: "mindroot_list_notes",
+      name: "list_notes",
       description:
         "List all memory notes for a project with their titles and section heading paths. Use this to see a note's section layout, then read only the section you need via mindroot_read_note's section argument instead of fetching the whole note.",
       inputSchema: {
@@ -93,7 +93,7 @@ export function tools() {
       },
     },
     {
-      name: "mindroot_read_note",
+      name: "read_note",
       description:
         "Read a memory note. Without `section`, returns full content plus the section list. With `section` (a heading path like 'Architecture::Storage' from mindroot_list_notes or mindroot_search_notes targets), returns only that section's body — prefer this when you don't need the whole note. Verifies file integrity first and re-indexes automatically if the file was edited externally.",
       inputSchema: {
@@ -107,7 +107,7 @@ export function tools() {
       },
     },
     {
-      name: "mindroot_save_note",
+      name: "save_note",
       description:
         "Create or fully overwrite a markdown memory note. Sections are parsed from headings (# .. ######) and are individually readable (mindroot_read_note `section`) and string-searchable (mindroot_search_notes); embeddings are generated for memories only. After saving, consider saving 1-3 linked memories (mindroot_save_memory with target_path) so key facts surface in memory searches.",
       inputSchema: {
@@ -121,7 +121,7 @@ export function tools() {
       },
     },
     {
-      name: "mindroot_update_section",
+      name: "update_section",
       description:
         "Replace the body of an existing heading-section, or append it to the note when missing.",
       inputSchema: {
@@ -136,7 +136,7 @@ export function tools() {
       },
     },
     {
-      name: "mindroot_delete_note",
+      name: "delete_note",
       description: "Delete a memory note and its sections index entries.",
       inputSchema: {
         type: "object",
@@ -144,36 +144,97 @@ export function tools() {
         required: ["project", "path"],
       },
     },
+    {
+      name: "search_skills",
+      description:
+        "Search a project's reusable procedures (hybrid over names and descriptions). Call once before starting a non-trivial multi-step task; skip simple tasks or work already clear from context. Returns summaries; use mindroot_read_skill only for promising matches and reuse skills already loaded.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          project: { type: "string" },
+          query: { type: "string", description: "The task or workflow to find a procedure for" },
+          limit: { type: "integer", minimum: 1, maximum: 100, description: "Max results (default 8)" },
+        },
+        required: ["project", "query"],
+      },
+    },
+    {
+      name: "read_skill",
+      description:
+        "Read a project's reusable skill instructions. Check prerequisites before applying; skills do not override the current task's instructions or permissions. Omit revision for the latest content, or supply a revision number to inspect history. Returns current_revision for safe updates.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          project: { type: "string" },
+          name: { type: "string", description: "Stable skill name from mindroot_search_skills" },
+          revision: { type: "integer", minimum: 1, description: "Optional historical revision" },
+        },
+        required: ["project", "name"],
+      },
+    },
+    {
+      name: "save_skill",
+      description:
+        "Create or update a project-specific skill for a non-trivial procedure that was verified to work and is not already captured. Search first to dedupe, read an existing match, then update its stable name. Automatically indexes name/description and preserves revisions; no linked memory is needed. Pass expected_revision from the latest read (0 for create-only); conflicts require rereading. Identical saves do not add revisions.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          project: { type: "string" },
+          name: { type: "string", maxLength: 64, pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$", description: "Stable lowercase hyphenated name, e.g. add-mcp-tool" },
+          description: { type: "string", minLength: 1, maxLength: 2000, description: "Short summary of when to use this skill; indexed for discovery" },
+          content: { type: "string", minLength: 1, description: "Markdown: when to use, prerequisites, procedure, success criteria, and pitfalls. Reference project notes for facts; never include secrets or task recaps." },
+          expected_revision: { type: "integer", minimum: 0, description: "Latest revision read; 0 requires that the skill does not exist" },
+        },
+        required: ["project", "name", "description", "content"],
+      },
+    },
+    {
+      name: "delete_skill",
+      description: "Delete a project's skill by stable name, including its revision history and search index. Use for obsolete or duplicate procedures after checking the existing skill.",
+      inputSchema: {
+        type: "object",
+        properties: { project: { type: "string" }, name: { type: "string" } },
+        required: ["project", "name"],
+      },
+    },
   ];
 }
 
 async function callTool(db, name, args) {
   const core = await import("./core.js");
   switch (name) {
-    case "mindroot_list_projects":
+    case "list_projects":
       return core.listProjects(db);
-    case "mindroot_search_projects":
+    case "search_projects":
       return core.searchProjects(db, args.query);
-    case "mindroot_rename_project":
+    case "rename_project":
       return core.renameProject(db, args.project, args.new_slug);
-    case "mindroot_search_memories":
+    case "search_memories":
       return core.searchMemories(db, args.project, args.query, args.limit ?? 8);
-    case "mindroot_search_notes":
+    case "search_notes":
       return core.searchNotes(db, args.project, args.query, args.limit ?? 8);
-    case "mindroot_save_memory":
+    case "save_memory":
       return core.addMemory(db, args.project, args.text, args.target_path);
-    case "mindroot_delete_memory":
+    case "delete_memory":
       return core.deleteMemory(db, args.project, Number(args.id));
-    case "mindroot_list_notes":
+    case "list_notes":
       return core.listDocs(db, args.project);
-    case "mindroot_read_note":
+    case "read_note":
       return core.readNote(db, args.project, args.path, args.section);
-    case "mindroot_save_note":
+    case "save_note":
       return core.saveNote(db, args.project, args.path, args.content);
-    case "mindroot_update_section":
+    case "update_section":
       return core.updateSection(db, args.project, args.path, args.heading_path, args.content);
-    case "mindroot_delete_note":
+    case "delete_note":
       return core.deleteNote(db, args.project, args.path);
+    case "search_skills":
+      return core.searchSkills(db, args.project, args.query, args.limit ?? 8);
+    case "read_skill":
+      return core.readSkill(db, args.project, args.name, args.revision);
+    case "save_skill":
+      return core.saveSkill(db, args.project, args.name, args.description, args.content, args.expected_revision);
+    case "delete_skill":
+      return core.deleteSkill(db, args.project, args.name);
     default:
       throw new Error(`unknown tool: ${name}`);
   }

package/src/paths.js

@@ -14,16 +14,28 @@ export const EMBED_DIM = 768;
 export const DEFAULT_PORT = 7620;
 
 export function loadConfig() {
+  let raw;
   try {
-    return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+    raw = fs.readFileSync(CONFIG_PATH, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return {};
+    throw err;
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(raw);
   } catch {
-    return {};
+    throw new Error(`invalid mindroot configuration at ${CONFIG_PATH}; fix or delete it before continuing`);
+  }
+  if (!cfg || typeof cfg !== "object" || Array.isArray(cfg)) {
+    throw new Error(`expected a JSON object in ${CONFIG_PATH}; fix or delete it before continuing`);
   }
+  return cfg;
 }
 
 export function saveConfig(cfg) {
   fs.mkdirSync(MINDROOT_DIR, { recursive: true });
-  fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n");
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
 }
 
 export function ensureConfig() {

package/src/search.js

@@ -118,6 +118,34 @@ export function rankMemories(db, projectId, qvec, query, limit = 8) {
   return rank(byId, limit);
 }
 
+export function rankSkills(db, projectId, qvec, query, limit = 8) {
+  const rows = db.prepare(
+    `SELECT s.id, s.name, s.description, s.revision, s.updated_at, e.vec
+     FROM skills s LEFT JOIN skill_embeddings e ON e.skill_id = s.id
+     WHERE s.project_id = ?`,
+  ).all(projectId);
+  const byId = new Map();
+  for (const row of rows) {
+    const vec = row.vec && toFloat32(row.vec);
+    byId.set(row.id, {
+      kind: "skill", name: row.name, description: row.description,
+      revision: row.revision, updated_at: row.updated_at,
+      score: vec?.length === qvec.length ? cosine(qvec, vec) : 0,
+    });
+  }
+  const fq = ftsQuery(query);
+  if (fq) {
+    const matches = db.prepare(
+      `SELECT s.id, bm25(skills_fts) AS rank FROM skills_fts
+       JOIN skills s ON s.id = skills_fts.rowid
+       WHERE skills_fts MATCH ? AND s.project_id = ? ORDER BY rank LIMIT 100`,
+    ).all(fq, projectId);
+    const max = Math.max(0, ...matches.map((r) => -r.rank));
+    for (const match of matches) byId.get(match.id).fts = max ? -match.rank / max : 1;
+  }
+  return rank(byId, limit);
+}
+
 function applyFts(db, projectId, query, byId) {
   const fq = ftsQuery(query);
   if (!fq) return;

package/src/server.js

@@ -12,6 +12,8 @@ const DASHBOARD = path.join(DASHBOARD_DIR, "index.html");
 const DASHBOARD_ASSETS = new Map([
   ["/favicon.png", ["favicon.png", "image/png"]],
   ["/logo.png", ["logo.png", "image/png"]],
+  ["/graph.js", ["graph.js", "text/javascript; charset=utf-8"]],
+  ["/vendor/force-graph.min.js", [fileURLToPath(new URL("./force-graph.min.js", import.meta.resolve("force-graph"))), "text/javascript; charset=utf-8"]],
 ]);
 
 export function createServer(db, cfg) {
@@ -29,10 +31,10 @@ export function createServer(db, cfg) {
 
       const asset = DASHBOARD_ASSETS.get(url.pathname);
       if (req.method === "GET" && asset) {
-        const body = await fs.readFile(path.join(DASHBOARD_DIR, asset[0]));
+        const body = await fs.readFile(path.resolve(DASHBOARD_DIR, asset[0]));
         res.writeHead(200, {
           "content-type": asset[1],
-          "cache-control": "public, max-age=86400",
+          "cache-control": asset[0] === "graph.js" ? "no-cache" : "public, max-age=86400",
         });
         res.end(body);
         return;
@@ -97,13 +99,30 @@ async function handleApi(req, res, url, db) {
     if (parts.length === 3) {
       if (req.method === "GET") {
         const project = getProjectRow(db, slug);
-        const [docs, memories] = await Promise.all([core.listDocs(db, slug), core.listMemories(db, slug)]);
-        return sendJson(res, 200, { slug, id: project.id, docs, memories });
+        const [docs, memories, skills] = await Promise.all([
+          core.listDocs(db, slug), core.listMemories(db, slug), core.listSkills(db, slug),
+        ]);
+        return sendJson(res, 200, { slug, id: project.id, docs, memories, skills });
       }
       if (req.method === "DELETE") return sendJson(res, 200, await core.deleteProject(db, slug));
       throw methodNotAllowed();
     }
 
+    if (parts[3] === "skills") {
+      if (parts.length === 4 && req.method === "GET") return sendJson(res, 200, core.listSkills(db, slug));
+      if (parts.length !== 5) throw notFound();
+      const name = decodeURIComponent(parts[4]);
+      if (req.method === "GET") {
+        const revision = url.searchParams.get("revision");
+        return sendJson(res, 200, core.readSkill(db, slug, name, revision === null ? undefined : Number(revision)));
+      }
+      if (req.method === "PUT") {
+        const body = await readJson(req);
+        return sendJson(res, 200, await core.saveSkill(db, slug, name, body.description, body.content, body.expected_revision));
+      }
+      if (req.method === "DELETE") return sendJson(res, 200, core.deleteSkill(db, slug, name));
+      throw methodNotAllowed();
+    }
     if (parts[3] === "docs") {
       if (req.method === "GET") return sendJson(res, 200, await core.listDocs(db, slug));
       throw methodNotAllowed();
@@ -153,6 +172,8 @@ async function handleApi(req, res, url, db) {
       hits = await core.searchMemories(db, body.project, body.query, limit);
     } else if (body.kind === "notes") {
       hits = await core.searchNotes(db, body.project, body.query, limit);
+    } else if (body.kind === "skills") {
+      hits = await core.searchSkills(db, body.project, body.query, limit);
     } else {
       const [memories, notes] = await Promise.all([
         core.searchMemories(db, body.project, body.query, limit),

package/src/skills.js

@@ -0,0 +1,133 @@
+import { validSlug, ensureProject, getProjectRow, httpError } from "./indexer.js";
+import { embedDoc, embedQuery } from "./embedder.js";
+import { ONNX_MODEL_ID } from "./paths.js";
+import { rankSkills } from "./search.js";
+
+function validateProject(slug) {
+  if (!slug) throw httpError(400, "project is required");
+  if (!validSlug(slug)) throw httpError(400, `invalid project slug: ${slug}`);
+}
+
+function validateName(name) {
+  if (typeof name !== "string" || name.length > 64 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
+    throw httpError(400, "skill name must be 1-64 lowercase letters/digits separated by single hyphens");
+  }
+}
+
+function validateRevision(revision, minimum) {
+  if (revision !== undefined && (!Number.isSafeInteger(revision) || revision < minimum)) {
+    throw httpError(400, `revision must be an integer >= ${minimum}`);
+  }
+}
+
+function findSkill(db, projectId, name) {
+  return db.prepare("SELECT * FROM skills WHERE project_id = ? AND name = ?").get(projectId, name);
+}
+
+function summary(row) {
+  return {
+    name: row.name,
+    description: row.description,
+    revision: row.revision,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+  };
+}
+
+export function listSkills(db, slug) {
+  validateProject(slug);
+  const project = getProjectRow(db, slug);
+  return db.prepare(
+    "SELECT name, description, revision, created_at, updated_at FROM skills WHERE project_id = ? ORDER BY name",
+  ).all(project.id);
+}
+
+export function readSkill(db, slug, name, revision) {
+  validateProject(slug);
+  validateName(name);
+  validateRevision(revision, 1);
+  const project = getProjectRow(db, slug);
+  const current = findSkill(db, project.id, name);
+  if (!current) throw httpError(404, `skill not found: ${name}`);
+  const row = revision === undefined ? current : db.prepare(
+    "SELECT description, content, revision, saved_at AS updated_at FROM skill_revisions WHERE skill_id = ? AND revision = ?",
+  ).get(current.id, revision);
+  if (!row) throw httpError(404, `skill revision not found: ${name}@${revision}`);
+  return { ...summary({ ...current, ...row }), content: row.content, current_revision: current.revision };
+}
+
+// Embed before opening the transaction; never hold a write lock during model inference.
+export async function saveSkill(db, slug, name, description, content, expectedRevision, embed = embedDoc) {
+  validateProject(slug);
+  validateName(name);
+  validateRevision(expectedRevision, 0);
+  if (typeof description !== "string" || !description.trim() || description.length > 2000) {
+    throw httpError(400, "skill description is required (maximum 2000 characters)");
+  }
+  if (typeof content !== "string" || !content.trim()) throw httpError(400, "skill content is required");
+  description = description.trim();
+  const project = db.prepare("SELECT id FROM projects WHERE slug = ?").get(slug);
+  const previous = project && findSkill(db, project.id, name);
+  const previousRevision = previous?.revision ?? 0;
+  if (expectedRevision !== undefined && expectedRevision !== previousRevision) {
+    throw httpError(409, "skill changed; read the latest revision before saving");
+  }
+  if (previous?.description === description && previous.content === content) {
+    return { ...summary(previous), unchanged: true };
+  }
+
+  const vec = await embed(`${name}\n${description}`);
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    const currentProject = db.prepare("SELECT id FROM projects WHERE slug = ?").get(slug);
+    if (project && currentProject?.id !== project.id) {
+      throw httpError(409, "project changed while saving skill; resolve the project again");
+    }
+    const target = currentProject ?? ensureProject(db, slug);
+    const current = findSkill(db, target.id, name);
+    if ((current?.revision ?? 0) !== previousRevision || current?.id !== previous?.id) {
+      throw httpError(409, "skill changed; read the latest revision before saving");
+    }
+    const now = Date.now();
+    const revision = previousRevision + 1;
+    const row = db.prepare(
+      `INSERT INTO skills (project_id, name, description, content, revision, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(project_id, name) DO UPDATE SET
+         description = excluded.description, content = excluded.content,
+         revision = excluded.revision, updated_at = excluded.updated_at
+       RETURNING *`,
+    ).get(target.id, name, description, content, revision, now, now);
+    db.prepare(
+      "INSERT INTO skill_revisions (skill_id, revision, description, content, saved_at) VALUES (?, ?, ?, ?, ?)",
+    ).run(row.id, revision, description, content, now);
+    db.prepare(
+      `INSERT INTO skill_embeddings (skill_id, dim, model, vec) VALUES (?, ?, ?, ?)
+       ON CONFLICT(skill_id) DO UPDATE SET dim = excluded.dim, model = excluded.model, vec = excluded.vec`,
+    ).run(row.id, vec.length, ONNX_MODEL_ID, Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength));
+    db.exec("COMMIT");
+    return { ...summary(row), unchanged: false };
+  } catch (err) {
+    db.exec("ROLLBACK");
+    throw err;
+  }
+}
+
+export function deleteSkill(db, slug, name) {
+  validateProject(slug);
+  validateName(name);
+  const project = getProjectRow(db, slug);
+  const result = db.prepare("DELETE FROM skills WHERE project_id = ? AND name = ?").run(project.id, name);
+  if (!result.changes) throw httpError(404, `skill not found: ${name}`);
+  return { deleted: name };
+}
+
+export async function searchSkills(db, slug, query, limit = 8) {
+  validateProject(slug);
+  if (typeof query !== "string" || !query.trim()) throw httpError(400, "query is required");
+  const project = getProjectRow(db, slug);
+  const n = Number(limit);
+  const count = Number.isFinite(n) ? Math.min(Math.max(Math.floor(n), 1), 100) : 8;
+  if (!db.prepare("SELECT 1 FROM skills WHERE project_id = ? LIMIT 1").get(project.id)) return [];
+  return rankSkills(db, project.id, await embedQuery(query), query, count);
+}

package/src/store/db.js

@@ -55,6 +55,56 @@ CREATE TABLE IF NOT EXISTS project_embeddings (
   vec BLOB NOT NULL
 );
 
+CREATE TABLE IF NOT EXISTS skills (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  description TEXT NOT NULL,
+  content TEXT NOT NULL,
+  revision INTEGER NOT NULL CHECK (revision > 0),
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  UNIQUE(project_id, name)
+);
+
+CREATE TABLE IF NOT EXISTS skill_revisions (
+  skill_id INTEGER NOT NULL REFERENCES skills(id) ON DELETE CASCADE,
+  revision INTEGER NOT NULL,
+  description TEXT NOT NULL,
+  content TEXT NOT NULL,
+  saved_at INTEGER NOT NULL,
+  PRIMARY KEY(skill_id, revision)
+);
+
+CREATE TABLE IF NOT EXISTS skill_embeddings (
+  skill_id INTEGER PRIMARY KEY REFERENCES skills(id) ON DELETE CASCADE,
+  dim INTEGER NOT NULL,
+  model TEXT NOT NULL,
+  vec BLOB NOT NULL
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS skills_fts USING fts5(
+  name,
+  description,
+  content='skills',
+  content_rowid='id'
+);
+
+CREATE TRIGGER IF NOT EXISTS skills_ai AFTER INSERT ON skills BEGIN
+  INSERT INTO skills_fts(rowid, name, description) VALUES (new.id, new.name, new.description);
+END;
+
+CREATE TRIGGER IF NOT EXISTS skills_ad AFTER DELETE ON skills BEGIN
+  INSERT INTO skills_fts(skills_fts, rowid, name, description)
+  VALUES ('delete', old.id, old.name, old.description);
+END;
+
+CREATE TRIGGER IF NOT EXISTS skills_au AFTER UPDATE OF name, description ON skills BEGIN
+  INSERT INTO skills_fts(skills_fts, rowid, name, description)
+  VALUES ('delete', old.id, old.name, old.description);
+  INSERT INTO skills_fts(rowid, name, description) VALUES (new.id, new.name, new.description);
+END;
+
 CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
   text,
   content='memories',