@mercury-fw/core 0.25.0 → 0.25.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @mercury-fw/core
 
+## 0.25.1
+
+### Patch Changes
+
+- 5613e5e: - Mercury starts even when Qdrant isn't answering yet: the memory collections are set up in the background and retried until Qdrant is reachable, instead of crashing the process at startup.
+  - A new session's context primer goes on without the last-session recap when Qdrant doesn't answer, instead of failing the turn.
+  - The scaffolded app's `docker-compose.yml` restarts the app service unless it was stopped.
+  - @mercury-fw/plugin-types@0.25.1
+  - @mercury-fw/channel-types@0.25.1
+  - @mercury-fw/cli-engine@0.25.1
+  - @mercury-fw/confirm-engine@0.25.1
+
 ## 0.25.0
 
 ### Minor Changes

package/dist/src/memory/collection-setup.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Layer 3's startup setup (creating the Qdrant collections and their indexes),
+ * run in the background so an unreachable Qdrant never stops Mercury from
+ * starting: the episodic store is enrichment and fails soft (principle 3).
+ */
+/**
+ * Runs `setup` now and, while it fails, again every `retryMs`, on a timer that
+ * doesn't keep the process alive. Logs once when Qdrant goes missing and once
+ * when it's back, never per retry. `done` resolves after the first success.
+ */
+export declare function setUpWhenReachable(setup: () => Promise<void>, { log, retryMs }: {
+    log: (msg: string) => void;
+    retryMs?: number;
+}): {
+    done: Promise<void>;
+};

package/dist/src/session/context-primer.d.ts

