pi-observational-memory: paying the memory cost before compaction arrives

Compaction of a compaction of a compaction

The README describes the failure mode in a way that anyone who has worked with a long coding session will recognise. A compaction summarizes the session. Later, another compaction summarizes that summary, and then another. After enough cycles, the agent is no longer carrying the real working context, it is carrying a compressed version of a compressed version of a compressed version.

The details that disappear are listed in the README, and the list is the interesting part, because it is a list of engineering rationale rather than of code state. Why a design decision was made. What approaches were already rejected. Which constraint mattered most. What the current branch is trying to achieve. What the user already clarified. What the agent already investigated. What should not be reopened.

The framing in the README is that this is not the agent becoming useless, and not the work becoming too complex, but the session starting to get compressed. For engineers, the argument is that long coding sessions are built out of accumulated decisions, and when those decisions lose their rationale the agent starts drifting.

The audience is named as engineers using Pi for real coding work, with the examples given as multi-day refactors, deep debugging sessions, architecture exploration, migrations, product implementation and long-running branches where context matters.

Observations record what happened, reflections record what holds

The extension organises memory around two concepts, and keeping them apart is the design decision that does the work.

Observations are concrete things that happened or were established during the session. The README's own examples are the user deciding to switch from REST to GraphQL, the migration being completed and validated, a bug being traced to a specific module, a branch focusing on replacing one implementation with another, or a deadline, constraint or preference being stated. Observations are timestamped events in chronological order, and they are what keeps the session grounded in actual work.

Reflections are durable facts distilled from observations, for example that the user is building a Next.js 15 dashboard with Supabase auth, that the current implementation must ship by a specific date, that the project prefers minimal abstractions over framework-heavy patterns, or that the branch is about improving long-session agent memory. Reflections are what keep the agent oriented over time.

The distinction has a practical consequence. An observation is tied to a moment and can be superseded. A reflection is a conclusion that survives, and it needs evidence. The README is unusually specific about that evidence: the reflector treats coverage as stewardship, every active observation it reviews carries a none, partial or strong coverage tier, and those tiers are review context rather than quotas. When the reflector emits a durable reflection, its support ids should cover all and only the observations whose durable meaning is actually preserved, because those ids later become dropper coverage evidence.

That is a claim about provenance, and it is the kind of detail that separates a memory system you can audit from one you cannot.

Background capture turns compaction into a rendering step

The second problem the extension targets is latency. Compaction can break flow: you are deep in a session, the agent needs to compact, and you wait while a model rewrites the past. In large sessions the README says that pause can take minutes, and it happens exactly when the session is already complex.

The approach is to move the work earlier. The extension continuously captures useful session memory while you work, capturing observations and distilling reflections in the background. When Pi needs to compact, the memory is already prepared, and compaction becomes a fast rendering step instead of a slow summarization event.

The README states the two resulting benefits plainly: less coherence loss, because important context is preserved as observations and reflections rather than repeatedly compressed through summary chains, and faster compaction, because the expensive memory work happens before compaction rather than while you wait. The stated goal is that when compaction happens you should barely notice.

The honest framing is also in the README. The promise is not magic infinite memory, it is practical continuity, that your agent keeps understanding the work even after days of iteration. The extension was built from real long-session usage, including Pi sessions that lasted for weeks, so the design target is a long session rather than an infinite one.

V3 is a new memory model, not an upgrade in place

The most important operational detail for anyone arriving from V2 sits in an important callout at the top of the README: the extension now uses the new V3 memory model, the V3 version does not read the old V2 settings or memory format, and you should start a new clean Pi session after upgrading.

That is a hard break, and it is stated as a requirement rather than a recommendation. If you used V2, you update your observational-memory settings before running this version, and the old configuration and stored memory are not migrated for you. A migration guide is referenced in the README under a section titled Migrating from V2, which tells you the intent exists even though the detail sits in a part of the document the excerpt here does not cover.

The second callout is about where you get the code. The master branch is the active development branch and may include unreleased or unstable changes. For stable versions, the README says to install the published npm package.

Together these two notes define the two installation postures: the branch is where the work happens, and the published package is where stability lives. The repository releases are consistent with that split, with 3.1.4 published on 2026-09-20 and 3.1.3 and 3.1.2 both on 2026-09-16, and the last push to the repository on 2026-10-05.

What Pi actually receives, and how to trace it back

The README shows the shape of the memory block Pi may receive at compaction time, and the formatting is not incidental. Entries carry ids in brackets, observations are timestamped with a severity marker, and the two sections are labelled separately.

