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.

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

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

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

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

Propose durable long-term memory for review:

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:

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

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

The ecosystem model is:

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

/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.

Optional pi-governance-rs bridge

The bridge is disabled by default:

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

/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
• Retain, Recall, Reflect
• Shared PI memory contract
• pi-governance-rs compatibility
• Standalone vs shared mode
• Export/import with pi-governance-rs
• Wiki docs

External evaluation

The repository includes a fingerprint-gated harness for AMA-Bench, LongMemEval-V2, and MemoryArena compatibility checks. It keeps production and diagnostic tracks separate and never runs external models during ordinary release checks. See External agent-memory benchmarks.

Development

PI uses Bun 1.3.13, pinned in package.json and the GitHub Actions workflows.

bun install --frozen-lockfile
bun run verify:pr
bun run release-audit

bun run verify:pr runs typecheck, unit tests, and deterministic evals. bun run release-audit adds stress tests and npm pack --dry-run package validation.

Replay fixtures are internal validation inputs, not public performance benchmarks.

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