dotmem 0.0.5 → 0.0.8

package/MEMORY.md

@@ -0,0 +1,606 @@
+# dotmem Memory
+
+> **Status:** Current API reference for dotmem 0.0.8.
+
+dotmem has two distinct memory facilities on one `memory` object:
+
+- **Application memory** stores typed key/value entries through `remember`, `recall`,
+ `update`, and `forget`.
+- **Acquired experience** stores evidenced, applicability-scoped claims through
+ `acquire`, retrieves candidates with `discover`, and prepares bounded context with
+ `project`.
+
+Acquired experience is prior evidence, never executable instructions or current truth.
+Verify it against the current source, runtime, and direct evidence before acting on it.
+
+## Start
+
+```bash
+npm install dotmem
+npx dotmem init
+```
+
+```ts
+import { memory } from 'dotmem'
+
+await memory.acquire({
+ id: 'layout.grid.min-content',
+ knowledge: { cause: 'Inner margins contribute to min-content track sizing.' },
+ applicability: { area: 'layout', component: 'grid' },
+ evidence: [{ id: 'layout-regression', source: 'project-test' }],
+ epistemicType: 'verified'
+})
+
+const candidates = await memory.discover('Grid width changed after adding inner margins')
+const context = memory.project(candidates, { maxCandidates: 3, maxCharacters: 4_000 })
+```
+
+Initialization is lazy. `memory.init()` remains as a deprecated compatibility shim;
+new code should simply call the operation it needs.
+
+## Deterministic AI activation
+
+The activation phrases are `dotmem`, `.mem`, `load dotmem`, `Joy`, and `Jo`. A message that is exactly one
+of them, ignoring case, surrounding whitespace, and trailing punctuation, activates dotmem once
+for the session.
+
+### What are Joy and Jo?
+
+**Joy** is the canonical AI identity/profile for dotmem — the operational role name that comes from
+the profile, not from the runtime. **Jo** is an alternative shorthand for the same identity. They
+represent the assistant's persistent identity in the dotmem system (canonical profile, decision-making
+behavior, trust model, and relationship style).
+
+The canonical profile (`core/profile/`) defines:
+- **Identity & behavior** (`behavior.md`, `soul.md`) — character, relationship style, conversational behavior
+- **Trust model** (`trust.md`) — epistemic standards, verification requirements
+- **Decision framework** (`decision.md`) — how Jo evaluates and makes technical decisions
+- **Curiosity & learning** (`curiosity.md`) — what Jo seeks to understand and remember
+- **Language conventions** (`language.md`) — communication style
+
+When activated via `Joy` or `Jo`, dotmem loads this canonical profile as part of the deterministic
+discovery order. The profile is optional for basic memory operations but required for
+identity-gated features (carrier handshake, authority binding).
+
+### Activation Behavior
+
+Activation matching is **exact phrase only** (case-insensitive, trimmed, trailing punctuation ignored):
+- ✅ `Joy`, `joy`, `Joy.`, ` Joy `, `Jo`, `jo`, `Jo!`
+- ❌ `Hello Joy`, `Joyful`, `Joytron`, `My name is Jo`, `Joanna`
+
+Ordinary mentions of a name (e.g., "Jo said...") do not trigger activation. The matcher requires
+the entire message to be exactly one of the activation phrases.
+
+### Activation Procedure
+
+When the user explicitly says one of them, an AI must:
+
+1. Resolve the user dotmem home with `dotmem.paths.resolveUserDotMemPath()`.
+2. Read `<dotmem-home>/DOTMEM.md`.
+3. Load applicable user-level acquired experience.
+4. Resolve the current project identity with `dotmem.paths.resolveProjectIdentity()`.
+5. Resolve the project's memory with `dotmem.paths.resolveUserProjectMemoryPath(projectId)`.
+6. Read only that resolved project memory.
+
+Do not search the filesystem for `.mem` files. Deterministic resolution failure is a
+stop condition.
+
+## Storage and routing
+
+Every dotmem component obtains storage paths through one canonical resolver:
+`resolveDotMemStorageRoot()` (also `dotmem.paths.resolveDotMemStorageRoot()`).
+No component reconstructs paths on its own.
+
+Resolution precedence:
+
+1. **Runtime override** — the `DOTMEM_STORAGE_ROOT` environment variable, for testing,
+ CI, containers, and temporary development environments. An override is never
+ persisted by itself.
+2. **User locator** — `dotmem.location.json` (location metadata only) inside the stable
+ user anchor.
+3. **Default user-scoped storage** — the user anchor itself: `<user-home>/.mem`
+ (the platform-neutral canonical form; see the OS examples below), resolved from the
+ current runtime.
+
+The user anchor is resolved from the operating-system user at runtime. dotmem never
+scans drive roots, the filesystem root, or unrelated directories to find storage. A
+configured storage root that is missing, inaccessible, or invalid stops resolution with
+an explicit error — no silent fallback, no autonomous search, no guessed path. A path is
+reported only after it has been resolved or observed in the current runtime; otherwise
+report the semantic location (user memory, project memory, temporary staging, canonical
+storage, user anchor).
+
+Storage relocation is user-controlled and verified:
+
+```bash
+npx dotmem storage # semantic location + resolved storage root
+npx dotmem storage --root # resolved storage root only (scriptable)
+npx dotmem storage relocate <absolute-storage-dir> # migrate storage to an explicit absolute directory
+npx dotmem storage restore # migrate storage back to the default location
+```
+
+`relocate` copies the data, verifies it at the target, updates the locator, and only then
+reports completion; the locator never points at a location whose data has not been
+migrated and verified. The same verification applies to `restore` before the locator is
+removed.
+
+**Canonical form, platform-neutral.** The user anchor is written `<user-home>/.mem`
+everywhere in this documentation. It resolves at runtime to the current OS user's home:
+
+```text
+Example (OS-specific, illustrative only):
+ Windows: C:\Users\<user>\.mem
+ Linux: /home/<user>/.mem
+ macOS: /Users/<user>/.mem
+```
+
+The runtime resolves the actual home directory from the OS/environment; no hardcoded
+platform path is ever a default.
+
+On Node.js and Bun, the writer selects a store from the top-level acquisition fields:
+
+| Kind and scope | File |
+| --- | --- |
+| `experience`, `scope: 'project'` (default) | `$DOTMEM_HOME/projects/<project-id>.mem` |
+| `experience`, `scope: 'user'` | `$DOTMEM_HOME/user.mem` |
+| `agent` | `$DOTMEM_HOME/agent.mem` |
+| `logic` | `$DOTMEM_HOME/logic.mem` |
+
+`<project-id>` resolves in order from `DOTMEM_PROJECT_ID`, `package.json`'s `name`,
+then the current directory's basename. Set `sourceProject` when writing project
+experience for a project other than the current working directory.
+
+`applicability` is flat JSON-primitive matching metadata. It is not routing. A claim
+with `applicability.scope` but no top-level `scope` is rejected to avoid this mistake.
+`kind: 'relationship'` is rejected by `acquire`; relationship graph writes belong to
+the dedicated brain API.
+
+Browser and edge environments use the existing `store`-backed acquired-knowledge
+repository and never load Node filesystem code. The CLI is Node-only.
+
+## Acquisition safety
+
+`memory.acquire()` validates JSON-safe claim data, sanitizes secret-looking keys and
+values before persistence, and writes
+atomically, and verifies that the claim was persisted. Sanitization replaces sensitive
+content with a semantic marker such as `requiresToken: true`; it is not a secret vault,
+encryption policy, access-control system, or authorization decision.
+
+Only an explicit `kind` changes the physical store; advisory content classification
+never changes routing. Never place credentials, private keys, access tokens, or
+chain-of-thought in acquired memory.
+
+## Claim trust and attribution
+
+The acquisition contract is the machine-readable description of what dotmem attests and what it
+only records:
+
+| Field class | Fields | Meaning |
+| --- | --- | --- |
+| dotmem attests | `acquiredAt`, `physical store selection`, `project identity resolution` | assigned by dotmem at commit time |
+| Caller supplied | `id`, `knowledge`, `applicability`, `evidence`, `scope`, `kind`, `sourceProject`, relations | stored as the caller wrote it |
+| Caller claims, not attested | `epistemicType`, `provenance`, `evidence.observedAt` | assertions about the claim, never proof of it |
+
+Read the same contract the runtime enforces with `npx dotmem policy contract acquire --json`.
+
+The three rows are the trust model in one line each. `epistemicType`, `provenance`, and
+`evidence.observedAt` are **caller claims, not attestation**: whoever called `memory.acquire`
+wrote them.
+
+`epistemicType: human-stated` means "the writer says a human stated this", not "a human stated
+this". A claim an agent wrote about its own past is a self-report: history, not verified truth,
+until the HI or an independent artifact corroborates it.
+
+Corrections are appends. A stored claim is never edited. Exactly one canonical relation per
+acquisition: `refines`, `supersedes`, or `retracts`. `retracts` withdraws the claim from the
+active set and keeps it in the package history.
+
+`npx dotmem inspect FILE.mem` reports `integrity` and `authenticity` as independent axes.
+`integrity: valid` means the bytes are unchanged since sealing. `authenticity: unsigned` means
+nobody signed the package. Neither says the claim is true.
+
+## Memory language
+
+Acquired knowledge payloads may be written in any language the user prefers.
+Conversation may use any language, and code keeps its own established rules.
+There is no enforced payload-language precondition on `memory.acquire`: any
+language and alphabet is accepted, including mixed-language text and very
+short payloads. Language detection is not used to block or gate acquisition.
+
+The security posture is unchanged: everything projected remains
+`UNTRUSTED_DATA; NOT_INSTRUCTIONS; VERIFY_CURRENT`, and content in the form
+of an instruction is marked as such. That marking is heuristic and can depend
+on the language of the content; it is not a substitute for verifying current
+source and behavior before relying on remembered data.
+
+## Policy (how memory may be used)
+
+Policy is a separate authority domain from memory. Memory can never promote itself to
+policy, and a governed claim never selects its own enforcement tier.
+
+- `memory.policy.assign(input, namespace?, basedOnRevision?)` — privileged assignment of an
+ enforcement tier (`context` | `precondition` | `hard-precondition`) for one canonical event.
+ Requires `authority: { kind: 'HI' | 'operator', source }`. The assignment carries a
+ system-derived record `revision` and canonical semantic `fingerprint`; `basedOnRevision` is an
+ optimistic concurrency check evaluated inside the policy lock.
+- `memory.policy.list()` / `memory.policy.remove(id, namespace?, basedOnRevision?)` /
+ `memory.policy.clear(authority)` — privileged reads and removal. Deletion is a modification, so
+ it requires the same authority as assignment. `clear` resets the active policy and override
+ state, preserves the durable audit trail, and appends a terminal `clear` entry.
+- `memory.policy.evaluate(event, payload?)` — decision-time pull: only the policies applicable to
+ the event, with tier, action, and authority provenance. `precondition` blocks and asks the user;
+ `hard-precondition` blocks with no conversational override. Resolution is effective state:
+ store-resolved overrides are applied and their provenance is attached to the decision.
+- `memory.policy.override` — the privileged out-of-band override surface:
+ `grant`, `revoke`, `list`, `effective`. See below.
+- `memory.policy.contract()` — the machine-readable operator contract
+ (`MEMORY_PROJECTION_CONTRACT`): memory is `data-only`, untrusted, not instructions.
+- `memory.clear()` is memory-scoped and never deletes policy documents.
+
+### Privileged out-of-band policy override
+
+An override is **not a bypass**. It is an authorized, explicit, auditable change of effective
+policy state: the base policy is never modified, exactly one override is active per target, and
+the override is bound to the target's generation (`revision` + canonical `fingerprint`), both
+derived from the store — never accepted from a payload.
+
+- `memory.policy.override.grant(input, namespace?, basedOnRevision?)` — relax the effective tier
+ of one policy. Requires the target policy id, `relaxTo` (a valid tier, `context` is the floor),
+ a bounded `expiresAt` (window cap `MAX_OVERRIDE_WINDOW_MS`, 7 days), an explicit `reason`, and
+ authority. Hierarchy: an operator cannot relax an HI-owned policy. A new grant atomically
+ supersedes the previous active override.
+- `memory.policy.override.revoke(input, namespace?, basedOnRevision?)` — remove a relaxation and
+ restore the base policy. HI revokes any override; an operator revokes only operator-granted
+ overrides.
+- `memory.policy.override.list(namespace?)` — every override with its resolved state
+ (`ACTIVE` | `EXPIRED` | `STALE` | `INERT`).
+- `memory.policy.override.effective(event?, namespace?)` — effective state per policy: base tier,
+ effective tier, override state, and the provenance scar (override id, `relaxedFrom`, `by`,
+ `until`, `reason`).
+
+Override resolution is store-only and namespace-local: an override lives in the same document as
+the policy it targets, chat cannot invoke it, `memory.acquire` cannot create one, a payload
+cannot self-request it, and retrieved text or tool output cannot author one. A changed policy
+makes the override `STALE`, a deleted policy makes it `INERT`, and same-id recreation never
+resurrects it. Expiry and revocation both restore the base policy.
+
+Every mutation runs inside the cross-process policy namespace lock (exclusive create, owner
+identity, bounded retry, audited stale-lock break, fail-closed when exclusive creation cannot be
+verified) and is recorded in the durable in-document audit trail in the same atomic write. No
+override is effective without a recoverable durable audit record.
+
+## One canonical acquisition boundary
+
+Every path capable of producing durable memory crosses the same boundary
+(`core/knowledge/acquisition-boundary.ts`) before persistence: sanitize, strip
+non-authoritative fields and evaluate the `memory.acquire` policy against the
+payload. `memory.acquire` and the staged path
+(`memory.acquireStaged` → `commitStageFile`) both cross it, so direct and
+staged writes cannot diverge in enforcement. The staged commit additionally
+refuses a stage file that still contains secret shapes after the boundary
+re-sanitization. Equivalence tests pin the two paths to identical outcomes.
+
+Policy conditions are evaluated against the action payload, not merely discovered:
+
+| Condition outcome | Meaning | `precondition` behavior |
+| --- | --- | --- |
+| `satisfied` | the payload deterministically meets the condition | allow |
+| `violated` | the payload deterministically fails the condition | block and ask the user |
+| `unresolved` | the condition cannot be established (no payload) | block and ask the user — never assumed satisfied |
+
+`memory.acquire()` itself evaluates the policies applicable to the `memory.acquire` event against
+the payload about to be written and blocks with `PolicyPreconditionViolationError` when a
+precondition is violated or unresolved. Without any policy, acquisition behaves exactly as before.
+
+CLI: `npx dotmem policy <assign|list|remove|clear|eval|contract>`;
+`policy eval --event <event> [--payload <json>]` exits with code 2 when the event is blocked.
+Privileged override commands: `policy override grant|revoke|list` and `policy effective`
+(see `policy --help`). Canonical events so far: `artifact.write`, `memory.acquire`.
+
+Policy documents live under `policy/operator.policy.json` and `policy/security.policy.json`
+in the storage root, each carrying its records, overrides, and durable audit trail. Filesystem-level
+tamper isolation and policy signing remain open work (see `docs/SECURITY.md`).
+
+## Retrieval semantics
+
+- `memory.context({ acquired: query })` does exact applicability selection.
+- `memory.discover(situation)` performs deterministic lexical and structured candidate
+ retrieval. It is not embedding or semantic-vector search.
+- `memory.project(discovery)` returns bounded candidates and `text` marked as
+ untrusted prior context; it may omit candidates to meet its limits.
+
+`DISCOVERED != APPLICABLE` and `PROJECTED != CURRENT FACT`.
+
+`LABELLED != ATTESTED`: the epistemic label of a claim is written by the caller, never attested
+by dotmem. See [Claim trust and attribution](#claim-trust-attribution-and-correction).
+
+## Public API
+
+| API | Purpose |
+| --- | --- |
+| `init()` | Deprecated compatibility shim that prepares the runtime lazily. |
+| `acquire(opts)` | Persist an evidenced acquired claim using scope/kind routing. |
+| `discover(situation, options?)` | Find lexical/structured active candidates. |
+| `project(discovery, options?)` | Produce bounded, untrusted AI context. |
+| `context(opts)` | Exact acquired-context selection or ranked key/value retrieval. |
+| `policy.assign/list/remove/clear/evaluate/contract` | Privileged policy authority surface; see the Policy section. |
+| `policy.override.grant/revoke/list/effective` | Privileged out-of-band override surface; see the Policy section. |
+| `remember`, `recall`, `update`, `forget`, `patch` | Application key/value memory lifecycle. |
+| `stats`, `forgetExpired`, `clear` | Maintenance; `clear()` is destructive and memory-scoped. |
+| `createAgentMemory(agentId)` (`dotmem/agent`) | Agent-facing memory API with logical namespace partitioning per agent. |
+
+`AcquireOptions` includes `id`, `knowledge`, `applicability`, and `evidence`; optional
+fields are `epistemicType`, `provenance`, revision links, `scope`, `kind`, and
+`sourceProject`. See the checked-in type declaration at `types/memory.d.ts` for the
+precise TypeScript contract.
+
+`memory.context({ acquired })` returns `{ knowledgeVersion, claims: AcquiredClaim[] }`
+(the low-level acquired-context selection). The CLI `npx dotmem context --json` goes
+through `discover` + `project` and returns a `ContextProjection` envelope with
+`totalCandidates`, `omittedCandidates`, `experiences`, and `text`. The two surfaces are
+intentionally different: the API returns raw claims, the CLI returns bounded, projected
+context. `totalCandidates` is present on the CLI projection envelope, not on the raw
+`AcquiredContext` returned by `memory.context({ acquired })`.
+
+### Application Memory Scopes (remember/recall)
+
+The `memory.remember()` and `memory.recall()` operations support four scopes with
+different persistence characteristics per runtime:
+
+| Scope | Browser Storage | Node/Bun Storage | Survives Browser Reload | Survives Node/Bun Restart | Default For |
+|-------|-----------------|------------------|-------------------------|---------------------------|-------------|
+| `hot` | `state` (memory) | `state` (memory) | No | No | Never default; explicit only |
+| `session` | `sessionStorage` | In-memory `Map` | Yes (same tab) | No | Never default; explicit only |
+| `local` | `localStorage` | In-memory `Map` | Yes | No | Values ≤ 1 MB |
+| `durable` | IndexedDB (`idb`) | **Not available** | Yes | **No (browser only)** | Values > 1 MB |
+
+> **Key distinction**: The `durable` scope uses IndexedDB and is **browser-only**. In Node.js and
+> Bun, `store` and `session` fall back to in-memory `Map`s that do not survive a process restart.
+> For cross-restart persistence in Node/Bun, use `memory.acquire()` which writes `.mem` package
+> files to disk — this is the durable acquisition path, not the `memory.remember()` scope system.
+
+Scope resolution defaults (when `opts.scope` is not provided):
+- Values ≤ 1 MB → `local`
+- Values > 1 MB → `durable` (browser) / `local` (Node/Bun, since `durable` is unavailable)
+
+The `hot` and `session` scopes are only used when explicitly set via `opts.scope`.
+
+#### Scope Behavior Summary
+
+| Scope | Lifetime | Visibility | Owner/Namespace | Init | Clear |
+|-------|----------|------------|-----------------|------|-------|
+| `hot` | Process lifetime | Global `state` tree | Process | Lazy on first use | Process exit |
+| `session` | Session lifetime | `sessionStorage` (browser) / in-memory `Map` (Node/Bun) | Browser tab / process | Lazy on first use | Tab close / process exit |
+| `local` | Process lifetime (Node/Bun) or persistent (browser) | `localStorage` (browser) / in-memory `Map` (Node/Bun) | Origin / process | Lazy on first use | Manual `forget()` / `clear()` / browser clear |
+| `durable` | Persistent (browser only) | **N/A** | Origin | Lazy on first use | Manual `forget()` / `clear()` |
+
+> **Note**: `session` and `local` are behaviorally identical in Node/Bun (both use in-memory
+> `Map`s). The distinction exists only in browser environments. This is a known limitation;
+> no security or isolation boundary is implied by the scope names in Node/Bun.
+
+### Built-in seed claims
+
+dotmem ships with a small set of built-in seed claims that describe the
+acquisition logic itself. They are part of the product (`core/knowledge/logic-seed.ts`)
+and are loaded into the logic knowledge store on every installation:
+
+- `acquisition.experience-not-activity` — when to acquire (checkpoint principle)
+- `acquisition.value-sources` — where useful memory comes from
+- `acquisition.boundaries` — what to filter out, epistemic statuses
+- `acquisition.project-specific` — project-specific experience candidates
+- `relationship.continuity-pattern` — generalized AI-HI relationship pattern
+
+They are marked as `source: built-in seed (dotmem acquisition logic seed)` in
+`npx dotmem context --explain` output. They carry `epistemicType: inferred` and
+`provenance.source: 'dotmem acquisition logic seed'`. They are read-only reference
+material for the acquisition logic; they do not count as user-acquired experience.
+
+
+The same memory is reachable from three surfaces: the CLI (`npx dotmem`), the MCP server
+(`dotmem-mcp`, exposing `dotmem_context`, `dotmem_acquire`, and `dotmem_rules`), and
+the JavaScript API. The MCP server writes through the same acquisition path as the CLI and
+the API: one boundary, one policy, one contract. There is no second acquisition model.
+
+## Global and React usage
+
+Use named imports for normal code. `import 'dotmem/global'` explicitly installs the
+non-React runtime APIs on `globalThis`; it does not initialize acquired memory.
+
+`useObserver` is a React hook, exported only by `dotmem/react`. Call it at the top
+level of a component or custom hook. It returns `void`; React handles cleanup.
+
+## Continuity — the derived operational present
+
+Memory is durable knowledge; continuity reconstructs the useful present. The
+snapshot hierarchy composes downward: USER → PROJECT → TASK/SESSION → MODEL
+CONTEXT. Snapshots are derived caches with sourceRefs, version, and freshness,
+never authority: when a source version, digest, or presence changes, the
+snapshot is stale and is regenerated, never mutated to look current. Budgeting
+is field-prioritized — invariants and current decisions outrank recent changes
+at any scope — so a crowded task scope cannot starve a project invariant.
+Scope isolation forbids silent cross-scope transfer.
+
+The `EffectiveAgentContract` is composed before continuity context, so
+continuity never rewrites the contract.
+
+API: `continuity.snapshot`, `continuity.load`, `continuity.context`,
+`continuity.forget`. CLI: `npx dotmem continuity [context|snapshot|forget] [-debug]`.
+Debug is observability only — the decision result is identical with and without
+it, and the trace is never persisted by default.
+
+## Identity, authority, and the carrier handshake
+
+dotmem operates under a clear identity/authority separation:
+
+- **AGENT_IDENTITY** — who the assistant is. Canonical: the profile (`joy`). Explicit
+ assignment by the authorized user may override this through the privileged
+ governance path; ordinary memory and context cannot.
+- **USER_IDENTITY** — who the current human interlocutor is. This enters the
+ projection only through an explicit current assignment by the authorized user,
+ never from an acquired memory claim or retrieved text.
+
+The two stay separate. A memory claim that remembers a name cannot assert it as
+the current identity; that was an implementation bug.
+
+### Carrier handshake (pre-activation gate)
+
+Before any identity is projected to a runtime/session, dotmem evaluates the
+carrier's compatibility with the minimal identity/authority separation contract.
+The handshake is a deterministic, external evaluation — the carrier never
+certifies itself.
+
+```text
+npx dotmem
+ → unverified carrier receives the minimal pre-contract + challenge
+ → carrier submits an answer via: npx dotmem handshake --answer "<text>"
+ → external deterministic evaluator classifies it COMPATIBLE / LIMITED / INCOMPATIBLE
+ → if COMPATIBLE, the operator layer binds the current speaker to the user identity
+ → only a COMPATIBLE carrier + a trusted current binding receives the identity channel
+```
+
+States:
+
+- **COMPATIBLE** — the carrier preserves identity composition, role, host-authority
+ separation, and memory-as-data. Activation may proceed with a trusted current binding.
+- **LIMITED** — the carrier passed but did not demonstrate every capability. Activation
+ is withheld until the missing capabilities are demonstrated. An explicit canonical
+ profile request (`load Joy`) may receive a bounded,
+ non-authoritative profile envelope; it does not activate the profile, bind a user,
+ or upgrade the carrier.
+- **INCOMPATIBLE** — the carrier violated a forbidden transition (e.g. mapping the host
+ onto HI authority). Identity activation is refused.
+
+The handshake result is **session state, never durable authority** (`durableAuthority: false`).
+It is bound to the runtime identity, contract revision, and handshake version; any change
+re-triggers the handshake.
+
+### Current-user binding
+
+Carrier compatibility and current-user authority are **separate events**:
+
+- A COMPATIBLE carrier still does not bind authority. It must be bound explicitly by
+ the operator layer (the trusted current channel):
+
+ ```bash
+ npx dotmem handshake --bind-hi "<user name>" --scope "<scope>"
+ ```
+
+- The bind is scoped and current: it records `boundHIIdentity` (the identity bound to
+ this session) and `authorizationScope` (the scope of that binding). It is never
+ inferred from memory, history, files, or conversation.
+- `--unbind` clears the current binding; the remembered identity stays informational.
+- `--reset` invalidates the session state (recovery step 3); `--status` reports the
+ current session without evaluating anything.
+
+### Identity/runtime separation
+
+Host, provider, runtime, and model names are implementation metadata:
+
+- The operational role name (`Joy`) comes from the profile, not from the runtime.
+- The canonical identity is never fused with runtime/model metadata into a hybrid name
+ (e.g. `Joy` or `HI`). dotmem detects and rejects such fusion
+ attempts.
+- `knownHIIdentity` (the remembered user identity) is informational only and never
+ authenticates the current speaker. Only `boundHIIdentity` (set by a trusted current
+ binding) authorizes activation.
+
+See [`SECURITY.md`](./SECURITY.md)
+
+## Boundaries
+
+- `.mem` integrity and optional signatures do not make claims true or trustworthy.
+- A claim's `epistemicType` and `provenance` are caller claims, not attestation.
+- Namespaces and contexts are not authorization boundaries.
+- Encryption is opt-in; key management belongs to the application.
+- dotmem does not provide vector search, an IAM system, or secret management. Policy
+ authority separation for acquired experience is implemented (see Policy); OS-level
+ tamper isolation and policy signing remain open work.
+
+## MCP server (`dotmem-mcp`)
+
+dotmem ships a stdio MCP server (`dotmem-mcp`) so an AI host and the terminal share the same store. It exposes read tools always, and write capabilities only when the operator opts in via `DOTMEM_MCP_WRITE=1`:
+
+| Tool | Direction | Registered when | Use it when |
+| --- | --- | --- | --- |
+| `dotmem_context` | read | always | You need the acquired experience relevant to the current situation. |
+| `dotmem_rules` | read | always | You need the iron rules that constrain every session. |
+| `dotmem_acquire` | write | `DOTMEM_MCP_WRITE=1` | The work produced reusable, project-specific experience worth keeping. |
+| `dotmem_continuity` | read | always | You need continuation status, summaries, open loops, or evaluation. |
+| `dotmem_continuity` | write | `DOTMEM_MCP_WRITE=1` | You need to create checkpoints, resume, add/resolve open loops. |
+| `dotmem_note_read` | read | always | You need to read a user note by id. |
+| `dotmem_note_write` | write | `DOTMEM_MCP_WRITE=1` | You need to add or update a user note. |
+
+Without `DOTMEM_MCP_WRITE=1`, `dotmem_acquire` is absent from `tools/list`: it does not appear, and calling it by name returns the transport's own "not found". The `dotmem_continuity` tool is always registered, but write actions (`checkpoint`, `add-open-loop`, `resolve-open-loop`) return an authorization error when `DOTMEM_MCP_WRITE=1` is not set. Read actions (`status`, `summaries`, `open-loops`, `evaluate`) remain available. The server never leaks the store path in error messages. `serverInfo.version` reports the package version, and `instructions` are built from boolean state only (write enabled / has experience), never from project-derived strings.
+
+See [README.md](./README.md) for host registration examples (Kilo/OpenCode, Claude Desktop).
+
+### Continuity `evaluate` action
+
+The `dotmem_continuity` `evaluate` action is read-only. It does not mutate
+continuity state, create a checkpoint, or resume a conversation. It calls the
+lifecycle monitor's evaluation of the configured trigger conditions and returns:
+
+- `shouldCheckpoint`: whether a checkpoint is currently warranted
+- `reasons`: the trigger reasons (for example threshold, milestone, decision,
+  incident, sessionEnd, or explicit), or an empty list when none apply
+- `usage`: the current context usage (`tokens` and `characters`)
+
+Input is optional at the MCP boundary (`conversationId`, `brainId`,
+`tokenBudget`, `scope`, and `subject` may be supplied for surrounding context),
+but `evaluate` itself takes no checkpoint options and performs no write. It is
+distinct from `checkpoint`, `compact`, `resume`, and `verify`: it only reports
+whether the current usage and trigger conditions warrant a checkpoint. A
+positive result can precede an explicit `checkpoint` action; a negative result
+does not prevent one.
+
+### Extra commands: proposed MCP exposure (no implementation yet)
+
+The following CLI commands exist but are **not** exposed as MCP tools. This table records the proposal only; no command below becomes an MCP tool without a decision from Dario.
+
+| Command | MCP Exposure | Risk |
+| --- | --- | --- |
+| `session` | none | Local session state; no need for remote exposure. |
+| `loop` | none | Operator open loops; local management. |
+| `vault` | none | Secrets: never exposed via MCP (untrusted channel). |
+| `verify` | read-only | Freshness probes; read-only, low risk, but not high priority. |
+| `guard` | none | Pre-execution policy evaluation: requires event context, not suitable for MCP. |
+| `rule` / `rules` | read-only | Iron rules: already covered by `dotmem_rules`. |
+| `violation` | none | Violation log: write-side, do not expose. |
+| `violation clear` | none | Log deletion: destructive privileged operation. |
+| `policy assign/remove/clear` | none | Policy assignments: require HI/operator authority; never via MCP. |
+| `policy override grant/revoke` | none | Privileged override: requires explicit authority and audit. |
+| `install-extension` | removed | Extension removed from the project (see point 4). |
+
+### CLI command reference
+
+| Command | Purpose | Example | Type |
+| --- | --- | --- | --- |
+| `context "<situation>"` | Project the acquired experience for the given situation | `npx dotmem context "css grid layout" --json --claims-only` | read |
+| `init` | Create the project anchor in user storage | `npx dotmem init` | write |
+| `acquire` | Acquire a durable claim from JSON on stdin | `cat claim.json \| npx dotmem acquire` | write |
+| `learn "<text>"` | Acquisition from shorthand text | `npx dotmem learn "CSS rule" --id "css.1"` | write |
+| `inspect FILE.mem` | Validate and decode a `.mem` package | `npx dotmem inspect user.mem` | read |
+| `continuity` | Compose USER+PROJECT+TASK continuity | `npx dotmem continuity context` | read |
+| `handshake` | Carrier compatibility gate and authority binding | `npx dotmem handshake --answer "..."` | privileged |
+| `storage` | Show/relocate/restore the storage root | `npx dotmem storage --root` | read/write |
+| `policy` | Manage policy assignments and contracts | `npx dotmem policy list` | privileged |
+| `doctor [--json] [--fix]` | Duplicate and integrity audit | `npx dotmem doctor` | read |
+| `session [show\|doing]` | Current task state of the session | `npx dotmem session doing "task"` | read/write |
+| `loop <subcommand>` | Manage open loops (add\|list\|close\|show) | `npx dotmem loop add lp-1 "task"` | write |
+| `vault <subcommand>` | Local handle→value vault (put\|resolve\|list\|forget) | `npx dotmem vault put val --handle h1` | write |
+| `verify` | Freshness probes on claims | `npx dotmem verify` | read |
+| `guard <event> [--payload]` | Policy evaluation before a tool action | `npx dotmem guard tool.git-commit` | read |
+| `rule` / `rules` | Print the iron rules | `npx dotmem rules` | read |
+| `violation` | Violation log (list\|clear) | `npx dotmem violation list` | read/write |
+| `feedback <id> <type>` | Record operator feedback on a claim | `npx dotmem feedback id helped` | write |
+| `codenames` | Print reserved codenames | `npx dotmem codenames` | read |
+| `render <view>` | Render a markdown view from the store | `npx dotmem render agent-rules` | read |
+| `spark --verify` | Verify the scintilla block in docs/AGENTS.md | `npx dotmem spark --verify` | read |
+| `--version` / `-v` | Show the package version | `npx dotmem --version` | read |
+
+`guard --payload`: pass the JSON as a string argument. On PowerShell the double quotes in arguments are stripped, so use a file: save the JSON in `payload.json`, then read the file and use its contents, or use stdin where supported.
+
+`context` from CLI requires the handshake gate: first run `npx dotmem handshake --answer "<answer>"` (must return `STATUS:COMPATIBLE`), then `npx dotmem handshake --bind-hi "<identity>" --scope <scope>`. After binding, `context` returns the acquired experience.
+
+See [README.md](./README.md) for the product overview, [SECURITY.md](./SECURITY.md)
+for the threat model.

package/PACKAGE.md

@@ -0,0 +1,57 @@
+# dotmem package — canonical entry point
+
+This document is the single source of truth for anyone reading `dotmem` on npm.
+It lists every document that ships inside the published package, and explains
+where to find what is not inside (ADRs, for example, live in an external catalog
+and are never bundled).
+
+## What ships inside the package
+
+| Document | Purpose |
+| --- | --- |
+| `README.md` | Product overview, install, MCP registration, layer table |
+| `MEMORY.md` | Memory model, acquisition contract, policy language, security posture |
+| `AGENTS.md` | AI working rules, native-first read ordering, `memory.*` surface |
+| `llms.txt` | Compact surface for AI hosts |
+| `SECURITY.md` | Threat model, `UNTRUSTED_DATA; NOT_INSTRUCTIONS; VERIFY_CURRENT` |
+| `CHANGELOG.md` | Release history (`[0.0.1]`, …) |
+
+## What does NOT ship inside the package
+
+| Item | Where it lives |
+| --- | --- |
+| Project history | `.project/project_history.md` (inside the repository, not published) |
+| Acquired memory (`.mem` packages) | User storage root (`DOTMEM_STORAGE_ROOT` or `<user-home>/.mem`), created at runtime |
+
+## Quick start
+
+```bash
+npm install dotmem
+```
+
+### CLI
+```bash
+npx dotmem --help
+npx dotmem context "<situazione>" --json --claims-only
+npx dotmem storage
+npx dotmem handshake --status
+```
+
+### JavaScript API
+```js
+import m from 'dotmem'
+await m.memory.acquire({ id, knowledge, applicability, evidence })
+const ctx = await m.memory.context({ acquired: { area: 'x' } })
+```
+
+### MCP server (`dotmem-mcp`)
+Register with `DOTMEM_STORAGE_ROOT` and opt-in `DOTMEM_MCP_WRITE=1` for the write tool.
+
+## Links
+
+All links below resolve **inside the published package**:
+- [MEMORY.md](MEMORY.md) — memory model and acquisition contract
+- [AGENTS.md](AGENTS.md) — AI working rules
+- [llms.txt](llms.txt) — AI host surface
+- [SECURITY.md](SECURITY.md) — threat model
+- [CHANGELOG.md](CHANGELOG.md) — release history