# Hermes Integration Plan

Mindpouch integrates with Hermes (and similar agent runtimes) in three tiers. All three now exist; Tier 3 is implemented in `packages/adapters-hermes/` (v1, CLI-subprocess transport) to the design below.

All three tiers are thin adapters over the same `@mindpouch/engine` API and share one config file. No tier owns memory semantics.

## Integration Tiers

### Tier 1: Skills + CLI (available now)

Markdown `SKILL.md` files teach the agent when to call `mindpouch recall/search/remember/probe/relate` via the CLI. Coexists with any active Hermes memory provider, and ports to OpenClaw or any skill-capable agent.

- Install: `mindpouch setup agent`, then `mindpouch setup skills --target <agent-skills-dir>`.
- With `MINDPOUCH_CONFIG` exported (or a `.mindpouch/config.json` above cwd), commands need no flags.
- Best for: users who already run another memory provider, or agents without MCP support.

### Tier 2: MCP tools (available now)

`mindpouch-mcp` (in `@mindpouch/mcp`) serves the same operations as MCP tools over stdio: recall, search, remember, probe, relationships, relate, links, tags, the proposal-review tools, the prospective-memory question tools, status, and index. The authoritative tool list lives in [AGENT_INSTALL.md](../AGENT_INSTALL.md).

- Launch: `mindpouch-mcp --config <path>` (or flag-free with config auto-discovery).
- The server reindexes incrementally on startup by default (`--no-auto-index` to skip).
- `mindpouch_recall` returns the agent-ready Markdown block; the other tools return the same JSON shapes as the CLI's `--json` output.
- Best for: MCP-capable hosts (Claude Code, OpenClaw, Hermes-as-MCP-client, IDE assistants). Still coexists with other memory providers.

### Tier 3: Hermes provider mode (implemented — `packages/adapters-hermes/`)

A Python plugin implementing the Hermes external-memory-provider interface, making Mindpouch the active memory store: automatic context prefetch before turns, provider-owned tools, and optional conservative turn capture. Hermes allows one external provider at a time, so this tier replaces (rather than coexists with) another provider; built-in Hermes memory remains active alongside.

Implementation notes (v1): CLI-subprocess transport behind `CliTransport.call(op, params)`; `prefetch` returns the epistemically labeled recall text or `None` when the vault has nothing relevant; incremental reindex before prefetch when stale (default 300s); `sync_turn` is a no-op; integration-tested against the real CLI (`python3 -m unittest discover packages/adapters-hermes/tests`). If the installed Hermes expects different method signatures, adapt in a thin subclass per the package README.

## Provider Mode Design

### Transport: CLI subprocess first, MCP client as the upgrade path

The Python provider needs to reach the TypeScript engine. Two options:

- **CLI subprocess per call** (v1 choice): run `mindpouch <cmd> --json` and parse stdout. Stateless, zero Python dependencies, per-call failure isolation, and the JSON contract is already exercised by tests. Cost: Node startup + SQLite open per call (~100–150 ms), which matters most for per-turn `prefetch`.
- **Long-lived `mindpouch-mcp` subprocess** (v2 optimization): the provider holds one MCP stdio session, keeping Node and the SQLite handle warm. Adds JSON-RPC client code (or the `mcp` Python package) and process lifecycle management (restart on crash).

The provider should hide the transport behind one internal `_call(op, args) -> dict` function so the v1→v2 swap does not touch provider logic.

### Method mapping

| Hermes provider method | Implementation |
| --- | --- |
| `name` | `"mindpouch"` |
| `is_available` | `node` on PATH + CLI dist present + cached `mindpouch doctor --json` `ready` |
| `initialize(session_id)` | resolve config, run `doctor`, run incremental `index` if `auto_index` |
| `get_config_schema` / `save_config` | vault, index, recall_limit, capture_dir, auto_index, auto_capture, scope; persisted as the standard Mindpouch config JSON |
| `get_tool_schemas` | mirror the MCP tool set (recall, search, remember, probe, relationships, relate, status) |
| `handle_tool_call` | `_call(op, args)` |
| `system_prompt_block` | short block from cached doctor counts: what Mindpouch is, vault size, "recall before answering personal-context questions" |
| `prefetch(query)` | `recall --json`, return `text` labeled as Mindpouch-sourced context |
| `queue_prefetch` | async wrapper over `prefetch` |
| `sync_turn` | **disabled by default**; see capture policy |
| `on_memory_write(content)` | `remember --json` (Hermes' explicit memory-save path) |
| `on_session_end` | optional session-summary note, off by default |
| `shutdown` | no-op (CLI transport) / close the MCP subprocess (MCP transport) |

### Capture policy

- v1: `sync_turn` off. Writes happen only through `on_memory_write` and explicit tool calls — same policy as the skills.
- v2 (opt-in `auto_capture`): conservative capture of explicitly memory-worthy turn content into the capture dir, `lane: experience`, with session id and agent name in frontmatter. Never rewrite existing notes; every captured note is a new reviewable file.
- Never write prefetched/recalled context back into the vault (no recursive memory pollution).

### Config and layout

One config file serves the CLI, MCP server, and provider. Default provider location: `$HERMES_HOME/mindpouch/config.json` with the index beside it, or vault-local `.mindpouch/` if the user prefers. The provider sets `MINDPOUCH_CONFIG` for any subprocess it spawns.

Proposed package layout:

```text
packages/adapters-hermes/
  README.md
  plugin/
    __init__.py
    plugin.yaml
    provider.py      # provider interface implementation
    transport.py     # _call() over CLI subprocess (later: MCP client)
```

### Freshness

`prefetch` must not reindex per turn. Policy: incremental `index` at `initialize`, plus reindex when `mindpouch_index`/`index` is explicitly requested, plus an optional staleness threshold (reindex before prefetch if the last index is older than N minutes). Incremental indexing makes all of these cheap on unchanged vaults.

### Engine gaps that provider mode will surface

These belong in `@mindpouch/engine` (so every adapter benefits), not in the provider:

- Recency-aware ranking (requires populating file `createdAt`/`updatedAt`).
- Token-budgeted context assembly for `prefetch` (budget in, receipt out).
- Hybrid lexical + semantic recall once the embeddings package is real.
- Relationship-aware recall (accepted edges as context, proposals as uncertain evidence).

## Setup Flow

Skills/tool mode (works today):

1. Install/build Mindpouch (`pnpm install && pnpm -r build`).
2. `mindpouch setup agent --vault <vault> [--index <index>] [--config <config>]`.
3. Smoke-test `mindpouch doctor` and `mindpouch recall <query>`.
4. Either copy skills (`mindpouch setup skills --target <skills_dir>`) or register the MCP server (`mindpouch-mcp --config <config>`), or both.
5. Run a smoke conversation: ask a vault question, confirm the agent calls recall before answering.

Provider mode adds:

1. Install/copy the Hermes provider plugin.
2. Activate with `hermes memory setup` or Hermes config.
3. Confirm `prefetch` injects Mindpouch context on a vault-relevant turn.

## Automatic Ingestion Later

Bulk ingestion (watched folders, email, calendar, web clips) remains an optional later layer, not part of provider mode v1. Rules stand: label provenance, support dry-run, write Markdown not just rows, automatic conversation capture off by default, explicit include/exclude for sensitive sources.