Português · Documentation · Credits · Contributing
Hierarchical conversation memory for Pi. OptChat Durable keeps original conversation records, builds a searchable tree of summaries, and supplies a bounded memory view to each new turn. The model can retrieve original text when a summary is insufficient.
This independent implementation combines Victor Taelin's OptChat design with Pi Durable from Mario Zechner, Earendil Works and the Pi contributors. It uses official, unmodified Pi packages. No custom Pi distribution or separate OptMem installation is required. See credits, source revisions and licensing boundaries; upstream endorsement is not implied.
| I want to… | Start here |
|---|---|
| Add memory to my normal Pi coding-agent conversations | Install in Pi — the recommended path for Pi users; keep Pi's tools, permissions and streaming |
| Try it without a model account or API charges | Run the standalone demo — local browser chat with simulated responses |
| Add memory and queued requests to my own application | Use the TypeScript SDK — bring your Pi Durable harness, providers and tools |
| Contribute or run the source | Develop locally — clone, run the demo, then validate changes |
The Pi package also retains the separate /optchat chat conversation from v0.3. It has its own history and queue; it is not the ordinary coding-agent conversation.
Pi Durable is installed automatically as an OptChat dependency. Pi is the terminal coding agent that provides the pi command; Pi Durable is the JavaScript/TypeScript runtime used by this integration. You do not need to install or configure that runtime separately. If you already build an application with the Pi Durable library, follow the SDK integration guide; adding OptChat to your own harness requires the documented code integration.
The release is 0.5.0, qualified against Pi 1.1.0 on macOS and Linux with Node 22.19+. Have Node, npm and Git available in your terminal. Other Pi versions and Windows are not qualified. The commands below pin the release; main can contain later changes listed under Unreleased.
This release includes the fix for the cache-prefix bug in Taelin's October 8 Gist revision. Comparative answer quality and cache savings remain unmeasured; benchmarks are optional. See cache behavior, native integration and measurement limits.
Upgrading from an earlier candidate? Finish pending work, close Pi and preserve a complete backup before installing 0.5.0. Follow the upgrade procedure.
With Pi 1.1.0 installed (pi --version), run this in your project's directory:
pi install git:github.com/kevinqz/optchat-durable@v0.5.0Then use /reload in your running Pi session, or start pi. Keep your existing login and selected model, and continue sending normal messages. OptChat imports the available text history on the selected session branch when preparing the next turn; it does not replay earlier tools. The first preparation of a long history can take additional time and summary calls. Use /resume if you want to reopen an older session.
With Node 22.19+, npm and Git available, run this in your project's directory:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent@1.1.0
pi install git:github.com/kevinqz/optchat-durable@v0.5.0
piThe first command uses Pi's official npm installation method, pinned to the qualified version. The second installs OptChat and its runtime dependencies. There is no separate Pi Durable setup, repository clone or build step.
Inside Pi, use /login to connect your provider and /model to select a concrete model with a context window of at least 40k. OptChat uses those credentials; no additional credentials file is needed. For a credential-free trial, use the standalone demo instead.
Send these one at a time, waiting for each answer:
My project is Aurora.
What is my project's name?
/optchat status
/optchat search Aurora
After the first completed turn, status should show "started": true, "mode": "native" and the archive directory. Search should return the original message containing Aurora. That verifies recording and retrieval independently of what the model answers. In a fresh session, /optchat zoom 0 1 retrieves the first original record.
When asking the model to retrieve memory, specify the current Pi session if needed. The separate /optchat chat conversation has its own history; the Pi guide explains the tool's history selection.
Continue using Pi normally. Use /resume to reopen that session; /new starts a separate memory. The Pi guide also covers project-local installation and updates/removal.
Summary calls use your provider's normal billing. The compactor initially uses the selected model unless you set --optchat-compactor provider/model-id. Its configuration is saved with the archive. The Pi guide covers budgets, commands, sessions, updates and recovery.
Use Node 22.19+ on macOS or Linux. This path does not require a Pi CLI installation, a separate Pi Durable installation or a provider account; npm installs the required runtime dependencies:
npm install -g https://github.com/kevinqz/optchat-durable/releases/download/v0.5.0/optchat-durable-0.5.0.tgz
optchat-durable --demoOpen http://127.0.0.1:4317 and send a message. The demo uses real local persistence and simulated responses and summaries; it makes no model API calls. By default, history is saved under .optchat/demo/ in the directory where you ran the command. Stop with Ctrl+C; running it again in the same directory reopens that history. The demo's model tools only retrieve memory; it cannot run shell commands or edit project files.
The standalone guide explains real providers, CLI commands and storage. Distribution is through GitHub releases; no npm-registry publication is claimed. Use the complete release URL.
| Symptom | Next step |
|---|---|
Pi does not recognize /optchat |
Check pi list, use /reload, and confirm the extension is enabled in pi config |
Status shows "started": false |
Send a normal Pi message first; installation and status inspection alone do not create the archive |
| Authentication or model error | Check /login and /model; use a concrete model with at least 40k context. Read the displayed error before retrying |
| Archive is already open in another process | Close the process using that history before reopening it; each archive allows one writer |
| Demo port 4317 is occupied | If another application uses the port, run OPTCHAT_PORT=4318 optchat-durable --demo. Stop an earlier demo that uses the same history first |
See the Pi recovery guide or standalone storage guide for interrupted work. If the problem persists, open a bug report with versions and a synthetic reproduction. Report sensitive findings through Security.
The release also provides offline archive inspection and export, including journals left before Pi saved its first transcript. These commands do not start models or replay host actions.
SDK hosts must call await optchat.prepare(storage) before Harness.open(). For a separate read-only compatibility preview, 0.5.0 adds optional await optchat.check(storage); preparation still checks again. The Pi adapter and openApp handle preparation automatically. See compatibility and upgrades before updating an existing archive.
- Indexes conversation text with references to its original records. Thinking blocks are excluded from memory.
- Builds binary summaries, targeting 512 UTF-8 bytes per node by default. Short text can remain verbatim without a model call.
- Maintains a bounded chronological view, retaining more detail for recent records. Budgets count bytes and markup, not exact tokens.
- Freezes that view for a turn. The live input and tool loop remain complete; incomplete preparation stops the request.
- Provides paginated original-text retrieval, literal case-insensitive search and timestamps. Summaries are an index, not proof of exact wording.
The architecture distinguishes native Pi memory from SDK request execution. The conformance review records adaptations to Taelin's design.
- Memory is recoverable; perfect recall is not guaranteed. A model can omit facts or fail to retrieve them. Quality, cache savings, cost and latency need real-provider evaluation.
- Native Pi tool execution stays in Pi. The adapter does not automatically replay external actions after a crash. Durable summary requests may be repeated and billed again.
- Data is local and unencrypted. Real providers receive model context and summary inputs. Context edits affect future views and retrieval; they do not erase append-only archives or backups.
- Native
--no-sessionis ephemeral. Explicitly opening the separate durable chat still creates persistent data. - The web UI is single-user and loopback-only. It is not a hosted service, semantic/vector search engine, or automatic memory of every file in a project. Its current interface language is Portuguese.
The 0.4.0 release consolidates native Pi memory, recovery and SDK integration. Its unchanged runtime passed 106 deterministic tests and package/installation/upgrade checks on the macOS/Ubuntu × Node 22.19/24 matrix. Real ChatGPT login, memory retrieval and native login renewal were also observed. The release validation record distinguishes those checks from unmeasured performance.
The repository includes frozen protocols and runners for answer quality and continuous cache use, both compared with ordinary Pi. Developers can also evaluate through native Pi login with ChatGPT, using isolated histories and shared token/call limits without an API-key fallback. These extensive studies are optional and have not been run; they do not block installation or the companion project. Synthetic storage observations through 100k short records are tied to their recorded source revisions; they do not establish real-model quality or general large-archive performance.
The roadmap separates the functional release from optional comparative research. The separate Pi Durable Agent application has published its first operational 0.1.0 release with Cloudflare hosting, approved Code Mode session-note actions and coordinated checkpoints. Its roadmap and qualification limits live in that repository. These application features are not dependencies or capabilities added to the OptChat memory package.
The upstream composition review records what Pi already provides, why OptChat retains its preparation protocol, and the coordinated simplification work across both repositories.
Clone the repository and start the source demo without model credentials:
git clone https://github.com/kevinqz/optchat-durable.git
cd optchat-durable
npm ci
npm run demoOpen http://127.0.0.1:4317. Stop the demo with Ctrl+C before another command opens the same history. Then validate your changes and try the SDK example:
npm run check:local
node examples/native-host.mjsnpm run format applies the repository style. To try the checkout as a Pi extension, run pi -e . from the repository root after npm ci; it uses TypeScript source and needs no build. Enable only one copy of OptChat in that profile. The SDK example uses a simulated provider and temporary in-memory storage.
These commands run from a checkout of this revision. check:local runs all engineering and distribution gates locally, without a push or GitHub Actions. Checks and the demo need no real model credentials; distribution checks need local loopback plus npm access or a populated cache. A documented offline route also uses a local, checksum-verified upgrade baseline. Ordinary Pi conversations use your selected provider. Start with the repository map and conventions, contribution workflow and release process.
MIT for this repository's original code and documentation. The original OptChat gist is linked, not bundled or relicensed. Dependency licenses remain their own. CITATION.cff, NOTICE and third-party notices preserve attribution in the distribution. Run optchat-durable credits to read it locally.