memorio 5.1.3 → 5.2.0

package/AGENTS.md

@@ -6,18 +6,20 @@ 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:
+`memorio`'s `llms.txt` previously flagged an unresolved locking-scope discrepancy. It is now
+resolved against the installed source: `memorio` implements **both** lock scopes with distinct,
+non-overlapping method names:
 
-> **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.
+- **Global:** `state.lock()` / `state.unlock()` — blocks all writes (set, deep mutation, array
+  mutation, and delete) across the entire `state` tree while held.
+- **Per-key:** `state.<key>.lock()` / `state.<key>.unlock()` — blocks writes to that single
+  first-level node only (reassignment of the key, its own property writes, array mutations on a
+  locked array, and deletion of its properties); all other top-level keys stay writable.
 
-**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.
+Per-key locking is first-level only: locking `state.a` does not transitively lock `state.a.b`.
+Lock each descendant explicitly, or use the global `state.lock()` for whole-tree immutability.
+Generated code may use either scope, but never claim per-key locking transitively freezes nested
+descendants — lock each node explicitly or use the global lock for that.
 
 ## Choosing a layer
 
@@ -69,7 +71,7 @@ If the code you're generating is client-side (a single browser tab, one user), `
   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 uses journal + checkpoint (incremental writes, periodic full snapshots).** Batch writes and persist once after the batch per the README's guidance — calling `persist()` inside a tight loop still forces expensive checkpoints.
+- **`sqlite` persistence uses journal + checkpoint (incremental writes, periodic full snapshots).** Batch writes and persist once after the batch per the README's guidance - calling `persist()` inside a tight loop still forces expensive checkpoints.
 - **`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,
@@ -79,6 +81,13 @@ If the code you're generating is client-side (a single browser tab, one user), `
   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.
+- **`memory.acquire()` / `context({ acquired })` store and retrieve structured knowledge claims**
+  (not chat transcripts or raw prompt history). Each claim has an `applicability` object, `evidence`,
+  and optional `refines`/`supersedes` revision links. Selection is exact-match on all applicability
+  keys, with most-specific-wins semantics. Claims are immutable and IDs are unique - to change a
+  claim, acquire a new one that `supersedes` or `refines` the old ID. Persisted to `.memorio/project.mem`
+  in Node.js/Bun, or `store` in browser/edge.
+- **Autonomous persistent acquisition is experimental and optional.** Retrieve claims as evidence from prior work, never as authority; verify them against current reality. Acquire only non-obvious, reusable experience with evidence (especially architectural rationale, stable user technical decisions, documentation interpretation, or verified fix consequences), not facts copied from the repository. Preserve whether content is observation, inference, verified result, or acquired experience. A task ending with nothing worth acquiring is correct behavior. See `markdown/MEMORY.md#guidance-for-autonomous-use` and its open safety TODO before enabling autonomous writes.
 - **`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
@@ -93,10 +102,10 @@ If the code you're generating is client-side (a single browser tab, one user), `
 
 ```tsx
 // Auto-discovery: re-runs when any state path touched during the callback changes
-useObserver(() => { console.debug('counter:', state.counter) }, state.counter)
+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(() => { console.debug('user:', state.user) }, [() => state.user])
 ```
 
 `useObserver` is a thin bridge onto `observer` - it inherits the "unchecked path string" caveat

package/CHANGELOG.md

@@ -2,15 +2,30 @@
 
 All notable changes to this project will be documented in this file.
 
