pi-claude-mem

A file-based, no-embeddings long-term memory system for the pi coding agent — indexed long-term memory files, automatic recall selection, daily logs, a scratchpad checklist, and opt-in background consolidation.

---

Inspired by OpenClaw's approach to agent memory: plain Markdown, file-based, no embeddings/vector search.

Layout

Memory files live under ~/.pi/agent/memory/ (override with PI_MEMORY_DIR):

Path	Purpose
MEMORY.md	Index of long-term memory files (see below) — a pure index, not freeform content
<name>.md (root)	Individual long-term memory files with name/description/type frontmatter, indexed from MEMORY.md
SCRATCHPAD.md	Checklist of things to keep in mind / fix later
daily/YYYY-MM-DD.md	Daily append-only log (today + yesterday loaded at session start)
daily/archive/*.md	Daily logs a consolidation pass has already distilled (see Consolidation below)
notes/*.md	LLM-created files (lessons, self-review, reference material, etc.)

Identity and behavioral files (e.g. SOUL.md, AGENTS.md, HEARTBEAT.md) can also live in the memory directory and be injected into context via PI_CONTEXT_FILES.

Tools

Tool	Description
memory_write	Write to long_term (a MEMORY.md-indexed file — pass filename, optional name/description/type), daily (today's log), or note (notes/filename). Supports append and overwrite modes.
memory_read	Read MEMORY.md (long_term), SCRATCHPAD.md (scratchpad), daily logs (daily), notes (note), any root file (file), or list everything (list).
memory_search	Search across all files — filenames and content. Case-insensitive keyword search across root, notes/, and daily/.
scratchpad	Manage a checklist: add, done, undo, clear_done, list.

Recall selection

Every long-term memory file gets a type (user/feedback/project/reference) and a one-line description in its frontmatter. On each new user message, a side model scans the current manifest of memory files and picks up to 5 that are clearly relevant, which get injected into context as a "Recalled memories" section (with the same staleness note as memory_read, if the file is old). No embeddings or vector search — just a small LLM call over filenames, types, and descriptions.

Selection is skipped (silently, at zero cost) when no side model/API key is available, and each file is only surfaced once per session. The selector also gets a list of tools the agent has recently called, so it can favor surfacing warnings/gotchas about those tools over basic usage documentation the agent is already exercising.

Context Injection

The following are automatically injected into the system prompt before every agent turn:

• Files listed in PI_CONTEXT_FILES (e.g. SOUL.md,AGENTS.md,HEARTBEAT.md)
• MEMORY.md (the index)
• Recalled long-term memory files relevant to the current message (see Recall selection above)
• SCRATCHPAD.md (open items only)
• Today's and yesterday's daily logs

Files in notes/ and older daily logs are not injected — they're accessible on-demand via memory_search and memory_read.

Configuration

Settings can be configured via environment variables or a .pi-mem.json file in the memory directory. Environment variables take precedence over file values.

.pi-mem.json

Place a .pi-mem.json in your memory directory (default ~/.pi/agent/memory/.pi-mem.json):

{
  "searchDirs": ["catchup", "projects"],
  "contextFiles": ["SOUL.md", "AGENTS.md"],
  "autocommit": true
}

Environment variables

Environment variables override .pi-mem.json values when set.

Env Var	Default	Description
PI_MEMORY_DIR	~/.pi/agent/memory/	Root directory for all memory files
PI_DAILY_DIR	$PI_MEMORY_DIR/daily/	Directory for daily logs
PI_CONTEXT_FILES	(empty)	Comma-separated list of extra files to inject into context (e.g. SOUL.md,AGENTS.md,HEARTBEAT.md)
PI_SEARCH_DIRS	(empty)	Comma-separated list of subdirectories (relative to PI_MEMORY_DIR) to include in memory_search. Searched recursively one level deep. (e.g. catchup,projects)
PI_AUTOCOMMIT	false	When 1 or true, auto-commit to git after every write
PI_TIMEZONE	TZ, then UTC	IANA timezone used for daily log filenames and today/yesterday context windows. Invalid values fall back to UTC.
PI_MEMORY_FRESHNESS_DAYS	7	Days before a root-level memory file is flagged as possibly stale when read via memory_read(target='file') or recalled automatically
PI_CONSOLIDATION_ENABLED	false	When 1 or true, opt into background consolidation: a restricted sub-agent periodically distills past daily logs and completed scratchpad items into long-term memory files, then archives those logs and clears the done items. Triggered on session start once 24h have passed since the last run, or 5 sessions have started since then.

Consolidation

When PI_CONSOLIDATION_ENABLED is on, a background pass runs on session start, whenever 24 hours have passed since the last run or 5 sessions have started since then. It hands past daily logs and completed scratchpad items to a restricted sub-agent that writes anything durable into long-term memory files via memory_write, then archives those daily logs under daily/archive/ (never deleted) and clears the completed scratchpad items. Today's daily log is never touched. If a run fails, nothing is archived or cleared and it is retried later.

Use /consolidate-stop to abort a consolidation that is currently running.

Dashboard Widget

An auto-generated "Last 24h" summary is shown on session start and switch:

• Scans recent session files for titles, costs, and sub-agent counts
• Groups by topic using an LLM call (falls back to flat list)
• Rebuilt every 15 minutes in the background
• Also shows open scratchpad items

Installation

pi install git:github.com/Muyuan-Zhang/pi-memory

(The project is developed under the working name pi-claude-mem; its repository currently lives at Muyuan-Zhang/pi-memory.)

License

MIT