dotmem 0.0.4 → 0.0.5

package/llms.txt

@@ -1,295 +0,0 @@
-dotmem — AI memory layer for agents and apps (v0.0.4). Built on memorio.
-Storage root: <user-home>/.dotmem (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
-
-=== 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, logic, continuity, agent } from 'dotmem'
-import { createAgentMemory } from 'dotmem/agent'
-
---- 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(): DotMemProfile | DotMemProfileDocument
-  // Returns the Joy canonical profile or a custom profile document
-
-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:
-  'permit'   — allow without verification
-  'advisory' — allow with warnings
-  'caution'  — allow with acknowledgment
-  'block'    — prevent the operation
-
-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}()  // privileged override (ADR-019)
-
---- 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
-
---- 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 ---
-
-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
-
---- 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 (canonical English if natural language)
-  - 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                     |
-|-----------|------------------------------|
-| permit    | Allow without verification   |
-| advisory  | Allow with warnings          |
-| caution   | Allow with acknowledgment    |
-| block     | Prevent the operation        |
-
-=== Activation Phrases ===
-
-dotmem, npx dotmem, Joy, Jo
-
-Handshake: npx dotmem handshake --status
-Storage:   <user-home>/.dotmem (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.