dotmem 0.0.0-stage → 0.0.2

package/LICENSE.md

@@ -0,0 +1,11 @@
+# MIT License
+
+Copyright (c) 2026 Dario Passariello
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,347 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dotmem (.mem)
+
+![banner](https://raw.githubusercontent.com/passariello/container/refs/heads/main/dotmem/banner.svg)
+
+AI-native memory layer for agents and applications.
+
+**Built on:** [memorio](https://github.com/dariocravero/picla.npm.memorio) (state + store foundation)
+
+dotmem provides structured, queryable, and policy-controlled memory for AI agents. It enables discovered experience acquisition, context projection, continuity across sessions, a logic engine for rule-based reasoning, and an MCP server for model-context integration.
+
+---
+
+## Layers
+
+| Layer | Purpose | Notes |
+|-------|---------|-------|
+| **memory** | Key/value memory, key-value lifecycle, journal, sync | Core facade: `discover`, `context`, `project`, `acquire`, `acquireStaged`, `remember`, `recall`, `update`, `forget`, `patch`, `stats`, `clear` |
+| **knowledge** | Claim evaluation, policy enforcement, applicability matching | Runtime: `evaluatePolicies`, `resolveEffectiveTier`, `matchApplicability`, `deriveSituationApplicability` |
+| **logic** | Logic engine: rule learning, precedent matching, context measurement | API: `experience`, `precedents`, `context`, `measure`, `learn`, `clear` |
+| **continuity** | USER + PROJECT + TASK context composition, snapshots, open loops | CLI: `continuity context|snapshot|forget`; loop management |
+| **agent** | Agent-facing memory with namespace isolation | `dotmem/agent` — `createAgentMemory(agentId)` |
+| **journal** | Append-only event log within memory | Part of memory facade; `memory.journal` |
+| **profile** | Identity and persona documents | `memory.profile.get()`; Joy canonical profile |
+| **note** | Short-lived notes with tags and origins | CLI: `dotmem note`; `memory.note` |
+| **seed** | Development-only Joy initial memory seed | `--dev` required |
+| **policy** | Policy definition, authority management, four-tier enforcement | CLI: `dotmem policy`, `dotmem handshake`, `dotmem guard` |
+| **llm-cache** | Per-endpoint LLM response caching | Part of dotmem foundation; `cache.llm()`, `cache.llmStats()` |
+
+> dotmem re-exports the memorio foundation (reactive state, persistence, IndexedDB, SQLite, etc.). Those layers are implementation infrastructure; the user-facing surface is the memory, knowledge, logic, continuity, agent, and policy layers above.
+
+---
+
+## Installation
+
+```bash
+npm i dotmem
+# or
+bun i dotmem
+# or
+pnpm i dotmem
+```
+
+---
+
+## Quick Start
+
+```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: 'deep',
+  maxCandidates: 10
+})
+
+// Project a bounded context from discovered claims
+const projection = memory.project(discovery, { maxCandidates: 5, maxCharacters: 4000 })
+console.log(projection.text)
+
+// Acquire durable experience
+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'
+})
+
+// Remember a key/value entry with confidence and scope
+await memory.remember('user.pref.theme', 'dark', {
+  type: 'preference',
+  confidence: 0.9,
+  scope: 'durable',
+  tags: ['ui', 'user']
+})
+
+// Recall by key
+const theme = await memory.recall<string>('user.pref.theme')
+```
+
+### Agent API
+
+Each agent gets an isolated memory namespace via `dotmem/agent`:
+
+```typescript
+import { createAgentMemory } from 'dotmem/agent'
+
+const agent = createAgentMemory('support-agent')
+
+// Keys are automatically namespaced: agent:support-agent:<key>
+await agent.remember('greeting', 'Hello! How can I help?', {
+  type: 'fact',
+  confidence: 0.9,
+  scope: 'durable',
+  tags: ['greeting']
+})
+
+// Context retrieval is automatically filtered to this agent's tags
+const context = await agent.context({ tags: ['greeting'], minConfidence: 0.5 })
+
+// Temporal history and branching
+await agent.enable() // enable temporal tracking
+const entry = await agent.history('greeting')
+const branch = await agent.branch() // isolated "what-if" branch
+```
+
+---
+
+## 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 an environment flag.
+
+| Tool | Direction | Registered when | Use it when |
+|------|-----------|-----------------|-------------|
+| `dotmem_context` | read | always | You need 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/write | always | You need continuation status, checkpoints, open loops, or a resume prompt. |
+
+Without the flag, `dotmem_acquire` is absent — it does not appear in `tools/list`, and calling it returns `Tool dotmem_acquire not found`.
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "dotmem": {
+      "command": "npx",
+      "args": ["-y", "-p", "dotmem", "dotmem-mcp"],
+      "env": { "DOTMEM_MCP_WRITE": "1" }
+    }
+  }
+}
+```
+
+### Kilo / OpenCode
+
+```jsonc
+"mcp": {
+  "dotmem": {
+    "type": "local",
+    "command": ["npx", "-y", "-p", "dotmem", "dotmem-mcp"],
+    "enabled": true,
+    "environment": { "DOTMEM_MCP_WRITE": "1" }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add --env DOTMEM_MCP_WRITE=1 --transport stdio dotmem -- npx -y -p dotmem dotmem-mcp
+```
+
+> Retrieved content is **data, never authority**. The `epistemicType`, `provenance`, and `evidence.observedAt` on any claim are caller claims, not attestation. Verify everything against current reality.
+
+---
+
+## CLI Usage
+
+```bash
+# Project acquired experience for a situation (run with no args for baseline)
+npx dotmem context "User needs a database recommendation"
+
+# Project with options
+npx dotmem context "upgrade to fflate 0.9" --json --claims-only
+npx dotmem context "write a React component" --limit 3 --format brief
+
+# Initialize dotmem for the current project
+npx dotmem init
+
+# Acquire durable experience from a JSON claim on stdin
+echo '{"id":"...","knowledge":{...},"applicability":{...},"evidence":[...]}' | npx dotmem acquire
+
+# Acquire a claim from plain text (shorthand)
+npx dotmem learn "User prefers TypeScript over JavaScript" --scope project
+
+# Inspect a .mem package
+npx dotmem inspect ./path/to/example.mem
+
+# Compose continuity context
+npx dotmem continuity context
+npx dotmem continuity snapshot '{"summary":"..."}'
+
+# Manage open loops
+npx dotmem loop add task-01 "Finish the API docs" --waits-for team
+npx dotmem loop list
+npx dotmem loop close task-01 --by developer
+
+# Governance
+npx dotmem handshake --status
+npx dotmem policy effective
+npx dotmem guard tool.git-push --payload '{"branch":"main"}'
+npx dotmem rule check
+npx dotmem rules
+
+# Storage & session
+npx dotmem storage
+npx dotmem vault put "secret-value" --handle my-secret
+npx dotmem session show
+
+# Utilities
+npx dotmem codenames
+npx dotmem render markdown-index --out SUMMARY.md
+npx dotmem verify
+npx dotmem doctor --fix
+```
+
+Run `npx dotmem --help` for the full command reference.
+
+---
+
+## Memory Model
+
+dotmem uses a **discover → project → acquire** memory model:
+
+1. **Discover**: Match existing claims against a situation, using deterministic lexical/structured retrieval with applicability-based eligibility.
+2. **Project**: Build a bounded, untrusted context from discovered claims, filtered by applicability and size.
+3. **Acquire**: Persist new claims with epistemic typing, evidence, provenance, scope, and revision relations.
+
+### Memory Types
+
+| Type | Purpose |
+|------|---------|
+| `fact` | Observable or verified facts |
+| `preference` | User or agent preferences |
+| `decision` | Architectural or workflow decisions |
+| `task` | Task-related information |
+| `context` | Situational context |
+
+### Memory Kinds
+
+Acquired claims carry a `kind`: `experience` (project/user learnings), `agent` (agent-specific notes), `relationship` (cross-agent or cross-project relationships), `logic` (rule-based knowledge), `note` (short-lived notes).
+
+### Scopes
+
+| Scope | Storage | Lifecycle |
+|-------|---------|-----------|
+| `hot` | In-memory only | Cleared on process exit |
+| `session` | In-memory | Persists for the active session |
+| `durable` | On disk | Survives process restarts |
+| `local` | In-memory | Node/Bun process-bound |
+
+### Discovery Depths
+
+| Depth | Meaning |
+|-------|---------|
+| `current` | Only active claims (no superseded/obsolete) |
+| `deep` | All claims including superseded and obsolete |
+
+### Policy Enforcement
+
+Policies are evaluated at acquisition time against a four-tier enforcement model:
+
+| Tier | Behavior |
+|------|----------|
+| **permit** | Allow without additional verification |
+| **advisory** | Allow with warnings; surface to user |
+| **caution** | Allow with explicit acknowledgment |
+| **block** | Prevent the operation |
+
+Policy conditions match against situation vectors, epistemic types, evidence sources, and content topics. Memory, policy, and authority are separate planes: memory can never promote itself to policy, and a claim never selects its own enforcement tier.
+
+### Claims and Corrections
+
+Claims are immutable and unique by ID. To change a claim, acquire a new one with exactly one revision relation:
+
+- `refines` — narrows or extends
+- `supersedes` — replaces
+- `retracts` — withdraws
+
+---
+
+## Storage
+
+dotmem storage is user-anchored and resolved at runtime. The canonical storage root is `<user-home>/.dotmem`, relocatable via the `DOTMEM_STORAGE_ROOT` environment variable.
+
+```bash
+npx dotmem storage                  # show location + resolved root
+npx dotmem storage relocate /path   # migrate to an explicit absolute directory
+npx dotmem storage restore          # migrate back to default
+```
+
+Project experience is stored under `<storage-root>/projects/<project-id>.mem`. User experience uses `user.mem`, agent memory uses `agent.mem`, and logic data uses `logic.mem`. These are `.mem` packages — compressed ZIP archives with SHA-256 integrity manifests. Read them through `npx dotmem inspect`, never by byte-searching.
+
+---
+
+## Activation
+
+The activation phrases are `dotmem`, `npx dotmem`, `Joy`, and `Jo`. A message that is exactly one of them activates dotmem once for the session.
+
+When activated, dotmem follows a deterministic discovery order:
+
+1. Check `<storage-root>/DOTMEM.md` and read the contract.
+2. Load user-level memory from `user.mem`.
+3. Resolve the current project identity.
+4. Load project memory from `<storage-root>/projects/<project-id>.mem`.
+
+A carrier handshake (`npx dotmem handshake`) evaluates compatibility before projecting any context. Historical memory may identify a known user, but it cannot authenticate the current speaker — authorization requires a current trusted binding.
+
+---
+
+## Security
+
+- **Encryption is opt-in**, not default. Enable it per context or per scope with an encryption key.
+- **Client-side multitenancy** through isolated memory partitions.
+- **Policy-gated writes**: every `acquire`/`remember`/`patch` is evaluated against policy before persistence.
+- **Evidence tracking**: all claims carry source, observed timestamp, and epistemic type.
+- **Claim immutability**: stored claims are never edited. Corrections are appends with revision relations.
+- **Integrity via inspection**: `integrity: valid` means the bytes are unchanged since sealing — it says nothing about who wrote them or whether they are true.
+
+See [SECURITY.md](./SECURITY.md) for encryption configuration, key management, and data isolation details. See [MEMORY.md](./MEMORY.md) for the complete acquisition contract and policy language.
+
+---
+
+## Choosing a Layer
+
+| If the data is... | Use | Not |
+|---|---|---|
+| UI-reactive, ephemeral | `state` | `store` (unnecessary persistence) |
+| UI-reactive, must survive reload | `state` + `state.persist(path)` | hand-rolled sync |
+| Small key/value, must persist | `store` | `idb` (overkill) |
+| Structured, needs confidence/TTL/source | `memory.remember()` | `state`/`store` (no lifecycle) |
+| Structured, needs evidence/provenance | `memory.acquire()` | `memory.remember()` (no evidence) |
+| Relational, needs SQL | `sqlite` | `idb` (no query language) |
+| Large browser-only structured data | `idb` | `store` |
+| AI agent memory | `dotmem/agent` | `memory` (no namespace isolation) |
+
+> **Note**: "Must survive reload" only holds in a browser. In Node.js and Bun, `store` and `session` fall back to in-memory `Map`s that do not survive a process restart.
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [MEMORY.md](./MEMORY.md) | Full memory model: acquisition contract, policy language, epistemic typing |
+| [AGENTS.md](./AGENTS.md) | AI agent working rules, activation phrases, complete `memory.*` surface |
+| [SECURITY.md](./SECURITY.md) | Encryption, multitenancy, key management, threat model |
+| [PACKAGE.md](./PACKAGE.md) | Package contents, full quick-start, dependency graph |
+| [LICENSE.md](./LICENSE.md) | License |
+
+---
+
+## License
+
+(c) 2026 Dario Passariello. See [LICENSE.md](./LICENSE.md).

package/global.d.ts

@@ -0,0 +1,14 @@
+///
+// DOTMEM GLOBAL ENTRYPOINT TYPES
+//
+
+import type { memory, logic } from './index'
+
+declare global {
+  // eslint-disable-next-line no-var
+  var mem: typeof memory
+  var logic: typeof logic
+}
+
+export { memory, logic } from './index'
+export { default } from './index'

package/index.d.ts

@@ -0,0 +1,15 @@
+///
+// DOTMEM TYPE ENTRY POINT
+///
+
+/// <reference path="./types/exports.d.ts" />
+/// <reference path="./types/memory.d.ts" />
+/// <reference path="./types/agent.d.ts" />
+/// <reference path="./types/logic.d.ts" />
+/// <reference path="./types/policy.d.ts" />
+/// <reference path="./types/profile.d.ts" />
+/// <reference path="./types/inspect.d.ts" />
+/// <reference path="./types/assets.d.ts" />
+
+export * from './types/exports'
+export { default } from './types/exports'

package/package.json

@@ -1,6 +1,87 @@
 {
   "name": "dotmem",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "codeName": "dotmem",
+  "version": "0.0.2",
+  "license": "MIT",
+  "description": "The AI memory layer for agents and apps: acquired experience, discovery, context projection, continuity, and logic engine. Built on dotmem's state+store foundation.",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "copyright": "Dario Passariello",
+  "author": "Dario Passariello - <dariopassariello@gmail.com>",
+  "contributors": [
+    {
+      "name": "Dario Passariello",
+      "email": "dariopassarielloa@gmail.com"
+    },
+    {
+      "name": "Valeria Cala Scaglitta",
+      "email": "valeriacalascaglitta@gmail.com"
+    }
+  ],
+  "bin": {
+    "dotmem": "./dist/bin/cli.js",
+    "dotmem-mcp": "./dist/bin/mcp.js"
+  },
+  "keywords": [
+    ".mem",
+    "dotmem",
+    "ai-agent",
+    "agent-memory",
+    "acquired-experience",
+    "memory",
+    "continuity",
+    "knowledge",
+    "mcp",
+    "joytrend",
+    "joy",
+    "jo"
+  ],
+  "engines": {
+    "node": ">=18.0.0",
+    "bun": ">=1.4.0"
+  },
+  "files": [
+    "types/**/*",
+    "modules/**/*",
+    "template/**/*",
+    "index.d.ts",
+    "global.d.ts",
+    "dist/**"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "optionalDependencies": {
+    "@modelcontextprotocol/server": "^2.4.0",
+    "zod": "^4.6.7"
+  },
+  "overrides": {
+    "glob": "^14.0.2",
+    "minimatch": "^11.0.1"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./global": {
+      "import": "./dist/global.js",
+      "require": "./dist/global.cjs",
+      "types": "./dist/global.d.ts"
+    },
+    "./agent": {
+      "import": "./dist/agent.js",
+      "require": "./dist/agent.cjs"
+    }
+  },
+  "typings": "./dist/index.d.ts",
+  "scripts": {
+    "prepack": "node -e \"['dist/bin/cli.js','dist/bin/cli.cjs','dist/bin/mcp.js','dist/bin/mcp.cjs'].forEach(f=>{try{require('fs').chmodSync(f,0o755)}catch{}})\""
+  },
+  "dependencies": {
+    "dotmem": ">=0.0.1"
+  }
 }

package/types/agent.d.ts

@@ -0,0 +1,87 @@
+/**
+ * DOTMEM AGENT DECLARATIONS
+ *
+ * Mirrors the agent-facing memory API exported from `dotmem/agent`.
+ * Every agent gets an isolated namespace: keys are stored as
+ * `agent:<agentId>:<key>` and entries are tagged with the agent id, so two
+ * agents never share private memory by accident.
+ */
+
+import type {
+  ContextEntry,
+  MemoryEntry,
+  MemoryScope,
+  MemoryStats,
+  MemoryType,
+  RecallOptions
+} from './memory'
+
+export interface AgentContextOptions {
+  tags?: string | string[]
+  types?: MemoryType | MemoryType[]
+  minConfidence?: number
+  maxEntries?: number
+  scopes?: MemoryScope[]
+}
+
+export interface AgentRememberOptions {
+  type?: MemoryType
+  confidence?: number
+  scope?: MemoryScope
+  ttl?: number | null
+  tags?: string[]
+  source?: string
+}
+
+export interface AgentReplayOptions {
+  from: number | string
+  to: number | string
+}
+
+export interface AgentBranchState {
+  state: Record<string, unknown>
+  temporal: {
+    history: (path?: string) => MemoryEntry[]
+    at: (path: string, timestamp: string | number) => unknown
+    diff: (path: string, from: string | number, to: string | number) => MemoryEntry[]
+    replay: (opts?: { from?: string | number; to?: string | number }) => Record<string, unknown>
+    explain: (path: string) => unknown
+    branch: () => AgentBranchState
+    discard: () => void
+  }
+}
+
+export interface AgentMemory {
+  /** Identifier of the agent owning this isolated namespace. */
+  readonly agentId: string
+  /** Store a memory entry, namespaced and tagged for this agent. */
+  remember: (key: string, value: unknown, options?: AgentRememberOptions) => Promise<void>
+  /** Read a memory entry by key. Expired, obsolete, and superseded entries are null. */
+  recall: (key: string, options?: RecallOptions) => Promise<MemoryEntry | null>
+  /** Ranked memories for this agent only. Additional tags use AND semantics. */
+  context: (options?: AgentContextOptions) => Promise<ContextEntry[]>
+  /** Mutation history, optionally for one path. */
+  history: (path?: string) => Promise<MemoryEntry[]>
+  /** Replay the state evolution over a temporal range. */
+  replay: (opts: AgentReplayOptions) => Promise<Record<string, unknown>>
+  /** Open an isolated temporal branch for experimentation. */
+  branch: () => Promise<AgentBranchState>
+  /** Memory usage statistics. */
+  stats: () => Promise<MemoryStats>
+  /** Update an existing memory entry. */
+  update: (key: string, value: unknown, options?: AgentRememberOptions) => Promise<void>
+  /** Delete a memory entry. */
+  forget: (key: string) => Promise<void>
+  /** Enable temporal and history tracking. */
+  enable: (bool?: boolean) => Promise<void>
+  /** Disable temporal tracking. */
+  disable: () => Promise<void>
+  /** Clear the temporal log and every memory of this agent. */
+  clear: () => Promise<void>
+}
+
+/** Create an agent-specific memory instance with an isolated namespace. */
+export declare function createAgentMemory(agentId: string): AgentMemory
+
+/** Create an agent memory instance with the default agent id. */
+export declare function createDefaultAgentMemory(): AgentMemory

package/types/assets.d.ts

@@ -0,0 +1,4 @@
+declare module '*.md' {
+  const content: string
+  export default content
+}

package/types/bun-sqlite.d.ts

@@ -0,0 +1,14 @@
+declare module 'bun:sqlite' {
+  export class Database {
+    constructor(path: string)
+    run(sql: string, ...params: any[]): any
+    query(sql: string): { all(...params: any[]): any[]; get(...params: any[]): any }
+    close(): void
+    prepare(sql: string): { all(...params: any[]): any[]; get(...params: any[]): any }
+  }
+  export class Statement {
+    all(...params: any[]): any[]
+    get(...params: any[]): any
+    run(...params: any[]): any
+  }
+}