pi-mythic-memory

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# 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).

Pi-Mythic-Memory

A local-first persistent-memory package for the Pi coding agent. 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.

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:

pi install npm:pi-mythic-memory

Then restart Pi or run:

/reload

Confirm installation:

pi list

Inside Pi, run /memory-status or ask:

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:

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:

pi install -l npm:pi-mythic-memory

The GitHub equivalent is:

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

Local checkout installation

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:

~/.pi/agent/mythic-memory/

On Windows this is normally:

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

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

npm run addendum:status
npm run addendum:install

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

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:

pi update npm:pi-mythic-memory

Or update all installed Pi packages:

pi update --extensions

Then run /reload or restart Pi.

Uninstalling

For the npm installation:

pi remove npm:pi-mythic-memory

For a GitHub installation:

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

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:

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 — design notes and deliberate Pi adaptations
skills/mythic-memory/SKILL.md — complete operating and privacy policy
THIRD_PARTY_NOTICES.md — Hermes-derived components and license attribution

License

MIT. See LICENSE.