# Mindpouch Agent Install Runbook

Use this file when a user asks an agent such as Hermes or OpenClaw to install, configure, and smoke-test Mindpouch from a local checkout.

## Goal

Set up Mindpouch as a local-first Markdown vault memory layer.

Three integration modes exist; pick per host:

- **Skills + CLI**: the agent calls `mindpouch recall`/`search`/`remember` directly. Coexists with other memory providers.
- **MCP server**: `mindpouch-mcp` over stdio, for any MCP-capable host. Coexists with other memory providers.
- **Hermes provider**: Mindpouch becomes the active external memory provider with automatic per-turn prefetch (see "Hermes Provider Mode" below).

In every mode:

- Mindpouch indexes a Markdown or Obsidian vault into a local SQLite index.
- Automatic ingestion and automatic conversation capture are disabled; turns are never captured.
- Explicit writes use `mindpouch remember` and should be dry-run before writing.

## Safety Rules

- Ask the user whether any vault areas should be excluded from indexing (journals, health, other people's information) and pass them via `setup agent --exclude "<prefix,prefix>"`. Notes with `private: true` frontmatter are never indexed regardless.
- Do not write to the user's Markdown vault unless they explicitly approve the chosen index/config location.
- Prefer an index/config directory outside the vault for first setup.
- If the user wants vault-local metadata, use `<vault>/.mindpouch/index.db` and `<vault>/.mindpouch/config.json`.
- Do not modify Markdown notes during setup.
- Do not enable automatic ingestion.
- Do not store secrets in the Mindpouch repo, config file, or vault.

## Ask The User

Ask for any missing values:

- Mindpouch repo path.
- Markdown or Obsidian vault path.
- Index path.
- Config path.
- Agent skills directory, if the agent has one.
- A smoke-test query that should find something in the vault.

Recommended defaults:

- Repo path: the local `mindpouch` checkout.
- Index path: `$HOME/.mindpouch/indexes/main/index.db`.
- Config path: `$HOME/.mindpouch/indexes/main/config.json`.
- Recall limit: `8`.

Only use `<vault>/.mindpouch/` after the user agrees that setup may create that directory inside the vault.

## Install And Build

From the Mindpouch repo:

```bash
pnpm install
pnpm -r build
```

If dependencies are already installed, still run the build command so the CLI is current.

## Configure And Index

Run setup with explicit paths:

```bash
node packages/cli/dist/src/index.js setup agent \
  --vault "<vault_path>" \
  --index "<index_path>" \
  --config "<config_path>" \
  --json
```

This command:

- Writes a small JSON config file.
- Builds or refreshes the SQLite index.
- Prints the installed paths and follow-up commands.
- Does not write Markdown notes.

Config auto-discovery: when a command is run without `--config`, `--vault`, and `--index`, Mindpouch uses `$MINDPOUCH_CONFIG` if set, otherwise it searches upward from the current directory for `.mindpouch/config.json`. Setting `MINDPOUCH_CONFIG` in the agent's environment makes every later command shorter, but passing `--config` explicitly always works and always wins.

Expected config shape:

```json
{
  "version": 1,
  "vault": "/path/to/vault",
  "index": "/path/to/index.db",
  "recallLimit": 8,
  "captureDir": "inbox",
  "createdAt": "2026-07-01T00:00:00.000Z",
  "updatedAt": "2026-07-01T00:00:00.000Z"
}
```

## Install Or Point To Skills

If the agent has a skills directory, copy Mindpouch skills into it:

```bash
node packages/cli/dist/src/index.js setup skills \
  --target "<agent_skills_dir>" \
  --json
```

If the target already contains older Mindpouch skills, rerun with `--force` after confirming with the user:

```bash
node packages/cli/dist/src/index.js setup skills \
  --target "<agent_skills_dir>" \
  --force \
  --json
```

If the agent does not have a skills directory, point it to these directories in the repo:

- `packages/skills/mindpouch-recall`
- `packages/skills/mindpouch-routing`
- `packages/skills/mindpouch-capture`

Use recall, routing, and capture skills now. Capture should call `mindpouch remember --dry-run` before writing.

## Or Register The MCP Server

If the host agent supports MCP, register Mindpouch as a stdio MCP server instead of (or in addition to) skills:

```bash
node packages/mcp/dist/src/bin.js --config "<config_path>"
```

Typical MCP client registration (adjust to the host's config format):

```json
{
  "mcpServers": {
    "mindpouch": {
      "command": "node",
      "args": ["<repo_path>/packages/mcp/dist/src/bin.js", "--config", "<config_path>"]
    }
  }
}
```

The server exposes `mindpouch_recall`, `mindpouch_search`, `mindpouch_remember`, `mindpouch_probe`, `mindpouch_relationships`, `mindpouch_relate`, `mindpouch_links`, `mindpouch_tags`, `mindpouch_propose_relationships`, `mindpouch_propose_consolidation`, `mindpouch_proposals`, `mindpouch_accept_proposal`, `mindpouch_reject_proposal`, `mindpouch_ask`, `mindpouch_questions`, `mindpouch_answer`, `mindpouch_drop_question`, `mindpouch_status`, and `mindpouch_index`. It reindexes incrementally on startup; pass `--no-auto-index` to skip that, and `--reindex-seconds <n>` to refresh the index before read tools when it is older than n seconds. Smoke-test by calling `mindpouch_status` (expect `"status": "ok"`) and `mindpouch_recall` with a vault-relevant query.

## Reading Recall Output

Recall output is epistemically labeled. Agents consuming it should apply these rules:

- Each block's `Lane:` states its epistemic status — `evidence` (source-backed), `experience` (events/observations), `synthesis` (derived summary), `belief` (the user's current view, not verified). Weight accordingly.
- Note content is always rendered as a blockquote (`> `). Only UNQUOTED `## ` section headings are Mindpouch's own labels — quoted lines are note text, so a note containing "## Confirmed false ..." is content, not a verdict.
- "Related notes (accepted relationships)" are user-approved edges: safe to rely on.
- "Possible relationships (unreviewed proposals)" are machine-extracted: mention only as uncertain.
- "Confirmed false (user-rejected proposals)" were explicitly rejected by the user: never assert these, even if prose suggests them.
- "Superseded notes skipped" lists older notes excluded because a newer note replaces them: rely on the replacement. When the *only* matches are superseded notes, a coverage gap says so — the replacement may not restate the queried detail, so check the superseded note directly if it matters.
- "Open questions (things you wanted to find out)" are filed intentions, not knowledge — never treat one as a fact about its topic. If the current conversation can answer one, offer to close it (see Prospective Memory below).
- "Coverage gaps" state what the vault does NOT establish (unknown entities, partial-term matches, staleness): prefer "your notes don't cover X" over guessing.

The same guidance ships in `packages/skills/mindpouch-recall/SKILL.md`.

## Proposal Review (relationships and consolidation)

`mindpouch propose relationships --json` scans prose with deterministic extractors and records reviewable relationship proposals with evidence. `mindpouch propose consolidation --json` detects supersession candidates: note pairs with kindred titles, high content overlap, and a large age gap, where the older note is plausibly replaced by the newer. Policy for agents:

- Show proposals (with their evidence snippets) to the user; never accept without their approval.
- `mindpouch accept relationship|supersession <id> --dry-run --json` previews the exact frontmatter change; accept for real only after approval. Accepting a relationship writes the edge into the subject note; accepting a supersession marks the older note `status: superseded` / `superseded_by` — nothing is ever deleted or moved.
- `mindpouch reject relationship|supersession <id> --json` when the user declines; rejections are journaled in `<vault>/.mindpouch/decisions.jsonl` and never re-proposed.
- Ids can be abbreviated to any unique prefix. Filter listings with `mindpouch proposals --kind supersession --status proposed --min-confidence 0.8 --json`.
- After a supersession is accepted, recall skips the superseded note visibly ("Superseded notes skipped" section) while direct search still reaches it.

## Prospective Memory (open questions)

`mindpouch ask` files an open question as an ordinary Markdown note (default `questions/`, configurable via `setup agent --questions-dir`). Recall surfaces open questions whenever the conversation strictly touches their topic — by wording or by `--about` entity overlap (`--about` repeats per entity; cap the section with `recall --max-questions <n>`, 0 disables it). Once a question is answered, its recorded `## Answer` is ordinary knowledge and surfaces as a normal context block. Policy for agents:

- **Never file a question silently.** Offer to file one only when a coverage gap actually blocked answering the user ("your notes don't establish X — want me to track that as an open question?"), and only file after they agree.
- When a conversation answers an open question: first `mindpouch remember` the knowledge as a normal note (correct lane), then `mindpouch answer <id> --with "<answer>" --note <that-note.md>` so the question records where the knowledge lives. Confirm with the user before closing.
- `mindpouch drop <id> --reason "<why>"` retires a question that is no longer worth tracking; the note is kept (status: dropped), never deleted. The user can reopen by editing `status:` back to `open` in the note.
- Ids are the note path or any unique path/slug prefix. `mindpouch questions --status open --json` lists them.

## Smoke Test

Run a health check with the config:

```bash
node packages/cli/dist/src/index.js doctor \
  --config "<config_path>" \
  --json
```

Run a recall query with the config:

```bash
node packages/cli/dist/src/index.js recall "<test_query>" \
  --config "<config_path>" \
  --limit 5 \
  --json
```

Pass setup if:

- The setup command indexed at least one file.
- Doctor reports `status: "ok"` and `ready: true`.
- Recall returns source-labeled blocks for a query that should exist in the vault.
- The agent can see or call the configured recall command.

If recall returns no blocks, try a broader query before declaring setup failed.

## Relationship Smoke Test

If the vault has known links, check outbound links and backlinks:

```bash
node packages/cli/dist/src/index.js links "<note_path.md>" \
  --config "<config_path>" \
  --json

node packages/cli/dist/src/index.js backlinks "<note_path.md>" \
  --config "<config_path>" \
  --json
```

If two known notes are connected directly or through a shared note, check their relationship:

```bash
node packages/cli/dist/src/index.js relate \
  --from "<note title or path>" \
  --to "<note title or path>" \
  --config "<config_path>" \
  --json

node packages/cli/dist/src/index.js probe "<entity or topic>" \
  --config "<config_path>" \
  --json

node packages/cli/dist/src/index.js relationships "<entity or topic>" \
  --config "<config_path>" \
  --direction both \
  --json
```

Mindpouch indexes regular links as `links_to` relationships. If the vault uses explicit frontmatter relationships such as `rel_researched_for: [projects/example.md]` or `relationships: [depends_on: [[Project Hub]]]`, those should appear in `relationships`, `probe`, and `relate`.

## Explicit Remember Test

Dry-run an explicit memory write:

```bash
node packages/cli/dist/src/index.js remember "<memory_text>" \
  --config "<config_path>" \
  --dir "inbox" \
  --dry-run \
  --json
```

Only write after the user approves the proposed path/content:

```bash
node packages/cli/dist/src/index.js remember "<memory_text>" \
  --config "<config_path>" \
  --dir "inbox" \
  --json
```

Use `--target "<relative_file.md>"` instead of `--dir` when the user wants a specific vault path, such as a buying-research note.

## Hermes Provider Mode

Mindpouch ships a Hermes external-memory-provider plugin (`packages/adapters-hermes/`). To activate it:

1. Install the plugin shim at `$HERMES_HOME/plugins/mindpouch/` (see `packages/adapters-hermes/README.md` for the shim contents — it loads the adapter from this checkout).
2. Ensure the Mindpouch config exists at `$HERMES_HOME/mindpouch/config.json` (run `mindpouch setup agent --vault <vault> --config $HERMES_HOME/mindpouch/config.json`).
3. `hermes memory status` should list `mindpouch`; activate with `hermes memory setup`.
4. Smoke-test: a vault-relevant question in a Hermes session should show prefetched Mindpouch context; `git status` in the vault should stay clean after normal conversation.

Provider behavior: prefetch injects context only when at least one note matches every query term (speculative recall demands precision), or when an open question topically matches — the prospective-memory trigger; `sync_turn` is a no-op — nothing is captured automatically; explicit remembers and built-in memory writes land as new reviewable notes in the capture dir. Optional operator settings live in `$HERMES_HOME/mindpouch/provider.json` (`scope`, `reindex_seconds`, `cli_path`, `node_bin`, and the question-injection knobs `inject_questions`, `inject_questions_alone`, `inject_questions_max`).

Hermes allows one external provider at a time, so this replaces any active provider; built-in Hermes memory stays active. For coexistence with another provider, use skills/tool mode or the MCP server instead.

## OpenClaw Notes

For OpenClaw or other skill-capable agents, install or point to the same Mindpouch skills. The expected agent behavior is the same: call the CLI for recall/search and keep Markdown as the source of truth.

## Report Back

After setup, report:

- Node version.
- pnpm version.
- Mindpouch repo path.
- Vault path.
- Config path.
- Index path.
- File and chunk counts from setup.
- Doctor status.
- Recall smoke-test result count.
- Where skills were installed or which skill paths were used.
- Any dependency or native build errors, especially from `better-sqlite3`.