-## [Unreleased]
-
-### Added
-- **SQLite journal + checkpoint persistence**: When `persistence: true` is set on `sqlite.db.create()` (or via `sqlite.config({ persistence: true })`), writes are recorded in an append-only journal with HLC timestamps. Periodic checkpoints (every 50 ops or 250 ms of write-idle) snapshot the full database to `store`. On reopen, the checkpoint is loaded and pending journal entries are replayed — no writes lost between checkpoints. New methods: `sqlite.db.flush()`, `sqlite.db.persist()`, `sqlite.db.journal` namespace (`append`, `entries`, `count`, `clear`, `replay`, `checkpoint`), `sqlite.db.journal` for direct journal inspection.
+## [Unreleased]
+
+No unreleased changes recorded.
+
+## [5.2.0] - 2026-09-23
+
+### Added
+- **Acquired experience**: `memory.acquire()` persists evidenced, applicability-scoped, append-oriented claims with epistemic type, provenance, acquisition time, and `refines` / `supersedes` / `retracts` history.
+- **Acquired Experience Discovery**: `memory.discover(situation, { depth, maxCandidates })` finds a deterministic, conservative set of active acquired-experience candidates from ordinary situation text. Results include match explanations and may correctly be empty; this is lexical/structured retrieval, not semantic search or a truth decision.
+- **Context Projection**: `memory.project(discovery, { maxCandidates, maxCharacters })` produces bounded structured experiences plus reusable AI-context text, preserves complete units and epistemic/applicability/provenance/evidence boundaries, and reports omitted candidates. Projected memory remains untrusted prior context that must be verified against current reality.
+- **Acquire → Discover → Project workflow**: public documentation and the runnable `acquired-knowledge.ts` example now demonstrate the complete production lifecycle while keeping exact `memory.context({ acquired })` selection separate.
+- **Portable MEM packages**: current writes use inspectable ZIP/JSON `memorio.package` v1 with MAP/DATA separation, SHA-256 integrity, production `inspectMem()`, and optional Ed25519 signatures through `signMemPackage()`.
+- **Logic PHASE 0**: public `logic` / `LogicEngine` APIs record and select structured situation/action/outcome experience in an isolated `.memorio/logic/logic.mem` repository. This is precedent projection, not autonomous reasoning or PHASE 1.
+- **SQLite journal + checkpoint persistence**: When `persistence: true` is set on `sqlite.db.create()` (or via `sqlite.config({ persistence: true })`), writes are recorded in an append-only journal with HLC timestamps. Periodic checkpoints (every 50 ops or 250 ms of write-idle) snapshot the full database to `store`. On reopen, the checkpoint is loaded and pending journal entries are replayed - no writes lost between checkpoints. New methods: `sqlite.db.flush()`, `sqlite.db.persist()`, `sqlite.db.journal` namespace (`append`, `entries`, `count`, `clear`, `replay`, `checkpoint`), `sqlite.db.journal` for direct journal inspection.
+
+### Fixed
+- **Public Logic declarations**: checked-in package declarations now expose `logic`, `LogicEngine`, and `memorio.logic` consistently with the runtime entry point.
+- **Release documentation and package contents**: synchronized the README, memory/MEM/Logic/security references, ADR classifications, project checkpoint, and navigation with verified 5.2.0 behavior; `SECURITY-HARDENING.md` remains included in the npm package.
+- **`package.json` `sideEffects`**: Added `./core/global.ts` to the `sideEffects` array so that esbuild/tsup no longer tree-shakes the `import './core/global'` side-effect-only import in `index.ts`. Without this fix, the `core/global.ts` initialization block (which defines `globalThis.memorio`) was eliminated from production builds, causing `memorio.global()` to throw `Cannot read properties of undefined (reading 'global')`.
 
 ## [5.1.2] - 2026-09-14
 
 ### Fixed
-- **`types/encryption.d.ts`**: Fixed parse error (`TS1005: ',' expected`) in `deriveKey` signature — missing comma after `alg` parameter caused all consumers' type checkers to fail, even with `skipLibCheck: true`.
+- **`types/encryption.d.ts`**: Fixed parse error (`TS1005: ',' expected`) in `deriveKey` signature - missing comma after `alg` parameter caused all consumers' type checkers to fail, even with `skipLibCheck: true`.
 - **`core/platform.ts`**: `_isBun()` now checks `typeof globalAny.Bun.version === 'string'` instead of `typeof globalAny.Bun.sqlite === 'function'`, correctly detecting the Bun runtime so `hasBunSqlite()` returns `true` and the `bun:sqlite` backend loads.
 - **`functions/sqlite/tools/bun-sqlite-adapter.ts`**: Removed unused `_index` variable.
 - **`functions/security/index.ts`**: Removed redundant type re-export block that conflicted with inline `export type`/`export interface` declarations under `isolatedModules`.
@@ -18,7 +33,7 @@ All notable changes to this project will be documented in this file.
 - **`extension/vscode/esbuild.config.mjs`**: Replaced TypeScript type annotations with JSDoc `/** @type */` to fix parse errors in `.mjs` context.
 
 ### Packaging
