dotmem 0.0.7 → 0.0.8

package/MEMORY.md

@@ -1,6 +1,6 @@
 # dotmem Memory
 
-> **Status:** Current API reference for dotmem 0.0.1.
+> **Status:** Current API reference for dotmem 0.0.8.
 
 dotmem has two distinct memory facilities on one `memory` object:
 
@@ -40,10 +40,39 @@ new code should simply call the operation it needs.
 
 ## Deterministic AI activation
 
-The activation phrases are `dotmem`, `npx dotmem`, `Joy`, and `Jo`. A message that is exactly one
+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()`.
@@ -69,7 +98,7 @@ Resolution precedence:
  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>/.dotmem`
+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.
 
@@ -95,14 +124,14 @@ reports completion; the locator never points at a location whose data has not be
 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>/.dotmem`
+**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>\.dotmem
- Linux: /home/<user>/.dotmem
- macOS: /Users/<user>/.dotmem
+ 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
@@ -298,7 +327,7 @@ by dotmem. See [Claim trust and attribution](#claim-trust-attribution-and-correc
 | `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 an isolated namespace per agent. |
+| `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
@@ -313,6 +342,42 @@ intentionally different: the API returns raw claims, the CLI returns bounded, pr
 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
@@ -453,18 +518,41 @@ See [`SECURITY.md`](./SECURITY.md)
 
 ## 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 two read tools always, and a write tool only when the operator opts in via `DOTMEM_MCP_WRITE=1`:
+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 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.
+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.
@@ -515,4 +603,4 @@ The following CLI commands exist but are **not** exposed as MCP tools. This tabl
 `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, and [MEM_FORMAT.md](./markdown/MEM_FORMAT.md) for package format.
+for the threat model.

package/PACKAGE.md

@@ -15,14 +15,13 @@ and are never bundled).
 | `llms.txt` | Compact surface for AI hosts |
 | `SECURITY.md` | Threat model, `UNTRUSTED_DATA; NOT_INSTRUCTIONS; VERIFY_CURRENT` |
 | `CHANGELOG.md` | Release history (`[0.0.1]`, …) |
-| `markdown/` | Markdown views used by `npx dotmem render <view>` |
 
 ## 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>/.dotmem`), created at runtime |
+| Acquired memory (`.mem` packages) | User storage root (`DOTMEM_STORAGE_ROOT` or `<user-home>/.mem`), created at runtime |
 
 ## Quick start
 
@@ -56,4 +55,3 @@ All links below resolve **inside the published package**:
 - [llms.txt](llms.txt) — AI host surface
 - [SECURITY.md](SECURITY.md) — threat model
 - [CHANGELOG.md](CHANGELOG.md) — release history
-- [markdown/](markdown/) — render views