@sksoftofficial/mindroot 1.0.6 → 1.2.0

package/INSTRUCTIONS.md

@@ -0,0 +1,41 @@
+<!-- mindroot:start -->
+# Agent memory policy (mindroot)
+
+Use mindroot MCP tools as persistent memory for durable facts about the user and each project. Keep it compact; it is not a scratchpad.
+
+## Project memory
+
+- Resolve the project once with `search_projects` or `list_projects` and reuse its slug.
+- Call `search_memories` when starting a new task or investigating a new topic, then `read_note` the relevant linked notes. Reuse notes already in context; repeat lookups only when more information or refreshed context is needed.
+- Consult memory before exploring source. If relevant notes are missing or contradict reality, inspect source and correct stale notes.
+- Project content tools need 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"). 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.
+
+Notes read like compact index cards: one sentence on what the feature is, then the files, entry points, and data flow needed to work on it later — enough to answer "where is this implemented?" without reading source. Keep one feature per note under keyword-rich headings (`## Model`, `## API`, `## Gotchas`, …), plus standard cross-cutting notes: `overview.md`, `conventions.md` (patterns shared across features), `commands.md`, `gotchas.md`.
+
+## What to save
+
+Facts that improve future navigation, implementation, debugging, or verification: structure and key files, config values, frameworks/services, build/test/deploy commands, conventions, recurring bugs and gotchas.
+
+Never save: task history, reasoning trails, rejected alternatives, dated recaps, secrets, logs, or speculation.
+
+Write bullets as standalone present-tense facts with file anchors (`models/AuditLog.jsx` defines model `AuditLog` in collection `auditlog`). Not "we decided X today".
+
+After work that changes a durable fact, update the smallest relevant note section — plus linked memories for its key facts — automatically before your final response, no confirmation needed. Notes stay compact: merge overlapping bullets, drop stale ones.
+
+## Project skills
+
+Skills store reusable procedures for recurring work in this project: notes and memories hold facts, skills hold how to do a task.
+
+- Call `search_skills` once before a non-trivial multi-step task; skip simple edits, straightforward questions, and work already clear from context. Reuse skills already loaded; if nothing fits, proceed normally.
+- After finishing a verified multi-step procedure that is not already captured, save or improve its skill automatically before responding — the reusable procedure, not a task recap, an issue-specific fix, or an unverified approach.
+- Structure content as **When to use**, **Prerequisites**, **Procedure**, **Success criteria**, and **Pitfalls**; reference notes or source instead of duplicating facts, and correct skills that no longer match project behavior.
+<!-- mindroot:end -->

package/README.md

