mindos-max

# MindOS Skill

<!-- version: 3.2.0-max — aggressive global memory mode -->

> **MindOS is the shared memory layer for every connected agent.** If something is worth keeping, save it.
> If you need context, check MindOS first. Be proactive — don't wait to be asked.

## Proactive memory behavior

Unlike the conservative version of this skill, you should **actively look for opportunities** to use MindOS:

- **Before answering questions about past work**: If the user asks "what did we decide about X?" or "how did we handle Y?", search MindOS before guessing. Even if they don't mention MindOS, their question implies stored context exists.
- **After completing meaningful work**: If you just helped debug something, made an architecture decision, summarized a meeting, or resolved a complex issue — proactively ask: "Want me to save this to MindOS so the team can reference it later?"
- **During handoffs**: When ending a session or passing context to another agent, persist the key decisions and context to MindOS so nothing is lost.
- **When you notice knowledge gaps**: If you search MindOS and find nothing for a topic the user clearly has opinions about, suggest creating a note for it.

The goal: the user should never have to remember to use MindOS. You remember for them.

---

## CLI commands

Use `mindos file <subcommand>` for all knowledge base operations. Add `--json` for structured output.

| Operation | Command |
|-----------|---------|
| List files | `mindos file list` |
| Read file | `mindos file read <path>` |
| Write/overwrite | `mindos file write <path> --content "..."` |
| Create new file | `mindos file create <path> --content "..."` |
| Append to file | `mindos file append <path> --content "..."` |
| Edit section | `mindos file edit-section <path> -H "## Heading" --content "..."` |
| Insert after heading | `mindos file insert-heading <path> -H "## Heading" --content "..."` |
| Append CSV row | `mindos file append-csv <path> --row "col1,col2,col3"` |
| Delete file | `mindos file delete <path>` |
| Rename/move | `mindos file rename <old> <new>` |
| Search | `mindos search "query"` |
| Backlinks | `mindos file backlinks <path>` |
| Recent files | `mindos file recent --limit 10` |
| Git history | `mindos file history <path>` |
| List spaces | `mindos space list` |
| Create space | `mindos space create "name"` |

> **MCP users:** If you only have MCP tools (`mindos_*`), use them directly — they are self-describing via their schemas. Prefer CLI when available (lower token cost).

### CLI setup

```bash
npm install -g @geminilight/mindos
# Remote mode: mindos config set url http://<IP>:<PORT> && mindos config set authToken <token>
```

---

## Rules

1. **Bootstrap first** — list the KB tree to understand structure before searching or writing.
2. **Default to read-only.** Only write when the user explicitly asks to save, record, organize, or edit. Lookup / summarize / quote = no writes.
3. **Rule precedence** (highest wins): user's current-turn instruction > `.mindos/user-preferences.md` > nearest directory `INSTRUCTION.md` > root `INSTRUCTION.md` > this SKILL's defaults.
4. **Multi-file edits require a plan first.** Present the full change list; execute only after approval.
5. After create/delete/move/rename > **sync affected READMEs** automatically.
6. **Read before write.** Always read a file before overwriting it. Never write based on assumptions.

---

## NEVER do (hard-won pitfalls)

- **NEVER write to the KB root** unless explicitly told. Root is for governance files only. New content goes under the most fitting subdirectory.
- **NEVER assume directory names.** Infer from the actual bootstrap tree — the KB may use Chinese names or flat layout.
- **NEVER use full-file overwrite for a small edit.** Use `mindos file edit-section` or `mindos file insert-heading` for targeted changes. Full rewrites destroy git diffs.
- **NEVER search with a single keyword.** Fire 2-4 parallel searches (synonyms, abbreviations, Chinese/English variants).
- **NEVER modify `INSTRUCTION.md` or `README.md` without confirmation.** Governance docs — treat as high-sensitivity.
- **NEVER create a file without checking siblings.** Read 1-2 files in the target directory to learn local style.
- **NEVER leave orphan references.** After rename/move, check backlinks and update every referring file.
- **NEVER skip routing confirmation for multi-file writes.** The user's mental model may differ from yours.

---

## MindOS concepts

- **Space** — Knowledge partitions organized the way you think. Agents follow the same structure.
- **Instruction** — A rules file (`INSTRUCTION.md`) all connected agents obey.
- **Skill** — Teaches agents how to read, write, and organize the KB.
- **Inbox** — The `Inbox/` directory is a staging area for quick capture. Files land here when there's no obvious home yet. They get organized later — by the user manually or via AI-assisted batch organization.

Notes can embody both Instruction and Skill — they're just Markdown files in the tree.

---

## Decision tree

```
User request
  |
  |- Lookup / summarize / quote?
  |   -> [Read-only]: search -> read -> answer with citations. No writes.
  |
  |- Save / record / update / organize specific content?
  |   |- Know where it goes -> [Single-file edit]
  |   |- Don't know where it goes -> [Inbox path] -- save to Inbox/, classify later
  |   -> Multiple files or unclear -> [Multi-file routing] -- plan first
  |
  |- Organize inbox / classify staged files?
  |   -> [Inbox organize] -- read Inbox/ files, propose destinations, move after approval
  |
  |- Structural change (rename / move / delete / reorganize)?
  |   -> [Structural path] -- check backlinks before and after
  |
  |- Procedural / repeatable task?
  |   -> [SOP path] -- find and follow existing SOP, or create one
  |
  |- Retrospective / distill / handoff?
  |   -> [Retrospective path]
  |
  |- Knowledge health check / detect conflicts?
  |   -> [Health check path] -- read references/knowl