---
slug: "zhafron-pi-memory"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/tickernelz/pi-memory@main/README.md"
repo: "https://github.com/tickernelz/pi-memory"
source_file: "README.md"
branch: "main"
---
# pi-memory

[![npm version](https://img.shields.io/npm/v/@zhafron/pi-memory)](https://www.npmjs.com/package/@zhafron/pi-memory)
[![npm downloads](https://img.shields.io/npm/dm/@zhafron/pi-memory)](https://www.npmjs.com/package/@zhafron/pi-memory)
[![license](https://img.shields.io/npm/l/@zhafron/pi-memory)](https://www.npmjs.com/package/@zhafron/pi-memory)

Memory management extension for [pi coding agent](https://pi.dev/).

## Features

- **Long-term Memory**: Store crucial facts, decisions, and preferences in MEMORY.md
- **Identity Management**: Define AI persona in IDENTITY.md
- **User Profile**: Store user context in USER.md
- **Daily Logging**: Track day-to-day activities in daily/YYYY-MM-DD.md
- **Auto Context Injection**: MEMORY.md, IDENTITY.md, USER.md automatically injected into system prompt
- **First Run Setup**: Interactive bootstrap process for new installations
- **Cross-platform**: Works on Windows, macOS, and Linux

## Installation

```bash
pi install git:github.com/tickernelz/pi-memory
```

Or via npm:

```bash
pi install npm:@zhafron/pi-memory
```

## Configuration

Add to `~/.pi/agent/settings.json`:

```json
{
  "pi-memory": {
    "memoryDir": "~/.pi/agent/memory",
    "dashboard": false
  }
}
```

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `memoryDir` | string | `~/.pi/agent/memory` | Memory directory location |
| `dashboard` | boolean | `false` | Enable dashboard widget |

## Memory Files

| File | Purpose |
|------|---------|
| `MEMORY.md` | Long-term memory (crucial facts, decisions, preferences) |
| `IDENTITY.md` | AI identity (name, persona, behavioral rules) |
| `USER.md` | User profile (name, preferences, context) |
| `daily/YYYY-MM-DD.md` | Daily logs (day-to-day activities) |
| `BOOTSTRAP.md` | First run setup instructions (deleted after setup) |

## Tools

### `memory`

Unified memory management tool.

**Actions:**

| Action | Description | Parameters |
|--------|-------------|------------|
| `read` | Read memory file | `target`: memory, identity, user, daily |
| `write` | Write to memory file | `target`: memory, identity, user, daily; `content`; `mode`: append/overwrite |
| `search` | Search memory files | `query`, `max_results` (optional) |
| `list` | List all files | - |

**Targets:**

| Target | File | Purpose |
|--------|------|---------|
| `memory` | MEMORY.md | Long-term memory (crucial facts, decisions, preferences) |
| `identity` | IDENTITY.md | AI identity (name, persona, behavioral rules) |
| `user` | USER.md | User profile (name, preferences, context) |
| `daily` | daily/YYYY-MM-DD.md | Daily logs (day-to-day activities) |

**Examples:**

```bash
# Read memory files
memory --action read --target memory
memory --action read --target identity
memory --action read --target user
memory --action read --target daily --date 2026-02-18

# Write to memory files
memory --action write --target memory --content "Remember to use PostgreSQL for all projects"
memory --action write --target identity --content "- **Name**: Jarvis" --mode overwrite
memory --action write --target user --content "- **Location**: New York (EST)"
memory --action write --target daily --content "Fixed critical bug in auth module"

# Search and list
memory --action search --query "PostgreSQL"
memory --action list
```

## First Run Flow

1. Extension detects no MEMORY.md exists
2. Creates BOOTSTRAP.md with setup instructions
3. AI reads BOOTSTRAP.md and asks user questions interactively
4. AI writes to MEMORY.md, IDENTITY.md, USER.md
5. AI deletes BOOTSTRAP.md manually
6. Setup complete

## Context Injection

The following files are automatically injected into the system prompt at session start:

- `MEMORY.md` — Long-term memory
- `IDENTITY.md` — AI identity
- `USER.md` — User profile

Daily logs are **not** auto-injected and must be accessed via the `memory` tool.

## License

MIT