@@ -4,7 +4,7 @@ AI agents that never forget.
 
 ![Mindroot persistent AI agent memory system](https://skbilisim.com/assets/projects/mindroot.webp)
 
-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.
+Mindroot is a tiny Node.js service that gives your AI agents project-scoped hybrid-searched **memories** over human-editable markdown **notes**, and reusable **skills** for recurring work. It exposes 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
@@ -14,15 +14,17 @@ Mindroot is a tiny Node.js service that gives your AI agents a permanent, projec
 - **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.
+- **Skills**: project-specific Markdown procedures stored in SQLite with stable names and revision history. Skill names and descriptions have their own hybrid search index; agents load the full instructions only when a match is relevant. Saving a skill indexes it automatically, without creating memories or embedding the full procedure.
 
 ## 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.
+- **Project skills** — agents discover and apply saved procedures, then automatically capture or improve verified procedures through the skills policy below.
+- **MCP server** — JSON-RPC endpoint at `/mcp` with 16 project/memory/note/skill 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.
+- **Dashboard** — web UI at `/` for browsing notes, memories, and skills, editing Markdown, and inspecting skill revisions.
 - **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.
@@ -57,6 +59,28 @@ The default address is `127.0.0.1:7620`, configurable in `~/.mindroot/config.jso
 
 ## Quick start (MCP)
 
+For OpenCode, Claude Code, or Codex, use the one-command setup instead of manually running `init` and `start`:
+
+```sh
+mindroot install opencode   # ~/.config/opencode
+mindroot install claude     # ~/.claude.json + ~/.claude/CLAUDE.md
+mindroot install codex      # ~/.codex/config.toml + ~/.codex/AGENTS.md
+```
+
+This initializes Mindroot (including the model cache), starts the background service if needed, and configures the client's global `mindroot` MCP entry with the local service URL and API key. It also installs the bundled `INSTRUCTIONS.md` policy into the client's global instructions file.
+
+Rerunning refreshes the MCP entry and replaces the policy between `<!-- mindroot:start -->` and `<!-- mindroot:end -->`, rather than appending duplicates. Other MCP servers, configuration settings, comments, and instructions outside the marked blocks are preserved. Unbalanced policy markers or malformed configuration cause an error rather than an overwrite.
+
+Default locations, honoring each client's directory override:
+
+- OpenCode: `~/.config/opencode`, honoring `XDG_CONFIG_HOME` and `OPENCODE_CONFIG_DIR`. An existing `opencode.jsonc` takes precedence; otherwise the command updates or creates `opencode.json`.
+- Claude Code: `~/.claude.json` and `~/.claude/CLAUDE.md`, honoring `CLAUDE_CONFIG_DIR` (both files then live inside that directory).
+- Codex: `~/.codex/config.toml` and `~/.codex/AGENTS.md`, honoring `CODEX_HOME`. A non-empty `AGENTS.override.md` takes precedence and is updated instead; an empty override falls back to `AGENTS.md`.
+
+Quit and restart the client afterward to load the changes. The command configures the client; it does not launch it.
+
+### Other MCP clients
+
 Point your MCP client at the service:
 
 ```json
@@ -81,10 +105,14 @@ Add this policy to your agent's instructions:
 <!-- mindroot:start -->
 # Agent memory policy (mindroot)
 
-Use mindroot MCP tools as persistent memory for durable project facts. It's a project index, not a scratchpad.
+Use mindroot MCP tools as persistent memory for durable facts about the user and each project. Keep it compact; it is not a scratchpad.
 
-- 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.
+## Project memory
+
+- Resolve the project once with `search_projects` or `list_projects` and reuse its slug.
+- Call `search_memories` when starting a new task or investigating a new topic, then `read_note` the relevant linked notes. Reuse notes already in context; repeat lookups only when more information or refreshed context is needed.
+- Consult memory before exploring source. If relevant notes are missing or contradict reality, inspect source and correct stale notes.
+- Project content tools need a project slug. A project is created automatically on first write.
 
 ## Notes vs memories
 
@@ -106,9 +134,39 @@ Never save: task history, reasoning trails, rejected alternatives, dated recaps,
 Write bullets as standalone present-tense facts with file anchors (`models/AuditLog.jsx` defines model `AuditLog` in collection `auditlog`). Not "we decided X today".
 
 After work that changes a durable fact, update the smallest relevant note section — plus linked memories for its key facts — automatically before your final response, no confirmation needed. Notes stay compact: merge overlapping bullets, drop stale ones.
+
+## Project skills
+
+Skills store reusable procedures for recurring work in this project: notes and memories hold facts, skills hold how to do a task.
+
+- Call `search_skills` once before a non-trivial multi-step task; skip simple edits, straightforward questions, and work already clear from context. Reuse skills already loaded; if nothing fits, proceed normally.
+- After finishing a verified multi-step procedure that is not already captured, save or improve its skill automatically before responding — the reusable procedure, not a task recap, an issue-specific fix, or an unverified approach.
+- Structure content as **When to use**, **Prerequisites**, **Procedure**, **Success criteria**, and **Pitfalls**; reference notes or source instead of duplicating facts, and correct skills that no longer match project behavior.
 <!-- mindroot:end -->
 ```
 
+## Using skills
+
+Automatic skill management is driven by the agent policy: the agent searches once before starting non-trivial work and captures verified procedures after finishing it. Mindroot stores and retrieves procedures; it does not watch conversations or execute skills itself. Copy the policy above (also available in `INSTRUCTIONS.md`) into your agent's instructions.
+
+For example, an agent can create a skill with `save_skill`:
+
+```json
+{
+  "project": "my-project",
+  "name": "add-api-route",
+  "description": "Use when adding an API route with the project's existing handler and error conventions.",
+  "content": "## When to use\nAdding an API route.\n\n## Prerequisites\nRead conventions.md::API and identify the existing router.\n\n## Procedure\n1. Follow a neighboring handler's registration and error handling.\n2. Implement the requested behavior.\n3. Update the API documentation.\n\n## Success criteria\nThe route is registered and satisfies the requested behavior; follow the task's authorized validation requirements.\n\n## Pitfalls\nDo not copy credentials or request-specific data into examples.",
+  "expected_revision": 0
+}
+```
+
+When a saved procedure would help with a later API task, call `search_skills` with `{ "project": "my-project", "query": "add an API endpoint" }`, then `read_skill` with a relevant returned name. Search returns only names, descriptions, revisions, timestamps, and scores.
+
+To improve a skill, read its latest version and save under the same name with that `expected_revision`. Each changed save preserves a revision; identical saves are a no-op. A stale or concurrent save returns a conflict so the agent can reread and reconcile. Use `read_skill` with `revision` to inspect an older version; to restore it, save that content using the latest revision as `expected_revision`. Deleting a skill removes all its revisions and index entries.
+
+Skills are available through MCP, REST, and the dashboard. The dashboard lists saved skills and supports reading, editing, viewing revision history, and deletion. CLI content commands cover notes and memories. After updating an existing installation, restart mindroot to create the skill tables and reconnect your MCP client to refresh its tool list.
+
 ## CLI
 
 CLI output is human-readable; agents should use MCP tools.
@@ -116,6 +174,7 @@ CLI output is human-readable; agents should use MCP tools.
 | Command | Description |
 |---|---|
 | `mindroot init` | Initialize store + model cache (idempotent) |
+| `mindroot install <opencode\|claude\|codex>` | Initialize, start, and configure a coding agent globally |
 | `mindroot start [--foreground]` | Daemonize the service (or run foreground for debugging) |
 | `mindroot stop` | Stop the running service |
 | `mindroot restart` | Restart the service (stop + start) |
@@ -129,11 +188,11 @@ CLI output is human-readable; agents should use MCP tools.
 
 ## MCP tools
 
-All tools are prefixed `mindroot_`.
+Tool names on the wire are unprefixed; MCP clients may display them with a `mindroot_` prefix.
 
 | Tool | Params | Purpose |
 |---|---|---|
-| `list_projects` | — | List projects with note/memory counts |
+| `list_projects` | — | List projects with note/memory/skill 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) |
@@ -145,6 +204,10 @@ All tools are prefixed `mindroot_`.
 | `save_note` | `project*`, `path`, `content` | Create/overwrite a note |
 | `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) |