-- **`package.json`**: Changed `"sideEffects": true` to `"sideEffects": ["./global.js", "./global.cjs"]` so tree-shaking works for consumers using only `state`/`store` — previously the entire engine (SQLite, memory, encryption) was bundled unconditionally.
+- **`package.json`**: Changed `"sideEffects": true` to `"sideEffects": ["./global.js", "./global.cjs"]` so tree-shaking works for consumers using only `state`/`store` - previously the entire engine (SQLite, memory, encryption) was bundled unconditionally.
 - Added `types/bun-sqlite.d.ts` module declaration so `import('bun:sqlite')` resolves under TypeScript.
 
 ### Migration guide: globals change (v5 breaking change)
@@ -26,16 +41,16 @@ All notable changes to this project will be documented in this file.
 **Upgrading from 4.x:** the globals (`state`, `store`, `session`, `cache`, `idb`, `observer`, `useObserver`) are no longer installed by `import "memorio"`. Applications that use them without importing them must change one line:
 
 ```ts
-// 4.x — globals installed on import
+// 4.x - globals installed on import
 import 'memorio'
 
-// 5.x — globals installed via the global entrypoint
+// 5.x - globals installed via the global entrypoint
 import 'memorio/global'
 ```
 
 Nothing else changes. The named imports (`import { state } from 'memorio'`) work identically.
 
-**Bundler cache:** after upgrading, restart the dev server and clear `node_modules/.vite` (Vite) or `.next/cache` (Next.js), because a stale pre-bundle can mask the breakage — the app may appear to work and then fail at the next dependency re-optimisation.
+**Bundler cache:** after upgrading, restart the dev server and clear `node_modules/.vite` (Vite) or `.next/cache` (Next.js), because a stale pre-bundle can mask the breakage - the app may appear to work and then fail at the next dependency re-optimisation.
 
 ## [5.1.0] - 2026-09-12
 

package/README.md

