# Agent skill

> One SKILL.md that any agent which reads Agent Skills can follow to remember and recall your facts with StateJar, through StateJar's MCP tools or the statejar command. Copy one folder into your agent's skills.

## What it does

The StateJar skill is an [Agent Skill](https://agentskills.io): plain instructions an agent follows to keep your facts with StateJar. With it, the agent:

- **searches before it answers** a question that depends on your facts, uses only what the search returns, and can name the handle (`shm_…`) the answer came from;
- **stores your own words**, not its summary, and reports what StateJar stored, held until said again, or declined;
- **never stores secrets** (passwords, API keys, tokens, private keys or card numbers), other people's private details, questions, hypotheticals or plans;
- **forgets on request**, saying that earlier versions keep the fact.

It calls StateJar through the [MCP server's tools](/docs/mcp.html) when the agent has them, and through the `statejar` command otherwise. The skill is open source (MIT) in [statejar-integrations](https://github.com/KING-OF-FLAME/statejar-integrations).

## Install

Copy the `statejar` folder to where your agent reads skills:

| Agent | Folder |
|---|---|
| Claude Code | `~/.claude/skills/statejar/`. The [Claude Code plugin](/docs/claude-code.html) carries its own skills. |
| OpenCode | `~/.config/opencode/skills/statejar/` or `~/.agents/skills/statejar/` |
| OpenClaw | `~/.agents/skills/statejar/`, or `skills/statejar/` inside one workspace, for that workspace only |
| Codex | `$CODEX_HOME/skills/statejar/` (`~/.codex/skills/statejar/`) |
| Hermes Agent | `~/.agents/skills/statejar/`, with `~/.agents/skills` under `skills.external_dirs` in `~/.hermes/config.yaml` |

```bash
git clone https://github.com/KING-OF-FLAME/statejar-integrations
mkdir -p ~/.agents/skills && cp -r statejar-integrations/skills/statejar ~/.agents/skills/
```

## Set it up

The skill needs one way to reach StateJar:

- **The MCP server:** add `https://statejar.com/mcp` to your agent with a developer key from the [API keys page](/api-keys), as the [MCP server page](/docs/mcp.html) shows. The agent then has the tools `search`, `remember`, `get`, `list`, `update`, `delete`, `history`, `audit`, `verify` and `export`.
- **Or the `statejar` command:** `pip install statejar`, then `statejar login`. The skill uses its `search`, `add`, `list`, `forget`, `export` and `status` commands, which come with version 0.7.0; version 0.6.0 signs in only.

A scope keeps one project's or one agent's memory apart: the command takes `--scope`, and the tools take `session`.

## Check it works

1. Tell the agent "I'm Kavya, I live in Bengaluru and my laptop budget is 80000 rupees." It reports what StateJar stored.
2. In a new session, ask "what is my laptop budget?". The agent searches first, and the answer uses the budget.
3. The [audit log](/audit) lists the search as a disclosure.

## What it sends

The skill itself sends nothing: it is instructions. What the agent sends through the tools or the command is what you tell it to remember, without secrets, and the questions it searches with. StateJar stores typed facts, never your messages, and every search is in your [audit log](/audit).

## Troubleshooting

- **The agent never uses the skill:** check the folder name is `statejar` and that it holds `SKILL.md`, in a folder your agent reads.
- **`401`:** the key is wrong or revoked. Make a new one, and set it again or run `statejar login`.
- **`429`:** your plan's limit ([what each limit counts](/docs/pricing-and-payments.html)). The agent says so and carries on without memory.
- **`statejar: command not found`, or `search` unknown:** install the package, at version 0.7.0 or later for the memory commands, or use the MCP server instead.