# feveromo/pi-hybrid-memory architecture

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

- Interactive diagram: https://gitdiagram.com/feveromo/pi-hybrid-memory
- Repository: https://github.com/feveromo/pi-hybrid-memory

## Overview

1. **What this repo is**
   `pi-hybrid-memory` is a **Pi package / plugin** written in TypeScript that adds a **local-first memory layer** for Pi agents. It is not a standalone server; it runs inside Pi’s extension/runtime boundary and exposes Pi commands, tools, and hooks.

2. **Core architectural boundary**
   The system is split into two storage scopes:
   - **User scope:** `~/.pi/agent/memory/`
   - **Project scope:** `<project>/.pi/hybrid-memory/`
   
   Both store durable memory as **JSONL plus Markdown summaries**, which makes the memory inspectable and editable by hand.

3. **Primary data model**
   The main persisted artifacts are:
   - `records.jsonl` for atomic memory records
   - `summary.md` for human-readable rollups
   - `state.json` for book-keeping
   - project-only files like `context.md`, `repomap.json`, `active.json`, and `audits/`
   
   This suggests a deliberately simple file-based architecture instead of a database-backed one.

4. **Memory retrieval path**
   Retrieval is **lexical/path/symbol-based first**. The repo explicitly avoids vector search and external services. Search is exposed through tools/commands and filtered by scope, kind, and status, so the architecture favors deterministic local lookup over semantic ranking infrastructure.

5. **Prompt injection boundary**
   Retrieved memory is injected through Pi’s `before_agent_start` path as **transient context**, not as privileged instructions. The injected payload is intentionally bounded by tunable budgets and section limits, with deduping and formatting polish to keep it compact. This is an important boundary for any diagram: memory is *context*, not control.

6. **Repo-map subsystem**
   The project maintains a lightweight `repomap.json` in the project memory folder. It includes **tracked and untracked non-ignored files**, plus symbols, imports, commands, tools, hooks, and exports. This acts as a fast orientation index for the current codebase and feeds search and context generation.

7. **Working-context subsystem**
   `context.md` is a compact generated summary of the current project state. It is refreshed alongside repo-map maintenance and is intended for fast agent orientation, not long-term durability.

8. **Session ingestion and pruning**
   There is a distinct pipeline for importing Pi session data:
   - current/recent session ingestion
   - compact recaps and explicit preferences
   - trimming validation/build recipes
   - skipping delegated-agent noise and temp artifacts
   
   After turns, the system can auto-capture durable preference prompts and prune/roll up older recaps. This creates a short-term-to-durable memory path rather than storing every raw interaction.

9. **Cleanup and curation subsystem**
   Memory cleanup is append-only and status-based: records can be marked `done`, `stale`, or `superseded`. There is also an opt-in `/hmemory-audit` flow that uses the selected Pi model to propose validated changes such as dedupe, merge, pin, stale, and rewrite. The architecture keeps model-assisted edits behind an explicit operator action.

10. **Concurrency and mutation safety**
    Mutating operations are described as **parallel-safe** via Pi’s file mutation queue. That matters because the repo writes JSONL appends, regenerated summaries, and refreshed context files from multiple command/hook paths without assuming a database transaction layer.

11. **Security/privacy boundary**
    Secrets and sensitive path-like tokens are redacted before storage or injection, including patterns like `sk-...`, `sk-ant-...`, and `sk-proj-...`. Retrieved memory is also treated as **untrusted context**, which is a key trust boundary for diagramming the agent workflow.

12. **Operator surface**
    The repo exposes a broad command/tool surface: memory CRUD, search, repo-map rebuild/search, health dashboards, review UIs, refresh/bootstrap, and session import. These are all thin entry points into the same file-backed memory/index subsystem rather than separate services.

13. **Project lifecycle**
    Typical lifecycle is:
    - install as a Pi package
    - load the extension
    - initialize user/project memory paths
    - refresh repo map and context
    - ingest sessions and preferences
    - prune/roll up older recaps
    - optionally audit with a model
   
    The design is intentionally local and low-ops: no daemon, no vector DB, no external service by default.

14. **Repo structure and tooling**
    The implementation appears centered on `extensions/hybrid-memory.ts`, with behavior/fixture tests in `scripts/`. The `docs/` folder is substantial and likely documents architecture, configuration, usage, security, and reference behavior; for an architecture diagram, the docs are a strong sign that the package is organized around a few well-defined runtime flows rather than many source modules.

