How feveromo/pi-hybrid-memory works
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: hybrid-memory.ts Hybrid Memory · README.md Docs · test.mjs Test Scripts
Components 18
Runtime
Pi extension boundary, commands, hooks, and local orchestration.
- Hybrid Memory · Main TypeScript extension entrypoint that wires the package into Pi's runtime.
extensions/hybrid-memory.ts - Commands & Hooks · Thin command, tool, and hook entry points that expose memory operations inside Pi.
- Local Search · Deterministic lexical/path/symbol-oriented retrieval filtered by scope and status.
- Redaction · Scrubs secrets and sensitive tokens before storage or injection.
- Mutation Queue · Parallel-safe file mutation layer used for appends and regenerated artifacts.
Persistence
File-backed memory scopes, indexes, and generated context artifacts.
- Memory Store · Durable local-first memory organized as JSONL records plus Markdown summaries.
- User Scope · Per-user memory rooted at ~/.pi/agent/memory/.
- Project Scope · Per-project memory rooted at <project>/.pi/hybrid-memory/.
- Records · Atomic durable memory records.
- Summary · Human-readable rollups of persisted memory.
- State · Persistence bookkeeping for memory lifecycle and status.
- Repo Map · Project orientation index of files, symbols, imports, commands, tools, hooks, and exports.
- Context · Compact generated project-state summary for fast agent orientation.
Maintenance
Session import, pruning, audits, and validation flows.
- Session Ingest · Imports current and recent Pi session data into short-term memory flows.
- Prune & Rollup · Trims recaps, captures durable preferences, and marks older items stale or superseded.
- Memory Audit · Opt-in model-assisted curation flow for dedupe, merge, pin, stale, and rewrite actions.
- Docs · Architecture, configuration, usage, security, and development documentation.
docs/README.md - Test Scripts · Behavior and fixture scripts used to validate core flows and regressions.
scripts/test.mjs
Connections 27
- 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.