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.

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.