@henryqw/pi-memory

Keep durable preferences and cross-project facts across Pi sessions, with a frozen snapshot in each session. Bounded Markdown controls prompt size without a hand-maintained knowledge tree.

Inspired by Hermes Agent and its bounded MEMORY.md/USER.md cross-session memory pattern.

Install

pi install npm:@henryqw/pi-ask-question
pi install npm:@henryqw/pi-task-models
pi install npm:@henryqw/pi-memory

Run /task-models and configure the balanced profile before adding memory. Open /task-models again and verify that balanced no longer says not configured.

Works with

| Package | Relationship | Purpose | | --- | --- | --- | | @henryqw/pi-ask-question | Required | Provides the validated conflict prompt. | | @henryqw/pi-herdr-btw | Improves | Marks side-thread children, suppressing parent-only memory injection and dream advice. | | @henryqw/pi-task-models | Required | Provides candidate-review routes. |

Candidate review does not use the current session model as a substitute.

Use

Run /remember I prefer concise release notes. Approve an explicit conflict choice only if Pi finds one.

Read ~/.pi/agent/config/pi-memory/memory/USER.md to verify the default store. Start a new session to use its frozen snapshot.

| Surface | Type | Purpose | | --- | --- | --- | | /remember <instruction> | command | Process an instruction into compact durable memory; semantic conflicts require user resolution; busy requests queue in FIFO order. | | /dream | command | Promote invariant memory instructions into the agent-global ~/.pi/agent/SYSTEM.md. | | memory | tool | Add, replace, remove, or batch-edit entries across sessions. |

Flow

Candidate review

Exact duplicate single adds and duplicate-only add batches are deterministic exceptions when every normalized entry already exists in the selected target. They skip the model call. All other single adds and batches containing an add are independently reviewed by the local pi-memory/reviewCandidate Model Task. It defaults to the shared balanced profile.

Candidate review gives the configured model live snapshots of agent-global SYSTEM.md, MEMORY.md, and USER.md. An initially missing SYSTEM.md is empty. Unreadable, oversized, or over-cap sources fail closed.

A SYSTEM file proven present during review cannot disappear later in that session. Restore it before the next add.

It resolves the configured Pi registry primary route, then fallback, through /task-models. It never substitutes the current session model. It accepts only verified bounded JSON evidence.

A missing shared task-model config warns once at session start. Configure pi-memory/reviewCandidate with /task-models before adding memory.

An overlap or contradiction pauses through ask_question. MEMORY/USER conflicts recommend merge or replacement. SYSTEM conflicts recommend keeping SYSTEM because pi-memory never edits it.

Exact duplicate single adds and duplicate-only add batches remain deterministic and idempotent without a model call. Merge, replacement, cancellation, custom answers, and non-interactive UI leave the add unwritten. Only explicit Add separately or Add anyway writes the original add after a conflict.

/remember

/remember <instruction> shows Remembering… while its processing instruction stays hidden. It normalizes a candidate, then uses the same tool review.

If Pi is busy, it queues the trimmed instruction. It processes one queued instruction after each settled response with freshly read live entries. Unsuitable project-specific, temporary, trivial, or otherwise unsuitable content is refused.

/dream

Pi recommends /dream when memory is non-empty and no previous dream is recorded. It also recommends it when memory is non-empty and the last dream was over 30 days ago.

It recommends /dream when either store is at least 70% full and the last dream was at least 7 days ago.

/dream shows a compact tool block. It hides its internal instructions and live entries.

It records its completed run time in ~/.pi/agent/config/pi-memory/dream.json. It validates live state first and reuses unchanged memory snapshots. It gives the current session agent live memory entries and instructions to edit only the agent-global ~/.pi/agent/SYSTEM.md, never a project .pi/SYSTEM.md.

That global file must already exist and be readable. Establish it deliberately and completely, because a partial SYSTEM replaces Pi's default prompt.

Per-turn memory check

/dream and final memory qualification remain current-session-agent workflows, not Model Tasks.

Each turn's memory check asks the current agent to save qualifying durable user identity, preferences, style, or corrections immediately to target=user. It saves stable cross-project environment facts, conventions, workflow lessons, or tool quirks useful later to target=memory.

Use the memory tool immediately only when something qualifies. Save inferred habits only after two independent signals from the conversation and/or existing profile. Skip project- or repository-specific facts, task-local behavior, progress, and temporary preferences.

Config

Optional JSON file at the exact package-owned path ~/.pi/agent/config/pi-memory/config.json. All fields are optional. A missing file uses defaults. Startup never creates or rewrites the file.

| Name | Description | Values | Default | | --- | --- | --- | --- | | directory | Sets the folder for both memory stores. | Non-empty absolute path without control characters. | ~/.pi/agent/config/pi-memory/memory | | memoryCharLimit | Caps MEMORY.md by character count. | Safe integer from 1 to 100000. | 8800 | | userCharLimit | Caps USER.md by character count. | Safe integer from 1 to 100000. | 5500 |

Any other invalid configuration fails fast. Malformed JSON, invalid UTF-8, files over 64 KiB, non-object roots, unknown keys, or out-of-range values throw an error naming the problem. The file is never rewritten.

State and storage

| Store | Scope | Default cap | | --- | --- | --- | | MEMORY.md | Global agent notes shared across all projects. Do not store project-specific facts here; they belong in the repository. | 8800 characters | | USER.md | User profile. | 5500 characters |

Each file holds entries delimited by § and is size-capped. At session start, both stores are captured. Later edits do not alter injected memory.

During a session, pi-memory remembers each store file proven to exist. This includes valid, invalid UTF-8, oversized, and symlinked files.

If a proven store disappears, writes stay blocked until you restore it. A path never confirmed present can be repaired and created normally. A new session starts new presence tracking.

Read <directory>/MEMORY.md and <directory>/USER.md to inspect live state.

Backups and the lock file live outside directory, under ~/.pi/agent/config/pi-memory/backups/.

Point directory at an iCloud Drive or Obsidian-vault-synced folder. The synced vault only carries files. pi-memory owns the file format and treats the remote as opaque storage, so no merge logic runs on the Pi side.

Limits and recovery

A configured cloud-synced directory can be read outside Pi. Review ADR 006 — pi-memory global store threat model before pointing it at a shared or cloud-synced path.

When a write would exceed a store's cap, the tool rejects it and reports current usage.

Consolidate with one batch that removes or shortens stale entries and adds the new entry together. A batch checks only the final size. A batch accepts at most 100 operations. A complete serialized mutation cannot exceed 1,000,000 UTF-8 bytes.

Both limits are checked before source loading or review. Calls over either limit do not write.

An external edit or sync can push an on-disk file over its cap. The session snapshot then omits the overflow and warns instead of injecting it.

Startup lists at most three unexpected regular filenames in directory. It stops on the fourth and reports at least four.