@gavin-hu/my-pi-agent 0.18.0 → 0.19.0

package/{extensions/memory/README.md → docs/extensions/memory.md}

@@ -7,7 +7,28 @@ live as human-editable markdown, not in the session branch, so they survive
 `AGENTS.md`; `memory` is for the one-liners the model should not have to be
 reminded of twice.
 
-<img src="../../assets/memory.png" alt="The /memory picker: a Memory title rule, an `All · 3 project, 2 global` summary, five notes tagged by scope with the focused one marked, and the key hints" width="100%">
+<img src="../../assets/screens/memory.png" alt="The /memory picker: a Memory title rule, an `All · 3 project, 2 global` summary, five notes tagged by scope with the focused one marked, and the key hints" width="100%">
+
+## Capabilities
+
+Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Automatic recall | the `[MEMORY]` context message | Stored notes arrive before each run, bounded by a byte cap, without the user asking. | Shipped |
+| Durable notes | `memory` | The model adds, updates, forgets, or lists short facts that outlive the session branch. | Shipped |
+| Two scopes | the `scope` parameter, `/memory path` | Notes are global or per-project, each a plain markdown file you can edit by hand. | Shipped |
+| Repo-root anchor | the `project` store | The project store is anchored at the repository root, so a subdirectory and every worktree read the same file. | Shipped |
+| Note picker | `/memory` | Add, edit, forget, merge, or move a note in the TUI, with a scope filter and a reload. | Shipped |
+| Whole-file editing | `/memory edit`, `/memory clear` | The file in the multi-line editor, or a scope cleared behind a confirm. | Shipped |
+| Duplicate guard | `memory` `add` | Re-stating a stored fact in new words is a no-op that names the existing note. | Shipped |
+| Store health | `/memory doctor` | Counts, file bytes, the injection budget with its omissions, and near-duplicate pairs. | Shipped |
+| Store freshness | `memory`, `/memory reload` | A hand edit is picked up on the next read, and `reload` forces it. | Shipped |
+| Recall off switch | `memory.inject` | Injection can be turned off without deleting the notes, for a session that must not receive them. | Shipped |
+| Trust-gated project store | the `project` scope | The project file is read and written only when the project is trusted. | Shipped |
+| Headless coverage | `list`, `path`, `reload`, `doctor` outside `tui` | Read-only verbs notify everywhere; picker, edit, and clear require an interactive session. | Shipped |
+
+## Quickstart
 
 ```bash
 pi --extension ./extensions/memory    # load just this extension
@@ -15,61 +36,42 @@ pi -e .                               # load the whole @gavin-hu/my-pi-agent pac
 pi install ./                         # install the package
 ```
 
-## Tool rendering
+```text
+/memory                               # open the picker (a listing elsewhere)
+/memory doctor                        # check the stores and the injection budget
+```
+
+## Tool
 
 How the `memory` call and its result look in the transcript — the call line as a headline and the body indented under it:
 
 <img src="../../assets/tools/memory.png" alt="The memory tool's result: the call line and an indented body confirming the write and the new project and global counts" width="100%">
 
-## What it does
-
-- Registers one model-callable tool, `memory`, with four actions: `add` a note,
-  `update` an exact note, `forget` an exact note, or `list` what is stored.
-  `add` is a no-op when the note already exists, ignoring case and trailing
-  punctuation, so re-stating a fact in new words does not grow the store.
-- Keeps two stores, both plain markdown with one bullet per note:
-
-  | Scope | File |
-  |---|---|
-  | `global` | `<agent-dir>/memory.md` |
-  | `project` | `<repo-root>/.pi/memory.md` |
-
-  The project store is anchored at the **repository root**, so it is stable when
-  Pi runs from a subdirectory and shared across git worktrees.
-- Injects the stored notes as a hidden `[MEMORY]` context message before each
-  run, bounded by a byte cap, so the model recalls them without being asked.
-- Re-reads each store when its file changes on disk (compared by mtime and size),
-  so an external edit lands in the same session without a restart.
-- Exposes `/memory`: in the TUI it opens a picker to add, edit, or forget a
-  single note, merge two notes into one, move a note to the other scope, filter
-  by scope, and reload; elsewhere it lists the store. `/memory path`, `edit`, and `clear` print the file paths,
-  open the multi-line editor, and clear a scope; `/memory doctor` reports store
-  health.
-- Reports store health with `/memory doctor`: note counts and file bytes per
-  scope, how much of the `maxInjectBytes` budget the injection uses and which
-  scope overflowed it, and the near-duplicate pairs the conservative key already
-  considers one fact. It is read-only — the report names the pair and the picker
-  merges it.
-- Loads and writes the project store only when the project is trusted, sanitizes
-  every note to one terminal-safe line, and writes atomically.
+`memory` — direct exposure (the default), `executionMode: "sequential"`,
+annotations `readOnlyHint: false`, `destructiveHint: true` (forget deletes),
+`idempotentHint: true`, `openWorldHint: false`. It is a singleton tool with an
+action switch (like `job`); `list` reads both stores, and the other three
+mutate one.
 
-## Tool
+| Parameter | Type | Meaning |
+|---|---|---|
+| `action` | `add` \| `update` \| `forget` \| `list` | What to do with the store. |
+| `text` | string | The note to add, or the exact note to update or forget. Required for `add`/`update`/`forget`. |
+| `to` | string | The replacement note for `update`. Required for `update`. |
+| `scope` | `project` (default) \| `global` | Which store `add`/`update`/`forget` changes. |
 
