Pi + Hindsight: Build Persistent Memory for Coding Agents

Introduction

The core motivation for connecting Pi to Hindsight is to enable new chat sessions to recall prior design decisions made in earlier conversations. Source code persists in repositories, but the rationale behind architectural choices often only exists in chat history and can be difficult to retrieve when revisiting projects.

During initial setup, even after the Pi extension for Hindsight was loaded, no memory entries appeared inside the memory bank. The root cause was straightforward: the LLM provider used by the Hindsight service for memory extraction lacked proper authorization. After switching to an authenticated provider, the system successfully ingested Git history, project structure scans and dialogue transcripts into memory storage.

Troubleshooting this integration requires separating two layers: verifying whether Pi can successfully call Hindsight APIs, and checking if the Hindsight backend can complete memory processing. This guide focuses on local daemon deployment. Hindsight Coding Agents also support multiple coding agents including Claude Code, Codex CLI, Cursor CLI, GitHub Copilot CLI and OpenCode. Installation instructions and hook configuration for each agent are available in the official documentation.

Data Flow Between Pi and Hindsight

Hindsight Coding Agents registers extensions and tooling for Pi, and invokes the Hindsight API mid-conversation. On the first connection to a repository, the default pipeline reads Git history and runs a read-only project scan to build initial memory. After each conversation round, the plugin writes dialogue records into the matching memory bank. The backend service extracts memory from these records to make them retrievable for future sessions.

1 Pi chat session starts → Retrieve existing memory based on current repository context
2 Pi calls Hindsight API → Fetch relevant observations and knowledge pages
3 Hindsight memory bank → Persist conversation records and progressively update observations

By default, each repository gets an independent memory bank, with naming patterns similar to coding-agent::my-repo. Worktree links do not share the main repository’s memory bank. This means Pi sessions working on the same repository share memory, while separate repositories maintain isolated memory stores.

Installing the Pi Extension

This guide uses local daemon mode. Run the following bash command for installation:

npm @vectorize-io/hindsight-coding-agents@0.8.0 install pi --server daemon

The installer places the Hindsight runtime in the user directory and registers the Pi extension within ~/.pi/agent/settings.json. Pi connects to Hindsight through native extension hooks.

The local daemon requires uv. macOS environments additionally need the Rust toolchain. Before the extension starts services, it validates dependencies and the LLM provider assigned for memory extraction. If the Pi API launches but the daemon fails to start, inspect these prerequisites alongside Hindsight service logs.

The local Hindsight API endpoint defaults to http://127.0.0.1:9077. CLI tools and the web control plane run on separate ports. The web dashboard is started with the hindsight ui command, accessible at http://localhost:9999/dashboard.

Point the CLI at the local API endpoint first, then validate service health:

# Set API URL
hindsight configure
# API URL: http://127.0.0.1:9077
# Check service status
hindsight health
# List available memory banks
hindsight bank list

The dashboard screenshot comes from http://localhost:9999/dashboard, with bank names and activity data redacted.

The Eight Sidebar Menu Items: Usage During Coding Work

Decoded from the sample URL coding-agent%3A%3Aclaude-session-viewer, the bank ID reads coding-agent::claude-session-viewer. Once a target bank is selected in the top selector, these eight menu panels manage and inspect memory assets. Changing menu tabs updates the view URL parameter, which can be saved to directly jump to specific pages.

Menu	Page & URL	Practical usage during coding
Home	view=home	View memory overview, knowledge page distribution, recent activity and memory type statistics. Validate whether the bank has loaded data and new content ingestion. Track token consumption and memory growth.
Memories	view=memories	Browse World Facts, Experience records. World Facts capture objective external observations. Experience stores cross-turn dialogue history. Use this panel to verify whether requirements and design decisions are correctly captured.
Knowledge base	view=knowledge	Browse knowledge pages and mental models, search and edit entries. Before refactoring code, check component maps, conventions and prior decisions here to align with existing project rules.
Recall	view=recall	Recall Analyzer configures retrieval filters and returns traceable search results. Confirm whether Pi can fetch previous design decisions. Inspect retrieved token volume, filter logic and scoring.
Reflect	view=reflect	Trigger reflection over conversation history. The model synthesizes long-term memory to answer high-level design questions. Compare Recall raw search results against synthesized reflection outputs.
Documents	view=documents	View source files ingested into the bank. Check raw conversation logs, Git commit records and source materials. Distinguish original input documents from extracted memory records.
Entities	view=entities	Use relationship graphs or list view to inspect extracted entities and connections. Locate recurring objects and relationships mentioned across chat history.
Bank Configuration	view=config	Adjust bank-wide service behaviors. All clients connected to this bank inherit these settings. Tune memory strategy and permission rules for Pi integration.