+| `search_skills` | `project*`, `query`, `limit?` | Hybrid search over skill names and descriptions; returns summaries |
+| `read_skill` | `project*`, `name`, `revision?` | Read current instructions or a historical revision |
+| `save_skill` | `project*`, `name`, `description`, `content`, `expected_revision?` | Create/update and index a skill; preserve history; use revision 0 for create-only |
+| `delete_skill` | `project*`, `name` | Delete a skill, its history, and its index |
 
 ## REST API
 
@@ -155,14 +218,16 @@ Same operations as MCP, for scripts and integrations. All `/api/*` routes (and `
 | `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 |
+| `GET` | `/api/projects/:slug` | Project detail with docs, memories, and skill summaries |
 | `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? }` |
+| `GET` | `/api/projects/:slug/skills` | List skill summaries |
+| `GET/PUT/DELETE` | `/api/projects/:slug/skills/:name` | Read (`?revision=` optional), save `{ description, content, expected_revision? }`, or delete a skill |
+| `POST` | `/api/search` | Search `{ project, query, kind?: "memories"\|"notes"\|"skills", limit? }`; omit `kind` for memories + notes |
 | `POST` | `/mcp` | JSON-RPC MCP endpoint |
 
 ## Dashboard
@@ -170,8 +235,10 @@ Same operations as MCP, for scripts and integrations. All `/api/*` routes (and `
 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.
+- **Memories** view for browsing saved memories, following note links, and deleting entries.
+- **Skills** view for browsing saved procedures, editing descriptions and Markdown in Write / Split / Read modes, inspecting older revisions, and deleting skills. Saves detect conflicting updates and preserve your draft on failure; historical revisions are read-only.
+
+Memory creation and search are available through MCP and REST; the dashboard has no add-memory form or Search tab.
 
 ## Configuration
 
@@ -180,7 +247,7 @@ Everything lives under `~/.mindroot/`:
 - `config.json` — `port` (default 7620) and `apiKey`
 - `notes/<project>/` — your markdown notes
 - `models/` — cached ONNX embedding model
-- `mindroot.db` — SQLite index (WAL mode)
+- `mindroot.db` — SQLite index, skill Markdown content, and skill revisions (WAL mode)
 - `mindroot.pid` / `mindroot.log` — written by `start`/`stop`
 
 Set `MINDROOT_DIR` to relocate the whole store.

package/bin/mindroot.js

@@ -4,6 +4,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";
+import { install } from "../src/commands/install.js";
 
 const [command, ...rest] = process.argv.slice(2);
 
@@ -11,6 +12,7 @@ const usage = `mindroot — persistent memory for AI agents
 
 Usage:
   mindroot init                          Initialize store and download model
+  mindroot install <opencode|claude|codex>  Initialize, start, and configure a coding agent globally
   mindroot start [--foreground]          Start the service in the background (or foreground)
   mindroot stop                          Stop the running service
   mindroot restart                       Restart the service (stop + start)
@@ -32,6 +34,8 @@ async function main() {
       return console.log(usage);
     case "init":
       return init();
+    case "install":
+      return install(rest);
     case "start":
       return start(rest);
     case "stop":

package/package.json

@@ -1,13 +1,21 @@
 {
   "name": "@sksoftofficial/mindroot",
-  "version": "1.0.6",
+  "version": "1.2.0",
   "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sksoftofficial/mindroot.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sksoftofficial/mindroot/issues"
+  },
+  "homepage": "https://github.com/sksoftofficial/mindroot#readme",
   "type": "module",
   "bin": {
     "mindroot": "./bin/mindroot.js"
   },
   "files": [
+    "INSTRUCTIONS.md",
     "bin/",
     "src/",
     "test/"
@@ -40,7 +48,10 @@
   "author": "sksoftofficial",
   "license": "ISC",
   "dependencies": {
-    "@huggingface/transformers": "^3.7.5"
+    "@decimalturn/toml-patch": "^3.0.5",
+    "@huggingface/transformers": "^3.7.5",
+    "force-graph": "1.51.4",
+    "jsonc-parser": "^3.3.1"
   },
   "engines": {
     "node": ">=22"

package/src/commands/install.js

@@ -0,0 +1,210 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parse, modify, applyEdits } from "jsonc-parser";
+import { parse as parseToml, patch as patchToml } from "@decimalturn/toml-patch";
+import { ensureConfig } from "../paths.js";
+import { init } from "./init.js";
+import { start } from "./start.js";
+
+function readPolicy() {
+  return fs.readFileSync(new URL("../../INSTRUCTIONS.md", import.meta.url), "utf8").trim();
+}
+
+function syncPolicy(agents, agentsPath) {
+  const policy = readPolicy();
+  const markers = [...agents.matchAll(/<!-- mindroot:(start|end) -->/g)];
+  if (markers.length % 2 || markers.some((marker, i) => marker[1] !== (i % 2 ? "end" : "start"))) {
+    throw new Error(`unbalanced mindroot markers in ${agentsPath}; fix them before rerunning`);
+  }
+  let replaced = false;
+  let updated = agents.replace(/<!-- mindroot:start -->[\s\S]*?<!-- mindroot:end -->/g, () => {
+    if (replaced) return "";
+    replaced = true;
+    return policy;
+  });
+  if (!replaced) {
+    const separator = !agents || agents.endsWith("\n\n") ? "" : agents.endsWith("\n") ? "\n" : "\n\n";
+    updated = agents + separator + policy + "\n";
+  }
+  return updated;
+}
+
+function mcpEntry(cfg) {
+  return {
+    url: `http://127.0.0.1:${cfg.port}/mcp`,
+    headers: { Authorization: `Bearer ${cfg.apiKey}` },
+  };
+}
+
+function isObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value);
+}
+
+function writeBoth(configPath, originalConfig, updatedConfig, agentsPath, agents, updatedAgents) {
+  // Validate both files before writing either.
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.mkdirSync(path.dirname(agentsPath), { recursive: true });
+  if (updatedConfig !== originalConfig) fs.writeFileSync(configPath, updatedConfig, { mode: 0o600 });
+  if (updatedAgents !== agents) fs.writeFileSync(agentsPath, updatedAgents);
+  return { configPath, agentsPath };
+}
+
+export function configureOpencode(cfg, configDir) {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  configDir ??= process.env.OPENCODE_CONFIG_DIR || path.join(
+    xdg && path.isAbsolute(xdg) ? xdg : path.join(os.homedir(), ".config"), "opencode",
+  );
+  const jsoncPath = path.join(configDir, "opencode.jsonc");
+  const configPath = fs.existsSync(jsoncPath) ? jsoncPath : path.join(configDir, "opencode.json");
+  const agentsPath = path.join(configDir, "AGENTS.md");
+  const originalConfig = fs.existsSync(configPath) ? fs.readFileSync(configPath, "utf8") : "{}\n";
+  const agents = fs.existsSync(agentsPath) ? fs.readFileSync(agentsPath, "utf8") : "";
+  const errors = [];
+  const config = parse(originalConfig, errors, { allowTrailingComma: true });
+  if (errors.length || !isObject(config)) {
+    throw new Error(`invalid OpenCode configuration: ${configPath}; fix it before rerunning`);
+  }
+  if (config.mcp !== undefined && !isObject(config.mcp)) {
+    throw new Error(`expected an mcp object in ${configPath}; fix it before rerunning`);
+  }
+
+  const indent = originalConfig.match(/\n([ \t]+)\S/)?.[1] ?? "  ";
+  const options = { formattingOptions: {
+    insertSpaces: !indent.includes("\t"), tabSize: indent.length,
+    eol: originalConfig.includes("\r\n") ? "\r\n" : "\n",
+  } };
+  let updatedConfig = originalConfig;
+  if (config.$schema === undefined) {
+    updatedConfig = applyEdits(updatedConfig, modify(updatedConfig, ["$schema"], "https://opencode.ai/config.json", options));
+  }
+  updatedConfig = applyEdits(updatedConfig, modify(updatedConfig, ["mcp", "mindroot"], {
+    type: "remote",
+    ...mcpEntry(cfg),
+    enabled: true,
+  }, options));
+  const updatedAgents = syncPolicy(agents, agentsPath);
+
+  return writeBoth(configPath, originalConfig, updatedConfig, agentsPath, agents, updatedAgents);
+}
+
+export function configureClaude(cfg, configDir) {
+  const override = configDir ?? process.env.CLAUDE_CONFIG_DIR;
+  const home = os.homedir();
+  // Without CLAUDE_CONFIG_DIR, the config file lives outside the instructions directory.
+  const configPath = override ? path.join(override, ".claude.json") : path.join(home, ".claude.json");
+  const agentsPath = override ? path.join(override, "CLAUDE.md") : path.join(home, ".claude", "CLAUDE.md");
+  const originalConfig = fs.existsSync(configPath) ? fs.readFileSync(configPath, "utf8") : "{}\n";
+  const agents = fs.existsSync(agentsPath) ? fs.readFileSync(agentsPath, "utf8") : "";
+  let config;
+  try {
+    config = JSON.parse(originalConfig);
+  } catch {
+    throw new Error(`invalid Claude configuration: ${configPath}; fix it before rerunning`);
+  }
+  if (!isObject(config)) {
+    throw new Error(`invalid Claude configuration: ${configPath}; fix it before rerunning`);
+  }
+  if (config.mcpServers !== undefined && !isObject(config.mcpServers)) {
+    throw new Error(`expected an mcpServers object in ${configPath}; fix it before rerunning`);
+  }
+
+  const updatedConfig = JSON.stringify({
+    ...config,
+    mcpServers: {
+      ...config.mcpServers,
+      mindroot: { type: "http", ...mcpEntry(cfg) },
+    },
+  }, null, 2) + "\n";
+  const updatedAgents = syncPolicy(agents, agentsPath);
+
+  return writeBoth(configPath, originalConfig, updatedConfig, agentsPath, agents, updatedAgents);
+}
+
+export function configureCodex(cfg, configDir) {
+  configDir ??= process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+  const configPath = path.join(configDir, "config.toml");
+  const basePath = path.join(configDir, "AGENTS.md");
+  const overridePath = path.join(configDir, "AGENTS.override.md");
+  const originalConfig = fs.existsSync(configPath) ? fs.readFileSync(configPath, "utf8") : "";
+  let config;
+  try {
+    config = parseToml(originalConfig);
+  } catch {
+    throw new Error(`invalid Codex configuration: ${configPath}; fix it before rerunning`);
+  }
+  if (config.mcp_servers !== undefined && !isObject(config.mcp_servers)) {
+    throw new Error(`expected an mcp_servers table in ${configPath}; fix it before rerunning`);
+  }
+  if (config.mcp_servers?.mindroot !== undefined && !isObject(config.mcp_servers.mindroot)) {
+    throw new Error(`expected mcp_servers.mindroot to be a table in ${configPath}; fix it before rerunning`);
+  }
+
+  // A non-empty AGENTS.override.md hides AGENTS.md entirely, so sync it instead.
+  let agentsPath = basePath;
+  let agents;
+  if (fs.existsSync(overridePath)) {
+    const override = fs.readFileSync(overridePath, "utf8");
+    if (override.trim()) {
+      agentsPath = overridePath;
+      agents = override;
+    }
+  }
+  agents ??= fs.existsSync(basePath) ? fs.readFileSync(basePath, "utf8") : "";
+
+  const updatedConfig = patchToml(originalConfig, {
+    mcp_servers: {
+      ...config.mcp_servers,
+      mindroot: {
+        url: `http://127.0.0.1:${cfg.port}/mcp`,
+        http_headers: { Authorization: `Bearer ${cfg.apiKey}` },
+      },
+    },
+  });
+  const updatedAgents = syncPolicy(agents, agentsPath);
+
+  return writeBoth(configPath, originalConfig, updatedConfig, agentsPath, agents, updatedAgents);
+}
+
+const TARGETS = {
+  opencode: {
+    label: "OpenCode",
+    configure: configureOpencode,
+    hint: "Quit and restart OpenCode to load the updated configuration and instructions.",
+  },
+  claude: {
+    label: "Claude Code",
+    configure: configureClaude,
+    hint: "Start a new Claude Code session to load the updated configuration and instructions.",
+  },
+  codex: {
+    label: "Codex",
+    configure: configureCodex,
+    hint: "Start a new Codex session to load the updated configuration and instructions.",
+  },
+};
+
+export async function install(argv = []) {
+  const target = argv.length === 1 ? TARGETS[argv[0]] : undefined;
+  if (!target) {
+    throw new Error("usage: mindroot install <opencode|claude|codex>");
+  }
+  await init();
+  await start();
+  if (process.exitCode) return;
+
+  const { cfg } = ensureConfig();
+  const response = await fetch(`http://127.0.0.1:${cfg.port}/api/projects`, {
+    headers: { Authorization: `Bearer ${cfg.apiKey}` },
+    signal: AbortSignal.timeout(5000),
+  });
+  if (!response.ok) {
+    throw new Error("mindroot is not ready with the configured API key; run mindroot restart and retry");
+  }
+  await response.body?.cancel();
+
+  const { configPath, agentsPath } = target.configure(cfg);
+  console.log(`${target.label} MCP configured: ${configPath}`);
+  console.log(`Mindroot instructions synced: ${agentsPath}`);
+  console.log(target.hint);
+}

package/src/core.js

@@ -16,13 +16,15 @@ import { ONNX_MODEL_ID } from "./paths.js";
 import { searchMemories as hybridSearchMemories, searchNotes as hybridSearchNotes, searchProjects } from "./search.js";
 
 export { searchProjects };
+export { listSkills, readSkill, saveSkill, deleteSkill, searchSkills } from "./skills.js";
 
 export async function listProjects(db) {
   return db
     .prepare(
       `SELECT p.slug, p.created_at,
               (SELECT COUNT(*) FROM docs d WHERE d.project_id = p.id) AS docs,
-              (SELECT COUNT(*) FROM memories m WHERE m.project_id = p.id) AS memories
+              (SELECT COUNT(*) FROM memories m WHERE m.project_id = p.id) AS memories,
+              (SELECT COUNT(*) FROM skills s WHERE s.project_id = p.id) AS skills
        FROM projects p ORDER BY p.slug`,
     )
     .all();
@@ -50,7 +52,12 @@ export async function renameProject(db, from, to) {
   if (await fs.stat(targetDir).then(() => true, () => false)) {
     throw httpError(409, `directory already exists: ${to}`);
   }
-  await fs.rename(projectDir(from), targetDir);
+  // A project containing only skills or memories may have no notes directory.
+  const hasNotes = await fs.stat(projectDir(from)).then(() => true, (err) => {
+    if (err.code === "ENOENT") return false;
+    throw err;
+  });
+  if (hasNotes) await fs.rename(projectDir(from), targetDir);
   db.prepare("UPDATE projects SET slug = ? WHERE id = ?").run(to, project.id);
   db.prepare("DELETE FROM project_embeddings WHERE project_id = ?").run(project.id);
   return { renamed: { from, to } };