@amaster.ai/pi-memory

Persistent curated memory for pi agents — MEMORY.md (the agent's own notes) and USER.md (what the agent knows about the user). The extension loads both files at session start and injects a sanitized snapshot into the system prompt. Writes are durable on disk immediately and visible through memory_read right away; the system-prompt snapshot refreshes after successful context compaction or in a new session.

Modeled after hermes' default MemoryStore mechanism (no provider/manager abstraction).

Storage

• Location: <agentDir>/memories/MEMORY.md and <agentDir>/memories/USER.md
• Entries separated by \n§\n
• Atomic writes via temp-file + rename
• Read-modify-write protected by proper-lockfile
• Drift detection: if the on-disk file contains content that wouldn't round-trip through the parser/serializer (or any single entry exceeds the per-store char limit), the mutation is refused and a .bak.<unix-ts> snapshot is taken for the user to recover from.

Safety

Every write — and every system-prompt snapshot build — runs the content through the bundled threat-patterns scanner at the strict scope. Patterns cover prompt injection, role hijack, C2 framework names, exfiltration, persistence (SSH backdoor, agent-config edits), and invisible unicode.

Tools

Four LLM-callable tools (separate, not action-multiplexed):

target is 'memory' (the agent's own notes) or 'user' (user profile facts).

Defaults

These are total chars after §-joining all entries. The limit is enforced at write time, and at load time as a drift signal (single-entry overflow).

Integration Modes

Mode 1: Extension auto-discovery (standalone / CLI)

When installed as a dependency with the pi.extensions field declared in package.json, the runtime auto-discovers and loads the extension. The extension creates its own MemoryStore with file-based storage at <agentDir>/memories/ — fully self-contained.

pi.extensions → session_start → initialize store → register tools
              → before_agent_start → append frozen snapshot to systemPrompt
              → session_compact → reload MEMORY.md/USER.md for the next agent run
              → session_shutdown → release

• Storage: <agentDir>/memories/MEMORY.md and <agentDir>/memories/USER.md
• Lifecycle: capture a fresh system-prompt snapshot for new and forked sessions, restore it on resume or reload, and refresh it after successful compaction
• Status command: /memory status shows entry counts per file
• LLM tools: memory_add, memory_replace, memory_remove, memory_read

Configure via the pi-memory settings key:

Project .pi/settings.json values are loaded only after project trust is accepted and are not environment-interpolated. User and agent settings retain environment interpolation.

{
  "pi-memory": {
    "dataDir": "/custom/memory/path",
    "memoryCharLimit": 4000,
    "userCharLimit": 2000
  }
}

Mode 2: Dependency import (host-controlled)

When the host process owns the MemoryStore (e.g. shared across agents, test fixtures, custom storage path), construct the store yourself and register tools directly:

import { MemoryStore, createMemoryTools } from "@amaster.ai/pi-memory";

const store = new MemoryStore({
  dir: "/var/lib/pi/agent-42/memories",
  memoryCharLimit: 4000,
});
await store.loadFromDisk();

// ToolDefinition[] — wire into your tool registry directly
const tools = createMemoryTools(store);

// System prompt fragment (rebuilt by loadFromDisk; freeze it for the session)
const promptBlock = store.formatAllForSystemPrompt();

You can also pass a pre-built store into the extension via injectedConfig to keep the extension lifecycle but use your own storage:

import memoryExtension from "@amaster.ai/pi-memory";

memoryExtension(pi, { store });

Drift recovery

If memory_add / memory_replace / memory_remove returns success: false with driftBackup: ".../MEMORY.md.bak.<ts>", the on-disk file no longer round-trips through the parser. This usually means a patch tool / shell append / manual edit / concurrent session wrote raw content that broke the §-delimited structure.

To recover:

1. Open the .bak.<ts> snapshot and identify content not yet captured as clean entries.
2. Add each missing entry via memory_add.
3. Either delete the original MEMORY.md (the next add will recreate it) or rewrite it as a clean §-delimited list.

The drift guard exists to prevent silent data loss — never bypass it by deleting .bak.<ts> snapshots blindly.

Prompt snapshot

loadFromDisk() refreshes live entries from disk and rebuilds the sanitized system-prompt block. A new or forked session captures that block and persists it in the Pi session; resume and reload restore a saved block after validating it again. Invalid saved blocks fall back to a newly sanitized disk snapshot. The same bytes are reused across agent runs until successful context compaction, while session-tree navigation selects the snapshot saved on that branch. Subsequent add / replace / remove calls update live state and disk, but not the frozen prompt snapshot. Why:

• Reusing the same system prompt preserves the provider's prefix-cache opportunity across agent runs in the session.
• Tool responses always reflect live state, so the model still sees its own writes — just via tool-result tail, not system-prompt head.
• The prompt snapshot picks up changes after successful session_compact or in a new session. A changed snapshot can still cause a cache miss at that boundary.

The extension bounds very large prompt snapshots when capturing them and reserves space for both files when both are present; the memory files and tool reads retain their full content.

Lifecycle reference

Dreaming (Background Memory Consolidation)

On session start, pi-memory checks whether enough Pi session history has accumulated and, when due, starts an isolated background agent that consolidates durable facts into memory. The default global memory store reads Pi sessions across all projects; an injected store or custom dataDir reads only the active session directory. It does not add a turn to the active conversation or install an operating-system scheduled task.

How it works

1. Session-start trigger — The extension launches the check asynchronously after memory initialization, so the active session is not blocked.

2. Gate and lock — Each run checks whether enough time and turns have elapsed, then takes a cross-process lock so multiple Pi hosts cannot dream concurrently.

3. Consolidation — An agentic loop (using pi-agent-core) reviews recent Pi sessions and updates MEMORY.md/USER.md via the memory tools. Follows a 4-phase prompt: Orient → Gather recent signal → Consolidate → Verify and report.

Configuration

Add to settings.json under the pi-memory key:

{
  "pi-memory": {
    "dreaming": {
      "enabled": true,
      "minHoursSinceLastRun": 24,
      "minTurnsSinceLastRun": 5,
      "model": {
        "provider": "openai",
        "model": "gpt-4.1-mini"
      }
    }
  }
}

All fields are optional with sensible defaults. The model field accepts any provider/model pair configured in your ~/.pi/agent/models.json (built-in or custom). minSessionsSinceLastRun is accepted as a deprecated alias for minTurnsSinceLastRun.

Set "enabled": false to disable background dreaming.

Dreaming is opportunistic: it runs while a Pi host is active and catches up on the next session start. It does not run while every Pi host is closed.

Structured results (Pi 0.99+)

memory_read, memory_add, memory_replace, and memory_remove declare outputSchema and return their live store results as structuredContent. Codemode receives entries and usage directly; writes also expose success, target, and entryCount. Failed writes set isError: true and preserve available error, matches, currentEntries, usage, and drift-remediation fields. Entry text remains the existing substring reference used by replace/remove; no new entry-ID format is introduced.

const result = await tools.memory_read({ target: "memory" });
if (result.error || result.truncated) throw new Error("Read a complete memory result before updating");
const entry = result.entries.find(e => e.includes("TypeScript"));
if (entry) text(await tools.memory_replace({ target: "memory", oldText: entry, newContent: "Project uses strict TypeScript" }));

Structured output is limited to 12 KiB and top-level lists to 100 complete records. truncated: true indicates omitted records; total retains the original count where available. Oversized records with an id retain that complete ID and small scalar metadata, omit large fields, and carry truncated: true both on the record and envelope; callers must check that flag before reusing content for an update. Oversized results without a record ID return a typed output-limit error instead of clipped paths or content. A write may already have completed when that happens: inspect saved state before retrying. Readable text and renderer details are independently bounded.

Background turn extraction keeps only a bounded recent-message buffer and drains each batch after scheduling it. The serialized review context is capped at 4,000 characters, including a single oversized message; processed history is not retained in the extraction buffer.

Dreaming checks model availability before discovering history and filters files by modification time. Each pass reads at most 32 eligible session files, oldest first; a persisted cursor resumes remaining pages at the next startup without advancing the completed-scan watermark early. Reads begin with a 256 KiB tail and expand up to 8 MiB when recent turns are hidden behind large records, following the active branch within that window. At most five recent turns per file (160 per page) are retained, with beginning-and-conclusion excerpts for oversized messages and an 8,000-character consolidation prompt shared fairly across the selected sessions. History discovery shares a 5-second budget and stops on session cancellation. Session shutdown also cancels the running consolidation agent. Dangling history links and files removed during discovery are skipped. Malformed session history, permission errors, and I/O errors leave the checkpoint unchanged; restore access before the next run. Content outside these bounds is not consolidation input; omission does not authorize deleting existing facts.