# Codex

> The StateJar plugin for Codex, the same plugin as Claude Code's, recalls the memory each prompt needs, captures your prompts with secrets removed, and adds StateJar's tools and six skills. Install it from the open-source marketplace, then trust its hooks.

## What it does

- **Recall.** Codex gets the memory each moment needs, at the start of every session and before each prompt. 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 prompts are queued on your machine with secrets removed: API keys and tokens, private keys, passwords and card numbers. The queue is sent in batches: after a few prompts, at compaction and at the end of a session. StateJar extracts typed facts from them, 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.** Codex gets the ten tools of StateJar's [MCP server](/docs/mcp.html): `search`, `remember`, `get`, `list`, `update`, `delete`, `history`, `audit`, `verify` and `export`.
- **Skills.** `$statejar:search`, `$statejar:remember`, `$statejar:forget`, `$statejar:status`, `$statejar:pause` and `$statejar:resume`.

It is the same plugin as the [Claude Code](/docs/claude-code.html) one: Codex reads its own manifest and hooks from it. It is open source (MIT) in [statejar-integrations](https://github.com/KING-OF-FLAME/statejar-integrations).

## Install

You need Codex CLI 0.163 or later, and Python 3.8 or later as `python3`. The hooks use the standard library only.

```bash
codex plugin marketplace add KING-OF-FLAME/statejar-integrations
codex plugin add statejar@statejar
```

Codex asks you to review a plugin's hooks before they run. Open Codex, run `/hooks`, and trust the five StateJar hooks: SessionStart, UserPromptSubmit, Stop, PreCompact and SessionEnd. Until you do, the tools and skills work, but nothing is recalled or captured on its own.

**Tools only, without the plugin:**

```bash
codex mcp add statejar --url https://statejar.com/mcp --bearer-token-env-var STATEJAR_API_KEY
```

## Set it up

Make a developer key on the [API keys page](/api-keys) and put it in the environment Codex runs in:

```bash
export STATEJAR_API_KEY="sj_live_…"        # macOS, Linux
```

```powershell
setx STATEJAR_API_KEY "sj_live_…"          # Windows: a new terminal picks it up
```

Codex reads the key from that variable when it calls the tools, and never writes it to `config.toml`. The other options are variables too:

| Variable | Default | What it does |
|---|---|---|
| `STATEJAR_SCOPE` | `codex` | The scope in your account the plugin reads and writes. A new scope builds on your newest memory. |
| `STATEJAR_AUTO_CAPTURE` | `true` | Queue your prompts and send them in batches. |
| `STATEJAR_RECALL_EACH_PROMPT` | `true` | Add the memory each prompt needs, as one audited query per prompt. |
| `STATEJAR_API_URL` | `https://api.statejar.com/api/v1` | The REST API the hooks call. |

If `STATEJAR_API_KEY` is empty, the hooks use the key that `statejar login` (the `statejar` package on PyPI) keeps. The tools still need the variable.

## Check it works

1. `codex mcp list` shows `statejar  https://statejar.com/mcp  STATEJAR_API_KEY  enabled  Bearer token`.
2. In a session, say "I'm Kavya, I live in Bengaluru and my laptop budget is 80000 rupees." Then end the session.
3. In a new session, ask "what is my laptop budget?" or run `$statejar:search what is my budget?`. The answer uses the budget and names the handle it came from.
4. `$statejar:status` shows the scope, what is queued, and the last batch's status (202 when accepted).

## What it sends

- **Leaves your machine:** each recall sends the question (your prompt) to StateJar's query endpoint. Each batch sends your queued prompts, with secrets already removed. Nothing goes anywhere else.
- **Stays on your machine:** the queue lives in `statejar/clients/codex`, mode 600, beside the credentials file of `statejar login` (`~/.config` on macOS and Linux, `%APPDATA%` on Windows). 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.
- **What the plugin never reads:** Codex's replies, your code and your files.
- `$statejar:pause` stops recall and capture until `$statejar:resume`.

## Troubleshooting

- **Nothing is recalled or captured:** the hooks are not trusted yet. Run `/hooks` and trust the StateJar hooks.
- **"no developer key yet" at session start:** `STATEJAR_API_KEY` is not set where Codex runs, and there is no `statejar login` key.
- **`401` from the tools:** the key is wrong or revoked. Make a new one and set the variable again.
- **`429` in `$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.
- **Python not found:** the hooks run `python3` (`python` on Windows). Install Python 3.8 or later, or put it on `PATH`.