@pellux/goodvibes-agent 1.5.9 → 1.6.1

package/src/runtime/bootstrap.ts

@@ -40,6 +40,7 @@ import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import { startMcpConfigAutoReload } from '../mcp/runtime-reload.ts';
 import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
 import { foldLegacySpineStore } from '@pellux/goodvibes-sdk/platform/runtime/session-spine';
+import { reconcileMemorySpineAdoption } from './memory-spine-adoption.ts';
 import { AgentPromptContextReceiptStore, composeRuntimePromptWithReceipt } from '../agent/prompt-context-receipts.ts';
 import { registerAgentAuditTool } from '../tools/agent-audit-tool.ts';
 import { registerAgentAutonomyTool } from '../tools/agent-autonomy-tool.ts';
@@ -214,6 +215,16 @@ export async function bootstrapRuntime(
     runtimeBus.on<Extract<TurnEvent, { type: 'TURN_SUBMITTED' }>>('TURN_SUBMITTED', (event) => {
       activePromptTurnId = event.payload.turnId;
       activePromptTurnText = event.payload.prompt;
+      // Per-turn recall refresh (SDK 1.2.0 sync-recall seam): the ASYNC
+      // pre-turn hook. getSystemPrompt below is SYNCHRONOUS and cannot await
+      // this, so it is fired here (not awaited) and read back via the cached
+      // recallSnapshot() a moment later when the orchestrator actually builds
+      // the prompt. A miss (this turn's prompt reads last turn's snapshot, or
+      // the still-empty boot snapshot on a very first turn) is surfaced
+      // honestly by the snapshot's own staleness note, never silently hidden.
+      services.memorySpineClient.refreshRecallSnapshot(undefined, { recall: false }).catch((error: unknown) => {
+        logger.debug('Per-turn memory recall snapshot refresh failed', { error: summarizeError(error) });
+      });
     }),
     runtimeBus.on<Extract<TurnEvent, { type: 'TURN_COMPLETED' }>>('TURN_COMPLETED', (event) => {
       promptContextReceipts.recordTurnOutcome({
@@ -291,6 +302,7 @@ export async function bootstrapRuntime(
         shellPaths: services.shellPaths,
         memoryRegistry: services.memoryRegistry,
         turnText: activePromptTurnText,
+        memoryRecallSnapshot: services.memorySpineClient.recallSnapshot(),
       });
       promptContextReceipts.record(composed.receipt);
       return composed.prompt;
@@ -523,6 +535,55 @@ export async function bootstrapRuntime(
       logger.debug('Deferred session-spine startup failed', { error: summarizeError(error) });
     },
   });
+  // Memory spine (SDK 1.1.0): the daemon-owned canonical memory store is
+  // single-writer, so the agent must make an explicit adopted/not-adopted decision
+  // rather than trying the wire per call. Reuses the SAME reachability signal as the
+  // session-spine fold above (services.sessionSpineClient.probeReachability(), one
+  // daemon, one connected-host token) instead of inventing a second probe. On a
+  // reachable daemon, activate the spine for CLIENT mode — every wire-covered memory
+  // op now routes over HTTP and the local store is never written again. Embedded/
+  // offline is unaffected: the agent must keep working with no daemon running, and a
+  // failed/absent probe simply leaves the client in its constructed LOCAL mode.
+  //
+  // A daemon can also appear or disappear AFTER boot, so this keeps checking for the
+  // whole process lifetime on the same cadence as the runtime heartbeat: adopt late
+  // if one shows up, and hand back to local (deactivate) the moment a PREVIOUSLY
+  // adopted daemon stops answering — never guess and keep routing to a dead wire.
+  let memorySpineHeartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  const reconcileMemorySpine = (): Promise<void> => reconcileMemorySpineAdoption({
+    memorySpineClient: services.memorySpineClient,
+    transport: services.memorySpineTransport,
+    probeReachability: () => services.sessionSpineClient.probeReachability(),
+  });
+  deferredStartup.schedule({
+    label: 'memory-spine',
+    run: async () => {
+      await reconcileMemorySpine();
+      // Prime the recall snapshot (SDK 1.2.0 sync-recall seam) so the FIRST
+      // system prompt built after boot already has a real snapshot to read
+      // instead of the honest-but-empty "not yet captured" one — see
+      // recallSnapshot's doc comment on prompt-context-receipts.ts's
+      // memoryRecallSnapshot field. { recall: false } captures an unfiltered
+      // browse set: the receipt's own eligibility/suppression logic (not the
+      // snapshot) decides what is prompt-active, so this must mirror the old
+      // memoryRegistry.getAll() read exactly, not the recall-floor-filtered set.
+      await services.memorySpineClient.refreshRecallSnapshot(undefined, { recall: false }).catch((error: unknown) => {
+        logger.debug('Initial memory recall snapshot refresh failed', { error: summarizeError(error) });
+      });
+      if (configManager.get('watchers.enabled')) {
+        const intervalMs = Number(configManager.get('watchers.heartbeatIntervalMs') ?? 30_000);
+        memorySpineHeartbeatTimer = setInterval(() => {
+          reconcileMemorySpine().catch((error: unknown) => {
+            logger.debug('Memory-spine reachability recheck failed', { error: summarizeError(error) });
+          });
+        }, intervalMs);
+        memorySpineHeartbeatTimer.unref?.();
+      }
+    },
+    onError: (error) => {
+      logger.debug('Deferred memory-spine startup failed', { error: summarizeError(error) });
+    },
+  });
 
   const toolCount = toolRegistry.list().length;
   conversation.splashOptions = {
@@ -660,6 +721,13 @@ export async function bootstrapRuntime(
       // the heartbeat timer. Tolerates a racing daemon stop; never blocks teardown.
       services.sessionSpineClient.close(runtime.sessionId);
       services.sessionSpineClient.dispose();
+      // Stop the memory-spine reachability recheck timer (see the 'memory-spine'
+      // deferred startup task above). No wire close call needed — unlike sessions,
+      // memory ops are request/response, not a registered/heartbeat-tracked record.
+      if (memorySpineHeartbeatTimer !== null) {
+        clearInterval(memorySpineHeartbeatTimer);
+        memorySpineHeartbeatTimer = null;
+      }
       // Clear bootstrap-owned subscriptions
       bootstrapUnsubs.forEach(fn => fn());
       bootstrapUnsubs.length = 0;

package/src/runtime/memory-spine-adoption.ts

@@ -0,0 +1,50 @@
+/**
+ * memory-spine-adoption.ts
+ *
+ * The single policy for deciding whether the agent's memory spine should be
+ * routing over the wire (CLIENT mode, an adopted daemon owns the store) or
+ * reading/writing its own local store (LOCAL mode) — given the SAME
+ * daemon-reachability signal already used by the session spine
+ * (services.sessionSpineClient.probeReachability()), per Mike's direction to reuse
+ * the agent's existing daemon-adoption signal rather than invent a second one.
+ *
+ * Extracted out of bootstrap.ts so this decision is unit-testable in isolation and
+ * so the boot-time check and the periodic recheck (a daemon can appear or
+ * disappear after boot) run through exactly ONE code path, not two copies that
+ * could drift apart.
+ */
+import type { MemorySpineClient, MemoryTransport } from '@pellux/goodvibes-sdk/platform/runtime/memory-spine';
+
+export interface MemorySpineAdoptionOptions {
+  /** Only the three methods this policy needs — narrow on purpose so a test double is trivial to write. */
+  readonly memorySpineClient: Pick<MemorySpineClient, 'active' | 'activate' | 'deactivate'>;
+  readonly transport: MemoryTransport;
+  /** The existing daemon-adoption signal — reuse services.sessionSpineClient.probeReachability() in production. */
+  readonly probeReachability: () => Promise<'unknown' | 'online' | 'offline'>;
+  readonly deactivateReason?: string;
+}
+
+/**
+ * Runs one reachability check and adopts/releases the daemon accordingly:
+ *  - reachable AND not yet active -> activate(transport) (adopt the daemon; every
+ *    wire-covered memory op now routes over HTTP and the local store is never
+ *    written again, for as long as this holds).
+ *  - NOT reachable AND currently active -> deactivate(reason) (hand back to owned
+ *    local access — a sustained daemon loss, never guessed from a single call
+ *    failure elsewhere; see memory-spine/client.ts's honest-failure contract).
+ *  - otherwise: no-op, already in the correct mode.
+ *
+ * A probe rejection propagates to the caller (it does not swallow errors) — the
+ * caller decides how to log a failed reachability check (see bootstrap.ts's
+ * onError handling on the deferred startup task and the interval tick).
+ */
+export async function reconcileMemorySpineAdoption(options: MemorySpineAdoptionOptions): Promise<void> {
+  const reachable = (await options.probeReachability()) === 'online';
+  if (reachable && !options.memorySpineClient.active) {
+    options.memorySpineClient.activate(options.transport);
+    return;
+  }
+  if (!reachable && options.memorySpineClient.active) {
+    options.memorySpineClient.deactivate(options.deactivateReason ?? 'daemon unreachable on periodic reachability check');
+  }
+}

package/src/runtime/memory-spine-rest-transport.ts

@@ -0,0 +1,327 @@
+/**
+ * memory-spine-rest-transport.ts
+ *
+ * The agent's REST transport adapter for the SDK's memory spine
+ * (`@pellux/goodvibes-sdk/platform/runtime/memory-spine`). The daemon's canonical
+ * memory store is single-writer: once this agent process has adopted a daemon, every
+ * memory operation must go over the wire and the agent must never open its own copy
+ * of the store file. This file is the thin REST mirror that realizes that wire —
+ * hand-rolled rather than a typed daemon client, for the same version-tolerance
+ * reason as session-spine-rest-transport.ts (the agent may run against an older
+ * pinned SDK/daemon pair that predates one of these routes).
+ *
+ * HONEST-FAILURE CONTRACT. Unlike the session mirror (fire-and-forget, degrades to
+ * an offline queue), a memory read/write returns data the caller actually uses. So
+ * every method here either resolves with the real record/result or REJECTS the
+ * promise — it never invents a placeholder success and never silently falls back to
+ * a local copy. That fallback decision belongs to the caller (MemorySpineClient),
+ * which is deliberately built so its wire branch never touches the local store.
+ *
+ * Reuses the connection resolver and reachability probe already built for the
+ * session spine (session-spine-rest-transport.ts) — same daemon, same connected-host
+ * token, one resolver for both spines.
+ */
+
+import type {
+  MemoryAddOptions,
+  MemoryBundle,
+  MemoryLink,
+  MemoryRecord,
+  MemorySearchFilter,
+  MemorySemanticSearchResult,
+} from '@pellux/goodvibes-sdk/platform/state';
+import type { HonestMemorySearchOptions, HonestMemorySearchResult } from '@pellux/goodvibes-sdk/platform/state';
+import { foldMemoryWireExtendedError } from '@pellux/goodvibes-sdk/platform/runtime/memory-spine';
+import type { MemoryTransport, MemoryUpdatePatch } from '@pellux/goodvibes-sdk/platform/runtime/memory-spine';
+import type { SessionRegistrationConnection } from '../agent/session-registration.ts';
+
+// MemoryReviewPatch is not part of the public `platform/state` barrel export (only
+// the SDK's internal memory-store module has it), so its shape is derived from the
+// MemoryTransport method signature itself rather than importing an unexported type.
+type MemoryReviewPatch = Parameters<MemoryTransport['updateReview']>[1];
+
+// MemoryImportResult is likewise internal-only; derived from importBundle's return
+// type rather than importing an unexported type from the store module. importBundle
+// is an EXTENDED (optional-on-the-type) verb, so NonNullable strips the `| undefined`
+// before ReturnType can apply.
+type MemoryImportResult = Awaited<ReturnType<NonNullable<MemoryTransport['importBundle']>>>;
+
+const DEFAULT_MEMORY_WIRE_TIMEOUT_MS = 2_000;
+
+export interface MemorySpineRestTransportOptions {
+  readonly resolveConnection: () => SessionRegistrationConnection;
+  readonly timeoutMs?: number;
+}
+
+type JsonRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is JsonRecord {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+async function readJsonBody(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!text.trim()) return {};
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+function errorDetail(body: unknown): string {
+  return isRecord(body) && typeof body.error === 'string' ? body.error : '';
+}
+
+/** A thrown wire error that carries the HTTP status and the daemon's structured body code. */
+type WireHttpError = Error & { status?: number; code?: string };
+
+/**
+ * The wire `code` the daemon sets on a 404 whose body means the addressed RECORD
+ * does not exist (the route ran; the store had no such id) is now discriminated by
+ * the SDK's own `foldMemoryWireExtendedError` (platform/runtime/memory-spine), which
+ * classifies a caught wire error from its `.status`/`.code` (stamped onto the error
+ * by {@link wireFetch} below) exactly the way this file used to inline by hand. That
+ * hand-rolled copy is retired in favor of the shared helper — see
+ * wire-verb-availability.ts in the SDK for the record-missing vs. method-unavailable
+ * vs. other classification this delegates to.
+ *
+ * PIN NOTE: `foldMemoryWireExtendedError` ships on the SDK's main branch but is not
+ * yet in a published npm release (the pinned devDependency is 1.2.0, which predates
+ * this export). This file was adopted and proven against the unreleased SDK via the
+ * local sdk-dev overlay; `bun run typecheck` will not pass against the CURRENTLY
+ * PINNED 1.2.0 until the SDK publishes a release containing this export and the
+ * pin in package.json is bumped to it. That bump is a separate, later step.
+ */
+
+/** Fold for a NULLABLE record-scoped verb: record-miss → null; version-skew → honest reject; else rethrow. */
+function foldNullableMemoryWire404(verb: string, error: unknown): null {
+  foldMemoryWireExtendedError(verb, error);
+  // foldMemoryWireExtendedError throws for 'method-unavailable' and 'other'; it only
+  // falls through here for a genuine record-miss, which this nullable verb folds to null.
+  return null;
+}
+
+/** Fold for a NON-NULLABLE verb: version-skew → honest reject; else rethrow (incl. a record-missing 404). */
+function rethrowMemoryWire404(verb: string, error: unknown): never {
+  foldMemoryWireExtendedError(verb, error);
+  // Falls through only for a genuine record-miss; a non-nullable verb has no null to
+  // return, so it rethrows the original error rather than inventing a placeholder.
+  throw error;
+}
+
+/**
+ * The one fetch wrapper every memory-wire call goes through. Throws (never
+ * returns an ok:false envelope) on a missing token, a non-2xx response, or a
+ * network/timeout failure — the honest-failure contract above.
+ */
+async function wireFetch(
+  connection: SessionRegistrationConnection,
+  path: string,
+  init: { readonly method: 'GET' | 'POST' | 'DELETE'; readonly body?: JsonRecord },
+  timeoutMs: number,
+): Promise<unknown> {
+  if (!connection.token) {
+    throw new Error(connection.tokenPath
+      ? `memory spine: no connected-host operator token found at ${connection.tokenPath}`
+      : 'memory spine: no connected-host operator token found');
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(`${connection.baseUrl}${path}`, {
+      method: init.method,
+      headers: {
+        authorization: `Bearer ${connection.token}`,
+        ...(init.body ? { 'content-type': 'application/json' } : {}),
+      },
+      ...(init.body ? { body: JSON.stringify(init.body) } : {}),
+      signal: controller.signal,
+    });
+    const body = await readJsonBody(response);
+    if (!response.ok) {
+      const detail = errorDetail(body);
+      // Carry the status AND the structured body code onto the thrown error so the
+      // memory-wire 404 discriminator can tell a record-missing 404 (which folds to
+      // null) apart from a route-not-found 404 from an older daemon (an honest
+      // "verb unavailable" reject) — never on the bare status alone.
+      const error = new Error(`memory spine: HTTP ${response.status} on ${path}${detail ? `: ${detail}` : ''}`) as WireHttpError;
+      error.status = response.status;
+      const code = isRecord(body) && typeof body.code === 'string' ? body.code : undefined;
+      if (code !== undefined) error.code = code;
+      throw error;
+    }
+    return body;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function requireRecord(body: unknown, path: string): MemoryRecord {
+  if (isRecord(body) && isRecord(body.record)) return body.record as unknown as MemoryRecord;
+  throw new Error(`memory spine: malformed response from ${path} (missing record)`);
+}
+
+/**
+ * Builds the wire `MemoryTransport` the agent injects into `MemorySpineClient` once
+ * it has confirmed a daemon is adopted. Mirrors the daemon-owned `memory.records.*`
+ * routes exactly (see method-catalog-runtime.ts in the SDK):
+ *
+ * CORE (1.1.0): POST /api/memory/records, POST /api/memory/records/search,
+ * GET/DELETE /api/memory/records/{id}, POST /api/memory/records/{id}/review.
+ *
+ * EXTENDED (1.2.0 full-detach catalog): POST /api/memory/records/list,
+ * POST /api/memory/records/search-semantic, POST /api/memory/records/{id}/update,
+ * GET/POST /api/memory/records/{id}/links, POST /api/memory/records/export,
+ * POST /api/memory/records/import. Deliberately NOT implemented here —
+ * reviewQueue and vectorStats/doctor — see the CLI ruling in
+ * memory-command-wire.ts for why those stay local-direct rather than wired.
+ */
+export function createMemorySpineRestTransport(options: MemorySpineRestTransportOptions): MemoryTransport {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_MEMORY_WIRE_TIMEOUT_MS;
+
+  return {
+    async add(opts: MemoryAddOptions): Promise<MemoryRecord> {
+      const connection = options.resolveConnection();
+      const body = await wireFetch(connection, '/api/memory/records', { method: 'POST', body: opts as unknown as JsonRecord }, timeoutMs);
+      return requireRecord(body, '/api/memory/records');
+    },
+
+    async honestSearch(filter: MemorySearchFilter, searchOptions?: HonestMemorySearchOptions): Promise<HonestMemorySearchResult> {
+      const connection = options.resolveConnection();
+      const requestBody: JsonRecord = { ...filter, ...(searchOptions?.recall ? { recall: true } : {}) };
+      const body = await wireFetch(connection, '/api/memory/records/search', { method: 'POST', body: requestBody }, timeoutMs);
+      if (!isRecord(body) || !Array.isArray(body.records)) {
+        throw new Error('memory spine: malformed response from /api/memory/records/search (missing records)');
+      }
+      return body as unknown as HonestMemorySearchResult;
+    },
+
+    async get(id: string): Promise<MemoryRecord | null> {
+      const connection = options.resolveConnection();
+      try {
+        const body = await wireFetch(connection, `/api/memory/records/${encodeURIComponent(id)}`, { method: 'GET' }, timeoutMs);
+        return requireRecord(body, '/api/memory/records/{id}');
+      } catch (error) {
+        // A record-missing 404 (MEMORY_RECORD_NOT_FOUND) is an honest "not found" and
+        // folds to null exactly like the local store's `get()`. A route-not-found 404
+        // (older daemon) rejects honestly; every other failure still rejects.
+        return foldNullableMemoryWire404('get', error);
+      }
+    },
+
+    async updateReview(id: string, patch: MemoryReviewPatch): Promise<MemoryRecord | null> {
+      const connection = options.resolveConnection();
+      try {
+        const body = await wireFetch(connection, `/api/memory/records/${encodeURIComponent(id)}/review`, { method: 'POST', body: patch as unknown as JsonRecord }, timeoutMs);
+        return requireRecord(body, '/api/memory/records/{id}/review');
+      } catch (error) {
+        return foldNullableMemoryWire404('updateReview', error);
+      }
+    },
+
+    async delete(id: string): Promise<boolean> {
+      const connection = options.resolveConnection();
+      const body = await wireFetch(connection, `/api/memory/records/${encodeURIComponent(id)}`, { method: 'DELETE' }, timeoutMs);
+      // The route always answers 200 with an honest { id, deleted } boolean (never a
+      // 200 that pretends a phantom row was removed) — see integration-routes.ts.
+      return isRecord(body) && body.deleted === true;
+    },
+
+    // ── Extended verbs (1.2.0 full-detach catalog) ──────────────────────────
+
+    async list(filter?: MemorySearchFilter): Promise<readonly MemoryRecord[]> {
+      const connection = options.resolveConnection();
+      try {
+        const body = await wireFetch(connection, '/api/memory/records/list', { method: 'POST', body: (filter ?? {}) as unknown as JsonRecord }, timeoutMs);
+        if (!isRecord(body) || !Array.isArray(body.records)) {
+          throw new Error('memory spine: malformed response from /api/memory/records/list (missing records)');
+        }
+        return body.records as unknown as readonly MemoryRecord[];
+      } catch (error) {
+        return rethrowMemoryWire404('list', error);
+      }
+    },
+
+    async searchSemantic(filter?: MemorySearchFilter): Promise<readonly MemorySemanticSearchResult[]> {
+      const connection = options.resolveConnection();
+      try {
+        const body = await wireFetch(connection, '/api/memory/records/search-semantic', { method: 'POST', body: (filter ?? {}) as unknown as JsonRecord }, timeoutMs);
+        if (!isRecord(body) || !Array.isArray(body.results)) {
+          throw new Error('memory spine: malformed response from /api/memory/records/search-semantic (missing results)');
+        }
+        // distance is nullable on the wire (Infinity, a no-vector-match fallback,
+        // serializes to null) — an honest signal the row was ranked lexically, not
+        // by vector; forwarded through verbatim, not coerced.
+        return body.results as unknown as readonly MemorySemanticSearchResult[];
+      } catch (error) {
+        return rethrowMemoryWire404('searchSemantic', error);
+      }
+    },
+
+    async update(id: string, patch: MemoryUpdatePatch): Promise<MemoryRecord | null> {
+      const connection = options.resolveConnection();
+      try {
+        const body = await wireFetch(connection, `/api/memory/records/${encodeURIComponent(id)}/update`, { method: 'POST', body: patch as unknown as JsonRecord }, timeoutMs);
+        return requireRecord(body, '/api/memory/records/{id}/update');
+      } catch (error) {
+        return foldNullableMemoryWire404('update', error);
+      }
+    },
+
+    async link(fromId: string, toId: string, relation: string): Promise<MemoryLink | null> {
+      const connection = options.resolveConnection();
+      try {
+        const body = await wireFetch(connection, `/api/memory/records/${encodeURIComponent(fromId)}/links`, { method: 'POST', body: { toId, relation } }, timeoutMs);
+        if (!isRecord(body) || !isRecord(body.link)) {
+          throw new Error('memory spine: malformed response from /api/memory/records/{id}/links (missing link)');
+        }
+        return body.link as unknown as MemoryLink;
+      } catch (error) {
+        // A record-missing 404 means an endpoint id does not exist — an honest "link
+        // not made", folded to null like the local registry's link(). A route-not-found
+        // 404 (older daemon) rejects honestly.
+        return foldNullableMemoryWire404('link', error);
+      }
+    },
+
+    async linksFor(id: string): Promise<readonly MemoryLink[]> {
+      const connection = options.resolveConnection();
+      try {
+        const body = await wireFetch(connection, `/api/memory/records/${encodeURIComponent(id)}/links`, { method: 'GET' }, timeoutMs);
+        if (!isRecord(body) || !Array.isArray(body.links)) {
+          throw new Error('memory spine: malformed response from /api/memory/records/{id}/links (missing links)');
+        }
+        return body.links as unknown as readonly MemoryLink[];
+      } catch (error) {
+        return rethrowMemoryWire404('linksFor', error);
+      }
+    },
+
+    async exportBundle(filter?: MemorySearchFilter): Promise<MemoryBundle> {
+      const connection = options.resolveConnection();
+      try {
+        const body = await wireFetch(connection, '/api/memory/records/export', { method: 'POST', body: (filter ?? {}) as unknown as JsonRecord }, timeoutMs);
+        if (!isRecord(body) || !isRecord(body.bundle)) {
+          throw new Error('memory spine: malformed response from /api/memory/records/export (missing bundle)');
+        }
+        return body.bundle as unknown as MemoryBundle;
+      } catch (error) {
+        return rethrowMemoryWire404('exportBundle', error);
+      }
+    },
+
+    async importBundle(bundle: MemoryBundle): Promise<MemoryImportResult> {
+      const connection = options.resolveConnection();
+      try {
+        const body = await wireFetch(connection, '/api/memory/records/import', { method: 'POST', body: { bundle } as unknown as JsonRecord }, timeoutMs);
+        if (!isRecord(body) || !isRecord(body.result)) {
+          throw new Error('memory spine: malformed response from /api/memory/records/import (missing result)');
+        }
+        return body.result as unknown as MemoryImportResult;
+      } catch (error) {
+        return rethrowMemoryWire404('importBundle', error);
+      }
+    },
+  };
+}

package/src/runtime/services.ts

@@ -18,6 +18,9 @@ import {
   createSpineRestProbe,
   createSpineRestTransport,
 } from './session-spine-rest-transport.ts';
+import { MemorySpineClient, createLocalMemoryAccess } from '@pellux/goodvibes-sdk/platform/runtime/memory-spine';
+import type { MemoryTransport } from '@pellux/goodvibes-sdk/platform/runtime/memory-spine';
+import { createMemorySpineRestTransport } from './memory-spine-rest-transport.ts';
 import { WatcherRegistry } from '@pellux/goodvibes-sdk/platform/watchers';
 import { ArtifactStore } from '@pellux/goodvibes-sdk/platform/artifacts';
 import {
@@ -429,6 +432,20 @@ export interface RuntimeServices extends SdkRuntimeServices {
   readonly workPlanStore: WorkPlanStore;
   readonly memoryStore: MemoryStore;
   readonly memoryRegistry: MemoryRegistry;
+  /**
+   * The consumer half of the daemon-served memory spine (SDK 1.1.0). Constructed
+   * in LOCAL mode always (wrapping `memoryRegistry` directly); a deferred boot task
+   * (see bootstrap.ts, mirroring the session-spine reachability probe) activates it
+   * with the REST wire transport when the agent confirms an adopted daemon, and
+   * deactivates it back to local on confirmed daemon loss. Every consumer that can
+   * express its memory op through the five wire-covered methods (add/honestSearch/
+   * get/updateReview/delete) should route through THIS client, never `memoryRegistry`
+   * directly, so it automatically stops touching the local store file the moment a
+   * daemon is adopted (the single-writer invariant — see memory-spine/client.ts).
+   */
+  readonly memorySpineClient: MemorySpineClient;
+  /** The wire transport handed to `memorySpineClient.activate()` on daemon adoption; exposed so bootstrap can activate/reuse it without rebuilding the connection resolver. */
+  readonly memorySpineTransport: MemoryTransport;
   readonly serviceRegistry: ServiceRegistry;
   readonly secretsManager: SecretsManager;
   readonly subscriptionManager: SubscriptionManager;
@@ -648,6 +665,20 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     embeddingRegistry: memoryEmbeddingRegistry,
   });
   const memoryRegistry = new MemoryRegistry(memoryStore);
+  // Consumer half of the memory spine (SDK 1.1.0). Always constructed in LOCAL mode
+  // (embedded/offline is a hard requirement — the agent must work with no daemon
+  // running). `spineResolveConnection` above is the SAME connected-host connection
+  // (host/port/token) already built for the session spine; one daemon, one resolver.
+  // Activation to CLIENT mode (routing every op over the wire, for the whole process
+  // lifetime, never touching this local store again) happens in a deferred boot task
+  // — see bootstrap.ts's 'memory-spine' schedule — once that task confirms a daemon
+  // is actually adopted, reusing sessionSpineClient.probeReachability() as the
+  // existing daemon-adoption signal rather than inventing a second one.
+  const memorySpineClient = new MemorySpineClient({
+    local: createLocalMemoryAccess(memoryRegistry),
+    log: logger,
+  });
+  const memorySpineTransport = createMemorySpineRestTransport({ resolveConnection: spineResolveConnection });
   const deliveryManager = new AutomationDeliveryManager({
     configManager,
     serviceRegistry,
@@ -955,6 +986,8 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     workPlanStore,
     memoryStore,
     memoryRegistry,
+    memorySpineClient,
+    memorySpineTransport,
     serviceRegistry,
     secretsManager,
     subscriptionManager,