# pi-persistent-intelligence

Native governed memory for the pi coding agent: durable project memory, session search, reviewable curation, diagnostics, and optional Obsidian vault integration.

> **Canonical memory is JSONL. Markdown is a rendered projection.**

```bash
pi install npm:pi-persistent-intelligence
/reload
```

## Why it exists

Coding agents forget project conventions, previous corrections, release decisions, and workflow preferences between sessions. `pi-persistent-intelligence` gives pi a local governed memory layer that can retain useful observations, recall scoped context, and reflect on memory health without silently rewriting durable memory.

It is a standalone pi-agent-native extension. It does not require `pi-governance-rs`, does not require Rust, and does not run an MCP server.

## Install

```bash
pi install npm:pi-persistent-intelligence
/reload
```

PI stores data locally under `~/.pi/agent/pi-memory/` by default. Project-local storage can be configured with `.pi/settings.json`.

## Quick start

```bash
/memory-inbox
/curate-memory
/memory-doctor
/memory-health-audit
/memory-store-quality
/memory-recall-effectiveness
/memory-quality
/memory-relationship-quality
/memory-diagnostics
```

Write a short-lived session decision:

```bash
memory_write target=daily content="#decision use canonical JSONL as the source of truth"
```

Propose durable long-term memory for review:

```bash
memory_write target=long_term \
  content="Always run bun test and bun run typecheck before pushing." \
  tags='["workflow","testing"]' \
  confidence=0.88
```

Search memory and prior sessions:

```bash
memory_search "bun test"
session_search "Lambda timeout debug"
```

PI inspection commands are interactive by default when the terminal TUI is available: inbox, memory browsing, evidence, diagnostics, doctor, Recall X-ray, timeline, background activity, and command history open pageable/searchable browsers with expandable details. Use `--plain` or `--json` when scripting.

See [Command reference](docs/commands.md) for the full command and tool list.

## How memory works

The public model is **Retain, Recall, Reflect**:

- **Retain** useful candidates with evidence.
- **Recall** scoped memory with policy, search, and diagnostics.
- **Reflect** through reviewable health, quality, recall, relationship, maintenance, abstraction, and procedure reports.

See [Retain, Recall, Reflect](docs/retain-recall-reflect.md) for the longer model.

Memory is stored as JSONL records and rendered to Markdown for inspection. The Markdown projection is not canonical.

| Layer | Store | Governance |
|---|---|---|
| **L1 Identity** | `memory/L1.identity.jsonl` | Never auto-applied; requires explicit ratification |
| **L2 Playbooks** | `memory/L2.playbooks.jsonl` | Patch-governed; confidence and evidence gated |
| **L3 Session** | `daily/YYYY-MM-DD.md` | Freely writable session context |
| **Evidence** | `memory/evidence.jsonl` | Content-addressed support, bounded excerpts, redactable |
| **Tombstones** | `memory/tombstones.jsonl` | Content-free deletion markers that prevent re-promotion |

## Core workflow

```text
observation or correction
  -> candidate + evidence
  -> verification
  -> inbox review
  -> patch-governed mutation
  -> scoped recall in future sessions
  -> diagnostics and maintenance recommendations
```

Durable memory changes are patch-governed. No record is silently mutated. Low-trust sources, generated content, repository text, contested records, and L1 identity proposals require review. Quality dashboards, relationship analysis, recall effectiveness, patch simulation, and governance reports are review-only unless you explicitly apply a patch.

Legacy provenance backfill and inquiry staleness are preview-first migrations: review their fingerprint before apply, which creates backups and audit reports. Explicit reinforcement records user confirmation without directly changing confidence or stability; implicit success requires observable successful execution rather than mere exposure.

## Context-sensitive preference capture

PI recognizes natural-language preferences such as "Avoid promotional language in my public writing" without requiring a special command. Capture remains **candidate-first**: direct preferences are checkpointed per turn, surfaced for review, and never written directly to active memory. Repeated equivalent preferences reinforce one candidate instead of creating silent duplicates.

Scope follows intent and observed work, not the shell location. The launch directory does not determine scope. User-wide writing and interaction preferences are proposed as global L2 records. Repository conventions target each materially modified project, while repositories used only for reading are not inferred as targets. Reading research in an Obsidian vault does not make a repository convention vault-scoped.

