Plain-Markdown persistent memory for AI coding agents. Long-term facts, daily logs, scratchpad, and semantic search — works with pi, Claude Code, and any LLM agent.
See the codeREADME
pi-mem
surprisingly useful daily memory for the pi coding agent
Inspired by OpenClaw's approach to agent memory.
Layout
Memory files live under ~/.pi/agent/memory/ (override with PI_MEMORY_DIR):
| Path | Purpose |
|---|---|
MEMORY.md | Curated long-term memory (decisions, preferences, durable facts) |
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) |
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 (MEMORY.md), 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. |
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.mdSCRATCHPAD.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. |
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
Related
- pi-reflect — Self-improving reflection engine for pi. Analyzes recent conversations and iterates on memory, behavioral rules, and identity files. Pairs naturally with pi-mem.
Installation
pi install git:github.com/jo-inc/pi-mem
License
MIT
Pi Ecosystem
| Package | Description |
|---|---|
| pi-reflect | Self-improving behavioral files |
| pi-boss | Multi-agent orchestration via tmux |
| pi-room | Multi-agent awareness and coordination |
| pi-vertex-anthropic | Claude via Google Cloud Vertex AI |
| pi-skill-posthog | PostHog analytics skill for pi agents |
Contributors
Similar repos
Languages
TypeScript
99.0%
Plain-Markdown persistent memory for AI coding agents. Long-term facts, daily logs, scratchpad, and semantic search — works with pi, Claude Code, and any LLM agent.
See the codeREADME
pi-mem
surprisingly useful daily memory for the pi coding agent
Inspired by OpenClaw's approach to agent memory.
Layout
Memory files live under ~/.pi/agent/memory/ (override with PI_MEMORY_DIR):
| Path | Purpose |
|---|---|
MEMORY.md | Curated long-term memory (decisions, preferences, durable facts) |
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) |
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 (MEMORY.md), 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. |
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.mdSCRATCHPAD.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. |
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
Related
- pi-reflect — Self-improving reflection engine for pi. Analyzes recent conversations and iterates on memory, behavioral rules, and identity files. Pairs naturally with pi-mem.
Installation
pi install git:github.com/jo-inc/pi-mem
License
MIT
Pi Ecosystem
| Package | Description |
|---|---|
| pi-reflect | Self-improving behavioral files |
| pi-boss | Multi-agent orchestration via tmux |
| pi-room | Multi-agent awareness and coordination |
| pi-vertex-anthropic | Claude via Google Cloud Vertex AI |
| pi-skill-posthog | PostHog analytics skill for pi agents |
Similar repos
Contributors
Languages
TypeScript
99.0%