Quick Concept Distinction

Documents store raw source materials. Memories are extracted facts and experiences derived from source material. Knowledge Pages represent synthesized design conventions. Use Recall for retrieval inspection, and Reflect for model synthesis over memory. A common workflow for refactoring: check component conventions from Knowledge Base → run Recall to fetch related decisions → use Reflect to understand design rationale → return to source code and test files to confirm context.

Subpages inside Bank Configuration

Settings under Bank Configuration modify runtime behaviors for the selected memory bank. Every client attached to this bank will be affected by configuration changes.

Subpage	Practical Purpose
General	Check bank overview, memory composition, merge status and backend operations. Diagnose write ingestion failures.
Memory Defense	Scans sensitive data and security risks during entry ingestion. Full detection, redaction and audit features are available within Hindsight Cloud.
Configuration	Set observation retention policy, mission and reflection prompt templates, knowledge page refresh frequency, and rewrite rules. Default values can be overridden.
Webhooks	Manage webhook endpoints to receive bank event notifications. Configure external alerting for memory ingestion events.
Audit Logs	Inspect retention, recall, and reflection execution traces. This feature requires service-side enablement.
LLM Requests	Review model usage, token volume, operation types and status codes. Critical for troubleshooting provider errors, latency and quota consumption.

The Pi extension registers Hindsight tooling in ~/.hindsight/coding-agents/dist/pijs. before_agent_start injects memory context according to configuration, and agent_end writes conversation transcripts back into the memory bank. Ingestion status can be cross-validated across Documents, Memories and General configuration panels. The control plane manages memory banks, while Vue dashboard code lives inside the repository. Pi plugin configuration is maintained independently and will not sync automatically with bank configuration changes.

Separate Model Configuration for Pi and Hindsight

Pi’s local model handles problem understanding, code generation and tool invocation. The Hindsight backend uses its own LLM provider for memory extraction and consolidation. Pi may function normally while the Hindsight provider authorization fails, resulting in no new memory written to banks.

The local Hindsight daemon uses authenticated Codex OAuth by default. Provider configuration lives inside daemon environment files:

# .env
HINDSIGHT_API_LLM_PROVIDER=codex-agent
HINDSIGHT_API_LLM_MODEL=copilot-gpt-4.1
HINDSIGHT_API_LLM_MODEL=gpt-5.6-luna

The model identifier must match models available under your authenticated account. If your tenant lacks access to gpt-5.4-mini, switching to gpt-5.6-luna will resolve backend authentication. After modifying provider or model parameters, restart the Hindsight daemon and run hindsight health to validate service status. API keys and OAuth credentials should not be hard-coded in source files or screenshots.

Two Hindsight Provider Modes for Claude

The HINDSIGHT_API_LLM_PROVIDER variable selects which provider Hindsight uses for memory processing. Two valid options exist for Claude workloads: claude-code and anthropic.

1. Claude Code login mode Set the environment variable and authenticate in the same user environment running the daemon.

HINDSIGHT_API_LLM_PROVIDER=claude-code
HINDSIGHT_API_LLM_MODEL=claude-sonnet-4-5-20250929

This path does not require manually defining HINDSIGHT_API_LLM_API_KEY, but it requires a valid Claude Code login. Some organization accounts block Claude subscription access, making this route unavailable.

1. Direct Anthropic API access Select the anthropic provider and supply an API key retrieved from Anthropic Console. Usage charges are billed directly to your Anthropic account.

HINDSIGHT_API_LLM_PROVIDER=anthropic
HINDSIGHT_API_LLM_API_KEY=<your-anthropic-api-key>
HINDSIGHT_API_LLM_MODEL=claude-haiku-4-5

<your-anthropic-api-key> is a placeholder. Replace this value with your real key and avoid committing secrets to version control.

Configuring Pi Automatic Memory Injection