Main entry points: [`extensions/hybrid-memory.ts`](https://github.com/feveromo/pi-hybrid-memory/blob/main/extensions/hybrid-memory.ts) (Hybrid Memory), [`docs/README.md`](https://github.com/feveromo/pi-hybrid-memory/blob/main/docs/README.md) (Docs), [`scripts/test.mjs`](https://github.com/feveromo/pi-hybrid-memory/blob/main/scripts/test.mjs) (Test Scripts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_entrypoint["Hybrid Memory<br/>Pi extension<br/>[hybrid-memory.ts]"]
  node_surface{{"Commands & Hooks<br/>Pi surface"}}
  node_search(("Local Search<br/>lookup"))
  node_redaction{{"Redaction<br/>privacy filter"}}
  node_queue["Mutation Queue<br/>write safety"]
end

subgraph group_persistence["Persistence"]
  node_store[("Memory Store<br/>file-backed memory")]
  node_user_scope[("User Scope")]
  node_project_scope[("Project Scope")]
  node_records["Records<br/>JSONL log"]
  node_summary["Summary<br/>Markdown rollup"]
  node_state["State<br/>book-keeping"]
  node_repomap["Repo Map<br/>code index"]
  node_context["Context<br/>working summary"]
end

subgraph group_maintenance["Maintenance"]
  node_session(("Session Ingest<br/>pipeline"))
  node_prune{{"Prune & Rollup<br/>lifecycle"}}
  node_audit{{"Memory Audit<br/>operator flow"}}
  node_docs["Docs<br/>reference<br/>[README.md]"]
  node_tests["Test Scripts<br/>validation<br/>[test.mjs]"]
end

node_entrypoint -->|"wires"| node_surface
node_entrypoint -->|"orchestrates"| node_store
node_entrypoint -->|"builds"| node_repomap
node_entrypoint -->|"refreshes"| node_context
node_entrypoint -->|"ingests"| node_session
node_entrypoint -->|"exposes"| node_audit
node_surface -->|"invokes"| node_search
node_surface -->|"reads/writes"| node_store
node_surface -->|"queries"| node_repomap
node_surface -->|"serves"| node_context
node_search -->|"filters"| node_user_scope
node_search -->|"filters"| node_project_scope
node_store -->|"persists"| node_records
node_store -->|"rolls up"| node_summary
node_store -->|"tracks"| node_state
node_project_scope -->|"contains"| node_repomap
node_project_scope -->|"contains"| node_context
node_session -->|"feeds"| node_prune
node_prune -->|"updates"| node_store
node_audit -->|"proposes edits"| node_store
node_redaction -->|"scrubs"| node_store
node_redaction -->|"filters"| node_search
node_queue -->|"serializes writes"| node_store
node_queue -->|"serializes writes"| node_repomap
node_queue -->|"serializes writes"| node_context
node_docs -.->|"describes"| node_entrypoint
node_tests -.->|"verifies"| node_entrypoint

click node_entrypoint "https://github.com/feveromo/pi-hybrid-memory/blob/main/extensions/hybrid-memory.ts"
click node_docs "https://github.com/feveromo/pi-hybrid-memory/blob/main/docs/README.md"
click node_tests "https://github.com/feveromo/pi-hybrid-memory/blob/main/scripts/test.mjs"

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_entrypoint,node_surface,node_search,node_redaction,node_queue toneBlue
class node_store,node_user_scope,node_project_scope,node_records,node_summary,node_state,node_repomap,node_context toneAmber
class node_session,node_prune,node_audit,node_docs,node_tests toneMint
```

## Components

### Runtime

Pi extension boundary, commands, hooks, and local orchestration.

- [Hybrid Memory](https://github.com/feveromo/pi-hybrid-memory/blob/main/extensions/hybrid-memory.ts): Pi extension · Main TypeScript extension entrypoint that wires the package into Pi's runtime. · `extensions/hybrid-memory.ts`
- **Commands & Hooks**: Pi surface · Thin command, tool, and hook entry points that expose memory operations inside Pi.
- **Local Search**: lookup · Deterministic lexical/path/symbol-oriented retrieval filtered by scope and status.
- **Redaction**: privacy filter · Scrubs secrets and sensitive tokens before storage or injection.
- **Mutation Queue**: write safety · Parallel-safe file mutation layer used for appends and regenerated artifacts.

### Persistence

File-backed memory scopes, indexes, and generated context artifacts.

- **Memory Store**: file-backed memory · Durable local-first memory organized as JSONL records plus Markdown summaries.
- **User Scope**: scope · Per-user memory rooted at ~/.pi/agent/memory/.
- **Project Scope**: scope · Per-project memory rooted at <project>/.pi/hybrid-memory/.
- **Records**: JSONL log · Atomic durable memory records.
- **Summary**: Markdown rollup · Human-readable rollups of persisted memory.
- **State**: book-keeping · Persistence bookkeeping for memory lifecycle and status.
- **Repo Map**: code index · Project orientation index of files, symbols, imports, commands, tools, hooks, and exports.
- **Context**: working summary · Compact generated project-state summary for fast agent orientation.

### Maintenance

Session import, pruning, audits, and validation flows.

- **Session Ingest**: pipeline · Imports current and recent Pi session data into short-term memory flows.
- **Prune & Rollup**: lifecycle · Trims recaps, captures durable preferences, and marks older items stale or superseded.
- **Memory Audit**: operator flow · Opt-in model-assisted curation flow for dedupe, merge, pin, stale, and rewrite actions.
- [Docs](https://github.com/feveromo/pi-hybrid-memory/blob/main/docs/README.md): reference · Architecture, configuration, usage, security, and development documentation. · `docs/README.md`
- [Test Scripts](https://github.com/feveromo/pi-hybrid-memory/blob/main/scripts/test.mjs): validation · Behavior and fixture scripts used to validate core flows and regressions. · `scripts/test.mjs`

## Connections

- Hybrid Memory → Commands & Hooks: wires · Registers the command, tool, and hook surface inside Pi.
- Hybrid Memory → Memory Store: orchestrates · Coordinates file-backed memory operations and lifecycle updates.
- Hybrid Memory → Repo Map: builds · Refreshes the repository orientation index from project files.
- Hybrid Memory → Context: refreshes · Regenerates compact working context for agent startup.
- Hybrid Memory → Session Ingest: ingests · Pulls recent session data into the memory pipeline.
- Hybrid Memory → Memory Audit: exposes · Makes the explicit curation/audit operator flow available.
- Commands & Hooks → Local Search: invokes · Search commands and tools query local memory and repo state.
- Commands & Hooks → Memory Store: reads/writes · CRUD and search operations act on the local memory files.
- Commands & Hooks → Repo Map: queries · Repo-map commands rebuild and inspect the project index.
- Commands & Hooks → Context: serves · Context refresh and bootstrap flows expose the generated summary.
- Local Search → User Scope: filters · Retrieval can be scoped to user-level memory.
- Local Search → Project Scope: filters · Retrieval can be scoped to project-level memory.
- Memory Store → Records: persists · Stores atomic memory entries as append-only JSONL records.
- Memory Store → Summary: rolls up · Maintains human-readable Markdown summaries alongside records.
- Memory Store → State: tracks · Keeps lifecycle and bookkeeping state in a small state file.
- Project Scope → Repo Map: contains · Project scope includes the repo-map index used for orientation.
- Project Scope → Context: contains · Project scope includes the generated working-context summary.
- Session Ingest → Prune & Rollup: feeds · Session ingestion produces recap and preference material for rollup.
- Prune & Rollup → Memory Store: updates · Pruning marks entries done, stale, or superseded and appends curated changes.
- Memory Audit → Memory Store: proposes edits · Model-assisted curation suggests validated memory mutations.
- Redaction → Memory Store: scrubs · Sensitive tokens are redacted before durable storage.
- Redaction → Local Search: filters · Retrieved memory is treated as untrusted and sanitized before use.
- Mutation Queue → Memory Store: serializes writes · Parallel-safe mutation queue protects concurrent file updates.
- Mutation Queue → Repo Map: serializes writes · Queue also guards index refreshes and regenerated artifacts.
- Mutation Queue → Context: serializes writes · Queue prevents conflicting context rewrites.
- Docs → Hybrid Memory: describes · Documentation mirrors the main runtime and operator flows.
- Test Scripts → Hybrid Memory: verifies · Validation scripts exercise core package behaviors.
