@seangle/pi-remember 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+## 0.3.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.
+
+### Changed
+
+- 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/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,190 @@
-# Temporary Holding Version
+# @seangle/pi-remember
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+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
+
+```sh
+pi install npm:@seangle/pi-remember
+```
+
+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.
+
+If you already install this npm package, use:
+
+```sh
+pi update npm:@seangle/pi-remember
+```
+
+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.**
+
+## Stores and context
+
+| Scope | Default path |
+|---|---|
+| Local | `<workspace>/.agents/memory`—shared with compatible agent adapters |
+| Global | `~/.pi/agent/memory`—Pi-owned |
+
+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.
+
+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.
+
+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.
+
+## Tools and command
+
+| Tool | Purpose | Default scope |
+|---|---|---|
+| `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_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',
+})
+```
+
+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.
+
+### Other changes
+
+- `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.
+
+## Configuration
+
+| 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` |
+
+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.
+
+## Concurrency and safety
+
+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.
+
+## Local development
+
+```sh
+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
+```
+
+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
+
+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");
+}

package/dist/index.js

@@ -0,0 +1,124 @@
+import { basename } from "node:path";
+                                                                    
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { ensureStoreVersion, readStoreVersion } from "@seangle/remember-core";
+import { migrate } from "@seangle/remember-migrators";
+import { registerMemoryCommand } from "./command.js";
+import { loadConfig, storesFor,                     } from "./context.js";
+import { detectForWorkspace, formatReport, snapshotFor, statusText, toolSpecs } from "./tools.js";
+
+/** System-prompt section name; Pi wraps it in a matching <remember> tag. */
+const SNAPSHOT_SECTION = "remember";
+
+/**
+ * Offer a migration once per workspace and session when a legacy store exists
+ * and the target is not initialized. The model asks the user; nothing is
+ * written without consent.
+ */
+async function migrationNotice(cwd        , config                )                  {
+  try {
+    const detection = await detectForWorkspace(cwd, config);
+    if (!detection) return "";
+    const targetVersion = await readStoreVersion({ dir: detection.target });
+    if (targetVersion !== null) return "";
+    const where = detection.source === detection.target
+      ? `at ${detection.source}, which is missing only remember.json`
+      : `at ${detection.source}; no remember store exists at ${detection.target}`;
+    return `<remember-migration>\nLegacy memory detected: ${detection.description} ${where}.\nAsk the user whether to migrate. If they agree, call memory_migrate (dryRun first if unsure). If they decline, continue without it and do not ask again this session.\n</remember-migration>`;
+  } catch {
+    // Detection is advisory; never block injection on it.
+    return "";
+  }
+}
+
+/**
+ * Mount the memory engine: ten model-facing tools, a `/memory` command, and one
+ * system-prompt section rebuilt at each run start. Pi patches the section only
+ * when its bytes change, so the snapshot stays cache-stable between runs.
+ */
+export default function (pi              ) {
+  const config = loadConfig();
+  let noticeWorkspace                = null;
+
+  pi.on("session_start", async (_event, ctx) => {
+    noticeWorkspace = null;
+    // Adopt a store that already exists without a marker (e.g. a copied tree),
+    // and surface an invalid version instead of injecting nothing silently.
+    const stores = storesFor(ctx.cwd, config);
+    for (const scope of ["global", "local"]         ) {
+      try {
+        await withFileMutationQueue(stores[scope].memoryFile, () => ensureStoreVersion(stores[scope]));
+      } catch (error) {
+        if (ctx.hasUI) ctx.ui.notify(`pi-remember: ${scope} memory unavailable: ${String(error)}`, "warning");
+      }
+    }
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    if (!config.autoInject) {
+      delete event.systemPromptOptions.sections[SNAPSHOT_SECTION];
+      return;
+    }
+    const stores = storesFor(ctx.cwd, config);
+    const snapshot = await snapshotFor(stores, config, basename(ctx.cwd));
+
+    let notice = "";
+    if (noticeWorkspace !== ctx.cwd) {
+      notice = await migrationNotice(ctx.cwd, config);
+      if (notice) noticeWorkspace = ctx.cwd;
+    }
+
+    const text = [notice, snapshot.text].filter((part) => part.trim().length > 0).join("\n\n");
+    if (text) event.systemPromptOptions.sections[SNAPSHOT_SECTION] = text;
+    else delete event.systemPromptOptions.sections[SNAPSHOT_SECTION];
+  });
+
+  for (const spec of toolSpecs({ config })) {
+    pi.registerTool({
+      name: spec.name,
+      label: spec.label,
+      description: spec.description,
+      promptSnippet: spec.promptSnippet,
+      promptGuidelines: spec.promptGuidelines,
+      parameters: spec.parameters,
+      async execute(
+        _toolCallId        ,
+        params                         ,
+        signal                         ,
+        _onUpdate         ,
+        toolCtx                 ,
+      ) {
+        try {
+          const result = await (spec.execute                                                                                                                )(
+            params, { cwd: toolCtx.cwd, signal },
+          );
+          return {
+            content: [{ type: "text"         , text: result.text }],
+            details: {},
+            ...(result.isError ? { isError: true } : {}),
+          };
+        } catch (error) {
+          return {
+            content: [{ type: "text"         , text: `remember: ${(error         ).message}` }],
+            details: {},
+            isError: true,
+          };
+        }
+      },
+    });
+  }
+
+  registerMemoryCommand(pi, {
+    status: async (ctx) => statusText(storesFor(ctx.cwd, config), config, ctx.cwd),
+    migrate: async (ctx) => {
+      const detection = await detectForWorkspace(ctx.cwd, config);
+      if (!detection) return `No legacy memory store found for ${ctx.cwd}.`;
+      try {
+        const report = await migrate({ source: detection.source, target: detection.target });
+        return formatReport(report);
+      } catch (error) {
+        return `Migration refused: ${(error         ).message}`;
+      }
+    },
+  });
+}

