# Retain, Recall, Reflect

PI is a local-first governed operational memory layer for pi coding agents. Its public mental model is:

```text
Retain -> Recall -> Reflect
```

This is not chat history replay. PI stores scoped, evidence-backed operational memory with review boundaries, secret scanning, tombstones, and patch-governed durable mutation.

## Retain

**Retain** means capture observations that may be useful later, but do not silently turn them into durable truth.

Retain paths include:

- `memory_write target=daily` for ephemeral session notes and `#decision` markers
- `memory_write target=long_term` for governed inbox candidates
- automatic correction capture for explicit user corrections
- context-compaction and consolidation candidates before context is lost
- deterministic evidence records, including `codebase_analysis` evidence from tools such as `tsc`, ESLint, Vitest, Playwright, Fallow-like analysis, or custom scripts

Before long-term capture, PI can score whether an observation is worth preserving. The memory-worth decision is one of:

- `reject` -- too trivial, duplicate, unsafe, vague, or sensitive without explicit request
- `daily_only` -- useful for the current session but not durable memory
- `candidate` -- worth inbox review and possible L2 promotion
- `inquiry` -- potentially important, but underspecified or risky enough to require clarification

Retain does not bypass governance. Durable L1/L2 changes still require patch application.

## Recall

**Recall** means retrieve scoped memory for the current task while respecting policy filters.

Recall uses profile, resource, thread, project, status, tombstone, negative-scope, contested, and dependency-invalidated state. The default context injection remains `scoped`; lower-token `policy_only` and `wakeup` modes are also available.

Use:

```bash
memory_search "query"
/memory-recall-xray "query"
```

`/memory-recall-xray` is read-only. It explains included and excluded memories, including retrieval tier, score, evidence status, trust class, memory kind, scope mismatch, negative-scope match, tombstone state, contested status, stale status, and dependency invalidation. Reports are redacted before display.

## Reflect

**Reflect** means produce reviewable maintenance and abstraction artifacts.

Reflect operations include:

- `/memory-diagnostics`
- `/memory-graph --save`
- `/memory-timeline --save`
- `/maintain-memory --report`
- `/meta-consolidation`
- `/procedure-candidates --save`
- `/memory-background enqueue diagnostics` and `/memory-background run`

Reflect operations may produce reports, candidate patches, inquiries, or review-only procedure candidates. They must not silently mutate durable memory. Procedure candidates can suggest skill names, but PI does not write `SKILL.md` automatically.

## How this preserves governance

- L1 records are never auto-applied.
- Durable memory mutation remains patch-before-mutation.
- Strict governance mode still requires trust metadata, verification, and evidence IDs.
- Compatibility mode remains backward-compatible with older records.
- Codebase-analysis evidence is support, not automatic truth.
- Background jobs are local, inspectable, repeatable, and report-producing by default.
- Secret-like content is blocked or redacted where PI controls persistence and reporting.
- Tombstones and privacy purge remain respected.
- Contested memory is warning-only and never injected as hard truth.