Hindsight defaults to reflect injection, synthesizing full memory history when a new session starts. For memory-heavy banks, switch Pi to lower-volume recall injection to fetch only a small subset of relevant observations.

{
  "serverMode": "daemon",
  "hindsight": {
    "injectMethod": "recall",
    "injectTimeoutMs": 2000,
    "recallOptions": {
      "types": ["observation"],
      "maxTokens": 2000,
      "budget": 10000,
      "include": {
        "entities": null
      },
      "pageSearchLimit": 3,
      "pageRefreshEveryMinutes": 10,
      "pageTriggerType": "cron",
      "pageTriggerCron": "*/15 * * * *"
    }
  }
}

This configuration file lives at ~/.hindsight/coding-agents/settings.json. The injectTimeoutMs caps waiting time for memory retrieval. The recall scope filters returned memory to observations only, to reduce context window consumption. pageSearchLimit controls how many knowledge pages are fetched. Cron rules control background refresh cycles for knowledge pages. Newly written memory entries will not immediately appear in Knowledge Pages; these records require refresh jobs to populate.

Frequently Used Hindsight CLI Commands

Replace <bank-id> with the bank name returned from hindsight bank list. Use hindsight configure to persist the target API endpoint.

Command	Purpose
hindsight health	Check API and database service health
hindsight bank list	List all available memory banks on the connected API
hindsight bank stats <bank-id>	View memory statistics for a specific bank
hindsight memory recall <bank-id> "query" --fact-type observation --budget 2000	Run memory retrieval queries, inspect project decisions and history
hindsight memory reflect <bank-id> "query" --budget 10000	Trigger model synthesis over stored memory, suitable for high-level design questions
hindsight knowledge list-pages	Enumerate all knowledge pages
hindsight knowledge search <bank-id> "query" --limit 3	Hybrid search across documents and knowledge pages
hindsight operation list	Check ingestion and extraction job status
hindsight ui	Launch web dashboard

Troubleshooting bank ingestion failures: run hindsight health, inspect hindsight operation list and service logs. When provider errors occur, failures appear in operation history. Judge health from pending task counts and recent job status rather than cumulative counts alone.

Hindsight Tools Available inside Pi

After registering the Hindsight extension, these tools can be invoked on demand during Pi conversations.

Tool	Suitable Scenarios
hindsight_search_knowledge_pages(query)	Search project architecture, historical decisions and active tasks for large refactors
hindsight_list_knowledge_pages()	Enumerate page titles and retrieve page content
hindsight_recall(query)	Pull relevant memory observations when page content is insufficient
hindsight_reflect(query)	Synthesize memory records to answer high-level design questions
hindsight_ingest_doc(tile, content)	Manually write new documents into memory banks
hindsight_sync_status()	Check current synchronization state and metrics

Pi automatically uses recall for memory injection by default. Manual reflect calls are reserved when you need deep design analysis. If memory retrieval fails, inspect plugin logs and Hindsight service logs separately to determine whether the fault originates from the Pi extension or backend memory processing.

Official Documentation and Reference Resources

Installation and provider configuration can change across Hindsight versions. Always refer to the official documentation matching your installed release.

• Hindsight Coding Agents documentation: covers supported agents, installation and hook configuration

• Hindsight provider documentation: environment variable configuration for LLM providers

• Hindsight GitHub repository

• Anthropic API reference, Claude Code setup guides

• OpenAI API reference and authentication documentation

Version defaults shown here apply to hindsight-coding-agents@0.8.0 and Hindsight API 0.10.2. Values and provider support may shift in later releases. Use --help commands for version-specific parameter details.

Conclusion

Adding Hindsight memory capabilities to Pi turns isolated coding sessions into a continuous knowledge system. The integration separates two core responsibilities: Pi handles conversational reasoning and tool calls, while Hindsight manages long-term memory extraction, storage and retrieval. The most common failure point during setup is authorization issues for the memory-extraction LLM provider. The web dashboard and CLI suite deliver granular visibility across documents, entity relationships, recall traces and bank configuration.

Developers running multi-agent memory pipelines often need centralized routing and credential management for multiple LLM endpoints. 4sapi operates as an API gateway that streamlines unified access control and traffic routing across diverse model providers.

International access: https://4sapi.com

Domestic access: https://4sapi.org