@sksoftofficial/mindroot 1.0.2 → 1.0.3

package/README.md

@@ -1,26 +1,60 @@
 # Mindroot
 
-Persistent two-layer memory system for AI agents. Embedding-searched **memories** over human-editable markdown **notes**, exposed through a local HTTP service with an MCP interface.
+AI agents that never forget.
 
 ![Mindroot persistent AI agent memory system](https://skbilisim.com/assets/projects/mindroot.webp)
 
-- **Notes** (Layer 2): human-editable markdown files under `~/.mindroot/notes/<project>/`, parsed into heading-addressable sections. The unit of storage.
-- **Memories** (Layer 1): short, retrieval-optimized texts linked (or standalone) that point into notes. Embedded and full-text indexed. The unit of retrieval.
-- **Search**: hybrid semantic (embeddinggemma-300m ONNX) + keyword (SQLite FTS5/bm25), strictly project-scoped. Fuzzy project-name matching included (`search_projects`).
+Mindroot is a tiny Node.js service that gives your AI agents a permanent, project-scoped memory: hybrid-searched **memories** over human-editable markdown **notes**, exposed through a local HTTP service with an MCP interface, a REST API, and a built-in dashboard. Everything runs on your machine — offline embeddings, SQLite, plain markdown files you own. No cloud, no API keys, no per-query cost.
 
 - Website: https://skbilisim.com/en/projects/mindroot
 - npm: https://www.npmjs.com/package/@sksoftofficial/mindroot
 
+## How it works
+
+- **Notes** (Layer 2): human-editable markdown files under `~/.mindroot/notes/<project>/`, parsed into heading-addressable sections such as `Overview::API`. The unit of storage.
+- **Memories** (Layer 1): short, retrieval-optimized texts that stand alone or point into a note or section via `target_path`. The unit of retrieval.
+- **Search**: memories are the semantic index — hybrid ranking of cosine similarity (0.75) over local embeddings plus BM25 keyword search (0.25) through SQLite FTS5. Note sections use literal case-insensitive string matching. All content search is strictly project-scoped; project discovery uses its own fuzzy slug search with slug embeddings and token overlap.
+
+## Features
+
+- **Two-layer memory** — markdown notes for depth, short memories for recall, linked via heading paths.
+- **Local embeddings** — 768-dimensional q8 embeddings from `onnx-community/embeddinggemma-300m-ONNX` via transformers.js, computed fully offline and cached under `~/.mindroot/models`.
+- **Hybrid search** — semantic + BM25 ranking over memories, literal string matching over note sections, fuzzy project-name matching across projects.
+- **MCP server** — JSON-RPC endpoint at `/mcp` with 12 project/memory/note tools for agents.
+- **REST API** — the same operations over `POST/GET/PUT/DELETE /api/*` for scripts and integrations.
+- **Dashboard** — web UI at `/` for browsing notes and memories, editing markdown, and searching.
+- **CLI** — init, start/stop/restart/status, and human-readable browsing commands.
+- **Background service** — `mindroot start` daemonizes, writes a pidfile, and waits until healthy; `stop` and `restart` manage it.
+- **Self-healing reads** — note reads verify a stored content hash and silently re-index files edited externally.
+- **Surgical edits** — `update_section` splices only the targeted heading's line range, leaving the rest of the file byte-identical.
+- **Link cleanup** — deleting a note clears memories linked to its exact path or one of its heading paths.
+- **Auto-created projects** — any write to a new project slug creates it; no cwd detection, no disk scanning, no cross-project content search.
+- **Local-first storage** — one SQLite database (`node:sqlite`, WAL mode, FTS5) plus plain markdown files you own.
+- **Security** — constant-time Bearer API-key auth for every `/api` and `/mcp` request, server-side path-traversal and slug validation, localhost-only by default.
+
 ## Install
 
 Requires Node.js >= 22.
 
 ```sh
 npm install -g @sksoftofficial/mindroot   # or: npm link from a clone
-mindroot init                              # creates store, caches the embedding model (~316MB)
+mindroot init                              # creates store, schema, api key; caches the embedding model (~316MB)
 mindroot start                             # daemonizes and waits until healthy
 ```
 
+## Service management
+
+```sh
+mindroot start            # start in the background, wait for /health
+mindroot start --foreground  # run attached for debugging
+mindroot stop             # stop the pidfile process (escalates when needed)
+mindroot restart          # stop + start
+mindroot status           # pidfile, health endpoint, and key consistency check
+mindroot dashboard        # open the dashboard in your browser
+```
+
+The default address is `127.0.0.1:7620`, configurable in `~/.mindroot/config.json`. There is no crash auto-restart.
+
 ## Quick start (MCP)
 
 Point your MCP client at the service:
@@ -37,7 +71,7 @@ Point your MCP client at the service:
 }
 ```
 
-The API key is generated by `mindroot init` and stored in `~/.mindroot/config.json` (never printed). Dashboard lives at `http://127.0.0.1:7620/`.
+The API key is generated by `mindroot init` and stored in `~/.mindroot/config.json` (never printed). Tool failures return `isError: true` content instead of crashing the call.
 
 ## Agent memory policy
 
