Skip to content
Pi Hindsight

Getting started

Pi Hindsight gives Pi durable memory through Hindsight. For normal use, install the published package, run /hindsight, choose a memory profile, and let the TUI guide setup.

1. Install

Section titled “1. Install”

Install the npm package:

Terminal window
pi install npm:@luxusai/pi-hindsight

If you need unreleased source from GitHub:

Terminal window
pi install https://github.com/luxus/pi-hindsight

Local checkout installs are for contributors; see Development.

2. Choose a Hindsight server

Section titled “2. Choose a Hindsight server”

Use either:

The default local URL is:

http://localhost:8888

For a fully private setup without external LLM API keys, use Hindsight’s built-in llama.cpp/local-LLM path.

3. Run /hindsight

Section titled “3. Run /hindsight”

Open Pi in your repository and run:

/hindsight

If no project config exists, /hindsight offers guided setup, open hub, Ignore this repo (durable enabled: false + setupComplete: true + status.style: off; tools refuse calls), or skip for now. You can rerun guided setup later from the TUI with g. Details: Setup TUI.

Setup gate: automatic bank ensure, recall, and retain stay off until setup is satisfied. For default domain-tagged mode with project memory on, that means an explicit coding bank id (banks.project.bankId / PI_HINDSIGHT_PROJECT_BANK_ID, usually via guided setup). Soft signals alone (empty project config, queue/cursor files, or setupComplete without a bank id) do not unlock domain-tagged auto memory. Isolated-bank may keep path-derived banks after config/runtime signals or guided setup. Status warns when setup is required. Upgrading from path banks: Upgrading to domain banks.

Guided setup handles:

  1. Hindsight server URL
  2. memory profile (Coding is recommended for normal repos)
  3. coding and/or life bank ids (shared coding bank id is saved to user/global config and prefilled next time)
  4. optional dry-run-first historical import

Bank templates, mental models, and directives are managed in the Hindsight control-plane web UI, not in Pi.

4. Pick a profile (Coding is the default recommendation)

Section titled “4. Pick a profile (Coding is the default recommendation)”
  • Coding (recommended): one shared coding bank; repos separated by tags. Use for almost every personal coding repo.
  • Coding + Life: coding bank plus an optional personal/life bank for prefs and goals.
  • Isolated project: hard-wall bank for this repo only (client/sensitive work).
  • Life only: personal bank only; no coding bank.
  • Recall only: inject memory, do not auto-save this session.

See Memory profiles and Memory banks.

5. Check status

Section titled “5. Check status”

After setup, /hindsight should show:

  • reachable Hindsight server
  • expected memory profile (usually Coding)
  • expected coding bank and optional life bank
  • automatic recall/retain state
  • retain queue path
  • import checkpoint/manifest state when imports have run

If automatic recall injects irrelevant noise, see Recall quality for always-on filters and optional score floors (off by default).

To share the same banks with other AI tools over MCP, see MCP multi-client bank wiring.

6. Import old sessions only when useful

Section titled “6. Import old sessions only when useful”

Live retain starts after setup. Historical import is optional backfill. Use guided setup’s import prompt first when it appears; it previews before writing memory.

For later imports, use the Importing sessions guide. Commands and tools remain available for advanced or scripted imports.