pi-remember

A lightweight, simple persistent file-based memory for pi agents.

Install

pi install npm:pi-remember   # or, from this directory: pi install .

What it does

On session start the extension creates this memory directory if it doesn't exist, and on each agent turn appends a # Memory section to the system prompt explaining how to use it.

Memory is scoped to a project, not to a specific working directory. The project root is discovered by walking up from ctx.cwd:

1. The nearest enclosing git repository root (handles worktrees), so a repository root and its subdirectories (e.g. src/) share one memory.
2. Otherwise the nearest directory containing a project manifest (package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml, .gitignore) for projects that are not under git.
3. Otherwise ctx.cwd itself.

Note that within a monorepo all packages share the git repo root and therefore one memory.

The directory name is derived from the project root path. To stay unambiguous it combines a readable slug with a short hash of the path, since path segments can themselves contain hyphens:

/project/root                  ->  ~/.pi/memories/--project-root-<hash>--/
/home/sam/foo                  ->  ~/.pi/memories/--home-sam-foo-<hash>--/memory/

So /home/sam/foo maps to ~/.pi/memories/--home-sam-foo-<hash>--/memory/, and the colliding /projects/acme/api and /projects/acme-api map to different directories because their hashes differ.

Structure

Each project gets a memory/ folder for fact files and a MEMORY.md index that is loaded into the system prompt each session:

~/.pi/memories/--home-sam-foo-<hash>--/
└── memory/
    ├── MEMORY.md        ← index, one line per memory, injected into the prompt
    └── some-memory.md   ← a single fact with frontmatter

System prompt injection

On each before_agent_start, the extension appends a # Memory section containing:

• Guidance on memory files, types, and what to save / not save
• A ## Memory Index subsection with the contents of MEMORY.md as it was at session start, when it exists (capped at 200 lines / 25 KB by UTF-8 byte length). It's captured once and left unchanged for the session so the system prompt stays stable and the provider's cached prefix is not invalidated; updates made during the session are reloaded on the next session start.

The agent reads and writes memory files directly with the built-in read, write, and edit tools; no dedicated remember tool is needed.

Memory file format

---
name: short-kebab-case-slug
description: one-line summary, used to decide relevance during recall
metadata:
  type: user | feedback | project | reference
---

The fact. For `feedback` / `project`, follow with **Why:** and **How to
apply:** lines. Link related memories with [[their-name]].

Development

npm install
npm run typecheck
# smoke test
pi -e ./src/index.ts -p "hi"