@sksoftofficial/mindroot 1.0.4 → 1.0.6

package/README.md

@@ -143,7 +143,7 @@ All tools are prefixed `mindroot_`.
 | `list_notes` | `project*` | List notes with section paths |
 | `read_note` | `project*`, `path`, `section?` | Full note content, or one section's body via `section` (hash-verified, auto-reindexed) |
 | `save_note` | `project*`, `path`, `content` | Create/overwrite a note |
-| `update_section` | `project*`, `path`, `heading_path`, `content` | Replace one section body, leave the rest untouched |
+| `update_section` | `project*`, `path`, `heading_path`, `content` | Replace one section body, or append the section when missing |
 | `delete_note` | `project*`, `path` | Delete a note (clears its linked memories) |
 
 ## REST API

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sksoftofficial/mindroot",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Long-term memory for AI agents: hybrid-searched memories over human-editable markdown notes. 100% local — offline ONNX embeddings, SQLite FTS5, MCP server, REST API, CLI, dashboard. No cloud, no API keys.",
   "homepage": "https://skbilisim.com/en/projects/mindroot",
   "type": "module",

package/src/core.js

@@ -10,7 +10,7 @@ import {
   reindexDoc,
   httpError,
 } from "./indexer.js";
-import { parseMarkdown, replaceSectionBody } from "./markdown.js";
+import { appendSection, parseMarkdown, replaceSectionBody } from "./markdown.js";
 import { embedDoc } from "./embedder.js";
 import { ONNX_MODEL_ID } from "./paths.js";
 import { searchMemories as hybridSearchMemories, searchNotes as hybridSearchNotes, searchProjects } from "./search.js";
@@ -137,8 +137,9 @@ export async function updateSection(db, slug, relPath, headingPath, newContent)
   const { content } = await verifyAndLoadDoc(db, slug, relPath);
   const parsed = parseMarkdown(content);
   const sec = parsed.sections.find((s) => s.path === headingPath);
-  if (!sec) throw httpError(404, `section not found: ${headingPath}`);
-  const updated = replaceSectionBody(content, sec, newContent);
+  const updated = sec
+    ? replaceSectionBody(content, sec, newContent)
+    : appendSection(content, headingPath, newContent);
   return saveNote(db, slug, relPath, updated);
 }
 

package/src/markdown.js

@@ -70,3 +70,9 @@ export function replaceSectionBody(raw, sec, newBody) {
   const replacement = newBody.replace(/\n+$/, "").split("\n");
   return [...lines.slice(0, sec.bodyStart), ...replacement, ...lines.slice(sec.bodyEnd)].join("\n");
 }
+
+export function appendSection(raw, headingPath, body) {
+  const note = raw.replace(/\n+$/, "");
+  const content = body.replace(/\n+$/, "");
+  return `${note ? `${note}\n\n` : ""}## ${headingPath}${content ? `\n\n${content}` : ""}\n`;
+}

package/src/mcp.js

