@xdarkicex/openclaw-memory-libravdb 1.10.10 → 1.10.14-beta.1

package/dist/index.js

@@ -18615,10 +18615,10 @@ function buildRulesContext() {
 }
 
 // src/manifest.ts
-import * as fs2 from "fs";
-import * as path2 from "path";
-import * as crypto from "crypto";
-import * as os2 from "os";
+import * as fs2 from "node:fs";
+import * as path2 from "node:path";
+import * as crypto from "node:crypto";
+import * as os2 from "node:os";
 var TurnManifestStore = class {
   manifestDir;
   constructor() {
@@ -18923,7 +18923,7 @@ function normalizeCompactResult(response, options = {}) {
   const threshold = options.threshold;
   const overBudget = threshold != null && tokensBefore >= threshold;
   const engineRefused = !didCompact && overBudget;
-  const tokensAfter = didCompact && typeof response?.tokensAfter === "number" && response.tokensAfter > 0 ? response.tokensAfter : void 0;
+  const tokensAfter = didCompact && typeof response?.tokensAfter === "number" && response.tokensAfter >= 0 ? response.tokensAfter : void 0;
   return {
     ok: !engineRefused,
     compacted: didCompact,
@@ -18931,8 +18931,7 @@ function normalizeCompactResult(response, options = {}) {
     result: {
       tokensBefore,
       ...tokensAfter != null ? { tokensAfter } : {},
-      ...details.summaryMethod ? { summary: details.summaryMethod } : {},
-      ...details.summaryText ? { summaryText: details.summaryText } : {},
+      ...details.summaryText ? { summary: details.summaryText } : {},
       details: { ...details, ...threshold != null ? { threshold } : {} }
     }
   };
@@ -19011,6 +19010,18 @@ function findLastUserMessageIndex(messages) {
   }
   return -1;
 }
+function selectTurnAlignedSourceSuffix(messages, maxMessages) {
+  if (messages.length === 0) return [];
+  let start = Math.max(0, messages.length - Math.max(1, Math.floor(maxMessages)));
+  while (start > 0 && messages[start]?.role !== "user") {
+    start -= 1;
+  }
+  if (messages[start]?.role !== "user") {
+    const firstUserIndex = messages.findIndex((message) => message.role === "user");
+    start = firstUserIndex >= 0 ? firstUserIndex : 0;
+  }
+  return messages.slice(start);
+}
 function normalizeKernelContent(content, options = {}) {
   const text = typeof content === "string" ? content : Array.isArray(content) ? content.map(stringifyKernelBlock).filter((part) => part.length > 0).join("\n") : "";
   return stripOpenClawUntrustedMetadataEnvelope(text, {
@@ -19374,6 +19385,32 @@ function trimMessagesToBudget(messages, tokenBudget) {
   }
   return [{ ...last, content: truncated }];
 }
+function trimTurnAlignedSourceSuffixToBudget(messages, tokenBudget) {
+  if (messages.length === 0) return [];
+  const userStarts = [];
+  for (let index = 0; index < messages.length; index += 1) {
+    if (messages[index]?.role === "user") userStarts.push(index);
+  }
+  if (userStarts.length === 0) {
+    return messages;
+  }
+  const keptBundles = [];
+  let used = 0;
+  let bundleEnd = messages.length;
+  for (let index = userStarts.length - 1; index >= 0; index -= 1) {
+    const bundleStart = userStarts[index];
+    const bundle = messages.slice(bundleStart, bundleEnd);
+    const bundleCost = approximateMessagesTokens(bundle);
+    if (keptBundles.length > 0 && used + bundleCost > tokenBudget) {
+      break;
+    }
+    keptBundles.unshift(bundle);
+    used += bundleCost;
+    bundleEnd = bundleStart;
+    if (used >= tokenBudget) break;
+  }
+  return keptBundles.flat();
+}
 function boundAfterTurnMessagesForIngest(messages, logger, sessionId) {
   const estimatedTokens = approximateMessagesTokens(messages);
   if (estimatedTokens <= AFTER_TURN_INGEST_MAX_TOKENS) {
@@ -19414,6 +19451,34 @@ function enforceTokenBudgetInvariant(result, tokenBudget) {
     estimatedTokens: Math.min(effectiveBudget, systemPromptTokens + trimmedEstimate)
   };
 }
+function enforceCompactedProjectionBudgetInvariant(result, tokenBudget) {
+  if (typeof tokenBudget !== "number" || !Number.isFinite(tokenBudget) || tokenBudget <= 0) {
+    return result;
+  }
+  const effectiveBudget = resolveEffectiveAssembleBudget(Math.max(1, Math.floor(tokenBudget)));
+  const approximateTotal = approximateTokenCount(result.systemPromptAddition) + approximateMessagesTokens(result.messages);
+  if (result.estimatedTokens <= effectiveBudget && approximateTotal <= effectiveBudget) {
+    return result;
+  }
+  const lastUserIndex = findLastUserMessageIndex(result.messages);
+  const mandatoryMessages = lastUserIndex >= 0 ? result.messages.slice(lastUserIndex) : result.messages;
+  const mandatoryTokens = approximateMessagesTokens(mandatoryMessages);
+  const systemPromptBudget = Math.max(0, effectiveBudget - mandatoryTokens);
+  const systemPromptAddition = truncateSystemPromptAdditionToTokenBudget(
+    result.systemPromptAddition,
+    systemPromptBudget
+  );
+  const systemPromptTokens = approximateTokenCount(systemPromptAddition);
+  const messageBudget = Math.max(mandatoryTokens, effectiveBudget - systemPromptTokens);
+  const messages = trimTurnAlignedSourceSuffixToBudget(result.messages, messageBudget);
+  const estimatedTokens = systemPromptTokens + approximateMessagesTokens(messages);
+  return {
+    ...result,
+    messages,
+    systemPromptAddition,
+    estimatedTokens
+  };
+}
 function buildBudgetFallbackContext(messages, tokenBudget) {
   const effectiveBudget = resolveEffectiveAssembleBudget(tokenBudget);
   const fallbackMessages = trimMessagesToBudget(
@@ -19430,7 +19495,11 @@ function buildBudgetFallbackContext(messages, tokenBudget) {
 var DAEMON_AUTHORED_CONTEXT_RE = /<authored_context\b[^>]*>([\s\S]*?)<\/authored_context>/gi;
 var DAEMON_AUTHORED_CONTEXT_GUIDANCE_RE = /^\s*Treat the authored entries below as active project rules and identity context\.?\s*$/i;
 var COMPACTED_SESSION_CONTEXT_RE = /<compacted_session_context\b([^>]*)>([\s\S]*?)<\/compacted_session_context>/gi;
+var HAS_COMPACTED_SESSION_CONTEXT_RE = /<compacted_session_context\b/i;
 var COMPACTED_SESSION_RENDER_LEDGER_RE = /(?:^|\n)(?:Artifacts:|Constraints:|Open Next Steps:|Extracted context anchors:)(?:\n|$)/;
+function hasCompactedSessionContext(text) {
+  return HAS_COMPACTED_SESSION_CONTEXT_RE.test(text);
+}
 function sanitizeDaemonSystemPromptAddition(text) {
   return demoteDaemonAuthoredContextBlocks(
     sanitizeToolCallPatterns(canonicalizeCompactedSessionContextBlocks(text))
@@ -19781,13 +19850,13 @@ function ensureReplaySafeUserTurn(assembled, sourceMessages, logger, tokenBudget
     estimatedTokens: baseEstimatedTokens + approximateMessageTokens(fallbackUser)
   };
 }
-function normalizeAssembleResult(result, sourceMessages) {
+function normalizeAssembleResult(result, sourceMessages, promptAuthority = PROMPT_AUTHORITY_PREASSEMBLY_MAY_OVERFLOW) {
   const systemPromptAddition = typeof result.systemPromptAddition === "string" ? sanitizeDaemonSystemPromptAddition(result.systemPromptAddition) : "";
   return {
     messages: sourceMessages ?? [],
     estimatedTokens: typeof result.estimatedTokens === "number" ? result.estimatedTokens : 0,
     systemPromptAddition,
-    promptAuthority: PROMPT_AUTHORITY_PREASSEMBLY_MAY_OVERFLOW,
+    promptAuthority,
     ...result.debug != null ? { debug: result.debug } : {}
   };
 }
@@ -19858,6 +19927,7 @@ function buildContextEngineFactory(runtime, cfg, logger = console) {
     setOptimizationMemoCacheSize(cfg.optimizationMemoCacheSize);
   }
   const predictiveContextCache = /* @__PURE__ */ new Map();
+  const compactedProjectionSessions = /* @__PURE__ */ new Set();
   const PREDICTIVE_CACHE_MAX_SIZE = 100;
   const turnCache = new TurnMemoryCache(100);
   const circuitBreakers = /* @__PURE__ */ new Map();
@@ -19865,6 +19935,21 @@ function buildContextEngineFactory(runtime, cfg, logger = console) {
   let lastUserMessageHash = null;
   let cachedIdentity = null;
   let cachedSessionKey;
+  function activateCompactedProjection(sessionId, source) {
+    const wasActive = compactedProjectionSessions.has(sessionId);
+    compactedProjectionSessions.add(sessionId);
+    predictiveContextCache.delete(sessionId);
+    postToolRecallCache.delete(sessionId);
+    turnCache.invalidateSession(sessionId);
+    if (!wasActive) {
+      logger.info?.(
+        `LibraVDB activated daemon-owned compacted projection sessionId=${sessionId} source=${source}`
+      );
+    }
+  }
+  function enforceAssembleBudget(result, tokenBudget, compactionProjectionActive) {
+    return compactionProjectionActive ? enforceCompactedProjectionBudgetInvariant(result, tokenBudget) : enforceTokenBudgetInvariant(result, tokenBudget);
+  }
   function resolveUserId(args) {
     const fwUserId = args?.userIdOverride?.trim();
     if (fwUserId) return fwUserId;
@@ -20281,16 +20366,36 @@ ${cached}
       return null;
     }
   }
+  async function injectPersonaContext(params) {
+    try {
+      const resp = await params.client.getUserCard({ userId: "__bot_persona__" });
+      if (!resp.cardJson) return null;
+      let card;
+      try {
+        card = JSON.parse(resp.cardJson).card ?? resp.cardJson;
+      } catch {
+        card = resp.cardJson;
+      }
+      if (!card || card.trim().length === 0) return null;
+      return "<bot_persona>\n" + card + "\n</bot_persona>";
+    } catch {
+      return null;
+    }
+  }
   async function runCompaction(args) {
     const request3 = buildCompactSessionRequest(args);
     try {
       const client = await runtime.getClient();
       const threshold = getDynamicCompactThreshold(args.tokenBudget);
-      return normalizeCompactResult(await client.compactSession(request3), {
+      const result = normalizeCompactResult(await client.compactSession(request3), {
         tokensBefore: args.currentTokenCount,
         logger,
         ...threshold != null ? { threshold } : {}
       });
+      if (result.ok && result.compacted) {
+        activateCompactedProjection(args.sessionId, "compact");
+      }
+      return result;
     } catch (error2) {
       return {
         ok: false,
@@ -20347,6 +20452,7 @@ ${cached}
       const sessionId = requireSessionId(args.sessionId, "bootstrap");
       predictiveContextCache.delete(sessionId);
       postToolRecallCache.delete(sessionId);
+      turnCache.invalidateSession(sessionId);
       asyncIngestionQueues.delete(sessionId);
       const userId = resolveUserId({
         userIdOverride: args.userId,
@@ -20390,13 +20496,26 @@ ${cached}
     },
     async assemble(args) {
       const sessionId = requireSessionId(args.sessionId, "assemble");
+      let compactionProjectionActive = compactedProjectionSessions.has(sessionId);
       const userId = resolveUserId({
         userIdOverride: args.userId,
         sessionKey: args.sessionKey
       });
       const normalizeWindow = 50;
-      const recentMessages = args.messages.length > normalizeWindow ? args.messages.slice(-normalizeWindow) : args.messages;
+      const recentMessages = selectTurnAlignedSourceSuffix(args.messages, normalizeWindow);
       const messages = normalizeKernelMessages(recentMessages);
+      const projectedSourceMessages = () => compactionProjectionActive ? recentMessages : args.messages;
+      const buildAssembleFallback = () => {
+        if (!compactionProjectionActive) {
+          return buildBudgetFallbackContext(args.messages, args.tokenBudget);
+        }
+        return enforceCompactedProjectionBudgetInvariant({
+          messages: projectedSourceMessages(),
+          estimatedTokens: approximateMessagesTokens(projectedSourceMessages()),
+          systemPromptAddition: "",
+          promptAuthority: "assembled"
+        }, args.tokenBudget);
+      };
       const strippedPrompt = args.prompt ? normalizeKernelContent(args.prompt, { retainOpenClawContext: false }) : "";
       const lastUserIndex = findLastUserMessageIndex(messages);
       const isPostToolContinuation = lastUserIndex >= 0 && lastUserIndex < messages.length - 1 && hasLiveToolProtocolAfterLastUser(messages, lastUserIndex);
@@ -20442,17 +20561,23 @@ ${cached}
           compacted: compactionResult.compacted,
           reason: compactionResult.reason
         });
-        if (!compactionResult.ok) {
+        compactionProjectionActive = compactedProjectionSessions.has(sessionId);
+        if (!compactionResult.ok && !compactionProjectionActive) {
           logger.info?.(
             `LibraVDB predictive compaction blocked assemble path at ${currentContextTokens} tokens (threshold=${dynamicCompactThreshold}): ${compactionResult.reason ?? "compaction failed"}`
           );
           return ensureReplaySafeUserTurn(
-            buildBudgetFallbackContext(args.messages, args.tokenBudget),
+            buildAssembleFallback(),
             args.messages,
             logger,
             args.tokenBudget
           );
         }
+        if (!compactionResult.ok) {
+          logger.info?.(
+            `LibraVDB predictive compaction made no additional progress at ${currentContextTokens} tokens; continuing with the existing daemon-owned compacted projection.`
+          );
+        }
       }
       const btLog = cfg.beforeTurnDebug ? (msg) => logger.info?.(msg) : (_msg) => {
       };
@@ -20499,10 +20624,20 @@ ${cached}
           }
         }
         if (cachedSystemPrompt !== void 0) {
-          const mockResp = { messages: args.messages, systemPromptAddition: cachedSystemPrompt };
-          enforced = enforceTokenBudgetInvariant(
-            normalizeAssembleResult(mockResp, args.messages),
-            args.tokenBudget
+          if (hasCompactedSessionContext(cachedSystemPrompt)) {
+            activateCompactedProjection(sessionId, "assemble");
+            compactionProjectionActive = true;
+          }
+          const sourceProjection = projectedSourceMessages();
+          const mockResp = { messages: sourceProjection, systemPromptAddition: cachedSystemPrompt };
+          enforced = enforceAssembleBudget(
+            normalizeAssembleResult(
+              mockResp,
+              sourceProjection,
+              compactionProjectionActive ? "assembled" : PROMPT_AUTHORITY_PREASSEMBLY_MAY_OVERFLOW
+            ),
+            args.tokenBudget,
+            compactionProjectionActive
           );
         } else {
           const pending = asyncIngestionQueues.get(sessionId);
@@ -20564,7 +20699,16 @@ ${cached}
               (_, reject) => setTimeout(() => reject(new Error(`AssembleContextInternal timed out after ${assembleTimeout}ms`)), assembleTimeout)
             )
           ]);
-          const assembled = normalizeAssembleResult(resp, args.messages);
+          if (typeof resp.systemPromptAddition === "string" && hasCompactedSessionContext(resp.systemPromptAddition)) {
+            activateCompactedProjection(sessionId, "assemble");
+            compactionProjectionActive = true;
+          }
+          const sourceProjection = projectedSourceMessages();
+          const assembled = normalizeAssembleResult(
+            resp,
+            sourceProjection,
+            compactionProjectionActive ? "assembled" : PROMPT_AUTHORITY_PREASSEMBLY_MAY_OVERFLOW
+          );
           const continuityContext = await injectContinuityContext({
             client,
             userId,
@@ -20575,10 +20719,14 @@ ${cached}
             systemPromptAddition: assembled.systemPromptAddition
           });
           const userCardContext = await injectUserCardContext({ client, userId });
+          const personaContext = await injectPersonaContext({ client });
           const rulesContext = buildRulesContext();
           const isSessionBootstrap = messages.length <= 1;
           let withContext = assembled;
           if (isSessionBootstrap) {
+            if (personaContext) {
+              withContext = { ...withContext, systemPromptAddition: appendSystemPromptAddition(withContext.systemPromptAddition, personaContext) };
+            }
             if (userCardContext) {
               withContext = { ...withContext, systemPromptAddition: appendSystemPromptAddition(withContext.systemPromptAddition, userCardContext) };
             }
@@ -20589,7 +20737,7 @@ ${cached}
               withContext = { ...withContext, systemPromptAddition: appendSystemPromptAddition(withContext.systemPromptAddition, rulesContext) };
             }
           }
-          enforced = enforceTokenBudgetInvariant(
+          enforced = enforceAssembleBudget(
             await augmentWithExactRecall(withContext, {
               queryText: retrievalQuery,
               userId,
@@ -20597,7 +20745,8 @@ ${cached}
               tokenBudget: args.tokenBudget,
               reservedTokens: reservedCurrentTurnTokens
             }),
-            args.tokenBudget
+            args.tokenBudget,
+            compactionProjectionActive
           );
           const predictions = predictiveContextCache.get(sessionId) || [];
           predictiveContextCache.delete(sessionId);
@@ -20654,9 +20803,10 @@ ${cached}
             systemPromptAddition: enforced.systemPromptAddition
           });
         }
-        enforced = enforceTokenBudgetInvariant(
+        enforced = enforceAssembleBudget(
           enforced,
-          args.tokenBudget
+          args.tokenBudget,
+          compactionProjectionActive
         );
         return ensureReplaySafeUserTurn(enforced, args.messages, logger, args.tokenBudget);
       } catch (error2) {
@@ -20664,7 +20814,7 @@ ${cached}
           `LibraVDB assemble failed, using budget-clamped fallback context: ${error2 instanceof Error ? error2.message : String(error2)}`
         );
         return ensureReplaySafeUserTurn(
-          buildBudgetFallbackContext(args.messages, args.tokenBudget),
+          buildAssembleFallback(),
           args.messages,
           logger,
           args.tokenBudget
@@ -20852,6 +21002,7 @@ ${cached}
         }
       }
       predictiveContextCache.clear();
+      compactedProjectionSessions.clear();
       postToolRecallCache.clear();
       asyncIngestionQueues.clear();
       triggerCache.clear();
@@ -31174,6 +31325,12 @@ function buildToolGuidance(availableTools) {
     return [];
   }
   const lines = [];
+  const hasSearch = availableTools.has("memory_search");
+  const hasGet = availableTools.has("memory_get");
+  const hasDescribe = availableTools.has("memory_describe");
+  const hasExpand = availableTools.has("memory_expand");
+  const hasGrep = availableTools.has("memory_grep");
+  const hasUserCard = availableTools.has("get_user_card");
   const hasGetCard = availableTools.has("get_user_card");
   const hasListCards = availableTools.has("list_user_cards");
   if (hasGetCard || hasListCards) {
@@ -31184,7 +31341,7 @@ function buildToolGuidance(availableTools) {
       hasListCards ? "- `list_user_cards()` \u2014 MANDATORY roster check. Call if unsure whether a card exists." : "",
       "Cards are the canonical record. You MUST call these tools. Do NOT answer from",
       "memory, context, or training data without checking the card first.",
-      "Only use memory_search if the card is empty or missing.",
+      hasSearch ? "Only use memory_search if the card is empty or missing." : "Use the card result as the available identity record.",
       "",
       "**Autonomous card maintenance:**",
       hasGetCard ? "- When ANY speaker is mentioned with new or changed information (status, relationships, jobs, life events, feelings), call `update_user_card` BEFORE responding. Update the card first, then reply. Do NOT wait to be asked. Build the world picture proactively. Every person the user mentions matters." : "",
@@ -31192,20 +31349,19 @@ function buildToolGuidance(availableTools) {
       ""
     );
   }
-  lines.push(
-    "Call `memory_search` once per user question for prior turns, remembered",
-    "facts, earliest interactions, and channel history. Do not answer memory",
-    "questions from prior transcript claims \u2014 perform a search every time.",
-    "After receiving results, use them directly; do not re-call in the same turn.",
-    ...availableTools.has("memory_get") ? [
-      "After a `memory_search` hit, call `memory_get` when exact wording or more context is needed.",
-      "IMPORTANT: If a search snippet is cluttered with metadata, do NOT claim nothing was found. Call `memory_get` on the hit's path to read the full record first. The data is there \u2014 expand before giving up."
-    ] : [],
-    ""
-  );
-  const hasDescribe = availableTools.has("memory_describe");
-  const hasExpand = availableTools.has("memory_expand");
-  const hasGrep = availableTools.has("memory_grep");
+  if (hasSearch) {
+    lines.push(
+      "Call `memory_search` once per user question for prior turns, remembered",
+      "facts, earliest interactions, and channel history. Do not answer memory",
+      "questions from prior transcript claims \u2014 perform a search every time.",
+      "After receiving results, use them directly; do not re-call in the same turn.",
+      ...hasGet ? [
+        "After a `memory_search` hit, call `memory_get` when exact wording or more context is needed.",
+        "IMPORTANT: If a search snippet is cluttered with metadata, do NOT claim nothing was found. Call `memory_get` on the hit's path to read the full record first. The data is there \u2014 expand before giving up."
+      ] : [],
+      ""
+    );
+  }
   if (hasDescribe || hasExpand || hasGrep) {
     lines.push(
       "**Compacted summaries \u2014 recall hierarchy (cheap \u2192 expensive):**",
@@ -31252,13 +31408,16 @@ function buildToolGuidance(availableTools) {
     ""
   );
   if (hasExpand) {
+    const traversalSteps = [
+      hasSearch ? "1. `memory_search` for the people/events in question to get record IDs" : "1. Start from a record ID already present in context or another tool result",
+      "2. `memory_expand` with the most relevant `record_id` to walk typed causal and 6W1H hop edges",
+      hasGet ? "3. Follow interesting edges; use `memory_get` for exact detail on connected records" : "3. Use the typed edge snippets to decide whether the connected records answer the question",
+      ...hasUserCard ? ["4. Use `get_user_card` to cross-reference identity context"] : []
+    ];
     lines.push(
       "### Causal Graph Traversal",
       "When the user asks about causes, patterns, or relationships:",
-      "1. `memory_search` for the people/events in question to get record IDs",
-      "2. `memory_expand` with the most relevant `record_id` to walk causal edges",
-      "3. Follow interesting edges \u2014 use `memory_get` for full detail on connected records",
-      "4. Use `get_user_card` to cross-reference identity context",
+      ...traversalSteps,
       ""
     );
   }
@@ -31446,7 +31605,7 @@ function createMemoryExpandTool(getClient, getSessionKey, logger = console, getS
   return {
     name: "memory_expand",
     label: "Memory Expand",
-    description: "Expand compacted summaries OR walk causal graph edges from ANY record. Summary mode (summaryIds): walk the summary tree up to maxDepth levels. Graph mode (record_id): walk causal edges (why_ids/how_ids/hop_targets) from a record ID. Use exact IDs from memory_search or memory_get results \u2014 any ingested turn, memory, or summary has graph edges. After get_user_card for context, search for related people/events then expand the most relevant hit. For large expansions, spawns a sub-agent. Use memory_describe first to check if expansion is warranted.",
+    description: "Expand compacted summaries OR walk causal graph edges from ANY record. Summary mode (summaryIds): walk the summary tree up to maxDepth levels. Graph mode (record_id): walk causal edges (why_ids/how_ids/hop_targets) from a record ID. Use exact IDs from memory_search or memory_get results \u2014 any ingested turn, memory, or summary has graph edges. For large expansions, spawns a sub-agent. Use memory_describe first to check if expansion is warranted.",
     parameters: MEMORY_EXPAND_SCHEMA,
     execute: async (_toolCallId, rawParams) => {
       const params = asParams(rawParams);
@@ -31461,10 +31620,16 @@ function createMemoryExpandTool(getClient, getSessionKey, logger = console, getS
           const client = await getClient();
           const resp = await client.expandSummary({ recordId, maxDepth });
           let text = resp.text ?? "";
-          const connected = resp.connected;
-          if (connected && connected.length > 0) {
+          const connected = (resp.connected ?? []).map((c) => ({
+            recordId: c.recordId,
+            text: c.text ?? "",
+            depth: c.depth,
+            edgeType: c.edgeType || "unknown",
+            edgeWeight: c.edgeWeight ?? 0
+          }));
+          if (connected.length > 0) {
             text = connected.map(
-              (c) => `[depth=${c.depth}] ${c.recordId}: ${c.text || ""}`
+              (c) => `[depth=${c.depth} edge=${c.edgeType} weight=${c.edgeWeight}] ${c.recordId}: ${c.text}`
             ).join("\n\n");
           }
           if (!text && resp.whyIds?.length) {
@@ -31474,7 +31639,7 @@ hop_targets: ${resp.hopTargets?.join(", ") ?? "none"}`;
           }
           return {
             content: [{ type: "text", text: text || "(no graph edges found)" }],
-            details: { summaryId: recordId, depth: maxDepth, text: text || "", truncated: false, exceededBudget: false, parentCount: connected?.length ?? 0 }
+            details: { summaryId: recordId, depth: maxDepth, text: text || "", truncated: false, exceededBudget: false, parentCount: connected.length, connected }
           };
         } catch (error2) {
           logger.warn?.(`memory_expand graph mode failed: ${formatError(error2)}`);
@@ -31788,6 +31953,55 @@ function createListUserCardsTool(getClient, logger = console) {
     }
   };
 }
+function createSetPersonaTool(getClient, logger = console) {
+  return {
+    name: "set_persona",
+    label: "Set Persona",
+    description: "Define who YOU are \u2014 your personality, tone, boundaries, and behavior. Write in prose like you're describing yourself. This is injected as <bot_persona> at the start of every session. Update it when your persona changes. The LLM will embody this persona in all interactions.",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        persona: { type: "string", description: "Prose description of how you should behave." }
+      },
+      required: ["persona"]
+    },
+    execute: async (_toolCallId, rawParams) => {
+      const params = rawParams;
+      const persona = typeof params?.persona === "string" ? params.persona.trim() : "";
+      if (!persona) return jsonResult2({ ok: false, error: "set_persona requires a persona string" });
+      try {
+        const client = await getClient();
+        const resp = await client.upsertUserCard({
+          userId: "__bot_persona__",
+          cardJson: JSON.stringify({ card: persona, updatedAt: Date.now() })
+        });
+        return jsonResult2({ ok: resp.ok });
+      } catch (error2) {
+        logger.warn?.(`set_persona failed: ${formatError(error2)}`);
+        return jsonResult2({ ok: false, error: formatError(error2) });
+      }
+    }
+  };
+}
+function createGetPersonaTool(getClient, logger = console) {
+  return {
+    name: "get_persona",
+    label: "Get Persona",
+    description: "Read your current persona. Returns the full prose description of how you should behave.",
+    parameters: { type: "object", additionalProperties: false, properties: {} },
+    execute: async () => {
+      try {
+        const client = await getClient();
+        const resp = await client.getUserCard({ userId: "__bot_persona__" });
+        return jsonResult2({ persona: resp.cardJson || null });
+      } catch (error2) {
+        logger.warn?.(`get_persona failed: ${formatError(error2)}`);
+        return jsonResult2({ error: formatError(error2) });
+      }
+    }
+  };
+}
 
 // src/memory-tools.ts
 var MEMORY_SEARCH_SCHEMA = {
@@ -35609,6 +35823,14 @@ function register(api) {
     api.registerTool?.(() => createGetRuleTool(logger), { names: ["get_rule"] });
     api.registerTool?.(() => createListRulesTool(logger), { names: ["list_rules"] });
     api.registerTool?.(() => createDeleteRuleTool(logger), { names: ["delete_rule"] });
+    api.registerTool?.(() => {
+      const getClient = runtimeOrNull.getClient;
+      return createSetPersonaTool(getClient, logger);
+    }, { names: ["set_persona"] });
+    api.registerTool?.(() => {
+      const getClient = runtimeOrNull.getClient;
+      return createGetPersonaTool(getClient, logger);
+    }, { names: ["get_persona"] });
   }
   if (isLightweight || isDiscovery) {
     if (!isLightweight) {

package/dist/manifest.js

@@ -1,7 +1,7 @@
-import * as fs from "fs";
-import * as path from "path";
-import * as crypto from "crypto";
-import * as os from "os";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import * as os from "node:os";
 export class TurnManifestStore {
     manifestDir;
     constructor() {

package/dist/memory-provider.js

@@ -25,22 +25,27 @@ function buildToolGuidance(availableTools) {
         return [];
     }
     const lines = [];
+    const hasSearch = availableTools.has("memory_search");
+    const hasGet = availableTools.has("memory_get");
+    const hasDescribe = availableTools.has("memory_describe");
+    const hasExpand = availableTools.has("memory_expand");
+    const hasGrep = availableTools.has("memory_grep");
+    const hasUserCard = availableTools.has("get_user_card");
     // ── User card tools (identity-first override) ──
     const hasGetCard = availableTools.has("get_user_card");
     const hasListCards = availableTools.has("list_user_cards");
     if (hasGetCard || hasListCards) {
-        lines.push("**Identity/Entity questions — MANDATORY card lookup:**", "BEFORE answering any question about a person, pet, place, or named thing:", hasGetCard ? "- `get_user_card(user_id)` — MANDATORY lookup for a specific entity." : "", hasListCards ? "- `list_user_cards()` — MANDATORY roster check. Call if unsure whether a card exists." : "", "Cards are the canonical record. You MUST call these tools. Do NOT answer from", "memory, context, or training data without checking the card first.", "Only use memory_search if the card is empty or missing.", "", "**Autonomous card maintenance:**", hasGetCard ? "- When ANY speaker is mentioned with new or changed information (status, relationships, jobs, life events, feelings), call `update_user_card` BEFORE responding. Update the card first, then reply. Do NOT wait to be asked. Build the world picture proactively. Every person the user mentions matters." : "", hasGetCard ? "- If a card for the speaker doesn't exist yet, CREATE one with `update_user_card`. Better to have a stub card than no card at all." : "", "");
+        lines.push("**Identity/Entity questions — MANDATORY card lookup:**", "BEFORE answering any question about a person, pet, place, or named thing:", hasGetCard ? "- `get_user_card(user_id)` — MANDATORY lookup for a specific entity." : "", hasListCards ? "- `list_user_cards()` — MANDATORY roster check. Call if unsure whether a card exists." : "", "Cards are the canonical record. You MUST call these tools. Do NOT answer from", "memory, context, or training data without checking the card first.", hasSearch ? "Only use memory_search if the card is empty or missing." : "Use the card result as the available identity record.", "", "**Autonomous card maintenance:**", hasGetCard ? "- When ANY speaker is mentioned with new or changed information (status, relationships, jobs, life events, feelings), call `update_user_card` BEFORE responding. Update the card first, then reply. Do NOT wait to be asked. Build the world picture proactively. Every person the user mentions matters." : "", hasGetCard ? "- If a card for the speaker doesn't exist yet, CREATE one with `update_user_card`. Better to have a stub card than no card at all." : "", "");
+    }
+    if (hasSearch) {
+        lines.push("Call `memory_search` once per user question for prior turns, remembered", "facts, earliest interactions, and channel history. Do not answer memory", "questions from prior transcript claims — perform a search every time.", "After receiving results, use them directly; do not re-call in the same turn.", ...(hasGet
+            ? [
+                "After a `memory_search` hit, call `memory_get` when exact wording or more context is needed.",
+                "IMPORTANT: If a search snippet is cluttered with metadata, do NOT claim nothing was found. Call `memory_get` on the hit's path to read the full record first. The data is there — expand before giving up."
+            ]
+            : []), "");
     }
-    lines.push("Call `memory_search` once per user question for prior turns, remembered", "facts, earliest interactions, and channel history. Do not answer memory", "questions from prior transcript claims — perform a search every time.", "After receiving results, use them directly; do not re-call in the same turn.", ...(availableTools.has("memory_get")
-        ? [
-            "After a `memory_search` hit, call `memory_get` when exact wording or more context is needed.",
-            "IMPORTANT: If a search snippet is cluttered with metadata, do NOT claim nothing was found. Call `memory_get` on the hit's path to read the full record first. The data is there — expand before giving up."
-        ]
-        : []), "");
     // ── Summaries / recall (when available) ──
-    const hasDescribe = availableTools.has("memory_describe");
-    const hasExpand = availableTools.has("memory_expand");
-    const hasGrep = availableTools.has("memory_grep");
     if (hasDescribe || hasExpand || hasGrep) {
         lines.push("**Compacted summaries — recall hierarchy (cheap → expensive):**", "", "Summaries in search results show `[Summary sum_xxx]: [eviction cue]`.", "The cue lists what the summary covers — anchors (files, tools, versions),", "decisions, constraints, and signal counts. Many questions can be answered", "from the cue alone without expanding.", "");
         if (hasDescribe) {
@@ -58,7 +63,17 @@ function buildToolGuidance(availableTools) {
     lines.push("### Hard Constraint Rules", "Rules are injected at session start as `<hard_constraints>`. They are non-negotiable.", "Use `set_rule` to create one (max 20), `list_rules` to see current rules,", "`delete_rule` to remove one. Rules override all other instructions.", "Never reason around a rule, find loopholes, or deprioritize it.", "");
     // ── Causal graph traversal (when expand supports record_id) ──
     if (hasExpand) {
-        lines.push("### Causal Graph Traversal", "When the user asks about causes, patterns, or relationships:", "1. `memory_search` for the people/events in question to get record IDs", "2. `memory_expand` with the most relevant `record_id` to walk causal edges", "3. Follow interesting edges — use `memory_get` for full detail on connected records", "4. Use `get_user_card` to cross-reference identity context", "");
+        const traversalSteps = [
+            hasSearch
+                ? "1. `memory_search` for the people/events in question to get record IDs"
+                : "1. Start from a record ID already present in context or another tool result",
+            "2. `memory_expand` with the most relevant `record_id` to walk typed causal and 6W1H hop edges",
+            hasGet
+                ? "3. Follow interesting edges; use `memory_get` for exact detail on connected records"
+                : "3. Use the typed edge snippets to decide whether the connected records answer the question",
+            ...(hasUserCard ? ["4. Use `get_user_card` to cross-reference identity context"] : []),
+        ];
+        lines.push("### Causal Graph Traversal", "When the user asks about causes, patterns, or relationships:", ...traversalSteps, "");
     }
     lines.push("LibraVDB memory is vector-backed and retrieved through tools, not files.", "");
     return lines;