# 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.

```plaintext
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:

```bash
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:

```bash
# 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
# .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.
    

```env
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.

2.  **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.
    

```env
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.

```json
{
  "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](https://4sapi.com)

Domestic access: https://4sapi.org