The plugin keeps a **Memory** folder in your vault for notes that shape how Steward remember its previous works.

## Tool instructions memory

Extra guidelines per tool that are merged into the agent prompt when those tools are active.

The Memory notes are meant for the **model** (and you when you want to tune behavior). Steward reads validated YAML blocks from the file; prose above or between blocks is for the model only and is not parsed as guidelines.

See [YAML blocks in markdown](YAML-blocks-in-markdown) for the shared pattern (fences, validation, and the `status` field).

### Location

| Item              | Path                                                                      |
| ----------------- | ------------------------------------------------------------------------- |
| Folder            | `Steward/Memory/`                                                         |
| Agent guide       | `Steward/Memory/Agent.md` — how to edit tool instructions (for the model) |
| Tool instructions | `Steward/Memory/Tool instructions.md`                                     |

On first run, Steward creates the folder and starter **`Agent.md`** and **`Tool instructions.md`** if they do not exist. Saving or editing **Tool instructions** triggers validation; frontmatter `status` is updated automatically (`Valid` or `Invalid: …`).

### Agent.md

`Agent.md` is a short, model-facing checklist: section layout (heading per tool, no underscores in the heading; YAML block below), the `tool_instruction` field table, and re-read **Tool instructions** after edits to confirm `status` is valid.

### How tool instructions work

1. **Built-in guidelines**: Each tool already has descriptions and guidelines in Steward. Those are always the baseline.
2. **Memory guidelines**: Valid `tool_instruction` YAML blocks in `Tool instructions.md` add more bullet points for the matching tool.
3. **When they apply**: Memory guidelines are merged into the system prompt for **active** tools only (same timing as [Guardrails](Guardrails) rule text for tools). They apply on the next agent turn after the file is loaded or updated.

Hard-coded guidelines appear directly under each tool heading in **Tool → Guidelines**; **Guardrails** and **Memory** use their own subheadings when present.

### Block format

Each guideline set is a ` ```yaml ` fence with `name: tool_instruction`:

| Field        | Required | Description                                                            |
| ------------ | -------- | ---------------------------------------------------------------------- |
| `name`       | Yes      | Must be `tool_instruction`                                             |
| `tool`       | Yes      | Tool id (e.g. `shell`, `grep`, `edit`), must match a Steward tool name |
| `enabled`    | No       | `false` skips this block. Default `true`                               |
| `guidelines` | Yes      | List of strings; one guideline per line                                |

The whole note can be disabled with `enabled: false` in frontmatter (same pattern as guardrails and skills).

#### Example block

```yaml
name: tool_instruction
tool: shell
enabled: true
guidelines:
  - (Steward adds its custom guidelines here)
```

You or Steward can add multiple blocks for different tools, or several blocks for the same tool (guidelines are appended in file order).

Only `tool_instruction` blocks are loaded. Other YAML fence types in the file are reported as validation errors.

### Example: RTK and the shell tool

[RTK](https://github.com/rtk-ai/rtk) is a CLI proxy that compresses common command output (git, tests, docker, etc.) to save tokens in LLM context. Steward does **not** hard-code RTK. You (or the model) record how to use RTK in **Tool instructions** for the `shell` tool.

#### Scenario

You ask Steward to help save tokens when running shell commands, and to install RTK if needed:

> Install [rtk](https://github.com/rtk-ai/rtk) for token-saving on shell output, and remember to use it for routine commands.

Steward may install RTK (e.g. via `shell` after your confirmation) and update `Steward/Memory/Tool instructions.md` with a `tool_instruction` block for `shell`, similar to:

```yaml
name: tool_instruction
tool: shell
enabled: true
guidelines:
  - Run routine non-interactive commands as rtk <command> (e.g. rtk git status) so output stays compact for follow-up turns.
  - Use plain shell (no rtk prefix) for interactive programs. output.
```

#### What happens on later turns

1. The model activates `shell` (or it is already active) via `activate_tools`.
2. The activate result reminds the model that supplemental guidelines can be edited in `Steward/Memory/Tool instructions.md`.
3. When the model calls the **shell** tool, Steward shows your command for confirmation as usual; Memory does not rewrite commands automatically.
4. On each agent turn, the **shell** entry under **Tool → Guidelines** lists built-in bullets first, then **Guardrails** and **Memory** subsections when present; Memory lines come from `Tool instructions.md`, so the model tends to choose `rtk git status` instead of raw `git status` without you repeating the preference every chat.

Transcript and interactive shell behavior are described in [Shell command & Terminal](Shell-command-and-Terminal). Memory only affects **instructions in context**, not automatic command wrapping.