The instruction text inside that block is aimed at the agent rather than the human, and it establishes the rules for using the memory. Entries are to be treated as past records, and when entries conflict the most recent observation reflects the latest known state. Work that prior observations describe as completed should not be redone unless the user explicitly asks to revisit it.

There is also a recall tool, and the block is explicit about when to use it and when not to. When exact source context is needed for precision or traceability, you use recall with the relevant observation or reflection id, which is especially useful when a reflection materially affects a decision or is too compressed to continue confidently. It should not be used as broad search, and raw source should not be injected unless it is needed.

That last constraint is a good sign about the design. The memory is a summary layer, and the system admits it, pointing to ids so that a claim can be traced back to the event that supports it. An agent that cannot retrieve the underlying record is a system you have to trust on faith, and this one gives you the handle.

A Pi extension with four peer dependencies and an esbuild step

The package manifest describes the integration points precisely. The extension registers itself through the pi key in package.json, pointing at a built entry file in the dist/ directory, and the published files list includes dist/, src/, LICENSE and README.md.

  "pi": {
    "extensions": [
      "./dist/index.ts"
    ]
  },

The stable install path given in the README is a single command, pi install npm:pi-observational-memory, which pulls the published package rather than the branch.

The build, typecheck and test scripts are equally short.

  "scripts": {
    "build": "node scripts/build.js",
    "typecheck": "tsc --noEmit",
    "test": "vitest run"
  },

The peer dependencies are the Pi runtime packages: @earendil-works/pi-agent-core, @earendil-works/pi-ai, @earendil-works/pi-coding-agent and @earendil-works/pi-tui, each declared as a wildcard so the extension follows whatever version the host agent is running. The development dependencies pin the same four at 0.87.0, and add esbuild for bundling, typebox, typescript 5.6 and vitest 4.1.

The scripts are minimal: the build runs node scripts/build.js, typecheck runs tsc with no emit, and the test script runs vitest. The repository layout matches, with src/ for sources, tests/, docs/, scripts/, a committed dist/ directory, and vitest.config.ts at the root. There is also a package-lock.json rather than a pnpm or yarn lock, an AGENTS.md and a CLAUDE.md for coding agents working in the tree, and a .github directory for the workflows.

The version in the manifest is 3.1.4, matching the latest published release, and the licence field says MIT, with the LICENSE file at the repository root. The description in the manifest is more precise than the README tagline: an observational memory extension for pi, with cache-friendly tiered compaction with observations and reflections. The cache-friendly part is the only phrase there that hints at the implementation, and it points at a design where the memory is stored in a form the compaction path can read cheaply rather than recomputed.

An extension versus the built-in compaction, and the risk it carries

The alternative is to use Pi's own compaction and accept the behaviour the README describes, which is a summary of a summary over a long session with a multi minute pause when the window fills. The difference in approach is that the extension moves memory construction out of the critical moment and into the background of the session, at the cost of maintaining a second representation of the history that has to be kept consistent with the conversation.

That is the real trade, and it comes with a specific risk. The extension's value depends on the quality of its distilled memory, and a distillation that drops the wrong detail is worse than a summary you can read, because the agent treats it as settled. The provenance rules in the README, the coverage tiers, the support ids and the recall tool are all mechanisms for making that quality auditable, but they are mechanisms the reader has to check, and the README does not publish an evaluation of how often the reflector gets it right.

There is also a boundary worth naming. This is a memory layer, not a planner. It preserves what was decided and why, which is what makes a long refactor survivable, but it does not expand what the agent can do. A session that lacks context and a session that lacks capability are different failures, and this extension addresses only the first.

For the licence, MIT is about as permissive as software licences get, with the usual attribution requirement on redistribution and no restriction on commercial use. The last push was on 2026-10-05 and the repository is not archived, so the 3.1.x line is still moving.

Editorial conclusion

Adopt pi-observational-memory if you run multi day Pi sessions where compaction repeatedly degrades the agent's grasp of earlier decisions, and you are on V3 already or willing to redo your settings after upgrading. Do not adopt it to solve a slow first compaction, since the extension shifts the cost earlier rather than removing it, and do not install it from the master branch if you need a reproducible environment, because the README marks that branch as active development with unreleased changes. Verify first by installing the published package with pi install npm:pi-observational-memory, starting a clean session, and checking that a compaction produces a memory block containing dated observation ids you can look up with the recall tool.

Frequently asked questions

Official sources

1. elpapi42/pi-observational-memory on GitHub
2. Issues
3. License: MIT
4. README
5. Releases