# Command Reference

This page lists the public commands and tools provided by `pi-persistent-intelligence`.

For first-time setup and the short workflow, start with the [README](../README.md).

## Interactive output

Inspection commands open an interactive terminal browser by default when pi's TUI is available. Standard keys are:

| Key | Action |
|---|---|
| `↑` / `↓` | Move selection |
| `PgUp` / `PgDn` or `p` / `n` | Previous / next page |
| `Home` / `End` | Jump to first / last result |
| `/` | Start live filtering within current results |
| `Enter` / `Space` | Expand or collapse details |
| `Tab` | Cycle sortable columns where available |
| `S` | Reverse sort direction |
| `q` / `Esc` | Close browser |

Use `--plain` for text output or `--json` for machine-readable output on commands that support interactive browsing.

## Core commands

| Command | Description |
|---|---|
| `/memory-inbox [--plain\|--json]` | Browse pending inbox candidates with pagination, search, expandable provenance, and governed approve/review actions. |
| `/curate-memory [--mode=propose\|auto]` | Review pending candidates and apply selected patch operations. |
| `/memory-doctor [--profile] [--plain\|--json]` | Open a collapsible dashboard for runtime, memory, governance, privacy, and diagnostics health; `--profile` adds stage timings. |
| `/memory-health-audit [--save] [--plain\|--json]` | Run a report-only health audit with category scores, trends, and review recommendations; never mutates memory. |
| `/memory-diagnostics [--profile] [--save] [--plain\|--json]` | Run integrity, secret, provenance, and re-verification checks in a dashboard; `--profile` adds stage timings and `--save` writes a diagnostics report. |
| `/memory-recall-xray <query> [--profile] [--plain\|--json]` | Browse included/excluded memories, scores, evidence, and selection reasons; `--profile` adds stage timings. Read-only and redacted. |
| `/memory-export --format pi-governance [--redacted] [--output bundle.json]` | Export a pi-governance-compatible PI memory contract bundle. |
| `/memory-import --format pi-governance <bundle.json> [--apply] [--backup] [--redacted-aware]` | Preview or apply a pi-governance-compatible bundle import. By default this is a dry-run import. |
| `/memory-governance doctor` | Check optional pi-governance-rs bridge configuration; disabled standalone mode is valid. |

## Memory lifecycle commands

| Command | Description |
|---|---|
| `/memory-store-quality [--plain\|--json]` | Browse report-only aggregate store quality across memory, relationships, recall effectiveness, governance, inbox, and runtime; never mutates memory. |
| `/memory-recall-effectiveness [--plain\|--json]` | Browse report-only analytics for recalled, excluded, never-recalled, and correction-adjacent memories; never mutates memory. |
| `/memory-quality [--plain\|--json]` | Browse report-only per-memory quality and lifecycle analysis with review recommendations; never mutates memory. |
| `/memory-relationship-quality [--plain\|--json]` | Browse report-only relationship-quality analysis across memory graph edges, orphan/dead-end memories, hubs, and weak links; never mutates memory. |
| `/memory-worth <observation>` | Score whether an observation should be rejected, kept daily-only, captured as a candidate, or turned into an inquiry. |
| `/memory-simulate-patch <patch-id> [--plain\|--json]` | Preview patch effects on memory, relationship, and store-quality scores without applying mutation. |
| `/memory-patches` | List pending patch files. |
| `/apply-memory-patch <id>` | Apply default-selected operations from a patch file. |
| `/maintain-memory [--mode=propose\|auto] [--report]` | Generate confidence-decay patches and reinforcement-based stability recommendations. |
| `/render-memory` | Regenerate Markdown projection from canonical JSONL. |
| `/consolidate-memory` | Manually trigger session-end LLM extraction using the current Pi model by default; set `PI_MEMORY_CONSOLIDATION_MODEL` to prefer a specific model. |
| `/meta-consolidation [--handoff]` | Propose L1 patterns from stable L2 clusters; review-only and never auto-applied. |
| `/memory-handoff [--goal <goal>]` | Generate a handoff snapshot of current active memory state. |

## Evidence, diagnostics, and review commands

| Command | Description |
|---|---|
| `/memory-background enqueue <kind>` | Queue an inspectable local background analysis job. Supported kinds include `diagnostics`, `provenance_liveness`, `reverification`, `memory_graph`, `memory_timeline`, `procedure_candidates`, `memory_worth_review`, `memory_health_audit`, `memory_relationship_quality`, `memory_recall_effectiveness`, `memory_store_quality`, `meta_consolidation`, and `vault_promotion_candidates`. |
| `/memory-background run` | Run queued background jobs and write report artifacts. |
| `/memory-background list [--plain\|--json]` | Browse queued, running, succeeded, and failed background analysis jobs. |
| `/memory-evidence [list] [--plain\|--json]` | Browse evidence and provenance records. |
| `/memory-evidence add-codebase-analysis ...` | Add deterministic codebase-analysis evidence from tools such as `tsc`, ESLint, Playwright, Vitest, Fallow-like analysis, or custom scripts. |
| `/memory-evidence link <evidence-id> --statement "..."` | Turn existing evidence into a reviewable inbox candidate without bypassing governance. |
| `/memory-skill draft <procedure-candidate-id>` | Generate a review-only skill draft artifact from a procedure candidate; never writes `SKILL.md` automatically. |
| `/memory-failures analyze [--save]` | Mine failed jobs or rejected candidates into review-only learning artifacts. |
| `/memory-graph [--save]` | Export a read-only dependency graph of memory, evidence, inquiries, tombstones, candidates, and reinforcement. |
| `/memory-timeline [--memory <id>] [--save] [--plain\|--json]` | Browse timeline events and effective validity for one memory or the whole store. |
| `/procedure-candidates [--save]` | Generate review-only procedure candidates from repeated workflow memory. |
| `/memory-learnings [--plain\|--json]` | Interactive pageable/searchable browser for long-term memory records. |
| `/memory-history [--plain\|--json]` | Browse session-local PI command outputs without rerunning commands. |

## Session search commands

| Command | Description |
|---|---|
| `/session-sync` | Sync session index and export summaries for semantic search. |
| `/session-reindex` | Force full re-parse of all session files. |
| `/setup-session-search` | Show session index size and qmd semantic-search setup hint. |

## Tools

| Tool | Description |
|---|---|
| `memory_write` | `target=daily` appends to the daily log; `target=long_term` creates an inbox candidate. |
| `memory_read` | Read rendered long-term memory, daily log, scratchpad, or inbox. |
| `memory_search` | Search PI memory. `mode=keyword` uses built-in FTS, `mode=semantic` uses qmd, and `mode=deep` uses qmd hybrid search. |
| `scratchpad` | Manage active task checklist: add, done, undo, clear done, or list. |
| `session_search` | Search past pi sessions by content, project, or date. |
| `session_list` | List sessions filtered by project or date range. |
| `session_read` | Read a full conversation from a past session by ID or path. |
| `session_decisions` | List `#decision` markers from recent sessions. |

## Examples

```bash
/memory-inbox
/curate-memory
/memory-diagnostics --save
/memory-health-audit --save
/memory-store-quality
/memory-recall-effectiveness
/memory-quality
/memory-relationship-quality
/memory-recall-xray "release workflow" --profile
/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
/memory-simulate-patch patch_123 --plain
/memory-governance doctor
```

```bash
memory_write target=daily content="#decision use canonical JSONL as source of truth"
memory_write target=long_term content="Always run bun test before pushing." confidence=0.88
memory_search "bun test" --mode=keyword
session_search "auth edge case" --project=api
session_decisions --days=30
```