package/dist/tools.js

@@ -0,0 +1,552 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { truncateTail, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import {
+  appendEntry,
+  assertCurrentStoreVersion,
+  buildSnapshot,
+  entryId,
+  ensureStoreVersion,
+  findSimilar,
+  forgetEntries,
+  initializeMemory,
+  parseEntries,
+  readCatalogue,
+  readMemo,
+  resolveNotePath,
+  resolveWorkspaceStores,
+  restoreEntry,
+  searchStores,
+  statMemory,
+  updateMemo,
+  validNoteSlug,
+  workspaceAccessError,
+  writeNote,
+                   
+             
+                
+                  
+} from "@seangle/remember-core";
+import { detectMigrations, migrate,                      } from "@seangle/remember-migrators";
+import { Type } from "typebox";
+import { expandHome, legacySource, storesFor,                     } from "./context.js";
+
+const READ_CAP = { maxBytes: 20_000, maxLines: 400 };
+const NOTE_CAP = { maxBytes: 30_000, maxLines: 600 };
+const MAX_FACT = 300;
+const MAX_DESCRIPTION = 300;
+
+                           
+              
+                       
+ 
+
+                              
+                         
+ 
+
+                             
+               
+                    
+ 
+
+                                                                                  
+
+const ROOT_PARAMETER = Type.Optional(Type.String({
+  minLength: 1,
+  description: "Workspace directory for local memory (not its .agents directory). Defaults to the session working directory; accepts absolute, relative-to-cwd, and ~/ paths. Ignored for global-only operations.",
+}));
+
+const SCOPE_WRITE = Type.Optional(StringEnum(["local", "global"]         , {
+  description: "local = this workspace; global = user/machine facts. Defaults to local.",
+}));
+
+const SCOPE_READ = Type.Optional(StringEnum(["local", "global", "both"]         , {
+  description: "Which stores to read. Defaults to both.",
+}));
+
+const WORKSPACE_GUIDANCE =
+  " Optional root selects another workspace's local memory; global memory is unchanged. Local memory requires memory_init first.";
+
+function resolveScopes(param                    )          {
+  if (param === "global") return ["global"];
+  if (param === "local") return ["local"];
+  return ["global", "local"];
+}
+
+function formatTruncated(t                                 )         {
+  return t.truncated ? `${t.content}\n[truncated: showing ${t.outputLines}/${t.totalLines} lines]` : t.content;
+}
+
+function formatEntry(entry             )         {
+  const id = entryId(entry);
+  return `${id ? `[id=${id}] ` : ""}${entry.line}`;
+}
+
+function restoreHint(recoveryId        , scope       , root         )         {
+  const args = { recoveryId, scope, ...(scope === "local" && root !== undefined ? { root } : {}) };
+  return `Undo with memory_restore(${JSON.stringify(args)}).`;
+}
+
+function failure(message        )             {
+  return { text: message, isError: true };
+}
+
+/**
+ * Find a legacy store this workspace could migrate. Prefers `.pi/memory`, and
+ * also recognizes an in-place store (a copied tree missing only the marker).
+ */
+export async function detectForWorkspace(cwd        , config                ) {
+  const target = join(cwd, config.dirName, "memory");
+  const source = legacySource(cwd);
+  const candidates = await detectMigrations(source, target);
+  if (candidates.length > 0) return candidates[0];
+  const inPlace = await detectMigrations(target, target);
+  return inPlace[0] ?? null;
+}
+
+export function formatReport(report                                                                                   )         {
+  const lines = [
+    `${report.dryRun ? "Dry run" : "Migrated"} ${report.plan?.inPlace ? "in place" : `from ${report.source} to ${report.target}`}: ${report.facts} fact(s), ${report.notes} note(s).`,
+  ];
+  if (report.wrote.length > 0) lines.push(`Wrote: ${report.wrote.join(", ")}`);
+  if (report.skipped.length > 0) lines.push(`Skipped:\n${report.skipped.map((item) => `- ${item.rel}: ${item.reason}`).join("\n")}`);
+  if (report.warnings.length > 0) lines.push(`Warnings:\n${report.warnings.map((warning) => `- ${warning}`).join("\n")}`);
+  return lines.join("\n");
+}
+
+export async function statusText(stores                           , config                , cwd        )                  {
+  const lines           = [];
+  for (const scope of ["global", "local"]         ) {
+    const stat = await statMemory(stores[scope]);
+    lines.push(stat.exists
+      ? `${scope}: ${stat.path} — ${stat.entries} facts, ${stat.notesCount} notes, ${stat.bytes} bytes, ${stat.recoveryCount} recovery file(s)`
+      : `${scope}: ${stat.path} — no memory yet${scope === "local" ? "; run memory_init first" : ""}`);
+  }
+  const snapshot = await snapshotFor(stores, config, basename(cwd));
+  lines.push(`injected snapshot (current session: ${cwd}): ${snapshot.text.length} chars (global ${snapshot.globalChars}, local ${snapshot.localChars})`);
+  lines.push(`config: dirName=${config.dirName}, autoInject=${config.autoInject ? "on" : "off"}, snapshot budgets global/local ${config.injectCharsGlobal}/${config.injectCharsLocal}`);
+  return lines.join("\n");
+}
+
+/** Build the snapshot from both stores; never throws on a missing or invalid store. */
+export async function snapshotFor(
+  stores                           ,
+  config                ,
+  projectName        ,
+)                    {
+  const read = async (store            ) => {
+    try {
+      await assertCurrentStoreVersion(store);
+      return await readCatalogue(store);
+    } catch {
+      return "";
+    }
+  };
+  const [globalText, localText] = await Promise.all([read(stores.global), read(stores.local)]);
+  return buildSnapshot(globalText, localText, projectName, {
+    maxGlobalChars: config.injectCharsGlobal,
+    maxLocalChars: config.injectCharsLocal,
+    // Pi wraps a named system-prompt section in <remember> itself.
+    wrap: false,
+  });
+}
+
+/** Map the model-facing tools onto the host-agnostic engine. */
+export function toolSpecs(ctx             ) {
+  const queue                = (path, operation) => withFileMutationQueue(path, operation);
+  const memoryDir = join("<workspace>", ctx.config.dirName, "memory");
+
+  /** Resolve stores for one call without changing the session's injected memory. */
+  const targetStores = (root                    , scopes         , exec          ) =>
+    scopes.includes("local")
+      ? resolveWorkspaceStores(exec.cwd, ctx.config.globalDir, ctx.config.dirName, root)
+      : { status: "resolved"         , root: exec.cwd, stores: storesFor(exec.cwd, ctx.config) };
+
+  /** Validate after acquiring the queue, mark a new store, then run the mutation. */
+  const mutate = async    (
+    stores                           ,
+    scope       ,
+    operation                  ,
+    requireInit = true,
+  )                                                                             => {
+    return queue(stores[scope].memoryFile, async () => {
+      const error = workspaceAccessError(stores, [scope], requireInit);
+      if (error) return { status: "error"         , message: error };
+      try {
+        // Mark a brand-new store before the first write, otherwise the
+        // post-write check sees content without a marker and refuses it.
+        await ensureStoreVersion(stores[scope], { create: true });
+      } catch (cause) {
+        return { status: "error"         , message: String(cause) };
+      }
+      const value = await operation();
+      await ensureStoreVersion(stores[scope]);
+      return { status: "ok"         , value };
+    });
+  };
+
+  /** Reads of other workspaces validate and migrate lazily; missing stores stay missing. */
+  const prepareReads = async (stores                           , scopes         )                         => {
+    for (const scope of scopes) {
+      const error = workspaceAccessError(stores, [scope]);
+      if (error) return error;
+      try {
+        await queue(stores[scope].memoryFile, () => assertCurrentStoreVersion(stores[scope]));
+      } catch (cause) {
+        return String(cause);
+      }
+    }
+    return null;
+  };
+
+  /** Similar entries in the other scope of this call, not another workspace. */
+  const similarInOtherScope = async (stores                           , store            , content        ) => {
+    const other = store.scope === "local" ? stores.global : stores.local;
+    try {
+      return findSimilar(parseEntries(await readCatalogue(other)), content);
+    } catch {
+      return [];
+    }
+  };
+
+  const similarWarning = (similar               , scope       )         =>
+    similar.length > 0
+      ? `\nNote: similar entry in ${scope === "local" ? "global" : "local"} memory: ${similar[0].line}\nKeep knowledge in ONE scope — memory_forget the copy that does not belong.`
+      : "";
+
+  return [
+    {
+      name: "memory_init",
+      label: "Memory Init",
+      description:
+        `Explicitly initialize local memory in an existing workspace. Optional root defaults to the session working directory. Creates ${memoryDir}/MEMORY.md only if missing; never overwrites existing memory or creates the workspace itself. Global memory needs no initialization.`,
+      promptSnippet: "Initialize local memory in an existing workspace",
+      promptGuidelines: [
+        "Use root to access local memory in another workspace. Initialize it with memory_init only when you intend to create a memory store there; do not initialize merely to make a search succeed.",
+      ],
+      parameters: Type.Object({ root: ROOT_PARAMETER }),
+      async execute(args                   , exec          )                      {
+        const target = targetStores(args.root, ["local"], exec);
+        if (target.status === "error") return failure(target.message);
+        const store = target.stores.local;
+        const mutation = await mutate(target.stores, "local", () => initializeMemory(store), false);
+        if (mutation.status === "error") return failure(mutation.message);
+        const result = mutation.value;
+        if (result.status === "error") return failure(result.message);
+        return {
+          text: result.status === "initialized"
+            ? `Initialized local memory: ${store.memoryFile}`
+            : `Local memory already initialized: ${store.memoryFile}. Existing content preserved.`,
+        };
+      },
+    },
+    {
+      name: "memory_write",
+      label: "Memory Write",
+      description:
+        `Append exactly ONE concise, durable fact to memory. Default scope 'local' (this workspace, ${ctx.config.dirName}/memory/MEMORY.md). ` +
+        "Use scope 'global' ONLY for machine/user-wide facts (identity, OS, global tool preferences). " +
+        "Store only knowledge that was expensive to obtain and will plausibly matter in a FUTURE session: stable preferences, decisions, lessons, environment quirks. " +
+        "NEVER store temporary session state: current task, todos, in-progress work, debugging state, 'user asked me to X'. " +
+        "One line only, max 300 chars. For longer content use memory_store, which writes a standalone note." +
+        WORKSPACE_GUIDANCE,
+      promptSnippet: "Persist one durable fact to memory (project-local or global)",
+      promptGuidelines: [
+        "Use memory_write sparingly — only for facts a future session will plausibly need. When in doubt, don't write.",
+        "global scope is reserved for facts about the user or the machine; facts about specific software, repos, or configs stay local to the workdir where they were learned.",
+        "Do not record session state (what you're doing now, todos, next steps) — pi's own session files persist that.",
+        "Keep MEMORY.md for one-line facts only. Notes carry their own metadata; their descriptions are automatically included in session context.",
+        "Use memory_search to recall stored knowledge before re-deriving it or asking the user.",
+      ],
+      parameters: Type.Object({
+        content: Type.String({ description: "Single fact to remember (one line, max 300 chars)." }),
+        scope: SCOPE_WRITE,
+        root: ROOT_PARAMETER,
+      }),
+      async execute(args                                                   , exec          )                      {
+        if (args.content.length > MAX_FACT) {
+          return failure(`Entry too long for the index (${args.content.length} chars, max ${MAX_FACT}). Use memory_store for detailed knowledge — it writes a notes file and keeps MEMORY.md lean.`);
+        }
+        const scope = args.scope ?? "local";
+        const target = targetStores(args.root, [scope], exec);
+        if (target.status === "error") return failure(target.message);
+        const store = target.stores[scope];
+        const mutation = await mutate(target.stores, scope, () => appendEntry(store, args.content));
+        if (mutation.status === "error") return failure(mutation.message);
+        const result = mutation.value;
+        if (result.duplicate) {
+          return { text: `Duplicate — already in ${scope} memory:\n${(result.existing ?? []).map((entry) => `- ${formatEntry(entry)}`).join("\n")}` };
+        }
+        if (!result.line) return { text: "Empty content — nothing saved." };
+        const similar = await similarInOtherScope(target.stores, store, result.line);
+        return { text: `Saved to ${scope} memory (${store.memoryFile}). Memo ID: ${result.id}.${similarWarning(similar, scope)}` };
+      },
+    },
+    {
+      name: "memory_store",
+      label: "Memory Store Note",
+      description:
+        "Store detailed knowledge as a standalone Markdown note with description, ID and timestamps in frontmatter. " +
+        "Only note descriptions/IDs/paths enter context; bodies are read on demand via memory_read. " +
+        "Filenames always prepend the UTC date; no Markdown heading is added. Default scope 'local'. " +
+        "Existing/duplicate entries are returned without creating or overwriting a note; use memory_update to revise an indexed memo." +
+        WORKSPACE_GUIDANCE,
+      promptSnippet: "Store detailed knowledge as a dated, self-describing note",
+      promptGuidelines: [
+        "Use memory_store instead of memory_write whenever knowledge needs more than one line. MEMORY.md holds only short facts; notes are discovered from frontmatter.",
+        "When recalling, prefer memory_search to find notes, then memory_read(path=...) to fetch the full note.",
+      ],
+      parameters: Type.Object({
+        title: Type.String({ description: "Short note description stored in frontmatter and injected into context (max 300 chars). Not a heading." }),
+        content: Type.String({ description: "Markdown body only; no frontmatter. Include your own heading if useful." }),
+        slug: Type.Optional(Type.String({
+          minLength: 1,
+          maxLength: 80,
+          description: "Concise filename slug: letters/digits separated by hyphens, no date/path/extension. UTC date is prepended.",
+        })),
+        scope: SCOPE_WRITE,
+        root: ROOT_PARAMETER,
+      }),
+      async execute(args                                                                                 , exec          )                      {
+        if (!args.title.trim() || /[\x00-\x1f\x7f]/.test(args.title)) return failure("Description must be a nonempty single line.");
+        if (!args.content.trim()) return failure("Empty note body — nothing saved.");
+        if (args.slug !== undefined && !validNoteSlug(args.slug)) return failure("Invalid slug: use 1–80 letters/digits separated by hyphens, without date, path or extension.");
+        if (args.title.length > MAX_DESCRIPTION) return failure(`Title too long (${args.title.length} chars, max ${MAX_DESCRIPTION}).`);
+        const scope = args.scope ?? "local";
+        const target = targetStores(args.root, [scope], exec);
+        if (target.status === "error") return failure(target.message);
+        const store = target.stores[scope];
+        const mutation = await mutate(target.stores, scope, () => writeNote(store, args.title, args.content, args.slug));
+        if (mutation.status === "error") return failure(mutation.message);
+        const result = mutation.value;
+        if (result.duplicate) {
+          return { text: `Already indexed in ${scope} memory; no note created or overwritten:\n${(result.existing ?? []).map((entry) => `- ${formatEntry(entry)}`).join("\n")}\nRead the existing memo and use memory_update to revise it.` };
+        }
+        const similar = await similarInOtherScope(target.stores, store, result.indexLine);
+        return {
+          text: `Stored note: ${result.noteRel}\nMemory file: ${store.memoryFile}\nMemo ID: ${result.id}\nDescription: ${result.indexLine}\nMetadata is stored in the note, not duplicated in MEMORY.md.${similarWarning(similar, scope)}`,
+        };
+      },
+    },
+    {
+      name: "memory_update",
+      label: "Memory Update",
+      description:
+        "Update ONE existing memo by its exact eight-character metadata ID, preserving ID, creation date, note path and description. " +
+        "Default scope 'local'. Read the memo first. For facts, content replaces the fact (one line, max 300 chars); " +
+        "for notes, content replaces the full Markdown body excluding frontmatter. Blank content is rejected; identical content is a no-op. " +
+        "Actual changes return a recovery ID for memory_restore." +
+        WORKSPACE_GUIDANCE,
+      promptSnippet: "Revise one memo in place by its ID",
+      parameters: Type.Object({
+        id: Type.String({ pattern: "^[a-fA-F0-9]{8}$", description: "Exact memo ID from index metadata or a tool result (not a recovery ID)." }),
+        content: Type.String({ description: "Replacement fact or full Markdown note body; omit frontmatter." }),
+        scope: SCOPE_WRITE,
+        root: ROOT_PARAMETER,
+      }),
+      async execute(args                                                               , exec          )                      {
+        const scope = args.scope ?? "local";
+        const target = targetStores(args.root, [scope], exec);
+        if (target.status === "error") return failure(target.message);
+        const store = target.stores[scope];
+        const mutation = await mutate(target.stores, scope, () => updateMemo(store, args.id, args.content, queue));
+        if (mutation.status === "error") return failure(mutation.message);
+        const result = mutation.value;
+        if (result.status === "error") return failure(result.message);
+        return {
+          text: result.status === "unchanged"
+            ? `Memo ${args.id} unchanged; nothing written.`
+            : `Updated memo ${args.id} in ${scope} memory (${store.dir}). ID, creation date and note reference preserved; note last-modified-date updated.\nRecovery ID: ${result.recoveryId}\n${restoreHint(result.recoveryId, scope, args.root)}`,
+        };
+      },
+    },
+    {
+      name: "memory_read",
+      label: "Memory Read",
+      description:
+        "Read memory contents. Default: one-line facts plus a derived note catalogue for scope 'both' (global + local). " +
+        "Optional query filters index entries (case-insensitive substring). Optional path reads an existing note file. " +
+        "Optional id retrieves exactly one indexed memo, including note contents. Do not combine id with query/path. " +
+        "Ambiguous IDs/paths require an explicit scope; no guessing." +
+        WORKSPACE_GUIDANCE,
+      promptSnippet: "Read memory facts, the note catalogue, or one memo by ID/path",
+      parameters: Type.Object({
+        id: Type.Optional(Type.String({ pattern: "^[a-fA-F0-9]{8}$", description: "Exact memo ID; returns the index entry and linked note contents." })),
+        query: Type.Optional(Type.String({ description: "Case-insensitive substring filter over catalogue lines." })),
+        path: Type.Optional(Type.String({ description: "Note path to read, e.g. 'notes/2026-08-27-foo.md'." })),
+        scope: SCOPE_READ,
+        root: ROOT_PARAMETER,
+      }),
+      async execute(args                                                                               , exec          )                      {
+        const scopes = resolveScopes(args.scope);
+        const target = targetStores(args.root, scopes, exec);
+        if (target.status === "error") return failure(target.message);
+        const preparationError = await prepareReads(target.stores, scopes);
+        if (preparationError) return failure(preparationError);
+
+        if (args.id !== undefined) {
+          if (args.query !== undefined || args.path !== undefined) return failure("Specify id alone, or use query/path without id.");
+          const memo = await readMemo(target.stores, args.id, scopes);
+          if (memo.status === "error") return failure(memo.message);
+          const out = `## ${memo.store.scope} memo ${args.id} — ${memo.store.memoryFile}\n\n${memo.entry.meta ?? ""}\n${memo.entry.line}` +
+            (memo.noteText !== undefined ? `\n\n## Note: ${memo.noteRel}\n\n${memo.noteText}` : "");
+          return { text: formatTruncated(truncateTail(out, NOTE_CAP)) };
+        }
+
+        if (args.path !== undefined) {
+          const resolved = resolveNotePath(target.stores, args.path, scopes);
+          if (resolved.status === "error") return failure(resolved.message);
+          const text = await readFile(resolved.absPath, "utf8");
+          return { text: formatTruncated(truncateTail(`## ${resolved.store.scope} note: ${resolved.rel}\n\n${text}`, NOTE_CAP)) };
+        }
+
+        const sections           = [];
+        for (const scope of scopes) {
+          const store = target.stores[scope];
+          const text = await readCatalogue(store);
+          let body = text;
+          if (args.query) {
+            const q = args.query.toLowerCase();
+            body = parseEntries(text)
+              .filter((entry) => entry.line.toLowerCase().includes(q) || (entry.meta ?? "").toLowerCase().includes(q))
+              .map((entry) => `${entry.meta ? `${entry.meta}\n` : ""}${entry.line}`)
+              .join("\n");
+          }
+          const label = scope === "local" ? `local (${basename(target.root)})` : "global";
+          sections.push(`## ${label} memory — ${store.memoryFile}${existsSync(store.memoryFile) ? "" : " (missing)"}\n\n${body.trim() || "(empty)"}`);
+        }
+        return { text: formatTruncated(truncateTail(sections.join("\n\n"), READ_CAP)) };
+      },
+    },
+    {
+      name: "memory_search",
+      label: "Memory Search",
+      description:
+        "Search facts and note bodies with weighted lexical ranking, exact tokens, phrase/coverage boosts and matching-passage counts. Descriptions and tags weigh more; one result per note. Default scope 'both'." +
+        WORKSPACE_GUIDANCE,
+      promptSnippet: "Search memory facts and note bodies",
+      parameters: Type.Object({
+        query: Type.String({ description: "Search terms." }),
+        scope: SCOPE_READ,
+        root: ROOT_PARAMETER,
+      }),
+      async execute(args                                                  , exec          )                      {
+        const scopes = resolveScopes(args.scope);
+        const target = targetStores(args.root, scopes, exec);
+        if (target.status === "error") return failure(target.message);
+        const preparationError = await prepareReads(target.stores, scopes);
+        if (preparationError) return failure(preparationError);
+        const hits = await searchStores(target.stores, args.query, scopes, 20);
+        if (hits.length === 0) return { text: "No matches in memory." };
+        const lines = hits.map((hit) =>
+          `[${hit.scope}/${hit.file}] ${hit.id ? `[id=${hit.id}] ` : ""}${hit.line}${hit.matchLines > 1 ? ` (+${hit.matchLines - 1} more matching lines)` : ""}`,
+        );
+        return { text: formatTruncated(truncateTail(lines.join("\n"), READ_CAP)) };
+      },
+    },
+    {
+      name: "memory_forget",
+      label: "Memory Forget",
+      description:
+        "Delete facts or notes whose description, path or metadata contains the given text (case-insensitive); note bodies are not matched. Removes note files with recoverable snapshots. Returns a recovery ID for memory_restore. Default scope 'local'." +
+        WORKSPACE_GUIDANCE,
+      promptSnippet: "Forget facts or notes matching a string (recoverable)",
+      parameters: Type.Object({
+        text: Type.String({ description: "Text that identifies entries to delete." }),
+        scope: SCOPE_WRITE,
+        root: ROOT_PARAMETER,
+      }),
+      async execute(args                                                , exec          )                      {
+        const scope = args.scope ?? "local";
+        const target = targetStores(args.root, [scope], exec);
+        if (target.status === "error") return failure(target.message);
+        const store = target.stores[scope];
+        const mutation = await mutate(target.stores, scope, () => forgetEntries(store, args.text, queue));
+        if (mutation.status === "error") return failure(mutation.message);
+        const result = mutation.value;
+        if (result.recoveryId === null) return { text: `No entries matching "${args.text}" in ${scope} memory.` };
+        return { text: `Removed ${result.removed.length} entr(y/ies) from ${scope} memory (${store.memoryFile}). Recovery id: ${result.recoveryId}\n${restoreHint(result.recoveryId, scope, args.root)}` };
+      },
+    },
+    {
+      name: "memory_restore",
+      label: "Memory Restore",
+      description:
+        "Restore entries deleted by memory_forget or undo a memory_update using its recovery ID. Refuses to overwrite later edits; conflicts retain the recovery record. Default scope 'both'; use the same root as the original change." +
+        WORKSPACE_GUIDANCE,
+      promptSnippet: "Undo a forget or update with its recovery ID",
+      parameters: Type.Object({
+        recoveryId: Type.String({ description: "Recovery id returned by memory_forget or memory_update." }),
+        scope: SCOPE_READ,
+        root: ROOT_PARAMETER,
+      }),
+      async execute(args                                                       , exec          )                      {
+        const scopes = resolveScopes(args.scope);
+        const target = targetStores(args.root, scopes, exec);
+        if (target.status === "error") return failure(target.message);
+        const result = await restoreEntry(
+          target.stores,
+          args.recoveryId,
+          queue,
+          scopes,
+          (store) => workspaceAccessError(target.stores, [store.scope]),
+          ensureStoreVersion,
+        );
+        if (!result) return { text: `No recovery record found for id ${args.recoveryId}.` };
+        if (result.status === "error") return failure(result.message);
+        return {
+          text: `Restored ${result.entries.length} entr(y/ies) to ${result.scope} memory:\n${result.entries.map((entry) => `- ${entry.line}`).join("\n")}`,
+        };
+      },
+    },
+    {
+      name: "memory_status",
+      label: "Memory Status",
+      description:
+        "Show memory file locations, sizes, entry counts, and current session's injected snapshot size. Optional root selects another existing workspace. Works before memory_init and never creates files.",
+      promptSnippet: "Show memory store locations, counts, and snapshot size",
+      parameters: Type.Object({ root: ROOT_PARAMETER }),
+      async execute(args                   , exec          )                      {
+        const target = targetStores(args.root, ["local"], exec);
+        if (target.status === "error") return failure(target.message);
+        return { text: await statusText(target.stores, ctx.config, target.root) };
+      },
+    },
+    {
+      name: "memory_migrate",
+      label: "Memory Migrate",
+      description:
+        "Migrate a legacy plain-file memory store into this workspace's shared store. Detects a pi-remember v1 store at <workspace>/.pi/memory (or an in-place copy missing only the marker). " +
+        "Copies current facts and notes only; recovery records, migration backups and other history are left behind. " +
+        "Never overwrites an initialized target. Use dryRun first when unsure, and ask the user before migrating.",
+      promptSnippet: "Migrate a legacy pi-remember store into this workspace",
+      parameters: Type.Object({
+        source: Type.Optional(Type.String({ description: "Legacy store directory. Defaults to <workspace>/.pi/memory." })),
+        target: Type.Optional(Type.String({ description: `Destination store directory. Defaults to <workspace>/${ctx.config.dirName}/memory.` })),
+        dryRun: Type.Optional(Type.Boolean({ description: "Plan and report without writing anything." })),
+        root: ROOT_PARAMETER,
+      }),
+      async execute(args                                                                       , exec          )                      {
+        const cwd = args.root?.trim() ? resolve(exec.cwd, expandHome(args.root.trim())) : exec.cwd;
+        const explicit = Boolean(args.source?.trim() || args.target?.trim());
+        let source = args.source?.trim() ? resolve(cwd, expandHome(args.source.trim())) : legacySource(cwd);
+        let target = args.target?.trim() ? resolve(cwd, expandHome(args.target.trim())) : join(cwd, ctx.config.dirName, "memory");
+        if (!explicit) {
+          const detection = await detectForWorkspace(cwd, ctx.config);
+          if (!detection) return { text: `No legacy memory store found for ${cwd} (looked for ${legacySource(cwd)} and an in-place marker in ${target}).` };
+          source = detection.source;
+          target = detection.target;
+        }
+        try {
+          const report = await migrate({ source, target, dryRun: args.dryRun === true });
+          return { text: formatReport(report) };
+        } catch (error) {
+          return failure(`Migration refused: ${(error         ).message}`);
+        }
+      },
+    },
+  ];
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@seangle/pi-remember",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Portable plain-file memory for the Pi coding agent: facts, notes, stable memo IDs, lexical search, and a session snapshot.",
+  "license": "Apache-2.0",
+  "author": "Esensats",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Esensats/agents-remember.git",
+    "directory": "packages/pi"
+  },
+  "homepage": "https://github.com/Esensats/agents-remember/tree/main/packages/pi#readme",
+  "bugs": {
+    "url": "https://github.com/Esensats/agents-remember/issues"
+  },
+  "keywords": ["pi-package", "pi-extension", "memory", "persistent-memory"],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "pi": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@seangle/remember-core": "^0.1.0",
+    "@seangle/remember-migrators": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=22.15.0"
+  },
+  "scripts": {
+    "prepack": "node ../../scripts/build.mjs",
+    "build": "node ../../scripts/build.mjs",
+    "test": "node --test test/*.test.ts"
+  }
+}