pi-memory-evolution 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to pi-memory-evolution are documented here.
 
+## [0.2.6](https://github.com/btnalit/pi-memory-evolution/compare/v0.2.5...v0.2.6) (2026-09-09)
+
+
+### Bug Fixes
+
+* reach an allowlisted sibling model and give claims real headroom ([#16](https://github.com/btnalit/pi-memory-evolution/issues/16)) ([ffc47d1](https://github.com/btnalit/pi-memory-evolution/commit/ffc47d148355d5cbf2d77bb5edd1d0111947b7e1))
+
+## [0.2.5](https://github.com/btnalit/pi-memory-evolution/compare/v0.2.4...v0.2.5) (2026-09-09)
+
+
+### Bug Fixes
+
+* recover memory jobs with bounded cross-provider fallback ([#14](https://github.com/btnalit/pi-memory-evolution/issues/14)) ([76cfa6f](https://github.com/btnalit/pi-memory-evolution/commit/76cfa6fcd257866d6ed98a5b6a9fd14cc1b914a7))
+
 ## [0.2.4](https://github.com/btnalit/pi-memory-evolution/compare/v0.2.3...v0.2.4) (2026-09-09)
 
 

package/README.cn.md

@@ -15,7 +15,7 @@
 - **相关内容注入**：结合当前问题和近期用户上下文选择记忆，过滤弱匹配和失效状态；没有匹配就不填充无关内容。
 - **跨会话召回**：在共享记忆库的不同会话、目录中查找背景；提供只读 `memory_recall` 工具，供助手在任务中途补查。
 
-学习使用 Pi 当前模型和已有认证，无需另配 API Key、向量数据库或嵌入服务。
+学习默认使用 Pi agent 当前模型和已有认证；额度耗尽、限流或重复故障时，可切换到 Pi 已配置的其他供应商模型，不改变主对话模型。无需另配 API Key、向量数据库或嵌入服务。详见[重试、切换与预算](docs/recovery.md)。
 
 ## 安装
 
@@ -42,7 +42,7 @@ pi install https://github.com/btnalit/pi-memory-evolution
 /memory status
 ```
 
-出现 `SQLite ok (schema 6)` 表示存储初始化成功。后续正常使用 Pi 即可，学习和召回会自动运行。
+出现 `SQLite ok (schema 7)` 表示存储初始化成功。后续正常使用 Pi 即可，学习和召回会自动运行。
 
 ## 使用
 
@@ -87,7 +87,7 @@ Git 安装请把上面的包来源替换为安装时使用的仓库 URL。操作
 
 数据默认保存在 `~/.pi/agent/agent-suite/memory-evolution/`，使用本地 SQLite。`PI_CODING_AGENT_DIR` 可改变存储前缀；不同工作目录默认共享记忆库。
 
-学习会将经过过滤的来源内容发送给当前模型，并消耗相应额度。记忆不是经过独立验证的事实，匹配和敏感信息过滤也并非万无一失；重要内容仍需核实。详见[存储与隐私](docs/usage.md#local-storage-and-provenance)。
+学习会将经过过滤的来源内容发送给当前模型或允许使用的备用供应商，并消耗相应额度。默认启用跨供应商切换；可通过[恢复配置](docs/recovery.md)限制供应商模型名单或关闭切换。所有备用模型共享调用上限。记忆不是经过独立验证的事实，匹配和敏感信息过滤也并非万无一失；重要内容仍需核实。详见[存储与隐私](docs/usage.md#local-storage-and-provenance)。
 
 ## 开发
 

package/README.md

@@ -22,8 +22,10 @@ assistant to remember them.
 - **Recall across sessions.** Find background from another session or directory.
   A read-only `memory_recall` tool lets the assistant look up missing context mid-task.
 
-Learning uses Pi's active model and existing authentication. No separate API key,
-embedding service or vector database is required.
+Learning defaults to Pi's active model and existing authentication. Quota/rate limits
+or repeated failures can use an available model from another configured provider, without
+changing the foreground model. [Fallback and budgets](docs/recovery.md) are configurable;
+no separate API key, embedding service or vector database is required.
 
 ## Install
 
@@ -46,7 +48,7 @@ Choose **one** source, then run these commands inside Pi:
 /memory status
 ```
 
-`SQLite ok (schema 6)` confirms storage initialization. Continue using Pi normally;
+`SQLite ok (schema 7)` confirms storage initialization. Continue using Pi normally;
 learning and recall run automatically.
 
 ## Use
@@ -96,7 +98,9 @@ Local SQLite state lives in `~/.pi/agent/agent-suite/memory-evolution/`.
 `PI_CODING_AGENT_DIR` changes that prefix; different working directories share the
 same store by default.
 
-Learning sends filtered source content to the active model and consumes its quota.
+Learning sends filtered source content to the active model, or an allowed fallback provider,
+and consumes that provider's quota. Cross-provider fallback is enabled by default; restrict
+its allowlist or disable it in [recovery configuration](docs/recovery.md).
 Memories are historical evidence, not independently verified facts. Matching and
 secret filtering are imperfect; verify important claims. See [privacy and storage](docs/usage.md#local-storage-and-provenance).
 

package/docs/core-quality.md

@@ -195,7 +195,7 @@ reset, automatic state revival or fabricated verification occurs.
 Reads validate evidence/feedback shape and tool-observation kind, and return independent
 copies of nested metadata. Status validates receipt fields in addition to existing
 record/job/history integrity. Unsupported schema versions fail before DDL. Old builds
-reject schema 6: do not manually downgrade its marker.
+reject schema 7: do not manually downgrade its marker.
 
 Stop all Pi processes sharing the state directory and back up the complete state before
 activation. Update/restart all those processes together (or reload after a consistent

package/docs/design.md

@@ -177,7 +177,7 @@ multiple projects. The prompt requires an explicitly identifiable same subject/f
 preservation of project/resource qualifications; matching cwd alone is not identity.
 
 Output is validated JSON (an outer Markdown fence is tolerated), at most 64,000 bytes
-and 16 claims of 4–480 UTF-16 code units each. Fields are restricted to `kind`, `content`,
+and 16 claims of 4–800 UTF-16 code units each. Fields are restricted to `kind`, `content`,
 optional `replaces` and `searchTerms`. Aliases are at most 8 sanitized strings of 2–64
 characters, with total JSON <=1024 bytes. Malformed claims/aliases reject the batch.
 The prompt asks for concise Chinese/English aliases, never added facts. Existing text
@@ -194,9 +194,9 @@ not detected globally.
 
 Each attempt uses at most one model call, no tools, an 8,192-output-token cap (clamped
 against a smaller model limit), a fresh request session ID and `cacheRetention: "none"`.
-A 120-second outer deadline bounds waiting
-even when a provider ignores abort; remote computation/billing cannot be guaranteed to
-stop. Failed calls retain local summary claims. User-cue prose is saved but needs a
+A 120-second per-attempt deadline bounds waiting even when a provider ignores abort;
+remote computation/billing cannot be guaranteed to stop. A backup has a fresh deadline,
+clamped by the source's remaining 300-second cumulative allowance. Failed calls retain local summary claims. User-cue prose is saved but needs a
 successful model attempt to become claims; it has no local extraction fallback.
 
 Global recall is **not global rewriting**. Cross-origin variants remain separate instead
@@ -223,6 +223,12 @@ One SQLite database, WAL + FULL synchronous mode and private file permissions.
 - `feedback_receipts`: exact source-ID/memory-ID idempotency keys, verdict and numeric
   timestamp, including redundant/late feedback receipts; undo never reopens them.
 - `metadata`: schema/import marker.
+- `model_calls`: reserved attempts, selected model/provider, outcome, usage and estimated/reported cost.
+- `route_health`: provider/model cooldowns, separate from source backoff.
+- `recovery_notices`: bounded persistent notice deduplication keys.
+Source-level call/model/time/correction counts survive receipt pruning; shared ceilings are
+reserved transactionally. The active model is preferred; allowed backups come only from
+other Pi-configured providers. [Recovery policy and privacy](recovery.md) define the bounds.
 
 The `scope` field records canonical cwd, not an inferred repository/branch/subject identity
 (or an explicit annotation of a legacy record). It is no longer a recall boundary. Reads
@@ -239,13 +245,16 @@ failure with backoff; attempt/state checks prevent late results or failures from
 a new owner's job. Model waiting and recurring recovery use the same serial task chain;
 queued capture/manual work prevents the timer from piling up duplicate tasks.
 
-Automatic selection/claim both enforce persisted due time and failure budget, ordered by
-retry time then oldest source. Each actual failure schedules 1 minute, 5 minutes, 15 minutes,
-then 1 hour of backoff. Five consecutive failures pause that source with a warning and
-status diagnostics; repeated crashes also consume the budget. Shutdown cancellation does
-not. Successful completion resets the failure fields. Other eligible work continues;
-there is no unbounded per-source model loop. `/memory evolve` selects one newest eligible
-source and can override the delay/cap for one explicit attempt (not reset the budget).
+Automatic selection/claim enforce source backoff and call/time/failure caps. Least-recently
+checked ordering prevents temporarily unroutable sources starving other work. Provider/model
+cooldowns never contaminate a source's retry_at. Generic runtime backoff is 1 minute,
+5 minutes, 15 minutes, then 1 hour with up to 20% jitter; quota/auth/rate-limit errors can
+immediately use an allowed other provider. Two recent transport failures pause a model.
+Defaults allow 4 reserved calls / 2 models / 300 seconds per source, one format correction,
+and 20 reservations/hour shared across providers and processes. Unsafe writes/refusals
+pause immediately. Three output failures or five generic failures also pause work.
+Shutdown adds no failures, but an already reserved request may still cost money.
+`/memory evolve` overrides source delay/caps for one attempt, never shared ceilings.
 Completed/retired jobs are never forced to run again. A source resumed in another directory
 retains its original provenance. While Pi is closed no polling occurs.
 
@@ -266,9 +275,9 @@ Memory reads validate indexed identity/origin/hash against JSON. Undo validates
 unique before/after IDs and only succeeds when the current records still equal the event's
 after state. New records become tombstones rather than being physically erased. Status
 also validates source jobs/history and the schema marker. Unsupported schema versions
-are rejected before DDL. Schemas 2/3/4 upgrade transactionally to 5 without rewriting
-claims/history or resetting evidence timestamps; missing retry columns/indexes and the
-feedback receipt table are added. Old evidence metadata stays absent/unknown.
+are rejected before DDL. Schemas 2–6 upgrade transactionally to 7 without rewriting
+claims/history or resetting evidence timestamps. Missing retry/feedback tables and routing
+accounting are added; known v6 model waits are separated from source backoff. Old evidence metadata stays absent/unknown.
 Old failures below the cap are due immediately, with unknown cause/time explicitly labeled.
 The source/alias/retry contract is validated on read.
 These detect structural corruption, not all well-formed edits by an owner of the database.
@@ -278,7 +287,7 @@ Undo does not clear suppression hashes or reopen jobs. Forget/undo is not secure
 
 Earlier 0.2 SQLite records, IDs, histories and origin labels stay intact and become
 eligible for global relevance-based recall, including existing `legacy` claims. The
-schema-2/3/4-to-5 upgrade requires no data copying, JSONL re-import or manual reset.
+schema-2-through-6-to-7 upgrade requires no data copying, JSONL re-import or manual reset.
 Stop/back up before upgrading, reload all processes sharing the DB, and restore a matching
 backup for rollback; older code must not be pointed at a manually downgraded marker.
 
@@ -288,6 +297,9 @@ facts. Parent corrections preserve unchanged children and derive new facts witho
 reintroducing explicitly suppressed child content. Missing origins retain the `legacy`
 label. Adoption is an optional annotation, not a recall prerequisite. Completed imports
 are not replayed; earlier discarded revision information is not automatically reconstructed.
+Empty/missing ledgers do not consume the import opportunity. Only saved digests proving a
+recognized empty v6 snapshot (without a migration event) can reopen old completed markers;
+zero derived claims from a real consumed ledger are not sufficient.
 Old signals/proposals/execution plans remain historical files, never automatic actions.
 
 List defaults to all origins, 20 per page sorted by update time then ID; `all` is an alias.

package/docs/recovery.md

@@ -0,0 +1,134 @@
+# Recovery, provider fallback and budgets
+
+Memory learning defaults to **Pi's active agent model**. With no session override this
+is Pi's configured default. The extension never sets the foreground model, creates a
+second credential store, changes provider configuration, or probes models to rank them.
+It discovers available models through Pi's registry and uses registry completion/auth.
+
+## Provider fallback
+
+Cross-provider fallback is enabled by default. If the default route is unavailable,
+learning may send the sanitized source and selected candidate memories to another
+**already-configured, available Pi provider**. This is a privacy/cost boundary: configure
+an explicit allowlist or disable fallback below if some configured providers must not
+receive memory data. Installing this update does not require per-request approvals.
+
+The active model is always first when eligible. Backups must support text. Another model of
+the **same** provider is never chosen automatically, because it shares that provider's
+credentials and account quota. Naming one in `fallbackModels` overrides that: it is the only
+redundancy available when Pi has a single configured provider, and it is then used for
+model-specific failures (`rate_limit`, `invalid_output`, `output_limit`, `context_limit`)
+but still skipped for `auth` and `quota`, which no sibling can escape. An explicit
+fallback list defines priority; otherwise known catalog input/output price, non-reasoning
+preference and stable model ID order choose among available backups. Unknown/zero prices
+are not assumed free. Catalog availability is not proof of working credentials or credit.
+At most two models may receive any one source by default, including the primary.
+
+All source/model budgets are checked in a SQLite write transaction. Selection does not
+grant call authority. Provider cooldowns are shared across sources and Pi processes.
+A cooldown for A does **not** change a source's retry timestamp or prevent B from working.
+Last-checked ordering moves temporarily unroutable sources behind other eligible work.
+
+## Error policy
+
+| Result | Automatic action |
+| --- | --- |
+| HTTP 401/403 | Cool down that provider for 15 minutes; try an allowed other provider. Pi owns auth resolution/refresh. |
+| HTTP 402 or fixed quota/billing code | Cool down the provider for 1 hour or a later supplied reset; try another provider. |
+| HTTP 429 without a known quota code | Cool down that **model** for at least 60 seconds and at least `Retry-After`, since tpm/rpm ceilings are usually per model; try another provider, or an allowlisted model of the same provider. |
+| HTTP 408, timeout, network/5xx failure | Delayed retry; two recent transport failures cool down that model for 15 minutes and permit fallback. |
+| Context overflow or HTTP 400/404/422 | Do not resend unchanged requests to that model immediately; cool it down for 1 hour and permit a compatible backup. |
+| Invalid JSON / output truncation | Initial attempt, at most one corrective prompt, then an alternate model. Three output failures pause the source; two failures do not authorize repeatedly probing the same model. |
+| Unsafe/unauthorized write or recognized safety/refusal | Reject and pause that source. No fallback to circumvent safety or write guards. |
+| Stale result | Re-read on a bounded delayed retry; not counted as a provider-health failure. |
+| Cancellation / shutdown / reload | Release the lease without adding a failure; already-reserved requests may still have consumed quota. |
+| Unknown error | Safe generic category and bounded transport retry; no guessing that arbitrary error prose means insufficient credit. |
+
+Generic source backoff is 1 minute, 5 minutes, 15 minutes, then 1 hour, with up to 20%
+positive jitter on runtime failures. Route failures can try one alternate immediately;
+there are at most two immediate attempts per queue item, not a sleep/retry loop. The
+120-second deadline is **per attempt**, not an outer timeout that also kills its backup.
+Request deadlines are clamped to the source's remaining cumulative time budget. A provider
+ignoring cancellation cannot commit late output, but remote execution/billing may continue.
+
+HTTP status/error codes are observed before the underlying SDK consumes failed responses,
+using request-local fetch only for verified supporting APIs: OpenAI completions/responses,
+Azure responses, Codex responses, Anthropic messages and Mistral conversations. Codex memory
+requests use HTTP SSE; foreground transport is unchanged. Other adapters retain their normal
+transport. Complete structured JSON errors (including Google SDK errors) can also supply a
+fixed status/code; arbitrary text is never searched for status-like numbers or echoed.
+Only known code values, numeric `Retry-After`/reset metadata and raw stop enums are used.
+Unsupported/opaque SDK errors can still be generic `provider`; no universal balance API is
+claimed. Error-body inspection is transient, bounded to 8192 bytes and 200 ms, never stored.
+
+Input planning drops lower-priority existing candidates when a conservative byte/token
+estimate exceeds the chosen context window. It does not truncate facts or progress JSON to
+pretend they fit. If the original evidence still cannot fit, that route is rejected. Model
+mistakes and provider-specific tokenization remain possible; this is not exact token counting.
+
+## Optional configuration
+
+Create `recovery.json` **in the memory state directory**, not in Pi's settings file. Reload
+all Pi processes sharing that directory after changing policy. Defaults are:
+
+```json
+{
+  "crossProviderFallback": true,
+  "fallbackModels": [],
+  "callsPerHour": 20,
+  "sourceCalls": 4,
+  "sourceModels": 2,
+  "timeoutMs": 120000,
+  "sourceTimeMs": 300000,
+  "dailyEstimatedUsd": null
+}
+```
+
+`fallbackModels` optionally contains exact `provider/model-id` strings, in priority order.
+Only models Pi reports available are considered. It does not override the default model
+or configure authentication. `crossProviderFallback: false` confines learning to the active
+model. Invalid policy fails closed with a fixed error, never prints configuration contents.
+
+Limits apply together:
+
+- **20 reservations per rolling hour across all models/providers/processes**, not 20 per
+  fallback model. An exhausted shared budget cannot be bypassed by switching providers.
+- **4 reserved calls, 2 models and 300 seconds per source** by default. Reservations include
+  failed/preflight/cancelled attempts conservatively; they are not exact server billing counts.
+- One persisted format-correction allowance survives cancellation/reload. Safety validation
+  and transactional all-or-nothing writes apply equally to every backup model.
+- The older five-failure safety cap is also retained, including crashes and pre-upgrade work.
+- `/memory evolve [source-id]` may override source backoff/route cooldown/source caps for
+  **one** explicit attempt, without clearing counters. It cannot bypass shared request or
+  estimated-cost ceilings and does not loop through backup models. Settled jobs are not rerun.
+
+`dailyEstimatedUsd` is disabled by default because provider catalogs can contain absent,
+zero, outdated or non-billing prices (subscriptions and local models are common). Set a
+positive value to enforce a rolling 24-hour **catalog-estimated** spending ceiling.
+Unknown pricing fails closed under this optional ceiling. Reservation uses a conservative
+input-byte bound, maximum configured pricing tier and output allowance; returned usage/cost
+replaces it when available. Missing usage and cancelled/error responses are not assumed
+free. These estimates are not account balance, billing receipts, or a guaranteed invoice cap.
+Actual provider accounting can differ. Token counts, estimates and unknown-cost counts are
+shown separately from Pi's foreground session totals.
+
+## Diagnostics and upgrade
+
+`/memory status` shows the current default, allowed routes, provider/model cooldowns,
+source attempts/calls/output failures/time, shared budget and recent selected-model outcomes.
+A successful fallback can show one informational notice per route pair/hour. Failures and
+pause summaries are also deduplicated across reloads, not re-armed by unrelated successes.
+No exception bodies, credentials or failed model text are persisted in diagnostics.
+
+Schema **2–6 upgrade to 7**. Stop Pi and back up the whole state directory first; restart or
+reload all processes after updating. Claims, IDs, histories, forgetting and evidence dates
+are preserved. Existing v6 call receipts seed source counts/model history where available;
+missing history is not invented. Known v6 route-contaminated waits are separated from the
+original source backoff. Earlier paused five-failure jobs are not indiscriminately reset.
+Older code rejects schema 7; rollback requires a matching backup, not editing the marker.
+
+Empty/missing legacy input no longer consumes the one-time import opportunity. Supply valid
+ledgers and use `/memory import [directory]`. A v6 completed/zero-count marker is reopened
+only when its saved digest proves a recognized empty snapshot and no migration event exists.
+A real consumed ledger with no derived claims remains completed; zero count alone cannot
+justify replay over later corrections/forgetting. Originals and copy-only archives are kept.

package/docs/testing.md

@@ -17,6 +17,17 @@ helper scripts and memory state must not ship in the package.
 
 `check:package` inspects `npm pack --dry-run --json`; it does not publish to npm.
 
+## Recovery and routing regressions
+
+`http-diagnostics.test.ts` and `fallback-http.test.ts` use the real Pi ModelRuntime/Registry
+with loopback HTTP responses, not mocks that simply invoke `onResponse`. They verify HTTP
+401/403/400/429/503, quota/context/safety codes, Retry-After, Google SDK JSON errors, and
+cross-provider fallback with the backup's own authentication. No live provider is contacted.
+`scheduler.test.ts` covers bounded correction, per-attempt timeout/late-output rejection,
+provider cooldowns, allowlists, shared hard ceilings and persistent source limits.
+`reliability-regressions.test.ts` covers empty ledgers, safe v6-marker repair, preserving
+zero-claim real imports, schema-6 scheduling migration, and case-sensitive resource identity.
+
 ## npm CLI compatibility
 
 All consumers of `npm pack --json` share `scripts/lib/npm-pack.mjs`. npm 10/11
@@ -67,7 +78,7 @@ host explicitly. The script prints the tested host version. The test:
 1. Builds and extracts the actual npm tarball, outside the development checkout.
 2. Uses real `pi install`, `pi list` and default package discovery—no explicit `-e`
    entry or memory-extension wrapper. Checks `/memory status`, `/memory learning`
-   and `/memory explain`, including schema 6, with no checkout `node_modules`.
+   and `/memory explain`, including schema 7, with no checkout `node_modules`.
 3. Verifies repeated installation does not duplicate the package setting, then
    removes it and confirms the command disappears while records/history remain.
 4. Creates a local Git origin from the packed files and the real lockfile. A
@@ -75,7 +86,7 @@ host explicitly. The script prints the tested host version. The test:
    `file` transport is permitted. No GitHub access is needed.
 5. Exercises the native Git installer and its real npm dependency step, updates to
    a new commit, switches from an old pinned tag back to the default branch, and
-   verifies source switching and removal preserve schema-6 state.
+   verifies source switching and removal preserve schema-7 state.
 6. Serves the actual tarball through a loopback npm registry, with a fresh cache,
    then checks native `pi install npm:pi-memory-evolution`, repeat installation,
    normal loading and removal. No host peer packages are served or installed.

package/docs/usage.md

@@ -10,6 +10,7 @@ This reference covers detailed behavior and optional controls; normal use is aut
 - [Commands](#commands)
 - [Migration](#migration-from-01)
 - [Recovery and troubleshooting](#recovery-and-troubleshooting)
+- [Provider fallback, error policies and budgets](recovery.md)
 
 ## Installation and updates
 
@@ -110,9 +111,11 @@ rename the tool to hide the conflict; an old installation would still run its ho
 - Each processing attempt makes at most one background model call, using up to 32
   recently updated active memories from that source's capture origin. This is a
   conservative automatic-replacement safeguard, **not a recall restriction**.
-  It uses **the current Pi session model and Pi's own provider/auth resolution**.
-  With no model override in the session, this is Pi's configured default model.
-  There is no extra API key, provider setting, subagent, or alternate-model fallback.
+  It defaults to **the current Pi session model and Pi's own provider/auth resolution**.
+  With no session override, this is Pi's configured default. Quota/rate limits or repeated
+  failures may switch to an available model from another configured provider, not a sibling
+  sharing the default provider's quota. The foreground model is never changed. See
+  [fallback privacy, error handling and budgets](recovery.md); no extra credentials are stored.
 - Valid additions/replacements commit immediately, with provenance and before/after
   history. Inferred memories remain labeled `provisional`, but are recallable without
   approval. Pinned memories cannot be automatically replaced.
@@ -123,14 +126,17 @@ rename the tool to hide the conflict; an old installation would still run its ho
   learning its claims requires a successful model attempt.
 - Session start checks persisted work across **all origins**. While Pi remains running,
   a local recovery timer checks every **15 seconds** (after the previous check/call ends),
-  gradually draining eligible pending/failed work one source per check. Selection favors
-  the earliest retry time, then oldest capture; a failed source does not block other work.
-- Failed attempts retry automatically after **1 minute, 5 minutes, 15 minutes, then 1 hour**.
-  After **5 consecutive failures**, that source pauses and a warning points to diagnostics;
-  there are no indefinite paid probes. Retry times/budgets survive reloads and restarts.
-  `/memory status` shows safe error categories, failure times, attempt counts, next retry
-  times and paused counts. `/memory evolve` remains an optional one-off override of the
-  delay/limit, not the normal recovery path; successful/retired jobs are never rerun.
+  gradually draining eligible pending/failed work one source per check (at most one immediate
+  backup per check). Selection favors least recently checked work, then retry time and oldest
+  capture, so unavailable routes do not indefinitely block other sources.
+- Recovery is **error-specific**, with persisted source backoff, separate provider/model
+  cooldowns, at most one output correction, and bounded cross-provider fallback. Generic
+  backoff is 1 minute, 5 minutes, 15 minutes, then 1 hour, plus up to 20% jitter. Defaults
+  cap each source at **4 reserved calls / 2 models / 300 seconds**, and all models and
+  processes share **20 calls per rolling hour**. Three output failures or five generic
+  failures also pause work; unsafe writes/refusals pause immediately. `/memory status`
+  explains routes, budgets and actual outcomes. `/memory evolve` overrides source limits
+  for one attempt, never shared ceilings or settled jobs. [Full policy/configuration](recovery.md).
 - A job lease lasts **150 seconds** (120-second deadline plus 30-second grace). The timer
   detects expired running jobs and schedules them with the same bounded backoff. Shutdown/
   reload cancellation returns work to pending without consuming the failure budget.
@@ -158,7 +164,7 @@ rename the tool to hide the conflict; an old installation would still run its ho
   recall regardless of its original directory.
 - Query coverage, evidence-based document frequency, field weights, mild length
   normalization and a relative cutoff reject weak secondary matches. Unseen query words
-  no longer receive the highest rarity weight. Exact paths must match, and a quoted
+  no longer receive the highest rarity weight. Exact paths must match, including case; `/srv/Atlas` and `/srv/atlas` are distinct. A quoted
   question in a replay/incident note is weaker than evidence answering it. Redundancy
   filtering cannot let a project-state note hide a preference of the same origin.
   Source IDs/cwd have no authority bonus. After relevance gates, host-assigned evidence,
@@ -181,8 +187,10 @@ There is no additional call on ordinary recall. Eligible work turns may now incu
 additional background call each; no related tracked state or no tool observation means
 no progress call. A mixed statement/work turn may additionally incur a separate learning
 call; interrupted turns with usable observations may also learn through automatic recovery.
-Automatic retries may add up to four calls per source after the initial
-failure; every attempt uses the session's then-current model/authentication. Model mistakes
+Automatic retries/fallback share a default total of four reserved calls per source;
+they do not get separate budgets per model. Each request uses Pi's authentication for the
+selected provider. Cross-provider data sharing and optional estimated-cost limits are
+explained in [recovery configuration](recovery.md). Model mistakes
 remain possible; tool observations and model-generated aliases are not proof of truth. Use
 history, correction, pinning and undo rather than treating generated claims as verified facts.
 
@@ -270,7 +278,9 @@ Sensitive lines/blocks are suppressed before capture, edits, model submission an
 recall. This covers common token/password/JSON/Chinese/Bearer/private-key formats,
 including quoted multiline values, indented YAML blocks and control-character cleanup,
 but not every possible secret. Do not rely on a regex as a complete DLP system. Sanitized
-sources and selected existing memories go to the already-configured Pi model provider.
+sources and selected existing memories go to the active Pi model provider or an allowed
+already-configured fallback provider. Fallback is enabled by default; restrict the model
+allowlist or disable it in [recovery configuration](recovery.md) to constrain data sharing.
 
 ## Commands
 
@@ -291,10 +301,10 @@ These are optional direct controls, **not approval gates**:
 /memory evolve                       # optional one-off retry, overriding delay/failure limit
 /memory evolve <source-id>            # retry one named source without clearing other failure counts
 /memory import [directory]            # explicit, repeat-safe legacy JSONL import; never replays a completed one
-/memory archive-legacy                # copy inactive legacy plan files to a timestamped archive; originals kept
+/memory archive-legacy                # copy inactive legacy plan files to a private unique archive; originals kept
 /memory undo <event-id>               # reverse actual changes, if not modified since
 /memory feedback <id> <verdict>       # useful | unhelpful | accurate | incorrect
-/memory correct <id> <replacement>    # literal replacement, 4–480 characters
+/memory correct <id> <replacement>    # literal replacement, 4–800 characters
 /memory forget <id>
 /memory pin <id>
 /memory unpin <id>
@@ -350,18 +360,23 @@ preserve unchanged children of corrected summaries and carry superseded-content
 when corrected legacy claims are adopted into a project.
 
 **Upgrading from earlier 0.2 development builds:** stop Pi and back up the state directory
-first, then update/reload all Pi processes sharing it. Schema markers **2, 3 and 4 upgrade
-transactionally to 5**, adding replay-safe feedback receipts and the optional evidence/feedback
-contract (plus missing retry fields for older schemas). Existing records, IDs, histories and
+first, then update/reload all Pi processes sharing it. Schema markers **2–6 upgrade
+transactionally to 7**, adding missing recovery/feedback fields, source call/time/model
+budgets, provider cooldowns and usage receipts. Known v6 route waits are separated from
+source failure backoff; retained call history seeds counters without inventing missing calls. Existing records, IDs, histories and
 evidence dates remain unchanged. Missing evidence stays unknown, with no fabricated backfill.
 Existing failures below the limit become automatically eligible; their old error cause/time
 remain labeled unknown rather than invented. No copying, manual marker reset or JSONL
-re-import is needed. Older builds reject schema 6; rollback requires a matching backup,
+re-import is needed. Older builds reject schema 7; rollback requires a matching backup,
 not editing the marker. Existing records are immediately eligible for global relevance-based recall.
 Legacy claims previously excluded by cwd filtering become eligible too. This shares
 relevant stored claims with the active Pi session/provider, not raw session archives.
 
-These migration fixes do not replay an already completed import or retroactively erase
+Empty/missing ledgers do not mark an import completed. After supplying files, use
+`/memory import [directory]`. Provably empty v6 snapshots can reopen safely; a zero claim
+count alone never authorizes replay of a real consumed ledger. See [migration details](recovery.md).
+
+These migration fixes do not replay an already completed real import or retroactively erase
 previously stored sensitive data. If an older import already lost revision information,
 use the preserved ledgers/backup to review and correct affected records; do not reset the
 migration marker or replace a populated database blindly.
@@ -395,10 +410,11 @@ JSONL, not changes made in the new database.
   automatically processes due work. `/memory status` distinguishes scheduled retries from
   paused sources and shows the next eligible time (the next poll may be up to 15 seconds
   later when no local work is queued). After a crash, the 150-second lease must expire first.
-  If a source reaches 5 failures, inspect its category: `timeout`, `output_limit`,
-  `invalid_output`, `write_rejected`, `stale`, `provider`, `unavailable`, `interrupted` or
-  `unknown`. Fix model/authentication or investigate repeated output/write rejection;
-  `/memory evolve` can then make one extra attempt without resetting the automatic budget.
+  Inspect source call/time/output limits as well as failure count. Status distinguishes
+  `auth`, `quota`, `rate_limit`, `context_limit`, `request`, `safety`, transport, output and
+  stale-write failures. Provider cooldowns are separate from source retry times; switching
+  providers cannot bypass the shared budget. `/memory evolve` makes one explicit source
+  attempt without resetting counters or overriding shared ceilings. See [error policy](recovery.md).
   A bad source remains saved/visible rather than being deleted or labeled successful.
 - **Persistent storage/import errors:** stop all Pi processes using that agent directory
   and back up the **entire** state directory, including any SQLite sidecars and legacy
@@ -411,4 +427,4 @@ JSONL, not changes made in the new database.
   stopped; do not mix one backup's database with another's WAL/SHM files.
 
 Diagnostics intentionally do not echo provider error bodies, which may contain secrets.
-`SQLite ok (schema 6)` checks database structure/record validity, not the truth of model claims.
+`SQLite ok (schema 7)` checks database structure/record validity, not the truth of model claims.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-memory-evolution",
-	"version": "0.2.4",
+	"version": "0.2.6",
 	"description": "Memory that maintains itself. Pi learns what matters, injects what this session needs, and recalls the rest — nothing to configure, no commands to learn.",
 	"license": "MIT",
 	"publishConfig": {

package/src/adapter/http-diagnostics.ts

@@ -0,0 +1,76 @@
+import type { Diagnostic } from '../memory/diagnostics.ts';
+import type { FailureCode } from '../memory/recovery.ts';
+
+// Only adapters verified to support request-local fetch injection. Never monkey-patch global fetch,
+// replace auth/proxy composition, or pass this option to SDKs (e.g. Google/Bedrock) that reject it.
+export const OBSERVABLE_HTTP_APIS = new Set(['openai-completions', 'openai-responses', 'azure-openai-responses',
+ 'openai-codex-responses', 'anthropic-messages', 'mistral-conversations']);
+const ERROR_CODES: Record<string, FailureCode> = {
+ insufficient_quota: 'quota', quota_exceeded: 'quota', billing_hard_limit_reached: 'quota', insufficient_balance: 'quota',
+ usage_limit_reached: 'quota', usage_not_included: 'quota',
+ context_length_exceeded: 'context_limit', max_context_length_exceeded: 'context_limit',
+ content_filter: 'safety', content_policy_violation: 'safety', safety: 'safety',
+};
+export function httpFailure(d: Diagnostic): FailureCode {
+ if (d.errorClass) return d.errorClass;
+ return d.httpStatus === 401 || d.httpStatus === 403 ? 'auth' : d.httpStatus === 402 ? 'quota'
+  : d.httpStatus === 429 ? 'rate_limit' : d.httpStatus === 408 ? 'timeout'
+  : [400, 404, 422].includes(d.httpStatus ?? 0) ? 'request' : 'provider';
+}
+export function observeStatus(d: Diagnostic, status: number, headers?: Record<string, string>, now = Date.now()): void {
+ if (Number.isSafeInteger(status) && status >= 100 && status <= 599) d.httpStatus = status;
+ const retry = Object.entries(headers ?? {}).find(([key]) => key.toLowerCase() === 'retry-after')?.[1];
+ if (retry) {
+  const delay = /^\d+(?:\.\d+)?$/u.test(retry.trim()) ? Number(retry) * 1000 : Date.parse(retry) - now;
+  // Preserve long waits (up to the JS timestamp range); never shorten a server's requested pause.
+  if (Number.isFinite(delay) && delay > 0 && now + delay <= 8_640_000_000_000_000) d.retryAfterMs = Math.ceil(delay);
+ }
+}
+/** Some SDKs (notably Google) return a complete JSON error document as errorMessage.
+ * Decode only that structural shape, not status-looking numbers or prose substrings. */
+export function observeStructuredError(d: Diagnostic, message?: string): void {
+ if (!message || Buffer.byteLength(message) > 8192) return;
+ try {
+  const value = JSON.parse(message);
+  const status = value?.error?.code ?? value?.status;
+  if (d.httpStatus === undefined && Number.isInteger(status) && status >= 400 && status <= 599) observeStatus(d, status);
+  const code = [value?.error?.code, value?.error?.type, value?.code].find(c => typeof c === 'string' && Object.hasOwn(ERROR_CODES, c));
+  if (code) d.errorClass = ERROR_CODES[code] as Diagnostic['errorClass'];
+ } catch { /* Opaque provider errors stay unknown; no raw text is retained or guessed from. */ }
+}
+export function diagnosticFetch(d: Diagnostic, signal: AbortSignal): typeof globalThis.fetch {
+ const underlying = globalThis.fetch;
+ return async (input, init) => {
+  const response = await underlying(input, init);
+  observeStatus(d, response.status, Object.fromEntries(response.headers));
+  if (response.status < 400) return response;
+  // Inspect only a bounded error JSON clone, without delaying the original body indefinitely.
+  // No free-form message, header, URL, credential or body is copied into the diagnostic.
+  const reader = response.clone().body?.getReader();
+  if (!reader) return response;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const inspect = async () => {
+   const chunks: Uint8Array[] = []; let bytes = 0;
+   while (!signal.aborted) {
+    const { done, value } = await reader.read(); if (done) break;
+    bytes += value.byteLength; if (bytes > 8192) return;
+    chunks.push(value);
+   }
+   if (signal.aborted) return;
+   try {
+    const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    const code = [value?.error?.code, value?.error?.type, value?.code].find(c => typeof c === 'string' && Object.hasOwn(ERROR_CODES, c));
+    if (code) {
+     d.errorClass = ERROR_CODES[code] as Diagnostic['errorClass'];
+     const reset = value?.error?.resets_at;
+     if (d.errorClass === 'quota' && Number.isSafeInteger(reset) && reset * 1000 > Date.now() && reset * 1000 <= 8_640_000_000_000_000)
+      d.retryAfterMs = Math.max(d.retryAfterMs ?? 0, reset * 1000 - Date.now());
+    }
+   } catch { /* Unknown/HTML/oversized bodies retain only the status. */ }
+  };
+  try { await Promise.race([inspect(), new Promise<void>(resolve => { timer = setTimeout(resolve, 200); })]); }
+  catch { /* Diagnostics must not change the provider's response handling. */ }
+  finally { clearTimeout(timer); void reader.cancel().catch(() => {}); }
+  return response;
+ };
+}