@@ -49,15 +83,15 @@ Add this policy to your agent's instructions:
 
 Use mindroot MCP tools as persistent memory for durable project facts. It's a project index, not a scratchpad.
 
-- Once per session, before relying on memory or exploring source: `list_projects` (or `search_projects` for fuzzy name matching), then `search_memories` / `read_note` on relevant subjects. Source files are ground truth; fall back to them when memory lacks the detail.
+- EVERY task — not once per session; a single session can contain multiple unrelated tasks, so run this per task: resolve the project slug (`search_projects` with the repo name, or `list_projects`), `search_memories` with keywords from the task, then `read_note` the notes those memory hits link to. Always choose reading the facts from mindroot over exploring the codebase. Exploring source is the second option, ONLY when mindroot has no relevant notes or the notes don't match reality — then source is the truth (and correct the stale note).
 - Every content tool needs a project slug. A project is created automatically on first write.
 
 ## Notes vs memories
 
 Notes are storage; memories are the retrieval index into them. They work as a pair:
 
-- **Memories** (`save_memory`, `delete_memory`) — short, standalone atomic facts ("where email delivery lives", "never migrate during business hours"), optionally linked via `target_path` ("note.md::Heading"). No listing tool: `search_memories` is how you find them; hits carry the ids for `delete_memory`. When in doubt, save a memory.
-- **Notes** (`save_note`, `update_section`, `read_note`, `delete_note`) — structured markdown docs parsed by headings. `update_section` takes full heading paths (`Audit logging::API`); run `read_note` first and copy exact paths.
+- **Memories** (`save_memory`, `delete_memory`) — short, standalone atomic facts ("where email delivery lives", "never migrate during business hours"), optionally linked via `target_path` ("note.md::Heading"). The semantic search layer: `search_memories` ranks hybrid (embeddings + keywords). No listing tool; hits carry the ids for `delete_memory`. When in doubt, save a memory.
+- **Notes** (`save_note`, `update_section`, `read_note`, `delete_note`) — structured markdown docs parsed into heading-addressable sections. `read_note` without args returns full content plus the section list; with `section` ("Audit logging::API") returns only that section's body — prefer section reads when you don't need the whole note. `update_section` takes the same heading paths; run `read_note`/`list_notes` first and copy exact paths. `search_notes` is a literal case-insensitive string search over section text — a fallback for exact keywords/identifiers, not semantic search.
 
 After writing or updating a notable note section, also save 1–3 memories pointing at it (`target_path`) so future searches surface it — one per key fact a future agent would search for. If a memory stands alone (no note worth writing), that's fine too. Dedupe by searching first, then deleting stale hits — never stack near-copies.
 
@@ -77,12 +111,16 @@ After work that changes a durable fact, update the smallest relevant note sectio
 
 ## CLI
 
+CLI output is human-readable; agents should use MCP tools.
+
 | Command | Description |
 |---|---|
 | `mindroot init` | Initialize store + model cache (idempotent) |
 | `mindroot start [--foreground]` | Daemonize the service (or run foreground for debugging) |
 | `mindroot stop` | Stop the running service |
+| `mindroot restart` | Restart the service (stop + start) |
 | `mindroot status` | Show whether the service is running |
