pi-recall

Fast full-text search and native session resume for Pi.

Search prior Pi sessions, filter by #tags, and resume the one you want — from a terminal picker or from the model via a built-in recall tool.

Install

pi install npm:@joshbochu/pi-recall

Supported prebuilt addons: macOS (arm64, x64), Linux glibc (x64, arm64), Windows (x64). Other platforms compile during install and need Rust/Cargo.

In-session manual (after install):

/recall help

Quick start

/recall
/recall staging deploy
/recall #codebase
/recall authentication #codebase

Key	Action
Type	Search (trailing tokens get prefix matching while you type)
↑ / ↓	Move selection
Enter	Resume the selected session
Tab	Toggle this folder ↔ all projects
Esc	Close

/recall-reindex rebuilds the search index. Tags and config are kept.

Commands

Command	What it does
/recall [query]	Open the session picker, optionally with an initial query
/recall search <query>	Same as /recall, but safe when the query starts with a command word (tag, help, …)
/recall help	Show the in-session manual (?, manual, -h, --help also work)
/recall tag #a #b	Add manual tags to the current session
/recall untag #a	Remove tags from the current session
/recall tags	Show manual and generated tags for the current session
/recall autotag	Generate tags for the current session
/recall autotag --all-untagged	Confirm, then auto-tag every searchable session that has no tags
/recall-reindex	Discard and rebuild the Tantivy index

Session tags

Tags belong to the current session and survive /recall-reindex:

/recall tag #codebase #rust #search
/recall tags
/recall untag #search
/recall autotag
/recall autotag --all-untagged

• #tag in a search query is an exact session filter (multiple hashtags AND together).
• Remaining words are ordinary full-text search over message content and tag text.
• Manual tags are never replaced by generated tags; an explicitly removed tag is suppressed from later generation.
• --all-untagged shows a confirmation overlay with session count and model before any API calls. Esc cancels.

Default auto-tag model is whatever Pi has selected. Override in ~/.pi/agent/pi-recall/config.json:

{
  "autoTags": {
    "model": "provider/model-id",
    "minimum": 3,
    "maximum": 7
  }
}

The model must exist in Pi’s registry with credentials configured. Auto-tagging sends a bounded session excerpt to that provider (API usage and provider privacy terms apply).

Env overrides:

• PI_RECALL_DATA_DIR — durable tag/config directory (default ~/.pi/agent/pi-recall)
• PI_RECALL_CONFIG_FILE — specific config file path

Model tool

The agent gets one recall tool with actions:

Action	Purpose
search	Full-text search (optional query, scope, limit)
list	List sessions (scope, limit)
read	Read a session by id / id prefix / path (session, limit = latest N messages)

scope is current (this folder) or all (default for the tool). Output is capped at 800 lines / 40KB.

Search behavior

• One Tantivy document per normalized user/assistant message, plus a metadata document for each tagged session.
• Consecutive same-role messages are joined before indexing.
• Message content and tag text are searchable; IDs, names, and paths are stored metadata.
• Ordinary terms use OR semantics; tag-text matches get a 4× field boost; multi-token queries also get a 10× exact-phrase OR clause.
• #tag filters are exact. Cwd / allowed-session constraints are applied natively before top-doc collection.
• Results are grouped by session; near-tied messages prefer later messageIndex; session scores get a seven-day recency boost.
• Snippets are ~200 characters with byte-offset match spans for highlighting.
• The picker prefix-expands an unfinished trailing token (≥2 chars, not a #tag, query not ending in whitespace). The recall tool keeps exact lexical semantics (no prefix expansion).

This is lexical search, not semantic retrieval: no embeddings, stemming, synonyms, or typo edit-distance.

Only user and assistant text (plus tags) are indexed. Thinking blocks, tool calls, and tool output are excluded.

Storage

Path	Contents
~/.pi/agent/cache/pi-recall-tantivy-v3/	Native Tantivy index
~/.pi/agent/cache/pi-recall-v3.json	File signatures + session summaries
~/.pi/agent/pi-recall/tags-v1.json	Tags (user data; kept across reindex)

PI_RECALL_CACHE_DIR relocates both cache files. Unreadable sessions are skipped with a warning; searchable sessions remain indexed.

Local development

git clone https://github.com/joshbochu/pi-recall.git
cd pi-recall
npm install
pi install /absolute/path/to/pi-recall
# or: pi -e /absolute/path/to/pi-recall

npm run check
npm run check:native
npm test

See docs/architecture.md for component boundaries and the native bridge.

Publishing

Every push to main publishes a new package version via GitHub Actions (publish.yml). The workflow chooses the next patch from max(package.json, npm latest), verifies, publishes platform addons when possible, stamps optionalDependencies for addons that exist, publishes the root package, then records release: vX.Y.Z and tag vX.Y.Z.

Trusted publisher on npm (per package, including each @joshbochu/pi-recall-native-*):

• Repository: joshbochu/pi-recall
• Workflow: publish.yml
• Allowed action: npm publish

First-time platform package names need a one-shot NPM_TOKEN (or a manual first publish), then OIDC is enough. Until a platform addon exists, root still publishes and postinstall falls back to a local Cargo build.

Helpers: npm run pack:platform, npm run version:next, npm run check:release, npm run stamp:prebuilt.

License

MIT. See THIRD_PARTY_NOTICES.md for required third-party notices.