priorstates 0.1.13__tar.gz

priorstates-0.1.13/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

priorstates-0.1.13/NOTICE

@@ -0,0 +1,8 @@
+PriorStates
+Copyright 2026 Zhendong Qin
+
+This product is licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. A copy of the
+License is provided in the LICENSE file and at:
+
+    http://www.apache.org/licenses/LICENSE-2.0

priorstates-0.1.13/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: priorstates
+Version: 0.1.13
+Summary: Shared memory & research journal for your AI agents — memory + journal + cockpit + runnable-markdown (mdlab) for Claude, Codex, and Gemini.
+Author: Zhendong Qin
+License: Apache-2.0
+Keywords: ai,memory,journal,mcp,claude,codex,gemini,mdlab
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: numpy>=1.21
+Provides-Extra: onnx
+Requires-Dist: onnxruntime>=1.16; extra == "onnx"
+Requires-Dist: tokenizers>=0.15; extra == "onnx"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Provides-Extra: extras
+Requires-Dist: pyyaml>=6; extra == "extras"
+Requires-Dist: pandas>=2; extra == "extras"
+Provides-Extra: kernel
+Requires-Dist: jupyter_client>=8; extra == "kernel"
+Requires-Dist: ipykernel>=6; extra == "kernel"
+Provides-Extra: winterm
+Requires-Dist: pywinpty>=2; sys_platform == "win32" and extra == "winterm"
+Provides-Extra: sign
+Requires-Dist: cryptography>=41; extra == "sign"
+Provides-Extra: full
+Requires-Dist: onnxruntime>=1.16; extra == "full"
+Requires-Dist: tokenizers>=0.15; extra == "full"
+Requires-Dist: mcp>=1.2; extra == "full"
+Requires-Dist: pyyaml>=6; extra == "full"
+Requires-Dist: pandas>=2; extra == "full"
+Requires-Dist: jupyter_client>=8; extra == "full"
+Requires-Dist: ipykernel>=6; extra == "full"
+Requires-Dist: pywinpty>=2; sys_platform == "win32" and extra == "full"
+Requires-Dist: cryptography>=41; extra == "full"
+Dynamic: license-file
+
+<div align="center">
+
+# 🔭 PriorStates
+
+### Shared memory &amp; a research journal for your AI agents
+
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![MCP-native](https://img.shields.io/badge/MCP-native-3fb950.svg)](https://modelcontextprotocol.io/)
+[![100% local](https://img.shields.io/badge/100%25-local-3fb950.svg)](#private-by-default)
+[![Stars](https://img.shields.io/github/stars/zqin2012/priorstates?style=social)](https://github.com/zqin2012/priorstates)
+
+**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 &amp; 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](https://priorstates.com)**  ·  🎬 **[80-second demo](https://priorstates.com)**  ·  📖 **[Docs](docs/USER_GUIDE.md)**
+
+<img src="docs/img/demo.gif" alt="PriorStates in action: save a memory, then recall it by meaning in a brand-new agent session" width="760">
+
+</div>
+
+## 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`](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:
+
+<details open>
+<summary><b>🐧 Linux (Debian / Ubuntu) — the <code>.deb</code> (recommended)</b></summary>
+
+Apt pulls in `python3` + `numpy`, and you get the desktop app, an icon, the
+`priorstates` CLI and man pages — nothing else to install:
+
+```bash
+curl -fSLO https://github.com/zqin2012/priorstates/releases/latest/download/priorstates_0.1.0_all.deb
+sudo apt install -y ./priorstates_0.1.0_all.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 — `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.
+</details>
+
+<details>
+<summary><b>🪟 Windows — the one-click installer (easiest of all)</b></summary>
+
+Download and run
+**[PriorStates-Windows-Setup.exe](https://github.com/zqin2012/priorstates/releases/latest/download/PriorStates-Windows-Setup.exe)**
+— it auto-installs Python if you don't have it, then installs PriorStates and adds
+Start Menu + Desktop shortcuts. Nothing else required.
+</details>
+
+<details>
+<summary><b>🍎 macOS / any OS with Python 3.10+ — pip</b></summary>
+
+```bash
+pip install --user --no-cache-dir "priorstates @ git+https://github.com/zqin2012/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](docs/QUICKSTART.md).
+</details>
+
+Full install matrix (`.deb` / macOS `.pkg` / Windows / source) is in
+**[docs/QUICKSTART.md](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 &amp; 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 &amp; 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 &amp; results in one file and splice output back in. |
+
+All of it is wired into your agents over the open **[MCP](https://modelcontextprotocol.io/)**
+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.
+
+<img src="docs/img/cockpit.png" alt="The PriorStates cockpit — search and manage memory, journal and docs in one local web view" width="820">
+
+<img src="docs/img/cli.png" alt="PriorStates CLI — capture a memory in plain English, list pinned memories, search the journal by outcome" width="720">
+
+## 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.
+
+## 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&nbsp;MB model download
+whenever you want.
+
+## 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):
+
+```bash
+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:
+
+```bash
+priorstates pack import --demo
+```
+
+## Docs
+
+- **[docs/USER_GUIDE.md](docs/USER_GUIDE.md)** — the everyday-use manual. **Start here.**
+- **[docs/PROJECTS_AND_AREAS.md](docs/PROJECTS_AND_AREAS.md)** — Projects vs Areas: the two scoping axes + the GUI Area selector.
+- **[docs/QUICKSTART.md](docs/QUICKSTART.md)** — install + first run.
+- **[docs/RESEARCH_WORKFLOW.md](docs/RESEARCH_WORKFLOW.md)** — research folders + how agents log to the journal.
+- **[docs/DATA_MODEL.md](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 — **[service@priorstates.com](mailto:service@priorstates.com)**.
+Bug reports and feature requests are welcome as GitHub issues.
+
+## License
+
+**Apache-2.0** (permissive + patent grant). See [LICENSE](LICENSE) and [NOTICE](NOTICE).
+Copyright 2026 Zhendong Qin.

priorstates-0.1.13/README.md

@@ -0,0 +1,181 @@
+<div align="center">
+
+# 🔭 PriorStates
+
+### Shared memory &amp; a research journal for your AI agents
+
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![MCP-native](https://img.shields.io/badge/MCP-native-3fb950.svg)](https://modelcontextprotocol.io/)
+[![100% local](https://img.shields.io/badge/100%25-local-3fb950.svg)](#private-by-default)
+[![Stars](https://img.shields.io/github/stars/zqin2012/priorstates?style=social)](https://github.com/zqin2012/priorstates)
+
+**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 &amp; 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](https://priorstates.com)**  ·  🎬 **[80-second demo](https://priorstates.com)**  ·  📖 **[Docs](docs/USER_GUIDE.md)**
+
+<img src="docs/img/demo.gif" alt="PriorStates in action: save a memory, then recall it by meaning in a brand-new agent session" width="760">
+
+</div>
+
+## 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`](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:
+
+<details open>
+<summary><b>🐧 Linux (Debian / Ubuntu) — the <code>.deb</code> (recommended)</b></summary>
+
+Apt pulls in `python3` + `numpy`, and you get the desktop app, an icon, the
+`priorstates` CLI and man pages — nothing else to install:
+
+```bash
+curl -fSLO https://github.com/zqin2012/priorstates/releases/latest/download/priorstates_0.1.0_all.deb
+sudo apt install -y ./priorstates_0.1.0_all.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 — `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.
+</details>
+
+<details>
+<summary><b>🪟 Windows — the one-click installer (easiest of all)</b></summary>
+
+Download and run
+**[PriorStates-Windows-Setup.exe](https://github.com/zqin2012/priorstates/releases/latest/download/PriorStates-Windows-Setup.exe)**
+— it auto-installs Python if you don't have it, then installs PriorStates and adds
+Start Menu + Desktop shortcuts. Nothing else required.
+</details>
+
+<details>
+<summary><b>🍎 macOS / any OS with Python 3.10+ — pip</b></summary>
+
+```bash
+pip install --user --no-cache-dir "priorstates @ git+https://github.com/zqin2012/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](docs/QUICKSTART.md).
+</details>
+
+Full install matrix (`.deb` / macOS `.pkg` / Windows / source) is in
+**[docs/QUICKSTART.md](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 &amp; 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 &amp; 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 &amp; results in one file and splice output back in. |
+
+All of it is wired into your agents over the open **[MCP](https://modelcontextprotocol.io/)**
+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.
+
+<img src="docs/img/cockpit.png" alt="The PriorStates cockpit — search and manage memory, journal and docs in one local web view" width="820">
+
+<img src="docs/img/cli.png" alt="PriorStates CLI — capture a memory in plain English, list pinned memories, search the journal by outcome" width="720">
+
+## 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.
+
+## 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&nbsp;MB model download
+whenever you want.
+
+## 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):
+
+```bash
+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:
+
+```bash
+priorstates pack import --demo
+```
+
+## Docs
+
+- **[docs/USER_GUIDE.md](docs/USER_GUIDE.md)** — the everyday-use manual. **Start here.**
+- **[docs/PROJECTS_AND_AREAS.md](docs/PROJECTS_AND_AREAS.md)** — Projects vs Areas: the two scoping axes + the GUI Area selector.
+- **[docs/QUICKSTART.md](docs/QUICKSTART.md)** — install + first run.
+- **[docs/RESEARCH_WORKFLOW.md](docs/RESEARCH_WORKFLOW.md)** — research folders + how agents log to the journal.
+- **[docs/DATA_MODEL.md](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 — **[service@priorstates.com](mailto:service@priorstates.com)**.
+Bug reports and feature requests are welcome as GitHub issues.
+
+## License
+
+**Apache-2.0** (permissive + patent grant). See [LICENSE](LICENSE) and [NOTICE](NOTICE).
+Copyright 2026 Zhendong Qin.

priorstates-0.1.13/priorstates/__init__.py

@@ -0,0 +1,13 @@
+"""PriorStates — local memory + research journal + cockpit + runnable-markdown
+for Claude, Codex, and Gemini.
+
+See docs/DESIGN.md for the architecture. Subpackages:
+  core/    shared engine (config, .psmem store, embedder, indexer, journal)
+  memory/  semantic memory (write path, pinned-block render, high-level API)
+  mdlab/   headless runnable-Markdown (parser + runner + result regions)
+  agents/  Claude / Codex / Gemini adapters + installer
+  mcp/     one MCP server exposing memory_* / journal_* / mdlab tools
+  gui/     Tkinter desktop control panel
+  cli      `priorstates` entrypoint
+"""
+__version__ = "0.1.0"

priorstates-0.1.13/priorstates/__main__.py

@@ -0,0 +1,6 @@
+"""Enable `python -m priorstates ...` as a PATH-independent entry point
+(equivalent to the `priorstates` console script)."""
+from .cli import main
+
+if __name__ == "__main__":
+    main()

priorstates-0.1.13/priorstates/agents/__init__.py

@@ -0,0 +1,9 @@
+"""pm-agents — Claude / Codex / Gemini adapters + installer.
+
+All three agents speak MCP for tools, so the memory/journal/mdlab logic is
+written once (priorstates.mcp.server) and each agent differs only in (a) where its
+MCP registration lives and (b) which context file the pinned block goes into.
+That whole per-agent surface is the ADAPTERS table in adapters.py.
+"""
+from .adapters import ADAPTERS, detect_installed, pinned_targets  # noqa: F401
+from .install import install, uninstall, status, protocol  # noqa: F401