pi-hindsight-stats

Hindsight memory analytics for Pi agent sessions — fetches tags, entities, entity-graph hotspots, and mental models from Hindsight banks and renders a compact project-insight cover.

Injected into Pi agent context on session start (async, non-blocking) or queried on-demand via CLI and slash commands.

Features

• Tag analytics — top tags with level-grouping and ranking
• Entity tracking — most-mentioned named entities with mention counts
• Graph visualization — hotspot chains from entity relationship graph
• Mental models — active mental model summaries
• TTL-based disk cache — avoids redundant API calls with configurable TTL
• Token-budgeted rendering — respects configurable max token budget for context injection
• Non-blocking injection — async fire-and-forget on session_start, never blocks Pi workflow
• Configurable steps — enable/disable individual stat sections independently

Example Output

[Top Tags]
- repo:vendor-omo (182)
- topic:auth (91)

[Top Entities]
- Stripe (31)
- AuthService (28)

[Hotspots]
- AuthService ↔ Stripe ↔ SessionToken

[Top Mental Models]
- active-project-goals
- coding-constraints

Installation

For Humans

npm install pi-hindsight-stats

For AI Agents

Add to your Pi settings.json packages array:

{
  "packages": [
    "pi-hindsight-stats"
  ]
}

For pi git-sourced

Add the git URL to your Pi settings.json packages array:

{
  "packages": [
    "https://github.com/buihongduc132/pi-hindsight-stats"
  ]
}

Or local path for development:

{
  "packages": [
    "/path/to/pi-hindsight-stats"
  ]
}

Prerequisites

• A running Hindsight server
• Pi CLI agent (@mariozechner/pi-coding-agent)

Configuration

Create ~/.hindsight/stats-config.json:

{
  "enabled": true,
  "baseUrl": "http://localhost:8888",
  "bankId": "my-bank",
  "injectOnSessionStart": true,
  "cache": {
    "dir": "~/.hindsight/cache/stats",
    "ttlSeconds": 600
  },
  "steps": {
    "topTags": { "enabled": true, "limit": 5, "maxTokens": 120, "level": 2 },
    "topEntities": { "enabled": true, "limit": 5, "maxTokens": 120 },
    "hotspots": { "enabled": true, "limit": 5, "maxTokens": 160, "level": 2 },
    "topMentalModels": { "enabled": true, "limit": 5, "maxTokens": 120 }
  },
  "render": {
    "totalMaxTokens": 420,
    "compact": true
  }
}

Config precedence

env vars (HINDSIGHT_BASE_URL, HINDSIGHT_API_KEY, HINDSIGHT_BANK_ID)
  > ~/.hindsight/stats-config.json
  > defaults

Step options

| Step | Config key | Description | |------|-----------|-------------| | Top Tags | topTags | Most frequent tags across all facts | | Top Entities | topEntities | Most mentioned named entities | | Hotspots | hotspots | Highly connected entity clusters from the entity graph | | Top Mental Models | topMentalModels | Active mental model summaries |

Each step supports: enabled, limit, maxTokens, and optional level (graph traversal depth).

Usage

Pi Extension (automatic)

When installed as a Pi package, the extension auto-registers hooks and commands:

• Session start — if injectOnSessionStart is true, fetches and injects a stats cover into context (non-blocking)
• hindsight-stats:cover — show stats cover on demand via Pi slash command
• hindsight-stats:cache-clear — clear the stats cache via Pi slash command

CLI

# Full cover report
npx hindsight-stats cover

# Individual sections
npx hindsight-stats top-tags --limit 10
npx hindsight-stats top-entities --limit 10
npx hindsight-stats hotspots --limit 5
npx hindsight-stats top-mental-models --limit 5

# Cache management
npx hindsight-stats cache-clear

# Diagnostics
npx hindsight-stats doctor

Architecture

src/
├── index.ts    # Pi extension — session_start hook, async injection
├── client.ts   # Hindsight REST API client (tags, entities, mental models)
├── config.ts   # Config resolution with file/env/defaults
├── cache.ts    # TTL-based disk cache
└── steps.ts    # Individual stat extraction + rendering
cli/
└── index.ts    # Standalone CLI entry point
tests/          # Vitest test suite

Development

npm install
npm run typecheck
npm test

License

MIT © 2025 buihongduc132