Global preferences use positive, context-sensitive applicability. A writing preference can appear for editing or documentation work and stay out of unrelated debugging. This filtering keeps the existing 14 KB default context budget and the bounded hard-rule section unchanged.

Use `/memory-capture-quality` for aggregate capture health, `/memory-capture-audit` for report-only historical findings, and `/memory-capture-backfill` for fingerprinted candidate-only recovery. Backfill preview is the default and does not activate memories or apply cleanup proposals.

## Relationship to [pi-governance-rs](https://github.com/Mont3ll/pi-governance-rs)

The ecosystem model is:

```text
pi-persistent-intelligence
  = standalone lightweight pi-agent-native memory extension

pi-governance-rs
  = standalone Rust CLI + MCP stdio governed memory runtime

Shared PI memory contract
  = schema/import/export/terminology compatibility layer
```

`pi-persistent-intelligence` is native governed memory for the pi coding agent.

[`pi-governance-rs`](https://github.com/Mont3ll/pi-governance-rs) is the standalone Rust CLI/MCP runtime for governed memory across Codex, Claude, OpenCode, Cursor, PI agent, and other MCP-capable tools.

Both can be used alone. Both can interoperate through the shared PI memory contract, compatible import/export, and optional bridge diagnostics.

Key boundaries:

- `pi-persistent-intelligence` does **not** require Rust.
- `pi-persistent-intelligence` does **not** host or run an MCP server.
- `pi-governance-rs` remains the MCP runtime.
- Normal pi-agent usage does **not** require `pi-governance-rs`.

## Import and export

Use pi-governance-compatible bundles when you want to move governed memory between compatible runtimes:

```bash
/memory-export --format pi-governance --redacted --output bundle.json
/memory-import --format pi-governance bundle.json
/memory-import --format pi-governance bundle.json --apply --backup --redacted-aware
```

By default, import shows what would change before it writes anything. Imports are merge-oriented and route proposed changes through governed flows.

See [Export/import with pi-governance-rs](docs/export-import-pi-governance.md).

## Optional pi-governance-rs bridge

The bridge is disabled by default:

```json
{
  "piGovernance": {
    "enabled": false,
    "mode": "external",
    "command": null,
    "store": null,
    "namespace": "default"
  }
}
```

Run this only when you intentionally want to check optional external Rust-runtime configuration:

```bash
/memory-governance doctor
```

Disabled standalone mode is valid.

## Safety guarantees

| Invariant | Guarantee |
|---|---|
| Canonical storage | JSONL is authoritative; Markdown is rendered |
| Patch governance | Durable L1/L2 changes go through patch review/application |
| L1 identity safety | L1 records are never auto-applied |
| Trust boundaries | Low-trust/generated/repository content cannot auto-apply |
| Tombstones | Deleted records cannot be silently re-promoted |
| Privacy purge | Removes recoverable content from normal memory files |
| Redacted export | Best-effort, user-reviewed redaction metadata included |
| Contested records | Warned separately; never injected as hard rules |
| Vault integration | Optional; promotion reports do not mutate vault files automatically |
| Quality and recall reports | Health, quality, relationship, store, recall, and patch-simulation reports are review-only |
| Session consolidation | Uses the configured/current Pi model when available; failures are surfaced in runtime events and daily logs |
| pi-governance-rs bridge | Optional diagnostics only; no MCP server in this package |

## Documentation

- [Command reference](docs/commands.md)
- [Retain, Recall, Reflect](docs/retain-recall-reflect.md)
- [Shared PI memory contract](docs/pi-memory-contract.md)
- [pi-governance-rs compatibility](docs/pi-governance-rs-compatibility.md)
- [Standalone vs shared mode](docs/standalone-vs-shared-mode.md)
- [Export/import with pi-governance-rs](docs/export-import-pi-governance.md)
- [Wiki docs](docs/wiki/)

## Development

```bash
bun test
bun run typecheck
bun run eval
bun run test:stress
npm pack --dry-run
```

`bun run eval` runs deterministic governance, recall, package/docs, replay, and hardening checks. Replay fixtures are internal validation inputs, not public performance benchmarks.

`bun run build` is intentionally unavailable because this package has no build script.