# Hermes Agent

> StateJar as Hermes Agent's memory provider (memory.provider statejar). It recalls the memory each message needs and captures your messages with secrets removed, and it adds four tools and a statejar command.

## What it does

- **Recall.** Before each model call, Hermes gets the memory your message needs. StateJar sends the whole state while it is small, and only the fields a question needs once it is large. Every recall names the handle it came from (`shm_…`) and is written to your audit log.
- **Capture.** Your messages are queued on your machine with secrets removed: API keys and tokens, private keys, passwords and card numbers. The agent's replies and tool output are never queued. What Hermes's own memory tool saves is queued the same way.
  - The queue is sent in batches: after three messages, or at compression, session end and shutdown.
  - StateJar extracts typed facts from the messages, refuses a value that fails its type, and keeps a fact said once in a weak form until it is said again. It stores no transcript.
- **Tools.** `statejar_search`, `statejar_remember`, `statejar_forget` and `statejar_list`.
- **Commands.** `hermes statejar status | search | add | list | forget | export | pause | resume`.

Scheduled (cron), subagent and flush runs read memory but never write to it. The provider is open source (MIT) in [statejar-integrations](https://github.com/KING-OF-FLAME/statejar-integrations).

## Install

You need Hermes Agent 0.19 or later. The provider uses Python's standard library only.

```bash
hermes plugins install KING-OF-FLAME/statejar-integrations/hermes/statejar --enable
hermes memory setup          # choose statejar and paste your key
```

## Set it up

Make a developer key on the [API keys page](/api-keys). `hermes memory setup` stores it as `STATEJAR_API_KEY` in your profile's `.env`, and sets the provider in `config.yaml`:

```yaml
memory:
  provider: statejar
```

Other options go in `statejar.json` in your Hermes home (`~/.hermes` unless you use profiles):

| Key | Default | What it does |
|---|---|---|
| `scope` | `hermes` | The scope in your account the provider reads and writes. A new scope builds on your newest memory. |
| `auto_capture` | `true` | Queue your messages and send them in batches. |
| `recall_each_prompt` | `true` | Recall what each message needs, as one audited query per message. |
| `api_url` | `https://api.statejar.com/api/v1` | The REST API the provider calls. |

If no key is set, the provider uses the one that `statejar login` (the `statejar` package on PyPI) keeps.

## Check it works

1. `hermes memory status` lists `statejar ← active`.
2. `hermes statejar status` shows the scope, what is queued, and the last batch's status (202 when accepted).
3. In a chat, say "I'm Kavya, I live in Bengaluru and my laptop budget is 80000 rupees." Then end the chat.
4. In a new chat, ask "what is my laptop budget?". The answer uses the budget, and `hermes statejar search what is my budget` prints the memory with its handle.

## What it sends

- **Leaves your machine:** each recall sends the question (your message) to StateJar's query endpoint. Each batch sends your queued messages, with secrets already removed. The agent's replies and tool output are never sent.
- **Stays on your machine:** the queue lives in `statejar/` inside your Hermes home (mode 600), one per profile. Its `state.json` holds only counts, times and the last status code.
- **What StateJar stores:** typed facts, never your messages. Every disclosure is in your [audit log](/audit), and deleting your account deletes all of it.
- `hermes statejar pause` stops recall and capture until `hermes statejar resume`.

## Troubleshooting

- **`statejar` is not in `hermes memory status`:** the plugin is not installed in this profile. Install it again with `hermes plugins install …`.
- **"no developer key yet" in the agent's context:** run `hermes memory setup` again, or `statejar login`.
- **`401` from a tool:** the key is wrong or revoked. Make a new one and run `hermes memory setup`.
- **`429` in `hermes statejar status`:** your plan's per-minute or monthly limit ([what each limit counts](/docs/pricing-and-payments.html)). The batch stays queued and is sent later.
- **Nothing is captured:** `hermes statejar status` says whether memory is paused. Messages of under three words and slash commands are not captured.