Pi Dream

Pi Dream helps Pi remember what matters between sessions. Memories remain ordinary Markdown documents backed by local Git. From time to time, a dream can gather completed sessions and attached Stores into a separate, tidier memory for you to review. Your current memory stays untouched until you explicitly choose the new one.

Install

pi install npm:pi-dream

Requirements: Pi 0.83 or later, Node 22.19 or later, Git, and macOS or Linux.

Memory in everyday Pi sessions

Start Pi in a Git repository. Pi Dream quietly creates or reuses a Repository Store and attaches it read/write for that session. Pi receives only a compact descriptor with the Store name, scope, access mode, and managed path—not the contents of every memory document.

The agent uses Pi's normal filesystem tools to consult and update memory. Valid changes become attributable Git commits at turn end. Focused files work best:

architecture/decisions.md
conventions/testing.md
integrations/payments.md
lessons/deployments.md

Choose View memory from /dream to browse documents by folder and heading, or search across their titles, paths, and contents. Long lists are paged so a well-stocked memory remains pleasant to explore. When a Primary shared memory is connected, choose between This repository and Shared memory (read-only) before browsing. The memories remain separate, and Store IDs, commit hashes, and internal Candidate names are not shown.

Connected repositories use both their repository memory and Primary shared memory by default. Choose Memory for this session from /dream to switch between Repository + shared memory and Repository memory only. This changes only subsequent prompts in the current session; it does not disconnect the repository, and information Pi already read remains in the conversation. New sessions return to the repository-and-shared default.

Inspect the current attachments or all known Stores:

/memory status
/memory stores
/memory recover

/memory recover is deliberately read-only. It surfaces preserved unsaved Attachments, interrupted Dreams, missing worktrees, Store-version disagreements, orphaned Candidate or Workspace Stores, and lock files requiring review. It never deletes or resets ambiguous data automatically.

Do not edit .pi-dream/; it contains Store identity, stable Memory IDs, and provenance managed by the extension.

Dreaming

Open the guided Dream home:

/dream

It shows the current memory, shared-memory connection, memory available to this session, eligible completed sessions, and dreams awaiting review. Shared memory — Not connected means this repository remembers independently. Choosing Begin a dream:

• asks whether the dream should update the current repository memory or a connected shared memory;
• selects completed sessions since prior work, newest first, up to 100;
• includes connected Repository Stores for a shared-memory dream;
• uses Pi's currently active model;
• previews everything before model work starts.

Escape returns to the previous Dream menu. From a memory folder it moves up one folder; from the top-level /dream home it closes Dream. Choosing Back has the same navigation meaning.

The selected dream scope is independent of the memory available to ordinary prompts. A repository dream proposes a new version of that repository's private memory. A shared-memory dream proposes a new version of the shared Store using the connected repository Stores as read-only evidence.

All eligible sessions are selected initially. Choose Choose sessions to search by conversation text and toggle sessions using their name or opening message. For advanced scripted runs, --sessions session-id-1,session-id-2 accepts a comma-separated list.

The command equivalent is:

/dream run

Use another configured Pi model for the dream worker:

/dream run --model qwen3.6-35b

The shorter form works too:

/dream --model qwen3.6-35b

For unattended scripts, add --yes to use all eligible sessions and skip the optional source and final confirmation dialogs. In a repository without shared memory, the current repository is the target. When shared memories are connected, select one explicitly with --workspace <workspace-id>, or pass the repository Store with --target <store-id> for a private dream; otherwise Pi Dream still asks which scope to use. An unknown --workspace fails clearly instead of falling back to another memory. Optional memory from another repository is included only when --source is supplied.

Pi resolves model names using its existing configuration. Pi Dream does not modify models.json and does not silently substitute a different model. A genuinely local model with zero configured pricing can therefore perform dreams without provider token charges.

After confirmation, a dream takes shape quietly in the background. Its Target and Source Stores remain unchanged, and you can keep using Pi while it works.

Each completed dream receives a short, grounded name derived locally from the memory it kept—no additional model call is made. Examples include Rayed, remembered, Payments, clarified, and Agent Bench, gathered. The technical dream_… ID remains available when you need it.

Review a dream before deciding what future sessions should remember:

/dream list
/dream status dream_…
/dream review dream_…
/dream diff dream_…
/dream verify dream_…
/dream promote dream_…
/dream discard dream_…
/dream cancel dream_…

/dream list shows human names and friendly states. Use /dream list --technical when you need IDs for the advanced commands above.

The guided home and /dream list show dreams for the current repository and its connected shared memories. They do not mix in dreams from unrelated repositories. Use /dream list --all only when you deliberately want the cross-repository history; an explicit dream ID can still open any known dream.

