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

At a glance

How it runs
CLIAgent plugin / skill
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
pi coding agentNode.js (npm package @askjo/pi-mem)Git (optional, for PI_AUTOCOMMIT)Shell / CLINetwork accessLocal filesystem
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

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.

  1. A developer who runs the pi coding agent daily and wants project decisions and personal preferences recalled without restating them each session.
  2. Teams that fork or clone agent sessions and need to know which ancestor threads the current one descends from via /ancestry.
  3. Users who want to review, diff and version agent memory as plain text, optionally with PI_AUTOCOMMIT committing every write to git.
  4. People juggling several coding agents who want one shared Markdown memory directory, pointed at with PI_MEMORY_DIR, to reuse durable facts.
  5. 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-mem

The 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=1

Then 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:

/ancestry

What are this agent's strengths and limitations?

Pros
  • 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.
Limitations
  • 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?

FollowAgents source review · FARS-2.1
Major gaps
43/ 100 5-point scale 2.2 / 5
Trust 10/29
Reliability 6/14
Adaptability 9/18
Convention 8/18
Effectiveness 7/13
Verifiability 3/8
Why each dimension lost points
Trust10 / 29 · 1.7/5

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.

Reliability6 / 14 · 2.1/5

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.

Adaptability9 / 18 · 2.5/5

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.

Convention8 / 18 · 2.2/5

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.

Effectiveness7 / 13 · 2.7/5

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.

Verifiability3 / 8 · 1.9/5

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.

Risks and how to mitigate them
  • 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.
Evidence confidence: Low Reviewed Nov 11, 2026 Reviewed revision 4dd3d369854d
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/pi-mem.svg)](https://followagents.com/en/agents/pi-mem)
<a href="https://followagents.com/en/agents/pi-mem"><img src="https://followagents.com/badge/pi-mem.svg" alt="FARS review"></a>

FAQ

Is search actually semantic?
The docs describe memory_search as case-insensitive keyword matching over filenames and content in the root, notes/ and daily/; no embedding model or vector index is documented.
Does my memory leave the machine?
Only if PI_AUTOCOMMIT is set to 1 or true, in which case pi-mem commits after every write to git. Otherwise files stay in the local memory directory.
How much context does system mode consume?
The long-term block is about 3K tokens, cut at a line boundary with a memory_read pointer; the per-turn trailing message is capped near 3K tokens with whole items dropped; daily logs keep the latest entries under a 2,000-character cap.
Can I use it with Claude Code or other agents?
The README states it works with pi, Claude Code and any LLM agent, but the only documented install command is pi install; other hosts need their own tool and context-injection wiring.
What does enabling session_ancestry cost?
Nothing until you opt in with PI_ANCESTRY=1 or ancestry: true in .pi-mem.json; then it registers one read-only tool and the /ancestry command.
Is pi-mem open source?
Yes. The source code is on GitHub (jo-inc/pi-mem) under the MIT licence.
Is pi-mem safe to use?
FollowAgents' FARS review (Nov 11, 2026) scored pi-mem 10/29 on trust and safety. None of the eight safety controls the review checks for was missing outright.
Is pi-mem still maintained?
Yes. The latest commit on GitHub is from 2026-11-02, within the last 30 days.
Who makes pi-mem?
pi-mem is published on GitHub by the account jo-inc. FollowAgents has not verified which person or company is behind that account.
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts