pi-hindsight

Memory that compounds, not clutters.

Persistent memory for Pi, backed by a self-hosted Hindsight server. Install it, point it at your server, and memory works automatically from the first session.

Best fit for:

• Self-hosted Hindsight users who want full data control
• Long-lived repo work where context carries across sessions, including cross-project memory via a shared global bank
• Users who want per-prompt memory controls (#nomem, #global, #tags)
• Anyone who prefers a minimal, single-file extension with zero extra dependencies

Requirements

This extension connects to a self-hosted Hindsight server. It does not include or manage the backend.

You need a running Hindsight server.

If you don't have a Hindsight server yet, follow the Hindsight getting started guide first, then come back here.

Install

pi install npm:pi-hindsight

Or from GitHub:

pi install git:github.com/anh-chu/pi-hindsight

Quick start

1. Install the extension (see above).

2. Configure your Hindsight server in ~/.hindsight/config:

   api_url = "http://your-hindsight-server:8888"
   api_key = "<API_KEY>"
   global_bank = "optional-global-bank-id"

3. Verify in Pi:

   /hindsight status

That's it. Memory is fully automatic from here: recall before each turn, retain after each turn, no manual intervention needed.

Features

Automatic memory lifecycle

• Auto-recall: Before each agent turn, relevant memories from your project and global banks are injected into the prompt.
• Auto-retain: After each agent turn, the conversation is appended to a per-session memory document. Only the new delta is processed, no redundant work.
• Feedback loop prevention: Memory blocks are stripped from retained content. No recursive memory bloat.
• Noise filtering: Low-signal tool calls (bash, read, write, edit) are dropped from retained transcripts. Conversation and meaningful tool usage are kept.

Per-prompt controls

• #nomem or #skip: skip retain for this turn (sensitive or throwaway prompts).
• #global or #me: also retain this turn to your global bank (cross-project learnings).
• #architecture, #bug, etc.: custom tags extracted and attached to memory for filtering.

Project-level opt-out

Disable memory for specific projects by setting recall_enabled and retain_enabled to false in a project-level .hindsight/config:

recall_enabled = false
retain_enabled = false

Or use the interactive /hindsight settings command.

Manual tools (hindsight_recall, hindsight_retain, hindsight_reflect) remain available regardless.

Home directory handling

When Pi runs from your home directory, the global config (~/.hindsight/config) and local config (.hindsight/config in CWD) are the same file. This means a project-<username> bank is created alongside your global bank, causing duplicate recall and retain.

To fix this, set homedir_project = false in your global config:

homedir_project = false

With this set, sessions started from the home directory use only the global bank. All other project directories are unaffected.

In-chat visibility

| Event | What you see | |-------|-------------| | Recall | 🧠 Hindsight recalled N memories + snippet | | Retain (success) | 💾 Hindsight saved turn to memory → bank-name | | Retain (failure) | 💾 Hindsight retain failed, use hindsight_retain to save manually |

Manual tools

• hindsight_recall: Pull additional context from memory on demand.
• hindsight_retain: Force-save a specific insight.
• hindsight_reflect: Ask Hindsight to synthesize an answer from your memories (server-side reasoning).

Configuration

Global config: ~/.hindsight/config

api_url          = "http://localhost:8888"
api_key          = "your-api-key"
global_bank      = "sil"
recall_types     = "observation"
recall_budget    = "mid"
recall_max_tokens = 800
async_retain     = true

Project override: .hindsight/config (in project root)

Place a .hindsight/config file in any project directory to override global settings. Local values win.

recall_types     = "observation,experience"
recall_budget    = "low"
recall_max_tokens = 512

Config reference

| Key | Default | Description | |-----|---------|-------------| | recall_types | observation | Memory types to search: observation, world, experience. Comma-separated. Each type runs the full retrieval pipeline independently. | | recall_budget | mid | Retrieval depth: low, mid, high. Higher = more coverage but added latency. | | recall_max_tokens | Server default (4096) | Max tokens for injected memories. Lower values reduce context noise. Recommended: 800. | | async_retain | true | Non-blocking retain. Set false for sync retain with failure notifications. | | recall_enabled | true | Enable automatic recall before agent turns. Set false to disable auto-recall for this project. Manual hindsight_recall tool still works. | | retain_enabled | true | Enable automatic retain after agent turns. Set false to disable auto-retain for this project. Manual hindsight_retain tool still works. | | homedir_project | true | Treat home directory as a project. Set false to prevent creating a project-<username> bank when running Pi from your home directory. Recall and retain use only global_bank instead. | | global_bank | (none) | Bank ID for cross-project memory. When set, this bank is queried alongside the project bank on every recall. Turns tagged #global or #me are also retained here. Leave unset if you only want per-project memory. |

Commands

/hindsight status

Full health check: server reachability, auth, bank access, hook state, debug log tail.

URL:    http://localhost:8888
Server: ✓ online
Bank:   project-myapp
  ✓ auth ok
Global: global-bank

Hooks this session:
  session_start:      ✓ ok
  recall:             ✓ ok (3 memories)
  retain:             ✓ ok (project-myapp)

Debug log: disabled (set HINDSIGHT_DEBUG=1 to enable)

/hindsight stats

Memory, entity, and document counts for all active banks.

/hindsight settings

Interactive settings menu. View all current settings with their source (global, project, or default), toggle boolean settings, edit text values, and choose where to save (project or global config). When running from the home directory, saves go to global config only.

Use this to opt out a project from memory:

/hindsight settings
→ Auto-Recall: true [default]  →  toggle Off  →  save to Project
→ Auto-Retain: true [default]  →  toggle Off  →  save to Project

Or to disable home directory as a project:

/hindsight settings
→ Home Dir as Project: true [default]  →  toggle Off

Banks

Project bank

Named project-<dirname> based on your current working directory, created automatically on first use. No setup required. All turns are retained here by default, so each project builds its own isolated memory over time.

Global bank

Optional. Set global_bank = <bank-id> in your config to enable it. The global bank is meant for knowledge that applies across projects: preferred patterns, personal conventions, people and teams you work with, recurring tools.

On each session's first turn, both banks are queried in parallel and their results are merged into a single recall injection. You get project-specific context and cross-project context together, with no duplicated queries.

Turns are retained to the global bank only when you explicitly tag the prompt with #global or #me. Everything else goes to the project bank only, keeping global memory intentional.

Debug logging

Set HINDSIGHT_DEBUG=1 to enable verbose logging to ~/.hindsight/debug.log. Log tail is shown inline in /hindsight status.

Performance

Recall latency depends primarily on your database indexes and hosting tier. With HNSW indexes on Supabase free tier, expect ~4s for a parallel global + project bank recall.

For benchmarks, latency analysis, recommended settings, and a Supabase index checklist, see docs/performance.md.

Why Hindsight over other memory approaches

| Approach | Typical tradeoff | Hindsight + this extension | |---|---|---| | Markdown/file-based memory | Human-readable, but quality degrades over time | Automatic retain + retrieval, still inspectable | | Custom vector DB (ChromaDB, etc.) | Flexible, but requires ongoing tuning | Built-in memory model with multi-strategy recall | | Other Pi memory extensions | Often weak deduplication or limited bank cooperation | Observation-first recall with dedup, project + global bank cooperation |

On every first turn, both your project bank and global bank are queried in parallel. Project memories cover the current codebase; global memories carry patterns and preferences you've built across all your projects. You get both without any extra setup beyond setting global_bank in your config.

Hindsight uses semantic, BM25, graph, and temporal retrieval strategies. Entities (people, projects, tools) are recalled as connected context, not isolated snippets. Recent memories rank higher automatically.

Comparison with @walodayeet/hindsight-pi

There are two Hindsight extensions for Pi. Both connect to a self-hosted Hindsight server and provide auto-recall and auto-retain. They share the same core goal but differ in philosophy: this extension optimizes for simplicity and per-prompt control, while @walodayeet/hindsight-pi optimizes for configurability and operational tooling.

This section aims to help you pick the right one. Both are good.

At a glance

| Dimension | pi-hindsight (this) | @walodayeet/hindsight-pi | |---|---|---| | Install | pi install npm:pi-hindsight | pi install npm:@walodayeet/hindsight-pi | | Backend required | Self-hosted Hindsight server + Postgres (pgvector) + embedding API | Same | | Extra dependencies | None (raw fetch) | @vectorize-io/hindsight-client SDK | | Config format | .ini | JSON | | Codebase | Single file (~450 LOC) | Multi-file modular (~1500 LOC) |

Recall

| Dimension | pi-hindsight | @walodayeet/hindsight-pi | |---|---|---| | Trigger | before_agent_start, first turn only | before_agent_start or context hook | | Injection frequency | Implicit (internal recallDone flag) | Explicit: first-turn or every-turn | | Recall modes | Always auto-inject + manual tools | hybrid, context, tools, or off | | Dual-bank recall | Always queries global + project in parallel | Queries primary bank + optional globalBankId | | Recall types | Configurable, defaults to observation | Configurable per-type with recallPerType count | | Budget control | recall_budget + recall_max_tokens | budget + maxTokens via SDK | | Retry on failure | Up to 3 attempts across turns | No retry on recall failure |

What the differences mean:

• Recall modes. @walodayeet/hindsight-pi lets you set recallMode: tools to skip auto-injection entirely. This eliminates the before_agent_start blocking cost, which matters if your Hindsight server is slow or remote. This extension always auto-injects on first turn, no way to disable without unloading the extension.
• Dual-bank recall. Both extensions query multiple banks. This extension always queries global + project banks in parallel on every first turn, so cross-project knowledge is always available. @walodayeet/hindsight-pi does the same when globalBankId is configured, plus supports linked banks for multi-server setups.
• Injection frequency. @walodayeet/hindsight-pi makes the first-turn vs every-turn choice explicit and prompt-cache-friendly. This extension does the same thing implicitly (the recallDone flag), but the behavior is identical in practice.
• Retry logic. This extension retries recall up to 3 times across turns if the server is temporarily unreachable, which helps with flaky connections. @walodayeet/hindsight-pi does not retry recall, but retries retain writes with a 1.5s backoff.

Retain

| Dimension | pi-hindsight | @walodayeet/hindsight-pi | |---|---|---| | Trigger | agent_end, async by default | agent_end | | Write scheduling | Immediate (async fire-and-forget) or sync | turn, async, session, or N-turn batch | | Retain modes | Full transcript, append mode | response, step-batch, both, or off | | Content retained | User + assistant + non-operational tool calls | User + assistant text (turn summary) | | Document strategy | Append-mode with stable document_id per session | Per-turn writes, chunked if large | | Credential sanitization | No | Yes (strips API keys, tokens, secrets) | | Session lifecycle | Resets on session_compact | Flushes on shutdown, switch, compact, fork |

What the differences mean:

• Write scheduling. @walodayeet/hindsight-pi offers session (batch all writes until session end) and numeric batching (flush every N turns). This reduces server load for long sessions. This extension fires immediately after each turn, either async (non-blocking, default) or sync (blocks until confirmed).
• Retain content. This extension retains the full transcript including tool call names and inputs (excluding noisy operational tools like bash, read, write). This gives Hindsight richer context for extraction. @walodayeet/hindsight-pi retains a user+assistant text summary, which is lighter but may lose tool-use context.
• Append mode. This extension uses document_id + update_mode: append, so Hindsight only re-extracts the new delta each turn rather than reprocessing the entire session. @walodayeet/hindsight-pi writes each turn as separate retain calls, which is simpler but means each turn is processed independently.
• Credential sanitization. @walodayeet/hindsight-pi strips API keys, bearer tokens, and secrets from retained content before sending to the server. This extension does not, so secrets in conversation may end up in your Hindsight memory. If you work with credentials in chat, this matters.
• Session lifecycle. @walodayeet/hindsight-pi hooks into more Pi lifecycle events (shutdown, switch, fork) to flush pending writes. This extension only resets state on session_compact. If Pi exits abruptly with session-mode batching, @walodayeet/hindsight-pi is more likely to flush pending writes.

Per-prompt controls

| Dimension | pi-hindsight | @walodayeet/hindsight-pi | |---|---|---| | Opt-out | #nomem/#skip per-prompt, recall_enabled/retain_enabled per-project | Not available | | Global bank routing | #global or #me per prompt | Configured at bank strategy level | | Custom tags | #hashtags in prompt attached to memory | Automatic metadata tags (source, workspace, kind) | | Trivial prompt skip | Yes | Yes, plus meta-memory query filtering |

What the differences mean:

• Opt-out. This extension lets you prevent any single turn from being retained by starting your prompt with #nomem or #skip. Useful for sensitive discussions, throwaway questions, or noisy debugging sessions. @walodayeet/hindsight-pi has no per-prompt opt-out; you would need to set retainMode: off in config.
• Global bank routing. This extension lets you tag individual prompts with #global or #me to also retain that turn to your global bank (cross-project learnings). @walodayeet/hindsight-pi routes to global bank based on the configured bankStrategy, not per-prompt.
• Custom tags. This extension extracts #hashtags from your prompt and attaches them as Hindsight tags, useful for filtering memories later. @walodayeet/hindsight-pi adds structured metadata tags automatically (source, workspace, bank, kind) but does not extract user-defined tags from prompts.

Tooling and setup

| Dimension | pi-hindsight | @walodayeet/hindsight-pi | | -------------------| -------------------------------------------------------------| ---------------------------------------------------------------------------------------| | Config format | .ini (~/.hindsight/config) | JSON (~/.hindsight/config.json), also reads .toml | | Config inspection | /hindsight config shows current values | /hindsight:where shows which file won precedence | | Setup experience | Manual: edit config file, run /hindsight status | Interactive: /hindsight:setup wizard | | Diagnostics | /hindsight status (health + hooks + log tail) | /hindsight:doctor (preflight), /hindsight:status (runtime) | | Manual tools | hindsight_recall, hindsight_retain, hindsight_reflect | hindsight_search, hindsight_context, hindsight_retain, hindsight_bank_profile | | Commands | 3 (status, stats, settings) | 10+ (setup, settings, doctor, where, sync, map, mode, config, connect, stats) | | Performance docs | Benchmarks, latency analysis, Supabase index guide | Not included |

What the differences mean:

• Setup. @walodayeet/hindsight-pi has an interactive setup wizard that walks you through enabling Hindsight, setting the URL, choosing bank strategy, and saving. This extension requires manually editing a config file. If you are comfortable with config files, this is fine. If you want a guided first run, theirs is smoother.
• Diagnostics. Both have status commands. @walodayeet/hindsight-pi adds /hindsight:doctor for preflight checks and /hindsight:where to show exactly which config file contributed each value. This extension shows hook state and debug log tail inline in /hindsight status.
• Tools. This extension includes hindsight_reflect for server-side memory synthesis (Hindsight reasons over your memories and returns a synthesized answer). @walodayeet/hindsight-pi includes hindsight_context (similar, backed by the reflect API) and hindsight_bank_profile for inspecting bank metadata.
• Performance documentation. This extension includes latency benchmarks, analysis of what causes slow recall, and a Supabase index checklist. Useful if you are tuning a self-hosted setup.

Backend requirements

Both extensions require the same backend:

• A self-hosted Hindsight server
• Postgres with pgvector (Supabase works, dedicated Postgres works)
• An embedding API (Gemini embedding-001 or compatible)
• HNSW indexes on memory_units for acceptable recall latency (see Performance tuning)

Neither extension bundles or manages the backend. You deploy Hindsight separately and point the extension at it via config.

This extension uses raw fetch calls against the Hindsight REST API, no SDK dependency. @walodayeet/hindsight-pi uses the official @vectorize-io/hindsight-client SDK, which adds a dependency but tracks API changes automatically.

When to choose this extension

• You want a single-file, low-overhead setup with minimal config.
• Per-project opt-out matters: disable memory for specific projects or your home directory via config or /hindsight settings.
• Per-prompt memory controls matter: #nomem to skip, #global to route, #tags to annotate.
• You prefer full transcript retention with append-mode documents over turn summaries.
• You want hindsight_reflect for server-side memory synthesis.
• You want documented performance benchmarks and Supabase index guidance.
• You prefer zero extra dependencies beyond Pi itself.

When to choose @walodayeet/hindsight-pi

• You want granular recall control: tools-only mode eliminates cold-start latency from before_agent_start blocking.
• Flexible retain scheduling matters: session, async, or N-turn batching to reduce server load.
• You want a setup wizard and diagnostic commands (/hindsight:doctor, /hindsight:where).
• Credential sanitization in retained content is important to you.
• You prefer JSON config with a richer settings hierarchy.
• You want the official Hindsight client SDK for automatic API compatibility.

Shared strengths

Both extensions:

• Auto-recall relevant memories before agent turns
• Auto-retain conversation after agent turns
• Query global + project banks for cross-project knowledge
• Show visible recall/retain indicators in chat
• Provide manual tools for explicit memory operations
• Skip trivial prompts to reduce noise
• Support project-level config overrides
• Work with any self-hosted Hindsight server

Running tests

node --experimental-strip-types test.ts