dotmem 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,347 @@
+# 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).