@matthewfl/pi-contemplator 0.0.9 → 0.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 `pi-contemplator` is a [Pi](https://pi.dev/) plugin for long-running, largely unsupervised agentic sessions. It does two things:
 
-1. **Keeps memory alive across compaction.** A background **observer**, **reflector**, and **dropper** distill the conversation into a durable, branch-local memory ledger. When Pi compacts the context window, the summary is rendered deterministically from that ledger — fast, model-free, and lossless enough that important facts survive.
+1. **Keeps memory alive across compaction.** A background **observer** records evidence and a **summarizer** progressively condenses older memories into a durable, branch-local citation graph. When Pi compacts the context window, the active memory is rendered deterministically from that ledger — fast, model-free, and lossless enough that important facts survive.
 2. **Gives the primary agent a second set of eyes.** A background **contemplator** reads the accumulated memories and watches for reasoning that is going wrong. When it finds a genuine problem, it can inject a focused, memory-cited question. For deeper, recurring structural issues, it can commission a short-lived **reviewer** that produces a durable, advisory design proposal.
 
 The result: a long session is less likely to drift off course, get stuck in an unproductive loop, or silently compound a wrong conclusion — and when it does, it can often catch itself before the mistake poisons the rest of the work.
@@ -14,7 +14,7 @@ The result: a long session is less likely to drift off course, get stuck in an u
 > **Significant token usage:** The plugin runs multiple background agents and will significantly increase model-token consumption and associated API costs, especially during long sessions.
 
 > [!NOTE]
-> This project is a fork of the excellent [pi-observational-memory](https://github.com/elpapi42/pi-observational-memory) plugin by [@elpapi42](https://github.com/elpapi42). It retains that project's observer, reflector, dropper, memory, and compaction foundations while adding contemplation and structural review capabilities.
+> This project is a fork of the excellent [pi-observational-memory](https://github.com/elpapi42/pi-observational-memory) plugin by [@elpapi42](https://github.com/elpapi42). It builds on that project's observational-memory and compaction foundations, replacing separate reflection/pruning workers with a provenance-preserving summarizer while adding contemplation and structural review capabilities.
 
 ## Why use it?
 
@@ -127,9 +127,9 @@ Proposals are deliberately conceptual — the reviewer cannot write code, specif
 
 The memory system is built to be trustworthy:
 
-- **Every memory has provenance.** Observations cite the exact source entries that support them; reflections cite the observations they're based on. Everything gets a deterministic 12-character id computed in code, not guessed by a model.
-- **Nothing important is silently lost.** The `recall` tool recovers the exact source evidence behind any memory id. The `search_memories` tool finds candidate memories by topic. Even observations the dropper later prunes remain recallable from ledger history.
-- **Compaction is deterministic and model-free.** The summary the agent sees is folded from the ledger by code, not rewritten by a model. That makes compaction fast and cheap, and it means the same session state always produces the same summary.
+- **Every memory has provenance.** Observations cite the exact source entries that support them; summaries cite at least two source memories inline and retain machine-readable backpointers. Everything gets a deterministic 12-character id computed in code, not guessed by a model.
+- **Condensation stays navigable.** Once a memory is consumed by a summary it leaves the injected active pool, but remains searchable and recallable. `recall` shows immediate backward and forward graph links so the agent can walk from a summary to its evidence or from old evidence to the summaries that consumed it.
+- **Compaction is deterministic and model-free.** The active memory the agent sees is folded from the ledger by code, not rewritten during compaction by a model. That makes compaction fast and cheap, and it means the same session state always produces the same result.
 
 ## Why you can trust it in the background
 
@@ -144,17 +144,16 @@ Running extra agents in the background can be worrying — what if they take ove
 
 ## Background agents
 
-`pi-contemplator` uses five specialized background agents, all enabled by default:
+`pi-contemplator` uses four specialized background agents, all enabled by default:
 
 | Agent | What it does | When it runs |
 |---|---|---|
-| **Observer** | Extracts concrete, timestamped observations from the primary session, citing source entries. | In the background after turns, once enough new source text accumulates. |
-| **Reflector** | Distills durable conclusions (user intent, decisions, constraints) from observations, citing supporting observations. | Periodically, after the observer is up to date. |
-| **Dropper** | Prunes observations that are obsolete, redundant, or safely represented elsewhere, keeping the active memory pool bounded. | Only after a successful reflection, when the memory pool is over target. |
+| **Observer** | Extracts concrete, timestamped observations from the primary session, citing source entries and assigning a simple retention class. | In the background after turns, once enough new source text accumulates. |
+| **Summarizer** | Condenses related old observations and summaries into shorter, citation-linked summaries. Consumed sources leave active context but remain searchable and recallable through the graph. | When the old memory pool exceeds its token target; the newest memory pool remains protected. |
 | **Contemplator** | Watches accumulated memories for reasoning gaps, contradictions, overlooked alternatives, and recurring structural concerns; can send a focused probe or request a review. | Asynchronously after enough new memories accumulate. |
 | **Reviewer** | Performs a deep, scoped (workflow or software) structural investigation and records a durable proposal or a no-proposal conclusion. | Only when the contemplator commissions a review, and only one at a time. |
 
-The observer, reflector, and dropper provide the durable memory substrate. The contemplator reasons over that substrate, while the reviewer is launched only when a concern warrants a deeper structural investigation.
+The observer and summarizer provide the durable memory substrate. The contemplator reasons over that substrate, while the reviewer is launched only when a concern warrants a deeper structural investigation.
 
 ## Installation
 
@@ -180,8 +179,9 @@ Useful commands:
 - `/om:view` — inspect visible memory (and attempt to copy it).
 - `/om:view full` — inspect the full memory ledger, including everything not yet folded into a compaction.
 - `/om:view contemplator` — inspect the contemplator's private transcript and probes.
+- `/om:view summarizer` — inspect the latest launch-local summarizer transcript, including live thinking/output and completion or failure status.
 - `/om:view reviewer` — inspect structural reviewer transcripts and outcomes.
-- `/om:settings` — inspect or change session-level settings (including `messages on|off`, `reviewer on|off`, `compaction on|off`).
+- `/om:settings` — inspect or change session-level settings (including `messages on|off`, `summarizer on|off`, `reviewer on|off`, `compaction on|off`).
 
 Model selection, trigger thresholds, passive mode (which stops all background work), compaction behavior, and other tuning are documented in [docs/configuration.md](docs/configuration.md). See [docs/how-it-works.md](docs/how-it-works.md) for the memory lifecycle and [docs/concepts.md](docs/concepts.md) for the mental model.
 
@@ -190,9 +190,15 @@ Model selection, trigger thresholds, passive mode (which stops all background wo
 ```bash
 npm install
 npm test
+npm run test:unit
+npm run test:e2e
 npm run typecheck
 ```
 
+`npm test` runs both the unit and RPC end-to-end suites. Use `test:unit` or `test:e2e` to run either suite independently.
+
+`test:e2e` starts a local OpenAI-compatible model server and launches isolated real Pi CLI processes in RPC mode while mocking only the external model-server boundary. The suites cover observer, summarizer, contemplator, reviewer, primary-agent, memory-tool, and compaction flows. They exercise slow and parallel tools, probe races and feedback, hidden/idle delivery, cumulative activity time, process restore, reviewer transcript resume and budget exhaustion, accepted/rejected reviews, manual/failed compaction continuations and non-restarting proactive compaction, compaction observer sidecars, malformed memory records, huge-source bounding, id collisions, role-specific model routing, feature flags, session-tree forks, and concurrent session isolation.
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matthewfl/pi-contemplator",
-  "version": "0.0.9",
+  "version": "0.1.0",
   "description": "A Pi extension that keeps long-running agentic sessions on track with background memory, contemplation, and structural review.",
   "type": "module",
   "license": "MIT",
@@ -39,7 +39,9 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "npm run test:unit && npm run test:e2e",
+    "test:unit": "vitest run",
+    "test:e2e": "node tests/e2e/rpc-contemplator.mjs && node tests/e2e/rpc-summarizer.mjs && node tests/e2e/rpc-delivery.mjs && node tests/e2e/rpc-restore-review.mjs && node tests/e2e/rpc-compaction.mjs && node tests/e2e/rpc-compaction-resilience.mjs && node tests/e2e/rpc-memory-edges.mjs && node tests/e2e/rpc-routing-isolation.mjs"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
@@ -48,10 +50,10 @@
     "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.81.0",
-    "@earendil-works/pi-ai": "^0.81.0",
-    "@earendil-works/pi-coding-agent": "^0.81.0",
-    "@earendil-works/pi-tui": "^0.81.0",
+    "@earendil-works/pi-agent-core": "^0.84.3",
+    "@earendil-works/pi-ai": "^0.84.3",
+    "@earendil-works/pi-coding-agent": "^0.84.3",
+    "@earendil-works/pi-tui": "^0.84.3",
     "@types/node": "^22.0.0",
     "typebox": "^1.1.38",
     "typescript": "^5.6.0",