@@ -7,6 +7,8 @@ export type ContextPrimerDeps = {
     listWikiFilesInRootsFn: typeof listWikiFilesInRoots;
     readWikiFileInRootsFn: typeof readWikiFileInRoots;
     readIndexFileFn: typeof readIndexFile;
+    /** Where a skipped section says why (the recap, when Qdrant doesn't answer). */
+    log: (msg: string) => void;
 };
 /**
  * Text of the primer for `userId`, built from injected deps only — never

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/core",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -31,10 +31,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@mercury-fw/channel-types": "0.25.0",
-    "@mercury-fw/cli-engine": "0.25.0",
-    "@mercury-fw/confirm-engine": "0.25.0",
-    "@mercury-fw/plugin-types": "0.25.0",
+    "@mercury-fw/channel-types": "0.25.1",
+    "@mercury-fw/cli-engine": "0.25.1",
+    "@mercury-fw/confirm-engine": "0.25.1",
+    "@mercury-fw/plugin-types": "0.25.1",
     "@qdrant/js-client-rest": "^1.19.0",
     "ai": "^7.0.77",
     "ai-sdk-ollama": "^4.2.0",

package/src/compose.ts

@@ -56,6 +56,7 @@ import { ensureVerbatimCollection, listVerbatimBySession, listVerbatimSessions }
 import { createVerbatimArchiveProvider } from "./memory/memory-provider.ts";
 import { ensureSemanticFactsCollection, storeSemanticFact, searchSemanticFactsByTopic } from "./memory/semantic-facts-store.ts";
 import { ensureToolCorrectionsCollection, storeToolCorrection, searchToolCorrectionsByTopic } from "./memory/tool-corrections-store.ts";
+import { setUpWhenReachable } from "./memory/collection-setup.ts";
 import { consolidateSemanticFact, consolidateToolCorrection, type ToolCorrectionConsolidationDeps } from "./cron/semantic-consolidation.ts";
 import { createToolCorrectionExtractor } from "./session/tool-correction-extractor.ts";
 import { createEmbedder } from "./memory/embedder.ts";
@@ -227,14 +228,12 @@ export async function composeMercury(config: MercuryConfig): Promise<ComposedApp
   const qdrant = new QdrantClient({ url: process.env.QDRANT_URL ?? "http://qdrant:6333" });
   const episodicCollection = process.env.QDRANT_EPISODIC_COLLECTION ?? "episodic_memory";
   const episodicVectorSize = Number(process.env.QDRANT_EPISODIC_VECTOR_SIZE ?? "768");
-  await ensureEpisodicCollection(qdrant, episodicCollection, episodicVectorSize);
 
   // Verbatim conversation archive (#4): a distinct collection holding the raw
   // user<->model exchange, lossless and durable — separate from the lossy
   // Layer-1 window and the derived episodic summaries above.
   const verbatimCollection = process.env.QDRANT_VERBATIM_COLLECTION ?? "verbatim_archive";
   const verbatimVectorSize = Number(process.env.QDRANT_VERBATIM_VECTOR_SIZE ?? "768");
-  await ensureVerbatimCollection(qdrant, verbatimCollection, verbatimVectorSize);
   const verbatimProvider = createVerbatimArchiveProvider({ client: qdrant, collectionName: verbatimCollection, embed });
 
   // Semantic consolidation (D-22/D-34): a separate Qdrant collection from
@@ -242,7 +241,6 @@ export async function composeMercury(config: MercuryConfig): Promise<ComposedApp
   // vector embedded on the topic alone (see semantic-facts-store.ts for why).
   const semanticFactsCollection = process.env.QDRANT_SEMANTIC_FACTS_COLLECTION ?? "semantic_facts";
   const semanticFactsVectorSize = Number(process.env.QDRANT_SEMANTIC_FACTS_VECTOR_SIZE ?? "768");
-  await ensureSemanticFactsCollection(qdrant, semanticFactsCollection, semanticFactsVectorSize);
   const extractFacts = createSemanticFactExtractor(model);
 
   // Idempotent self-heal: the vault lives on a named Docker volume, empty on
@@ -322,7 +320,17 @@ export async function composeMercury(config: MercuryConfig): Promise<ComposedApp
   // the tool-call trace only exists in memory for the duration of its turn.
   const toolCorrectionsCollection = process.env.QDRANT_TOOL_CORRECTIONS_COLLECTION ?? "tool_corrections";
   const toolCorrectionsVectorSize = Number(process.env.QDRANT_TOOL_CORRECTIONS_VECTOR_SIZE ?? "768");
-  await ensureToolCorrectionsCollection(qdrant, toolCorrectionsCollection, toolCorrectionsVectorSize);
+  // Every Layer-3 collection, set up in the background: Mercury starts even
+  // while Qdrant isn't answering yet, and memory switches on once it does.
+  setUpWhenReachable(
+    async () => {
+      await ensureEpisodicCollection(qdrant, episodicCollection, episodicVectorSize);
+      await ensureVerbatimCollection(qdrant, verbatimCollection, verbatimVectorSize);
+      await ensureSemanticFactsCollection(qdrant, semanticFactsCollection, semanticFactsVectorSize);
+      await ensureToolCorrectionsCollection(qdrant, toolCorrectionsCollection, toolCorrectionsVectorSize);
+    },
+    { log: (msg) => console.error(`[memory] ${msg}`) },
+  );
   const extractToolCorrections = createToolCorrectionExtractor(model, undefined, {
     log: (msg) => console.error(`[cron] ${msg}`),
   });
@@ -464,6 +472,7 @@ export async function composeMercury(config: MercuryConfig): Promise<ComposedApp
           listWikiFilesInRootsFn: listWikiFilesInRoots,
           readWikiFileInRootsFn: readWikiFileInRoots,
           readIndexFileFn: readIndexFile,
+          log: (msg) => console.error(`[memory] ${msg}`),
         });
         return getOrCreateHistory(key, trackForCapture, primer);
       }

package/src/memory/collection-setup.ts

@@ -0,0 +1,34 @@
+/**
+ * Layer 3's startup setup (creating the Qdrant collections and their indexes),
+ * run in the background so an unreachable Qdrant never stops Mercury from
+ * starting: the episodic store is enrichment and fails soft (principle 3).
+ */
+
+/**
+ * Runs `setup` now and, while it fails, again every `retryMs`, on a timer that
+ * doesn't keep the process alive. Logs once when Qdrant goes missing and once
+ * when it's back, never per retry. `done` resolves after the first success.
+ */
+export function setUpWhenReachable(
+  setup: () => Promise<void>,
+  { log, retryMs = 5000 }: { log: (msg: string) => void; retryMs?: number },
+): { done: Promise<void> } {
+  let failing = false;
+  const done = new Promise<void>((resolve) => {
+    const attempt = async () => {
+      try {
+        await setup();
+        if (failing) log("Qdrant reachable, memory collections ready");
+        resolve();
+      } catch (err) {
+        if (!failing) {
+          log(`Qdrant unreachable, Layer-3 memory is off until it answers (retrying every ${retryMs / 1000}s): ${String(err)}`);
+        }
+        failing = true;
+        setTimeout(attempt, retryMs).unref();
+      }
+    };
+    void attempt();
+  });
+  return { done };
+}

package/src/session/context-primer.ts

@@ -21,6 +21,8 @@ export type ContextPrimerDeps = {
   listWikiFilesInRootsFn: typeof listWikiFilesInRoots;
   readWikiFileInRootsFn: typeof readWikiFileInRoots;
   readIndexFileFn: typeof readIndexFile;
+  /** Where a skipped section says why (the recap, when Qdrant doesn't answer). */
+  log: (msg: string) => void;
 };
 
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n/;
@@ -78,7 +80,12 @@ async function pendingConfirmationTokens(userId: string, deps: ContextPrimerDeps
  * `index.ts` supplies the real Qdrant-backed episodic query and wiki reads.
  */
 export async function buildContextPrimer(userId: string, deps: ContextPrimerDeps): Promise<string> {
-  const entries = await deps.getLastSessionEntries(userId);
+  // Episodic memory is enrichment: without Qdrant the primer goes on without
+  // the recap instead of failing the turn.
+  const entries = await deps.getLastSessionEntries(userId).catch((err: unknown) => {
+    deps.log(`last session for ${userId} unavailable, primer built without it: ${String(err)}`);
+    return [];
+  });
   // Checked regardless of `entries` — a pending confirmation isn't tied to
   // "was there a prior episodic session", it's simply still open right now.
   const pendingTokens = await pendingConfirmationTokens(userId, deps);