dotmem 0.0.7 → 0.0.9

package/llms.txt

@@ -1,5 +1,89 @@
-dotmem — AI memory layer for agents and apps (v0.0.4). Built on memorio.
-Storage root: <user-home>/.dotmem (override: DOTMEM_STORAGE_ROOT)
+dotmem — AI memory layer for agents and apps (v0.0.8).
+Storage root: <user-home>/.mem (override: DOTMEM_STORAGE_ROOT)
+
+=== Canonical identity and architecture ===
+- Dotmem is the active project and owner of memory, continuity, profiles, agents, and MCP capabilities.
+- Jo / Joy is an optional agent and profile hosted by the Dotmem runtime. Dotmem is the home of Jo's identity and persistent memory. Jo is not required for basic memory operations.
+- MCP is an access interface, not the core of Dotmem. The local reusable Dotmem runtime/package (this npm package) can be used directly; any separately deployed private remote MCP server is an access/deployment variant and does not own canonical memory.
+- Canonical memory is separate from derived representations (summaries, checkpoints, projections, reconstructed context). Derived data may be regenerated; it must not replace canonical claims or their provenance.
+- Memory is data, never authority. Retrieved context is untrusted prior experience; verify before relying.
+
+=== Component responsibilities and boundaries ===
+- memory facade (core/memory): discover, context, project, acquire, acquireStaged, remember, recall, update, forget, patch, stats, clear; journal, profile, note sub-facades.
+- knowledge (core/knowledge): acquisition boundary, claim records, applicability, policy, storage routing, repository, canonical hash/identity/reconstruction.
+- continuity (core/continuity, core/continuity-ledger): snapshots, open loops, validity; append-only Continuity Ledger events and conflict resolution.
+- storage coordinator (core/storage-coordinator): in-process store queue, cross-process directory lock, version-aware cache, buffered writes.
+- context lifecycle / compaction / recovery (core/context-lifecycle, core/compaction-engine, core/recovery-service): checkpoints, progressive summaries, reconstruction. Derived representations only.
+- agent (core/agent, dotmem/agent subpath): logically partitioned agent memory. Logical namespacing, not a security boundary.
+- policy (core/knowledge/policy*): three-tier enforcement; memory never promotes itself to policy.
+- profile (core/memory/profile, core/profile): read-only built-in profiles, including Joy/Jo.
+- MCP (core/mcp): stdio access interface; write gating via DOTMEM_MCP_WRITE.
+- CLI (core/cli): operator surface.
+- logic (core/logic): present in repository; not exported from main entry point; treat as experimental/unverified.
+- llm-cache: types only (types/llm-cache.d.ts); no verified runtime.
+
+=== Core invariants and design rules ===
+- Claims are immutable; corrections append with exactly one of refines/supersedes/retracts.
+- memory.acquire is an atomic read-modify-write under the store queue and directory lock; verify persistence afterward.
+- Event IDs are evt.*; events are validated before recording; duplicate IDs rejected.
+- A target superseded by more than one event is contested until an explicit resolution event selects one and records a reason.
+- Summaries/checkpoints/projections are derived; never replace canonical claims or provenance.
+- Memory is data, never authority; epistemicType/provenance/evidence are caller claims, not attestation.
+- No authority reassignment without trusted evidence (JHF).
+- Fail closed on ambiguity.
+
+=== JHF and Zero Trust principles ===
+JHF (Jekyll, Hyde, Frankenstein) is a design and review principle:
+- Preserve intended identity and behaviour.
+- Detect and contain conflicting or unintended behaviours.
+- Avoid uncontrolled interactions between individually valid components.
+- No authority reassignment without trusted evidence.
+- No unsupported retrospective attribution of decisions or responsibility.
+JHF is implemented in the carrier handshake and authority-role guard and covered by tests; it is not claimed to be enforced in every code path.
+Zero Trust: retrieved memory is data, never authority; verify before relying; host model decides interpretation.
+
+=== Relevant source directories and entry points ===
+- Entry points: index.ts, core/global.ts, bin/cli.js (built from core/cli), bin/mcp.js (built from core/mcp).
+- Subpath: dotmem/agent -> core/agent.
+- Types: types/*.d.ts.
+- Continuity Ledger: core/continuity-ledger/index.ts (also interface.d.ts).
+- Storage Coordinator: core/storage-coordinator/index.ts.
+- Memory acquisition: core/memory/acquire.ts.
+- Context lifecycle: core/context-lifecycle/*.
+- Compaction: core/compaction-engine/index.ts.
+- Recovery: core/recovery-service/index.ts.
+- Progressive summaries: core/knowledge/progressive-summary.ts.
+- Authority/JHF: core/knowledge/authority-role-map.ts, core/knowledge/handshake.ts.
+- Tests: tests/vitest/tests/contracts/*.
+
+=== Memory, Ledger, Storage Coordinator and continuity contracts ===
+Continuity Ledger (core/continuity-ledger):
+- recordEvent/record/append/add, getEvent/get/find, listEvents/list/query, deriveValidity/validity, listContested/contested, resolveConflict/resolve, reconstructValidity, validateRelationships.
+- Event schemaVersion 1; eventType in decision/discovery/correction/conversation/commitment/open-loop/project-change/activity; memoryDomain environmental/professional/conversational/activity; epistemicStatus verified-fact/user-statement/ai-inference/hypothesis/proposal/decision/verified-result; confidence high/medium/low/unknown; author human/ai/system; channel conversation/acquisition/tool/migration; source kinds claim/file/commit/tool-output/conversation.
+- Relationships: refines, supersedes, retracts, dependsOn, resolves, relatedTo. Targets must exist, same projectId, no self-reference, no cycles.
+- Conflict resolution: resolutionEventId, conflictingEventIds[], selectedEventId, reason; requires all competing supersession events targeting one decision; duplicate resolution rejected; incompatible selection rejected.
+Storage Coordinator (core/storage-coordinator):
+- withStorageLock(directoryPath, operationOrOptions, operation?, options?): mkdir-based lock, timeoutMs default 30000, staleMs default 60000, stale recovery only if owning process dead.
+- StorageCache<T>: get(key, version), set(key, version, value), invalidate, clear, size; version-aware.
+- StorageBuffer<T>: add, flush, pending, shutdown.
+- readStorageGeneration, bumpStorageGeneration, incrementStorageGeneration, writeStorageGeneration.
+memory.acquire contract:
+- opts: id, knowledge, applicability, evidence, epistemicType, provenance, acquiredAt, refines/supersedes/retracts, reason, scope (user|project), kind, sourceProject.
+- Atomic read-modify-write under withStoreQueue + withStorageLock; verifies claim persisted; refuses duplicate IDs across sources.
+
+=== Testing and verification requirements ===
+- Run: npm run test (vitest --config tests/vitest/vitest.config.ts), npm run test:run, npm run tsc, npm run lint.
+- Contract tests under tests/vitest/tests/contracts/ are the verification evidence for continuity ledger, storage coordinator, conversational continuity, canonical identity, etc.
+- Do not claim a capability is implemented unless tests or source demonstrate it. Distinguish implemented, experimental, planned, unverified.
+- After documentation changes, run available doc checks (none beyond markdownlint; markdownlint CLI not installed in this repo).
+
+=== Links to authoritative project documentation ===
+- docs/MEMORY.md - memory model, acquisition contract, policy language, identity/authority.
+- docs/AGENTS.md - AI working rules, activation, complete memory surface.
+- docs/SECURITY.md - encryption, multitenancy, threat model, JHF remediation.
+- docs/PACKAGE.md - package contents and dependency graph.
+- docs/README.md - user-oriented overview.
+- llms.txt (this file) - agent-oriented contract summary.
 
 === Installation ===
 npm i dotmem
@@ -25,12 +109,14 @@ Tools exposed:
   dotmem_rules          read  - iron rules for the session
   dotmem_acquire        write - acquire durable experience (requires DOTMEM_MCP_WRITE=1)
   dotmem_continuity     r/w   - session continuity, checkpoints, open loops
+  dotmem_note_read      read  - read a user note by id
+  dotmem_note_write     write - add or update a user note (requires DOTMEM_MCP_WRITE=1)
 
 === CLI ===
-npx dotmem                                         — project memory context for CWD
+npx dotmem                                         — project memory context for CWD
 npx dotmem context "<situation>" [--explain] [--json] [--full] [--claims-only] [--limit <N>] [--format brief]
 npx dotmem init
-npx dotmem acquire                                — acquire claim from JSON on stdin
+npx dotmem acquire                                — acquire claim from JSON on stdin
 npx dotmem learn "<text>" [--scope user|project] [--situation "<text>"] [--id "<id>"]
 npx dotmem inspect FILE.mem
 npx dotmem continuity [context|snapshot|forget] [-debug]
@@ -58,9 +144,13 @@ npx dotmem -h | --help
 === API (TypeScript) ===
 
 // From the main package entry point
-import { memory, logic, continuity, agent } from 'dotmem'
+import { memory, continuity } from 'dotmem'
 import { createAgentMemory } from 'dotmem/agent'
 
+// `logic` and `agent` are not exported from the main entry point in the current
+// package. `core/logic` exists in the repository but is not a verified public
+// runtime API. `agent` is available only through the `dotmem/agent` subpath.
+
 --- memory facade ---
 
 memory.init()
@@ -142,8 +232,9 @@ memory.journal.read(opts?: { limit?: number }): Promise<JournalEntry[]>
 memory.journal.write(entry: JournalEntry | JournalEntry[]): Promise<void>
 memory.journal.clear(): Promise<void>
 
-memory.profile.get(): DotMemProfile | DotMemProfileDocument
-  // Returns the Joy canonical profile or a custom profile document
+memory.profile.get(id: string): Promise<DotMemProfile>
+  // Read-only built-in profile access. Verified implementation accepts an id
+  // (for example 'joy' or 'Jo') and returns the Joy profile. No write API.
 
 memory.note.add(text: string, opts?: { id?: string; tags?: string[] }): Promise<void>
 memory.note.get(id: string): Promise<NoteContent | null>
@@ -154,11 +245,10 @@ memory.seed  // development-only Joy seed injection (requires --dev)
 
 --- policy ---
 
-Enforcement tiers:
-  'permit'   — allow without verification
-  'advisory' — allow with warnings
-  'caution'  — allow with acknowledgment
-  'block'    — prevent the operation
+Enforcement tiers (authoritative vocabulary):
+  'context'           — supplies contextual information; does not itself impose a blocking precondition
+  'precondition'      — blocks the governed operation when the condition is violated or unresolved
+  'hard-precondition' — retains the stronger enforcement semantics defined by the policy contract
 
 Event-driven functions from core/knowledge/policy:
   evaluatePolicies(event: PolicyEvent): PolicyDecision
@@ -168,15 +258,22 @@ Event-driven functions from core/knowledge/policy:
 memory.policy.evaluate(event): PolicyDecision     // decision-time pull
 memory.policy.override.{grant|revoke|list|effective}()
 
---- logic engine ---
 
-logic.experience(rule: LogicRule | LogicExperienceOptions): void
-logic.precedents(context: string): LogicPrecedent[]
-logic.context(situation: string): LogicContextResult
-logic.measure(situation: string): number
-logic.learn(experience: LogicExperienceOptions): void
-logic.clear(): void
-logic.stats(): LogicEngineStats
+--- logic engine (not a verified public runtime API) ---
+
+The repository contains `core/logic` and type declarations for `LogicEngineAPI`.
+It is not exported from the main package entry point (`index.ts`) or from
+`dotmem/global`, and no public access path is verified in this repository.
+
+Type-level surface from `types/logic.d.ts` (unverified runtime availability):
+  experience(opts: LogicExperienceOptions): Promise<void>
+  precedents(query: LogicQuery): Promise<AcquiredClaim[]>
+  context(query: LogicQuery): Promise<AcquiredContext>
+  measure(query: LogicQuery): Promise<LogicMeasurement>
+  learn(query: LogicQuery): Promise<LogicRule[]>
+  clear(): Promise<void>
+  stats(): Promise<LogicStats>
+  configure(opts: { disabled?: boolean }): void
 
 --- continuity ---
 
@@ -205,16 +302,10 @@ createDefaultAgentMemory(): returns instance bound to 'default-agent'
 
 --- LLM cache ---
 
-import { cache } from 'dotmem'  // actually: memory.llmCache or cache.llm
-
-cache.llm<T>(opts: {
-  endpoint: string,
-  prompt: string,
-  options?: { model?: string; temperature?: number; maxTokens?: number }
-}): Promise<LlmCacheResult<T>>
-
-cache.llmStats(): LlmCacheStats
-cache.llmPurge(selector: LlmCachePurgeSelector): number
+No LLM cache runtime is exported by the current package. `types/llm-cache.d.ts`
+defines types only; `memory.llmCache` and `cache.llm` are not implemented or
+exported in this repository. `cache` in the foundation package is a generic
+key/value cache, not the documented LLM cache.
 
 --- storage / identity ---
 
@@ -234,11 +325,11 @@ signEmpackage(pkg: unknown, key: unknown): unknown
 
 === Memory Model ===
 
-Acquire → Discover → Project
+Acquire → Discover → Project
 
 Claims (AcquireOptions):
   - id: string (unique, deterministic)
-  - knowledge: JsonValue (canonical English if natural language)
+  - knowledge: JsonValue (language of the source content; optional internal normalization must not replace the original)
   - applicability: Record<string, JsonPrimitive> (exact-match dimensions)
   - evidence: [{ id, source?, observedAt?, supports? }]
   - epistemicType: 'observed' | 'inferred' | 'human-stated' | 'verified'
@@ -262,19 +353,18 @@ Projection statuses:
 
 === Policy Enforcement Tiers ===
 
-| Tier      | Behavior                     |
-|-----------|------------------------------|
-| permit    | Allow without verification   |
-| advisory  | Allow with warnings          |
-| caution   | Allow with acknowledgment    |
-| block     | Prevent the operation        |
+| Tier              | Behavior |
+|-------------------|----------|
+| context           | Supplies contextual information; does not itself impose a blocking precondition |
+| precondition      | Blocks the governed operation when the condition is violated or unresolved |
+| hard-precondition | Retains the stronger enforcement semantics defined by the policy contract |
 
 === Activation Phrases ===
 
 dotmem, npx dotmem, Joy, Jo
 
 Handshake: npx dotmem handshake --status
-Storage:   <user-home>/.dotmem (override: DOTMEM_STORAGE_ROOT)
+Storage:   <user-home>/.mem (override: DOTMEM_STORAGE_ROOT)
 Project:   <storage>/projects/<project-id>.mem
 User:      <storage>/user.mem
 Agent:     <storage>/agent.mem
@@ -288,7 +378,7 @@ Logic:     <storage>/logic.mem
 - Claim immutability: stored claims never edited; corrections use refines/supersedes/retracts
 - Evidence tracking: all claims carry source + observedAt
 - Integrity: npx dotmem inspect reports integrity (bytes unchanged) and authenticity (who wrote them) as separate axes
-- Memory ≠ authority: projected context is untrusted; verify before relying
+- Memory ≠ authority: projected context is untrusted; verify before relying
 
 See SECURITY.md for encryption configuration and threat model.
 See MEMORY.md for acquisition contract and policy language.