dotmem 0.1.0 → 0.1.1

package/README.md

@@ -1,93 +1,122 @@
 # dotmem (.mem)
 
-![banner](https://raw.githubusercontent.com/passariello/container/refs/heads/main/dotmem/banner.svg)
+![Dotmem banner](https://raw.githubusercontent.com/passariello/container/refs/heads/main/dotmem/banner.svg)
 
-AI memory and continuity infrastructure for agents and applications.
+**AI memory and continuity infrastructure for agents and applications... Say `Hi Joy!`**
 
-Dotmem provides structured, queryable, policy-controlled memory for AI agents. It supports experience acquisition, bounded context projection, continuity across sessions, rule-based reasoning, and MCP integration. The memory substrate is independent of a specific model, vendor, host, or conversational client.
+Dotmem provides structured, queryable, policy-controlled memory for AI agents and applications. It supports experience acquisition, bounded context projection, continuity across sessions, rule-based reasoning, and MCP integration.
 
-> **Retrieval model**: dotmem uses deterministic lexical/structured retrieval with applicability-based eligibility. It does not use embeddings, vector indexes, or semantic similarity search. The term "AI-oriented" refers to the memory lifecycle and API design (acquisition with evidence/provenance, applicability scoping, policy-gated writes, context projection for LLM consumption), not the underlying retrieval algorithm. For semantic/vector search, pair dotmem with a dedicated embedding store.
+The memory substrate is independent of any specific model, vendor, host, or conversational client.
+
+> **Retrieval:** deterministic lexical and structured matching. No embeddings or vector search. See [Retrieval model](#retrieval-model).
 
 ---
 
 ## What Dotmem is
 
-- **Acquired experience**: evidenced, applicability-scoped claims via `discover`, `project`, and `acquire`.
-- **Application memory**: typed key/value entries via `remember`, `recall`, `update`, `forget`, and `patch`.
-- **Continuity**: snapshots, checkpoints, compaction, and open loops across sessions.
-- **Policy**: separate authority domain with tiered enforcement and privileged out-of-band overrides.
-- **Agent namespaces**: logically partitioned memory via `dotmem/agent`.
-- **Notes and profiles**: short-lived notes and read-only built-in profiles (including the optional Joy profile).
-- **MCP and CLI**: stdio MCP server (`dotmem-mcp`) and command-line tools.
+- **Acquired experience:** evidenced, applicability-scoped claims through `discover`, `project`, and `acquire`.
+- **Application memory:** typed key/value entries through `remember`, `recall`, `update`, `forget`, and `patch`.
+- **Continuity:** snapshots, checkpoints, compaction, and open loops across sessions.
+- **Policy:** a separate authority domain with tiered enforcement and privileged out-of-band overrides.
+- **Agent namespaces:** logically partitioned memory through `dotmem/agent`.
+- **Notes and profiles:** short-lived notes and read-only built-in profiles, including the Joy profile.
+- **MCP and CLI:** a stdio MCP server (`dotmem-mcp`) and command-line tools.
+
+Dotmem owns memory, continuity, profiles, agents, and MCP capabilities end to end. MCP is an access interface, not the core.
 
 ---
 
-Dotmem is the active owner of memory, continuity, profiles, agents, and MCP capabilities. It is not a wrapper around an external memory service. MCP is an access interface, not the core.
+## Installation
 
----
+```bash
+npm install dotmem
+```
 
-## Install
+Other supported package managers:
 
 ```bash
-npm i dotmem
-# or
-bun i dotmem
-# or
-pnpm i dotmem
+bun add dotmem
+pnpm add dotmem
 ```
 
-Requires Node.js >= 18.0.0.
+**Requirements:** Node.js >= 20.0.0.
+
+The MCP server is distributed separately as `dotmem-mcp`. See [MCP server](#mcp-server).
 
 ---
 
-## Quick Start (continuos chat)
+## Quick Start — Continuous Chat
 
-### Install dotmem global
+Run the Dotmem MCP server on your machine so that your AI host and your terminal share the same local memory store.
 
-```sh
-npm i -g dotmem memorio
+1. Add the server to your host configuration (example for Claude Desktop, read-only by default):
 
-```
-### See MCP section or
+   ```json
+   {
+     "mcpServers": {
+       "dotmem": {
+         "command": "npx",
+         "args": ["-y", "-p", "dotmem-mcp", "dotmem-mcp"]
+       }
+     }
+   }
+   ```
 
-```chat
-npx -y -p dotmem dotmem-mcp
+2. Restart the host.
+3. Start the conversation with `Hi Joy!`.
 
-```
+To allow the host to write memory, add `"env": { "DOTMEM_MCP_WRITE": "1" }`. Configurations for other hosts are in [MCP server](#mcp-server).
+
+---
 
-## Quick Start (coding)
+## Quick Start — Coding
 
-The runtime initializes lazily on first call; no explicit `init()` is required.
+The runtime initializes lazily on the first call. No explicit `init()` is required.
 
 ```typescript
 import { memory } from 'dotmem'
 
 // Discover relevant acquired experience for a situation
-const discovery = await memory.discover('User needs a language recommendation for a new project', {
-  depth: 'current',
-  maxCandidates: 10
-})
+const discovery = await memory.discover(
+  'User needs a language recommendation for a new project',
+  {
+    depth: 'current',
+    maxCandidates: 10
+  }
+)
 
 // Project a bounded context from discovered claims
-const projection = memory.project(discovery, { maxCandidates: 5, maxCharacters: 4000 })
+const projection = memory.project(discovery, {
+  maxCandidates: 5,
+  maxCharacters: 4000
+})
+
 console.info(projection.text)
 
-// Acquire durable experience (persists across restarts via .mem files)
+// Acquire durable experience
+// Persists across restarts through .mem files
 await memory.acquire({
   id: 'user.language-preference',
   knowledge: { language: 'TypeScript' },
   applicability: { area: 'language-selection' },
-  evidence: [{ id: 'conv-001', source: 'conversation', observedAt: new Date().toISOString() }],
+  evidence: [
+    {
+      id: 'conv-001',
+      source: 'conversation',
+      observedAt: new Date().toISOString()
+    }
+  ],
   epistemicType: 'observed'
 })
 ```
 
-For agent-namespaced memory, use the `dotmem/agent` subpath:
+### Agent-namespaced memory
 
 ```typescript
 import { createAgentMemory } from 'dotmem/agent'
 
 const agent = createAgentMemory('support-agent')
+
 await agent.remember('greeting', 'Hello! How can I help?', {
   type: 'fact',
   confidence: 0.9,
@@ -96,68 +125,94 @@ await agent.remember('greeting', 'Hello! How can I help?', {
 })
 ```
 
-> `remember()` with scope `durable` uses IndexedDB and is browser-only. For Node/Bun, use `memory.acquire()`. See [MEMORY.md](./MEMORY.md) for scope details.
+> ⚠️ **Persistence in Node.js, Bun, and Deno**
+>
+> - `remember()` with scope `durable` uses IndexedDB and is **browser-only**.
+> - The internal `store` and `session` layers fall back to in-memory `Map` instances outside the browser. **Data stored there is lost on restart.**
+> - To persist across restarts in Node.js and Bun, use `memory.acquire()`, which writes `.mem` files.
+>
+> See [MEMORY.md](./MEMORY.md) for scope details.
 
 ---
 
 ## Core capabilities
 
-- `memory.discover`, `memory.context`, `memory.project` — retrieval and bounded context projection.
-- `memory.acquire`, `memory.acquireStaged` — evidenced acquisition with policy evaluation.
-- `memory.remember`, `memory.recall`, `memory.update`, `memory.forget`, `memory.patch` — application memory.
-- `memory.journal`, `memory.note`, `memory.profile`, `memory.seed`, `memory.policy`, `memory.brain` — sub-facades.
-- `continuity` — snapshots, checkpoints, compaction, open loops.
-- `security`, `encryption` — RBAC/audit/consent and AES-GCM + PBKDF2 helpers.
-- Foundation re-exports: `state`, `store`, `session`, `idb`, `dispatch`, `hlc`.
+| API | Purpose |
+|---|---|
+| `memory.discover`, `memory.context`, `memory.project` | Retrieval and bounded context projection |
+| `memory.acquire`, `memory.acquireStaged` | Evidenced acquisition with policy evaluation |
+| `memory.remember`, `memory.recall`, `memory.update`, `memory.forget`, `memory.patch` | Application memory operations |
+| `memory.journal`, `memory.note`, `memory.profile`, `memory.seed`, `memory.policy`, `memory.brain` | Specialized memory facades |
+| `continuity` | Snapshots, checkpoints, compaction, and open loops |
+| `security`, `encryption` | RBAC, audit, consent, AES-GCM, and PBKDF2 helpers |
 
 ---
 
-## Layers
+## Architecture and layers
 
-Dotmem exposes **6 user-facing layers** through its public entry points. `knowledge` and `logic` are not public runtime exports (`logic` is experimental/unverified and not exported; `knowledge` is internal). `profile` is available via `memory.profile.get(id)` and its stability depends on the package semver contract.
+Dotmem exposes **six user-facing layers** through its public entry points.
 
 | Layer | Availability | Purpose |
-|-------|--------------|---------|
+|---|---|---|
 | **memory** | `dotmem` (main) | Key/value memory, acquisition lifecycle, journal, and sub-facades |
-| **continuity** | `dotmem` (main) | USER + PROJECT + TASK context composition, snapshots, open loops |
+| **continuity** | `dotmem` (main) | USER + PROJECT + TASK context composition, snapshots, and open loops |
 | **agent** | `dotmem/agent` (subpath) | Agent-facing memory with logical namespace partitioning |
-| **policy** | `memory.policy` | Policy definition, authority management, three-tier enforcement |
-| **profile** | `memory.profile.get(id)` | Identity and persona documents (read-only built-in profiles, including Joy) |
+| **policy** | `memory.policy` | Policy definition, authority management, and three-tier enforcement |
+| **profile** | `memory.profile.get(id)` | Identity and persona documents; read-only built-in profiles, including Joy |
 | **note** | `memory.note` | Short-lived notes with tags and origins |
 
-### Internal / infrastructure
+Not part of the public runtime surface:
 
-| Layer | Purpose | Notes |
-|-------|---------|-------|
-| **seed** | Development-only initial memory seed | `--dev` required |
-| **llm-cache** | LLM response cache types only; no verified runtime implementation | `types/llm-cache.d.ts` |
+- `logic` is experimental and unverified.
+- `knowledge` is internal.
+- `seed` is development-only and requires `--dev`.
+- `llm-cache` ships types only; there is no verified runtime implementation.
 
-> Dotmem re-exports foundational infrastructure: `state` (reactive state), `store` (key/value storage), `idb` (IndexedDB), and `sqlite` (SQL database integration). These are lower-level utilities, not additional AI memory layers.
+The `profile` layer follows the package semver contract.
 
 ---
 
 ## Retrieval model
 
-dotmem uses **deterministic, verifiable retrieval** without embedding-model dependencies:
+Dotmem uses **deterministic, verifiable retrieval** without embedding-model dependencies.
 
-- Lexical/structured matching with applicability-based eligibility.
+- Lexical and structured matching with applicability-based eligibility.
 - No embeddings, vector indexes, or semantic similarity search.
 - Results are reproducible given the same store and query.
 
-"AI-oriented" refers to the memory lifecycle and API design (acquisition with evidence/provenance, applicability scoping, policy-gated writes, context projection for LLM consumption), not the underlying retrieval algorithm. For semantic/vector search, pair dotmem with a dedicated embedding store.
+"AI-oriented" describes the memory lifecycle and API design, not the retrieval algorithm:
+
+- Acquisition with evidence and provenance.
+- Applicability scoping.
+- Policy-gated writes.
+- Context projection for LLM consumption.
+
+For semantic or vector search, pair Dotmem with a dedicated embedding store.
 
 ---
 
 ## MCP server
 
-`dotmem-mcp` is the stdio MCP server. It runs on the operator's machine so a connected AI host and the terminal share the same store. Write access is gated by `DOTMEM_MCP_WRITE=1`.
+`dotmem-mcp` is the stdio MCP server. It runs on the operator's machine, so a connected AI host and the terminal share the same local memory store.
+
+### Read-only by default
+
+The server starts **read-only**. Write access is an explicit opt-in:
+
+```bash
+DOTMEM_MCP_WRITE=1
+```
+
+Enable it only if you want the connected host to be able to modify memory.
 
-Canonical launch command (use this form in all configurations):
+### Launch command
 
 ```bash
-npx -y -p dotmem-mcp
+npx -y -p dotmem-mcp dotmem-mcp
 ```
 
+> 💡 For long-lived setups, pin the version (`dotmem-mcp@x.y.z`) instead of taking the latest on every launch.
+
 ### Claude Desktop
 
 ```json
@@ -165,7 +220,20 @@ npx -y -p dotmem-mcp
   "mcpServers": {
     "dotmem": {
       "command": "npx",
-      "args": ["-y", "-p", "dotmem-mcp"],
+      "args": ["-y", "-p", "dotmem-mcp", "dotmem-mcp"]
+    }
+  }
+}
+```
+
+With write access:
+
+```json
+{
+  "mcpServers": {
+    "dotmem": {
+      "command": "npx",
+      "args": ["-y", "-p", "dotmem-mcp", "dotmem-mcp"],
       "env": { "DOTMEM_MCP_WRITE": "1" }
     }
   }
@@ -175,77 +243,97 @@ npx -y -p dotmem-mcp
 ### Claude Code
 
 ```bash
-claude mcp add --env DOTMEM_MCP_WRITE=1 --transport stdio dotmem -- npx -y -p dotmem-mcp
+# read-only
+claude mcp add --transport stdio dotmem -- npx -y -p dotmem-mcp dotmem-mcp
+
+# with write access
+claude mcp add \
+  --env DOTMEM_MCP_WRITE=1 \
+  --transport stdio \
+  dotmem -- npx -y -p dotmem-mcp dotmem-mcp
 ```
 
 ### Kilo / OpenCode
 
 ```jsonc
-"mcp": {
-  "dotmem": {
-    "type": "local",
-    "command": ["npx", "-y", "-p", "dotmem-mcp"],
-    "enabled": true,
-    "environment": { "DOTMEM_MCP_WRITE": "1" }
+{
+  "mcp": {
+    "dotmem": {
+      "type": "local",
+      "command": ["npx", "-y", "-p", "dotmem-mcp", "dotmem-mcp"],
+      "enabled": true
+      // For write access, add:
+      // "environment": { "DOTMEM_MCP_WRITE": "1" }
+    }
   }
 }
 ```
 
-### Windows Command Prompt (cmd.exe)
+### Windows (cmd.exe)
 
-In Windows `cmd.exe`, `npx` may not be directly executable as a command. Use `cmd /c npx`:
+On Windows, `npx` may not be directly executable by an MCP host. Use `cmd /c npx`:
 
 ```json
 {
   "mcpServers": {
     "dotmem": {
       "command": "cmd",
-      "args": ["/c", "npx", "-y", "-p", "dotmem-mcp"],
-      "env": { "DOTMEM_MCP_WRITE": "1" }
+      "args": ["/c", "npx", "-y", "-p", "dotmem-mcp", "dotmem-mcp"]
     }
   }
 }
 ```
 
-See [MEMORY.md](./MEMORY.md) for the full tool list and write-gating details.
+Add `"env": { "DOTMEM_MCP_WRITE": "1" }` for write access.
+
+See [MEMORY.md](./MEMORY.md) for the complete MCP tool list and write-gating details.
 
 ---
 
-## Optional Joy identity
+## Joy identity
+
+Dotmem core is model- and provider-independent.
 
-Dotmem core is model- and persona-independent. Joy/Jo is an optional agent identity and profile. See [docs/JOY.md](./JOY.md) for activation (exact phrase only), discovery order, and the optional profile.
+**Joy/Jo is the native, Dotmem collaborator identity and profile.**
+
+Joy is the canonical identity. Jo is its conversational abbreviation and alias; both resolve to the same identity.
+
+The Joy profile is part of Dotmem's native profile system. It is not an optional plugin, external persona, or provider-specific feature.
+
+See [JOY.md](./JOY.md) for activation rules, discovery order, identity resolution, profile requirements.
 
 ---
 
 ## Documentation
 
 | Document | Description |
-|----------|-------------|
-| [MEMORY.md](./MEMORY.md) | Full memory model: acquisition contract, policy language, epistemic typing, enforcement, continuity, identity |
-| [AGENTS.md](./AGENTS.md) | AI agent working rules, activation phrases, complete `memory.*` surface |
-| [SECURITY.md](./SECURITY.md) | Encryption, multitenancy, key management, trust model, JHF, sandbox |
-| [JOY.md](./JOY.md) | Optional Joy identity, activation matching, discovery order |
-| [PACKAGE.md](./PACKAGE.md) | Package contents, full quick-start, dependency graph |
+|---|---|
+| [MEMORY.md](./MEMORY.md) | Memory model: acquisition contract, policy language, epistemic typing, enforcement, continuity, and identity |
+| [AGENTS.md](./AGENTS.md) | AI agent working rules, activation phrases, and complete `memory.*` surface |
+| [SECURITY.md](./SECURITY.md) | Encryption, multitenancy, key management, trust model, JHF, and sandbox |
+| [JOY.md](./JOY.md) | Joy identity, activation matching, and discovery order |
+| [PACKAGE.md](./PACKAGE.md) | Package contents, complete quick start, and dependency graph |
 | [LICENSE.md](./LICENSE.md) | License |
 
 ---
 
 ## Compatibility
 
-**License**: MIT (SPDX: `MIT`)
+| Runtime | Compatibility |
+|---|---|
+| Node.js >= 20.0.0 | Declared in `package.json` engines |
+| Bun >= 1.0 | Tested in CI |
+| Browser | ES2020+ with IndexedDB, localStorage, and sessionStorage |
+| Deno | Compatible, not routinely tested |
 
-**Supported runtimes**:
-- Node.js >= 18.0.0 (declared in `package.json` engines)
-- Bun >= 1.0 (tested in CI)
-- Browser (ES2020+ with IndexedDB, localStorage, sessionStorage)
-- Deno (compatible, not routinely tested)
+**Tested in CI:** Node.js 20.x, Node.js 22.x, Bun 1.x.
 
-**Tested in CI**: Node.js 20.x, 22.x; Bun 1.x
-
-**Note**: The `durable` scope in `memory.remember()` uses IndexedDB and is browser-only. For cross-restart persistence in Node/Bun, use `memory.acquire()` which writes `.mem` package files. The `store` and `session` layers fall back to in-memory `Map`s in Node/Bun/Deno and do not survive process restarts.
+For persistence rules per runtime, see the [persistence warning](#agent-namespaced-memory) in Quick Start.
 
 ---
 
 ## License
 
-MIT (c) 2026 Dario Passariello.
+MIT — Copyright (c) 2026 Dario Passariello.
+
+SPDX-License-Identifier: `MIT`

package/SECURITY.md

@@ -8,7 +8,7 @@ This document covers dotmem's optional encryption layer, client-side multitenanc
 
 This applies to every layer: `state`, `store`, `session`, `idb`, `memory`, `sqlite`. Treat browser storage as client-controlled unless you explicitly opt in.
 
-Core declares no production dependencies in package.json. `memorio` is listed under devDependencies, but the built ESM/CJS output imports it as an external runtime module; a published install therefore needs `memorio` available unless packaging changes. No `eval`, no dynamic code execution, no bundled telemetry, sanitized keys, validated inputs, bounded journal entries, UUID-based session identifiers. Independently checkable via Socket.dev / Snyk. (The optional MCP stdio entrypoint is the one declared-dependency surface: `zod` and `@modelcontextprotocol/server`.)
+The published package declares production dependencies, including `@modelcontextprotocol/server`, `memorio` and `zod`. The MCP stdio entrypoint uses `zod` and `@modelcontextprotocol/server`. No `eval`, no dynamic code execution, no bundled telemetry, sanitized keys, validated inputs, bounded journal entries, UUID-based session identifiers. Independently checkable via Socket.dev / Snyk.
 
 ---
 

package/agent.cjs

@@ -18,10 +18,10 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
-// suppress-idb-warning.ts
+// core/suppress-idb-warning.ts
 var orig;
 var init_suppress_idb_warning = __esm({
-  "suppress-idb-warning.ts"() {
+  "core/suppress-idb-warning.ts"() {
     orig = console.warn.bind(console);
     console.warn = (...args) => {
       if (typeof args[0] === "string" && args[0].includes("IndexedDB is not available")) return;

package/agent.js

@@ -16,10 +16,10 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
-// suppress-idb-warning.ts
+// core/suppress-idb-warning.ts
 var orig;
 var init_suppress_idb_warning = __esm({
-  "suppress-idb-warning.ts"() {
+  "core/suppress-idb-warning.ts"() {
     orig = console.warn.bind(console);
     console.warn = (...args) => {
       if (typeof args[0] === "string" && args[0].includes("IndexedDB is not available")) return;