@nklisch/pi-enhanced 0.4.4 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Changelog
 
-## v0.4.4 — Prepared
+## v0.5.0 — 2026-09-07
+
+### Changed
+
+- Bundle Astral Pocket 0.3.0: repository-scoped navigation clues and hard-won technical pitfalls replace broad startup digests. User preferences and delivery history no longer belong in memory.
+- Keep legacy notes and raw session history behind explicit historical recall. Add note retirement and complete-card startup budgets; exclude the active session from past-session search.
+
+### Migration
+
+- Old notes are not automatically promoted to startup learning. Existing Markdown remains available through explicit historical recall; no user data is deleted automatically. User preferences belong in user-maintained `AGENTS.md`, not Pocket.
+
+## v0.4.4 — 2026-09-06
 
 ### Fixed
 

package/README.md

@@ -25,7 +25,7 @@ install commands, or versions to coordinate.
 | pi-background-tasks | Background jobs with polling, status, cancellation, and wakeups. |
 | pi-model-modes | System-prompt adaptation per model and mode. |
 | pi-conveniences | `/exit`, `.agents/AGENTS.md` context loading, context-window footer, subagent model listing. |
-| pi-astral-pocket | Persistent note pocket and past-session recall, active only for gpt-6-astra. |
+| pi-astral-pocket | Repository navigation clues and technical pitfalls, with explicit historical recall; active only for gpt-6-astra. |
 | pi-fff-compat | FFF-indexed file search through Pi-native find/grep semantics (no fuzzy fallback). |
 
 (`@nklisch/pi-zai-research` remains published separately if you prefer its

package/node_modules/@nklisch/pi-astral-pocket/README.md

@@ -1,37 +1,104 @@
 # @nklisch/pi-astral-pocket
 
-Astral Pocket keeps durable Markdown notes across Pi sessions. It activates only
-when the current model is `openai-codex/gpt-6-astra`.
-
-Notes normally belong to the current Git repository. Subdirectories and linked
-worktrees share the same local repository identity. Explicit global notes can
-carry a general preference or a conditional lesson between repositories.
-Foreign repository memories are not injected into the current session.
-
-## Notes and digest
-
-The extension adds two tools while Astra is active:
-
-- `pocket_note` saves a durable note. Its default scope is `project`. The caller
-  may set `scope: "global"` only for an intentionally portable preference or
-  observation.
-- `pocket_recall` searches current-project and global notes, plus past Astra
-  sessions from the current repository. `full: true` returns larger excerpts.
-  `scope: "all"` deliberately includes other repositories and labels their
-  results as cross-repository precedent. Recall returns at most 20 matches from
-  each selected source.
-
-Distillation means extracting durable decisions, constraints, preferences, and
-pitfalls from an idle session into a source-linked note. Automatic extraction
-always stays project-scoped. A digest is then rebuilt from the actual notes for
-the current repository. Explicit global notes have a separate, smaller digest.
-The extension never builds a new digest by recursively summarizing an old one.
-
-Memory is historical evidence, not an instruction source. The current user
-request and current repository guidance take priority. Verify remembered facts
-when their relevance or freshness is uncertain.
-
-## Commands
+Astral Pocket helps an agent find its way around a repository and avoid repeating
+expensive technical mistakes. It stores short Markdown learnings across Pi
+sessions and activates only for `openai-codex/gpt-6-astra`.
+
+## What belongs in memory
+
+A learning is either:
+
+- **Navigation:** a non-obvious place to start investigating a problem, with the
+  relevant file, symbol, or evidence pointer.
+- **Pitfall:** a concrete failure, its cause or diagnostic clue, and what avoids
+  repeating the investigation.
+
+For example, knowing that a nested model call needs explicitly resolved
+credentials can save debugging an otherwise unexplained authentication failure.
+A general description of the repository's architecture does not belong here.
+
+User preferences, permissions, model choices, review instructions, and other
+user decisions are not Pocket learnings. Those belong in user-maintained
+`AGENTS.md` only when the user explicitly chooses to record them. Pocket does not
+write that file. Delivery history and facts already explained by current
+repository documentation also stay out of startup memory.
+
+## What enters the prompt
+
+Before an agent run, Pocket adds complete, source-linked learning cards from the
+current repository. Each card identifies its kind, last note-update date, and
+note file. That date does not mean the underlying fact was reverified.
+
+Selection considers every eligible note, prioritizes deliberate agent-authored
+notes over automatic extraction, and alternates navigation clues with pitfalls
+within those groups. Newer notes come first within each kind. Selection is not
+tailored to the current question.
+
+The default card budget is 6,000 characters; cards that do not fit are omitted
+rather than cut mid-sentence. The summary reports omitted material so the agent
+can search when needed.
+
+Subdirectories and linked Git worktrees share one repository identity. Foreign
+repository notes and global notes are not injected. Older, unclassified notes
+are not automatically promoted into learnings. Old aggregate digest files are
+not read or recursively summarized.
+
+Cards are investigation clues, not current engineering authority. Read current
+code and foundations before relying on a remembered claim. A useful discovery
+can become obsolete; replace or retire it rather than keeping two competing
+current-looking descriptions.
+
+## Saving and recalling
+
+`pocket_note` saves a repository-scoped navigation or pitfall learning with a
+short title and actionable body. Saving requires `kind`, `title`, and `body`;
+`kind` is `navigation` or `pitfall`. An optional `evidence` pointer can name the
+relevant file, symbol, test, or source. Keep one technical lesson per note.
+
+To update an agent-authored note, supply its filename as `replace`. To retire a
+note, call `pocket_note` with `action: "retire"` and `noteFile`. Saving a new note
+with `supersedes: ["old-note.md"]` retires the old note after saving its
+replacement. Retired notes leave startup and default recall immediately.
+
+Retiring a generated note also excludes its source session from further
+automatic extraction, including rebuilds. This prevents a model from reviving
+the same obsolete claim under a different title. Other active learnings from
+that session remain available; later useful discoveries can be saved manually.
+
+`pocket_recall` searches active repository learnings by default. Search terms
+are case-insensitive and must all match; there is no semantic search service.
+Start with one focused lookup and expand only when the result helps.
+
+Use `includeHistory: true` to include legacy, retired, or global notes. Use
+`source: "sessions"` or `source: "both"` to search raw session transcripts.
+`scope: "all"` adds other repositories. Historical results are labeled as
+precedent, not current truth. The active
+session is excluded from past-session searches. Cross-repository scope does not
+implicitly opt into legacy or retired notes.
+
+Returned text is an excerpt, not a model-generated summary. `full: true` requests
+a larger excerpt, not the complete file. Recall returns at most 20 matches per
+selected source.
+
+## Automatic extraction
+
+Distillation extracts a few narrowly useful technical learnings from an idle
+session. It does not produce a general session summary or a repository digest.
+The model is instructed to omit preferences, user decisions, delivery history,
+documented facts, and unsupported conclusions. Structured output validates the
+learning shape; it cannot guarantee perfect judgment about arbitrary prose.
+
+By default, an activation-time pass considers changed Astra sessions from the
+current repository that have been idle for at least six hours and were modified
+within the last 30 days. It processes at most 16 sessions, oldest eligible first.
+The active session is excluded. Changed sessions replace their generated notes;
+an extraction with no useful learnings removes obsolete generated notes.
+
+There is no daemon. Work runs on Astra activation or an explicit command.
+Switching away from Astra, disabling Pocket, reloading, or shutting down cancels
+the session-owned pass.
+
+## Controls
 
 ```text
 /pocket status
@@ -48,24 +115,13 @@ when their relevance or freshness is uncertain.
 /pocket rebuild
 ```
 
-`/pocket status` shows the requested and resolved model, requested and effective
-reasoning, whether distillation is enabled, and the last pass outcome. Pi may
-map a requested reasoning level to a model-supported effort; status reports that
-mapping.
-
-`/pocket distill` retries changed or previously failed session work and stale
-digests. `/pocket rebuild` also forces the current project and global digest
-caches to be regenerated. Both commands require an active Astra session and an
-enabled distiller.
-
-Changing the model or reasoning setting cancels the current pass before starting
-a replacement. Switching away from Astra, disabling the pocket, reloading, or
-shutting down cancels the session-owned pass.
+`/pocket status` reports activation, model availability, requested/effective
+reasoning, and the last pass outcome. `/pocket distill` processes eligible new or
+changed sources. `/pocket rebuild` forces a bounded re-extraction pass, preserving
+manual notes and retirements; it no longer rebuilds an aggregate digest. Both
+require an active Astra session and an enabled distiller.
 
-## Configuration
-
-Configuration lives in `config.json`. All fields are optional. These are the
-defaults:
+Configuration lives in `config.json`. All fields are optional:
 
 ```json
 {
@@ -81,52 +137,29 @@ defaults:
 }
 ```
 
-The model must use the exact `provider/modelId` form. Astral Pocket asks Pi's
-model registry for current authentication and headers on every request. It does
-not silently select another provider when that model is unavailable. A malformed
-configuration falls back to defaults without blocking note access.
+The model uses the exact `provider/modelId` form. Authentication and headers are
+resolved through Pi's model registry on every request. There is no silent
+provider fallback. Malformed configuration falls back to defaults without
+blocking note access.
 
-## Storage and recovery
+## Storage and privacy
 
-Files are stored under `~/.pi/agent/astral-pocket/`, or under
-`$PI_CODING_AGENT_DIR/astral-pocket/` when that variable is set:
+Storage lives under `~/.pi/agent/astral-pocket/`, or under
+`$PI_CODING_AGENT_DIR/astral-pocket/` when set. `notes/` holds canonical Markdown;
+`POCKET.md` is a rebuildable registry and `distilled.json` records extraction
+progress. Legacy summary and digest files are unused. Upgrading does not delete
+existing notes automatically.
 
-```text
-config.json       settings
-notes/            canonical Markdown notes
-digests/          rebuildable per-project and global digest caches
-POCKET.md         rebuildable note registry
-SUMMARY.md        legacy-compatible derived summary surface
-distilled.json    processed source revisions and digest fingerprints
-```
+Files are atomically replaced, and Pi's file mutation queue serializes writes
+inside one process. Concurrent Pi processes can still duplicate extraction work
+or publish competing derived registries; this is not cross-process locking.
+Canonical notes remain accessible when a model request fails.
 
-Canonical note files remain readable if a model call fails or a derived registry
-or digest lags. Changed sessions replace their one stable generated note. If a
-fresh extraction returns `NONE`, that generated note is removed rather than
-leaving superseded knowledge behind. Legacy notes are not rewritten: notes with
-project metadata remain project-scoped, while notes with unknown scope appear
-only in an explicit all-project recall.
-
-There is no daemon or global worker. Work runs only on Astra activation or an
-explicit command. Pi's file mutation queue serializes writes inside one process,
-and files are atomically replaced to avoid torn output. Two simultaneous Pi
-processes can still duplicate model calls or publish competing derived snapshots;
-the extension does not claim cross-process locking. A later rebuild recovers the
-registry and digest from canonical notes.
-
-## Privacy
-
-Session files can contain prompts, tool arguments, and tool results. Distillation
-uses a bounded transcript that omits most tool output and instructs the model to
-exclude credentials, personal data, quoted instructions, rejected proposals,
-and facts already documented in the repository. A prompt cannot guarantee that
-every sensitive value is removed.
-
-Choosing a distiller model sends the bounded source material to that model's
-configured provider. Astral Pocket never falls back to a different provider.
-Use `pocket_recall` without `full` first; larger session excerpts can re-surface
-sensitive text from past work. Use all-project recall only when you intentionally
-want foreign repository precedent.
+Session transcripts can contain prompts, tool arguments, and results. Extraction
+sends a bounded transcript to the configured model provider and asks it to omit
+secrets and personal data. Prompt instructions cannot guarantee redaction.
+Explicit raw-session recall can also surface old preferences or sensitive text;
+those transcripts are evidence, not automatically accepted learnings.
 
 ## Install
 
@@ -134,5 +167,6 @@ want foreign repository precedent.
 pi install npm:@nklisch/pi-enhanced
 ```
 
-Astral Pocket is currently distributed as part of Pi Enhanced rather than as a
-standalone npm package.
+Astral Pocket is distributed inside Pi Enhanced rather than as a standalone npm
+package. Update Pi Enhanced to receive Pocket changes, then reload Pi or start a
+new session to activate the new extension code.

package/node_modules/@nklisch/pi-astral-pocket/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@nklisch/pi-astral-pocket",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
-  "description": "Model-gated note pocket and session recall for gpt-6-astra",
+  "description": "Repository navigation clues and hard-won technical learnings for gpt-6-astra",
   "type": "module",
   "author": {
     "name": "Nathan Klisch"