clawvault 1.6.0 → 1.7.0

package/bin/clawvault.js

@@ -384,6 +384,29 @@ program
     }
   });
 
+// === SESSION-RECAP ===
+program
+  .command('session-recap <sessionKey>')
+  .description('Generate recap from a specific OpenClaw session transcript')
+  .option('-n, --limit <n>', 'Number of messages to include', '15')
+  .option('--format <format>', 'Output format (markdown|json)', 'markdown')
+  .option('-a, --agent <id>', 'Agent ID (default: OPENCLAW_AGENT_ID or clawdious)')
+  .action(async (sessionKey, options) => {
+    try {
+      const { sessionRecapCommand } = await import('../dist/commands/session-recap.js');
+      const format = options.format === 'json' ? 'json' : 'markdown';
+      const parsedLimit = Number.parseInt(options.limit, 10);
+      await sessionRecapCommand(sessionKey, {
+        limit: Number.isNaN(parsedLimit) ? 15 : parsedLimit,
+        format,
+        agentId: options.agent
+      });
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
 // === LIST ===
 program
   .command('list [category]')

package/dist/chunk-XQUQIW6E.js

@@ -0,0 +1,273 @@
+import {
+  getSessionFilePath,
+  getSessionsDir,
+  loadSessionsStore
+} from "./chunk-AZRV2I5U.js";
+
+// src/commands/session-recap.ts
+import * as fs from "fs";
+import * as path from "path";
+var DEFAULT_LIMIT = 15;
+var MAX_LIMIT = 50;
+var READ_CHUNK_SIZE = 64 * 1024;
+var MAX_TURN_TEXT_LENGTH = 420;
+var MAX_TOTAL_TEXT_LENGTH = 12e3;
+var SESSION_KEY_PATTERN = /^agent:[a-zA-Z0-9_-]+:[a-zA-Z0-9:_-]+$/;
+var AGENT_ID_PATTERN = /^[a-zA-Z0-9_-]{1,100}$/;
+function sanitizeSessionKey(input) {
+  const sessionKey = input.trim();
+  if (!SESSION_KEY_PATTERN.test(sessionKey)) {
+    throw new Error("Invalid session key. Expected format: agent:<agentId>:<scope>");
+  }
+  return sessionKey;
+}
+function sanitizeAgentId(input) {
+  const agentId = input.trim();
+  if (!AGENT_ID_PATTERN.test(agentId)) {
+    throw new Error('Invalid agent ID. Use letters, numbers, "_" or "-".');
+  }
+  return agentId;
+}
+function parseAgentIdFromSessionKey(sessionKey) {
+  const match = /^agent:([^:]+):/.exec(sessionKey);
+  if (!match?.[1]) return null;
+  return sanitizeAgentId(match[1]);
+}
+function resolveAgentId(sessionKey, explicitAgentId) {
+  if (explicitAgentId) {
+    return sanitizeAgentId(explicitAgentId);
+  }
+  const fromSessionKey = parseAgentIdFromSessionKey(sessionKey);
+  if (fromSessionKey) return fromSessionKey;
+  const fromEnv = process.env.OPENCLAW_AGENT_ID;
+  if (fromEnv) return sanitizeAgentId(fromEnv);
+  return "clawdious";
+}
+function normalizeLimit(limit) {
+  if (limit === void 0 || Number.isNaN(limit)) return DEFAULT_LIMIT;
+  const parsed = Math.floor(limit);
+  return Math.min(MAX_LIMIT, Math.max(1, parsed));
+}
+function isPathInside(parentPath, candidatePath) {
+  const normalizedParent = parentPath.endsWith(path.sep) ? parentPath : `${parentPath}${path.sep}`;
+  return candidatePath.startsWith(normalizedParent);
+}
+function resolveSafeTranscriptPath(agentId, sessionId, sessionFile) {
+  const sessionsDir = getSessionsDir(agentId);
+  if (!fs.existsSync(sessionsDir)) {
+    throw new Error(`Sessions directory not found for agent "${agentId}".`);
+  }
+  const sessionsDirRealPath = fs.realpathSync(sessionsDir);
+  const candidatePaths = [];
+  if (typeof sessionFile === "string" && sessionFile.trim()) {
+    candidatePaths.push(path.resolve(sessionFile));
+  }
+  candidatePaths.push(getSessionFilePath(agentId, sessionId));
+  for (const candidatePath of candidatePaths) {
+    if (path.extname(candidatePath).toLowerCase() !== ".jsonl") continue;
+    if (!fs.existsSync(candidatePath)) continue;
+    let candidateRealPath = "";
+    try {
+      candidateRealPath = fs.realpathSync(candidatePath);
+    } catch {
+      continue;
+    }
+    if (!isPathInside(sessionsDirRealPath, candidateRealPath)) {
+      continue;
+    }
+    const stat = fs.statSync(candidateRealPath);
+    if (!stat.isFile()) continue;
+    return candidateRealPath;
+  }
+  throw new Error(`No valid transcript found for session "${sessionId}".`);
+}
+function getSessionStoreEntry(agentId, sessionKey) {
+  const store = loadSessionsStore(agentId);
+  if (!store) {
+    throw new Error(`Could not load sessions store for agent "${agentId}".`);
+  }
+  const entry = store[sessionKey];
+  if (!entry) {
+    throw new Error(`Session key not found: ${sessionKey}`);
+  }
+  if (typeof entry.sessionId !== "string" || !entry.sessionId.trim()) {
+    throw new Error(`Invalid session mapping for "${sessionKey}" (missing sessionId).`);
+  }
+  return entry;
+}
+function sanitizeText(input) {
+  return input.replace(/[\x00-\x1f\x7f]/g, " ").replace(/\s+/g, " ").trim();
+}
+function truncateText(input, maxLength) {
+  if (input.length <= maxLength) return input;
+  return `${input.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}
+function extractTextFromContent(content) {
+  if (typeof content === "string") {
+    const cleaned = sanitizeText(content);
+    return truncateText(cleaned, MAX_TURN_TEXT_LENGTH);
+  }
+  if (Array.isArray(content)) {
+    const parts = [];
+    for (const part of content) {
+      if (typeof part === "string") {
+        const cleaned2 = sanitizeText(part);
+        if (cleaned2) parts.push(cleaned2);
+        continue;
+      }
+      if (!part || typeof part !== "object") continue;
+      const block = part;
+      const blockType = typeof block.type === "string" ? block.type.toLowerCase() : "";
+      if (blockType.includes("tool") || blockType.includes("thinking") || blockType.includes("reason")) {
+        continue;
+      }
+      const blockText = typeof block.text === "string" ? block.text : typeof block.content === "string" && blockType.includes("text") ? block.content : "";
+      const cleaned = sanitizeText(blockText);
+      if (cleaned) parts.push(cleaned);
+    }
+    return truncateText(parts.join(" "), MAX_TURN_TEXT_LENGTH);
+  }
+  return "";
+}
+function parseTurnFromLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const entry = parsed;
+  if (entry.type !== "message" || !entry.message || typeof entry.message !== "object") {
+    return null;
+  }
+  const message = entry.message;
+  const role = typeof message.role === "string" ? message.role.toLowerCase() : "";
+  if (role !== "user" && role !== "assistant") return null;
+  const text = extractTextFromContent(message.content);
+  if (!text) return null;
+  return { role, text };
+}
+function applyOutputBudget(turns) {
+  let remaining = MAX_TOTAL_TEXT_LENGTH;
+  const selected = [];
+  for (let i = turns.length - 1; i >= 0; i -= 1) {
+    if (remaining <= 0) break;
+    const current = turns[i];
+    let text = current.text;
+    if (text.length > remaining) {
+      if (remaining < 16) break;
+      text = truncateText(text, remaining);
+    }
+    selected.push({ role: current.role, text });
+    remaining -= text.length;
+  }
+  return selected.reverse();
+}
+function readRecentTurnsFromTranscript(filePath, limit) {
+  if (limit <= 0) return [];
+  const fileHandle = fs.openSync(filePath, "r");
+  const collected = [];
+  let remainder = "";
+  try {
+    let position = fs.fstatSync(fileHandle).size;
+    while (position > 0 && collected.length < limit) {
+      const readSize = Math.min(READ_CHUNK_SIZE, position);
+      position -= readSize;
+      const buffer = Buffer.allocUnsafe(readSize);
+      fs.readSync(fileHandle, buffer, 0, readSize, position);
+      const chunk = buffer.toString("utf-8");
+      const text = chunk + remainder;
+      const lines = text.split("\n");
+      remainder = lines.shift() ?? "";
+      for (let lineIndex = lines.length - 1; lineIndex >= 0; lineIndex -= 1) {
+        if (collected.length >= limit) break;
+        const turn = parseTurnFromLine(lines[lineIndex]);
+        if (turn) collected.push(turn);
+      }
+    }
+    if (position === 0 && remainder && collected.length < limit) {
+      const turn = parseTurnFromLine(remainder);
+      if (turn) collected.push(turn);
+    }
+  } finally {
+    fs.closeSync(fileHandle);
+  }
+  return applyOutputBudget(collected.reverse());
+}
+function toSessionLabel(sessionKey, agentId) {
+  const normalizedPrefix = `agent:${agentId}:`;
+  if (sessionKey.startsWith(normalizedPrefix)) {
+    return sessionKey.slice(normalizedPrefix.length) || sessionKey;
+  }
+  const parts = sessionKey.split(":");
+  if (parts[0] === "agent" && parts.length > 2) {
+    return parts.slice(2).join(":");
+  }
+  return sessionKey;
+}
+function formatSessionRecapMarkdown(result) {
+  let output = `## Session Recap: ${result.sessionLabel}
+
+`;
+  output += `### Recent Conversation (last ${result.count} messages)
+`;
+  if (result.messages.length === 0) {
+    output += "_No recent user/assistant messages found._\n";
+    return output.trimEnd();
+  }
+  for (const message of result.messages) {
+    const label = message.role === "user" ? "User" : "Assistant";
+    output += `**${label}:** ${message.text}
+
+`;
+  }
+  return output.trimEnd();
+}
+async function buildSessionRecap(sessionKeyInput, options = {}) {
+  const sessionKey = sanitizeSessionKey(sessionKeyInput);
+  const agentId = resolveAgentId(sessionKey, options.agentId);
+  const limit = normalizeLimit(options.limit);
+  const entry = getSessionStoreEntry(agentId, sessionKey);
+  const sessionId = String(entry.sessionId).trim();
+  const transcriptPath = resolveSafeTranscriptPath(agentId, sessionId, entry.sessionFile);
+  const messages = readRecentTurnsFromTranscript(transcriptPath, limit);
+  const result = {
+    sessionKey,
+    sessionLabel: toSessionLabel(sessionKey, agentId),
+    agentId,
+    sessionId,
+    transcriptPath,
+    generated: (/* @__PURE__ */ new Date()).toISOString(),
+    count: messages.length,
+    messages,
+    markdown: ""
+  };
+  result.markdown = formatSessionRecapMarkdown(result);
+  return result;
+}
+async function sessionRecapCommand(sessionKey, options = {}) {
+  const result = await buildSessionRecap(sessionKey, options);
+  const format = options.format ?? "markdown";
+  if (format === "json") {
+    console.log(JSON.stringify({
+      sessionKey: result.sessionKey,
+      sessionLabel: result.sessionLabel,
+      agentId: result.agentId,
+      sessionId: result.sessionId,
+      generated: result.generated,
+      count: result.count,
+      messages: result.messages
+    }, null, 2));
+    return;
+  }
+  console.log(result.markdown);
+}
+
+export {
+  formatSessionRecapMarkdown,
+  buildSessionRecap,
+  sessionRecapCommand
+};

package/dist/commands/session-recap.d.ts

@@ -0,0 +1,27 @@
+type SessionRecapFormat = 'markdown' | 'json';
+type SessionRole = 'user' | 'assistant';
+interface SessionRecapOptions {
+    limit?: number;
+    format?: SessionRecapFormat;
+    agentId?: string;
+}
+interface SessionTurn {
+    role: SessionRole;
+    text: string;
+}
+interface SessionRecapResult {
+    sessionKey: string;
+    sessionLabel: string;
+    agentId: string;
+    sessionId: string;
+    transcriptPath: string;
+    generated: string;
+    count: number;
+    messages: SessionTurn[];
+    markdown: string;
+}
+declare function formatSessionRecapMarkdown(result: SessionRecapResult): string;
+declare function buildSessionRecap(sessionKeyInput: string, options?: SessionRecapOptions): Promise<SessionRecapResult>;
+declare function sessionRecapCommand(sessionKey: string, options?: SessionRecapOptions): Promise<void>;
+
+export { type SessionRecapFormat, type SessionRecapOptions, type SessionRecapResult, type SessionRole, type SessionTurn, buildSessionRecap, formatSessionRecapMarkdown, sessionRecapCommand };

package/dist/commands/session-recap.js

@@ -0,0 +1,11 @@
+import {
+  buildSessionRecap,
+  formatSessionRecapMarkdown,
+  sessionRecapCommand
+} from "../chunk-XQUQIW6E.js";
+import "../chunk-AZRV2I5U.js";
+export {
+  buildSessionRecap,
+  formatSessionRecapMarkdown,
+  sessionRecapCommand
+};

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { V as VaultConfig, S as StoreOptions, D as Document, a as SearchOptions,
 export { f as DEFAULT_CATEGORIES, g as DEFAULT_CONFIG, h as MEMORY_TYPES, T as TYPE_TO_CATEGORY, i as VaultMeta } from './types-DMU3SuAV.js';
 export { setupCommand } from './commands/setup.js';
 export { ContextEntry, ContextFormat, ContextOptions, ContextResult, buildContext, contextCommand, formatContextMarkdown } from './commands/context.js';
+export { SessionRecapFormat, SessionRecapOptions, SessionRecapResult, SessionTurn, buildSessionRecap, formatSessionRecapMarkdown, sessionRecapCommand } from './commands/session-recap.js';
 export { TemplateVariables, buildTemplateVariables, renderTemplate } from './lib/template-engine.js';
 
 /**

package/dist/index.js

@@ -1,3 +1,8 @@
+import {
+  buildSessionRecap,
+  formatSessionRecapMarkdown,
+  sessionRecapCommand
+} from "./chunk-XQUQIW6E.js";
 import {
   setupCommand
 } from "./chunk-PIJGYMQZ.js";
@@ -30,6 +35,7 @@ import {
   qmdEmbed,
   qmdUpdate
 } from "./chunk-MIIXBNO3.js";
+import "./chunk-AZRV2I5U.js";
 
 // src/index.ts
 import * as fs from "fs";
@@ -55,6 +61,7 @@ export {
   TYPE_TO_CATEGORY,
   VERSION,
   buildContext,
+  buildSessionRecap,
   buildTemplateVariables,
   contextCommand,
   createVault,
@@ -62,9 +69,11 @@ export {
   extractWikiLinks,
   findVault,
   formatContextMarkdown,
+  formatSessionRecapMarkdown,
   hasQmd,
   qmdEmbed,
   qmdUpdate,
   renderTemplate,
+  sessionRecapCommand,
   setupCommand
 };

package/hooks/clawvault/HOOK.md

@@ -1,10 +1,10 @@
 ---
 name: clawvault
-description: "Context death resilience - auto-checkpoint and recovery detection"
+description: "Context resilience - recovery detection, auto-checkpoint, and session context injection"
 metadata:
   openclaw:
     emoji: "🐘"
-    events: ["gateway:startup", "command:new"]
+    events: ["gateway:startup", "command:new", "session:start"]
     requires:
       bins: ["clawvault"]
 ---
@@ -15,6 +15,7 @@ Integrates ClawVault's context death resilience into OpenClaw:
 
 - **On gateway startup**: Checks for context death, alerts agent
 - **On /new command**: Auto-checkpoints before session reset
+- **On session start**: Injects relevant vault context for the initial prompt
 
 ## Installation
 
@@ -43,6 +44,20 @@ openclaw hooks enable clawvault
 2. Captures state even if agent forgot to handoff
 3. Ensures continuity across session resets
 
+### Session Start
+
+1. Extracts the initial user prompt (`context.initialPrompt` or first user message)
+2. Runs `clawvault context "<prompt>" --format json -v <vaultPath>`
+3. Injects up to 4 relevant context bullets into session messages
+
+Injection format:
+
+```text
+[ClawVault] Relevant context for this task:
+- <title> (<age>): <snippet>
+- <title> (<age>): <snippet>
+```
+
 ## No Configuration Needed
 
 Just enable the hook. It auto-detects vault path via:

package/hooks/clawvault/handler.js

@@ -4,6 +4,7 @@
  * Provides automatic context death resilience:
  * - gateway:startup → detect context death, inject recovery info
  * - command:new → auto-checkpoint before session reset
+ * - session:start → inject relevant context for first user prompt
  * 
  * SECURITY: Uses execFileSync (no shell) to prevent command injection
  */
@@ -12,6 +13,12 @@ import { execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 
+const MAX_CONTEXT_RESULTS = 4;
+const MAX_CONTEXT_PROMPT_LENGTH = 500;
+const MAX_CONTEXT_SNIPPET_LENGTH = 220;
+const MAX_RECAP_RESULTS = 6;
+const MAX_RECAP_SNIPPET_LENGTH = 220;
+
 // Sanitize string for safe display (prevent prompt injection via control chars)
 function sanitizeForDisplay(str) {
   if (typeof str !== 'string') return '';
@@ -22,6 +29,205 @@ function sanitizeForDisplay(str) {
     .slice(0, 200);                   // Limit length
 }
 
+// Sanitize prompt before passing to CLI command
+function sanitizePromptForContext(str) {
+  if (typeof str !== 'string') return '';
+  return str
+    .replace(/[\x00-\x1f\x7f]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, MAX_CONTEXT_PROMPT_LENGTH);
+}
+
+function sanitizeSessionKey(str) {
+  if (typeof str !== 'string') return '';
+  const trimmed = str.trim();
+  if (!/^agent:[a-zA-Z0-9_-]+:[a-zA-Z0-9:_-]+$/.test(trimmed)) {
+    return '';
+  }
+  return trimmed.slice(0, 200);
+}
+
+function extractSessionKey(event) {
+  const candidates = [
+    event?.sessionKey,
+    event?.context?.sessionKey,
+    event?.session?.key,
+    event?.context?.session?.key,
+    event?.metadata?.sessionKey
+  ];
+
+  for (const candidate of candidates) {
+    const key = sanitizeSessionKey(candidate);
+    if (key) return key;
+  }
+
+  return '';
+}
+
+function extractAgentIdFromSessionKey(sessionKey) {
+  const match = /^agent:([^:]+):/.exec(sessionKey);
+  if (!match?.[1]) return '';
+  const agentId = match[1].trim();
+  if (!/^[a-zA-Z0-9_-]{1,100}$/.test(agentId)) return '';
+  return agentId;
+}
+
+function extractTextFromMessage(message) {
+  if (typeof message === 'string') return message;
+  if (!message || typeof message !== 'object') return '';
+
+  const content = message.content ?? message.text ?? message.message;
+  if (typeof content === 'string') return content;
+
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (typeof part === 'string') return part;
+        if (!part || typeof part !== 'object') return '';
+        if (typeof part.text === 'string') return part.text;
+        if (typeof part.content === 'string') return part.content;
+        return '';
+      })
+      .filter(Boolean)
+      .join(' ');
+  }
+
+  return '';
+}
+
+function isUserMessage(message) {
+  if (typeof message === 'string') return true;
+  if (!message || typeof message !== 'object') return false;
+  const role = typeof message.role === 'string' ? message.role.toLowerCase() : '';
+  const type = typeof message.type === 'string' ? message.type.toLowerCase() : '';
+  return role === 'user' || role === 'human' || type === 'user';
+}
+
+function extractInitialPrompt(event) {
+  const fromContext = sanitizePromptForContext(event?.context?.initialPrompt);
+  if (fromContext) return fromContext;
+
+  const candidates = [
+    event?.context?.messages,
+    event?.context?.initialMessages,
+    event?.context?.history,
+    event?.messages
+  ];
+
+  for (const list of candidates) {
+    if (!Array.isArray(list)) continue;
+    for (const message of list) {
+      if (!isUserMessage(message)) continue;
+      const text = sanitizePromptForContext(extractTextFromMessage(message));
+      if (text) return text;
+    }
+  }
+
+  return '';
+}
+
+function truncateSnippet(snippet) {
+  const safe = sanitizeForDisplay(snippet).replace(/\s+/g, ' ').trim();
+  if (safe.length <= MAX_CONTEXT_SNIPPET_LENGTH) return safe;
+  return `${safe.slice(0, MAX_CONTEXT_SNIPPET_LENGTH - 3).trimEnd()}...`;
+}
+
+function truncateRecapSnippet(snippet) {
+  const safe = sanitizeForDisplay(snippet).replace(/\s+/g, ' ').trim();
+  if (safe.length <= MAX_RECAP_SNIPPET_LENGTH) return safe;
+  return `${safe.slice(0, MAX_RECAP_SNIPPET_LENGTH - 3).trimEnd()}...`;
+}
+
+function parseContextJson(output) {
+  try {
+    const parsed = JSON.parse(output);
+    if (!parsed || !Array.isArray(parsed.context)) return [];
+
+    return parsed.context
+      .slice(0, MAX_CONTEXT_RESULTS)
+      .map((entry) => ({
+        title: sanitizeForDisplay(entry?.title || 'Untitled'),
+        age: sanitizeForDisplay(entry?.age || 'unknown age'),
+        snippet: truncateSnippet(entry?.snippet || '')
+      }))
+      .filter((entry) => entry.snippet);
+  } catch {
+    return [];
+  }
+}
+
+function parseSessionRecapJson(output) {
+  try {
+    const parsed = JSON.parse(output);
+    if (!parsed || !Array.isArray(parsed.messages)) return [];
+
+    return parsed.messages
+      .map((entry) => {
+        if (!entry || typeof entry !== 'object') return null;
+        const role = typeof entry.role === 'string' ? entry.role.toLowerCase() : '';
+        if (role !== 'user' && role !== 'assistant') return null;
+        const text = truncateRecapSnippet(typeof entry.text === 'string' ? entry.text : '');
+        if (!text) return null;
+        return {
+          role: role === 'user' ? 'User' : 'Assistant',
+          text
+        };
+      })
+      .filter(Boolean)
+      .slice(-MAX_RECAP_RESULTS);
+  } catch {
+    return [];
+  }
+}
+
+function formatSessionContextInjection(recapEntries, memoryEntries) {
+  const lines = ['[ClawVault] Session context restored:', '', 'Recent conversation:'];
+
+  if (recapEntries.length === 0) {
+    lines.push('- No recent user/assistant turns found for this session.');
+  } else {
+    for (const entry of recapEntries) {
+      lines.push(`- ${entry.role}: ${entry.text}`);
+    }
+  }
+
+  lines.push('', 'Relevant memories:');
+  if (memoryEntries.length === 0) {
+    lines.push('- No relevant vault memories found for the current prompt.');
+  } else {
+    for (const entry of memoryEntries) {
+      lines.push(`- ${entry.title} (${entry.age}): ${entry.snippet}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function injectSystemMessage(event, message) {
+  if (!event.messages || !Array.isArray(event.messages)) return false;
+
+  if (event.messages.length === 0) {
+    event.messages.push(message);
+    return true;
+  }
+
+  const first = event.messages[0];
+  if (first && typeof first === 'object' && !Array.isArray(first)) {
+    if ('role' in first || 'content' in first) {
+      event.messages.push({ role: 'system', content: message });
+      return true;
+    }
+    if ('type' in first || 'text' in first) {
+      event.messages.push({ type: 'system', text: message });
+      return true;
+    }
+  }
+
+  event.messages.push(message);
+  return true;
+}
+
 // Validate vault path - must be absolute and exist
 function validateVaultPath(vaultPath) {
   if (!vaultPath || typeof vaultPath !== 'string') return null;
@@ -151,11 +357,9 @@ async function handleStartup(event) {
     const alertMsg = alertParts.join(' ');
 
     // Inject into event messages if available
-    if (event.messages && Array.isArray(event.messages)) {
-      event.messages.push(alertMsg);
+    if (injectSystemMessage(event, alertMsg)) {
+      console.warn('[clawvault] Context death detected, alert injected');
     }
-    
-    console.warn('[clawvault] Context death detected, alert injected');
   } else {
     console.log('[clawvault] Clean startup - no context death');
   }
@@ -194,6 +398,67 @@ async function handleNew(event) {
   }
 }
 
+// Handle session start - inject dynamic context for first prompt
+async function handleSessionStart(event) {
+  const vaultPath = findVaultPath();
+  if (!vaultPath) {
+    console.log('[clawvault] No vault found, skipping context injection');
+    return;
+  }
+
+  const sessionKey = extractSessionKey(event);
+  const prompt = extractInitialPrompt(event);
+  let recapEntries = [];
+  let memoryEntries = [];
+
+  if (sessionKey) {
+    console.log('[clawvault] Fetching session recap for context restoration');
+    const recapArgs = ['session-recap', sessionKey, '--format', 'json'];
+    const agentId = extractAgentIdFromSessionKey(sessionKey);
+    if (agentId) {
+      recapArgs.push('--agent', agentId);
+    }
+
+    const recapResult = runClawvault(recapArgs);
+    if (!recapResult.success) {
+      console.warn('[clawvault] Session recap lookup failed');
+    } else {
+      recapEntries = parseSessionRecapJson(recapResult.output);
+    }
+  } else {
+    console.log('[clawvault] No session key found, skipping session recap');
+  }
+
+  if (prompt) {
+    console.log('[clawvault] Fetching vault memories for session start prompt');
+    const contextResult = runClawvault([
+      'context',
+      prompt,
+      '--format', 'json',
+      '-v', vaultPath
+    ]);
+
+    if (!contextResult.success) {
+      console.warn('[clawvault] Context lookup failed');
+    } else {
+      memoryEntries = parseContextJson(contextResult.output);
+    }
+  } else {
+    console.log('[clawvault] No initial prompt, skipping vault memory lookup');
+  }
+
+  if (recapEntries.length === 0 && memoryEntries.length === 0) {
+    console.log('[clawvault] No session context available to inject');
+    return;
+  }
+
+  if (injectSystemMessage(event, formatSessionContextInjection(recapEntries, memoryEntries))) {
+    console.log(`[clawvault] Injected session context (${recapEntries.length} recap, ${memoryEntries.length} memories)`);
+  } else {
+    console.log('[clawvault] No message array available, skipping injection');
+  }
+}
+
 // Main handler - route events
 const handler = async (event) => {
   try {
@@ -206,6 +471,11 @@ const handler = async (event) => {
       await handleNew(event);
       return;
     }
+
+    if (event.type === 'session' && event.action === 'start') {
+      await handleSessionStart(event);
+      return;
+    }
   } catch (err) {
     console.error('[clawvault] Hook error:', err.message || 'unknown error');
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawvault",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "🐘 An elephant never forgets. Structured memory for OpenClaw agents. Context death resilience, Obsidian-compatible markdown, local semantic search.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -28,7 +28,7 @@
     ]
   },
   "scripts": {
-    "build": "tsup src/index.ts src/commands/entities.ts src/commands/link.ts src/commands/checkpoint.ts src/commands/recover.ts src/commands/status.ts src/commands/template.ts src/commands/setup.ts src/commands/context.ts src/commands/wake.ts src/commands/sleep.ts src/commands/doctor.ts src/commands/shell-init.ts src/commands/repair-session.ts src/lib/entity-index.ts src/lib/auto-linker.ts src/lib/config.ts src/lib/template-engine.ts src/lib/session-utils.ts src/lib/session-repair.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts src/commands/entities.ts src/commands/link.ts src/commands/checkpoint.ts src/commands/recover.ts src/commands/status.ts src/commands/template.ts src/commands/setup.ts src/commands/context.ts src/commands/session-recap.ts src/commands/wake.ts src/commands/sleep.ts src/commands/doctor.ts src/commands/shell-init.ts src/commands/repair-session.ts src/lib/entity-index.ts src/lib/auto-linker.ts src/lib/config.ts src/lib/template-engine.ts src/lib/session-utils.ts src/lib/session-repair.ts --format esm --dts --clean",
     "dev": "tsup src/index.ts src/commands/*.ts src/lib/*.ts --format esm --dts --watch",
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",