@sksoftofficial/mindroot 1.0.0 → 1.0.1

package/README.md

@@ -2,6 +2,8 @@
 
 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.
 
+![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`).
@@ -14,9 +16,9 @@ Persistent two-layer memory system for AI agents. Embedding-searched **memories*
 Requires Node.js >= 22.
 
 ```sh
-npm install -g mindroot   # or: npm link from a clone
-mindroot init             # creates store, caches the embedding model (~316MB)
-mindroot start            # daemonizes and waits until healthy
+npm install -g @sksoftofficial/mindroot   # or: npm link from a clone
+mindroot init                              # creates store, caches the embedding model (~316MB)
+mindroot start                             # daemonizes and waits until healthy
 ```
 
 ## Quick start (MCP)
@@ -37,7 +39,41 @@ 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/`.
 
-For how agents should actually *use* this memory day-to-day, see [INSTRUCTIONS.md](./INSTRUCTIONS.md) — a ready-made memory policy you can drop into your agent's configuration.
+## Agent memory policy
+
+Add this policy to your agent's instructions:
+
+```markdown
+<!-- 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.
+
+- 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 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.
+
+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.
+<!-- mindroot:end -->
+```
 
 ## CLI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sksoftofficial/mindroot",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Persistent two-layer memory for AI agents: embedding-searched memories over human-editable markdown facts. Runs as a local background service.",
   "homepage": "https://skbilisim.com/en/projects/mindroot",
   "type": "module",