@@ -4,12 +4,12 @@ const PROTOCOL_VERSION = "2025-06-18";
 export function tools() {
   return [
     {
-      name: "mindroot_list_projects",
+      name: "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",
+      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,9 +121,9 @@ export function tools() {
       },
     },
     {
-      name: "mindroot_update_section",
+      name: "update_section",
       description:
-        "Replace the body of one heading-section inside an existing note, leaving the rest of the file untouched.",
+        "Replace the body of an existing heading-section, or append it to the note when missing.",
       inputSchema: {
         type: "object",
         properties: {
@@ -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",
@@ -150,29 +150,29 @@ export function tools() {
 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);
     default:
       throw new Error(`unknown tool: ${name}`);

package/test/markdown.test.js

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { parseMarkdown, docTitle, replaceSectionBody } from "../src/markdown.js";
+import { appendSection, parseMarkdown, docTitle, replaceSectionBody } from "../src/markdown.js";
 
 test("parseMarkdown builds nested heading paths and excludes H1", () => {
   const md = "# Title\n\nintro\n\n## Arch\n\ntop\n\n### Arch::Storage\n\nnested\n";
@@ -30,3 +30,8 @@ test("replaceSectionBody splices only the target section", () => {
   assert.match(out, /keep me/);
   assert.match(out, /^# T/);
 });
+
+test("appendSection adds a missing section at the end", () => {
+  const md = "# T\n\n## Existing\n\nkeep me\n";
+  assert.equal(appendSection(md, "Added", "new body"), `${md}\n## Added\n\nnew body\n`);
+});

package/test/mcp.test.js

@@ -10,18 +10,18 @@ let db;
 let open;
 
 const EXPECTED_TOOLS = [
-  "mindroot_list_projects",
-  "mindroot_search_projects",
-  "mindroot_rename_project",
-  "mindroot_search_memories",
-  "mindroot_search_notes",
-  "mindroot_save_memory",
-  "mindroot_delete_memory",
-  "mindroot_list_notes",
-  "mindroot_read_note",
-  "mindroot_save_note",
-  "mindroot_update_section",
-  "mindroot_delete_note",
+  "list_projects",
+  "search_projects",
+  "rename_project",
+  "search_memories",
+  "search_notes",
+  "save_memory",
+  "delete_memory",
+  "list_notes",
+  "read_note",
+  "save_note",
+  "update_section",
+  "delete_note",
 ];
 
 before(async () => {
@@ -58,19 +58,19 @@ test("unknown tool returns clean error", async () => {
 });
 
 test("search without project is a clean isError", async () => {
-  const res = await call("mindroot_search_memories", { query: "x" });
+  const res = await call("search_memories", { query: "x" });
   assert.equal(res.body.result.isError, true);
   assert.match(res.body.result.content[0].text, /project is required/);
 });
 
 test("invalid slug is rejected before any lookup", async () => {
-  const res = await call("mindroot_search_memories", { project: "../evil", query: "x" });
+  const res = await call("search_memories", { project: "../evil", query: "x" });
   assert.equal(res.body.result.isError, true);
   assert.match(res.body.result.content[0].text, /invalid project slug/);
 });
 
 test("unknown project is a clean error", async () => {
-  const res = await call("mindroot_search_memories", { project: "ghost", query: "x" });
+  const res = await call("search_memories", { project: "ghost", query: "x" });
   assert.match(res.body.result.content[0].text, /unknown project: ghost/);
 });
 
@@ -89,23 +89,43 @@ test("rename_project moves slug, dir, and embeddings", async () => {
   fs.mkdirSync(path.join(NOTES_DIR, "old-name"), { recursive: true });
   fs.writeFileSync(path.join(NOTES_DIR, "old-name", "overview.md"), "# Old\n");
 
-  const res = await call("mindroot_rename_project", { project: "old-name", new_slug: "new-name" });
+  const res = await call("rename_project", { project: "old-name", new_slug: "new-name" });
   const data = JSON.parse(res.body.result.content[0].text);
   assert.deepEqual(data.renamed, { from: "old-name", to: "new-name" });
   assert.equal(db.prepare("SELECT slug FROM projects WHERE id = ?").get(pid).slug, "new-name");
   assert.ok(fs.existsSync(path.join(NOTES_DIR, "new-name", "overview.md")));
   assert.ok(!fs.existsSync(path.join(NOTES_DIR, "old-name")));
   assert.equal(db.prepare("SELECT COUNT(*) n FROM project_embeddings WHERE project_id = ?").get(pid).n, 0);
-  const listed = JSON.parse((await call("mindroot_list_projects", {})).body.result.content[0].text);
+  const listed = JSON.parse((await call("list_projects", {})).body.result.content[0].text);
   const row = listed.find((p) => p.slug === "new-name");
   assert.equal(row.memories, 1);
   assert.ok(!listed.some((p) => p.slug === "old-name"));
 
-  const dup = await call("mindroot_rename_project", { project: "new-name", new_slug: "new-name" });
+  const dup = await call("rename_project", { project: "new-name", new_slug: "new-name" });
   assert.equal(dup.body.result.isError, true);
   assert.match(dup.body.result.content[0].text, /already named/);
 
-  const bad = await call("mindroot_rename_project", { project: "new-name", new_slug: "../evil" });
+  const bad = await call("rename_project", { project: "new-name", new_slug: "../evil" });
   assert.equal(bad.body.result.isError, true);
   assert.match(bad.body.result.content[0].text, /invalid project slug/);
 });
+
+test("update_section appends a missing section", async () => {
+  await call("save_note", {
+    project: "section-upsert",
+    path: "note.md",
+    content: "# Note\n\n## Existing\n\nkeep me\n",
+  });
+
+  const res = await call("update_section", {
+    project: "section-upsert",
+    path: "note.md",
+    heading_path: "Added",
+    content: "new body",
+  });
+  assert.equal(res.body.result.isError, undefined);
+
+  const note = JSON.parse(res.body.result.content[0].text);
+  assert.equal(note.content, "# Note\n\n## Existing\n\nkeep me\n\n## Added\n\nnew body\n");
+  assert.ok(note.sections.some((section) => section.path === "Added"));
+});