edheltzel · edheltzel · Jul 22, 2026 · Jul 22, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -25,12 +25,12 @@ Top-level directories, by purpose (one line each — not a file enumeration):
 - `hooks/` — self-contained lifecycle hooks + cron jobs (never import from `src/`)
 - `tests/` — `bun:test` suite mirroring source areas, plus install-lifecycle tests
 - `benchmarks/` — wake-up context-efficiency benchmark harness
-- `agent-skills/` — Agent Skills (SKILL.md, one per skill dir) installed to `~/.claude/skills`, `~/.pi/agent/skills`, `~/.omp/agent/skills` — the single `recall-*` command surface (the former `/Recall:*` slash commands, #228)
+- `agent-skills/` — canonical Agent Skills (SKILL.md, one per skill dir) installed to `~/.claude/skills` and `~/.omp/agent/skills`, discovered by Pi through the root package manifest, and generated into native host plugin payloads — the single `recall-*` command surface (the former `/Recall:*` slash commands, #228)
 - `plugins/` — native host plugin bundles, one per host: Codex in `plugins/recall/`, Claude Code in `plugins/recall-claude/`, each packaging MCP plus its own skill payload
 - `docs/` — user-facing published docs + ADRs (`docs/adr/`) + agent skill docs (`docs/agents/`)
 - `lib/` — shared bash for the install / update / uninstall lifecycle scripts
 - `opencode/` — OpenCode host integration (plugins / hooks / guide)
-- `pi/` — Pi host integration (extensions / hooks)
+- `pi/` — Pi package extensions for native lifecycle capture and memory injection
 - `scripts/` — dev / CI helper scripts (version check, e2e)
 - `templates/` — install templates (`CLAUDE.md.template`, `mcp.json.template`)
 - `assets/` — README banner + VHS demo tapes / gifs
@@ -115,7 +115,7 @@ Before adding code or content, search for an existing definition and extend it.
 - **Runtime**: Bun (not Node). Uses `bun:sqlite` directly. Shebangs are `#!/usr/bin/env bun`.
 - **Build**: tsup produces ESM. Build script replaces node shebang with bun shebang.
 - **Database**: SQLite at `~/.agents/Recall/recall.db` (override via `RECALL_DB_PATH`; legacy `MEM_DB_PATH` still accepted). WAL mode. FTS5 full-text search with sync triggers.
-- **Install layout**: Canonical files live under `~/.agents/Recall/` (`shared/hooks/`, `shared/skills/`, `opencode/plugins/`, `pi/extensions/`, `MEMORY/`, `backups/`). Platform homes (`~/.claude/hooks/`, `~/.config/pencode/plugins/`, `~/.pi/agent/extensions/`) receive **per-file symlinks** back to canonicals. The collision rule in `lib/install-lib.sh:recall_link` backs up any existing user file before replacing it with a symlink.
+- **Install layout**: Canonical files live under `~/.agents/Recall/` (`shared/hooks/`, `shared/skills/`, `opencode/plugins/`, `MEMORY/`, `backups/`). Claude lifecycle hooks and OpenCode integration receive **per-file symlinks** back to canonicals; when the optional Claude plugin is active, it owns skills + MCP and the installer reconciles the legacy duplicates. Pi loads `pi/*.ts` and the canonical Agent Skills from the root package's native `package.json#pi` manifest; its MCP adapter and `mcp.json` registration remain separate because Pi packages have no MCP resource. The collision rule in `lib/install-lib.sh:recall_link` backs up any existing user file before replacing it with a symlink.
 - **MCP registration**: User scope in `~/.claude/settings.json` (or `~/.claude.json` if managed by `claude mcp add`) under `mcpServers`. The `env.RECALL_DB_PATH` block is populated by the installer.
 - **Hook registration**: `Stop`, `SessionStart`, `PreCompact` events in `~/.claude/settings.json` under `hooks.*`.
 - **Hooks are self-contained**: `RecallExtract.ts`, `RecallStart.ts`, etc. are standalone scripts symlinked into `~/.claude/hooks/` from `~/.agents/Recall/shared/hooks/`. They don't import from `src/`. The shared resolver `hooks/lib/db-path.ts` centralizes DB-path resolution so the CLI and every hook agree.
@@ -131,7 +131,7 @@ Before adding code or content, search for an existing definition and extend it.
 - **Modify extraction**: Edit `hooks/RecallExtract.ts` (self-contained, no build step)
 - **Add a hook helper**: Create `hooks/lib/foo.ts` — kept standalone so hooks don't import from `src/`
 - **Edit lifecycle scripts**: `install.sh`, `update.sh`, and `uninstall.sh` share `lib/install-lib.sh` — put shared bash functions there, not duplicated across scripts. Validate each with `bash -n`.
-- **Add an Agent Skill**: Create `agent-skills/<name>/SKILL.md` — the install/update/uninstall scripts pick it up automatically (canonical copy under `$RECALL_SHARED_SKILLS_DIR`, per-file symlinks into `~/.claude/skills`, `~/.pi/agent/skills`, `~/.omp/agent/skills`). Also add `<name>` to `RECALL_SKILL_NAMES` in `uninstall.sh` so uninstall removes it, and regenerate the native plugin bundles with `bun run build:codex-plugin` and `bun run build:claude-plugin` (their tests fail on drift).
+- **Add an Agent Skill**: Create `agent-skills/<name>/SKILL.md` — the install/update/uninstall scripts pick it up automatically (canonical copy under `$RECALL_SHARED_SKILLS_DIR`, per-file symlinks into `~/.claude/skills` and `~/.omp/agent/skills`; Pi discovers it through the root native package manifest). Also add `<name>` to `RECALL_SKILL_NAMES` in `uninstall.sh` so legacy/uninstall cleanup removes it, and regenerate the native plugin bundles with `bun run build:codex-plugin` and `bun run build:claude-plugin` (their tests fail on drift).
 - **Update the Claude guide**: Edit `FOR_CLAUDE.md` (installer copies it to `~/.claude/Recall_GUIDE.md`). Keep `FOR_OPENCODE.md` and `FOR_PI.md` in sync if lifecycle commands change.
 - **Cut a release**: See `docs/releasing.md` for the tag → GitHub release flow.
 

diff --git a/FOR_PI.md b/FOR_PI.md
@@ -19,66 +19,78 @@ user has never written one, recommend `recall onboard` via Bash to create it.
 
 ## Your MCP Tools
 
-These tools are available via the `recall-memory` MCP server. In Pi, tool names are prefixed with the server name using `recall-memory_`:
+These tools are available via the `recall-memory` MCP server. Recall enables the adapter's direct-tool mode by default, which normalizes the server prefix to `recall_memory_`; an existing explicit `directTools` preference is preserved:
 
-### recall-memory_memory_search
+On the first Pi session after adding the server, `pi-mcp-adapter` populates its metadata cache in the background and keeps the operations available through its `mcp` proxy tool.
+After one Pi reload or restart, the nine direct names below are registered from that cache.
+If a direct name is not present yet, call the same base operation through `mcp`, for example `mcp({ server: "recall-memory", tool: "memory_search", args: '{"query":"deployment"}' })`.
+
+### recall_memory_memory_search
 
 Search all memory with FTS5 full-text search. **Use this BEFORE asking the user to repeat anything.** Use `table` for a hard filter; use `bias_type` to prefer one type while preserving other matches.
 
 ```
-recall-memory_memory_search({ query: "kubernetes auth", project: "my-app" })
-recall-memory_memory_search({ query: "database choice", table: "decisions" })      // decisions only
-recall-memory_memory_search({ query: "database choice", bias_type: "decisions" })  // decisions first, broader context kept
+recall_memory_memory_search({ query: "kubernetes auth", project: "my-app" })
+recall_memory_memory_search({ query: "database choice", table: "decisions" })      // decisions only
+recall_memory_memory_search({ query: "database choice", bias_type: "decisions" })  // decisions first, broader context kept
 ```
 
 Bias quick picks: `decisions` for “what did we decide,” `learnings` for “what did we learn,” `breadcrumbs` for “where did we leave off,” `loa` for curated summaries, `messages` for raw conversation traces.
 
-### recall-memory_memory_hybrid_search
+### recall_memory_memory_hybrid_search
 
 Combines keyword (FTS5) and semantic (embedding) search. Best for natural language queries.
 
 ```
-recall-memory_memory_hybrid_search({ query: "how did we handle rate limiting" })
+recall_memory_memory_hybrid_search({ query: "how did we handle rate limiting" })
 ```
 
-### recall-memory_memory_recall
+### recall_memory_memory_recall
 
 Get recent context — LoA entries, decisions, breadcrumbs. Good for session start.
 
 ```
-recall-memory_memory_recall({ limit: 5, project: "my-app" })
+recall_memory_memory_recall({ limit: 5, project: "my-app" })
 ```
 
-### recall-memory_memory_add
+### recall_memory_memory_add
 
 Record structured information during sessions:
 
 ```
-recall-memory_memory_add({ type: "decision", content: "Use PostgreSQL over MySQL", detail: "Better JSON support and extensions" })
-recall-memory_memory_add({ type: "learning", content: "bun:sqlite uses $param syntax", detail: "Not :param like better-sqlite3" })
-recall-memory_memory_add({ type: "breadcrumb", content: "Auth refactor in progress, do not touch middleware yet" })
-recall-memory_memory_add({ type: "decision", content: "Ship onboarding first", importance: 9 })
+recall_memory_memory_add({ type: "decision", content: "Use PostgreSQL over MySQL", detail: "Better JSON support and extensions" })
+recall_memory_memory_add({ type: "learning", content: "bun:sqlite uses $param syntax", detail: "Not :param like better-sqlite3" })
+recall_memory_memory_add({ type: "breadcrumb", content: "Auth refactor in progress, do not touch middleware yet" })
+recall_memory_memory_add({ type: "decision", content: "Ship onboarding first", importance: 9 })
 ```
 
 The optional `importance` parameter (integer 1-10, default 5) controls
 L1 tier ranking at session start. LoA entries have a floor of 5.
 
-### recall-memory_memory_stats
+### recall_memory_memory_stats
 
 Get database statistics (record counts, database size).
 
-### recall-memory_loa_show
+### recall_memory_loa_show
 
 Show a full Library of Alexandria entry with its extracted wisdom.
 
-### recall-memory_context_for_agent
+### recall_memory_context_for_agent
 
 Get context to pass to a subagent before delegating tasks:
 
 ```
-recall-memory_context_for_agent({ agent_task: "implement the auth middleware", project: "my-app" })
+recall_memory_context_for_agent({ agent_task: "implement the auth middleware", project: "my-app" })
 ```
 
+### recall_memory_memory_dump
+
+Persist caller-supplied visible messages as a session and LoA entry. Use the `recall-dump` skill so the explicit user-consent gate is preserved.
+
+### recall_memory_decision_update
+
+Change an existing decision's status by ID when it is superseded, reverted, or confirmed.
+
 ## The CLI
 
 You can also use the `recall` CLI directly via shell commands:
@@ -102,8 +114,8 @@ Canonical workflow — memory-first, sensitive-data boundary, opt-in artifacts
 
 | Canonical step | Your tool / invocation |
 |---|---|
-| Invoke the workflow | `recall-scout` agent skill (installed at `~/.pi/agent/skills/recall-scout/`) |
-| "Search Recall first" (memory-first) | `recall-memory_memory_search` (keyword), `recall-memory_memory_hybrid_search` (natural language) |
+| Invoke the workflow | `recall-scout` Agent Skill (discovered from Recall's native Pi package) |
+| "Search Recall first" (memory-first) | `recall_memory_memory_search` (keyword), `recall_memory_memory_hybrid_search` (natural language) |
 | Persist a report (only if endorsed) | Write to `.agents/atlas/artifacts/YYYY-MM-DD-scout-<focus>.md` |
 
 ## Lifecycle scripts
@@ -115,7 +127,7 @@ They are platform-agnostic — Pi, Claude Code, and OpenCode share them.
 |---|---|
 | `./install.sh` | Install or reinstall. Idempotent. |
 | `./update.sh --check` | Check if a newer GitHub release exists. Check-only. |
-| `./update.sh` | Pull latest, rebuild, migrate DB, re-register extensions. Exit Pi first. |
+| `./update.sh` | Pull latest, rebuild, migrate DB, and refresh the Pi package plus MCP registration. Exit Pi first. |
 | `./uninstall.sh --dry-run` | Preview what would be removed. |
 | `./uninstall.sh` | Surgical remove; preserves `~/.agents/Recall/` (DB + backups + canonicals) by default. |
 | `./uninstall.sh --purge` | Also destroy `~/.agents/Recall/` and any legacy DB (double-confirmed). |
@@ -127,24 +139,37 @@ binary lives in the same `bun link` process tree, and rebuilding
 mid-session can corrupt in-flight extension invocations. Have them
 exit Pi first.
 
+## How Pi Is Installed
+
+Pi packages can carry Recall's two extensions and nine Agent Skills together.
+Pi packages cannot register an MCP server.
+
+`recall install` therefore coordinates separate native pieces: the Recall Pi package, the `pi-mcp-adapter` package, the owned `recall-memory` entry in `mcp.json`, and this guide.
+It also removes pre-package Recall extension and skill symlinks so Pi never loads two copies.
+
+Do not treat `pi install npm:recall-memory` as a complete Recall install.
+It omits the MCP adapter/configuration and does not guarantee that `recall` or `recall-mcp` is on `PATH`.
+
+See [`docs/PI_INTEGRATION.md`](docs/PI_INTEGRATION.md) for the verified Pi capability matrix and the explicit differences from Codex and Claude plugin bundles.
+
 ## Core Rules
 
 1. **Search before asking** — Before asking the user to repeat information, search memory first. Use `bias_type` when a likely record type should come first without hiding other context; use `table` only when you need one type exclusively.
-2. **Record decisions** — When architectural decisions are made, use `recall-memory_memory_add` to record them
-3. **Delegate with context** — Before spawning subagents, call `recall-memory_context_for_agent` to give them relevant history
+2. **Record decisions** — When architectural decisions are made, use `recall_memory_memory_add` to record them
+3. **Delegate with context** — Before spawning subagents, call `recall_memory_context_for_agent` to give them relevant history
 4. **Capture sessions** — At the end of a session, run `recall dump "Descriptive Title"` (the `recall-dump` skill) to persist the conversation
 5. **Onboarding check** — At session start, if the L0 identity tier is empty (no `~/.claude/MEMORY/identity.md` or the file is missing), suggest `recall onboard` once. Do not nag on subsequent turns.
-6. **Never store secrets** — `recall-memory_memory_add` and `recall dump` persist content verbatim into `recall.db`, and stored records can resurface in future sessions' L0/L1 context. Redact API keys, tokens, passwords, and credential-bearing snippets before recording (e.g. `[REDACTED:api-key]`). When dumping a session that touched credentials, say so and confirm with the user first.
-7. **Record corrections** — When the user corrects you ("no, actually…", "that's wrong, use X"), record it immediately: `recall-memory_memory_add({ type: "learning", content: "<what was wrong → what is right>", confidence: "high", importance: 7 })`. Corrections are the highest-signal and most perishable memory; do not wait for session end.
+6. **Never store secrets** — `recall_memory_memory_add` and `recall dump` persist content verbatim into `recall.db`, and stored records can resurface in future sessions' L0/L1 context. Redact API keys, tokens, passwords, and credential-bearing snippets before recording (e.g. `[REDACTED:api-key]`). When dumping a session that touched credentials, say so and confirm with the user first.
+7. **Record corrections** — When the user corrects you ("no, actually…", "that's wrong, use X"), record it immediately: `recall_memory_memory_add({ type: "learning", content: "<what was wrong → what is right>", confidence: "high", importance: 7 })`. Corrections are the highest-signal and most perishable memory; do not wait for session end.
 
 ## How Extraction Works
 
 A Recall extension (`RecallPreCompact.ts` + `RecallExtract.ts`) runs inside Pi:
 
 1. `RecallPreCompact.ts` hooks into `before_agent_start` and injects relevant memory into the system prompt before each agent turn
-2. `RecallExtract.ts` hooks into `session_shutdown` (fires on exit — Ctrl+C, Ctrl+D, SIGTERM)
+2. `RecallExtract.ts` hooks into `session_shutdown` and reads the supported path from `ctx.sessionManager.getSessionFile()`
 3. Pi sessions use tree-structured JSONL (each entry has `id` and `parentId`) rather than a linear format — the extension linearizes the active branch into flat markdown
-4. The markdown is dropped into `~/.claude/MEMORY/pi-sessions/`
+4. The markdown is dropped into `$RECALL_HOME/MEMORY/pi-sessions/` (default `~/.agents/Recall/MEMORY/pi-sessions/`)
 5. A batch extraction cron job (`RecallBatchExtract`) processes these files into structured memory
 
 ## Database Location
@@ -155,4 +180,4 @@ The SQLite database is at `~/.agents/Recall/recall.db` (or wherever `RECALL_DB_P
 - **FTS5** indexes on all text tables
 - **Vector embeddings** (optional, requires Ollama) for semantic search
 
-The same database is shared with Claude Code and OpenCode if both are installed — your memory is unified across platforms.
+The same database is shared with Claude Code, OpenCode, and Codex if they are installed — your memory is unified across platforms.
diff --git a/README.md b/README.md
@@ -320,7 +320,7 @@ Recall is built around two integration surfaces: **MCP** (memory search and add,
 | Agent                                                         | MCP |                      Lifecycle hooks                       | Status                                |
 | ------------------------------------------------------------- | :-: | :--------------------------------------------------------: | ------------------------------------- |
 | [**Claude Code**](https://claude.com/claude-code)             | ✅  |            ✅ Stop · SessionStart · PreCompact             | **Stable** — reference implementation; native plugin ships skills + MCP |
-| [**Pi**](https://pi.dev/)                                     | ✅  | ⚠ Beta — `recall-compaction` + `recall-extract` extensions | In progress                           |
+| [**Pi**](https://pi.dev/)                                     | ✅  | ⚠ Beta — native package with memory-injection + shutdown-capture extensions | Package + separate MCP adapter/config |
 | [**OpenCode**](https://opencode.ai/)                          | ✅  |             ⚠ Alpha — `recall-extract` plugin              | In progress                           |
 | [**Codex CLI**](https://github.com/openai/codex)              | ✅  |               — native plugin, explicit dump only          | MCP + skills available                |
 | [**Gemini CLI**](https://github.com/google-gemini/gemini-cli) |  —  |                             —                              | Coming soon                           |
@@ -342,6 +342,7 @@ Have an agent you'd like to see supported? [Open an issue](https://github.com/ed
 | [Agent Skills](docs/agent-skills.md)       | `recall-*` skills for Claude Code, Pi, and omp                            |
 | [Codex Integration](docs/CODEX_INTEGRATION.md) | Native plugin install, MCP coverage, and lifecycle limits             |
 | [Claude Integration](docs/CLAUDE_INTEGRATION.md) | Native plugin install, plugin/installer ownership split, migration    |
+| [Pi Integration](docs/PI_INTEGRATION.md)   | Native package, separate MCP setup, lifecycle coverage, and host limits  |
 | [Upgrading](docs/upgrading.md)             | Update, backup, migration system                                          |
 | [Troubleshooting](docs/troubleshooting.md) | Common issues and fixes                                                   |
 | [Changelog](CHANGELOG.md)                  | Release notes and breaking changes                                        |