pi-mem
Plain-Markdown persistent memory for AI coding agents: durable facts, daily logs, scratchpad and searchable notes.
- Source repo
- jo-inc/pi-mem
- Stars
- ★ 81
- Last updated
- 18d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 43/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesClaude Code (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer who runs the pi coding agent daily and wants project decisions and personal preferences recalled without restating them each session.
- Not a fit if
- Users whose agents have no plugin or tool-calling extension points
- Teams that forbid agents from writing local memory files automatically
- Users who want zero-config memory with no context-mode tuning
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-02
- Source review
- 43/100 · Major gaps
What does this agent do, and when should you use it?
pi-mem is a persistent memory plugin for coding agents that stores everything as plain Markdown under ~/.pi/agent/memory/ (overridable with PI_MEMORY_DIR). It defines four artifact types: MEMORY.md for curated long-term facts, SCRATCHPAD.md as a checklist, daily/YYYY-MM-DD.md as append-only daily logs, and notes/*.md for agent-created files. Agents interact through the memory_write, memory_read, memory_search and scratchpad tools, plus an opt-in session_ancestry tool that walks the parentSession chain across session files. Context injection runs in system, bootstrap, full or off mode; the default system mode keeps a roughly 3K-token memory block in a cacheable system-prompt section and adds one trailing retrieval message per turn. Configuration comes from environment variables or a .pi-mem.json file in the memory directory, and installation is a single pi install command. It ships under the MIT license as the npm package @askjo/pi-mem.
At runtime pi-mem registers memory tools for the agent: memory_write writes to long_term (MEMORY.md), daily (today's log) or note (notes/filename) in append or overwrite mode; memory_read reads long-term memory, the scratchpad, daily logs, notes, any root file, or lists everything; memory_search performs case-insensitive keyword matching over filenames and content across the root, notes/ and daily/; scratchpad manages checklist items with add, done, undo, clear_done and list. Context injection follows PI_MEMORY_CONTEXT_MODE: system mode caches MEMORY.md condensed to about 3K tokens, hard-cut at a line boundary with a pointer to memory_read, then appends a trailing message per turn containing a retrieval block from other memory files, similar past conversations and stored facts (capped near 3K tokens, whole items dropped never fragments) plus today's and yesterday's logs (2,000-char cap). Bootstrap mode injects a recall block including MEMORY.md as a user message every turn; full mode injects context files, MEMORY.md, recent logs and catchup indexes; off injects nothing. With PI_ANCESTRY enabled, a read-only session_ancestry tool and /ancestry command walk the cross-file parentSession chain up to the root, guarding against cycles, missing files and runaway chains. On session start and switch it also renders an auto-generated "Last 24h" widget that scans recent session files for titles, costs and sub-agent counts, groups them by topic via an LLM call with a flat-list fallback, and rebuilds every 15 minutes in the background.
- A developer who runs the pi coding agent daily and wants project decisions and personal preferences recalled without restating them each session.
- Teams that fork or clone agent sessions and need to know which ancestor threads the current one descends from via /ancestry.
- Users who want to review, diff and version agent memory as plain text, optionally with PI_AUTOCOMMIT committing every write to git.
- People juggling several coding agents who want one shared Markdown memory directory, pointed at with PI_MEMORY_DIR, to reuse durable facts.
- Users who maintain identity or behavioral files such as SOUL.md and AGENTS.md and want them injected through PI_CONTEXT_FILES with full context mode.
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Environment variables
PI_MEMORY_DIR- Config files
~/.pi/agent/memory/.pi-mem.json
How do you install or deploy this agent?
You need the pi coding agent installed with a working CLI. Install the plugin through pi's install command:
pi install git:github.com/jo-inc/pi-memThe package is also published to npm as @askjo/pi-mem. Git is only needed if you want PI_AUTOCOMMIT to commit memory changes. Optionally drop a config file into the memory directory:
{
"searchDirs": ["catchup", "projects"],
"contextFiles": ["SOUL.md", "AGENTS.md"],
"contextMode": "system",
"autocommit": true,
"ancestry": false
}How do you use this agent?
Memory files default to ~/.pi/agent/memory/. Environment variables override .pi-mem.json values:
export PI_MEMORY_DIR=~/.pi/agent/memory/
export PI_MEMORY_CONTEXT_MODE=system
export PI_TIMEZONE=Asia/Shanghai
export PI_AUTOCOMMIT=1
export PI_ANCESTRY=1Then let the agent call the tools during a session — record a decision to long-term memory, queue a scratchpad item, or search past notes:
memory_write(target='long_term', mode='append', content='Project uses pnpm exclusively')
memory_write(target='note', filename='lessons.md', content='...')
memory_search(query='deploy pipeline')
scratchpad(action='add', item='Add README example')With ancestry enabled, the slash command prints this thread's ancestor chain:
/ancestryWhat are this agent's strengths and limitations?
- Memory lives as plain Markdown you can read, grep, diff and roll back in git, with no database or vector store to run.
- The default system context mode keeps the long-term memory block in a cacheable system prompt and varies only a small trailing message per turn.
- Retrieval and daily-log injections have explicit token caps, drop whole items instead of truncating, and leave memory_search / memory_read pointers when content is cut.
- session_ancestry is off by default and, once enabled, is read-only and guards against cycles, missing files and runaway chains.
- Configuration is available through both environment variables and .pi-mem.json, with env vars taking precedence for per-machine or per-project overrides.
- The documented install path is the pi install command, tying first-class use to the pi coding agent ecosystem; Claude Code support is claimed but has no equivalent setup steps in the repo.
- All memory defaults to a single directory under the user's home folder, so keeping projects separate requires switching PI_MEMORY_DIR yourself.
- memory_search is case-insensitive keyword matching, not embedding-based semantic retrieval despite the "semantic search" phrasing in the description.
- The "Last 24h" widget depends on an LLM call for topic grouping, falls back to a flat list on failure, and rebuilds in the background every 15 minutes, adding extra calls.
- Turning on PI_AUTOCOMMIT commits on every write with no review step, which can quickly generate a noisy git history.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| pi-mem This agent | 43 · Major gaps | CLIFree + model costs | ★ 81 | 18d ago | TypeScript | — |
| Magic Context | 54 · Major gaps | CLIFree + model costs | ★ 2.5k | today | TypeScript | — |
| Ori Mnemos | 56 · Major gaps | CLIFree | ★ 337 | 1mo ago | TypeScript | Claude Code · OpenAI API · Claude API |
| MCP Memory Service | 68 · Some gaps | MCP serverFree | ★ 2.1k | 1d ago | Python | ChatGPT · Codex · Claude Code · Claude.ai |
How does FollowAgents rate this agent?
Why each dimension lost points
index.ts reads PI_SPRITE_URL/SPRITE_TOKEN/USER_ID and posts conversation searches and SQL queries to a Sprite service (/conversation/search, /db/query), yet the README never discloses this outbound data flow, weakening transparency; autocommit and ancestry default off is good least-privilege design, but git add -A with --no-verify commits and sending user facts to an external service are notable side effects; rollback relies only on optional git commits with no explicit undo; dependencies are loose peerDependencies with no lockfile evidence; attribution rests on MIT and an author field while publisher identity is unverified.
Config parsing, context condensation, and ancestry walking have unit tests (cycles, missing files, depth caps), showing good self-consistency; however @earendil-works/pi-* and @sinclair/typebox are peer deps with wide ranges, so availability cannot be statically confirmed; error handling is mostly silent catch returning null/empty (spritePost, gitCommit), so failures are invisible to users.
README clearly targets pi, Claude Code, and any LLM agent, with clear scenarios (long-term memory, logs, scratchpad, search) and stated boundaries (no embeddings, plain Markdown); trigger precision depends on the model choosing tools plus a recall directive, with no explicit trigger rules; environment fit is tied to the pi extension API and specific session directory naming (--Users- prefix filter), limiting portability.
README is well structured with layout, tools, config tables and an install command; installation is a single pi install line lacking npm install, prerequisites, and fuller config examples; naming is stable (v1.2.0, fixed package name); examples and FAQ are sparse; known limitations are only mentioned in passing (3K truncation) with no dedicated section; LICENSE is full MIT; publish.yml validates tag vs version but there is no CHANGELOG; maintenance responsibility points only to jo-inc, an unverified publisher.
Outputs are Markdown memory and retrieval blocks directly injectable into context, with token budgets and truncation pointers, giving good usability; there is marginal value for agents needing cross-session memory; but per-turn injection and background LLM summarization every 15 minutes add token and call costs, and cost-benefit evidence is thin.
README claims (3K truncation, 2K daily cap, read-only ancestry) have matching test assertions, so traceability is fair; but the Sprite data flow and dashboard LLM summarization are absent from the README, limiting cross-source corroboration; documentation and code mix facts with inference about data egress without clear separation.
- index.ts posts conversation searches and SQL queries to PI_SPRITE_URL; the README does not disclose this egress, so audit and confirm acceptability before deployment.
- autocommit uses git add -A with --no-verify, which may commit unintended files and skip hooks; enable only in a dedicated memory repo.
- Dependencies are loose peerDependencies without pinned versions; verify compatibility of @earendil-works/pi-* and typebox before installing.
- Error handling is largely silent; Sprite or git failures give no user feedback, making troubleshooting hard.
- Publisher identity is unverified; independently confirm provenance before installing.
FAQ
Is search actually semantic?
Does my memory leave the machine?
How much context does system mode consume?
Can I use it with Claude Code or other agents?
What does enabling session_ancestry cost?
Is pi-mem open source?
Is pi-mem safe to use?
Is pi-mem still maintained?
Who makes pi-mem?
Thanks — we use this to improve the page.