@vellumai/assistant 0.10.7 → 0.10.8-dev.202607102228.5945895

package/src/plugins/defaults/memory/graph-topology/build-memory-graph.ts

@@ -0,0 +1,303 @@
+/**
+ * Produce the canonical {@link MemoryGraph} from the active memory backend.
+ *
+ * Today the active backend is memory-v3, whose knowledge corpus is already an
+ * Obsidian-style graph: markdown articles (identified by slug) linked by
+ * authored `links:` frontmatter / inline `[[wikilinks]]` (the STATIC link
+ * graph) plus behavioral co-selection associations (the LEARNED edge graph).
+ * This module reads exactly the same sources the v3 retrieval lanes build from
+ * (`getPageIndex` + `buildEdgeGraph` + `computeLearnedEdgeGraph`) and maps them
+ * into the backend-agnostic contract — no embeddings, no LLM calls.
+ *
+ * The mapping is split into a pure {@link assembleMemoryGraph} (unit-testable
+ * with plain inputs) and a thin {@link getMemoryGraph} that does the workspace
+ * / DB I/O. When the memory-backend plugin seam lands, `getMemoryGraph` becomes
+ * a call into `backend.getGraph()` — the contract and its route do not change.
+ */
+
+import { isMemoryV3Live } from "../../../../config/memory-v3-gate.js";
+import type { AssistantConfig } from "../../../../config/types.js";
+import { getDb } from "../../../../persistence/db-connection.js";
+import { getWorkspaceDir } from "../paths.js";
+import { getPageIndex, type PageIndexEntry } from "../v2/page-index.js";
+import { readPage, renderPageContent } from "../v2/page-store.js";
+import { isSkillSlug } from "../v2/skill-store.js";
+import { isCapabilitySlug } from "../v3/capabilities.js";
+import { buildEdgeGraph } from "../v3/edge.js";
+import { computeLearnedEdgeGraph } from "../v3/learned-edges.js";
+import type { Slug } from "../v3/types.js";
+import { isMemoryConceptGraphEnabled } from "./flag.js";
+import type {
+  MemoryGraph,
+  MemoryGraphEdge,
+  MemoryGraphNode,
+  MemoryGraphNodeDetail,
+} from "./types.js";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Matches the selection window the v3 shadow lanes read for learned edges. */
+const LEARNED_EDGES_WINDOW_DAYS = 90;
+/** Backend identifier stamped onto graphs produced from memory-v3. */
+const BACKEND_MEMORY_V3 = "memory-v3";
+/**
+ * Upper bound on returned nodes. Real corpora sit well under this (~100–500);
+ * the cap is a payload/render backstop. When exceeded, the highest-degree nodes
+ * are kept and `truncated` is set.
+ */
+const DEFAULT_MAX_NODES = 750;
+/**
+ * Viz-density scaling of the retrieval lane's learned-edges thresholds. The
+ * graph deliberately admits weaker co-selection associations than retrieval
+ * (half the pair-count requirement, 40% of the NPMI floor, and at least
+ * {@link GRAPH_LEARNED_MIN_MAX_PER_PAGE} neighbors per page) so it reads as a
+ * connected web instead of scattered orphans. Retuning
+ * `memory.v3.learnedEdges` for retrieval quality therefore also shifts graph
+ * density — by these factors.
+ */
+const GRAPH_LEARNED_MIN_COUNT_FACTOR = 0.5;
+const GRAPH_LEARNED_NPMI_FLOOR_FACTOR = 0.4;
+const GRAPH_LEARNED_MIN_MAX_PER_PAGE = 14;
+
+/** Adjacency as produced by `buildEdgeGraph` / `computeLearnedEdgeGraph`:
+ * source → (target → curated description | undefined). */
+type Adjacency = Map<Slug, Map<Slug, string | undefined>>;
+
+/** Order-independent key for an undirected pair, so (a,b) and (b,a) collapse. */
+function undirectedKey(a: string, b: string): string {
+  return a < b ? `${a}\t${b}` : `${b}\t${a}`;
+}
+
+/** Title-ish label from a slug: last path segment, separators → spaces,
+ * word-initial caps. `skills/agent-mail` → `Agent Mail`. */
+function humanizeSlug(slug: string): string {
+  const last = slug.split("/").pop() ?? slug;
+  const words = last.replace(/[-_]+/g, " ").trim();
+  if (!words) {
+    return slug;
+  }
+  return words.replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/** Node taxonomy tag used for coloring. Synthetic capability slugs (skills /
+ * CLI commands) carry `modifiedAt: 0`; real concept pages carry a file mtime. */
+function nodeKind(entry: PageIndexEntry): string {
+  if (isSkillSlug(entry.slug)) {
+    return "skill";
+  }
+  if (entry.modifiedAt <= 0) {
+    return "capability";
+  }
+  return "concept";
+}
+
+/** A real concept page: on-disk (has an mtime) and not a synthetic skill or
+ * CLI-command capability slug. The graph shows concepts only. */
+function isConceptEntry(entry: PageIndexEntry): boolean {
+  return entry.modifiedAt > 0 && !isCapabilitySlug(entry.slug);
+}
+
+export interface AssembleMemoryGraphInput {
+  /** Every article node in the corpus (page-index entries). */
+  entries: readonly PageIndexEntry[];
+  /** Directed static link graph (authored `links:` + wikilinks + numeric). */
+  staticAdjacency: Adjacency;
+  /** Undirected learned co-selection graph, or undefined when disabled. */
+  learnedAdjacency?: Adjacency;
+  /** Node cap; defaults to {@link DEFAULT_MAX_NODES}. */
+  maxNodes?: number;
+}
+
+/**
+ * Pure mapping from v3's article + edge structures to the canonical graph.
+ *
+ * Static edges are emitted directed (kind `link`), carrying their curated
+ * description when present. Learned edges are emitted undirected (kind
+ * `learned`), deduped against each other AND against any static edge on the
+ * same pair (an authored link supersedes the learned association visually).
+ * Edges referencing a slug with no node entry are dropped. Node `weight` is the
+ * resulting degree, and drives the truncation ranking.
+ */
+export function assembleMemoryGraph(input: AssembleMemoryGraphInput): {
+  nodes: MemoryGraphNode[];
+  edges: MemoryGraphEdge[];
+  truncated?: boolean;
+} {
+  const { entries, staticAdjacency, learnedAdjacency } = input;
+  const maxNodes = input.maxNodes ?? DEFAULT_MAX_NODES;
+
+  const nodeIds = new Set<string>(entries.map((e) => e.slug));
+  const degree = new Map<string, number>();
+  const bump = (id: string): void => {
+    degree.set(id, (degree.get(id) ?? 0) + 1);
+  };
+
+  const edges: MemoryGraphEdge[] = [];
+  const staticPairs = new Set<string>();
+
+  // Static link edges — directed, authored/structural.
+  for (const [source, out] of staticAdjacency) {
+    if (!nodeIds.has(source)) {
+      continue;
+    }
+    for (const [target, description] of out) {
+      if (!nodeIds.has(target)) {
+        continue;
+      }
+      const edge: MemoryGraphEdge = {
+        source,
+        target,
+        kind: "link",
+        directed: true,
+      };
+      if (description) {
+        edge.description = description;
+      }
+      edges.push(edge);
+      staticPairs.add(undirectedKey(source, target));
+      bump(source);
+      bump(target);
+    }
+  }
+
+  // Learned edges — undirected, deduped against static and each other.
+  if (learnedAdjacency) {
+    const emitted = new Set<string>();
+    for (const [source, out] of learnedAdjacency) {
+      if (!nodeIds.has(source)) {
+        continue;
+      }
+      for (const target of out.keys()) {
+        if (!nodeIds.has(target)) {
+          continue;
+        }
+        const key = undirectedKey(source, target);
+        if (staticPairs.has(key) || emitted.has(key)) {
+          continue;
+        }
+        emitted.add(key);
+        const [a, b] = key.split("\t") as [string, string];
+        edges.push({ source: a, target: b, kind: "learned", directed: false });
+        bump(a);
+        bump(b);
+      }
+    }
+  }
+
+  let nodes: MemoryGraphNode[] = entries.map((entry) => {
+    const node: MemoryGraphNode = {
+      id: entry.slug,
+      label: humanizeSlug(entry.slug),
+      kind: nodeKind(entry),
+      weight: degree.get(entry.slug) ?? 0,
+    };
+    if (entry.summary) {
+      node.summary = entry.summary;
+    }
+    if (entry.modifiedAt > 0) {
+      node.updatedAtMs = entry.modifiedAt;
+    }
+    return node;
+  });
+
+  if (nodes.length <= maxNodes) {
+    return { nodes, edges };
+  }
+
+  // Over the cap — keep the highest-degree nodes and drop dangling edges.
+  nodes = [...nodes]
+    .sort((a, b) => (b.weight ?? 0) - (a.weight ?? 0))
+    .slice(0, maxNodes);
+  const kept = new Set(nodes.map((n) => n.id));
+  const keptEdges = edges.filter(
+    (e) => kept.has(e.source) && kept.has(e.target),
+  );
+  return { nodes, edges: keptEdges, truncated: true };
+}
+
+/**
+ * Build the canonical memory graph for the active backend. Returns an
+ * unsupported, empty graph when memory-v3 is not the live backend, so callers
+ * can render a graceful empty state rather than an error.
+ */
+export async function getMemoryGraph(
+  config: AssistantConfig,
+): Promise<MemoryGraph> {
+  if (!isMemoryConceptGraphEnabled(config) || !isMemoryV3Live(config)) {
+    return { backend: null, supported: false, nodes: [], edges: [] };
+  }
+
+  const workspaceDir = getWorkspaceDir();
+  const pageIndex = await getPageIndex(workspaceDir);
+  // Concepts only: exclude synthetic skill / CLI-command slugs so the graph is
+  // purely the assistant's learned/authored concept pages. Edges to excluded
+  // slugs drop out downstream because they aren't in the node set.
+  const conceptEntries = pageIndex.entries.filter(isConceptEntry);
+
+  // Raw (frontmatter + body) page reader, matching the v3 lane build. A read
+  // that rejects drops that article's authored/wikilink edges but keeps its
+  // numeric fallbacks.
+  const pageRaw = async (slug: Slug): Promise<string> => {
+    const page = await readPage(workspaceDir, slug);
+    if (!page) {
+      throw new Error(`page not found: ${slug}`);
+    }
+    return renderPageContent(page);
+  };
+
+  const staticGraph = await buildEdgeGraph(conceptEntries, pageRaw, {
+    hubDegree: config.memory.v3.edge.hubDegree,
+  });
+
+  // Viz-tuned learned edges (see the GRAPH_LEARNED_* constants): this endpoint
+  // is visualization-only, so surfacing weaker co-selection associations (and a
+  // little extra edge noise) is a fair trade. Floors keep the thresholds sane
+  // even when the retrieval config is aggressive or disables the lane.
+  const learned = config.memory.v3.learnedEdges;
+  const learnedGraph = computeLearnedEdgeGraph(
+    { db: getDb() },
+    {
+      halfLifeMs: learned.halfLifeDays * DAY_MS,
+      minCount: Math.max(1, learned.minCount * GRAPH_LEARNED_MIN_COUNT_FACTOR),
+      npmiFloor: Math.max(
+        0,
+        learned.npmiFloor * GRAPH_LEARNED_NPMI_FLOOR_FACTOR,
+      ),
+      maxPerPage: Math.max(learned.maxPerPage, GRAPH_LEARNED_MIN_MAX_PER_PAGE),
+      now: Date.now(),
+      windowMs: LEARNED_EDGES_WINDOW_DAYS * DAY_MS,
+      knownSlugs: new Set(conceptEntries.map((e) => e.slug)),
+    },
+  );
+
+  const assembled = assembleMemoryGraph({
+    entries: conceptEntries,
+    staticAdjacency: staticGraph.adjacency,
+    learnedAdjacency: learnedGraph.adjacency,
+  });
+
+  return { backend: BACKEND_MEMORY_V3, supported: true, ...assembled };
+}
+
+/**
+ * Fetch a single concept node's content (its markdown body) by id. Used when a
+ * user opens a node in the graph. Concepts only — skill/capability slugs and
+ * unreadable pages return `{ found: false }`.
+ */
+export async function getMemoryGraphNode(
+  config: AssistantConfig,
+  id: string,
+): Promise<MemoryGraphNodeDetail> {
+  if (
+    !isMemoryConceptGraphEnabled(config) ||
+    !isMemoryV3Live(config) ||
+    !id ||
+    isCapabilitySlug(id)
+  ) {
+    return { found: false };
+  }
+  const page = await readPage(getWorkspaceDir(), id).catch(() => null);
+  if (!page) {
+    return { found: false };
+  }
+  return { found: true, title: humanizeSlug(id), content: page.body };
+}

package/src/plugins/defaults/memory/graph-topology/flag.ts

@@ -0,0 +1,14 @@
+import { isAssistantFeatureFlagEnabled } from "../../../../config/assistant-feature-flags.js";
+import type { AssistantConfig } from "../../../../config/types.js";
+
+/**
+ * Feature flag gating the memory concept graph — the identity-page graph and
+ * the backend-agnostic `/memory-graph` + `/memory-graph-node` routes that feed
+ * it. Default off; when off the endpoints report `supported: false` and the
+ * identity page falls back to the skills constellation.
+ */
+export const MEMORY_CONCEPT_GRAPH_FLAG = "memory-concept-graph" as const;
+
+export function isMemoryConceptGraphEnabled(config: AssistantConfig): boolean {
+  return isAssistantFeatureFlagEnabled(MEMORY_CONCEPT_GRAPH_FLAG, config);
+}

package/src/plugins/defaults/memory/graph-topology/types.ts

@@ -0,0 +1,84 @@
+/**
+ * Canonical, backend-agnostic memory-graph topology contract.
+ *
+ * This is the DURABLE wire shape for "the assistant's memory as a graph": a set
+ * of nodes (concepts / notes / entities) and the edges between them. It is
+ * deliberately minimal and optional-rich so that ANY memory backend can map
+ * onto it — the in-prod memory-v3 article/link graph today, and a swapped-in
+ * backend (Cognee, Zep, …) tomorrow — without the route or the clients that
+ * consume it having to change. The producer names itself via `backend`.
+ *
+ * Backends that cannot expose a graph return `{ supported: false }` with empty
+ * arrays; consumers render a dedicated "not available on this backend" state
+ * rather than treating it as an error (mirrors the `MEMORY_V2_DISABLED`
+ * two-state pattern already used by the concept-page reads).
+ */
+
+import { z } from "zod";
+
+export const MemoryGraphNodeSchema = z.object({
+  /** Stable, backend-defined node id (memory-v3: the article slug). */
+  id: z.string(),
+  /** Human-readable display title. */
+  label: z.string(),
+  /** Optional short description / summary shown on hover. */
+  summary: z.string().optional(),
+  /**
+   * Backend taxonomy tag for coloring/filtering (memory-v3: `concept` |
+   * `skill` | `capability`). Free-form so backends can use their own kinds.
+   */
+  kind: z.string().optional(),
+  /**
+   * Relative importance / size hint for rendering (memory-v3: node degree).
+   * Not normalized — consumers scale it for their own layout.
+   */
+  weight: z.number().optional(),
+  /** Epoch ms the node was last updated, when the backend tracks it. */
+  updatedAtMs: z.number().optional(),
+});
+export type MemoryGraphNode = z.infer<typeof MemoryGraphNodeSchema>;
+
+export const MemoryGraphEdgeSchema = z.object({
+  /** Source node id. */
+  source: z.string(),
+  /** Target node id. */
+  target: z.string(),
+  /**
+   * Relationship kind for styling (memory-v3: `link` for authored links /
+   * wikilinks, `learned` for behavioral co-selection associations).
+   */
+  kind: z.string().optional(),
+  /** Optional strength in [0, 1] when the backend scores edges. */
+  weight: z.number().optional(),
+  /** Optional curated edge label (memory-v3: the `links:` description). */
+  description: z.string().optional(),
+  /** Whether the edge is directed. Undirected edges may render without arrows. */
+  directed: z.boolean().optional(),
+});
+export type MemoryGraphEdge = z.infer<typeof MemoryGraphEdgeSchema>;
+
+export const MemoryGraphSchema = z.object({
+  /** Name of the memory backend that produced this graph; `null` if none. */
+  backend: z.string().nullable(),
+  /** Whether the active backend exposes a graph at all. */
+  supported: z.boolean(),
+  nodes: z.array(MemoryGraphNodeSchema),
+  edges: z.array(MemoryGraphEdgeSchema),
+  /** Set when the graph was capped and does not include every node/edge. */
+  truncated: z.boolean().optional(),
+});
+export type MemoryGraph = z.infer<typeof MemoryGraphSchema>;
+
+/**
+ * Detail for a single graph node — the concept's own rendered content, fetched
+ * on demand when a user opens a node. `found: false` when the node has no
+ * readable page (deleted, or a backend that can't render node bodies).
+ */
+export const MemoryGraphNodeDetailSchema = z.object({
+  found: z.boolean(),
+  /** Display title (humanized id). */
+  title: z.string().optional(),
+  /** Markdown-rendered node body (memory-v3: the concept page's markdown, frontmatter stripped). */
+  content: z.string().optional(),
+});
+export type MemoryGraphNodeDetail = z.infer<typeof MemoryGraphNodeDetailSchema>;

package/src/plugins/defaults/memory/hooks/init.ts

@@ -15,8 +15,8 @@
 import type { HookFunction, InitContext } from "@vellumai/plugin-api";
 
 import { getConfig } from "../../../../config/loader.js";
-import { getLogger } from "../../../../util/logger.js";
 import { registerMemoryPluginJobHandlers } from "../job-handler-registration.js";
+import { getLogger } from "../logging.js";
 import { runMemoryStartup } from "../startup.js";
 
 const log = getLogger("memory-init");

package/src/plugins/defaults/memory/hooks/user-prompt-submit.ts

@@ -31,6 +31,7 @@ import type {
   HookFunction,
   UserPromptSubmitContext,
 } from "@vellumai/plugin-api";
+import { updateMessageMetadata } from "@vellumai/plugin-api";
 
 import { getConfig } from "../../../../config/loader.js";
 import { isMemoryV3Live } from "../../../../config/memory-v3-gate.js";
@@ -43,9 +44,8 @@ import {
 } from "../../../../daemon/conversation-runtime-assembly.js";
 import type { MemoryRecalled } from "../../../../daemon/message-types/memory.js";
 import { resolveTrustClass } from "../../../../daemon/trust-context.js";
-import { updateMessageMetadata } from "../../../../persistence/conversation-crud.js";
 import { broadcastMessage } from "../../../../runtime/assistant-event-hub.js";
-import type { GraphMemoryResult } from "../../../types.js";
+import type { GraphMemoryResult } from "../graph/conversation-graph-memory.js";
 import { recordMemoryRecallLog } from "../memory-recall-log-store.js";
 import { MEMORY_V3_INJECTED_BLOCK_METADATA_KEY } from "../v3/ever-injected-store.js";
 
@@ -81,13 +81,13 @@ export function shouldRunV2Retrieval(params: {
  * persistInjectionBlocks} REMOVES this key again in its combined update — a
  * transient both-keys state mid-turn is acceptable; a v2 loss window is not.
  */
-function recordRecallSideEffects(
+async function recordRecallSideEffects(
   graphResult: GraphMemoryResult,
   ctx: UserPromptSubmitContext,
-): void {
+): Promise<void> {
   if (graphResult.injectedBlockText) {
     try {
-      updateMessageMetadata(ctx.userMessageId, {
+      await updateMessageMetadata(ctx.userMessageId, {
         memoryInjectedBlock: graphResult.injectedBlockText,
       });
     } catch (err) {
@@ -180,11 +180,11 @@ function recordRecallSideEffects(
  *    persists under `MEMORY_V3_INJECTED_BLOCK_METADATA_KEY`; `loadFromDb`
  *    re-wraps and splices it on load, freezing the cards into history.
  */
-function persistInjectionBlocks(
+async function persistInjectionBlocks(
   blocks: RuntimeInjectionResult["blocks"],
   ctx: UserPromptSubmitContext,
   v2BlockPersisted: boolean,
-): void {
+): Promise<void> {
   const removeV2Block = Boolean(blocks.memoryV3Active) && v2BlockPersisted;
   if (
     !blocks.unifiedTurnContext &&
@@ -243,7 +243,7 @@ function persistInjectionBlocks(
       metadataUpdates.nonInteractiveContextBlock =
         blocks.nonInteractiveContextBlock;
     }
-    updateMessageMetadata(ctx.userMessageId, metadataUpdates);
+    await updateMessageMetadata(ctx.userMessageId, metadataUpdates);
   } catch (err) {
     ctx.logger.warn(
       { err },
@@ -304,7 +304,7 @@ const userPromptSubmitMemoryRetrieval: HookFunction<
       broadcastMessage,
     );
 
-    recordRecallSideEffects(graphResult, ctx);
+    await recordRecallSideEffects(graphResult, ctx);
     // The v2 block is persisted inside `recordRecallSideEffects`. If
     // memory-v3 supersedes it later this turn, `persistInjectionBlocks`
     // removes the key in its combined post-assembly update.
@@ -365,7 +365,7 @@ const userPromptSubmitMemoryRetrieval: HookFunction<
     conversationId: ctx.conversationId,
   });
   ctx.latestMessages = injection.messages;
-  persistInjectionBlocks(injection.blocks, ctx, v2BlockPersisted);
+  await persistInjectionBlocks(injection.blocks, ctx, v2BlockPersisted);
 };
 
 export default userPromptSubmitMemoryRetrieval;

package/src/plugins/defaults/memory/host-utils.ts

@@ -0,0 +1,80 @@
+/**
+ * The memory plugin's single channel for generic host utilities. Every module
+ * in this plugin obtains these helpers here rather than importing the host
+ * `util/*` modules directly, so the host imports below are the plugin's sole
+ * util escapes (tracked by `plugin-import-boundary-guard.test.ts`), mirroring
+ * `logging.ts` and `paths.ts`.
+ *
+ * Forwarding (not copying) is deliberate: `BackendUnavailableError` identity
+ * must be shared with the host — `persistence/job-utils` classifies plugin-
+ * thrown errors via `instanceof` — and `isAbortReason` must agree with the
+ * host's abort-reason tagging. The pure helpers forward alongside them so the
+ * plugin has exactly one file to re-home per concern (own the copy, or a
+ * contract facet) if memory ever builds as an external plugin.
+ *
+ * Namespace imports keep this module loadable under tests that mock a host
+ * util with a subset of its exports; each wrapper resolves its function at
+ * call time, so `mock.module` interception keeps working through the waist.
+ */
+import type { AbortReason } from "../../../util/abort-reasons.js";
+import * as hostAbortReasons from "../../../util/abort-reasons.js";
+import * as hostLogRedact from "../../../util/log-redact.js";
+import * as hostProcessLiveness from "../../../util/process-liveness.js";
+import * as hostRetry from "../../../util/retry.js";
+import type { SqliteRetryOptions } from "../../../util/sqlite-retry.js";
+import * as hostSqliteRetry from "../../../util/sqlite-retry.js";
+import * as hostStripCommentLines from "../../../util/strip-comment-lines.js";
+import * as hostTruncate from "../../../util/truncate.js";
+import * as hostWorkerMemory from "../../../util/worker-memory.js";
+
+export { BackendUnavailableError } from "../../../util/errors.js";
+export { PromiseGuard } from "../../../util/promise-guard.js";
+
+export function isAbortReason(value: unknown): value is AbortReason {
+  return hostAbortReasons.isAbortReason(value);
+}
+
+export function redactLogString(value: string): string {
+  return hostLogRedact.redactLogString(value);
+}
+
+export function isProcessAlive(pid: number): boolean {
+  return hostProcessLiveness.isProcessAlive(pid);
+}
+
+export function computeRetryDelay(
+  attempt: number,
+  baseDelayMs?: number,
+): number {
+  return baseDelayMs === undefined
+    ? hostRetry.computeRetryDelay(attempt)
+    : hostRetry.computeRetryDelay(attempt, baseDelayMs);
+}
+
+export function abortableSleep(
+  ms: number,
+  signal?: AbortSignal,
+): Promise<void> {
+  return hostRetry.abortableSleep(ms, signal);
+}
+
+export function withSqliteRetry<T>(
+  fn: () => T | Promise<T>,
+  options: SqliteRetryOptions,
+): Promise<T> {
+  return hostSqliteRetry.withSqliteRetry(fn, options);
+}
+
+export function stripCommentLines(content: string): string {
+  return hostStripCommentLines.stripCommentLines(content);
+}
+
+export function truncate(str: string, maxLen: number, suffix?: string): string {
+  return suffix === undefined
+    ? hostTruncate.truncate(str, maxLen)
+    : hostTruncate.truncate(str, maxLen, suffix);
+}
+
+export function workerMemoryEnv(): Record<string, string | undefined> {
+  return hostWorkerMemory.workerMemoryEnv();
+}

package/src/plugins/defaults/memory/identity-context.ts

@@ -0,0 +1,39 @@
+import { resolveGuardianPersona } from "../../../prompts/persona-resolver.js";
+import { readPromptFile } from "../../../prompts/system-prompt.js";
+import { isTemplateContent } from "../../../prompts/template-detection.js";
+import { getWorkspacePromptPath } from "./paths.js";
+
+const IDENTITY_PROMPT_FILES = ["IDENTITY.md", "SOUL.md"] as const;
+
+/**
+ * The assistant's self-description for memory's own model calls: IDENTITY.md
+ * and SOUL.md from the workspace, plus the guardian's user persona. Returns
+ * null when none are present.
+ *
+ * Memory owns this composition — what its prompts include is a plugin
+ * concern. The output is kept in lockstep with the host's out-of-band
+ * identity block (`buildCoreIdentityContext`) by
+ * `memory-identity-context-parity.test.ts`; diverge deliberately, not by
+ * accident.
+ */
+export function buildIdentityContext(): string | null {
+  const parts: string[] = [];
+  for (const file of IDENTITY_PROMPT_FILES) {
+    const content = readPromptFile(getWorkspacePromptPath(file));
+    if (!content) {
+      continue;
+    }
+    // SOUL.md always counts — it provides personality defaults even before
+    // onboarding completes. Only skip IDENTITY.md while it is still an
+    // unmodified template.
+    if (file !== "SOUL.md" && isTemplateContent(content, file)) {
+      continue;
+    }
+    parts.push(content);
+  }
+  const guardianPersona = resolveGuardianPersona();
+  if (guardianPersona) {
+    parts.push(guardianPersona);
+  }
+  return parts.length > 0 ? parts.join("\n\n") : null;
+}