Code map

Derived navigation, not authoritative product documentation.

This page is generated by npm run code-map from a curated, deterministic module list in scripts/generate-code-map.mjs. It is meant to help maintainers find code paths. Hand-authored docs, ADRs, tests, and Hindsight/Pi official docs remain the source of truth.

Refresh or disable

Refresh the map after moving major modules:

npm run code-map

Check generated output and the docs site:

npm run code-map:check
npm run docs:check

Disable by removing this page from astro.config.mjs navigation and excluding npm run code-map:check from docs:check. Do that only in a focused PR that explains why the map is no longer useful.

Extension entrypoint and lifecycle

Related hand-authored docs: Extension entrypoint and lifecycle

extensions/index.ts — Registers Pi hooks, tools, commands, and setup surface.
extensions/memory-lifecycle.ts — Coordinates session start, context recall, agent-end retain, and shutdown.
extensions/memory-lifecycle-runtime.ts — Builds per-turn runtime dependencies for lifecycle handlers.
extensions/memory-lifecycle-recall.ts — Implements ephemeral recall injection for the context hook.
extensions/memory-lifecycle-retain.ts — Builds sanitized retain deltas at agent end.

Operation service and explicit surface

Related hand-authored docs: Operation service and explicit surface

extensions/memory-operation-service.ts — Shared service used by tools, commands, setup, and maintenance intents.
extensions/operation-catalog.ts — Registry for command/tool operation metadata.
extensions/tools.ts — Registers explicit Hindsight tools.
extensions/commands.ts — Registers slash commands and command dispatch.
extensions/tool-presenters.ts — Formats explicit tool responses.

Identity, scope, and routing

Related hand-authored docs: Identity, scope, and routing

extensions/memory-identity.ts — Derives stable repo/session/document identity.
extensions/memory-scope.ts — Selects project/global scopes and tags.
extensions/memory-router.ts — Routes memory behavior by mode and operation.
extensions/routing-strategy.ts — Keeps routing policy behind an explicit strategy seam.
extensions/observation-scopes.ts — Defines retain observation-scope vocabulary.

Retain Queue and durable delivery

Related hand-authored docs: Retain Queue and durable delivery

extensions/retain-queue.ts — Queues retain jobs before delivery.
extensions/queue.ts — Queue record helpers and public queue operations.
extensions/jsonl-queue-store.ts — JSONL-backed active/dead-letter queue storage.
extensions/queue-lock.ts — Cross-process queue lock coordination.
extensions/queue-delivery.ts — Flushes queued jobs to Hindsight.
extensions/retain-job-builder.ts — Builds structured retain jobs from messages.
extensions/retain-cursor.ts — Persists already-retained transcript cursor state.

Historical import

Related hand-authored docs: Historical import

extensions/import-sessions.ts — Imports Pi session JSONL history.
extensions/import-chat-transcript.ts — Imports chat transcript JSONL.
extensions/import-parser.ts — Projects raw session records into importable messages.
extensions/import-plan.ts — Builds preview and execution plans.
extensions/import-execution.ts — Runs import plans.
extensions/import-retain.ts — Transforms import batches into Hindsight retain calls.
extensions/import-checkpoint.ts — Tracks deterministic import progress.
extensions/import-manifest.ts — Records import provenance.

Diagnostics, status, and safety

Related hand-authored docs: Diagnostics, status, and safety

extensions/diagnostics.ts — Collects doctor/diagnostic results.
extensions/status.ts — Builds user-facing status summaries.
extensions/status-health.ts — Classifies health of config/client/queue surfaces.
extensions/sanitize.ts — Redacts secrets before retain or display.
extensions/client.ts — Hindsight client adapter boundary.
extensions/client-rest.ts — REST transport implementation.

Configuration and setup TUI

Related hand-authored docs: Configuration and setup TUI

extensions/config.ts — Loads and resolves extension config.
extensions/config-normalize.ts — Normalizes config defaults and legacy shapes.
extensions/config-writer.ts — Writes config updates.
extensions/config-editing-registry.ts — Defines editable config fields.
extensions/guided-setup.ts — Runs setup intent flow.
extensions/setup-tui.ts — Implements setup TUI screens.
extensions/setup-tui-actions.ts — Applies setup TUI actions.
extensions/setup-tui-render.ts — Renders setup TUI state.

Data-flow sketch

Pi calls the extension entrypoint and lifecycle hooks.
Runtime and config modules derive repo/session identity, selected banks, document IDs, tags, and routing policy.
The context hook performs Recall and injects an ephemeral Recall Block.
Agent-end retain builds a sanitized structured delta and enqueues a Retain Job before delivery.
Queue delivery flushes jobs to Hindsight through the client adapter; failures remain durable for replay.
Explicit tools and commands use the operation service so user-triggered recall, retain, reflect, import, diagnostics, and setup behavior share policy.

Boundaries

No secrets, local absolute paths, raw retained payloads, or queue contents are included.
No network or AI service is required to generate or build this page.
File roles are intentionally short and stable; implementation details belong in tests, source, and hand-authored design docs.