@@ -4,7 +4,6 @@
 
 [![npm version](https://img.shields.io/npm/v/memorio)](https://www.npmjs.com/package/memorio)
 [![license](https://img.shields.io/npm/l/memorio)](./LICENSE)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/memorio)](https://bundlephobia.com/package/memorio)
 [![Socket Badge](https://socket.dev/api/badge/npm/package/memorio)](https://socket.dev/npm/package/memorio)
 [![Known Vulnerabilities](https://snyk.io/test/npm/memorio/badge.svg)](https://snyk.io/test/npm/memorio)
 [![zero deps](https://img.shields.io/badge/dependencies-0-brightgreen)](#security)
@@ -13,14 +12,10 @@
 ![Edge Workers](https://img.shields.io/badge/Edge%20Workers-compatible-gray)
 ![TypeScript](https://img.shields.io/badge/TypeScript-native-gray?logo=typescript)
 ![React](https://img.shields.io/badge/React-compatible-gray?logo=react)
-![Tests](https://img.shields.io/badge/tests-500+%20passed-green)
 [![license](https://img.shields.io/npm/l/memorio.svg)](#license)
 
-<!--
-[![CI](https://img.shields.io/github/actions/workflow/status/GITHUB_ORG/GITHUB_REPO/ci.yml?branch=main)](https://github.com/GITHUB_ORG/GITHUB_REPO/actions)
--->
 
-**The memory layer for AI agents and apps — owned by the user, not the vendor.**
+**The memory layer for AI agents and apps - owned by the user, not the vendor.**
 
 ```ts
 import 'memorio/global'
@@ -41,13 +36,13 @@ Just data, available where your application needs it.
 
 That's the whole API for the simple case. No provider tree, no boilerplate.
 
-But real apps grow. Most AI-powered apps (and most apps in general) eventually need more than "just state" — persistence, session data, caches, structured browser storage, local SQL, application memory, history, optional sync. Usually that means pulling in a different library — and a different mental model — for each. Memorio gives them one consistent runtime, without making the simple case complicated:
+But real apps grow. Most AI-powered apps (and most apps in general) eventually need more than "just state" - persistence, session data, caches, structured browser storage, local SQL, application memory, history, optional sync. Usually that means pulling in a different library - and a different mental model - for each. Memorio gives them one consistent runtime, without making the simple case complicated:
 
 ```ts
 state.value = 42
 ```
 
-But the reason memorio exists isn't just "fewer dependencies." It's this: **the memory an AI agent builds about a user shouldn't be locked inside a vendor's server, opaque, and impossible to inspect or move.** Memorio's memory layer is structured, inspectable, editable, and — when you turn on encryption — readable only with a key the vendor doesn't hold. It runs client-side, in the browser, on the edge, or in Node.
+But the reason memorio exists isn't just "fewer dependencies." It's this: **the memory an AI agent builds with a user and project shouldn't be locked inside a vendor's server, opaque, and impossible to inspect or move.** Memorio's memory layer is structured, inspectable, editable, and - when you turn on encryption - readable only with a key the vendor doesn't hold. It runs client-side, in the browser, on the edge, or in Node. AI provides intelligence; Memorio preserves selected acquired experience and continuity across sessions, models, providers, machines, and time.
 
 That said, this covers *structured* memory - preferences, decisions, facts with confidence and provenance - not semantic similarity search. If your agent needs "find things like this conversation," pair memorio with a dedicated vector store; see [`markdown/MEMORY.md`](./markdown/MEMORY.md).
 
@@ -84,17 +79,27 @@ Named imports (`import { state } from 'memorio'`) are unaffected. After upgradin
 Three things cover most apps - reactive state, persistence, and observation:
 
 ```ts
-import { state, persist, observer } from 'memorio'
+import { state, observer } from 'memorio'
 
 state.user = { name: 'Sara' }
 
-persist('state.user')
+const stopPersisting = state.persist('state.user')
 
 observer('state.user', user => {
   console.log(user)
 })
 ```
 
+`state.persist()` creates a bidirectional mirror between `state` (live in-memory)
+and `store` (durable copy). It seeds the initial value from `store` if present,
+then every write to that path flows to `store` automatically. The return value is
+an unsubscribe function - call it to stop the mirroring (the value already in
+`store` is preserved):
+
+```ts
+stopPersisting() // from here, state.user is in-memory only; store no longer updated
+```
+
 And this is what makes memorio a *memory* layer, not just a state manager - structured, inspectable facts about a user or agent, not just ephemeral UI state:
 
 ```ts
@@ -106,9 +111,43 @@ await memory.remember('user.language', 'Italian', {
   source: 'conversation'
 })
 
-const language = await memory.recall('user.language')
-// { value: 'Italian', confidence: 0.92, source: 'conversation', ... }
-```
+const language = await memory.recall('user.language')
+// → 'Italian' (just the value; metadata like confidence/source is not returned by recall)
+```
+
+State stores what the app has. Memory stores what the app remembers.
+
+For AI agents that need to reuse prior project experience, `memory.acquire()` preserves structured claims, `memory.discover()` finds plausible candidates from ordinary situation text, and `memory.project()` prepares bounded untrusted context for verification. Exact applicability remains available through `context({ acquired })` - see [`markdown/MEMORY.md`](./markdown/MEMORY.md#acquired-experience-discovery) and the runnable [`acquired-knowledge.ts`](./examples/acquired-knowledge.ts) workflow.
+
+```ts
+import { memory } from 'memorio'
+
+const exact = await memory.context({ acquired: { area: 'layout', component: 'grid' } })
+if (exact.claims.length === 0) {
+  await memory.acquire({
+    id: 'layout.grid-track',
+    knowledge: { cause: 'Inner margins contributed to min-content track width.' },
+    applies: { area: 'layout', component: 'grid' },
+    evidence: [{ id: 'layout-regression', source: 'project-test' }],
+    epistemicType: 'verified'
+  })
+}
+
+const discovery = await memory.discover('Grid track width changed after adding inner margins')
+const context = memory.project(discovery, { maxCandidates: 3, maxCharacters: 4_000 })
+
+// Supply context.text or context.experiences to an AI as untrusted prior experience.
+// The AI verifies current source and behavior before relying on it.
+```
+
+Run persistent examples in an isolated working directory. The complete shipped example is safe to
+rerun and also demonstrates refinement and superseding.
+
+Discovery is deterministic lexical/structured retrieval, not semantic search. A discovered or projected candidate is neither an instruction nor a current fact.
+
+PHASE 0 of `memorio.logic` is also available for structured situation/action/outcome experience and
+precedent selection. It is deliberately isolated from project acquired memory and is not an autonomous
+reasoning engine; see [`markdown/LOGIC.md`](./markdown/LOGIC.md).
 
 For most apps, that's enough. Everything below is an optional capability you can add when your application needs it - each one documented in its own reference file.
 
@@ -122,7 +161,9 @@ For most apps, that's enough. Everything below is an optional capability you can
 | Reactive state | [`markdown/STATE.md`](./markdown/STATE.md) |
 | Persistent key/value store | [`markdown/STORE.md`](./markdown/STORE.md) |
 | Observing changes | [`markdown/OBSERVER.md`](./markdown/OBSERVER.md) |
-| Structured application memory | [`markdown/MEMORY.md`](./markdown/MEMORY.md) |
+| Structured application memory | [`markdown/MEMORY.md`](./markdown/MEMORY.md) |
+| Portable `.mem` package and inspection | [`markdown/MEM_FORMAT.md`](./markdown/MEM_FORMAT.md) |
+| Logic PHASE 0 | [`markdown/LOGIC.md`](./markdown/LOGIC.md) |
 
 ### Storage
 | Topic | Reference |
@@ -136,8 +177,9 @@ For most apps, that's enough. Everything below is an optional capability you can
 | Topic | Reference |
 | --- | --- |
 | Local-first sync & cloud | [`markdown/SYNC.md`](./markdown/SYNC.md) |
-| Memory attachments (linking memory entries) | [`markdown/MEMORY-ATTACHMENT.md`](./markdown/MEMORY-ATTACHMENT.md) |
+| Memory attachments (linking memory entries) *(proposed, not yet implemented)* | [`markdown/MEMORY-ATTACHMENT.md`](./markdown/MEMORY-ATTACHMENT.md) |
 | History, undo/redo, snapshot, diff, trace | [`markdown/HISTORY.md`](./markdown/HISTORY.md) |
+| Temporal memory: time-travel query, branching, provenance | [`markdown/TEMPORAL.md`](./markdown/TEMPORAL.md) |
 
 ### Integrations
 | Topic | Reference |
@@ -157,7 +199,7 @@ For most apps, that's enough. Everything below is an optional capability you can
 | Runtime introspection | [`markdown/INSPECT.md`](./markdown/INSPECT.md) |
 | Browser DevTools | [`markdown/DEVTOOLS.md`](./markdown/DEVTOOLS.md) |
 | Security, encryption, threat model | [`SECURITY.md`](./SECURITY.md) |
-| Internal self-assessment *(not a third-party audit)* | [`markdown/SELF-ASSESSMENT.md`](./markdown/SELF-ASSESSMENT.md) |
+| Historical internal audit *(not a third-party audit)* | [`markdown/AUDIT-REPORT.md`](./markdown/AUDIT-REPORT.md) |
 
 ### Other
 | Topic | Reference |
@@ -172,9 +214,9 @@ For most apps, that's enough. Everything below is an optional capability you can
 Memorio is upfront about what it doesn't do, so you don't find out the hard way:
 
 - **No encryption by default.** Data is stored in plain text unless you explicitly turn on `memorio.encryption` or pass an `encryptionKey`. See [`SECURITY.md`](./SECURITY.md).
-- **Namespaces/contexts aren't a security boundary.** `memorio.isolate()` gives you logical separation between tenants or sessions, not authorization or access control — enforce that at your application layer.
-- **SQLite persistence uses a journal + checkpoint strategy.** Individual writes are recorded in an append-only journal (incremental); periodic checkpoints snapshot the full database. This avoids serializing the entire database on every write. The `bun:sqlite` backend doesn't support `export()` but handles persistence natively — see [`markdown/SQLITE.md`](./markdown/SQLITE.md).
-- **`memory.context()` is rule-based, not embedding-based.** It ranks structured entries by recency, confidence, and type — it does not do semantic similarity search. Pair it with a vector store if your agent needs "find things like this."
+- **Namespaces/contexts aren't a security boundary.** `memorio.isolate()` gives you logical separation between tenants or sessions, not authorization or access control - enforce that at your application layer.
+- **SQLite persistence uses a journal + checkpoint strategy.** Individual writes are recorded in an append-only journal (incremental); periodic checkpoints snapshot the full database. This avoids serializing the entire database on every write. The `bun:sqlite` backend doesn't support `export()` but handles persistence natively - see [`markdown/SQLITE.md`](./markdown/SQLITE.md).
+- **`memory.context()` is rule-based, not embedding-based.** It ranks structured entries by recency, confidence, and type - it does not do semantic similarity search. Pair it with a vector store if your agent needs "find things like this."
 - **Key management is your responsibility.** Memorio's encryption is client-side; it doesn't manage, rotate, or store keys for you.
 
 ---

package/SECURITY-HARDENING.md

@@ -0,0 +1,258 @@
+# Security Hardening Guide - Memorio
+
+> **Status**: Living document. Review before production deployment.
+
+---
+
+## 1. Global API is opt-in
+
+As of the current architecture, Memorio does **not** expose its APIs
+(`state`, `store`, `session`, `cache`, `idb`, `sqlite`, `observer`,
+`useObserver`) on `globalThis` automatically.
+
+```js
+import { state } from 'memorio'        // normal - no global exposure
+import 'memorio/global'                 // opt-in - exposes globals on globalThis
+```
+
+The `memorio.global()` method is callable programmatically but is **not**
+invoked automatically in any build mode. The decision to use the global API
+is a consumer choice signalled by the entrypoint imported - not inferred from
+`NODE_ENV`, `import.meta.env`, or any bundler environment variable.
+
+**Recommendation**: Prefer explicit named imports in application code.
+Only use `import 'memorio/global'` in controlled environments (e.g. a shell,
+REPL, or devtools context) where global exposure is intentional.
+
+---
+
+## 2. Storage layers are not encrypted by default
+
+None of Memorio's storage layers encrypt data at rest - encryption is **opt-in**.
+
+| Layer   | Storage backend | Encrypted by default? |
+|---------|-----------------|----|
+| `state` | In-memory Proxy | N/A (volatile) |
+| `cache` | In-memory Map   | N/A (volatile) |
+| `store` | `localStorage`  | No - opt-in via `store.config({ encryptionKey })` or per-call `{ encrypt }` |
+| `session` | `sessionStorage` | No - opt-in via `session.config({ encryptionKey })` or per-call `{ encrypt }` |
+| `idb`   | IndexedDB       | No (use `memorio.encryption` externally) |
+| `memory` (local/durable scopes) | `store`/`idb` | No - opt-in when backed by encrypted `store` |
+| `sqlite` (sql.js, persisted) | `store` (base64 checkpoint + journal entries) | No - opt-in when `store` is configured with an encryption key |
+
+**Do not store** auth tokens, regulated data (PII, PCI, PHI), credentials,
+or any other sensitive information in `store`, `session`, `idb`, `memory`, or
+`sqlite` without applying encryption first.
+
+Memorio ships an optional built-in encryption layer. Use it directly or
+configure auto-encrypt on store/session:
+
+```js
+import { memorio, store } from 'memorio'
+
+// Derive a key from a password (PBKDF2, 600k iterations - NIST SP 800-132)
+const key = await memorio.encryption.deriveKey('app-secret', 'app-salt')
+
+// Per-call encryption
+await store.set('api_token', secretValue, { encrypt: key })
+const token = await store.get('api_token', { decrypt: key })
+
+// Or configure a default key for transparent encryption
+store.config({ encryptionKey: key })
+await store.set('api_token', secretValue)  // encrypted automatically
+const value = await store.get('api_token')  // decrypted automatically
+```
+
+> ⚠️ Once encryption is enabled on `store`/`session`, `get`/`set` become
+> **asynchronous** (they return `Promise`s). See the sync/async warning in
+> `docs/SECURITY.md`. Always `await` these calls defensively.
+
+For contexts, pass `{ encryptionKey }` to `createContext()` / `isolate()` to
+enable encrypted multitenancy - see "Encrypted multitenancy" in `docs/SECURITY.md`.
+
+---
+
+## 3. Logger captures written values - including secrets
+
+When enabled, `memorio.logger` records the **literal value** written on every
+tracked state path, including tokens, PII, or any other data passed to
+`state.*` or `store.set()`.
+
+```js
+memorio.logger.configure({
+  modules: ['state', 'store']
+})
+state.token = 'eyJ...'   // ← logged verbatim in getHistory() / exportLogs()
+```
+
+**Rules**:
+- Never enable `logger` on production paths that handle sensitive data.
+- Never wire `memorio.logger.exportLogs()` output to analytics, error
+  reporters, or support tooling without redaction.
+- Treat `logger.getHistory()` output as sensitive - it contains raw write
+  values.
+
+---
+
+## 4. DevTools are opt-in
+
+DevTools (`memorio.devtools.inspect()`, `$state`, `$store`, etc.) are only
+available when the `memorio/global` entrypoint is imported. In normal usage
+(`import { state } from 'memorio'`), DevTools are not exposed on `globalThis`.
+
+Even when using `import 'memorio/global'`, DevTools are intended for
+**development/debugging only**. Do not ship `memorio/global` to production
+user-facing entry points.
+
+---
+
+## 5. Contexts and namespaces are organizational, not security boundaries
+
+`memorio.createContext(id)` isolates data by key-prefixing storage namespaces.
+This prevents accidental cross-tenant data bleed but does **not** enforce
+access control.
+
+**Server-side (Node.js / Edge Workers)**:
+
+```js
+// ✅ Correct: use context for request isolation
+const ctx = memorio.createContext(`req:${req.id}`)
+ctx.state.user = userData
+
+// ❌ Wrong: bare global state in multi-tenant server code
+state.user = userData  // visible across ALL requests in the process
+```
+
+**Rules**:
+- Generate context IDs from **trusted server-side data** (authenticated user
+  ID, request-scoped token). Never use client-controlled input directly.
+- Treat context isolation as **organizational**, not a security boundary.
+  Always enforce authorization at your backend layer.
+- Delete contexts after the request completes: `memorio.deleteContext(id)`.
+
+---
+
+## 6. Observer paths are unchecked strings
+
+`observer('state.user.email', cb)` accepts string paths that are **not**
+checked against `state`'s actual shape at compile time or at registration
+time. A typo or a later rename of the corresponding `state` key will cause the
+observer to silently stop firing.
+
+**Mitigation**: For paths that must not silently fail, prefer:
+
+```js
+import { memorio, state } from 'memorio'
+
+// Runtime sanity check
+if (!memorio.pathExists('state.user.email')) {
+  console.warn('State path does not exist: state.user.email')
+}
+
+// Or use typed stores + schema validation for compile-time + runtime safety
+```
+
+---
+
+## 7. SQLite persistence (journal + checkpoint)
+
+SQLite (`sql.js`) persistence uses an incremental **journal + checkpoint**
+strategy to avoid serializing the entire database on every write:
+
+1. **Journal**: every `db.run(sql, params)` write is recorded as an append-only
+   journal entry in `store` (localStorage), keyed with an HLC timestamp. Only
+   the changed SQL statement is stored - not the whole database.
+2. **Checkpoint**: every 50 operations (configurable via
+   `CHECKPOINT_INTERVAL`), or after 250 ms of write-idle, a full database
+   snapshot is exported to `store` and the journal is cleared up to that point.
+3. **Recovery**: on `create(name, { persistence: true })`, the latest checkpoint
+   is loaded first, then pending journal entries are replayed - so no writes are
+   lost between page reloads.
+
+```javascript
+// ❌ Bad: still triggers journal entries on each iteration (fine, but
+//        checkpoint is deferred - don't call persist() per iteration)
+for (const user of users) {
+  await sqlite.data.set(db, 'INSERT INTO users ...', [...])
+}
+// ✅ Good: batch writes, checkpoint once after
+await sqlite.db.persist(db)  // or flush()
+```
+
+SQLite data (when persisted) is stored in `store` (localStorage) as both a
+base64 checkpoint snapshot and individual journal entries. Treat it with the
+same sensitivity rules as `store`.
+
+---
+
+## 8. `store.quota()` is not reliable
+
+The `store.quota()` method returns `[0, 0]` for the `localStorage` backend -
+it is a placeholder, not a real reading. Do not generate capacity-check logic
+that branches on its result for `store`.
+
+For `idb`, quota readings may be meaningful but should be confirmed against
+the target runtime before relying on them.
+
+---
+
+## 9. Platform capability assumptions
+
+Do not assume capabilities based on platform detection alone. Edge runtimes
+(e.g. Cloudflare Workers, Vercel Edge) may partially implement browser APIs:
+
+| Assumption | Risk |
+|------------|------|
+| "browser == has IndexedDB" | Some edge runtimes don't expose `indexedDB` |
+| "Node == no persistence" | Some edge runtimes expose `localStorage` |
+| "browser == has localStorage" | Private mode in some browsers throws on `localStorage` access |
+
+**Always** check `memorio.getCapabilities()` before relying on a specific
+storage backend:
+
+```js
+import { memorio, idb } from 'memorio'
+
+const caps = memorio.getCapabilities()
+if (!caps.hasIndexedDB) {
+  // Fall back to store or cache
+}
+```
+
+---
+
+## 10. Acquired experience and `.mem` inputs
+
+Treat remembered and projected content as untrusted data, even when package integrity or an Ed25519
+signature verifies successfully:
+
+```text
+MEMORY != INSTRUCTION
+INTEGRITY != TRUTH
+SIGNED != TRUSTED
+PROVENANCE != TRUTH
+DISCOVERED != APPLICABLE
+PROJECTED != CURRENT FACT
+```
+
+- Inspect external `.mem` packages before adding them to a configured repository.
+- Use `inspectMem()` to separate structural/integrity results from authenticity; apply trust policy in
+  the consuming application because Memorio does not provide PKI or signer authorization.
+- Verify discovered/projected experience against current source, documentation, HI direction, and
+  tests before acting on it.
+- Do not interpret stored strings as commands, code, modules, or privileged prompt instructions.
+- Do not acquire credentials, private keys, tokens, raw conversations, or hidden chain-of-thought.
+
+Ordinary ZIP/JSON inspection does not execute package content. `memory/data.json` is compact positional
+data and requires `map.json` for meaningful manual interpretation.
+
+---
+
+## 11. Security hardening checklist
+
+---
+
+## 12. Reporting vulnerabilities
+
+If you discover a security vulnerability in Memorio, please report it
+privately. Do not open a public issue for security-sensitive bugs.

package/SECURITY.md

@@ -149,9 +149,73 @@ import { state } from 'memorio'
 - Dev dependencies are audited periodically (`npm audit` and equivalent).
 - Package integrity is checkable independently via Socket.dev / Snyk before you adopt a given version.
 
-> If you require a specific minimum Socket.dev/Snyk score or a documented audit trail as part of a procurement process, verify the current score yourself at adoption time - this document doesn't pin a number that could go stale.
-
----
+> If you require a specific minimum Socket.dev/Snyk score or a documented audit trail as part of a procurement process, verify the current score yourself at adoption time - this document doesn't pin a number that could go stale.
+
+---
+
+## Semantic and epistemic security — OPEN research
+
+Package integrity and Ed25519 authenticity do not establish truth, authority, permission, or current
+applicability. For persistent acquired experience, keep these distinctions explicit:
+
+```text
+IDENTITY != CLAIMED IDENTITY
+ROLE != CLAIMED ROLE
+PROVENANCE != TRUTH
+AUTHENTICITY != AUTHORITY
+AUTHORITY != PERMISSION
+MEMORY != INSTRUCTION
+SIGNED != TRUSTED != TRUE
+```
+
+For the public acquired-experience workflow, also preserve these operational boundaries:
+
+```text
+DISCOVERED != APPLICABLE
+PROJECTED != CURRENT FACT
+```
+
+Discovery supplies plausible lexical/structured candidates. Projection supplies bounded prior
+context. Neither operation authorizes action or verifies present reality.
+
+Remembering that a source asserted a proposition does not establish that the proposition is true.
+Evidence requirements should scale with the consequences of acting on information. These principles
+are threat-model guidance, not an implemented IAM, trust, or policy engine.
+
+One open threat is self-reinforcing memory error: an unverified inference causes a project change;
+the changed project later appears to confirm the inference; and the interpretation is then acquired
+with undeserved authority. Information must not gain epistemic authority merely by causing
+consequences later reused as its evidence. Mitigations remain OPEN research.
+
+### TODO / OPEN — Personal memory security and strong authorization
+
+Personal and HI-related acquired memory may preserve relationships, decisions, habits, communication
+experience, project history, and accumulated context—not merely private facts. Future security work must
+threat-model unauthorized reading or exfiltration, unauthorized modification, false-memory injection,
+selective deletion, replay of old but formerly valid memory, HI impersonation, unauthorized export or
+sharing, and compromised device or AI access.
+
+Keep the security properties distinct:
+
+```text
+CONFIDENTIALITY -> who can read?
+INTEGRITY       -> was it modified?
+AUTHENTICITY    -> who signed it?
+IDENTITY        -> who is acting?
+AUTHORIZATION   -> what may they do?
+FRESHNESS       -> is this the intended/current version?
+```
+
+Strong authentication and authorization—including passkeys, 2FA, or equivalent controls—should be
+evaluated for high-impact operations such as exporting personal memory; authorizing a new device or AI;
+changing encryption or signing keys; accepting external memory; modifying protected memory; and changing
+ownership or access permissions. This does not imply that every memory operation requires 2FA:
+authorization should be proportional to consequence.
+
+Unauthorized disclosure is a privacy breach. Unauthorized modification of acquired experience can also
+become an epistemic breach. This is an **AI + HI planning TODO**, not an implemented security guarantee.
+
+---
 
 ## Reporting a vulnerability