# elpapi42/pi-observational-memory architecture

> Architecture diagram of the GitHub repository elpapi42/pi-observational-memory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elpapi42/pi-observational-memory
- Repository: https://github.com/elpapi42/pi-observational-memory

## Overview

pi-observational-memory is a Pi extension that preserves useful context across long sessions. Pi session activity enters through registered lifecycle hooks: background observation captures source-linked events, reflection distills durable facts, and dropper maintenance manages observation retention. The session ledger provides memory state for compaction rendering and ID-based recall. Configuration, model resolution, and worker streaming support that workflow; status and view commands expose memory to the user. The README documents these capabilities, while several subsystem links below are supported by its statements rather than inspected implementation details.

Main entry points: [`src/hooks/consolidation-trigger.ts`](https://github.com/elpapi42/pi-observational-memory/blob/master/src/hooks/consolidation-trigger.ts) (Background consolidation), [`src/session-ledger`](https://github.com/elpapi42/pi-observational-memory/tree/master/src/session-ledger) (Session ledger), [`src/index.ts`](https://github.com/elpapi42/pi-observational-memory/blob/master/src/index.ts) (Extension registration), [`src/commands/status.ts`](https://github.com/elpapi42/pi-observational-memory/blob/master/src/commands/status.ts) (Status and view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Pi integration"]
  node_registration["Extension registration<br/>[index.ts]"]
  node_consolidation["Background consolidation"]
  node_compaction["Compaction rendering<br/>[compaction-hook.ts]"]
  node_trigger["Compaction trigger"]
  node_catchup["Compaction catch-up"]
  node_recalltool["Recall tool"]
  node_commands["Status and view<br/>[status.ts]"]
end

subgraph group_memory["Memory processing"]
  node_observer["Observation capture<br/>[agent.ts]"]
  node_reflector["Reflection distillation<br/>[agent.ts]"]
  node_dropper["Observation retention<br/>[agent.ts]"]
  node_coverage["Reflection coverage<br/>[coverage.ts]"]
  node_pool["Observation pool<br/>[pool.ts]"]
end

subgraph group_ledger["Session memory"]
  node_ledger["Session ledger"]
  node_recall["Observation recall<br/>[recall.ts]"]
  node_summary["Memory summary<br/>[render-summary.ts]"]
end

subgraph group_support["Runtime support"]
  node_runtime["Runtime and model resolution<br/>[runtime.ts]"]
  node_config["Memory configuration<br/>[config.ts]"]
  node_serialize["Source serialization<br/>[serialize.ts]"]
  node_workerstream["Worker stream dispatch<br/>[worker-stream.ts]"]
end

node_pi(("Pi session"))
node_model(("Language model"))

node_pi -->|"loads extension"| node_registration
node_registration -->|"registers hook"| node_consolidation
node_registration -->|"registers hook"| node_compaction
node_registration -->|"registers hook"| node_trigger
node_registration -->|"registers tool"| node_recalltool
node_consolidation -->|"runs observer"| node_observer
node_consolidation -->|"runs reflector"| node_reflector
node_consolidation -->|"runs dropper"| node_dropper
node_consolidation -->|"reads and records"| node_ledger
node_consolidation -->|"serializes source"| node_serialize
node_dropper -->|"uses pool"| node_pool
node_dropper -->|"uses coverage"| node_coverage
node_reflector -->|"assesses support"| node_coverage
node_observer -->|"resolves stream"| node_workerstream
node_reflector -->|"resolves stream"| node_workerstream
node_observer -->|"requests generation"| node_model
node_reflector -->|"requests generation"| node_model
node_dropper -.->|"requests generation"| node_model
node_compaction -->|"reads memory"| node_ledger
node_compaction -->|"uses catch-up"| node_catchup
node_catchup -->|"runs observer"| node_observer
node_catchup -->|"reads and records"| node_ledger
node_trigger -->|"checks progress"| node_ledger
node_recalltool -->|"queries records"| node_recall
node_recalltool -->|"reads session state"| node_ledger
node_commands -->|"reads memory"| node_ledger
node_commands -->|"reads runtime state"| node_runtime
node_commands -->|"reads pool metrics"| node_pool
node_runtime -->|"loads settings"| node_config
node_consolidation -->|"uses runtime"| node_runtime
node_compaction -->|"uses runtime"| node_runtime
node_commands -.->|"renders memory"| node_summary

click node_registration "https://github.com/elpapi42/pi-observational-memory/blob/master/src/index.ts"
click node_consolidation "https://github.com/elpapi42/pi-observational-memory/blob/master/src/hooks/consolidation-trigger.ts"
click node_compaction "https://github.com/elpapi42/pi-observational-memory/blob/master/src/hooks/compaction-hook.ts"
click node_trigger "https://github.com/elpapi42/pi-observational-memory/blob/master/src/hooks/compaction-trigger.ts"
click node_catchup "https://github.com/elpapi42/pi-observational-memory/blob/master/src/hooks/compaction-catch-up.ts"
click node_observer "https://github.com/elpapi42/pi-observational-memory/blob/master/src/agents/observer/agent.ts"
click node_reflector "https://github.com/elpapi42/pi-observational-memory/blob/master/src/agents/reflector/agent.ts"
click node_dropper "https://github.com/elpapi42/pi-observational-memory/blob/master/src/agents/dropper/agent.ts"
click node_coverage "https://github.com/elpapi42/pi-observational-memory/blob/master/src/agents/dropper/coverage.ts"
click node_pool "https://github.com/elpapi42/pi-observational-memory/blob/master/src/agents/dropper/pool.ts"
click node_ledger "https://github.com/elpapi42/pi-observational-memory/tree/master/src/session-ledger"
click node_recall "https://github.com/elpapi42/pi-observational-memory/blob/master/src/session-ledger/recall.ts"
click node_recalltool "https://github.com/elpapi42/pi-observational-memory/blob/master/src/tools/recall-observation.ts"
click node_summary "https://github.com/elpapi42/pi-observational-memory/blob/master/src/session-ledger/render-summary.ts"
click node_commands "https://github.com/elpapi42/pi-observational-memory/blob/master/src/commands/status.ts"
click node_runtime "https://github.com/elpapi42/pi-observational-memory/blob/master/src/runtime.ts"
click node_config "https://github.com/elpapi42/pi-observational-memory/blob/master/src/config.ts"
click node_serialize "https://github.com/elpapi42/pi-observational-memory/blob/master/src/serialize.ts"
click node_workerstream "https://github.com/elpapi42/pi-observational-memory/blob/master/src/agents/worker-stream.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_registration,node_consolidation,node_compaction,node_trigger,node_catchup,node_recalltool,node_commands toneBlue
class node_observer,node_reflector,node_dropper,node_coverage,node_pool toneAmber
class node_ledger,node_recall,node_summary toneMint
class node_runtime,node_config,node_serialize,node_workerstream toneRose
class node_pi,node_model toneIndigo
```

## Components

### Pi integration

- [Extension registration](https://github.com/elpapi42/pi-observational-memory/blob/master/src/index.ts): `src/index.ts`
- [Background consolidation](https://github.com/elpapi42/pi-observational-memory/blob/master/src/hooks/consolidation-trigger.ts): `src/hooks/consolidation-trigger.ts`
- [Compaction rendering](https://github.com/elpapi42/pi-observational-memory/blob/master/src/hooks/compaction-hook.ts): `src/hooks/compaction-hook.ts`
- [Compaction trigger](https://github.com/elpapi42/pi-observational-memory/blob/master/src/hooks/compaction-trigger.ts): `src/hooks/compaction-trigger.ts`
- [Compaction catch-up](https://github.com/elpapi42/pi-observational-memory/blob/master/src/hooks/compaction-catch-up.ts): `src/hooks/compaction-catch-up.ts`
- [Recall tool](https://github.com/elpapi42/pi-observational-memory/blob/master/src/tools/recall-observation.ts): `src/tools/recall-observation.ts`
- [Status and view](https://github.com/elpapi42/pi-observational-memory/blob/master/src/commands/status.ts): `src/commands/status.ts`

### Memory processing

- [Observation capture](https://github.com/elpapi42/pi-observational-memory/blob/master/src/agents/observer/agent.ts): `src/agents/observer/agent.ts`
- [Reflection distillation](https://github.com/elpapi42/pi-observational-memory/blob/master/src/agents/reflector/agent.ts): `src/agents/reflector/agent.ts`
- [Observation retention](https://github.com/elpapi42/pi-observational-memory/blob/master/src/agents/dropper/agent.ts): `src/agents/dropper/agent.ts`
- [Reflection coverage](https://github.com/elpapi42/pi-observational-memory/blob/master/src/agents/dropper/coverage.ts): `src/agents/dropper/coverage.ts`
- [Observation pool](https://github.com/elpapi42/pi-observational-memory/blob/master/src/agents/dropper/pool.ts): `src/agents/dropper/pool.ts`

### Session memory

- [Session ledger](https://github.com/elpapi42/pi-observational-memory/tree/master/src/session-ledger): `src/session-ledger`
- [Observation recall](https://github.com/elpapi42/pi-observational-memory/blob/master/src/session-ledger/recall.ts): `src/session-ledger/recall.ts`
- [Memory summary](https://github.com/elpapi42/pi-observational-memory/blob/master/src/session-ledger/render-summary.ts): `src/session-ledger/render-summary.ts`

### Runtime support

- [Runtime and model resolution](https://github.com/elpapi42/pi-observational-memory/blob/master/src/runtime.ts): `src/runtime.ts`
- [Memory configuration](https://github.com/elpapi42/pi-observational-memory/blob/master/src/config.ts): `src/config.ts`
- [Source serialization](https://github.com/elpapi42/pi-observational-memory/blob/master/src/serialize.ts): `src/serialize.ts`
- [Worker stream dispatch](https://github.com/elpapi42/pi-observational-memory/blob/master/src/agents/worker-stream.ts): `src/agents/worker-stream.ts`

### Other components

- **Pi session**
- **Language model**

## Connections

- Pi session → Extension registration: loads extension (evidence: `src/index.ts`)
- Extension registration → Background consolidation: registers hook (evidence: `src/index.ts`)
- Extension registration → Compaction rendering: registers hook (evidence: `src/index.ts`)
- Extension registration → Compaction trigger: registers hook (evidence: `src/index.ts`)
- Extension registration → Recall tool: registers tool (evidence: `src/index.ts`)
- Background consolidation → Observation capture: runs observer (evidence: `src/hooks/consolidation-trigger.ts`)
- Background consolidation → Reflection distillation: runs reflector (evidence: `src/hooks/consolidation-trigger.ts`)
- Background consolidation → Observation retention: runs dropper (evidence: `src/hooks/consolidation-trigger.ts`)
- Background consolidation → Session ledger: reads and records (evidence: `src/hooks/consolidation-trigger.ts`)
- Background consolidation → Source serialization: serializes source (evidence: `src/hooks/consolidation-trigger.ts`)
- Observation retention → Observation pool: uses pool (evidence: `src/agents/dropper/agent.ts`)
- Observation retention → Reflection coverage: uses coverage (evidence: `src/agents/dropper/agent.ts`)
- Reflection distillation → Reflection coverage: assesses support (evidence: `src/agents/reflector/agent.ts`)
- Observation capture → Worker stream dispatch: resolves stream (evidence: `src/agents/observer/agent.ts`)
- Reflection distillation → Worker stream dispatch: resolves stream (evidence: `src/agents/reflector/agent.ts`)
- Observation capture → Language model: requests generation (evidence: `src/agents/observer/agent.ts`)
- Reflection distillation → Language model: requests generation (evidence: `src/agents/reflector/agent.ts`)
- Observation retention → Language model: requests generation
- Compaction rendering → Session ledger: reads memory (evidence: `src/hooks/compaction-hook.ts`)
- Compaction rendering → Compaction catch-up: uses catch-up (evidence: `src/hooks/compaction-hook.ts`)
- Compaction catch-up → Observation capture: runs observer (evidence: `src/hooks/compaction-catch-up.ts`)
- Compaction catch-up → Session ledger: reads and records (evidence: `src/hooks/compaction-catch-up.ts`)
- Compaction trigger → Session ledger: checks progress (evidence: `src/hooks/compaction-trigger.ts`)
- Recall tool → Observation recall: queries records (evidence: `src/tools/recall-observation.ts`)
- Recall tool → Session ledger: reads session state (evidence: `src/tools/recall-observation.ts`)
- Status and view → Session ledger: reads memory (evidence: `src/commands/status.ts`)
- Status and view → Runtime and model resolution: reads runtime state (evidence: `src/commands/status.ts`)
- Status and view → Observation pool: reads pool metrics (evidence: `src/commands/status.ts`)
- Runtime and model resolution → Memory configuration: loads settings (evidence: `src/runtime.ts`)
- Background consolidation → Runtime and model resolution: uses runtime (evidence: `src/hooks/consolidation-trigger.ts`)
- Compaction rendering → Runtime and model resolution: uses runtime (evidence: `src/hooks/compaction-hook.ts`)
- Status and view → Memory summary: renders memory
