Memory Plugin

Native pi /memory command for bounded project memory injection and parent-owned consolidation. It has no skill surface and honors Pi's configured agent directory.

Memory roots:

1. <agent-dir>/memory/<sha256(canonical-project-cwd)>/ — private harness memory, written first
2. <project>/.memory/ — safe, git-tracked mirror written only for explicitly safe files

<agent-dir> is resolved through Pi's getAgentDir() and may be overridden with PI_CODING_AGENT_DIR. The hashed project scope prevents punctuation-based path collisions. Private memories, credentials, and personal information never enter the public mirror.

Version: 0.2.5

Installation

pi install npm:@fradser/pi-memory
# or from this repository
pi install /path/to/pi-packages/packages/memory

Usage

Type /memory to open the management menu. Type /consolidate to start a background run without opening the menu.

Auto-memory: on

1. Select memory model
2. Enter provider/model manually
3. Consolidate memory now
4. Edit user instructions
5. Edit project instructions
6. Open memory folder
7. Toggle auto-memory

• Auto-memory is on by default. It adds bounded capture guidance; existing memory is injected independently of the toggle.
• Memory model accepts one complete provider/model reference. Menu selection and manual input use the same allowlist. Invalid persisted configuration is preserved and surfaced instead of being overwritten.
• Consolidate memory now starts a single-flight parent-owned transaction. /consolidate no-context intentionally disables session-context capture.
• Instructions use Pi's resolved context resource when available, including overrides and ancestor files.
• Open memory folder opens the configured harness directory, not a hard-coded home path.

Consolidation transaction

The parent extension owns the run from start to finish:

1. Acquire a cross-process project lock and create a private 0700 run directory.
2. Capture an immutable branch/context snapshot before launching the worker. no-context writes an explicit disabled-context manifest.
3. Launch a no-extension, read-only worker with only read, grep, find, and ls tools. The worker receives run paths and metadata, never provider credentials or a live session file.
4. Accept exactly one bounded structured JSON plan. Progress, prose, PASSED text, and validator-like output are not evidence.
5. Run validate-consolidate.py before mutation. The parent applies only selected, validated operations with atomic writes; unrelated files are untouched.
6. Rebuild the scoped indexes, run full post-apply validation, and write a receipt bound to the run, scope, exact plan artifact bytes, selected files, and final hashes.
7. Report success only after the parent-owned receipt and privacy/mirror checks verify the resulting state. Timeout, shutdown, spawn failure, stale identity, lock contention, and validation failure release the run without success notification.

An empty selected scope is a verified no-op. Global public-mirror repair is not part of scoped consolidation and requires a separate explicit confirmation.

Memory loading limits

Only direct regular Markdown files with a strict lower-case .md basename are loaded. Symlinked roots/files and non-regular entries are rejected. Loading is deterministic, harness memory shadows a public duplicate, and injection is bounded by file count, per-file size, and total size. Injected content is labeled untrusted reference data and must not be treated as instructions.

Files

memory/
├── index.ts
├── extensions/inject-memory.ts
├── extensions/consolidation-run.ts
├── extensions/memory-files.ts
├── extensions/memory-paths.ts
├── extensions/config.ts
├── procedures/consolidate.md
├── scripts/validate-consolidate.py
├── features/consolidate.feature
├── features/validate-consolidate.feature
└── tests/