OptMem for pi

Permanent memory for pi agents. OptMem keeps an append-only log and a compact binary summary tree, so memory survives sessions, compaction, model changes, and vendor changes.

Install

pi install npm:pi-optmem

Python 3.7 or newer is required. Restart pi after installation. On the first session, the extension creates ~/.optmem/memory. It then wakes automatically before the first model turn; there is no AGENTS.md block to paste.

Use a project-local installation with:

pi install -l npm:pi-optmem

To install the latest unreleased source directly from GitHub instead:

pi install git:github.com/pi-pod/pi-optmem

Update later with pi update --extensions.

What the extension does

• Runs memo wake at every pi session start and injects the result into the first turn.
• Registers the optmem tool for recording, compressing, searching, and navigating memory.
• Adds concise system guidance so durable facts and completed work are noted, and requested compressions are completed immediately.
• Initializes a missing memory store only after the extension is deliberately installed and started.

The agent-facing tool supports these actions:

Action	Purpose	Fields
note	Save one durable, non-redundant memory	text
nap	Ask for the next compression, or submit one	none, or block + text
recall	Search every raw memory with a regex	query
zoom	Open a summary block into its halves	block
wake	Continue paged startup output	optional part + snapshot
forget	Drop a bad summary so it can be rebuilt	block

Storage and configuration

~/.optmem/
  memory/
    LOG.txt     every memory, append-only
    TREE/       rebuildable summary cache
    config      size settings

Set MEMORY_DIR before starting pi to use another location, such as a synced folder or Git repository.

The bundled memo program remains the storage engine. To inspect or tune a store outside pi, run it from this checkout:

./memo config
./memo config WAKE_LINES=300
./memo recall 'project name'

Never edit LOG.txt or TREE/ directly.

Standalone CLI integration

OptMem can still be installed for other agent harnesses with the original single-file installer:

curl -fsSL https://raw.githubusercontent.com/VictorTaelin/OptMem/main/install.sh | sh

That installer prints the instruction block used by non-pi agents. The pi extension does not need it.

Development

python3 test.py
pi -e .

The Python test suite checks tree coverage, persistence, paging, UTF-8, concurrency, and crash recovery. pi -e . loads this repository as a temporary package for interactive testing.