priorstates 0.1.18

Shared memory & research journal for your AI agents — memory + journal + cockpit + runnable-markdown (mdlab) for Claude, Codex, and Gemini.

🔭 PriorStates

Shared memory & a research journal for your AI agents

Coding agents are amnesiacs — every session starts cold, re-deriving what you already taught them and re-running experiments a past session already concluded. PriorStates gives Claude, Codex & Gemini one local memory and a searchable research journal, so what one session learns, the next one remembers.

Runs entirely on your machine · CPU-only · no API keys · no cloud calls.

🌐 priorstates.com · 🎬 80-second demo · 📖 Docs

Install — in one sentence

Already using Claude, Codex, or Gemini? Hand it one line:

Install PriorStates: fetch https://priorstates.com/install.md and follow it.

The agent reads AGENT_INSTALL.md, installs the package, wires itself over MCP, and verifies with priorstates doctor — then restart it to load the new tools.

Prefer to do it yourself? Pick your platform. Everything installs per-user — no root/admin: the Windows .exe and macOS .pkg are "install for me only," and the one-liner / pip / tarball stay in your home. (Only the Linux .deb/.rpm use sudo, since that's how system packages work.)

🐧 Linux (Debian / Ubuntu) — the .deb (recommended)

Apt pulls in python3 + numpy, and you get the desktop app, an icon, the priorstates CLI and man pages — nothing else to install:

curl -fSLO https://priorstates.com/download/priorstates-latest.deb
sudo apt install -y ./priorstates-latest.deb   # resolves python3 (>= 3.10) + python3-numpy

Then just open “PriorStates” from your application menu (or run priorstates-gui). The desktop control panel does the rest — initialize your memory, wire Claude / Codex / Gemini over MCP, and launch the cockpit, all with a click. No further commands needed. (For agent integration it needs the MCP support package once — PIP_BREAK_SYSTEM_PACKAGES=1 pip3 install --user mcp; the app flags it if it's missing.)

sudo apt remove priorstates uninstalls. Re-running the same apt install upgrades in place.

RHEL / Rocky / Alma / Fedora — same experience via the .rpm (one noarch package for all of them; on EL9 it pulls python3.12 automatically):

curl -fSLO https://priorstates.com/download/priorstates-latest.noarch.rpm
sudo dnf install ./priorstates-latest.noarch.rpm

🪟 Windows — the one-click installer (easiest of all)

Download and run PriorStates-Setup.exe — it auto-installs Python if you don't have it, then installs PriorStates and adds Start Menu + Desktop shortcuts. Nothing else required.

The Windows installer uses free code signing provided by SignPath.io, with a certificate by the SignPath Foundation.

🍎 macOS / any OS with Python 3.10+ — pip

PIP_BREAK_SYSTEM_PACKAGES=1 pip install --user --no-cache-dir "priorstates @ git+https://github.com/priorstates-dev/priorstates.git"
priorstates init            # create ~/.priorstates + per-project .priorstates/
priorstates agents install  # wire Claude / Codex / Gemini over MCP
priorstates cockpit         # open the web cockpit → http://127.0.0.1:7700

macOS also has a native .pkg / Homebrew formula — see docs/QUICKSTART.md.

Full install matrix (.deb / macOS .pkg / Windows / source) is in docs/QUICKSTART.md. No model download is required — a built-in CPU hashing embedder works out of the box.

What's inside

	Subsystem	What it does
🧠	memory	A local semantic store. Save a fact once — any future session recalls it by meaning. Pinned facts are injected into every session.
📓	journal	An append-only research log. Every winner, loser, bug & decision becomes a searchable entry, so no experiment is run twice.
🛰️	cockpit	A pure-Python (stdlib-only) local web app that maps your memory, journal & docs — search, group, dashboards. Embedded terminal (on by default for a local cockpit; --no-terminal to disable) to run your agent CLIs right in the browser. No Node.js, no npm, no build step.
📝	mdlab	Runnable Markdown: interleave prose, code & results in one file and splice output back in.

All of it is wired into your agents over the open MCP protocol by priorstates agents install — so they recall before acting and record durable conclusions back, automatically.

MCP server

priorstates agents install registers the server into Claude / Codex / Gemini for you; to run it directly over stdio: priorstates mcp. It exposes 10 tools:

• memory — memory_add · memory_search · memory_get · memory_list_pinned · memory_pin · memory_delete
• journal — journal_add · journal_search · journal_regen
• mdlab — mdlab_run

See it in action

The cockpit maps your whole research surface; the CLI captures and recalls from your terminal.

Agent-neutral

One memory store and one journal, surfaced to Claude Code · Claude Desktop · Codex · Gemini · Antigravity through MCP and a pinned context block — no lock-in, no rewrites. Switch agents without losing a thing. The VS Code / JetBrains extensions for Claude Code and Codex share their CLI's MCP config, so they're covered automatically; Claude Desktop (its own app) is wired into claude_desktop_config.json too. Every client on the machine reads the same local store, so a memory saved in one is instantly recalled in all the others.

Global vs project memory

PriorStates keeps one global memory plus an optional per-project layer — and which one your agent uses follows its working directory, automatically:

• Anywhere (no project) → the global store in ~/.priorstates/. This is what you get right after installing.
• Inside a project you've set up with priorstates init (it creates a .priorstates/ folder in that repo) → that project's memory plus global, merged when recalling. New memories save to the project by default, so project-specific facts stay with the project and global facts stay global.

The whole rule is: memory follows the directory your agent runs in. Run an agent in a repo that has a .priorstates/ and it sees that project; run it elsewhere and it sees global. The desktop app's Projects list is just a convenient way to pick which project to browse and to launch an agent in — it doesn't change the rule. (To check where you are: priorstates doctor, or the scope badge in the cockpit.)

Private by default

Everything lives under ~/.priorstates/ and per-project .priorstates/. The default embedder is CPU-only and offline — no API keys, no telemetry, no cloud calls. Upgrade to semantic recall with a single optional ~127 MB model download whenever you want.

Removing it removes what it added. Uninstalling (Windows uninstaller, or the .pkg/tarball install.sh --uninstall) runs priorstates agents uninstall for you — taking the MCP server entry and the pinned instruction block back out of every agent it wired. Your memory under ~/.priorstates/ is left untouched. You can unwire (or re-wire) any time with priorstates agents uninstall / priorstates agents install. (For the system .deb/.rpm, run priorstates agents uninstall as your user before apt/dnf remove, since package removal runs as root and can't reach your per-user agent config.)

Share a pack

Export your memory + journal as a portable bundle and hand it to a teammate (or host it anywhere — any file or URL works):

priorstates pack export --name my-project        # → my-project.pspack
priorstates pack import ./my-project.pspack # on the other machine (or a URL)

Imported memory surfaces through the same MCP tools — no extra wiring. Imports are checksum-verified, shown for confirmation before ingest, and tagged with their source (and never auto-pinned). The cockpit has Export / Import buttons too (Import needs the cockpit started with --allow-write).

New here? Load a ready-made sample to see PriorStates populated instantly:

priorstates pack import --demo

Docs

• docs/USER_GUIDE.md — the everyday-use manual. Start here.
• docs/PROJECTS_AND_AREAS.md — Projects vs Areas: the two scoping axes + the GUI Area selector.
• docs/QUICKSTART.md — install + first run.
• docs/RESEARCH_WORKFLOW.md — research folders + how agents log to the journal.
• docs/DATA_MODEL.md — on-disk schemas + the .psmem layout.
• One-click native installers (the free Hub edition) — macOS / Windows / Linux — at https://priorstates.com/download.

Status

v0.1 — working end-to-end: memory, journal, mdlab, MCP server (10 tools), agent wiring (Claude / Codex / Gemini / Antigravity), the web cockpit, and the desktop launcher are all built and tested. Optional semantic model downloads on demand; the hashing fallback needs zero setup. A background embedder daemon and an autonomous priorstates research runner are next.

Issues and PRs welcome.

Get in touch

Questions, ideas, or feedback — [e-mail]. Bug reports and feature requests are welcome as GitHub issues.

License

Apache-2.0 (permissive + patent grant). See LICENSE and NOTICE. Copyright 2026 Zhendong Qin.