dotmem 0.0.9 → 0.1.0

package/MEMORY.md

@@ -98,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>/.mem`
+3. **Default user-scoped storage** — the user anchor itself: `<user-home>/.dotmem`
  (the platform-neutral canonical form; see the OS examples below), resolved from the
  current runtime.
 
@@ -124,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>/.mem`
+**Canonical form, platform-neutral.** The user anchor is written `<user-home>/.dotmem`
 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
+ Linux: /home/<user>/.dotmem
+ macOS: /Users/<user>/.dotmem
 ```
 
 The runtime resolves the actual home directory from the OS/environment; no hardcoded

package/PACKAGE.md

@@ -21,7 +21,7 @@ and are never bundled).
 | 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 |
+| Acquired memory (`.mem` packages) | User storage root (`DOTMEM_STORAGE_ROOT` or `<user-home>/.dotmem`), created at runtime |
 
 ## Quick start
 

package/README.md

@@ -1,200 +1,251 @@
-# dotmem (.mem)
-
-![banner](https://raw.githubusercontent.com/passariello/container/refs/heads/main/dotmem/banner.svg)
-
-AI memory and continuity infrastructure for agents and applications.
-
-**Built on:** [memorio](https://www.npmjs.com/package/memorio) (state, store, session, IndexedDB, SQLite, cache)
-
-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.
-
-> **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.
-
----
-
-## 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.
-
-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.
-
----
-
-## Install
-
-```bash
-npm i dotmem
-# or
-bun i dotmem
-# or
-pnpm i dotmem
-```
-
-Requires Node.js >= 18.0.0.
-
----
-
-## Quick Start
-
-The runtime initializes lazily on 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
-})
-
-// Project a bounded context from discovered claims
-const projection = memory.project(discovery, { maxCandidates: 5, maxCharacters: 4000 })
-console.info(projection.text)
-
-// Acquire durable experience (persists across restarts via .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() }],
-  epistemicType: 'observed'
-})
-```
-
-For agent-namespaced memory, use the `dotmem/agent` subpath:
-
-```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,
-  scope: 'local',
-  tags: ['greeting']
-})
-```
-
-> `remember()` with scope `durable` uses IndexedDB and is browser-only. For Node/Bun, use `memory.acquire()`. 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`.
-
----
-
-## 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.
-
-| 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 |
-| **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) |
-| **note** | `memory.note` | Short-lived notes with tags and origins |
-
-### Internal / infrastructure
-
-| 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` |
-
-> 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.
-
----
-
-## Retrieval model
-
-dotmem uses **deterministic, verifiable retrieval** without embedding-model dependencies:
-
-- Lexical/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.
-
----
-
-## 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`.
-
-Canonical launch command (use this form in all configurations):
-
-```bash
-npx -y -p dotmem dotmem-mcp
-```
-
-Example (Claude Desktop, read-only by default):
-
-```json
-{
-  "mcpServers": {
-    "dotmem": {
-      "command": "npx",
-      "args": ["-y", "-p", "dotmem", "dotmem-mcp"]
-    }
-  }
-}
-```
-
-See [MEMORY.md](./MEMORY.md) for the full tool list and write-gating details.
-
----
-
-## Optional Joy identity
-
-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.
-
----
-
-## 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 |
-| [LICENSE.md](./LICENSE.md) | License |
-
----
-
-## Compatibility
-
-**License**: MIT (SPDX: `MIT`)
-
-**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, 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.
-
----
-
-## License
-
+# dotmem (.mem)
+
+![banner](https://raw.githubusercontent.com/passariello/container/refs/heads/main/dotmem/banner.svg)
+
+AI memory and continuity infrastructure for agents and applications.
+
+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.
+
+> **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.
+
+---
+
+## 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.
+
+---
+
+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.
+
+---
+
+## Install
+
+```bash
+npm i dotmem
+# or
+bun i dotmem
+# or
+pnpm i dotmem
+```
+
+Requires Node.js >= 18.0.0.
+
+---
+
+## Quick Start (continuos chat)
+
+### Install dotmem global
+
+```sh
+npm i -g dotmem memorio
+
+```
+### See MCP section or
+
+```chat
+npx -y -p dotmem dotmem-mcp
+
+```
+
+## Quick Start (coding)
+
+The runtime initializes lazily on 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
+})
+
+// Project a bounded context from discovered claims
+const projection = memory.project(discovery, { maxCandidates: 5, maxCharacters: 4000 })
+console.info(projection.text)
+
+// Acquire durable experience (persists across restarts via .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() }],
+  epistemicType: 'observed'
+})
+```
+
+For agent-namespaced memory, use the `dotmem/agent` subpath:
+
+```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,
+  scope: 'local',
+  tags: ['greeting']
+})
+```
+
+> `remember()` with scope `durable` uses IndexedDB and is browser-only. For Node/Bun, use `memory.acquire()`. 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`.
+
+---
+
+## 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.
+
+| 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 |
+| **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) |
+| **note** | `memory.note` | Short-lived notes with tags and origins |
+
+### Internal / infrastructure
+
+| 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` |
+
+> 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.
+
+---
+
+## Retrieval model
+
+dotmem uses **deterministic, verifiable retrieval** without embedding-model dependencies:
+
+- Lexical/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.
+
+---
+
+## 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`.
+
+Canonical launch command (use this form in all configurations):
+
+```bash
+npx -y -p dotmem-mcp
+```
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "dotmem": {
+      "command": "npx",
+      "args": ["-y", "-p", "dotmem-mcp"],
+      "env": { "DOTMEM_MCP_WRITE": "1" }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add --env DOTMEM_MCP_WRITE=1 --transport stdio dotmem -- npx -y -p dotmem-mcp
+```
+
+### Kilo / OpenCode
+
+```jsonc
+"mcp": {
+  "dotmem": {
+    "type": "local",
+    "command": ["npx", "-y", "-p", "dotmem-mcp"],
+    "enabled": true,
+    "environment": { "DOTMEM_MCP_WRITE": "1" }
+  }
+}
+```
+
+### Windows Command Prompt (cmd.exe)
+
+In Windows `cmd.exe`, `npx` may not be directly executable as a command. Use `cmd /c npx`:
+
+```json
+{
+  "mcpServers": {
+    "dotmem": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "-p", "dotmem-mcp"],
+      "env": { "DOTMEM_MCP_WRITE": "1" }
+    }
+  }
+}
+```
+
+See [MEMORY.md](./MEMORY.md) for the full tool list and write-gating details.
+
+---
+
+## Optional Joy identity
+
+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.
+
+---
+
+## 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 |
+| [LICENSE.md](./LICENSE.md) | License |
+
+---
+
+## Compatibility
+
+**License**: MIT (SPDX: `MIT`)
+
+**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, 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.
+
+---
+
+## License
+
 MIT (c) 2026 Dario Passariello.

package/agent.cjs

@@ -18,6 +18,18 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// suppress-idb-warning.ts
+var orig;
+var init_suppress_idb_warning = __esm({
+  "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;
+      orig(...args);
+    };
+  }
+});
+
 // core/idb.ts
 var idb;
 var init_idb = __esm({
@@ -46,6 +58,7 @@ __export(global_exports, {
 var getPlatform;
 var init_global = __esm({
   "core/global.ts"() {
+    init_suppress_idb_warning();
     init_idb();
     getPlatform = /* @__PURE__ */ __name(() => {
       const proc = globalThis.process;

package/agent.js

@@ -16,6 +16,18 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// suppress-idb-warning.ts
+var orig;
+var init_suppress_idb_warning = __esm({
+  "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;
+      orig(...args);
+    };
+  }
+});
+
 // core/idb.ts
 var idb;
 var init_idb = __esm({
@@ -44,6 +56,7 @@ __export(global_exports, {
 var getPlatform;
 var init_global = __esm({
   "core/global.ts"() {
+    init_suppress_idb_warning();
     init_idb();
     getPlatform = /* @__PURE__ */ __name(() => {
       const proc = globalThis.process;

package/bin/cli.cjs

@@ -9,6 +9,11 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var process__default = /*#__PURE__*/_interopDefault(process);
 
+var __origWarn = console.warn.bind(console);
+console.warn = (...args2) => {
+  if (typeof args2[0] === "string" && args2[0].includes("IndexedDB is not available")) return;
+  __origWarn(...args2);
+};
 var rawArgs = process__default.default.argv.slice(2);
 var storageRootFlagIndex = rawArgs.indexOf("--storage-root");
 var hasStorageRootFlag = storageRootFlagIndex !== -1;

package/bin/cli.js

@@ -2,6 +2,11 @@
 import process from 'process';
 import { fileURLToPath } from 'url';
 
+var __origWarn = console.warn.bind(console);
+console.warn = (...args2) => {
+  if (typeof args2[0] === "string" && args2[0].includes("IndexedDB is not available")) return;
+  __origWarn(...args2);
+};
 var rawArgs = process.argv.slice(2);
 var storageRootFlagIndex = rawArgs.indexOf("--storage-root");
 var hasStorageRootFlag = storageRootFlagIndex !== -1;

package/bin/mcp.cjs

@@ -7,6 +7,11 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var process__default = /*#__PURE__*/_interopDefault(process);
 
+var __origWarn = console.warn.bind(console);
+console.warn = (...args) => {
+  if (typeof args[0] === "string" && args[0].includes("IndexedDB is not available")) return;
+  __origWarn(...args);
+};
 var nodeMajorVersion = Number.parseInt(process__default.default.versions.node.split(".")[0] ?? "", 10);
 if (!Number.isInteger(nodeMajorVersion) || nodeMajorVersion < 20) {
   console.error("dotmem-mcp requires Node.js >=20; the normal dotmem runtime remains compatible with its declared Node.js version.");

package/bin/mcp.js

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
 import process from 'process';
 
+var __origWarn = console.warn.bind(console);
+console.warn = (...args) => {
+  if (typeof args[0] === "string" && args[0].includes("IndexedDB is not available")) return;
+  __origWarn(...args);
+};
 var nodeMajorVersion = Number.parseInt(process.versions.node.split(".")[0] ?? "", 10);
 if (!Number.isInteger(nodeMajorVersion) || nodeMajorVersion < 20) {
   console.error("dotmem-mcp requires Node.js >=20; the normal dotmem runtime remains compatible with its declared Node.js version.");