Recall usage

Recall can run as a standalone Python CLI or as an extension inside Pi. Both modes use the same local SQLite index and Markdown context banks under ~/.recall.

What Recall indexes

• Claude Code transcripts under ~/.claude/projects
• Pi sessions under ~/.pi/agent/sessions or PI_CODING_AGENT_SESSION_DIR
• Codex sessions under $CODEX_HOME/sessions or ~/.codex/sessions
• OpenCode sessions in $OPENCODE_DB or $XDG_DATA_HOME/opencode/opencode.db (normally ~/.local/share/opencode/opencode.db)

Local state is stored at:

• ~/.recall/recall.db — SQLite index
• ~/.recall/contexts/ — reusable Markdown context banks
• ~/.recall/context-history/ — previous context-bank revisions

Standalone CLI

No-install usage

Core indexing, fuzzy search, and regex search have no required third-party Python packages:

python3 recall.py index
python3 recall.py search "deadlock investigation"

Install the recall command

Use a virtual environment to isolate Python dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .
recall --help

Update an editable install with git pull in the checkout. If you installed from a package archive, reinstall the newer package in the same virtual environment.

Search and session commands

recall index
recall search "deadlock investigation"
recall search --regex "IndexError|sqlite3"
recall recent
recall tui

Search can filter by source, project, role, date range, and result limit. It also supports JSON output and typo-tolerant fuzzy matching:

recall search "migration plan" --source pi --project recall --role user --limit 20 --json
recall search "retry backoff" --source opencode

If you have not installed the package, replace recall with python3 recall.py in these commands.

Optional local semantic search

Semantic indexing and search require fastembed and numpy. Install them with the semantic extra:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[semantic]"
recall index --semantic
recall search --semantic "why did we change the retry logic"

To install only the optional dependencies without installing the package:

pip install -r requirements-semantic.txt
python3 recall.py index --semantic

The configured embedding model is downloaded and run locally. Embeddings remain in the local SQLite database.

Pi extension

Install the published Pi package:

pi install npm:recall-pi

Update it later with:

pi update npm:recall-pi

To install from a local checkout while developing:

pi install /path/to/recall

The extension provides:

• /recall — interactive dashboard for search, recent sessions, contexts, and maintenance
• recall_search — search local session history
• recall_context — list, show, create, update, and attach context banks

The extension runs the bundled recall.py backend. It selects Python in this order:

1. RECALL_PYTHON, when set
2. .venv/bin/python inside the installed package
3. python3

For semantic search, install the optional dependencies into a Python environment the extension will use:

cd /path/to/recall-package
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[semantic]"

Alternatively, point the extension to another environment:

export RECALL_PYTHON=/absolute/path/to/venv/bin/python

Context banks

Context banks are plain Markdown files that can be reviewed, revised, reused, imported, and exported.

recall context create events-db "Track the durable state and open questions for the Events DB"
recall context create scratch --blank
recall context list
recall context show events-db
recall context path events-db
recall context update events-db "The migration is complete; remove the resolved question."
recall context undo events-db
recall context import ./handoff.md --name events-db
recall context export events-db ./events-db.md
recall context delete events-db --force
recall context generate events-db --session <session-id-prefix>

context create and context update accept natural-language instructions, show a focused preview, and offer Apply, Revise, Full editor, or Cancel. Use create --blank for an empty template. For model-free update scripts, repeat --replace OLD NEW.

In Pi, the recall_context tool provides the same review flow. You can ask naturally:

Create an events-db context that tracks durable state and open questions.
Attach the events-db context before we continue the migration.
Update the events-db context with the production rollout notes.

Privacy

Recall reads transcript files and writes its SQLite index and Markdown contexts locally. Core indexing, fuzzy search, regex search, and context-bank management do not send transcript content over the network.

Optional semantic search downloads its configured embedding model through fastembed, runs it locally, and stores embeddings in the local database.