-`memory` is a singleton tool with an action switch (like `job`). It declares an
-`outputSchema` and returns matching `structuredContent`
-(`{ action, scope, project, global, changed, entry?, to?, existing?, error? }`).
+Result (`details` / `structuredContent`, `MemoryResult`): `{ action, scope,
+project, global, changed, entry?, to?, existing?, error? }`.
 
-| Field | Value |
+The two stores are plain markdown with one bullet per note:
+
+| Scope | File |
 |---|---|
-| `name` | `memory` |
-| `action` | `add` \| `update` \| `forget` \| `list` |
-| `text` | The note to add, or the exact note to update or forget. Required for `add`/`update`/`forget`. |
-| `to` | The replacement note for `update`. Required for `update`. |
-| `scope` | `project` (default) or `global`. Used by `add`/`update`/`forget`. |
-| `exposure` | `direct` (default). |
-| `executionMode` | `sequential` — calls share the cached stores. |
-| `annotations` | `readOnlyHint: false`, `destructiveHint: true` (forget deletes), `idempotentHint: true`, `openWorldHint: false`. |
-| `outputSchema` | `MemoryResult` — also returned as `structuredContent`. |
+| `global` | `<agent-dir>/memory.md` |
+| `project` | `<repo-root>/.pi/memory.md` |
+
+The project store is anchored at the **repository root**, so it is stable when
+Pi runs from a subdirectory and shared across git worktrees.
 
 Validation happens before anything is written (a violation returns an error
 result carrying the unchanged notes, never a half-apply): a known action; a
@@ -97,6 +99,10 @@ or stem both survive.
 
 ## Commands
 
+`/memory` opens the picker in the TUI and notifies the stored notes elsewhere.
+`list`, `path`, `reload`, and `doctor` report through `notify` in every mode;
+`edit` and `clear` need an interactive session.
+
 | Command | What it does |
 |---|---|
 | `/memory` | In the TUI, open the picker (add, edit, forget, merge, or move notes; `s`/Tab filters by scope; `r` reloads). Other modes notify the stored notes. |
@@ -145,9 +151,8 @@ not change it.
 
 ## Configuration
 
-The `memory` section of the shared `bytefly.json`, read from the global
-document then the project document (project values override global; missing or
-malformed documents are ignored):
+The `memory` section of the shared `bytefly.json`; resolution rules are in
+[`../configuration.md`](../configuration.md#memory--durable-notes):
 
 | Key | Default | Meaning |
 |---|---|---|
@@ -177,10 +182,13 @@ skill. Mitigations:
 
 - Notes are injected whole (bounded), so a very large store is truncated with a
   `(+N more; use the memory tool)` tail rather than summarized.
-- External edits to a store are picked up automatically by an mtime/size check
-  before the next injection or tool call. A same-size edit within one filesystem
-  mtime tick is only caught by `/memory reload`; a store that becomes unreadable
-  (symlinked or over the size cap) keeps its last good view until fixed.
+- External edits to a store are picked up automatically by an `(mtimeNs, size)`
+  check before the next injection or tool call, so a same-size edit inside one
+  millisecond is seen. The residual case is the filesystem's own resolution: where
+  the stamp is no finer than the last one read — a one-second mtime, or a write
+  the kernel coalesced — only `/memory reload` catches the edit. A store that
+  becomes unreadable (symlinked or over the size cap) keeps its last good view
+  until fixed.
 - Matching for `forget` is exact and case-sensitive.
 - The near-duplicate guard on `add` is deliberately conservative: it folds
   case, whitespace runs, and trailing sentence punctuation only, never word
@@ -188,8 +196,8 @@ skill. Mitigations:
   both be stored; `/memory doctor` reports the pairs the key does consider equal,
   and `m` in the picker merges them under wording you write.
 - `update` replaces every exact match of `text`; a replacement that already
-exists under a different note can leave a duplicate. Forget the old note first
-when consolidating, or merge the pair in the picker afterward.
+  exists under a different note can leave a duplicate. Forget the old note first
+  when consolidating, or merge the pair in the picker afterward.
 - Only one note per line; multi-line notes are collapsed to a single line.
 
 ## Non-goals
@@ -237,10 +245,13 @@ when consolidating, or merge the pair in the picker afterward.
   writers for the same file, and each write lands atomically via a temp file and
   rename; `executionMode: "sequential"` keeps in-process calls ordered as well.
 - **Stamped cache, not a watcher.** The session cache is validated against each
-  file's `(mtimeMs, size)` stamp before every read, matching the worktree cache's
-  freshness check rather than holding an `fs.watch` handle. A mutation adopts the
-  fresh on-disk stamp, so a self-write is not mistaken for an external change, and
-  a failed re-read keeps the last good view instead of breaking the run.
+  file's `(mtimeNs, size)` stamp before every read rather than holding an
+  `fs.watch` handle. The stamp is the nanosecond field a bigint `stat` returns, so
+  a same-size edit in the same millisecond is a distinct state; a millisecond
+  stamp would have to read the file on every run to tell them apart. A mutation
+  adopts the fresh on-disk stamp, so a self-write is not mistaken for an external
+  change, and a failed re-read keeps the last good view instead of breaking the
+  run.
 
 ## Files