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

Development

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.