# pi-agent-memory

Project-local memory extension for [pi](https://pi.dev). It gives agents durable, human-editable project memory that can survive across sessions and be retrieved in future work.

## Why

Agent memory should be first-class project context, not private state hidden in one user's profile directory. Project facts, hardware configuration, debugging workarounds, architectural decisions, and conversational context often determine whether a fresh agent can be useful. If that knowledge is saved outside the repository, it does not travel with the project, does not transfer between machines, and cannot be shared with other contributors.

Existing harness-level memory systems tend to trigger too rarely and store memories in user-profile space. In practice, meaningful context is often discovered during normal work: an agent finds a workaround, the user explains an environment constraint, or a short debugging session uncovers durable state. Losing that between sessions tangibly worsens future outcomes.

This extension treats memory as repo-owned conditioning material. Memories live in `.pi/memory/`, can be reviewed and versioned with the codebase, and can be loaded by future agents to quickly regain project context. The goal is not background personalization; it is durable, shared project knowledge.

## What it provides

- A Project Store at `.pi/memory/`
- A generated Retrieval Map at `.pi/memory/INDEX.md`
- Topic Files under `.pi/memory/topics/`
- `/memory` commands for status, extraction, forgetting, and reindexing
- A `/memory-recall` prompt template for explicit memory retrieval
- Guardrails that block direct mutation of `.pi/memory/` and `.pi/memory-history/` through normal file tools

V1 intentionally does **not** provide global memory, vector search, background harvesting, or public agent-callable memory write tools.

## Install

### Project-local install

Copy or link the extension into a pi project:

```bash
mkdir -p .pi/extensions
cp -R /path/to/pi-agent-memory/.pi/extensions/agent-memory .pi/extensions/agent-memory
```

Then run `/reload` in pi.

### User/global install

For use across projects, link the extension into your user pi extensions directory:

```bash
mkdir -p ~/.pi/agent/extensions
ln -s /path/to/pi-agent-memory/.pi/extensions/agent-memory ~/.pi/agent/extensions/agent-memory
```

On Windows, use a junction:

```powershell
New-Item -ItemType Junction `
  -Path "$env:USERPROFILE\.pi\agent\extensions\agent-memory" `
  -Target "H:\pi-agent-memory\.pi\extensions\agent-memory"
```

Then run `/reload` in any open pi session.

## Commands

```text
/memory status
/memory extract
/memory forget <memory-id> [expected-hash]
/memory reindex [project]
/memory-recall <query>
```

### Typical workflow

1. Work normally in pi.
2. When something durable should be remembered, run:

   ```text
   /memory extract
   ```

3. Review and approve proposed Memory Candidates.
4. Future agents will see a lightweight memory awareness note when project memories exist.
5. For explicit recall, run:

   ```text
   /memory-recall what do we know about testing conventions?
   ```

## Memory Store layout

```text
.pi/
  memory/
    INDEX.md
    topics/
      <topic>.md
  memory-history/
    changes.jsonl
```

Do not edit `.pi/memory/INDEX.md` directly. If Topic Files are edited manually, run:

```text
/memory reindex
```

## Dependencies

- [Attractor](https://github.com/BigscreenVR/attractor) is a project dependency for workflow-mediated memory approval artifacts under `workflows/`.

## Development

Run conformance tests:

```bash
npm test
```

Relevant docs:

- `CONTEXT.md` — domain language
- `NLSPEC.md` — behavior specification
- `docs/adr/` — architectural decisions