dotmem 0.0.8 → 0.1.0

package/llms.txt

@@ -1,5 +1,89 @@
-dotmem — AI memory layer for agents and apps (v0.0.8).
-Storage root: <user-home>/.mem (override: DOTMEM_STORAGE_ROOT)
+dotmem — AI memory layer for agents and apps (v0.0.8).
+Storage root: <user-home>/.dotmem (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
@@ -29,10 +113,10 @@ Tools exposed:
   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]
@@ -162,9 +246,9 @@ 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
+  '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
@@ -241,7 +325,7 @@ signEmpackage(pkg: unknown, key: unknown): unknown
 
 === Memory Model ===
 
-Acquire → Discover → Project
+Acquire → Discover → Project
 
 Claims (AcquireOptions):
   - id: string (unique, deterministic)
@@ -280,7 +364,7 @@ Projection statuses:
 dotmem, npx dotmem, Joy, Jo
 
 Handshake: npx dotmem handshake --status
-Storage:   <user-home>/.mem (override: DOTMEM_STORAGE_ROOT)
+Storage:   <user-home>/.dotmem (override: DOTMEM_STORAGE_ROOT)
 Project:   <storage>/projects/<project-id>.mem
 User:      <storage>/user.mem
 Agent:     <storage>/agent.mem
@@ -294,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.

package/mcp.cjs

