dotmem 0.0.5 → 0.0.8

package/llms.txt

@@ -0,0 +1,301 @@
+dotmem — AI memory layer for agents and apps (v0.0.8).
+Storage root: <user-home>/.mem (override: DOTMEM_STORAGE_ROOT)
+
+=== Installation ===
+npm i dotmem
+bun i dotmem
+pnpm i dotmem
+
+=== MCP Server ===
+Register in Claude Desktop (claude_desktop_config.json):
+  "dotmem": {
+    "command": "npx",
+    "args": ["-y", "-p", "dotmem", "dotmem-mcp"],
+    "env": { "DOTMEM_MCP_WRITE": "1" }
+  }
+Register in Kilo/OpenCode (kilo.jsonc / opencode.json):
+  "mcp": { "dotmem": {
+    "type": "local",
+    "command": ["npx", "-y", "-p", "dotmem", "dotmem-mcp"],
+    "environment": { "DOTMEM_MCP_WRITE": "1" }
+  } }
+
+Tools exposed:
+  dotmem_context        read  - relevant acquired experience for situation
+  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 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 learn "<text>" [--scope user|project] [--situation "<text>"] [--id "<id>"]
+npx dotmem inspect FILE.mem
+npx dotmem continuity [context|snapshot|forget] [-debug]
+npx dotmem handshake [--status|--reset|--unbind|--bind-hi "<id>" --scope "<scope>"]
+npx dotmem policy <command>
+npx dotmem guard <event> [--payload <json>]
+npx dotmem rule check
+npx dotmem rules
+npx dotmem violation <rule-id> "<situation>" "<description>"
+npx dotmem feedback <claim-id> <helped|misled|ignored>
+npx dotmem loop <add|list|close|show> [options]
+npx dotmem note <add|add-text|list|show|export|forget> [args]
+npx dotmem vault <put|resolve|list|forget> [args]
+npx dotmem session <show|doing>
+npx dotmem storage [--root|--capabilities|relocate <path>|restore]
+npx dotmem render <view> [--out <path>] [--json]
+npx dotmem verify
+npx dotmem doctor [--json|--fix]
+npx dotmem codenames
+npx dotmem spark --verify
+npx dotmem seed <file|-> [--title <text>] [--id <id>] [--scope user|project] [--dev]
+npx dotmem -v | --version
+npx dotmem -h | --help
+
+=== API (TypeScript) ===
+
+// From the main package entry point
+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()
+  // deprecated no-op; runtime initializes lazily on first call. Remove from app code.
+
+memory.discover(situation: string, options?: {
+  depth?: 'current' | 'deep',
+  maxCandidates?: number,
+  facts?: Record<string, string|number|boolean>
+}): Promise<DiscoveryResult>
+
+memory.context(options?: {
+  tags?: string | string[],
+  types?: MemoryType | MemoryType[],
+  minConfidence?: number,
+  maxEntries?: number,
+  scopes?: MemoryScope[],
+  project?: boolean
+}): Promise<AcquiredContext>
+
+memory.context(options: { acquired: Record<string, string|number|boolean> }): Promise<AcquiredContext>
+  // Exact applicability lookup by structured values
+
+memory.project(discovery: DiscoveryResult, options?: {
+  maxCandidates?: number,
+  maxCharacters?: number
+}): ContextProjection
+
+memory.acquire(opts: {
+  id: string,
+  knowledge: JsonValue,
+  applicability: Record<string, JsonPrimitive>,
+  evidence: EvidenceReference[],
+  epistemicType?: EpistemicType,
+  provenance?: ClaimProvenance,
+  acquiredAt?: string,
+  refines?: string | string[],
+  supersedes?: string | string[],
+  retracts?: string | string[],
+  reason?: string,
+  scope?: 'user' | 'project',
+  kind?: MemoryKind,
+  sourceProject?: string
+}): Promise<void>
+
+memory.acquireStaged(opts: AcquireOptions): Promise<void>
+
+memory.remember<T>(key: string, value: T, opts?: {
+  id?: string,
+  type?: MemoryType,
+  confidence?: number,
+  scope?: MemoryScope,
+  ttl?: number | null,
+  tags?: string | string[],
+  source?: string
+}): Promise<void>
+
+memory.recall<T>(query: string | number, opts?: {
+  type?: MemoryType | MemoryType[],
+  tags?: string | string[],
+  minConfidence?: number,
+  includeObsolete?: boolean
+}): Promise<T | null>
+
+memory.update(key: string, value: any, opts?: Partial<RememberOptions>): Promise<void>
+
+memory.forget(key: string): Promise<void>
+
+memory.patch(key: string, patches: PatchOperation[]): Promise<void>
+
+memory.stats(): Promise<MemoryStats>
+memory.forgetExpired(): Promise<number>
+memory.clear(): Promise<void>           // memory-layer entries only (policy store intact)
+memory.fingerprint(): Promise<string>
+
+--- sub-facades ---
+
+memory.journal.read(opts?: { limit?: number }): Promise<JournalEntry[]>
+memory.journal.write(entry: JournalEntry | JournalEntry[]): Promise<void>
+memory.journal.clear(): Promise<void>
+
+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>
+memory.note.list(): Promise<NoteEntry[]>
+memory.note.forget(id: string): Promise<void>
+
+memory.seed  // development-only Joy seed injection (requires --dev)
+
+--- policy ---
+
+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
+  resolveEffectiveTier(event: PolicyEvent): EnforcementTier
+  resolveEffectivePolicies(...): EffectivePolicyState
+
+memory.policy.evaluate(event): PolicyDecision     // decision-time pull
+memory.policy.override.{grant|revoke|list|effective}()
+
+
+--- 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 ---
+
+continuity.context(options?: { debug?: boolean }): Promise<ContinuityContext>
+continuity.snapshot(data: object): Promise<SnapshotResult>
+continuity.forget(subject: string): Promise<void>
+
+--- agent memory (dotmem/agent) ---
+
+const agent = createAgentMemory(agentId: string)
+
+agent.remember(key: string, value: unknown, opts?: AgentRememberOptions): Promise<void>
+agent.recall(key: string, opts?: RecallOptions): Promise<MemoryEntry | null>
+agent.context(opts?: AgentContextOptions): Promise<ContextEntry[]>
+agent.update(key: string, value: unknown, opts?: AgentRememberOptions): Promise<void>
+agent.forget(key: string): Promise<void>
+agent.history(path?: string): Promise<MemoryEntry[]>
+agent.replay(opts: { from: number | string; to: number | string }): Promise<Record<string, any>>
+agent.branch(): Promise<AgentBranchState>
+agent.enable(bool?: boolean): Promise<void>
+agent.disable(): Promise<void>
+agent.stats(): Promise<MemoryStats>
+agent.clear(): Promise<void>
+
+createDefaultAgentMemory(): returns instance bound to 'default-agent'
+
+--- LLM cache ---
+
+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 ---
+
+resolveDotMemStorageRoot(): string
+describeDotMemStorage(): DotMemStorageDescription
+resolveUserDotMemPath(): string
+resolveUserProjectMemoryPath(projectId?: string): string
+resolveProjectIdentity(id?: string): Promise<string>
+resolveUserIdentity(): UserIdentity | null
+setUserIdentity(id: string, identity: UserIdentity): void
+clearUserIdentity(): void
+
+--- mem package inspection ---
+
+inspectMem(path: string | unknown, opts?: Record<string, unknown>): MemInspection
+signEmpackage(pkg: unknown, key: unknown): unknown
+
+=== Memory Model ===
+
+Acquire → Discover → Project
+
+Claims (AcquireOptions):
+  - id: string (unique, deterministic)
+  - 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'
+  - provenance: { source, detail? }
+  - scope: 'user' | 'project'
+  - kind: 'experience' | 'agent' | 'relationship' | 'logic' | 'note'
+  - revision: { kind: 'refines'|'supersedes'|'retracts', claimIds: string[], reason? }
+
+Scopes:
+  - hot: ephemeral, in-memory only
+  - session: active session lifetime
+  - local: Node/Bun process-bound
+  - durable: disk-backed, survives restarts
+
+Discovery depths:
+  - current: active claims only
+  - deep: includes superseded/obsolete
+
+Projection statuses:
+  - ContextProjection.status = 'candidate-context-not-current-truth'
+
+=== Policy Enforcement Tiers ===
+
+| 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>/.mem (override: DOTMEM_STORAGE_ROOT)
+Project:   <storage>/projects/<project-id>.mem
+User:      <storage>/user.mem
+Agent:     <storage>/agent.mem
+Logic:     <storage>/logic.mem
+
+=== Security ===
+
+- Encryption: OPT-IN (not default). Enable per-context or per-scope with encryptionKey.
+- Client-side multitenancy: isolated memory partitions via createContext/isolate
+- Policy-gated writes: every acquire/remember/patch evaluated against policy
+- 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
+
+See SECURITY.md for encryption configuration and threat model.
+See MEMORY.md for acquisition contract and policy language.
+See AGENTS.md for AI working rules and the complete memory.* surface.