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.