memorio 4.9.10 → 4.9.31

package/AGENTS.md

@@ -1,126 +1,126 @@
-# AGENTS.md — working with `memorio`
-
-Operational conventions for AI coding agents working in a repository that depends on `memorio`.
-See `README.md` and `llms.txt` for the full API. This file is decision rules: what to reach for,
-when, and the specific footguns this library's own docs flag.
-
-## Read this before generating any `memorio` code
-
-`memorio`'s own `llms.txt` contains an explicit unresolved discrepancy:
-
-> **Locking — VERIFY BEFORE PUBLISHING:** one source describes per-key locking
-> (`state.config.lock()` freezes only `config`); another describes global locking
-> (`state.lock()` / `state.unlock()` freezing everything). Do not generate code against this
-> section until it's resolved against the real source.
-
-**Do not write or suggest `.lock()` / `.unlock()` calls with a confident claim about scope**
-(per-key vs. global) until you've confirmed the actual signature against the installed
-package's type definitions or source — `node_modules/memorio/dist/*.d.ts` — in the target repo.
-If you can't confirm it, say so explicitly rather than picking one behavior and presenting it
-as fact.
-
-## Choosing a layer
-
-Don't default to `state` for everything just because it's the one-liner in the README. Walk the
-decision tree from the README's ["Which layer should I use"](./README.md#which-layer-should-i-use)
-section, and in particular:
-
-| If the data is... | Use | Not |
-| --- | --- | --- |
-| UI-reactive, doesn't need to survive reload | `state` | `store` (unnecessary persistence) |
-| Small, must survive reload, any tab | `store` | `idb` (overkill for simple k/v) |
-| Must survive reload, this tab only | `session` | `store` (wrong scope) |
-| Relational, needs joins/SQL | `sqlite` | `idb` (no query language) |
-| Structured, needs confidence/TTL/source/history | `memory` | `state`/`store` (no lifecycle semantics) |
-| Large or structured, browser-only | `idb` | `store` (size/shape limits) |
-
-`sqlite` and `memory` answer different questions — "what data do I have" vs. "what does the app
-believe, and how sure is it." Don't reach for `memory` just because a value happens to come from
-an LLM; if it doesn't need confidence scoring, TTL, or supersession history, plain `state`/`store`
-is simpler and correct.
-
-## Server-side and multi-request code — read this first
-
-**`state` is a shared global namespace by default.** A value set in one request handler is
-visible to every other read of `state` in the same process. There is no automatic per-request
-or per-tab isolation.
-
-Before generating any server-side code (API route, edge function, worker) that could handle more
-than one user or request in the same process:
-
-1. Create an explicit context per request/tenant: `const ctx = memorio.createContext(id)`, then
-   read/write via `ctx.state`, never the bare global `state`.
-2. **Generate the context ID from trusted server-side data** (authenticated user id, request-scoped
-   token) — never directly from client-controlled input. Contexts are a key-prefix convention, not
-   a hard boundary, so a spoofable ID is a real collision risk, not just a naming concern.
-3. Treat context isolation as *organizational*, not a security boundary. It does not replace
-   authorization checks at the backend layer — never use it as the only thing standing between
-   one tenant's data and another's.
-
-If the code you're generating is client-side (a single browser tab, one user), bare `state` is
-fine — this concern is specific to shared-process server/edge code.
-
-## Known rough edges — don't paper over these in generated code
-
-- **`store.quota()` returns `[0, 0]` for the `localStorage` backend** — it's a placeholder, not a
-  real reading. Don't generate capacity-check logic that branches on its result for `store`.
-  It may be meaningful for `idb`, but confirm before relying on it there too.
-- **`idb` is disabled outright in Node.js/Deno** (calls warn and no-op). Any code that might run
-  outside a guaranteed browser context must guard: `if (idb.db.support())` or check
-  `memorio.getCapabilities().hasIndexedDB` — don't rely on the no-op warning alone reaching a log
-  anyone will see.
-- **`sqlite` persistence serializes the entire database on every flush** — not incremental. Never
-  generate code that calls a persisting write inside a loop; batch writes in one transaction/run
-  and persist once after the batch, per the README's guidance.
-- **`observer('state.some.path', cb)` paths are plain strings, unchecked against `state`'s actual
-  shape.** A typo or a later rename fails *silently* — the observer just never fires again. Prefer
-  `memorio.typed<T>()` + `registerSchema()` for anything you'd hate to have silently stop working,
-  and consider `memorio.pathExists('state.some.path')` as a startup sanity check for
-  observer-heavy code.
-- **`memory.context()` is rule-based (tags/type/confidence/recency), not embedding-based.** Don't
-  imply semantic/meaning-based retrieval in comments or docs you generate — if the task genuinely
-  needs free-text similarity search, pair `memorio.memory` (for lifecycle: confidence, TTL,
-  supersession) with a separate embedding store, don't fake it with `context()` alone.
-- **`memorio.logger` records the literal value written**, including tokens or PII, in
-  `getHistory()` / `exportLogs()`. Never enable it unconditionally on a production path that
-  touches sensitive data, and never wire `exportLogs()` output to analytics or error reporters
-  without redaction first.
-- **Nothing in `store`, `session`, `idb`, or `memory` is encrypted.** Don't store auth tokens or
-  regulated data in any of these layers without adding your own encryption — flag it in code
-  review comments if you see it happening.
-
-## React usage
-
-`useObserver` has two modes — pick deliberately, don't mix them by accident:
-
-```tsx
-// Auto-discovery: re-runs when any state path touched during the callback changes
-useObserver(() => { console.debug('counter:', state.counter) }, state.counter)
-
-// Explicit deps: only re-runs when the listed paths change
-useObserver(() => { console.debug('user:', state.user) }, [state.user])
-```
-
-`useObserver` is a thin bridge onto `observer` — it inherits the "unchecked path string" caveat
-above for any path passed in string form.
-
-## Cross-platform code
-
-Before calling `idb`, `sqlite`, or `devtools`, or before relying on `store`/`session` durability,
-check `memorio.getCapabilities()` rather than branching on `memorio.isNode()`/`isBrowser()` alone
-— capabilities can differ inside a single platform category (e.g. some edge runtimes expose
-`localStorage`, some don't). Generated code that assumes "browser == has IndexedDB" or
-"Node == no persistence at all" will be wrong on edge runtimes.
-
-## Testing
-
-When testing `memory` lifecycle behavior (supersession, TTL, confidence), assert on the *history*
-being preserved, not just the current `recall()` value — `update()` is documented to supersede,
-not overwrite, and a test that only checks the latest value won't catch a regression that
-silently starts overwriting instead.
-
-## Related examples
-
-See `examples/` in this repo for runnable reference implementations:
-`multi-tenant-context.ts`, `react-observer.tsx`, `semantic-memory.ts`,
-`sqlite-batched-writes.ts`, and `cross-platform-guards.ts`.
+# AGENTS.md - working with `memorio`
+
+Operational conventions for AI coding agents working in a repository that depends on `memorio`.
+See `README.md` and `llms.txt` for the full API. This file is decision rules: what to reach for,
+when, and the specific footguns this library's own docs flag.
+
+## Read this before generating any `memorio` code
+
+`memorio`'s own `llms.txt` contains an explicit unresolved discrepancy:
+
+> **Locking - VERIFY BEFORE PUBLISHING:** one source describes per-key locking
+> (`state.config.lock()` freezes only `config`); another describes global locking
+> (`state.lock()` / `state.unlock()` freezing everything). Do not generate code against this
+> section until it's resolved against the real source.
+
+**Do not write or suggest `.lock()` / `.unlock()` calls with a confident claim about scope**
+(per-key vs. global) until you've confirmed the actual signature against the installed
+package's type definitions or source - `node_modules/memorio/dist/*.d.ts` - in the target repo.
+If you can't confirm it, say so explicitly rather than picking one behavior and presenting it
+as fact.
+
+## Choosing a layer
+
+Don't default to `state` for everything just because it's the one-liner in the README. Walk the
+decision tree from the README's ["Which layer should I use"](./README.md#which-layer-should-i-use)
+section, and in particular:
+
+| If the data is... | Use | Not |
+| --- | --- | --- |
+| UI-reactive, doesn't need to survive reload | `state` | `store` (unnecessary persistence) |
+| Small, must survive reload, any tab | `store` | `idb` (overkill for simple k/v) |
+| Must survive reload, this tab only | `session` | `store` (wrong scope) |
+| Relational, needs joins/SQL | `sqlite` | `idb` (no query language) |
+| Structured, needs confidence/TTL/source/history | `memory` | `state`/`store` (no lifecycle semantics) |
+| Large or structured, browser-only | `idb` | `store` (size/shape limits) |
+
+`sqlite` and `memory` answer different questions - "what data do I have" vs. "what does the app
+believe, and how sure is it." Don't reach for `memory` just because a value happens to come from
+an LLM; if it doesn't need confidence scoring, TTL, or supersession history, plain `state`/`store`
+is simpler and correct.
+
+## Server-side and multi-request code - read this first
+
+**`state` is a shared global namespace by default.** A value set in one request handler is
+visible to every other read of `state` in the same process. There is no automatic per-request
+or per-tab isolation.
+
+Before generating any server-side code (API route, edge function, worker) that could handle more
+than one user or request in the same process:
+
+1. Create an explicit context per request/tenant: `const ctx = memorio.createContext(id)`, then
+   read/write via `ctx.state`, never the bare global `state`.
+2. **Generate the context ID from trusted server-side data** (authenticated user id, request-scoped
+   token) - never directly from client-controlled input. Contexts are a key-prefix convention, not
+   a hard boundary, so a spoofable ID is a real collision risk, not just a naming concern.
+3. Treat context isolation as *organizational*, not a security boundary. It does not replace
+   authorization checks at the backend layer - never use it as the only thing standing between
+   one tenant's data and another's.
+
+If the code you're generating is client-side (a single browser tab, one user), bare `state` is
+fine - this concern is specific to shared-process server/edge code.
+
+## Known rough edges - don't paper over these in generated code
+
+- **`store.quota()` returns `[0, 0]` for the `localStorage` backend** - it's a placeholder, not a
+  real reading. Don't generate capacity-check logic that branches on its result for `store`.
+  It may be meaningful for `idb`, but confirm before relying on it there too.
+- **`idb` is disabled outright in Node.js/Deno** (calls warn and no-op). Any code that might run
+  outside a guaranteed browser context must guard: `if (idb.db.support())` or check
+  `memorio.getCapabilities().hasIndexedDB` - don't rely on the no-op warning alone reaching a log
+  anyone will see.
+- **`sqlite` persistence serializes the entire database on every flush** - not incremental. Never
+  generate code that calls a persisting write inside a loop; batch writes in one transaction/run
+  and persist once after the batch, per the README's guidance.
+- **`observer('state.some.path', cb)` paths are plain strings, unchecked against `state`'s actual
+  shape.** A typo or a later rename fails *silently* - the observer just never fires again. Prefer
+  `memorio.typed<T>()` + `registerSchema()` for anything you'd hate to have silently stop working,
+  and consider `memorio.pathExists('state.some.path')` as a startup sanity check for
+  observer-heavy code.
+- **`memory.context()` is rule-based (tags/type/confidence/recency), not embedding-based.** Don't
+  imply semantic/meaning-based retrieval in comments or docs you generate - if the task genuinely
+  needs free-text similarity search, pair `memorio.memory` (for lifecycle: confidence, TTL,
+  supersession) with a separate embedding store, don't fake it with `context()` alone.
+- **`memorio.logger` records the literal value written**, including tokens or PII, in
+  `getHistory()` / `exportLogs()`. Never enable it unconditionally on a production path that
+  touches sensitive data, and never wire `exportLogs()` output to analytics or error reporters
+  without redaction first.
+- **Nothing in `store`, `session`, `idb`, or `memory` is encrypted.** Don't store auth tokens or
+  regulated data in any of these layers without adding your own encryption - flag it in code
+  review comments if you see it happening.
+
+## React usage
+
+`useObserver` has two modes - pick deliberately, don't mix them by accident:
+
+```tsx
+// Auto-discovery: re-runs when any state path touched during the callback changes
+useObserver(() => { console.debug('counter:', state.counter) }, state.counter)
+
+// Explicit deps: only re-runs when the listed paths change
+useObserver(() => { console.debug('user:', state.user) }, [state.user])
+```
+
+`useObserver` is a thin bridge onto `observer` - it inherits the "unchecked path string" caveat
+above for any path passed in string form.
+
+## Cross-platform code
+
+Before calling `idb`, `sqlite`, or `devtools`, or before relying on `store`/`session` durability,
+check `memorio.getCapabilities()` rather than branching on `memorio.isNode()`/`isBrowser()` alone
+- capabilities can differ inside a single platform category (e.g. some edge runtimes expose
+`localStorage`, some don't). Generated code that assumes "browser == has IndexedDB" or
+"Node == no persistence at all" will be wrong on edge runtimes.
+
+## Testing
+
+When testing `memory` lifecycle behavior (supersession, TTL, confidence), assert on the *history*
+being preserved, not just the current `recall()` value - `update()` is documented to supersede,
+not overwrite, and a test that only checks the latest value won't catch a regression that
+silently starts overwriting instead.
+
+## Related examples
+
+See `examples/` in this repo for runnable reference implementations:
+`multi-tenant-context.ts`, `react-observer.tsx`, `semantic-memory.ts`,
+`sqlite-batched-writes.ts`, and `cross-platform-guards.ts`.