+| `mindroot dashboard` | Open the dashboard in your browser |
 | `mindroot projects` | List projects with counts |
 | `mindroot notes --project <slug> [path]` | List notes, or print one |
 | `mindroot memories --project <slug>` | List memories |
@@ -95,17 +133,45 @@ All tools are prefixed `mindroot_`.
 
 | Tool | Params | Purpose |
 |---|---|---|
-| `list_projects` | — | Discover slugs |
-| `search_projects` | `query` | Fuzzy-find a project by name |
+| `list_projects` | — | List projects with note/memory counts |
+| `search_projects` | `query` | Fuzzy-find a project by name (semantic + token overlap) |
+| `rename_project` | `project*`, `new_slug*` | Rename a project; moves notes and preserves memories and indexes |
 | `search_memories` | `project*`, `query`, `limit?` | Hybrid search over memories (hits carry ids) |
-| `search_notes` | `project*`, `query`, `limit?` | Search note sections |
+| `search_notes` | `project*`, `query`, `limit?` | Literal string search over note sections (fallback to memories' semantic search) |
 | `save_memory` | `project*`, `text`, `target_path?` | Save a memory, optionally linked to a note/section |
 | `delete_memory` | `project*`, `id` | Delete a memory by id |
 | `list_notes` | `project*` | List notes with section paths |
-| `read_note` | `project*`, `path` | Full note content (hash-verified) |
+| `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 |
-| `delete_note` | `project*`, `path` | Delete a note |
+| `update_section` | `project*`, `path`, `heading_path`, `content` | Replace one section body, leave the rest untouched |
+| `delete_note` | `project*`, `path` | Delete a note (clears its linked memories) |
+
+## REST API
+
+Same operations as MCP, for scripts and integrations. All `/api/*` routes (and `/mcp`) require `Authorization: Bearer <apiKey>`; `/health` does not.
+
+| Method | Path | Purpose |
+|---|---|---|
+| `GET` | `/health` | Liveness probe |
+| `GET` | `/api/projects` | List projects |
+| `POST` | `/api/projects` | Create project `{ slug }` |
+| `GET` | `/api/projects/:slug` | Project detail with docs and memories |
+| `DELETE` | `/api/projects/:slug` | Delete a project |
+| `GET` | `/api/projects/:slug/docs` | List notes |
+| `GET/PUT/DELETE` | `/api/projects/:slug/doc?path=` | Read (optionally `&section=`), write, or delete one note |
+| `POST` | `/api/projects/:slug/sections` | Update one section `{ path, heading_path, content }` |
+| `GET/POST` | `/api/projects/:slug/memories` | List or add memories `{ text, target_path? }` |
+| `DELETE` | `/api/projects/:slug/memories/:id` | Delete a memory |
+| `POST` | `/api/search` | Search `{ project, query, kind?: "memories"\|"notes", limit? }` |
+| `POST` | `/mcp` | JSON-RPC MCP endpoint |
+
+## Dashboard
+
+The dashboard at `http://127.0.0.1:7620/` stores its key in localStorage and offers:
+
+- **Notes** view with a markdown editor in Write / Split / Read modes and rendered preview.
+- **Memories** view for browsing and adding memories with optional note links.
+- **Search** view across notes and memories.
 
 ## Configuration
 
@@ -127,4 +193,4 @@ node --test    # runs the test suite in test/
 
 ## License
 
-MIT
+ISC

package/bin/mindroot.js

@@ -3,6 +3,7 @@
 import { init } from "../src/commands/init.js";
 import { start, stop, restart, status } from "../src/commands/start.js";
 import { projects, searchCmd, saveMemoryCmd, memoriesCmd, notesCmd } from "../src/commands/human.js";
+import { dashboard } from "../src/commands/dashboard.js";
 
 const [command, ...rest] = process.argv.slice(2);
 
@@ -14,6 +15,7 @@ Usage:
   mindroot stop                          Stop the running service
   mindroot restart                       Restart the service (stop + start)
   mindroot status                        Show whether the service is running
+  mindroot dashboard                     Open the dashboard in your browser
   mindroot projects                      List projects
   mindroot notes --project <slug> [path] List notes (or show one)
   mindroot memories --project <slug>     List memories
@@ -38,6 +40,8 @@ async function main() {
       return restart();
     case "status":
       return status();
+    case "dashboard":
+      return dashboard();
     case "projects":
       return projects();
     case "notes":

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sksoftofficial/mindroot",
-  "version": "1.0.2",
-  "description": "Persistent two-layer memory for AI agents: embedding-searched memories over human-editable markdown facts. Runs as a local background service.",
+  "version": "1.0.3",
+  "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",
   "bin": {
@@ -18,10 +18,24 @@
   "keywords": [
     "ai",
     "agent",
+    "agents",
     "memory",
-    "embeddings",
+    "long-term-memory",
+    "agent-memory",
     "mcp",
-    "markdown"
+    "mcp-server",
+    "rag",
+    "embeddings",
+    "semantic-search",
+    "hybrid-search",
+    "markdown",
+    "notes",
+    "sqlite",
+    "local-first",
+    "offline",
+    "llm",
+    "context",
+    "knowledge-base"
   ],
   "author": "sksoftofficial",
   "license": "ISC",

package/src/commands/dashboard.js

@@ -0,0 +1,57 @@
+import { spawn } from "node:child_process";
+import { DEFAULT_PORT, ensureConfig } from "../paths.js";
+
+const CANDIDATES = {
+  darwin: [
+    ["open", "-a", "Google Chrome"],
+    ["open", "-a", "Safari"],
+    ["open"],
+  ],
+  linux: [
+    ["google-chrome"],
+    ["google-chrome-stable"],
+    ["chromium"],
+    ["chromium-browser"],
+    ["firefox"],
+    ["xdg-open"],
+  ],
+  win32: [
+    ["cmd", "/c", "start", "chrome"],
+    ["cmd", "/c", "start", "msedge"],
+    ["cmd", "/c", "start"],
+  ],
+};
+
+function tryOpen(cmd, url) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd[0], [...cmd.slice(1), url], { stdio: "ignore" });
+    child.on("error", () => resolve(false));
+    child.on("close", (code) => resolve(code === 0));
+  });
+}
+
+export async function dashboard() {
+  const { cfg } = ensureConfig();
+  const port = cfg.port ?? DEFAULT_PORT;
+  const url = `http://127.0.0.1:${port}/`;
+
+  let healthy = false;
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/health`, { signal: AbortSignal.timeout(1500) });
+    healthy = res.ok;
+  } catch {}
+  if (!healthy) {
+    console.error("mindroot is not running — run `mindroot start` first");
+    process.exitCode = 1;
+    return;
+  }
+
+  for (const cmd of CANDIDATES[process.platform] ?? []) {
+    if (await tryOpen(cmd, url)) {
+      console.log(`opening dashboard: ${url}`);
+      return;
+    }
+  }
+  console.error(`could not open a browser — visit ${url} manually`);
+  process.exitCode = 1;
+}

package/src/core.js

@@ -72,7 +72,7 @@ export async function listDocs(db, slug) {
   return result;
 }
 
-export async function readNote(db, slug, relPath) {
+export async function readNote(db, slug, relPath, section) {
   await verifyAndLoadDoc(db, slug, relPath);
   const project = getProjectRow(db, slug);
   const doc = db
@@ -80,6 +80,17 @@ export async function readNote(db, slug, relPath) {
     .get(project.id, relPath);
   const content = await fs.readFile(safeJoin(slug, relPath), "utf8");
   const parsed = parseMarkdown(content);
+  if (section !== undefined && section !== null) {
+    const sec = parsed.sections.find((s) => s.path === section);
+    if (!sec) throw httpError(404, `section not found: ${section}`);
+    return {
+      path: relPath,
+      title: doc.title,
+      section,
+      updated_at: doc.indexed_at,
+      content: sec.body,
+    };
+  }
   return {
     path: relPath,
     title: doc.title,

package/src/dashboard/index.html

@@ -246,14 +246,53 @@ async function boot() {
     $("#gate").style.display = "none";
     $("#app").style.display = "flex";
     const projects = await renderProjects();
-    if (currentProject) selectProject(currentProject);
-    else if (projects.length) selectProject(projects[0].slug);
-    else $("#content").innerHTML = '<div class="empty">No projects yet</div>';
+    const r = routeFromHash();
+    if (projects.some((p) => p.slug === r.slug)) applyRoute(r);
+    else if (projects.length) navTo(routeUrl(projects[0].slug, "notes"));
+    else {
+      $(".header-context").hidden = true;
+      $("#content").innerHTML = '<div class="empty">No projects yet</div>';
+    }
   } catch (e) {
     if (e.message !== "unauthorized") showGate(String(e));
   }
 }
 
+function routeUrl(slug, tab, doc) {
+  return "#/" + encodeURIComponent(slug) + "/" + tab + (doc ? "/" + encodeURIComponent(doc) : "");
+}
+
+function routeFromHash() {
+  const [rawSlug, rawTab, rawDoc] = location.hash.replace(/^#\/?/, "").split("/");
+  return {
+    slug: rawSlug ? decodeURIComponent(rawSlug) : null,
+    tab: ["notes", "memories", "search"].includes(rawTab) ? rawTab : "notes",
+    doc: rawDoc ? decodeURIComponent(rawDoc) : null,
+  };
+}
+
+function navTo(hash) {
+  if (location.hash === hash) applyRoute(routeFromHash());
+  else location.hash = hash;
+}
+
+function applyRoute({ slug = null, tab = "notes", doc = null } = {}) {
+  currentProject = slug;
+  currentTab = tab;
+  currentDoc = doc;
+  if (currentProject) {
+    $(".header-context").hidden = false;
+    const projectLabel = $("#headerProject");
+    projectLabel.textContent = slug;
+    projectLabel.title = slug;
+    projectLabel.setAttribute("aria-label", "Current project: " + slug);
+  }
+  document.querySelectorAll(".proj").forEach((n) => n.classList.toggle("active", n.textContent === slug));
+  renderTabs();
+}
+
+window.addEventListener("hashchange", () => applyRoute(routeFromHash()));
+
 async function renderProjects() {
   const rows = await api("GET", "/api/projects");
   const el = $("#projList");
@@ -270,15 +309,7 @@ async function renderProjects() {
 }
 
 function selectProject(slug) {
-  currentProject = slug;
-  currentDoc = null;
-  $(".header-context").hidden = false;
-  const projectLabel = $("#headerProject");
-  projectLabel.textContent = slug;
-  projectLabel.title = slug;
-  projectLabel.setAttribute("aria-label", "Current project: " + slug);
-  document.querySelectorAll(".proj").forEach((n) => n.classList.toggle("active", n.textContent === slug));
-  renderTabs();
+  navTo(routeUrl(slug, "notes"));
 }
 
 function renderTabs() {
@@ -293,7 +324,7 @@ function renderTabs() {
       const t = document.createElement("div");
       t.className = "tab" + (currentTab === name ? " active" : "");
       t.textContent = label;
-      t.onclick = () => { currentTab = name; currentDoc = null; renderTabs(); };
+      t.onclick = () => navTo(routeUrl(currentProject, name));
       tabs.appendChild(t);
     }
     const actions = document.createElement("div");
@@ -316,8 +347,9 @@ async function deleteCurrentProject() {
     await api("DELETE", "/api/projects/" + encodeURIComponent(slug));
     currentProject = null;
     currentDoc = null;
+    history.replaceState(null, "", location.pathname + location.search);
     const rows = await renderProjects();
-    if (rows.length) selectProject(rows[0].slug);
+    if (rows.length) navTo(routeUrl(rows[0].slug, "notes"));
     else {
       const projectLabel = $("#headerProject");
       $(".header-context").hidden = true;
@@ -342,7 +374,7 @@ async function renderNotes(view) {
     row.querySelector(".t").textContent = d.title + " ";
     const chips = d.sections.filter(Boolean).map((s) => '<span class="sec-chip">' + esc(s) + "</span>").join("");
     row.insertAdjacentHTML("beforeend", '<div>' + chips + "</div>");
-    row.onclick = () => { currentDoc = d.path; renderTabs(); };
+    row.onclick = () => navTo(routeUrl(currentProject, "notes", d.path));
     view.appendChild(row);
   }
   if (!docs.length) view.innerHTML = '<div class="empty">No notes yet. Agents create them with <b>mindroot_save_note</b>.</div>';
@@ -376,7 +408,7 @@ async function renderEditor(view, docs) {
     '<button class="danger" id="delBtn">Delete note</button></div></div>';
   view.appendChild(head);
   head.querySelector(".editor-title").textContent = currentDoc;
-  $("#backBtn").onclick = () => { currentDoc = null; renderTabs(); };
+  $("#backBtn").onclick = () => history.back();
   head.querySelectorAll(".viewmode button").forEach((b) =>
     b.onclick = () => { mdMode = b.dataset.m; localStorage.setItem("mindroot_mdmode", mdMode); renderTabs(); });
 
@@ -413,8 +445,7 @@ async function renderEditor(view, docs) {
   $("#delBtn").onclick = async () => {
     if (!confirm("delete " + currentDoc + "?")) return;
     await api("DELETE", "/api/projects/" + currentProject + "/doc?path=" + encodeURIComponent(currentDoc));
-    currentDoc = null;
-    renderTabs();
+    navTo(routeUrl(currentProject, "notes"));
   };
 }
 
@@ -449,7 +480,7 @@ async function renderMemories(view) {
   }
   if (!rows.length) view.insertAdjacentHTML("beforeend", '<div class="empty">No memories yet</div>');
   view.querySelectorAll("a[data-p]").forEach((a) =>
-    a.onclick = (e) => { e.preventDefault(); currentTab = "notes"; currentDoc = a.dataset.p; renderTabs(); });
+    a.onclick = (e) => { e.preventDefault(); navTo(routeUrl(currentProject, "notes", a.dataset.p)); });
 }
 
 async function renderSearch(view) {

package/src/indexer.js

@@ -1,9 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import crypto from "node:crypto";
-import { NOTES_DIR, ONNX_MODEL_ID } from "./paths.js";
+import { NOTES_DIR } from "./paths.js";
 import { parseMarkdown, docTitle } from "./markdown.js";
-import { embedDoc } from "./embedder.js";
 
 export const sha256 = (s) => crypto.createHash("sha256").update(s).digest("hex");
 
@@ -47,25 +46,13 @@ async function walkMd(dir) {
   return out.sort();
 }
 
-function embedTextFor(title, headingPath, content) {
-  return `title: ${title} | text: ${headingPath ? headingPath + "\n" : ""}${content}`.slice(0, 4000);
-}
-
-async function upsertSectionEmbedding(db, docId, headingPath, content, title) {
+function upsertSection(db, docId, headingPath, content) {
   const now = Date.now();
   db.prepare(
     `INSERT INTO sections (doc_id, heading_path, content, updated_at)
      VALUES (?, ?, ?, ?)
      ON CONFLICT(doc_id, heading_path) DO UPDATE SET content = excluded.content, updated_at = excluded.updated_at`,
   ).run(docId, headingPath, content, now);
-  const row = db
-    .prepare("SELECT id FROM sections WHERE doc_id = ? AND heading_path = ?")
-    .get(docId, headingPath);
-  db.prepare("DELETE FROM embeddings WHERE owner_type = 'section' AND owner_id = ?").run(row.id);
-  const vec = await embedDoc(embedTextFor(title, headingPath, content));
-  db.prepare(
-    "INSERT INTO embeddings (owner_type, owner_id, dim, model, vec) VALUES ('section', ?, ?, ?, ?)",
-  ).run(row.id, vec.length, ONNX_MODEL_ID, Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength));
 }
 
 export async function reindexDoc(db, slug, relPath, content, mtime) {
@@ -102,7 +89,7 @@ export async function reindexDoc(db, slug, relPath, content, mtime) {
     const prev = existing.get(sec.path);
     existing.delete(sec.path);
     if (prev && prev.content === sec.body) continue;
-    await upsertSectionEmbedding(db, doc.id, sec.path, sec.body, title);
+    upsertSection(db, doc.id, sec.path, sec.body);
   }
   for (const stale of existing.values()) {
     db.prepare("DELETE FROM embeddings WHERE owner_type = 'section' AND owner_id = ?").run(stale.id);

package/src/mcp.js

@@ -34,7 +34,7 @@ export function tools() {
     {
       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.",
+        "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: {
         type: "object",
         properties: {
@@ -48,12 +48,12 @@ export function tools() {
     {
       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.",
+        "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: {
         type: "object",
         properties: {
           project: { type: "string", description: "Project slug to search in" },
-          query: { type: "string", description: "Natural language search query" },
+          query: { type: "string", description: "Literal text to find (matched as whole words/terms)" },
           limit: { type: "number", description: "Max results (default 8)" },
         },
         required: ["project", "query"],
@@ -84,7 +84,8 @@ export function tools() {
     },
     {
       name: "mindroot_list_notes",
-      description: "List all memory notes for a project with their titles and section paths.",
+      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: {
         type: "object",
         properties: { project: { type: "string" } },
@@ -94,17 +95,21 @@ export function tools() {
     {
       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.",
+        "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: {
         type: "object",
-        properties: { project: { type: "string" }, path: { type: "string", description: "Note path relative to the project, e.g. 'architecture.md'" } },
+        properties: {
+          project: { type: "string" },
+          path: { type: "string", description: "Note path relative to the project, e.g. 'architecture.md'" },
+          section: { type: "string", description: "Optional heading path like 'Architecture::Storage' — return only that section" },
+        },
         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.",
+        "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: {
         type: "object",
         properties: {
@@ -162,7 +167,7 @@ async function callTool(db, name, args) {
     case "mindroot_list_notes":
       return core.listDocs(db, args.project);
     case "mindroot_read_note":
-      return core.readNote(db, args.project, args.path);
+      return core.readNote(db, args.project, args.path, args.section);
     case "mindroot_save_note":
       return core.saveNote(db, args.project, args.path, args.content);
     case "mindroot_update_section":

package/src/search.js

@@ -151,39 +151,46 @@ function applyFts(db, projectId, query, byId) {
   }
 }
 
-export async function searchNotes(db, projectId, query, limit = 8) {
-  return rankNotes(db, projectId, await embedQuery(query), limit);
+export function searchNotes(db, projectId, query, limit = 8) {
+  return rankNotes(db, projectId, query, limit);
 }
 
-export function rankNotes(db, projectId, qvec, limit = 8) {
+export function rankNotes(db, projectId, query, limit = 8) {
+  const terms = query.trim().toLowerCase().split(/\s+/).filter(Boolean).slice(0, 8);
+  if (!terms.length) return [];
   const rows = db
     .prepare(
-      `SELECT e.owner_id, e.vec,
-              s.content AS scontent, s.heading_path, s.updated_at AS sut,
+      `SELECT s.id, s.content, s.heading_path, s.updated_at,
               d.rel_path, d.title AS dtitle
-       FROM embeddings e
-       JOIN sections s ON s.id = e.owner_id
+       FROM sections s
        JOIN docs d ON d.id = s.doc_id
-       WHERE e.owner_type = 'section' AND d.project_id = $pid`,
+       WHERE d.project_id = $pid`,
     )
     .all({ pid: projectId });
 
-  const byId = new Map();
+  const hits = [];
   for (const row of rows) {
-    const vec = toFloat32(row.vec);
-    if (vec.length !== qvec.length) continue;
-    byId.set(row.owner_id, {
+    const heading = row.heading_path.toLowerCase();
+    const content = (row.content ?? "").toLowerCase();
+    let matched = 0;
+    let headingMatched = false;
+    for (const term of terms) {
+      if (heading.includes(term)) headingMatched = true;
+      if (heading.includes(term) || content.includes(term)) matched++;
+    }
+    if (!matched) continue;
+    hits.push({
       kind: "note_section",
-      id: row.owner_id,
-      text: row.scontent?.slice(0, 300),
+      id: row.id,
+      text: row.content?.slice(0, 300),
       target: `${row.rel_path}::${row.heading_path}`,
       doc_title: row.dtitle,
-      score: cosine(qvec, vec),
-      updated_at: row.sut,
+      score: matched / terms.length + (headingMatched ? 0.25 : 0),
+      updated_at: row.updated_at,
     });
   }
-
-  return rank(byId, limit);
+  hits.sort((a, b) => b.score - a.score || b.updated_at - a.updated_at);
+  return hits.slice(0, limit);
 }
 
 function rank(byId, limit) {

package/src/server.js

@@ -111,7 +111,8 @@ async function handleApi(req, res, url, db) {
     if (parts[3] === "doc") {
       const relPath = url.searchParams.get("path");
       if (!relPath) throw badRequest("path query param required");
-      if (req.method === "GET") return sendJson(res, 200, await core.readNote(db, slug, relPath));
+      if (req.method === "GET")
+        return sendJson(res, 200, await core.readNote(db, slug, relPath, url.searchParams.get("section") ?? undefined));
       if (req.method === "PUT") {
         const body = await readJson(req);
         return sendJson(res, 200, await core.saveNote(db, slug, relPath, body.content ?? ""));

package/src/store/db.js

@@ -91,6 +91,8 @@ function migrate(db) {
   if (!docCols.includes("content_hash")) {
     db.exec("ALTER TABLE docs ADD COLUMN content_hash TEXT");
   }
+  // Section embeddings were removed from the design — memories are the only semantic note index.
+  db.prepare("DELETE FROM embeddings WHERE owner_type = 'section'").run();
 }
 
 export function open() {

package/test/search.test.js

@@ -49,7 +49,7 @@ test("rankMemories blends vector and keyword scores, respects limit", async () =
   assert.equal(rankMemories(db, pid, new Float32Array([1, 0]), "x", 10).some((h) => h.text === "dim mismatch"), false);
 });
 
-test("rankNotes ranks sections scoped to the project", async () => {
+test("rankNotes literal-matches sections scoped to the project", async () => {
   const { rankNotes } = await import("../src/search.js");
   const db = open();
   db.prepare("INSERT INTO projects (slug, created_at) VALUES ('p2', 2)").run();
@@ -61,14 +61,33 @@ test("rankNotes ranks sections scoped to the project", async () => {
   db.prepare(
     "INSERT INTO sections (doc_id, heading_path, content, updated_at) VALUES (?, 'Deploy', 'tag push deploys', 1)",
   ).run(docId);
-  const secId = db.prepare("SELECT id FROM sections").get().id;
   db.prepare(
-    "INSERT INTO embeddings (owner_type, owner_id, dim, model, vec) VALUES ('section', ?, ?, 'm', ?)",
-  ).run(secId, 2, vec([0.9, 0.1]));
+    "INSERT INTO sections (doc_id, heading_path, content, updated_at) VALUES (?, 'Cooking', 'boil pasta water', 1)",
+  ).run(docId);
+  // unrelated project section must not leak in
+  db.prepare("INSERT INTO projects (slug, created_at) VALUES ('p3', 3)").run();
+  const pid3 = db.prepare("SELECT id FROM projects WHERE slug='p3'").get().id;
+  const doc3 = Number(
+    db.prepare("INSERT INTO docs (project_id, rel_path, title, content_hash, mtime, indexed_at) VALUES (?, 'b.md', 'B', NULL, 1, 1)").run(pid3).lastInsertRowid,
+  );
+  db.prepare(
+    "INSERT INTO sections (doc_id, heading_path, content, updated_at) VALUES (?, 'Deploy', 'tag push deploys', 1)",
+  ).run(doc3);
 
-  const hits = rankNotes(db, pid, new Float32Array([0.9, 0.1]), 8);
+  const hits = rankNotes(db, pid, "deploy", 8);
+  assert.equal(hits.length, 1);
   assert.equal(hits[0].kind, "note_section");
   assert.equal(hits[0].target, "a.md::Deploy");
+
+  // heading matches outrank body-only matches
+  db.prepare(
+    "INSERT INTO sections (doc_id, heading_path, content, updated_at) VALUES (?, 'Releases', 'unrelated body mentioning deploy word', 1)",
+  ).run(docId);
+  const ranked = rankNotes(db, pid, "deploy", 8);
+  assert.equal(ranked[0].target, "a.md::Deploy");
+
+  // no terms -> no results
+  assert.equal(rankNotes(db, pid, "   ", 8).length, 0);
 });
 
 test("rankProjects applies token-overlap bonus and threshold", async () => {