# StateJar

> Deterministic, minimal-disclosure memory infrastructure for multi-session conversational AI. No transcripts stored. Append-only history. Full audit trail.

StateJar replaces chat-history replay and probabilistic vector recall with content-addressed structured state: conversations are extracted into structured facts, canonicalized into a deterministic JSON form, and hashed with SHA-256 into `shm_…` handles. Once the state is large (over ~400 tokens), each LLM query receives only the fields it matches; a small state is sent whole. Every /chat disclosure is audited.

## Key facts

- Token use depends on conversation length. Offline benchmark (`backend/benchmarks/benchmark.py`, 2026-10-08): baseline = resending the full transcript with no system prompt; StateJar's count includes its 91-token instruction block every turn. Over a whole scripted 17-turn conversation StateJar sent 72.8% more tokens than the baseline; over a 40-turn one 3.7% fewer, saving per turn from turn 25 on. Scripted conversations in one domain; no general saving is claimed.
- SHA-256 deterministic content-addressed handles: same canonical facts → byte-identical handle, every time
- No transcript is stored, and earlier messages are never re-sent to the model (it gets the current message plus the selected fields)
- Append-only versioning: updates create new handles linked by parent_handle; history never mutates
- Conflicting facts are preserved as explicit conflict records, never silently overwritten
- Every disclosure is logged with the handle, field names, provider, model and kind (chat, query, audited query, manual, tier-3 extraction) and can be replayed; the user's message and the model's reply are never stored
- BYOK (bring your own key) LLM gateway; provider keys encrypted at rest with AES-256-GCM
- Stack: FastAPI (Python) backend, React 18 frontend, MySQL or MariaDB append-only store

## The 10 modules

1. State Extraction — turns raw conversation text into structured state (facts, preferences, constraints, goals).
2. Canonicalization — one meaning, one byte sequence: sorted keys, normalized numbers and dates, versioned schema.
3. Handle Generation — SHA-256 over canonical state yields a deterministic `shm_` content address.
4. Deduplicated Storage — an identical state is stored once per account and session.
5. No Full Chat Replay — raw transcripts are rejected at write time; only structured state is kept.
6. Minimal Disclosure Retrieval — above ~400 tokens of state, a query discloses only the fields it matches (e.g. 1 of 29 for "How many trucks do we have?" in the project's 29-message test conversation).
7. Append-Only Versioning — updates create new handles; history is immutable.
8. Conflict Preservation — contradictions are recorded, never overwritten.
9. Cross-Session Consistency — a new session starts from the user's latest state; handles can be restored into any session and used with any provider.
10. Audit + Replay — replay which handle and fields each audited response was given.

## Links

- Website: https://statejar.com
- Playground: https://statejar.com/playground
- Full details: https://statejar.com/llms-full.txt

## Docs

- [Getting started](https://statejar.com/docs/getting-started.md): From a new account to a model that remembers, in seven steps — sign up, verify your address, make an API key, install the package, sign in from the terminal, remember and recall, and see your memory in the console. Each step has a recording of it running.
- [Python SDK](https://statejar.com/docs/python-sdk.md): The statejar package on PyPI, an HTTP client for StateJar's memory API. It stores what a message says, returns only the memory a question needs as the system message for your own model, and asks before it stores an unclear amount. Your model key never reaches it.
- [Node SDK](https://statejar.com/docs/node-sdk.md): The statejar package on npm, a typed client for StateJar's memory API in Node 20.3 or later. It stores what a message says and returns only the memory a question needs, as the system message for your own model, and it never sends a request you did not make.
- [The statejar command](https://statejar.com/docs/cli.md): statejar login signs a terminal in to your account the way gh auth login does. You approve a code in the browser once, and a one-year developer key is stored on the machine, where the Python SDK and the StateJar plugins find it. Your password never passes through the terminal.
- [Any LLM provider](https://statejar.com/docs/any-llm.md): StateJar as the memory layer in front of any model. It stores what each message says, and you put the memory a question needs in front of Claude, OpenAI, Gemini, a model on your own machine or any other provider, as its system message. StateJar never calls your model and never sees its key.
- [MCP server](https://statejar.com/docs/mcp.md): StateJar's memory as Model Context Protocol tools at https://statejar.com/mcp, for any client that speaks MCP over HTTP. Ten tools; sign in with OAuth from the client or paste a developer key; the same limits, checks and audit trail as the REST API.
- [Claude Code](https://statejar.com/docs/claude-code.md): The StateJar plugin for Claude Code recalls the memory each prompt needs, captures your prompts with secrets removed, and adds StateJar's tools and six commands. Install it from the open-source marketplace with two commands.
- [Codex](https://statejar.com/docs/codex.md): 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.
- [OpenCode](https://statejar.com/docs/opencode.md): The opencode-statejar plugin adds the memory each message needs to OpenCode's system prompt, captures your messages with secrets removed, and comes with StateJar's tools. Add it and the MCP server to opencode.json.
- [OpenClaw](https://statejar.com/docs/openclaw.md): The openclaw-statejar plugin takes OpenClaw's memory slot. It recalls the memory each turn needs, captures your messages with secrets removed, and answers OpenClaw's own memory tools from StateJar.
- [Hermes Agent](https://statejar.com/docs/hermes.md): 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.
- [Agent skill](https://statejar.com/docs/skills.md): 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.
- [Pricing and payments](https://statejar.com/docs/pricing-and-payments.md): Every account is on the Free plan while billing is closed, so no plan can be bought and no payment is taken. The plan limits are enforced on our server today. What each one counts, what the API answers at a limit, where to see your usage, and what a plan never pays for.
- [StateJar for Android](https://statejar.com/docs/android-app.md): The Android app is being built and is not on Google Play yet, so there is nothing to install today. What works on a phone now, what the app will do, how it is built, and what it will never do.
- [StateJar vs Mem0](https://statejar.com/docs/mem0.md): One head-to-head, both systems on the same small local model. StateJar gave the model the right, current memory for 248 of 300 questions, and Mem0 for 152. What was measured, what each costs, and how the two are built.