@seangle/pi-remember 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,14 +1,46 @@
 # Changelog
 
-## 0.2.0
+## 0.3.0
 
-First public release as `@seangle/pi-remember`, licensed under Apache-2.0.
+Breaking replacement of the standalone 0.2.0 implementation, now maintained in
+[Esensats/agents-remember](https://github.com/Esensats/agents-remember).
+The npm name and install command are unchanged.
 
-- Durable workspace-local and global facts, standalone Markdown notes, and lexical search.
-- Stable session context with on-demand note retrieval.
-- Explicit local initialization, memo updates, recoverable deletion and undo.
-- Versioned storage with backed-up migration from the legacy note-reference format.
-- Restore-path validation that refuses redirected recovery files and note directories.
-- Pi package metadata and a source-only npm artifact; no build step.
+### Changed
 
-Existing legacy stores migrate automatically when used. Back up stores, review the README's migration and concurrency limits, and upgrade every writer before using the new format.
+- Shared host-independent `@seangle/remember-core@0.1.0` and explicit
+  `@seangle/remember-migrators@0.1.0` dependencies.
+- Workspace memory defaults to `.agents/memory`, shared with compatible adapters,
+  instead of `.pi/memory`. Global memory remains Pi-owned.
+- Published plain ESM JavaScript instead of runtime TypeScript.
+- Snapshot rebuilt before each run in Pi's named `remember` prompt section;
+  unchanged bytes remain stable and external changes appear on the next run.
+- Environment configuration uses `REMEMBER_*`. In particular,
+  `PI_REMEMBER_DIR` becomes `REMEMBER_GLOBAL_DIR`.
+- New timestamps use minute-precision UTC; existing valid timestamps are retained.
+
+### Migration
+
+- New `memory_migrate` tool and `/memory migrate` command.
+- Migration is explicit, supports recognized legacy version-1 stores, preserves
+  current fact/note IDs and paths, and reports skipped invalid/duplicate content.
+- Local migration leaves the legacy source intact and refuses existing targets.
+- Global legacy stores require explicit in-place migration with source and target
+  set to the global directory.
+- Old recovery history and migration artifacts are not converted. They remain
+  at the source; in-place adoption leaves old files present but does not promise
+  compatibility. Back up stores and stop all writers before migrating.
+- Populated unmarked stores are refused, not silently adopted. Upgrade pre-v1
+  formats with the legacy 0.2.0 implementation first.
+
+### Removed
+
+- Opt-in automatic exit-summary model calls and `PI_REMEMBER_EXIT_SUMMARY*`
+  configuration. `/memory update` remains available for explicit review.
+
+See [README.md](README.md) for upgrade instructions and concurrency limits.
+
+## 0.2.0 and earlier
+
+Standalone implementation and historical changes:
+[Esensats/pi-remember](https://github.com/Esensats/pi-remember).

package/README.md

@@ -1,13 +1,14 @@
-# pi-remember
+# @seangle/pi-remember
 
-Durable memory for [pi](https://pi.dev/): a curated, plain-file knowledge cache that survives sessions. Save knowledge that was **expensive to obtain** and will matter again—decisions, preferences, lessons, environment quirks, research findings—not todos, debugging state, transcripts, or “the user asked me to X.” Pi's session files (`/resume`) already preserve session continuity.
+Durable, plain-file memory for the [Pi coding agent](https://pi.dev/): curated
+facts, Markdown notes, lexical search, stable memo IDs, recovery, and a
+byte-stable session snapshot. Save knowledge that was expensive to obtain and
+will matter again—not transcripts, todos, or temporary debugging state.
 
-| Scope | Store directory | Use for |
-|---|---|---|
-| `local` (default for writes) | `<root>/.pi/memory/` | Knowledge about that workspace, repo, software, server, or configuration |
-| `global` | `~/.pi/agent/memory/` | Facts about the user or machine itself: identity, OS, global tool preferences |
-
-`root` defaults to the session working directory. `PI_REMEMBER_DIR` overrides the global directory. Specific software/configuration knowledge belongs in its workspace even when the software is installed machine-wide.
+This is the Pi adapter for
+[agents-remember](https://github.com/Esensats/agents-remember). Starting with
+**0.3.0**, it replaces the standalone implementation while retaining the same
+npm package name. The unscoped `pi-remember` package is unrelated.
 
 ## Install
 
@@ -15,250 +16,175 @@ Durable memory for [pi](https://pi.dev/): a curated, plain-file knowledge cache
 pi install npm:@seangle/pi-remember
 ```
 
-Restart Pi (or use `/reload` in an existing session) after installation. Use `/memory` for help and ask Pi to remember a durable fact to get started. Local writes require explicit initialization with the `memory_init` tool; global memory needs no initialization.
-
-Requires Node.js **22.15 or newer**. Tested with Pi **1.4.0** (`@earendil-works/pi-coding-agent`); older Pi versions or other forks may not provide the host APIs this extension uses. Pi loads the TypeScript source directly; no build step or external service is needed.
-
-**Upgrading from a manually installed copy:** remove or move the old extension directory out of `~/.pi/agent/extensions/` before loading the npm package, so the same tools are not registered twice. Keep your memory stores; they live separately from the extension. Review the migration section below before upgrading existing stores.
-
-Source and issues: [Esensats/pi-remember](https://github.com/Esensats/pi-remember). The npm package is **`@seangle/pi-remember`**, not the unrelated unscoped `pi-remember` package.
-
-## Architecture and file format
-
-There is **no database, daemon, embedding service, or durable duplicate index**. Facts live in `MEMORY.md`; detailed notes are standalone Markdown files whose frontmatter is authoritative. A note catalogue is derived from those files when needed, never saved back into `MEMORY.md`.
-
-Each store can contain:
-
-| Path | Contents |
-|---|---|
-| `MEMORY.md` | One-line facts and their metadata comments; not note references |
-| `notes/<YYYY-MM-DD>-<slug>.md` | Standalone notes with YAML frontmatter and a Markdown body |
-| `pi-remember.json` | Store format marker: `{"version": 1}` |
-| `recovery/<recovery ID>.json` | Recoverable deletions and updates, including note snapshots |
-| `migrations/v0-to-v1-<uuid>/` | Original-file backups and a manifest from each migration attempt |
-
-Directories for notes and recovery are created only as needed. An absent store is not created merely by startup or migration checks.
-
-### Facts
-
-A fact is one line, at most 300 characters, with an eight-hex memo ID and a creation timestamp in the preceding HTML comment:
-
-```markdown
-<!-- 2026-10-18T16:10:33Z [a1b2c3d4] -->
-#lesson Use the workspace's own virtual environment.
-```
-
-**Facts currently have no last-modified date.** Updating a fact retains its ID and creation comment. Tags (`#lesson`) and wiki-links (`[[topic]]`) are optional text conventions, not required schema. Existing facts without IDs remain readable, but cannot be targeted by the ID-based update tool.
-
-### Notes
+Restart Pi or run `/reload`. Requires Node.js **>=22.15** and Pi host APIs tested
+with **`@earendil-works/pi-coding-agent@1.4.0`**. Published code is compiled ESM
+JavaScript; users do not need a build step. Host SDK packages are peer dependencies
+provided by Pi, not bundled copies.
 
-```markdown
----
-description: "Python environment conventions"
-memory-id: "e5f6a7b8"
-created-date: "2026-10-18T16:10:33.000Z"
-last-modified-date: "2026-10-18T16:10:33.000Z"
----
-# Optional body heading
+If you already install this npm package, use:
 
-Confirmed details, rationale, and examples go here.
+```sh
+pi update npm:@seangle/pi-remember
 ```
 
-The four frontmatter fields are **`description`, `memory-id`, `created-date`, and `last-modified-date`**. The description is the short catalogue text; it is not a body heading. IDs identify memos independently of their paths.
-
-`memory_store` retains the parameter name **`title` for backwards compatibility**, but it now means **description**. New descriptions must be nonempty, single-line, and at most 300 characters. Pass Markdown body text as `content`, **without frontmatter**. No H1 is generated; include your own heading in the body if useful.
-
-Choose an optional `slug` of 1–80 letters/digits separated by hyphens, **without a date, path, or extension**. The filename always receives the UTC creation date and `.md`: `notes/2026-10-18-python-environments.md`. Omitting `slug` uses a description-derived slug for older callers. Filename collisions receive numbered suffixes rather than overwriting files.
-
-The parser deliberately supports a **small scalar YAML subset**, not arbitrary YAML:
-
-- Exactly the four known fields, each once; blank lines and comments are allowed.
-- Plain scalars, single-quoted scalars (doubled apostrophes), or double-quoted scalars with JSON-compatible escapes. Quote ambiguous values.
-- No nested structures, lists, multiline values, tags, anchors, aliases, unknown fields, or duplicate fields.
-- A nonempty single-line description, an eight-hex ID, and valid ISO timestamps with time zones are required.
-- The header, including delimiters, must fit within **16 KiB of UTF-8**. Metadata discovery reads in 512-byte chunks and stops at the closing delimiter, with a hard cap of 16 KiB plus one lookahead byte, rather than loading large note bodies.
-
-A file beginning with a frontmatter delimiter but containing an invalid, incomplete, or oversized header is an error, not a legacy-note fallback. Invalid notes can make catalogue operations fail; optional session injection omits the affected scope instead of breaking the session. Ordinary text without frontmatter is treated as legacy input during migration.
-
-## Session context and retrieval
-
-At session start, pi-remember builds a snapshot containing facts plus a **frontmatter-only derived note catalogue**: description, memo ID, creation date, last-modified date, and path. Catalogue references may look like `#note [[notes/...]] Description`, but these are generated views, not persistent `MEMORY.md` entries. **Note bodies are not injected**; retrieve them explicitly by ID/path or search them on demand.
+A pinned version stays pinned; change its installation specification to upgrade.
+Remove any manually installed or local-path copy first so two extensions do not
+register the same `memory_*` tools. Keep memory stores: they live separately.
+**Read the migration section before upgrading from 0.2.x.**
 
-The snapshot is byte-stable between turns: `before_agent_start` appends the saved block without rereading files or making model calls. Writes/deletions and successful updates/restores to global or current-workspace memory rebuild it; another workspace's local changes do not replace the session's injected local memory. External file edits are not watched—start a fresh session to reliably pick them up.
+## Stores and context
 
-Each scope has a default **3,000-character snapshot budget**. Oversized content keeps roughly the first 20% and last 80%, replacing the middle with a truncation notice. These are character budgets, not token/byte limits or strict final-output ceilings: the notice, scope headings, and enclosing instructions add overhead. The snapshot can omit entries or cut through an entry; read/search the store before making decisions based on it.
-
-### Search
-
-`memory_search` builds a **query-local BM25F-like lexical ranking** over facts and notes. No embeddings, vector database, persistent search index, or model call is involved.
+| Scope | Default path |
+|---|---|
+| Local | `<workspace>/.agents/memory`—shared with compatible agent adapters |
+| Global | `~/.pi/agent/memory`—Pi-owned |
 
-- Unicode-normalized, case-insensitive **exact tokens**, not substring matches; common English stopwords and tokens shorter than two characters are omitted.
-- Field weighting favors descriptions and tags/wiki-links; term-frequency saturation and length normalization limit repetition bias.
-- Query coverage and contiguous phrase matches boost ranking. Quotes request a phrase boost, **not a mandatory phrase filter**.
-- A note's description and body form one document, producing **one hit and one matching-passage snippet per note**, with scope/path/ID and an additional matching-line count where applicable.
-- Managed frontmatter and HTML comments are excluded from searchable body text. Dates and IDs are metadata, not body keywords; use exact-ID reads for identity lookup.
-- Up to 20 results are returned. Search reads bodies on demand; injection/catalogue discovery does not.
+Facts live in `MEMORY.md`; notes live in `notes/<date>-<slug>.md` with validated
+`description`, `memory-id`, `created-date`, and `last-modified-date` frontmatter.
+The `remember.json` marker records store format version 1. Updates and deletions
+produce recovery records for conflict-aware undo.
 
-For a simple substring filter over fact/catalogue lines and metadata, use `memory_read({query})` instead.
+Facts and a derived note catalogue enter the named `remember` system-prompt
+section. Note bodies remain on disk until read or searched. The snapshot is
+rebuilt before each run; Pi patches the transcript only when its bytes change.
+Each scope has a default 3,000-character budget, with middle truncation for large
+stores. Read/search before assuming the snapshot is complete.
 
-## Tools
+Memory is agent-writable background data, **not trusted instructions**. Do not
+store secrets. Add `.agents/memory/` to a workspace's `.gitignore` if memory should
+remain private; recovery records can contain removed information too.
 
-Every tool accepts optional `root`; it selects only local memory. Scope defaults differ intentionally:
+## Tools and command
 
-| Tool | Parameters / behavior | Default scope |
+| Tool | Purpose | Default scope |
 |---|---|---|
-| `memory_init` | `{root?}`: explicitly initialize local memory in an existing workspace; preserve existing contents | local only |
-| `memory_write` | `{content, scope?, root?}`: append one fact (≤300 chars) | `local` |
-| `memory_store` | `{title, content, slug?, scope?, root?}`: create a standalone frontmatter note; `title` means description | `local` |
-| `memory_read` | `{id?, query?, path?, scope?, root?}`: facts + derived catalogue, substring filter, exact memo lookup, or file read | `both` |
-| `memory_search` | `{query, scope?, root?}`: ranked fact/note search with snippets | `both` |
-| `memory_update` | `{id, content, scope?, root?}`: revise one existing memo in place; return recovery ID on change | `local` |
-| `memory_forget` | `{text, scope?, root?}`: case-insensitive substring deletion by fact text or note description/path/identity metadata, **not note body** | `local` |
-| `memory_restore` | `{recoveryId, scope?, root?}`: undo a deletion or update | `both` |
-| `memory_status` | `{root?}`: store paths, counts, fact-file sizes, recoveries, and current session snapshot size | both stores |
-
-New writes use normalized-text duplicate checks against facts and the derived catalogue. Duplicate note storage returns existing references **without creating or overwriting a note**; read and update the existing memo instead. Similar entries in the other scope can produce non-blocking warnings. These are text heuristics, not semantic deduplication or a body-comparison service.
-
-Read/search outputs are bounded: catalogue/search output uses 20,000-byte / 400-line limits; note/ID reads use 30,000-byte / 600-line limits. Truncation keeps the tail and is reported. For a larger file, use pi's ordinary file-reading tools with offsets.
-
-## Workspaces, initialization, and security
-
-`root` is the **workspace directory containing `.pi`**, not `.pi` or the memory directory. Absolute paths, `~/` paths, and paths relative to the session cwd are accepted. The workspace must already exist; tools never create it. Symlinked workspace roots are canonicalized, and local access is rechecked after mutation-queue waits to avoid following a replaced root.
-
-Roots are **per call**: accessing another workspace does not change subsequent default calls or the session's injected local memory. Global-only calls ignore `root` entirely and do not depend on local initialization. `scope: 'both'` combines global memory with the selected workspace's local store; it does not search every workspace.
-
-Before using a local store, call `memory_init({root})` **only when you intend to create memory there**:
-
-- It exclusively creates an empty `.pi/memory/MEMORY.md` if missing, never truncates existing memory, and never recreates a vanished workspace. Notes/recovery directories stay lazy; format setup may create version/migration files.
-- An existing regular `MEMORY.md` already satisfies initialization; legacy data still needs the automatic format migration described below.
-- Local tools, including reads/searches and default `both` calls, fail with an initialization instruction if `MEMORY.md` is missing. A notes-only local store still requires that file.
-- `memory_status({root})` is the diagnostic exception: it works before initialization and never creates files or migrates the selected store. Its snapshot counts always describe the **current session**, not the selected root. Note counts include recursively discovered valid frontmatter notes. A note-only global store is reported even without a facts file.
-- Global memory needs no explicit initialization. Use `scope: 'global'` from an uninitialized workspace rather than creating unwanted local memory just to make a search succeed.
-
-Example tool calls from a session in another directory:
+| `memory_init` | Explicitly initialize local memory in an existing workspace | local |
+| `memory_write` | Append one durable fact, at most 300 characters | local |
+| `memory_store` | Store a Markdown note; `title` means its short description | local |
+| `memory_read` | Read facts/catalogue, filter, or fetch a memo by ID/path | both |
+| `memory_search` | Ranked lexical search over facts and note bodies | both |
+| `memory_update` | Replace one memo's content, preserving identity and path | local |
+| `memory_forget` | Recoverably remove matches by text/description/path/metadata | local |
+| `memory_restore` | Undo a deletion or update with its recovery ID | both |
+| `memory_status` | Inspect paths, counts, configuration, and snapshot size | both |
+| `memory_migrate` | Explicitly migrate a supported legacy store | explicit paths or local defaults |
+
+Local reads and writes require an initialized store. Global memory needs no
+explicit initialization. Optional `root` selects another existing workspace's
+local memory for that call; it does not change the session workspace or global
+memory. A memo ID identifies knowledge; a recovery ID identifies an undo record.
+Read before updating and preserve unrelated content.
+
+Search is lexical, with exact tokens, field weighting, phrase/coverage boosts,
+and one hit per note. No embeddings, database, model calls, or persistent search
+index are involved. Tool output is bounded and truncation is reported.
+
+- `/memory` or `/memory status`: show status without starting an agent turn.
+- `/memory migrate`: migrate the current workspace's recognized legacy store.
+- `/memory update`: ask the current agent to review durable knowledge, using a
+  follow-up turn rather than interrupting ongoing work. This can incur normal
+  model usage; it is not an automatic exit summarizer.
+
+## Upgrading from 0.2.x
+
+**0.3.0 is a breaking release.** The extension keeps its npm name but now uses
+shared core/migrator packages and a different local-store location.
+
+1. Back up important stores and stop other memory writers.
+2. Upgrade the extension and rename any configured environment variables below.
+3. For each workspace, inspect `memory_migrate({dryRun: true})`. With user
+   approval, run `/memory migrate` or `memory_migrate({})`.
+4. Review skipped files/warnings and verify facts/notes before relying on the new
+   store. Do not delete the source just because migration completed.
+
+The supported source is a legacy **version-1** store with `pi-remember.json`.
+If you still have an older/unmarked legacy format, first upgrade it with the
+legacy 0.2.0 extension. The new adapter does not silently adopt populated,
+unmarked stores or automatically convert old formats on reads.
+
+### Workspace memory
+
+Migration copies current facts and valid notes from `.pi/memory` to
+`.agents/memory`, preserving memo IDs and note paths and leaving the source
+intact. Invalid notes and duplicate IDs are skipped and reported. Existing
+target stores are refused, not merged.
+
+**Recovery history and old migration backups are not copied.** Keep the source
+if you need them. Do not mix old and new writers: the separate local stores will
+diverge, and legacy writers do not understand the new format marker.
+
+### Global memory
+
+The global path stays `~/.pi/agent/memory`, but an existing legacy store still
+needs an explicit, one-time in-place migration. `/memory migrate` handles local
+memory, not global memory. Use explicit tool arguments (adjust paths if configured):
 
 ```js
-memory_status({root: '~/homelab'})
-memory_init({root: '~/homelab'}) // only if you intend to create its local store
-memory_search({root: '~/homelab', scope: 'local', query: 'TV server'})
-memory_store({
-  root: '~/homelab',
-  title: 'TV server configuration', // stored as description
-  slug: 'tv-server',
-  content: '# TV server\n\nConfirmed durable details…',
+memory_migrate({
+  source: '~/.pi/agent/memory',
+  target: '~/.pi/agent/memory',
+  dryRun: true,
+})
+// Only after approval and reviewing the plan:
+memory_migrate({
+  source: '~/.pi/agent/memory',
+  target: '~/.pi/agent/memory',
 })
-memory_read({root: '~/homelab', scope: 'local', id: 'e5f6a7b8'}) // use returned ID
-memory_update({root: '~/homelab', id: 'e5f6a7b8', content: '# TV server\n\nFull revised body…'})
-memory_restore({root: '~/homelab', scope: 'local', recoveryId: '<returned recovery ID>'})
 ```
 
-Safe explicit path resolution rejects traversal/out-of-scope files and symlinks escaping a store. Catalogue discovery skips symlink aliases, and note/recovery writes refuse redirected subdirectories. Migration refuses symlinks within its input paths, including internal aliases. These checks are not a sandbox against hostile concurrent filesystem changes. Memory tools operate on local files with pi's permissions: `root` is not an SSH destination, and stored knowledge never grants remote-access permission. Do not store secrets or credentials.
-
-## IDs, updates, deletion, and undo
-
-A **memo ID** is eight hexadecimal characters, stored in a fact's metadata comment or a note's `memory-id`. A **recovery ID** identifies an undo record, not a memo. Use memo IDs with `memory_read`/`memory_update`, recovery IDs with `memory_restore`.
-
-- `memory_read({id})` returns exactly one memo, including the complete stored note text subject to output limits. Do not combine `id` with `query` or `path`.
-- IDs or relative paths present in both scopes are ambiguous with `scope: 'both'`; select `local` or `global`. Duplicate IDs within one scope require manual resolution, not a guessed match.
-- `memory_update` requires a prior read. For facts, pass the replacement single line (≤300 chars); for notes, pass the **full revised body without frontmatter**, including any body heading you want to retain. Preserve unrelated/correct details.
-- A note update preserves description, ID, creation date, and path; **`last-modified-date` advances only on an actual body change**. Fact updates do not add a modified date. Blank content is rejected; normalized/trim-equivalent no-ops leave bytes, timestamps, and recovery state untouched.
-- Actual updates save recovery data before replacing the file. Targeted fact updates preserve unrelated bytes; file replacements are atomic and retain permissions. Extension mutations use pi's file-mutation queues. Note updates/undo use the note-file queue; deletion holds all selected note queues before snapshotting and removing them. New notes and recovery records are published atomically without overwriting existing paths.
-- `memory_forget` saves matching entries and full note snapshots before removing them, including the note files themselves. For notes, the generated identity metadata used for matching contains the ID and creation date, **not the last-modified date**. Use a specific ID/path/description to avoid broad deletions.
-- `memory_restore` must use the **same root** as the original change. It searches only the selected stores. Ambiguous recovery IDs, existing recovered paths/IDs, missing targets, and later edits cause refusal; conflicting recovery records are retained.
-- Update undo checks the memo's identity and exact saved “after” content before restoring “before.” Note undo restores the **snapshot's metadata too**, including its previous last-modified date; it does not stamp the undo time. Successful undo consumes its recovery record. Deletion undo restores saved facts/notes without creating persistent note references and retains saved note permissions. Newly created notes/recovery records default to owner-only access (`0600`); new note/recovery directories use `0700`.
-
-## Format versions and automatic migration
-
-`pi-remember.json` inside each store records **format version 1**. An absent marker (or version `0`) means legacy format: note references were persisted in `MEMORY.md`, and generated notes could have a timestamp comment plus an automatic H1.
-
-Migration runs automatically:
-
-- At session startup for existing global and current-workspace stores.
-- Lazily before ordinary reads/searches or mutations of another workspace; restore prepares its selected recovery store before changing it.
-- Around initialization/first writes to establish the version of a newly created store. Missing stores are never created by migration itself.
-
-**A read/search can therefore write migration data.** Status inspection does not migrate. Startup migration failures warn when UI is available and omit that scope from injection; explicit operations surface the error. Invalid or future versions are refused rather than guessed or overwritten, and version checks are repeated rather than permanently cached.
-
-Migration validates its entire conversion plan before making backups or changing memory data. Each attempt creates **`migrations/v0-to-v1-<uuid>/`** containing a manifest (including modes, timestamps, and inference rules) and read-only, byte-for-byte backups of **all affected originals before any original is mutated**. Backups are retained even after success or a partial failure. The version marker is committed last; interrupted work can be retried with a new backup set. This is not a single multi-file transaction or an automatic rollback mechanism.
-
-Conversion preserves existing memo IDs, note paths, fact bytes, unrelated index bytes, and file modes. It removes persisted note references and their managed comments from `MEMORY.md`, moving identity/description/dates into notes. Only the recognized generated legacy timestamp marker and its immediate generated H1/blank line are stripped; user-authored body headings remain. Existing valid frontmatter is retained. Unindexed legacy notes become discoverable standalone notes and receive IDs if needed.
-
-Legacy notes had no recorded modified date: migration infers it from the original file's filesystem mtime. Creation comes from existing index/generated metadata where available, otherwise from mtime. These are documented inferences, not reconstructed edit history.
-
-Recovery records migrate too, including old deletion records and whole-note update snapshots. **Forgotten notes are not resurrected**: legacy files left behind after deletion are snapshotted into recovery and removed from the active store. Recovery conversion happens before note/index edits so retries can retain identities and conflict checks. Malformed records, unsafe/dangling references, duplicate IDs, or conflicting metadata halt migration rather than silently dropping data.
+A recognized in-place store receives only `remember.json`; its existing files
+are left in place. Old recovery files are not converted or guaranteed compatible
+with the new engine. Do not use the old extension against this store afterward.
 
-### Concurrency and compatibility limits
+### Other changes
 
-In-process migration calls for the same canonical store share one run. An exclusively created **`.pi-remember-migration.lock`** serializes migrators across processes; existing locks cause a clear refusal, are never stolen, and require manual inspection if left after a crash. Backups are followed by a source-change check before applying the plan.
+- `PI_REMEMBER_DIR` becomes `REMEMBER_GLOBAL_DIR`.
+- `PI_REMEMBER_INJECT_CHARS_GLOBAL` and `_LOCAL` become
+  `REMEMBER_INJECT_CHARS_GLOBAL` and `_LOCAL`.
+- The old opt-in `PI_REMEMBER_EXIT_SUMMARY*` feature is **not included**. Use
+  `/memory update` for an explicit review instead.
+- New timestamps use UTC minute precision; existing valid timestamps remain
+  readable and are preserved.
 
-The migration lock is **not a general cross-process writer lock**. Pi's ordinary file-mutation queues coordinate cooperating operations within the host process, not other pi instances, editors, sync tools, or old binaries. Avoid concurrent writers during migration; a lock cannot make uncooperative writers safe.
+## Configuration
 
-**Old binaries are not safe to use against a migrated store. There is no backward-writer support or dual-format index.** Upgrade every writer; do not downgrade by deleting the version marker. New code refuses future versions, but old code may not understand the marker at all. Preserve the migration backups before any manual recovery or downgrade work.
-
-## Commands
-
-- **`/memory`** shows status in a notification, without starting an agent turn.
-- **`/memory update`** sends an incremental memory-review reminder to the **current session's agent**. When idle it starts a normal turn; when busy it queues a **follow-up**, not an interruption. It uses the available conversation context (including compaction summaries) and normal tools, not a separate summarizer or bulk rewrite. Unknown arguments show usage; `update` is offered in completion.
-
-The reminder asks the agent to read/search relevant memory, add missed durable knowledge, correct confirmed errors with `memory_update`, and recoverably remove obsolete entries. It preserves unrelated/correct knowledge, treats age alone as insufficient evidence, avoids secrets/task state, and permits no changes when nothing useful needs saving. The agent briefly reports its changes or that none were needed. **The command does not authorize remote actions or carry prior remote permission forward.** Reload extension changes with `/reload`.
-
-## Configuration and opt-in exit summary
-
-| Environment variable | Default | Purpose |
-|---|---|---|
-| `PI_REMEMBER_DIR` | `~/.pi/agent/memory` | Global store directory |
-| `PI_REMEMBER_INJECT_CHARS_GLOBAL` | `3000` | Global snapshot character budget, plus truncation/wrapper overhead |
-| `PI_REMEMBER_INJECT_CHARS_LOCAL` | `3000` | Local snapshot character budget, plus truncation/wrapper overhead |
-| `PI_REMEMBER_EXIT_SUMMARY` | off | Enable with `1`, `true`, `yes`, or `on` (case-insensitive) |
-| `PI_REMEMBER_EXIT_SUMMARY_MODEL` | session model | Optional `provider/model-id` (or model ID); unavailable selection falls back to the session model |
-| `PI_REMEMBER_EXIT_SUMMARY_SCOPE` | `auto` | `global`, `local`, or `auto`: local if the session workdir has `.pi`, otherwise global |
-| `PI_REMEMBER_EXIT_SUMMARY_TIMEOUT_MS` | `10000` | Timeout for waiting on the summary model response |
-
-Character budgets and timeout must parse as positive integers; invalid/nonpositive values use defaults. Zero does not disable injection. Configuration is loaded when the extension loads; reload/restart after changing it.
-
-Exit summarization runs only on session shutdown with reason **`quit`**, when opted in. It sends up to the last 20,000 characters of user/assistant text from the current session branch to the selected model, asks for at most six concise durable fact lines (or `NONE`), filters the response, and appends accepted facts with normal duplicate checks. It is a model call that may incur cost and send conversation text to that provider—not purely local processing. No cheap model is automatically selected; choose one explicitly if desired.
-
-A selected but uninitialized local store is **skipped**, not created and not redirected to global. Too little conversation text, missing model/authentication, errors, and timeouts are best-effort skips. The timeout stops waiting for the response; it does **not** cancel the underlying provider request. This opt-in extractor is separate from `/memory update` and does not perform its targeted review/correction workflow.
-
-## Git and development
+| Variable | Default |
+|---|---|
+| `REMEMBER_DIR_NAME` | `.agents` (workspace configuration directory, not a store path) |
+| `REMEMBER_GLOBAL_DIR` | `~/.pi/agent/memory` |
+| `REMEMBER_INJECT_CHARS_GLOBAL` | `3000` |
+| `REMEMBER_INJECT_CHARS_LOCAL` | `3000` |
+| `REMEMBER_AUTO_INJECT` | `1` |
 
-To keep workspace memory private, add this to the project's `.gitignore`:
+Budgets must be positive integers; invalid/nonpositive values fall back to the
+default. Set `REMEMBER_AUTO_INJECT=0` to disable injection, not the tools.
+Configuration loads when the extension loads; restart or `/reload` after changes.
 
-```gitignore
-.pi/memory/
-```
+## Concurrency and safety
 
-Committing memory shares it with the team. Review not just facts/notes but **recovery snapshots and migration backups**, which may retain removed information. Files are plain Markdown/JSON and can be reviewed in git; concurrent merges still require care with unique IDs and metadata.
+Pi's mutation queues serialize cooperating operations within one process, not
+across Pi/DSH processes or editors. Avoid simultaneous writes to a shared store,
+including during migration. Path checks are not a sandbox against hostile
+concurrent filesystem changes. Stored paths, credentials, or remembered facts
+never grant permission for remote access.
 
-No build step: pi loads TypeScript via jiti. There are no declared npm dependencies; host imports (`pi`, TypeBox, and TUI) are supplied by pi. For a one-off load, use `pi --extension ./index.ts` from this directory.
+## Local development
 
 ```sh
-git clone git@github.com:Esensats/pi-remember.git
-cd pi-remember
-npm test
-# node --experimental-strip-types --test "test/*.test.ts"
+git clone git@github.com:Esensats/agents-remember.git
+cd agents-remember
+pnpm install
+npm run check
+npm run test:packed
+pi install ./packages/pi
 ```
 
-Use **Node >=22.15**: tests execute TypeScript directly with Node's experimental type stripping, and integration stubs use `module.registerHooks`. No separate TypeScript build or test runner is required. The tests use temporary fixture stores rather than live memory.
-
-Source responsibilities:
-
-| Module | Responsibility |
-|---|---|
-| `store.ts` | Facts, standalone note storage/discovery, derived catalogue, IDs, updates, deletion/recovery, safe path lookup |
-| `notes.ts` | Bounded frontmatter parsing/serialization and legacy generated-header handling |
-| `migration.ts` | Version guards, validation/planning, backups, migration lock, conversion of notes and recovery records |
-| `workspace.ts` | Existing-root resolution, explicit initialization, local-access guards |
-| `search.ts` | Query-local lexical ranking and passage selection |
-| `inject.ts` | Stable snapshot construction and middle truncation |
-| `summary.ts` | Exit-summary text extraction, prompt, and response filtering |
-| `command.ts` | `/memory` routing and incremental-review reminder (type-only pi import) |
-| `index.ts` | Host integration: lifecycle, tools, queues, configuration, snapshot refresh, exit-summary model call |
-
-Core modules have no pi runtime imports and are tested with plain Node; command behavior uses a stub API, and extension wiring tests stub host imports with Node module hooks.
+Remove an existing npm installation before installing the local path. Local
+packages load in place; rebuild with `npm run build` and run `/reload` after edits.
+Tests use temporary stores, not live memory. `test:packed` additionally installs
+only release tarballs outside the monorepo and reruns the adapter integration
+suite against emitted JavaScript.
 
 ## License
 
-Copyright 2026 Esensats.
-
-Licensed under the [Apache License, Version 2.0](LICENSE). Contributions are accepted under the same license.
+Apache-2.0. Copyright 2026 Esensats.

package/dist/command.js

@@ -0,0 +1,56 @@
+                                                                                             
+
+/**
+ * Incremental review prompt, kept from pi-remember so `/memory update` behaves
+ * the same. It asks for evidence-based edits, not a rewrite of the collection.
+ */
+export const MEMORY_UPDATE_PROMPT = `Please review durable memory in light of this conversation and update it only where needed. This is an incremental memory reminder, not a request to overhaul or rewrite the memory collection.
+
+- Use the available conversation context (including any compaction summary) to identify durable knowledge that will help in future sessions: established decisions, preferences, hard-won lessons, and confirmed project/server setup or operational details. Save important knowledge you have not already saved.
+- Read the current memory with memory_read and use memory_search for relevant topics; read related notes as needed before changing anything. The injected snapshot may be incomplete. Avoid duplicates and preserve unrelated or still-correct information. Do not scan or rewrite every note just for completeness.
+- Correct or remove information only when this conversation provides evidence that it is outdated or wrong; age alone or not mentioning it is not evidence. Make the smallest targeted changes. Use memory_forget with a specific identifying string for obsolete facts or notes (deletions are recoverable), memory_write for one-line facts, and memory_store for new detailed notes. For memos with IDs, read by ID and use memory_update to edit the relevant file in place instead of forgetting/recreating facts or creating redundant replacement notes; preserve identity, description and unrelated content. Notes carry their own frontmatter; supply only the revised Markdown body, including any body heading worth keeping. Store migration is automatic; do not manually recreate an index.
+- Default to local memory in the current workdir (a shared .agents/memory store that other harnesses may read too), including server-specific knowledge when working in a context directory such as ~/ctx/server-ABC. When the user requests memory in another workspace, use its root on each tool call, including reads and recovery; root is the workspace directory, not its .agents directory. Use memory_status to inspect a store before initialization, and memory_init only when you intend to create local memory in that existing directory; do not initialize a workspace merely to make a search succeed. Global memory is only for user/machine-wide facts, not particular servers, software, repos, or configs. Keep MEMORY.md for one-line facts only; put detailed knowledge in standalone notes with concise descriptions and chosen filename slugs. The date is prepended automatically; descriptions are injected from frontmatter, not duplicated in MEMORY.md.
+- Do not store secrets, credentials, temporary task state, todos, or a transcript/session recap. Work from already available evidence; this command does not authorize remote access or imply that past remote-access permission carries into future sessions.
+- If nothing useful needs changing, leave memory untouched. Briefly report what you added, corrected, or removed, or say that no updates were needed.`;
+
+                                       
+                                                        
+                                                         
+ 
+
+const COMPLETIONS = [
+  { value: "status", label: "status", description: "Show memory store locations, counts, and snapshot size" },
+  { value: "migrate", label: "migrate", description: "Migrate a legacy .pi/memory store into the shared store" },
+  { value: "update", label: "update", description: "Review this conversation and update memory only if needed" },
+];
+
+export function registerMemoryCommand(
+  pi                                                           ,
+  actions                      ,
+)       {
+  pi.registerCommand("memory", {
+    description: "Show memory status, migrate a legacy store, or review and update memory",
+    getArgumentCompletions: (prefix) => {
+      const value = prefix.trim().toLowerCase();
+      const matches = COMPLETIONS.filter((item) => item.value.startsWith(value));
+      return matches.length > 0 ? matches : null;
+    },
+    handler: async (args, ctx) => {
+      const subcommand = args.trim().toLowerCase();
+      if (subcommand === "update") {
+        // Start a normal turn when idle; otherwise wait for the ongoing work.
+        pi.sendUserMessage(MEMORY_UPDATE_PROMPT, { deliverAs: "followUp" });
+        return;
+      }
+      if (subcommand === "migrate") {
+        ctx.ui.notify(await actions.migrate(ctx), "info");
+        return;
+      }
+      if (subcommand === "" || subcommand === "status") {
+        ctx.ui.notify(await actions.status(ctx), "info");
+        return;
+      }
+      ctx.ui.notify("Usage: /memory [status|migrate|update]", "warning");
+    },
+  });
+}

package/dist/context.js

@@ -0,0 +1,57 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { resolveStores,                             } from "@seangle/remember-core";
+
+/**
+ * Deployment policy for the Pi adapter.
+ *
+ * The workspace store is shared with the DeepSeek Harness (`.agents/memory`), so
+ * both harnesses read and write the same facts and notes. The global store stays
+ * in Pi's home: machine-wide memory is harness-owned, not a shared file.
+ */
+                                 
+                  
+                    
+                            
+                           
+                      
+ 
+
+function truthy(value                    )          {
+  return value !== undefined && ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
+}
+
+function intEnv(env                   , name        , fallback        )         {
+  const raw = env[name]?.trim();
+  if (!raw) return fallback;
+  const value = Number.parseInt(raw, 10);
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+/** Expand a leading `~`; core's workspace resolver does the same for `root`. */
+export function expandHome(input        )         {
+  if (input === "~") return homedir();
+  if (input.startsWith("~/")) return join(homedir(), input.slice(2));
+  return input;
+}
+
+export function loadConfig(env                    = process.env)                 {
+  const globalDir = env.REMEMBER_GLOBAL_DIR?.trim();
+  return {
+    dirName: env.REMEMBER_DIR_NAME?.trim() || ".agents",
+    globalDir: globalDir ? expandHome(globalDir) : join(homedir(), ".pi", "agent", "memory"),
+    injectCharsGlobal: intEnv(env, "REMEMBER_INJECT_CHARS_GLOBAL", 3000),
+    injectCharsLocal: intEnv(env, "REMEMBER_INJECT_CHARS_LOCAL", 3000),
+    autoInject: env.REMEMBER_AUTO_INJECT === undefined ? true : truthy(env.REMEMBER_AUTO_INJECT),
+  };
+}
+
+/** Resolve both stores for one workspace root; nothing is created by resolution. */
+export function storesFor(cwd        , config                )                            {
+  return resolveStores(cwd, config.globalDir, config.dirName);
+}
+
+/** Default legacy source for a workspace: pi-remember's own layout. */
+export function legacySource(cwd        )         {
+  return join(cwd, ".pi", "memory");
+}