dotmem 0.0.7 → 0.0.8

package/llms.txt

@@ -1,5 +1,5 @@
-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)
 
 === Installation ===
 npm i dotmem
@@ -25,6 +25,8 @@ 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
@@ -58,9 +60,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 +148,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 +161,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 +174,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 +218,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 ---
 
@@ -238,7 +245,7 @@ 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 +269,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