@@ -22,6 +22,18 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// suppress-idb-warning.ts
+var orig;
+var init_suppress_idb_warning = __esm({
+  "suppress-idb-warning.ts"() {
+    orig = console.warn.bind(console);
+    console.warn = (...args) => {
+      if (typeof args[0] === "string" && args[0].includes("IndexedDB is not available")) return;
+      orig(...args);
+    };
+  }
+});
+
 // core/env.ts
 var DEV;
 var init_env = __esm({
@@ -2406,6 +2418,7 @@ var init_policy_store = __esm({
       if (entry.target !== void 0) built.target = entry.target;
       if (entry.reason !== void 0) built.reason = entry.reason;
       if (entry.detail !== void 0) built.detail = entry.detail;
+      if (entry.mandatory !== void 0) built.mandatory = entry.mandatory;
       return built;
     }, "validatePolicyAuditEntry");
     validatePolicyDocument = /* @__PURE__ */ __name((value) => {
@@ -2483,6 +2496,7 @@ var init_policy_store = __esm({
       if (entry.target !== void 0) built.target = entry.target;
       if (entry.reason !== void 0) built.reason = entry.reason;
       if (entry.detail !== void 0) built.detail = entry.detail;
+      if (entry.mandatory !== void 0) built.mandatory = entry.mandatory;
       return built;
     }, "buildAuditEntry");
     boundedAudit = /* @__PURE__ */ __name((entries2, overrides) => {
@@ -2495,9 +2509,10 @@ var init_policy_store = __esm({
       for (let index = entries2.length - 1; index >= 0; index--) {
         const entry = entries2[index];
         const activeLinked = entry.target !== void 0 && activeOverrideIds.has(entry.target) && (entry.action === "override" || entry.action === "revoke");
-        if (activeLinked || budget > 0) {
+        const mandatory = entry.mandatory === true;
+        if (activeLinked || mandatory || budget > 0) {
           kept.unshift(entry);
-          if (!activeLinked) budget--;
+          if (!activeLinked && !mandatory) budget--;
         }
       }
       return kept;
@@ -2538,6 +2553,12 @@ var init_policy_store = __esm({
         try {
           await fs.writeFile(temporary, `${JSON.stringify(document, null, 2)}
 `, "utf8");
+          const handle = await fs.open(temporary, "r+");
+          try {
+            await handle.sync();
+          } finally {
+            await handle.close();
+          }
           await fs.rename(temporary, filePath);
         } catch (error) {
           await fs.rm(temporary, { force: true }).catch(() => void 0);
@@ -4457,7 +4478,7 @@ function encodeMemFile(stateValue, preserved) {
 function decodeMemDocument(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid .mem file format");
   const file = value;
-  if (file.format !== MEM_FORMAT) throw new Error("Invalid .mem file format");
+  if (file.format !== MEM_FORMAT && file.format !== MEM_FORMAT_LEGACY) throw new Error("Invalid .mem file format");
   if (file.version === MEM_FORMAT_VERSION_V1) {
     if (!file.knowledge) throw new Error("Invalid .mem file format");
     return { state: validateSourceState(file.knowledge) };
@@ -4539,11 +4560,12 @@ function decodeMemDocument(value) {
     preserved: { map: structuredClone(map), data: structuredClone(stateRecord) }
   };
 }
-var MEM_FORMAT, MEM_FORMAT_VERSION, MEM_FORMAT_VERSION_V1, expectedFields, epistemicTypes, revisionKinds, claimKinds, isJsonValue2, createMemInterpretationMap, validateSourceState, trimRecord, fieldIndexes, validateVocabulary, put, get, optionalGet, requireRecord, putOptional;
+var MEM_FORMAT, MEM_FORMAT_LEGACY, MEM_FORMAT_VERSION, MEM_FORMAT_VERSION_V1, expectedFields, epistemicTypes, revisionKinds, claimKinds, isJsonValue2, createMemInterpretationMap, validateSourceState, trimRecord, fieldIndexes, validateVocabulary, put, get, optionalGet, requireRecord, putOptional;
 var init_mem_codec = __esm({
   "core/knowledge/mem-codec.ts"() {
     init_state();
     MEM_FORMAT = "dotmem.knowledge";
+    MEM_FORMAT_LEGACY = "memorio.knowledge";
     MEM_FORMAT_VERSION = 2;
     MEM_FORMAT_VERSION_V1 = 1;
     expectedFields = {
@@ -4649,12 +4671,13 @@ async function decodeMemArtifact(input) {
     throw new MemArtifactError(message.startsWith("Unsupported") ? "unsupported" : "invalid", message);
   }
 }
-var MEM_PACKAGE_FORMAT, MEM_PACKAGE_VERSION, MEM_PACKAGE_LIMITS, MEM_PACKAGE_WRITE_MARGIN_BYTES, MEM_PACKAGE_WRITE_LIMITS, MANIFEST_PATH, MAP_PATH, DATA_PATH, INTEGRITY_PATH, requiredParts, encoder2, decoder, MemArtifactError, stableValue, jsonBytes, sha256, parseJson, validEntryPath, concatenate, readZipParts, createManifest, digestTableIdentity, encodePackage, isZip, decodePackage;
+var MEM_PACKAGE_FORMAT, MEM_PACKAGE_FORMAT_LEGACY, MEM_PACKAGE_VERSION, MEM_PACKAGE_LIMITS, MEM_PACKAGE_WRITE_MARGIN_BYTES, MEM_PACKAGE_WRITE_LIMITS, MANIFEST_PATH, MAP_PATH, DATA_PATH, INTEGRITY_PATH, requiredParts, encoder2, decoder, MemArtifactError, stableValue, jsonBytes, sha256, parseJson, validEntryPath, concatenate, readZipParts, createManifest, digestTableIdentity, encodePackage, isZip, decodePackage;
 var init_mem_package = __esm({
   "core/knowledge/mem-package.ts"() {
     init_browser();
     init_mem_codec();
     MEM_PACKAGE_FORMAT = "dotmem.package";
+    MEM_PACKAGE_FORMAT_LEGACY = "memorio.package";
     MEM_PACKAGE_VERSION = 1;
     MEM_PACKAGE_LIMITS = Object.freeze({
       maximumPackageBytes: 10 * 1024 * 1024,
@@ -4828,10 +4851,10 @@ var init_mem_package = __esm({
         if (!parts[path]) throw new MemArtifactError("invalid", `Missing MEM package part: ${path}`);
       }
       const manifest = parseJson(parts[MANIFEST_PATH], MANIFEST_PATH);
-      if (manifest.format !== MEM_PACKAGE_FORMAT && manifest.format || manifest.version !== MEM_PACKAGE_VERSION) {
+      if (manifest.format !== MEM_PACKAGE_FORMAT && manifest.format !== MEM_PACKAGE_FORMAT_LEGACY || manifest.version !== MEM_PACKAGE_VERSION) {
         throw new MemArtifactError("unsupported", "Unsupported MEM package format or version");
       }
-      if (manifest.memory?.format !== MEM_FORMAT && manifest.memory?.format || manifest.memory.version !== MEM_FORMAT_VERSION || manifest.parts?.map !== MAP_PATH || manifest.parts?.data !== DATA_PATH || manifest.parts?.integrity !== INTEGRITY_PATH) {
+      if (manifest.memory?.format !== MEM_FORMAT && manifest.memory?.format !== MEM_FORMAT_LEGACY || manifest.memory.version !== MEM_FORMAT_VERSION || manifest.parts?.map !== MAP_PATH || manifest.parts?.data !== DATA_PATH || manifest.parts?.integrity !== INTEGRITY_PATH) {
         throw new MemArtifactError("invalid", "Invalid MEM package manifest");
       }
       const integrity = parseJson(parts[INTEGRITY_PATH], INTEGRITY_PATH);
@@ -4874,6 +4897,109 @@ var init_mem_package = __esm({
   }
 });
 
+// core/storage-coordinator/index.ts
+var nodeFs4, withStorageLock, readStorageGeneration, writeStorageGeneration;
+var init_storage_coordinator = __esm({
+  "core/storage-coordinator/index.ts"() {
+    nodeFs4 = /* @__PURE__ */ __name(async () => import('fs/promises'), "nodeFs");
+    withStorageLock = /* @__PURE__ */ __name(async (directoryPath, operationOrOptions, operation, _options = {}) => {
+      const opts = typeof operationOrOptions === "function" ? operation ?? {} : operationOrOptions ?? {};
+      const op = typeof operationOrOptions === "function" ? operationOrOptions : operation;
+      const timeoutMs = opts.timeoutMs ?? 3e4;
+      const staleMs = opts.staleMs ?? 6e4;
+      const lockName = opts.lockName ?? ".storage.lock";
+      const lockPath = `${directoryPath}/${lockName}`;
+      const fs = await nodeFs4();
+      const started = Date.now();
+      await fs.mkdir(directoryPath, { recursive: true });
+      while (true) {
+        try {
+          await fs.mkdir(lockPath);
+          const token2 = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+          await fs.writeFile(`${lockPath}/owner.json`, JSON.stringify({ token: token2, pid: process.pid, createdAt: Date.now() }), { flag: "wx" });
+          break;
+        } catch (error) {
+          const code = error.code;
+          if (code !== "EEXIST" && code !== "ENOENT" && code !== "EPERM" && code !== "ENOTEMPTY") throw error;
+          let stale = false;
+          let processDead = false;
+          try {
+            const raw = await fs.readFile(`${lockPath}/owner.json`, "utf8");
+            const parsed = JSON.parse(raw);
+            const ageStale = typeof parsed.createdAt === "number" && Date.now() - parsed.createdAt > staleMs;
+            if (typeof parsed.pid === "number") {
+              try {
+                process.kill(parsed.pid, 0);
+              } catch {
+                processDead = true;
+              }
+            } else {
+              processDead = true;
+            }
+            if (ageStale || processDead) stale = true;
+          } catch {
+            stale = true;
+          }
+          if (stale) {
+            if (processDead) {
+              try {
+                await fs.rm(lockPath, { recursive: true, force: true });
+                continue;
+              } catch {
+              }
+            }
+            try {
+              await fs.rmdir(lockPath);
+              continue;
+            } catch {
+            }
+          }
+          if (Date.now() - started > timeoutMs) {
+            throw new Error(`Storage lock timeout for ${directoryPath}`);
+          }
+          await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+      }
+      let token = "";
+      try {
+        const raw = await fs.readFile(`${lockPath}/owner.json`, "utf8");
+        token = JSON.parse(raw).token ?? "";
+      } catch {
+        token = "";
+      }
+      try {
+        return await op();
+      } finally {
+        try {
+          const raw = await fs.readFile(`${lockPath}/owner.json`, "utf8");
+          const parsed = JSON.parse(raw);
+          if (parsed.token === token && token) {
+            await fs.rm(lockPath, { recursive: true, force: true });
+          }
+        } catch {
+        }
+      }
+    }, "withStorageLock");
+    readStorageGeneration = /* @__PURE__ */ __name(async (directoryPath) => {
+      const fs = await nodeFs4();
+      try {
+        const raw = await fs.readFile(`${directoryPath}/.storage.generation`, "utf8");
+        const value = Number(raw.trim());
+        return Number.isFinite(value) && value >= 0 ? value : 0;
+      } catch {
+        return 0;
+      }
+    }, "readStorageGeneration");
+    writeStorageGeneration = /* @__PURE__ */ __name(async (directoryPath, value) => {
+      const fs = await nodeFs4();
+      await fs.mkdir(directoryPath, { recursive: true });
+      const temp = `${directoryPath}/.storage.generation.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+      await fs.writeFile(temp, String(value));
+      await fs.rename(temp, `${directoryPath}/.storage.generation`);
+    }, "writeStorageGeneration");
+  }
+});
+
 // core/knowledge/mem-repository.ts
 function resolveDuplicate(existing, existingSource, current, currentSource) {
   const existingRetracts = existing.revision?.kind === "retracts";
@@ -4914,19 +5040,20 @@ async function parseMemFile(value, sourceId) {
     throw new Error(`${message} in ${sourceId}`);
   }
 }
-var DOTMEM_DIRECTORY, DEFAULT_MEM_FILE, directoryLocks, nodeFs4, separator2, normalizePath, isAbsolutePath, resolvePath, joinPath2, parentPath, uniqueSuffix, withDirectoryLock, isMissingDirectory, sourcePriority, memFilePath, MemDirectoryKnowledgeRepository;
+var DOTMEM_DIRECTORY, DEFAULT_MEM_FILE, nodeFs5, repositoryLoadCaches, separator2, normalizePath, isAbsolutePath, resolvePath, joinPath2, parentPath, uniqueSuffix, isMissingDirectory, sourcePriority, memFilePath, MemDirectoryKnowledgeRepository;
 var init_mem_repository = __esm({
   "core/knowledge/mem-repository.ts"() {
     init_mem_codec();
     init_mem_package();
     init_state();
     init_acquisition_limits();
+    init_storage_coordinator();
     DOTMEM_DIRECTORY = ".dotmem";
     DEFAULT_MEM_FILE = "project.mem";
-    directoryLocks = /* @__PURE__ */ new Map();
-    nodeFs4 = /* @__PURE__ */ __name(async () => {
+    nodeFs5 = /* @__PURE__ */ __name(async () => {
       return import('fs/promises');
     }, "nodeFs");
+    repositoryLoadCaches = /* @__PURE__ */ new Map();
     separator2 = /* @__PURE__ */ __name(() => process.platform === "win32" ? "\\" : "/", "separator");
     normalizePath = /* @__PURE__ */ __name((value) => value.replace(/[\\/]+/g, separator2()), "normalizePath");
     isAbsolutePath = /* @__PURE__ */ __name((value) => /^(?:[A-Za-z]:[\\/]|[\\/])/.test(value), "isAbsolutePath");
@@ -4938,25 +5065,8 @@ var init_mem_repository = __esm({
       return index <= 0 ? "." : normalized.slice(0, index);
     }, "parentPath");
     uniqueSuffix = /* @__PURE__ */ __name(() => globalThis.crypto?.randomUUID?.() ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`, "uniqueSuffix");
-    withDirectoryLock = /* @__PURE__ */ __name(async (directoryPath, operation) => {
-      const previous = directoryLocks.get(directoryPath) ?? Promise.resolve();
-      let release = /* @__PURE__ */ __name(() => void 0, "release");
-      const gate = new Promise((resolveGate) => {
-        release = resolveGate;
-      });
-      const queued = previous.then(() => gate);
-      directoryLocks.set(directoryPath, queued);
-      await previous;
-      try {
-        return await operation();
-      } finally {
-        release();
-        if (directoryLocks.get(directoryPath) === queued) directoryLocks.delete(directoryPath);
-      }
-    }, "withDirectoryLock");
     isMissingDirectory = /* @__PURE__ */ __name((error) => error.code === "ENOENT", "isMissingDirectory");
     sourcePriority = /* @__PURE__ */ __name((sourceId, scope) => {
-      if (sourceId.endsWith(".mem") && sourceId !== "project.mem" && sourceId !== "user.mem" && sourceId !== "agent.mem") return 0;
       if (scope === "project" || sourceId === "project.mem") return 4;
       if (scope === "user" || sourceId === "user.mem") return 3;
       if (sourceId === "agent.mem" || sourceId === "agent") return 2;
@@ -4984,7 +5094,7 @@ var init_mem_repository = __esm({
         this.loadWritableOnly = loadWritableOnly;
       }
       async discover() {
-        const { readdir } = await nodeFs4();
+        const { readdir } = await nodeFs5();
         try {
           const entries2 = await readdir(this.directoryPath, { withFileTypes: true });
           return entries2.filter((entry) => entry.isFile() && entry.name.endsWith(".mem") && entry.name !== "@brain.mem").map((entry) => entry.name).sort((a, b) => a.localeCompare(b));
@@ -4999,7 +5109,7 @@ var init_mem_repository = __esm({
        * receive a clear failure instead of discovering corruption on first use.
        */
       async initialize() {
-        const { mkdir } = await nodeFs4();
+        const { mkdir } = await nodeFs5();
         await mkdir(this.directoryPath, { recursive: true });
         await this.load();
       }
@@ -5014,7 +5124,7 @@ var init_mem_repository = __esm({
        * that does not delete is not a delete.
        */
       async clearWritable() {
-        const { rm, readdir } = await nodeFs4();
+        const { rm, readdir } = await nodeFs5();
         const filePath = memFilePath(this.directoryPath, this.writableSourceId);
         await rm(filePath, { force: true });
         await rm(`${filePath}.bak`, { force: true });
@@ -5031,15 +5141,28 @@ var init_mem_repository = __esm({
         }
       }
       async load() {
-        const loaded = this.loadWritableOnly ? await this.loadSources([this.writableSourceId]) : await this.loadSources();
-        return this.combine(loaded);
+        const cacheKey = `${this.directoryPath}:${this.writableSourceId}:${this.loadWritableOnly}`;
+        for (let attempt = 0; attempt < 5; attempt += 1) {
+          const generationBefore = await readStorageGeneration(this.directoryPath);
+          const cached = repositoryLoadCaches.get(cacheKey);
+          if (cached && cached.signature === String(generationBefore)) {
+            return structuredClone(cached.state);
+          }
+          const loaded = this.loadWritableOnly ? await this.loadSources([this.writableSourceId]) : await this.loadSources();
+          const state2 = this.combine(loaded);
+          const generationAfter = await readStorageGeneration(this.directoryPath);
+          if (generationBefore !== generationAfter && attempt < 4) continue;
+          repositoryLoadCaches.set(cacheKey, { signature: String(generationAfter), state: structuredClone(state2) });
+          return state2;
+        }
+        throw new Error("Unable to load stable repository state");
       }
-      async save(state2, expectedVersion) {
+      async save(state2, expectedVersion, locked = false) {
         const validated = validateKnowledgeState(state2);
         if (!Number.isInteger(expectedVersion) || expectedVersion < 0 || validated.version !== expectedVersion + 1) {
           throw new Error("Invalid expected persisted version");
         }
-        await withDirectoryLock(this.directoryPath, async () => {
+        const doWrite = /* @__PURE__ */ __name(async () => {
           const loaded = await this.loadSources();
           const writable = loaded.find((source) => source.id === this.writableSourceId) ?? {
             id: this.writableSourceId,
@@ -5061,10 +5184,16 @@ var init_mem_repository = __esm({
             claims: [...writable.state.claims, ...newClaims]
           };
           await this.writeSource(writable.filePath, nextWritable, writable.preserved, writable.package);
-        });
+          await writeStorageGeneration(this.directoryPath, await readStorageGeneration(this.directoryPath) + 1);
+        }, "doWrite");
+        if (locked) {
+          await doWrite();
+        } else {
+          await withStorageLock(this.directoryPath, doWrite);
+        }
       }
       async loadSources(sourceIds) {
-        const { readFile: readFile5 } = await nodeFs4();
+        const { readFile: readFile5 } = await nodeFs5();
         const ids = sourceIds ?? await this.discover();
         const sources = [];
         for (const sourceId of ids) {
@@ -5154,7 +5283,7 @@ var init_mem_repository = __esm({
        * valid package, so the backup is always a version this library can read.
        */
       async keepLastValidVersion(filePath) {
-        const { readFile: readFile5, copyFile, rename, rm } = await nodeFs4();
+        const { readFile: readFile5, copyFile, rename, rm } = await nodeFs5();
         let current;
         try {
           current = await readFile5(filePath);
@@ -5178,7 +5307,7 @@ var init_mem_repository = __esm({
       }
       /** Best-effort directory sync: the rename is durable once the directory is. */
       async syncDirectory(directoryPath) {
-        const { open } = await nodeFs4();
+        const { open } = await nodeFs5();
         try {
           const handle = await open(directoryPath, "r");
           try {
@@ -5190,7 +5319,7 @@ var init_mem_repository = __esm({
         }
       }
       async writeSource(filePath, state2, preserved, preservedPackage) {
-        const { mkdir, rename, rm, open, readFile: readFile5 } = await nodeFs4();
+        const { mkdir, rename, rm, open, readFile: readFile5 } = await nodeFs5();
         if (!Number.isInteger(state2.version) || state2.version < 0) throw new Error("Invalid writable .mem knowledge version");
         for (const claim of state2.claims) validateClaim(claim);
         await mkdir(parentPath(filePath), { recursive: true });
@@ -5677,7 +5806,7 @@ var init_project_identity = __esm({
 });
 
 // core/knowledge/staging.ts
-var DOTMEM_STAGE_FORMAT, DOTMEM_STAGE_VERSION, StageFileError, generateRequestId, nodeCwd, resolveStagingDirectory, stagePathFor, nodeFs5, normalizeClaimIds, revisionFromOptions, writeStageFile, readStageFile, validateStageFile, commitStageFile, cleanupStageFile;
+var DOTMEM_STAGE_FORMAT, DOTMEM_STAGE_VERSION, StageFileError, generateRequestId, nodeCwd, resolveStagingDirectory, stagePathFor, nodeFs6, normalizeClaimIds, revisionFromOptions, writeStageFile, readStageFile, validateStageFile, commitStageFile, cleanupStageFile;
 var init_staging = __esm({
   "core/knowledge/staging.ts"() {
     init_claim_record();
@@ -5712,7 +5841,7 @@ var init_staging = __esm({
       return `${base}/dotmem`;
     }, "resolveStagingDirectory");
     stagePathFor = /* @__PURE__ */ __name((requestId) => `${resolveStagingDirectory()}/${requestId}.stage`, "stagePathFor");
-    nodeFs5 = /* @__PURE__ */ __name(async () => import('fs/promises'), "nodeFs");
+    nodeFs6 = /* @__PURE__ */ __name(async () => import('fs/promises'), "nodeFs");
     normalizeClaimIds = /* @__PURE__ */ __name((value) => {
       if (!value) return [];
       return Array.isArray(value) ? value : [value];
@@ -5737,7 +5866,7 @@ var init_staging = __esm({
       };
       const requestId = generateRequestId();
       const stagePath = stagePathFor(requestId);
-      const fs = await nodeFs5();
+      const fs = await nodeFs6();
       await fs.mkdir(resolveStagingDirectory(), { recursive: true });
       const stageFile = {
         format: DOTMEM_STAGE_FORMAT,
@@ -5757,7 +5886,7 @@ var init_staging = __esm({
     }, "writeStageFile");
     readStageFile = /* @__PURE__ */ __name(async (requestId) => {
       const stagePath = stagePathFor(requestId);
-      const fs = await nodeFs5();
+      const fs = await nodeFs6();
       try {
         const content = await fs.readFile(stagePath, "utf8");
         return JSON.parse(content);
@@ -5868,7 +5997,7 @@ var init_staging = __esm({
     }, "commitStageFile");
     cleanupStageFile = /* @__PURE__ */ __name(async (requestId) => {
       const stagePath = stagePathFor(requestId);
-      const fs = await nodeFs5();
+      const fs = await nodeFs6();
       try {
         await fs.unlink(stagePath);
       } catch (error) {
@@ -6690,6 +6819,7 @@ function _inferConfidence(claim) {
 var LOGIC_MEM_FILE, nodeCwd2, cachedRuntime, LogicEngine, logic, logic_default;
 var init_logic = __esm({
   "core/logic/index.ts"() {
+    init_suppress_idb_warning();
     init_knowledge();
     init_mem_repository();
     init_acquisition_boundary();
@@ -7053,11 +7183,18 @@ var init_note_types = __esm({
   }
 });
 
+// core/mcp/index.ts
+init_suppress_idb_warning();
+
 // package.json
 var package_default = {
-  version: "0.0.8"};
+  version: "0.1.0"};
+
+// core/memory/index.ts
+init_suppress_idb_warning();
 
 // core/memory/journal.ts
+init_suppress_idb_warning();
 init_env();
 var g = globalThis;
 function namespace() {
@@ -7264,6 +7401,7 @@ var journal_default = journal;
 init_brain();
 
 // core/memory/knowledge-runtime.ts
+init_suppress_idb_warning();
 init_knowledge();
 init_project_identity();
 init_user_paths();
@@ -7661,6 +7799,7 @@ var policy = {
 };
 
 // core/memory/entries.ts
+init_suppress_idb_warning();
 init_env();
 var MEMORY_INDEX_KEY = "__dotmem_memory_index__";
 var SUPERSEDED_PREFIX = "__dotmem_superseded__";
@@ -8205,15 +8344,18 @@ var context = {
 };
 
 // core/memory/acquire.ts
+init_suppress_idb_warning();
 init_env();
 init_project_identity();
 init_project_anchor();
 init_acquisition_boundary();
 init_claim_record();
+init_state();
 init_router();
 init_store_queue();
 init_staging();
 init_user_paths();
+init_storage_coordinator();
 init_mem_repository();
 function normalizeClaimIds3(value) {
   if (!value) return [];
@@ -8291,23 +8433,27 @@ var acquire = {
       );
     }
     const revision = revisionFromAcquire2(opts);
+    const repository = target.repository;
     await withStoreQueue(acquisitionStoreKey(kind, scope, sourceProject), async () => {
-      const state2 = await target.runtime.select([]);
-      await target.runtime.update({
-        basedOnVersion: state2.context.knowledgeVersion,
-        claims: [buildClaimRecord({
-          id: opts.id,
-          knowledge: boundary.knowledge,
-          applicability: opts.applicability,
-          evidence: opts.evidence,
-          epistemicType: opts.epistemicType,
-          provenance: opts.provenance,
-          acquiredAt: opts.acquiredAt,
-          revision,
-          scope,
-          sourceProject,
-          kind
-        })]
+      await withStorageLock(repository.directoryPath, async () => {
+        const state2 = await repository.load();
+        const next = updateKnowledge(state2, {
+          basedOnVersion: state2.version,
+          claims: [buildClaimRecord({
+            id: opts.id,
+            knowledge: boundary.knowledge,
+            applicability: opts.applicability,
+            evidence: opts.evidence,
+            epistemicType: opts.epistemicType,
+            provenance: opts.provenance,
+            acquiredAt: opts.acquiredAt,
+            revision,
+            scope,
+            sourceProject,
+            kind
+          })]
+        });
+        await repository.save(next, state2.version, true);
       });
     });
     const verification = await target.repository.load();