pi-claude-memory-index

A Pi extension that gives Pi read-only access to the auto memory Claude Code keeps for the current project.

Before each run it adds one prompt section, claude_memory_index, holding the project's MEMORY.md index (one line per memory, each linking to a file). It does not inject the memory bodies. The model opens one with the read tool when an entry looks relevant. The section tells the model to treat entries as leads that may be out of date, to let the user and the repository take precedence, and to leave the memory directory untouched.

What it reads

<projects root>/<project slug>/memory/MEMORY.md

• Projects roots, searched in order: $CLAUDE_CONFIG_DIR/projects (when set), then ~/.claude/projects. Profiles that symlink projects to a shared directory all resolve to the same real path.
• Project slug: Claude Code's rule, where every character other than [A-Za-z0-9] becomes -, so /Users/me/src/app becomes -Users-me-src-app. Paths whose slug is over 200 characters match Claude's <first 200 chars>-<hash> directory by prefix.
• Project directory: the repository's main checkout. Linked git worktrees (git worktree add, .claude/worktrees/*, orchestrator worktrees under /tmp, and so on) are resolved through .git → gitdir → commondir, the same way Claude Code does, so every worktree of a repo sees the main checkout's memory. The extension reads these files directly and never runs git. If the main checkout has no memory directory, it tries the worktree path and then the current directory.

When nothing is found, the file is empty, or the file is not valid UTF-8, the extension adds nothing and removes the section if an earlier run added it.

Install

As a Pi package from npm (adds an entry to ~/.pi/agent/settings.json):

pi install npm:pi-claude-memory-index

Or from git:

pi install git:github.com/yanyaoer/pi-claude-memory-index

Or as a plain user extension. The checkout itself is the extension, because Pi loads the index.ts at its root:

git clone https://github.com/yanyaoer/pi-claude-memory-index ~/.pi/agent/extensions/claude-memory-index

To try it without installing anything:

pi -e /path/to/pi-claude-memory-index

Orchestrators that start plain pi (orch-cli, for example) pick up any of the installs above. They do not see an extension that is only passed with -e.

To remove it, run pi remove npm:pi-claude-memory-index (or the git: source you installed), or delete the cloned directory. To switch it off for one process, set PI_CLAUDE_MEMORY=0.

Configuration

The defaults are the limits Claude Code applies when it loads MEMORY.md. The extension reads only that many bytes and cuts at a line boundary. When the index is cut short, the section says so.

If you moved Claude's memory with the autoMemoryDirectory setting, point PI_CLAUDE_MEMORY_DIR at the new directory. The extension does not read Claude's settings files.

Behaviour and costs

• Read-only. The extension never writes to Claude Code's directories, never changes Claude Code's configuration, and never writes memories itself.
• No double loading in Claude Code. Everything lives in Pi's extension directory. Claude Code keeps loading MEMORY.md natively, exactly once, as before. The extension adds no CLAUDE.md import and no symlink, and it gives Claude Code nothing more to load. If Pi already loads the same file as a context file (for example through a symlinked AGENTS.md), the extension skips its own section.
• Stable prompt. The section text stays the same until MEMORY.md changes, so Pi sends no prompt delta and the provider's prompt cache stays valid. Each run checks the file's size, mtime and inode and re-reads the file only after one of them changes.
• Size. The whole index goes into the system prompt of every run, up to the limits above, which is roughly 3k tokens for a 10 KB index.

Privacy

The index is sent to whichever model provider Pi is using, on every run in that project. That includes the memory titles and one-line descriptions, plus any memory file the model chooses to read. Don't use the extension with providers you would not show your Claude memory to. Use PI_CLAUDE_MEMORY=0 for those runs, or keep sensitive facts out of MEMORY.md lines. The extension logs nothing and does not print memory contents.

Compared with pi-claude-memory

pi-claude-memory by elecnix (npm pi-claude-memory, compared at 0.1.2) uses the same Claude Code memory directory, but lets Pi read and write it. This package is the read-only counterpart.

The two "later prompts" and "worktree" rows were observed with Pi 1.4.0. One Pi RPC process received two prompts in a row, and a probe extension checked each provider request. With elecnix's package, the first request contained the index and the second did not. With this package, both did. From a linked worktree, elecnix's package injected nothing.

Choose pi-claude-memory if you want Pi to save memories that Claude Code then loads. Choose this package if Claude Code should remain the only writer and Pi should only read the index Claude Code maintains. Don't install both: Pi would then get two copies of the index.

Development

npm test            # node --test; needs Node >= 22.18 (built-in TypeScript stripping)
npm run typecheck   # tsc against the locally installed Pi (links it into node_modules)

The tests build real git repos with worktrees under .claude/worktrees/, .orch-worktrees/ and a path outside the repo. They also cover missing memory, invalid UTF-8, multi-megabyte and single-line indexes, cache invalidation, switching the extension off, and loading it twice.

License

MIT