---
slug: "pi-mythic-memory"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/rcwells1879/Pi-Mythic-Memory@main/README.md"
repo: "https://github.com/rcwells1879/Pi-Mythic-Memory"
source_file: "README.md"
branch: "main"
---
# Pi-Mythic-Memory

[![npm version](https://img.shields.io/npm/v/pi-mythic-memory.svg)](https://www.npmjs.com/package/pi-mythic-memory)
[![CI](https://img.shields.io/github/actions/workflow/status/rcwells1879/Pi-Mythic-Memory/ci.yml?branch=main&label=CI)](https://github.com/rcwells1879/Pi-Mythic-Memory/actions/workflows/ci.yml)

A local-first persistent-memory package for the [Pi coding agent](https://github.com/earendil-works/pi). The design started from Fable 5's memory structure as described in its Claude Code system prompt — then we cut the overzealous memory creation and kept the good stuff. It is basically an improvement on the original.

**Model-agnostic.** If your model can make tool calls and work a terminal, it can use this memory. There are no external dependencies — no embeddings, vector databases, or cloud services — so it works the same with local models and API models.

It is also deliberately less creepy than a general-purpose assistant memory: it stores durable context that actually helps with coding work and applies strict guardrails against sensitive or unnecessary personal details.

- [npm package](https://www.npmjs.com/package/pi-mythic-memory)
- [Pi Package Gallery](https://pi.dev/packages/pi-mythic-memory)

The package combines:

- A Pi extension with six versioned memory tools
- An on-demand `mythic-memory` skill containing filing, privacy, and usage policy
- A small always-on memory index injected into Pi's system prompt
- An optional, separately managed coding-safety addendum

Memory stays on the user's machine. There are no background model calls, embeddings, databases, automatic transcript ingestion, or cloud services.

## Features

- Model-agnostic: works with any tool-calling model, local or API — no external dependencies
- Simple file taxonomy: `/profile.md`, `/preferences.md`, `/topics/`, `/areas/`, and `/people/`
- Privacy-conscious by design: strong guardrails keep sensitive and coding-irrelevant personal details out of memory
- Progressive disclosure: metadata is always available; full records are read only when relevant
- SHA-256 content versions and optimistic concurrency checks
- Exact unique-match patching
- Atomic publication, cross-process locking, and external-change detection
- Path traversal, symlink, credential, and high-confidence injection checks
- Global name uniqueness across memory collections
- Pi-compatible tool-output limits

## Requirements

- Pi coding agent 0.81.1 or newer
- Node.js 22.19 or newer when running the development tests or optional addendum script

## Quick installation

Install the published package globally for your user account:

```bash
pi install npm:pi-mythic-memory
```

Then restart Pi or run:

```text
/reload
```

Confirm installation:

```bash
pi list
```

Inside Pi, run `/memory-status` or ask:

```text
Remember that I prefer concise answers.
```

The extension and skill load in every Pi workspace for that user account. They are not tied to the directory from which `pi install` was run.

### Install directly from GitHub

To install the current repository instead of the npm release:

```bash
pi install git:github.com/rcwells1879/Pi-Mythic-Memory
```

### Project-local installation

To share the npm package through a trusted project's `.pi/settings.json` instead of installing it globally:

```bash
pi install -l npm:pi-mythic-memory
```

The GitHub equivalent is:

```bash
pi install -l git:github.com/rcwells1879/Pi-Mythic-Memory
```

## Local checkout installation

```bash
git clone https://github.com/rcwells1879/Pi-Mythic-Memory.git
cd Pi-Mythic-Memory
npm install
npm run check
pi install .
```

A local-path installation references that checkout directly. Keep the directory in place while it remains installed.

## How it works

The extension registers these tools:

| Tool | Purpose |
|---|---|
| `memory_index` | List document metadata with prefix and cursor pagination |
| `memory_recall` | Read one complete document and its concurrency version |
| `memory_inscribe` | Create or fully replace a document |
| `memory_revise` | Replace one exact, unique match |
| `memory_extend` | Append a genuinely new fact |
| `memory_forget` | Delete a complete subject after an explicit request |

Before each agent run, the extension adds a compact block containing:

- `<memory_listing>` with paths and descriptions
- `<profile>` with stable identity context
- `<preferences>` with response preferences
- External-change notices when another process modifies memory

The complete policy is progressively loaded from `skills/mythic-memory/SKILL.md` only when a conversation involves durable facts, recall, correction, or forgetting.

## Memory location

The default global store is:

```text
~/.pi/agent/mythic-memory/
```

On Windows this is normally:

```text
C:\Users\<username>\.pi\agent\mythic-memory\
```

To deliberately use another location, set `PI_MYTHIC_MEMORY_DIR` before starting Pi. This is especially useful for isolated tests.

The package never places memory records in its Git repository. Do not commit personal memory files.

## Memory document format

```markdown
---
name: auth-redesign
description: Decisions and constraints for the user's ongoing authentication redesign
sources: [pi]
aliases: [auth project]
---

- [stated] user chose passkeys as the preferred sign-in direction
```

Each record is limited to 64 KiB. `/profile.md` is additionally limited to 300 body words.

## Optional coding-safety addendum

`extras/APPEND_SYSTEM.md` contains the broader coding-safety and authorization guidance developed alongside this package. It is **not required** for memory and is not installed automatically, because users may already have a customized `~/.pi/agent/APPEND_SYSTEM.md`.

From a cloned checkout, inspect the file first, then install it idempotently:

```bash
npm run addendum:status
npm run addendum:install
```

Reload or restart Pi afterward. To remove only a copy installed with the managed marker block:

```bash
npm run addendum:remove
```

The script will not overwrite an existing addendum. If the same text already exists without package markers, it reports that state and leaves the file unchanged.

The memory-specific always-on block is injected by the extension automatically; no manual system-prompt edit is needed for memory to work.

## Updating

Update this npm package:

```bash
pi update npm:pi-mythic-memory
```

Or update all installed Pi packages:

```bash
pi update --extensions
```

Then run `/reload` or restart Pi.

## Uninstalling

For the npm installation:

```bash
pi remove npm:pi-mythic-memory
```

For a GitHub installation:

```bash
pi remove git:github.com/rcwells1879/Pi-Mythic-Memory
```

Removing the package does not delete `~/.pi/agent/mythic-memory/` or an optional safety addendum. This prevents accidental loss of user data. Delete those separately only when you intentionally want to remove them.

## Development

```bash
npm install
npm run check
```

The test suite covers the storage lifecycle, optimistic concurrency, exact patching, lock recovery, cross-process writes, global name uniqueness, prompt integration, and output truncation.

Useful commands:

```bash
npm test
npm run typecheck
npm pack --dry-run
```

## Security model

Pi packages execute with the user's full system permissions. Review third-party extensions before installing them. This package restricts memory paths to its own store and treats stored content as untrusted reference data rather than higher-priority instruction.

The regex scanner is defense in depth, not a semantic privacy classifier. Privacy and filing decisions remain governed by the bundled skill. Current user statements and current repository evidence take precedence over stored memory.

## Design documentation

- [`docs/MYTHIC_MAPPING.md`](https://github.com/rcwells1879/Pi-Mythic-Memory/blob/HEAD/docs/MYTHIC_MAPPING.md) — design notes and deliberate Pi adaptations
- [`skills/mythic-memory/SKILL.md`](https://github.com/rcwells1879/Pi-Mythic-Memory/blob/HEAD/skills/mythic-memory/SKILL.md) — complete operating and privacy policy
- [`THIRD_PARTY_NOTICES.md`](https://github.com/rcwells1879/Pi-Mythic-Memory/blob/HEAD/THIRD_PARTY_NOTICES.md) — Hermes-derived components and license attribution

## License

MIT. See [`LICENSE`](https://github.com/rcwells1879/Pi-Mythic-Memory/tree/HEAD/LICENSE).