The guided review begins with what the dream kept. Choose Review memory to read the proposed Markdown documents, Remember this to make it active for future sessions, or Technical details to inspect Store IDs, commits, the raw Git diff, provenance, and verification data.

Using the new memory changes the Active mapping for future sessions only. Existing sessions stay attached to their original Store, and the previous memory remains available.

Sharing memory across repositories

Pi Dream lets related repositories remember together through named shared memories, without merging their independent memories or creating a global memory pool.

From one repository, connect another local repository by name:

/dream connect payments-web

Pi Dream looks among previously encountered repositories and sibling Git checkouts. The guided picker shows ten repositories at a time and can search by repository name or path. If a name matches more than one checkout, it shows the matching paths. Relative and absolute paths remain available when needed:

/dream connect ../payments-web
/dream connect /Users/alice/code/payments-web

An ordinary folder inside the current repository is never mistaken for another repository. Before connecting, Pi Dream proposes a shared-memory name such as Payments API + Payments Web; accept it or choose another name. It does not derive names from generic parent folders such as code.

The extension previews the relationship before changing anything:

payments-api ─┐
payments-web ─┴─> Acme Payments shared memory

payments-api memory             read/write
Acme Payments shared memory    read-only when Primary

After confirmation:

• each repository keeps its own independent Repository Store;
• the shared memory gets a separate Store;
• accepting Use as Primary shared memory? makes future sessions in both repositories attach it read-only;
• declining that question leaves the connection available without changing either repository's Primary shared memory;
• dreams for the shared memory may use member Repository Stores as pinned evidence;
• no model runs merely because repositories were connected.

A newly created shared Store starts empty. Connecting does not copy, merge, or make the member repositories' private memories directly searchable from one another. Shared content is populated only when a shared-memory dream uses the member Repository Stores as evidence and you choose Remember this. Later repository changes reach the shared Store only through another reviewed shared-memory dream.

The resulting shared memory can be read and searched from any member repository where it is Primary. A repository's own memory remains private to that repository; connecting does not expose it directly to the other members. View memory presents the repository and Primary shared memory as separate choices.

After a connection is created, choose Later to finish or Dream with this shared memory now to open the guided shared-memory dream flow. The latter still shows session choices and requires final confirmation before any model work starts.

Repositories with an origin remote are identified by that remote. If a checkout moves, starting Pi from its new location associates the existing Store with the new path. Repositories without a remote use their local path as identity.

Choose Manage connections from /dream, or run /dream connections, to see how this repository shares memory. If nothing is connected, Pi Dream explains that the repository remembers on its own and offers Connect a repository or Back. When connections exist, select one to see the repositories remembering together, its read/write boundaries, and whether it is the Primary shared memory. You can then disconnect the current repository with confirmation; no Stores or historical dreams are deleted.

Connecting a different repository creates a separate shared memory instead of silently adding it to an existing one. Reconnecting the same repository pair reuses their existing shared memory. Adding further repositories to a particular shared memory is available through the advanced /dream workspace add-repo command.

Workspace is the internal domain term for a shared memory. You will mainly see it in advanced commands and technical recovery details:

/dream connections
/dream disconnect
/dream workspace list
/dream workspace show <workspace-id>
/dream workspace validate <workspace-id>

When starting a dream in the guided UI, Additional memory can include memory from another repository that Pi Dream already knows about. Select the repository by name; Pi Dream reads a pinned snapshot for that dream only. It does not connect the repositories or change either repository's memory.

For scripts and advanced use, the same one-dream-only memory can be supplied by Store ID:

/dream run --source store_…

Safety and local data

All state lives under ~/.pi/dream, or PI_DREAM_HOME when explicitly overridden. Pi Dream uses separate Store refs and managed worktrees, atomic registry writes, compare-and-swap ref updates, recovery refs, and owner-only files.

Dream workers receive prepared session transcripts and pinned Source snapshots as untrusted evidence. Their tool access is limited to reading declared evidence and editing the Candidate Store. Validation rejects path traversal, symlinks and special files, oversized or non-UTF-8 documents, reserved metadata tampering, and likely secrets.

Pi Dream does not configure Git remotes, transmit telemetry, automatically use a dream’s memory, or start billable model work merely by opening /dream.

Development

To use a local checkout before the npm package is published:

pi -e /absolute/path/to/pi-dream

npm ci
npm run check
npm pack --dry-run

The suite uses real temporary Git repositories and real Pi RPC processes. Its deterministic end-to-end journeys cover extension loading, persisted sessions, cross-repository shared-memory dreams, review and provenance, promotion into future sessions, and discard safety. Lower-level tests cover Store commits, candidate isolation, concurrency, recovery, secret redaction, connection DAG validation, and switching session memory without removing a connection.

Contributor references:

• Product and technical specification
• Terminology and user-facing language

License

MIT. See LICENSE.