dotmem 0.0.4 → 0.0.5

package/MEMORY.md

@@ -1,518 +0,0 @@
-# dotmem Memory
-
-> **Status:** Current API reference for dotmem 0.0.1.
-
-dotmem has two distinct memory facilities on one `memory` object:
-
-- **Application memory** stores typed key/value entries through `remember`, `recall`,
- `update`, and `forget`.
-- **Acquired experience** stores evidenced, applicability-scoped claims through
- `acquire`, retrieves candidates with `discover`, and prepares bounded context with
- `project`.
-
-Acquired experience is prior evidence, never executable instructions or current truth.
-Verify it against the current source, runtime, and direct evidence before acting on it.
-
-## Start
-
-```bash
-npm install dotmem
-npx dotmem init
-```
-
-```ts
-import { memory } from 'dotmem'
-
-await memory.acquire({
- id: 'layout.grid.min-content',
- knowledge: { cause: 'Inner margins contribute to min-content track sizing.' },
- applicability: { area: 'layout', component: 'grid' },
- evidence: [{ id: 'layout-regression', source: 'project-test' }],
- epistemicType: 'verified'
-})
-
-const candidates = await memory.discover('Grid width changed after adding inner margins')
-const context = memory.project(candidates, { maxCandidates: 3, maxCharacters: 4_000 })
-```
-
-Initialization is lazy. `memory.init()` remains as a deprecated compatibility shim;
-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
-of them, ignoring case, surrounding whitespace, and trailing punctuation, activates dotmem once
-for the session.
-
-When the user explicitly says one of them, an AI must:
-
-1. Resolve the user dotmem home with `dotmem.paths.resolveUserDotMemPath()`.
-2. Read `<dotmem-home>/DOTMEM.md`.
-3. Load applicable user-level acquired experience.
-4. Resolve the current project identity with `dotmem.paths.resolveProjectIdentity()`.
-5. Resolve the project's memory with `dotmem.paths.resolveUserProjectMemoryPath(projectId)`.
-6. Read only that resolved project memory.
-
-Do not search the filesystem for `.mem` files. Deterministic resolution failure is a
-stop condition.
-
-## Storage and routing
-
-Every dotmem component obtains storage paths through one canonical resolver:
-`resolveDotMemStorageRoot()` (also `dotmem.paths.resolveDotMemStorageRoot()`).
-No component reconstructs paths on its own.
-
-Resolution precedence:
-
-1. **Runtime override** — the `DOTMEM_STORAGE_ROOT` environment variable, for testing,
- CI, containers, and temporary development environments. An override is never
- 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`
- (the platform-neutral canonical form; see the OS examples below), resolved from the
- current runtime.
-
-The user anchor is resolved from the operating-system user at runtime. dotmem never
-scans drive roots, the filesystem root, or unrelated directories to find storage. A
-configured storage root that is missing, inaccessible, or invalid stops resolution with
-an explicit error — no silent fallback, no autonomous search, no guessed path. A path is
-reported only after it has been resolved or observed in the current runtime; otherwise
-report the semantic location (user memory, project memory, temporary staging, canonical
-storage, user anchor).
-
-Storage relocation is user-controlled and verified:
-
-```bash
-npx dotmem storage # semantic location + resolved storage root
-npx dotmem storage --root # resolved storage root only (scriptable)
-npx dotmem storage relocate <absolute-storage-dir> # migrate storage to an explicit absolute directory
-npx dotmem storage restore # migrate storage back to the default location
-```
-
-`relocate` copies the data, verifies it at the target, updates the locator, and only then
-reports completion; the locator never points at a location whose data has not been
-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`
-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
-```
-
-The runtime resolves the actual home directory from the OS/environment; no hardcoded
-platform path is ever a default.
-
-On Node.js and Bun, the writer selects a store from the top-level acquisition fields:
-
-| Kind and scope | File |
-| --- | --- |
-| `experience`, `scope: 'project'` (default) | `$DOTMEM_HOME/projects/<project-id>.mem` |
-| `experience`, `scope: 'user'` | `$DOTMEM_HOME/user.mem` |
-| `agent` | `$DOTMEM_HOME/agent.mem` |
-| `logic` | `$DOTMEM_HOME/logic.mem` |
-
-`<project-id>` resolves in order from `DOTMEM_PROJECT_ID`, `package.json`'s `name`,
-then the current directory's basename. Set `sourceProject` when writing project
-experience for a project other than the current working directory.
-
-`applicability` is flat JSON-primitive matching metadata. It is not routing. A claim
-with `applicability.scope` but no top-level `scope` is rejected to avoid this mistake.
-`kind: 'relationship'` is rejected by `acquire`; relationship graph writes belong to
-the dedicated brain API.
-
-Browser and edge environments use the existing `store`-backed acquired-knowledge
-repository and never load Node filesystem code. The CLI is Node-only.
-
-## Acquisition safety
-
-`memory.acquire()` validates JSON-safe claim data, sanitizes secret-looking keys and
-values before persistence, and writes
-atomically, and verifies that the claim was persisted. Sanitization replaces sensitive
-content with a semantic marker such as `requiresToken: true`; it is not a secret vault,
-encryption policy, access-control system, or authorization decision.
-
-Only an explicit `kind` changes the physical store; advisory content classification
-never changes routing. Never place credentials, private keys, access tokens, or
-chain-of-thought in acquired memory.
-
-## Claim trust and attribution
-
-The acquisition contract is the machine-readable description of what dotmem attests and what it
-only records:
-
-| Field class | Fields | Meaning |
-| --- | --- | --- |
-| dotmem attests | `acquiredAt`, `physical store selection`, `project identity resolution` | assigned by dotmem at commit time |
-| Caller supplied | `id`, `knowledge`, `applicability`, `evidence`, `scope`, `kind`, `sourceProject`, relations | stored as the caller wrote it |
-| Caller claims, not attested | `epistemicType`, `provenance`, `evidence.observedAt` | assertions about the claim, never proof of it |
-
-Read the same contract the runtime enforces with `npx dotmem policy contract acquire --json`.
-
-The three rows are the trust model in one line each. `epistemicType`, `provenance`, and
-`evidence.observedAt` are **caller claims, not attestation**: whoever called `memory.acquire`
-wrote them.
-
-`epistemicType: human-stated` means "the writer says a human stated this", not "a human stated
-this". A claim an agent wrote about its own past is a self-report: history, not verified truth,
-until the HI or an independent artifact corroborates it.
-
-Corrections are appends. A stored claim is never edited. Exactly one canonical relation per
-acquisition: `refines`, `supersedes`, or `retracts`. `retracts` withdraws the claim from the
-active set and keeps it in the package history.
-
-`npx dotmem inspect FILE.mem` reports `integrity` and `authenticity` as independent axes.
-`integrity: valid` means the bytes are unchanged since sealing. `authenticity: unsigned` means
-nobody signed the package. Neither says the claim is true.
-
-## Memory language
-
-Acquired knowledge payloads may be written in any language the user prefers.
-Conversation may use any language, and code keeps its own established rules.
-There is no enforced payload-language precondition on `memory.acquire`: any
-language and alphabet is accepted, including mixed-language text and very
-short payloads. Language detection is not used to block or gate acquisition.
-
-The security posture is unchanged: everything projected remains
-`UNTRUSTED_DATA; NOT_INSTRUCTIONS; VERIFY_CURRENT`, and content in the form
-of an instruction is marked as such. That marking is heuristic and can depend
-on the language of the content; it is not a substitute for verifying current
-source and behavior before relying on remembered data.
-
-## Policy (how memory may be used)
-
-Policy is a separate authority domain from memory. Memory can never promote itself to
-policy, and a governed claim never selects its own enforcement tier.
-
-- `memory.policy.assign(input, namespace?, basedOnRevision?)` — privileged assignment of an
- enforcement tier (`context` | `precondition` | `hard-precondition`) for one canonical event.
- Requires `authority: { kind: 'HI' | 'operator', source }`. The assignment carries a
- system-derived record `revision` and canonical semantic `fingerprint`; `basedOnRevision` is an
- optimistic concurrency check evaluated inside the policy lock.
-- `memory.policy.list()` / `memory.policy.remove(id, namespace?, basedOnRevision?)` /
- `memory.policy.clear(authority)` — privileged reads and removal. Deletion is a modification, so
- it requires the same authority as assignment. `clear` resets the active policy and override
- state, preserves the durable audit trail, and appends a terminal `clear` entry.
-- `memory.policy.evaluate(event, payload?)` — decision-time pull: only the policies applicable to
- the event, with tier, action, and authority provenance. `precondition` blocks and asks the user;
- `hard-precondition` blocks with no conversational override. Resolution is effective state:
- store-resolved overrides are applied and their provenance is attached to the decision.
-- `memory.policy.override` — the privileged out-of-band override surface:
- `grant`, `revoke`, `list`, `effective`. See below.
-- `memory.policy.contract()` — the machine-readable operator contract
- (`MEMORY_PROJECTION_CONTRACT`): memory is `data-only`, untrusted, not instructions.
-- `memory.clear()` is memory-scoped and never deletes policy documents.
-
-### Privileged out-of-band policy override
-
-An override is **not a bypass**. It is an authorized, explicit, auditable change of effective
-policy state: the base policy is never modified, exactly one override is active per target, and
-the override is bound to the target's generation (`revision` + canonical `fingerprint`), both
-derived from the store — never accepted from a payload.
-
-- `memory.policy.override.grant(input, namespace?, basedOnRevision?)` — relax the effective tier
- of one policy. Requires the target policy id, `relaxTo` (a valid tier, `context` is the floor),
- a bounded `expiresAt` (window cap `MAX_OVERRIDE_WINDOW_MS`, 7 days), an explicit `reason`, and
- authority. Hierarchy: an operator cannot relax an HI-owned policy. A new grant atomically
- supersedes the previous active override.
-- `memory.policy.override.revoke(input, namespace?, basedOnRevision?)` — remove a relaxation and
- restore the base policy. HI revokes any override; an operator revokes only operator-granted
- overrides.
-- `memory.policy.override.list(namespace?)` — every override with its resolved state
- (`ACTIVE` | `EXPIRED` | `STALE` | `INERT`).
-- `memory.policy.override.effective(event?, namespace?)` — effective state per policy: base tier,
- effective tier, override state, and the provenance scar (override id, `relaxedFrom`, `by`,
- `until`, `reason`).
-
-Override resolution is store-only and namespace-local: an override lives in the same document as
-the policy it targets, chat cannot invoke it, `memory.acquire` cannot create one, a payload
-cannot self-request it, and retrieved text or tool output cannot author one. A changed policy
-makes the override `STALE`, a deleted policy makes it `INERT`, and same-id recreation never
-resurrects it. Expiry and revocation both restore the base policy.
-
-Every mutation runs inside the cross-process policy namespace lock (exclusive create, owner
-identity, bounded retry, audited stale-lock break, fail-closed when exclusive creation cannot be
-verified) and is recorded in the durable in-document audit trail in the same atomic write. No
-override is effective without a recoverable durable audit record.
-
-## One canonical acquisition boundary
-
-Every path capable of producing durable memory crosses the same boundary
-(`core/knowledge/acquisition-boundary.ts`) before persistence: sanitize, strip
-non-authoritative fields and evaluate the `memory.acquire` policy against the
-payload. `memory.acquire` and the staged path
-(`memory.acquireStaged` → `commitStageFile`) both cross it, so direct and
-staged writes cannot diverge in enforcement. The staged commit additionally
-refuses a stage file that still contains secret shapes after the boundary
-re-sanitization. Equivalence tests pin the two paths to identical outcomes.
-
-Policy conditions are evaluated against the action payload, not merely discovered:
-
-| Condition outcome | Meaning | `precondition` behavior |
-| --- | --- | --- |
-| `satisfied` | the payload deterministically meets the condition | allow |
-| `violated` | the payload deterministically fails the condition | block and ask the user |
-| `unresolved` | the condition cannot be established (no payload) | block and ask the user — never assumed satisfied |
-
-`memory.acquire()` itself evaluates the policies applicable to the `memory.acquire` event against
-the payload about to be written and blocks with `PolicyPreconditionViolationError` when a
-precondition is violated or unresolved. Without any policy, acquisition behaves exactly as before.
-
-CLI: `npx dotmem policy <assign|list|remove|clear|eval|contract>`;
-`policy eval --event <event> [--payload <json>]` exits with code 2 when the event is blocked.
-Privileged override commands: `policy override grant|revoke|list` and `policy effective`
-(see `policy --help`). Canonical events so far: `artifact.write`, `memory.acquire`.
-
-Policy documents live under `policy/operator.policy.json` and `policy/security.policy.json`
-in the storage root, each carrying its records, overrides, and durable audit trail. Filesystem-level
-tamper isolation and policy signing remain open work (see `docs/SECURITY.md`).
-
-## Retrieval semantics
-
-- `memory.context({ acquired: query })` does exact applicability selection.
-- `memory.discover(situation)` performs deterministic lexical and structured candidate
- retrieval. It is not embedding or semantic-vector search.
-- `memory.project(discovery)` returns bounded candidates and `text` marked as
- untrusted prior context; it may omit candidates to meet its limits.
-
-`DISCOVERED != APPLICABLE` and `PROJECTED != CURRENT FACT`.
-
-`LABELLED != ATTESTED`: the epistemic label of a claim is written by the caller, never attested
-by dotmem. See [Claim trust and attribution](#claim-trust-attribution-and-correction).
-
-## Public API
-
-| API | Purpose |
-| --- | --- |
-| `init()` | Deprecated compatibility shim that prepares the runtime lazily. |
-| `acquire(opts)` | Persist an evidenced acquired claim using scope/kind routing. |
-| `discover(situation, options?)` | Find lexical/structured active candidates. |
-| `project(discovery, options?)` | Produce bounded, untrusted AI context. |
-| `context(opts)` | Exact acquired-context selection or ranked key/value retrieval. |
-| `policy.assign/list/remove/clear/evaluate/contract` | Privileged policy authority surface; see the Policy section. |
-| `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. |
-
-`AcquireOptions` includes `id`, `knowledge`, `applicability`, and `evidence`; optional
-fields are `epistemicType`, `provenance`, revision links, `scope`, `kind`, and
-`sourceProject`. See the checked-in type declaration at `types/memory.d.ts` for the
-precise TypeScript contract.
-
-`memory.context({ acquired })` returns `{ knowledgeVersion, claims: AcquiredClaim[] }`
-(the low-level acquired-context selection). The CLI `npx dotmem context --json` goes
-through `discover` + `project` and returns a `ContextProjection` envelope with
-`totalCandidates`, `omittedCandidates`, `experiences`, and `text`. The two surfaces are
-intentionally different: the API returns raw claims, the CLI returns bounded, projected
-context. `totalCandidates` is present on the CLI projection envelope, not on the raw
-`AcquiredContext` returned by `memory.context({ acquired })`.
-
-### Built-in seed claims
-
-dotmem ships with a small set of built-in seed claims that describe the
-acquisition logic itself. They are part of the product (`core/knowledge/logic-seed.ts`)
-and are loaded into the logic knowledge store on every installation:
-
-- `acquisition.experience-not-activity` — when to acquire (checkpoint principle)
-- `acquisition.value-sources` — where useful memory comes from
-- `acquisition.boundaries` — what to filter out, epistemic statuses
-- `acquisition.project-specific` — project-specific experience candidates
-- `relationship.continuity-pattern` — generalized AI-HI relationship pattern
-
-They are marked as `source: built-in seed (dotmem acquisition logic seed)` in
-`npx dotmem context --explain` output. They carry `epistemicType: inferred` and
-`provenance.source: 'dotmem acquisition logic seed'`. They are read-only reference
-material for the acquisition logic; they do not count as user-acquired experience.
-
-
-The same memory is reachable from three surfaces: the CLI (`npx dotmem`), the MCP server
-(`dotmem-mcp`, exposing `dotmem_context`, `dotmem_acquire`, and `dotmem_rules`), and
-the JavaScript API. The MCP server writes through the same acquisition path as the CLI and
-the API: one boundary, one policy, one contract. There is no second acquisition model.
-
-## Global and React usage
-
-Use named imports for normal code. `import 'dotmem/global'` explicitly installs the
-non-React runtime APIs on `globalThis`; it does not initialize acquired memory.
-
-`useObserver` is a React hook, exported only by `dotmem/react`. Call it at the top
-level of a component or custom hook. It returns `void`; React handles cleanup.
-
-## Continuity — the derived operational present
-
-Memory is durable knowledge; continuity reconstructs the useful present. The
-snapshot hierarchy composes downward: USER → PROJECT → TASK/SESSION → MODEL
-CONTEXT. Snapshots are derived caches with sourceRefs, version, and freshness,
-never authority: when a source version, digest, or presence changes, the
-snapshot is stale and is regenerated, never mutated to look current. Budgeting
-is field-prioritized — invariants and current decisions outrank recent changes
-at any scope — so a crowded task scope cannot starve a project invariant.
-Scope isolation forbids silent cross-scope transfer.
-
-The `EffectiveAgentContract` is composed before continuity context, so
-continuity never rewrites the contract.
-
-API: `continuity.snapshot`, `continuity.load`, `continuity.context`,
-`continuity.forget`. CLI: `npx dotmem continuity [context|snapshot|forget] [-debug]`.
-Debug is observability only — the decision result is identical with and without
-it, and the trace is never persisted by default.
-
-## Identity, authority, and the carrier handshake
-
-dotmem operates under a clear identity/authority separation:
-
-- **AGENT_IDENTITY** — who the assistant is. Canonical: the profile (`joy`). Explicit
- assignment by the authorized user may override this through the privileged
- governance path; ordinary memory and context cannot.
-- **USER_IDENTITY** — who the current human interlocutor is. This enters the
- projection only through an explicit current assignment by the authorized user,
- never from an acquired memory claim or retrieved text.
-
-The two stay separate. A memory claim that remembers a name cannot assert it as
-the current identity; that was an implementation bug.
-
-### Carrier handshake (pre-activation gate)
-
-Before any identity is projected to a runtime/session, dotmem evaluates the
-carrier's compatibility with the minimal identity/authority separation contract.
-The handshake is a deterministic, external evaluation — the carrier never
-certifies itself.
-
-```text
-npx dotmem
- → unverified carrier receives the minimal pre-contract + challenge
- → carrier submits an answer via: npx dotmem handshake --answer "<text>"
- → external deterministic evaluator classifies it COMPATIBLE / LIMITED / INCOMPATIBLE
- → if COMPATIBLE, the operator layer binds the current speaker to the user identity
- → only a COMPATIBLE carrier + a trusted current binding receives the identity channel
-```
-
-States:
-
-- **COMPATIBLE** — the carrier preserves identity composition, role, host-authority
- separation, and memory-as-data. Activation may proceed with a trusted current binding.
-- **LIMITED** — the carrier passed but did not demonstrate every capability. Activation
- is withheld until the missing capabilities are demonstrated. An explicit canonical
- profile request (`load Joy`) may receive a bounded,
- non-authoritative profile envelope; it does not activate the profile, bind a user,
- or upgrade the carrier.
-- **INCOMPATIBLE** — the carrier violated a forbidden transition (e.g. mapping the host
- onto HI authority). Identity activation is refused.
-
-The handshake result is **session state, never durable authority** (`durableAuthority: false`).
-It is bound to the runtime identity, contract revision, and handshake version; any change
-re-triggers the handshake.
-
-### Current-user binding
-
-Carrier compatibility and current-user authority are **separate events**:
-
-- A COMPATIBLE carrier still does not bind authority. It must be bound explicitly by
- the operator layer (the trusted current channel):
-
- ```bash
- npx dotmem handshake --bind-hi "<user name>" --scope "<scope>"
- ```
-
-- The bind is scoped and current: it records `boundHIIdentity` (the identity bound to
- this session) and `authorizationScope` (the scope of that binding). It is never
- inferred from memory, history, files, or conversation.
-- `--unbind` clears the current binding; the remembered identity stays informational.
-- `--reset` invalidates the session state (recovery step 3); `--status` reports the
- current session without evaluating anything.
-
-### Identity/runtime separation
-
-Host, provider, runtime, and model names are implementation metadata:
-
-- The operational role name (`Joy`) comes from the profile, not from the runtime.
-- The canonical identity is never fused with runtime/model metadata into a hybrid name
- (e.g. `Joy` or `HI`). dotmem detects and rejects such fusion
- attempts.
-- `knownHIIdentity` (the remembered user identity) is informational only and never
- authenticates the current speaker. Only `boundHIIdentity` (set by a trusted current
- binding) authorizes activation.
-
-See [`SECURITY.md`](./SECURITY.md)
-
-## Boundaries
-
-- `.mem` integrity and optional signatures do not make claims true or trustworthy.
-- A claim's `epistemicType` and `provenance` are caller claims, not attestation.
-- Namespaces and contexts are not authorization boundaries.
-- Encryption is opt-in; key management belongs to the application.
-- dotmem does not provide vector search, an IAM system, or secret management. Policy
- authority separation for acquired experience is implemented (see Policy); OS-level
- tamper isolation and policy signing remain open work.
-
-## 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`:
-
-| 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. |
-
-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.
-
-See [README.md](./README.md) for host registration examples (Kilo/OpenCode, Claude Desktop).
-
-### 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.
-
-| Command | MCP Exposure | Risk |
-| --- | --- | --- |
-| `session` | none | Local session state; no need for remote exposure. |
-| `loop` | none | Operator open loops; local management. |
-| `vault` | none | Secrets: never exposed via MCP (untrusted channel). |
-| `verify` | read-only | Freshness probes; read-only, low risk, but not high priority. |
-| `guard` | none | Pre-execution policy evaluation: requires event context, not suitable for MCP. |
-| `rule` / `rules` | read-only | Iron rules: already covered by `dotmem_rules`. |
-| `violation` | none | Violation log: write-side, do not expose. |
-| `violation clear` | none | Log deletion: destructive privileged operation. |
-| `policy assign/remove/clear` | none | Policy assignments: require HI/operator authority; never via MCP. |
-| `policy override grant/revoke` | none | Privileged override: requires explicit authority and audit. |
-| `install-extension` | removed | Extension removed from the project (see point 4). |
-
-### CLI command reference
-
-| Command | Purpose | Example | Type |
-| --- | --- | --- | --- |
-| `context "<situation>"` | Project the acquired experience for the given situation | `npx dotmem context "css grid layout" --json --claims-only` | read |
-| `init` | Create the project anchor in user storage | `npx dotmem init` | write |
-| `acquire` | Acquire a durable claim from JSON on stdin | `cat claim.json \| npx dotmem acquire` | write |
-| `learn "<text>"` | Acquisition from shorthand text | `npx dotmem learn "CSS rule" --id "css.1"` | write |
-| `inspect FILE.mem` | Validate and decode a `.mem` package | `npx dotmem inspect user.mem` | read |
-| `continuity` | Compose USER+PROJECT+TASK continuity | `npx dotmem continuity context` | read |
-| `handshake` | Carrier compatibility gate and authority binding | `npx dotmem handshake --answer "..."` | privileged |
-| `storage` | Show/relocate/restore the storage root | `npx dotmem storage --root` | read/write |
-| `policy` | Manage policy assignments and contracts | `npx dotmem policy list` | privileged |
-| `doctor [--json] [--fix]` | Duplicate and integrity audit | `npx dotmem doctor` | read |
-| `session [show\|doing]` | Current task state of the session | `npx dotmem session doing "task"` | read/write |
-| `loop <subcommand>` | Manage open loops (add\|list\|close\|show) | `npx dotmem loop add lp-1 "task"` | write |
-| `vault <subcommand>` | Local handle→value vault (put\|resolve\|list\|forget) | `npx dotmem vault put val --handle h1` | write |
-| `verify` | Freshness probes on claims | `npx dotmem verify` | read |
-| `guard <event> [--payload]` | Policy evaluation before a tool action | `npx dotmem guard tool.git-commit` | read |
-| `rule` / `rules` | Print the iron rules | `npx dotmem rules` | read |
-| `violation` | Violation log (list\|clear) | `npx dotmem violation list` | read/write |
-| `feedback <id> <type>` | Record operator feedback on a claim | `npx dotmem feedback id helped` | write |
-| `codenames` | Print reserved codenames | `npx dotmem codenames` | read |
-| `render <view>` | Render a markdown view from the store | `npx dotmem render agent-rules` | read |
-| `spark --verify` | Verify the scintilla block in docs/AGENTS.md | `npx dotmem spark --verify` | read |
-| `--version` / `-v` | Show the package version | `npx dotmem --version` | read |
-
-`guard --payload`: pass the JSON as a string argument. On PowerShell the double quotes in arguments are stripped, so use a file: save the JSON in `payload.json`, then read the file and use its contents, or use stdin where supported.
-
-`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.

package/PACKAGE.md

@@ -1,59 +0,0 @@
-# dotmem package — canonical entry point
-
-This document is the single source of truth for anyone reading `dotmem` on npm.
-It lists every document that ships inside the published package, and explains
-where to find what is not inside (ADRs, for example, live in an external catalog
-and are never bundled).
-
-## What ships inside the package
-
-| Document | Purpose |
-| --- | --- |
-| `README.md` | Product overview, install, MCP registration, layer table |
-| `MEMORY.md` | Memory model, acquisition contract, policy language, security posture |
-| `AGENTS.md` | AI working rules, native-first read ordering, `memory.*` surface |
-| `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 |
-
-## Quick start
-
-```bash
-npm install dotmem
-```
-
-### CLI
-```bash
-npx dotmem --help
-npx dotmem context "<situazione>" --json --claims-only
-npx dotmem storage
-npx dotmem handshake --status
-```
-
-### JavaScript API
-```js
-import m from 'dotmem'
-await m.memory.acquire({ id, knowledge, applicability, evidence })
-const ctx = await m.memory.context({ acquired: { area: 'x' } })
-```
-
-### MCP server (`dotmem-mcp`)
-Register with `DOTMEM_STORAGE_ROOT` and opt-in `DOTMEM_MCP_WRITE=1` for the write tool.
-
-## Links
-
-All links below resolve **inside the published package**:
-- [MEMORY.md](MEMORY.md) — memory model and acquisition contract
-- [AGENTS.md](AGENTS.md) — AI working rules
-- [llms.txt](llms.txt) — AI host surface
-- [SECURITY.md](SECURITY.md) — threat model
-- [CHANGELOG.md](CHANGELOG.md) — release history
-- [markdown/](markdown/) — render views