clawvault 2.1.2 → 2.2.1

package/dist/commands/wake.js

@@ -4,18 +4,23 @@ import {
 import {
   clearDirtyFlag
 } from "../chunk-MZZJLQNQ.js";
+import {
+  parseObservationMarkdown
+} from "../chunk-K6XHCUFL.js";
+import {
+  listObservationFiles
+} from "../chunk-Z2XBWN7A.js";
 import "../chunk-7ZRP733D.js";
 import {
   ClawVault
-} from "../chunk-QFBKWDYR.js";
-import "../chunk-MIIXBNO3.js";
-import "../chunk-O5V7SD5C.js";
+} from "../chunk-OTQW3OMC.js";
+import "../chunk-FDJIZKCW.js";
+import "../chunk-ZZA73MFY.js";
 
 // src/commands/wake.ts
 import * as fs from "fs";
 import * as path from "path";
 var DEFAULT_HANDOFF_LIMIT = 3;
-var OBSERVATION_HIGHLIGHT_RE = /^(🔴|🟡)\s+(.+)$/u;
 var MAX_WAKE_RED_OBSERVATIONS = 20;
 var MAX_WAKE_YELLOW_OBSERVATIONS = 10;
 var MAX_WAKE_OUTPUT_LINES = 100;
@@ -39,40 +44,48 @@ function buildWakeSummary(recovery, recap) {
   }
   return workSummary || "No recent work summary found.";
 }
-function formatDateKey(date) {
-  return date.toISOString().split("T")[0];
-}
 function readRecentObservationHighlights(vaultPath) {
   const now = /* @__PURE__ */ new Date();
+  const today = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+  const fileByDate = new Map(
+    listObservationFiles(vaultPath, {
+      includeLegacy: true,
+      includeArchive: false,
+      dedupeByDate: true
+    }).map((entry) => [entry.date, entry.path])
+  );
   const highlights = [];
   for (let daysAgo = 0; daysAgo < 7; daysAgo++) {
-    const date = new Date(now);
-    date.setDate(now.getDate() - daysAgo);
-    const dateKey = formatDateKey(date);
-    const filePath = path.join(vaultPath, "observations", `${dateKey}.md`);
-    if (!fs.existsSync(filePath)) continue;
+    const date = new Date(today);
+    date.setUTCDate(today.getUTCDate() - daysAgo);
+    const dateKey = date.toISOString().slice(0, 10);
+    const filePath = fileByDate.get(dateKey);
+    if (!filePath || !fs.existsSync(filePath)) continue;
     const content = fs.readFileSync(filePath, "utf-8");
-    const dayRed = [];
-    const dayYellow = [];
-    for (const line of content.split(/\r?\n/)) {
-      const match = line.trim().match(OBSERVATION_HIGHLIGHT_RE);
-      if (!match?.[2]) continue;
+    const parsed = parseObservationMarkdown(content).filter((record) => record.importance >= 0.4);
+    const dayStructural = [];
+    const dayPotential = [];
+    for (const record of parsed) {
       const item = {
         date: dateKey,
-        priority: match[1],
-        text: match[2].trim()
+        type: record.type,
+        importance: record.importance,
+        text: record.content.trim()
       };
-      if (item.priority === "\u{1F534}") dayRed.push(item);
-      else dayYellow.push(item);
+      if (record.importance >= 0.8) {
+        dayStructural.push(item);
+      } else {
+        dayPotential.push(item);
+      }
     }
     if (daysAgo === 0) {
-      highlights.push(...dayRed, ...dayYellow);
+      highlights.push(...dayStructural, ...dayPotential);
     } else if (daysAgo === 1) {
-      highlights.push(...dayRed, ...dayYellow.slice(0, 5));
+      highlights.push(...dayStructural, ...dayPotential.slice(0, 5));
     } else if (daysAgo <= 3) {
-      highlights.push(...dayRed);
+      highlights.push(...dayStructural);
     } else {
-      highlights.push(...dayRed.slice(0, 3));
+      highlights.push(...dayStructural.slice(0, 3));
     }
   }
   return highlights;
@@ -88,16 +101,19 @@ function compareByRecency(left, right) {
   if (left.date !== right.date) {
     return right.date.localeCompare(left.date);
   }
+  if (left.importance !== right.importance) {
+    return right.importance - left.importance;
+  }
   return timeFromObservationText(right.text) - timeFromObservationText(left.text);
 }
 function formatRecentObservations(highlights) {
   if (highlights.length === 0) {
-    return "_No critical or notable observations from today or yesterday._";
+    return "_No structural or potentially important observations from the recent window._";
   }
   const sorted = [...highlights].sort(compareByRecency);
-  const red = sorted.filter((item) => item.priority === "\u{1F534}").slice(0, MAX_WAKE_RED_OBSERVATIONS);
-  const yellow = sorted.filter((item) => item.priority === "\u{1F7E1}").slice(0, MAX_WAKE_YELLOW_OBSERVATIONS);
-  const visible = [...red, ...yellow].sort(compareByRecency);
+  const structural = sorted.filter((item) => item.importance >= 0.8).slice(0, MAX_WAKE_RED_OBSERVATIONS);
+  const potential = sorted.filter((item) => item.importance >= 0.4 && item.importance < 0.8).slice(0, MAX_WAKE_YELLOW_OBSERVATIONS);
+  const visible = [...structural, ...potential].sort(compareByRecency);
   const omittedCount = Math.max(0, highlights.length - visible.length);
   const byDate = /* @__PURE__ */ new Map();
   for (const item of visible) {
@@ -116,7 +132,7 @@ function formatRecentObservations(highlights) {
       if (lines.length >= bodyLineBudget) {
         break;
       }
-      lines.push(`- ${item.priority} ${item.text}`);
+      lines.push(`- [${item.type}|i=${item.importance.toFixed(2)}] ${item.text}`);
     }
     if (lines.length < bodyLineBudget) {
       lines.push("");
@@ -131,8 +147,8 @@ async function generateExecutiveSummary(recovery, recap, highlights) {
   if (process.env.CLAWVAULT_NO_LLM || process.env.VITEST) return null;
   const apiKey = process.env.GEMINI_API_KEY || process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY;
   if (!apiKey) return null;
-  const redItems = highlights.filter((h) => h.priority === "\u{1F534}").map((h) => h.text).slice(0, 10);
-  const yellowItems = highlights.filter((h) => h.priority === "\u{1F7E1}").map((h) => h.text).slice(0, 5);
+  const structuralItems = highlights.filter((h) => h.importance >= 0.8).map((h) => h.text).slice(0, 10);
+  const potentialItems = highlights.filter((h) => h.importance >= 0.4 && h.importance < 0.8).map((h) => h.text).slice(0, 5);
   const projects = recap.activeProjects.slice(0, 8);
   const commitments = recap.pendingCommitments.slice(0, 5);
   const lastWork = recovery.checkpoint?.workingOn || recap.recentHandoffs[0]?.workingOn?.join(", ") || "";
@@ -149,8 +165,8 @@ async function generateExecutiveSummary(recovery, recap, highlights) {
     `Next steps: ${nextSteps || "(none)"}`,
     `Active projects (${projects.length}): ${projects.join(", ") || "(none)"}`,
     `Pending commitments: ${commitments.join(", ") || "(none)"}`,
-    `Critical observations: ${redItems.join(" | ") || "(none)"}`,
-    `Notable observations: ${yellowItems.join(" | ") || "(none)"}`,
+    `Structural observations: ${structuralItems.join(" | ") || "(none)"}`,
+    `Potential observations: ${potentialItems.join(" | ") || "(none)"}`,
     "",
     "Write the briefing now. Be concise."
   ].join("\n");
@@ -190,7 +206,9 @@ async function wake(options) {
   const highlights = readRecentObservationHighlights(vaultPath);
   const observations = formatRecentObservations(highlights);
   const execSummary = options.noSummary ? null : await generateExecutiveSummary(recovery, recap, highlights);
-  const highlightSummaryItems = highlights.map((item) => `${item.priority} ${item.text}`);
+  const highlightSummaryItems = highlights.map(
+    (item) => `[${item.type}|i=${item.importance.toFixed(2)}] ${item.text}`
+  );
   const wakeSummary = formatSummaryItems(highlightSummaryItems);
   const baseSummary = buildWakeSummary(recovery, recap);
   const fullBaseSummary = wakeSummary ? `${baseSummary} | ${wakeSummary}` : baseSummary;

package/dist/{context-COo8oq1k.d.ts → context-BUGaWpyL.d.ts}

@@ -17,6 +17,7 @@ interface ContextOptions {
     includeObservations?: boolean;
     budget?: number;
     profile?: ContextProfileOption;
+    maxHops?: number;
 }
 interface ContextEntry {
     title: string;

package/dist/index.d.ts

@@ -4,8 +4,14 @@ export { f as DEFAULT_CATEGORIES, g as DEFAULT_CONFIG, h as MEMORY_TYPES, T as T
 export { setupCommand } from './commands/setup.js';
 export { CompatCheck, CompatCommandOptions, CompatReport, CompatStatus, checkOpenClawCompatibility, compatCommand, compatibilityExitCode } from './commands/compat.js';
 export { GraphSummary, graphCommand, graphSummary } from './commands/graph.js';
-export { C as ContextEntry, a as ContextFormat, b as ContextOptions, c as ContextProfile, d as ContextProfileInput, e as ContextProfileOption, f as ContextResult, R as ResolvedContextProfile, g as buildContext, h as contextCommand, i as formatContextMarkdown, j as inferContextProfile, n as normalizeContextProfileInput, r as registerContextCommand, k as resolveContextProfile } from './context-COo8oq1k.js';
+export { C as ContextEntry, a as ContextFormat, b as ContextOptions, c as ContextProfile, d as ContextProfileInput, e as ContextProfileOption, f as ContextResult, R as ResolvedContextProfile, g as buildContext, h as contextCommand, i as formatContextMarkdown, j as inferContextProfile, n as normalizeContextProfileInput, r as registerContextCommand, k as resolveContextProfile } from './context-BUGaWpyL.js';
 export { ObserveCommandOptions, observeCommand, registerObserveCommand } from './commands/observe.js';
+export { ReflectCommandOptions, reflectCommand, registerReflectCommand } from './commands/reflect.js';
+export { ArchiveCommandOptions, archiveCommand, registerArchiveCommand } from './commands/archive.js';
+export { RebuildCommandOptions, rebuildCommand, registerRebuildCommand } from './commands/rebuild.js';
+export { ReplayCommandOptions, registerReplayCommand, replayCommand } from './commands/replay.js';
+export { MigrateObservationsOptions, MigrateObservationsResult, migrateObservations, migrateObservationsCommand, registerMigrateObservationsCommand } from './commands/migrate-observations.js';
+export { SyncBdCommandOptions, registerSyncBdCommand, syncBdCommand } from './commands/sync-bd.js';
 export { SessionRecapFormat, SessionRecapOptions, SessionRecapResult, SessionTurn, buildSessionRecap, formatSessionRecapMarkdown, sessionRecapCommand } from './commands/session-recap.js';
 export { findNearestVaultPath, getVaultPath, resolveVaultPath } from './lib/config.js';
 export { TemplateVariables, buildTemplateVariables, renderTemplate } from './lib/template-engine.js';
@@ -138,6 +144,7 @@ declare class ClawVault {
     private slugify;
     private saveIndex;
     private createTemplates;
+    private createWelcomeNote;
     private syncMemoryGraphIndex;
     private generateReadme;
     private getCategoryDescription;
@@ -337,21 +344,28 @@ interface ObserverOptions {
     compressor?: ObserverCompressor;
     reflector?: ObserverReflector;
     now?: () => Date;
+    rawCapture?: boolean;
+}
+interface ObserverProcessOptions {
+    source?: string;
+    sessionKey?: string;
+    transcriptId?: string;
+    timestamp?: Date;
 }
 declare class Observer {
     private readonly vaultPath;
-    private readonly observationsDir;
     private readonly tokenThreshold;
     private readonly reflectThreshold;
     private readonly compressor;
     private readonly reflector;
     private readonly now;
+    private readonly rawCapture;
     private readonly router;
     private pendingMessages;
     private observationsCache;
     private lastRoutingSummary;
     constructor(vaultPath: string, options?: ObserverOptions);
-    processMessages(messages: string[]): Promise<void>;
+    processMessages(messages: string[], options?: ObserverProcessOptions): Promise<void>;
     /**
      * Force-flush pending messages regardless of threshold.
      * Call this on session end to capture everything.
@@ -362,17 +376,13 @@ declare class Observer {
     }>;
     getObservations(): string;
     private estimateTokens;
-    private getObservationPath;
     private readTodayObservations;
+    private readObservationForDate;
     private readObservationFile;
     private writeObservationFile;
-    private getObservationFiles;
-    private readObservationCorpus;
     private deduplicateObservationMarkdown;
-    private parseSections;
-    private renderSections;
-    private normalizeObservationContent;
-    private reflectIfNeeded;
+    private persistRawMessages;
+    private sanitizeSource;
 }
 
 interface CompressorOptions {
@@ -401,18 +411,14 @@ declare class Compressor {
      * Also fixes trailing word fragments fused after closing brackets.
      */
     private sanitizeWikiLinks;
-    /**
-     * Post-process LLM output to enforce priority rules.
-     * Lines matching critical rules get upgraded to 🔴, notable rules to 🟡.
-     */
-    private enforcePriorityRules;
+    private enforceImportanceRules;
+    private enforceImportanceForRecord;
     private fallbackCompression;
     private mergeObservations;
-    private deduplicateObservationLines;
-    private normalizeObservationContent;
-    private parseSections;
+    private mergeRecord;
     private renderSections;
-    private inferPriority;
+    private inferImportance;
+    private inferConfidence;
     private isCriticalContent;
     private isNotableContent;
     private normalizeText;
@@ -420,6 +426,7 @@ declare class Compressor {
     private extractTime;
     private formatDate;
     private formatTime;
+    private clamp01;
 }
 
 interface ReflectorOptions {
@@ -466,6 +473,35 @@ declare class SessionWatcher {
 
 declare function parseSessionFile(filePath: string): string[];
 
+interface ArchiveObservationsOptions {
+    olderThanDays?: number;
+    dryRun?: boolean;
+    now?: () => Date;
+}
+interface ArchiveObservationsResult {
+    scanned: number;
+    archived: number;
+    skipped: number;
+    dryRun: boolean;
+    archivedDates: string[];
+}
+declare function archiveObservations(vaultPath: string, options?: ArchiveObservationsOptions): ArchiveObservationsResult;
+
+interface ReflectOptions {
+    vaultPath: string;
+    days?: number;
+    dryRun?: boolean;
+    now?: () => Date;
+}
+interface ReflectResult {
+    processedWeeks: number;
+    writtenWeeks: number;
+    dryRun: boolean;
+    files: string[];
+    archive: ArchiveObservationsResult | null;
+}
+declare function runReflection(options: ReflectOptions): Promise<ReflectResult>;
+
 /**
  * ClawVault 🐘 — An Elephant Never Forgets
  *
@@ -495,4 +531,4 @@ declare function parseSessionFile(filePath: string): string[];
 declare const VERSION: string;
 declare function registerCommanderCommands(program: Command): Command;
 
-export { Category, ClawVault, Compressor, type CompressorOptions, Document, HandoffDocument, MEMORY_GRAPH_SCHEMA_VERSION, type MemoryGraph, type MemoryGraphEdge, type MemoryGraphEdgeType, type MemoryGraphIndex, type MemoryGraphNode, type MemoryGraphNodeType, type MemoryGraphStats, MemoryType, Observer, type ObserverCompressor, type ObserverOptions, type ObserverReflector, QMD_INSTALL_COMMAND, QMD_INSTALL_URL, QmdUnavailableError, Reflector, type ReflectorOptions, SearchEngine, SearchOptions, SearchResult, SessionRecap, SessionWatcher, type SessionWatcherOptions, StoreOptions, SyncOptions, SyncResult, VERSION, VaultConfig, buildOrUpdateMemoryGraphIndex, createVault, extractTags, extractWikiLinks, findVault, getMemoryGraph, hasQmd, loadMemoryGraphIndex, parseSessionFile, qmdEmbed, qmdUpdate, registerCommanderCommands };
+export { type ArchiveObservationsOptions, type ArchiveObservationsResult, Category, ClawVault, Compressor, type CompressorOptions, Document, HandoffDocument, MEMORY_GRAPH_SCHEMA_VERSION, type MemoryGraph, type MemoryGraphEdge, type MemoryGraphEdgeType, type MemoryGraphIndex, type MemoryGraphNode, type MemoryGraphNodeType, type MemoryGraphStats, MemoryType, Observer, type ObserverCompressor, type ObserverOptions, type ObserverReflector, QMD_INSTALL_COMMAND, QMD_INSTALL_URL, QmdUnavailableError, type ReflectOptions, type ReflectResult, Reflector, type ReflectorOptions, SearchEngine, SearchOptions, SearchResult, SessionRecap, SessionWatcher, type SessionWatcherOptions, StoreOptions, SyncOptions, SyncResult, VERSION, VaultConfig, archiveObservations, buildOrUpdateMemoryGraphIndex, createVault, extractTags, extractWikiLinks, findVault, getMemoryGraph, hasQmd, loadMemoryGraphIndex, parseSessionFile, qmdEmbed, qmdUpdate, registerCommanderCommands, runReflection };

package/dist/index.js

@@ -1,27 +1,60 @@
+import {
+  buildSessionRecap,
+  formatSessionRecapMarkdown,
+  sessionRecapCommand
+} from "./chunk-ZKGY7WTT.js";
+import {
+  setupCommand
+} from "./chunk-W463YRED.js";
+import {
+  registerSyncBdCommand,
+  syncBdCommand
+} from "./chunk-MGDEINGP.js";
 import {
   buildTemplateVariables,
   renderTemplate
 } from "./chunk-7766SIJP.js";
+import {
+  migrateObservations,
+  migrateObservationsCommand,
+  registerMigrateObservationsCommand
+} from "./chunk-WZI3OAE5.js";
 import {
   SessionWatcher,
   observeCommand,
   registerObserveCommand
-} from "./chunk-FEQ2CQ3Y.js";
+} from "./chunk-LB6P4CD5.js";
 import {
-  buildSessionRecap,
-  formatSessionRecapMarkdown,
-  sessionRecapCommand
-} from "./chunk-ZKGY7WTT.js";
+  parseSessionFile
+} from "./chunk-P5EPF6MB.js";
+import {
+  rebuildCommand,
+  registerRebuildCommand
+} from "./chunk-73P7XCQM.js";
+import {
+  reflectCommand,
+  registerReflectCommand
+} from "./chunk-GJEGPO7U.js";
 import "./chunk-HRLWZGMA.js";
 import {
-  setupCommand
-} from "./chunk-PIJGYMQZ.js";
+  registerReplayCommand,
+  replayCommand
+} from "./chunk-L6NB43WV.js";
 import {
   Compressor,
   Observer,
-  Reflector,
-  parseSessionFile
-} from "./chunk-5MQB7B37.js";
+  Reflector
+} from "./chunk-2HM7ZI4X.js";
+import {
+  runReflection
+} from "./chunk-GQVYQCY5.js";
+import {
+  archiveCommand,
+  registerArchiveCommand
+} from "./chunk-VR5NE7PZ.js";
+import {
+  archiveObservations
+} from "./chunk-MQUJNOHK.js";
 import {
   buildContext,
   contextCommand,
@@ -30,7 +63,9 @@ import {
   normalizeContextProfileInput,
   registerContextCommand,
   resolveContextProfile
-} from "./chunk-TBVI4N53.js";
+} from "./chunk-I5X6J4FX.js";
+import "./chunk-K6XHCUFL.js";
+import "./chunk-Z2XBWN7A.js";
 import {
   checkOpenClawCompatibility,
   compatCommand,
@@ -40,7 +75,7 @@ import {
   ClawVault,
   createVault,
   findVault
-} from "./chunk-QFBKWDYR.js";
+} from "./chunk-OTQW3OMC.js";
 import {
   DEFAULT_CATEGORIES,
   DEFAULT_CONFIG,
@@ -55,17 +90,17 @@ import {
   hasQmd,
   qmdEmbed,
   qmdUpdate
-} from "./chunk-MIIXBNO3.js";
+} from "./chunk-FDJIZKCW.js";
 import {
   graphCommand,
   graphSummary
-} from "./chunk-TXO34J3O.js";
+} from "./chunk-H7JW4L7H.js";
 import {
   MEMORY_GRAPH_SCHEMA_VERSION,
   buildOrUpdateMemoryGraphIndex,
   getMemoryGraph,
   loadMemoryGraphIndex
-} from "./chunk-O5V7SD5C.js";
+} from "./chunk-ZZA73MFY.js";
 import {
   findNearestVaultPath,
   getVaultPath,
@@ -87,6 +122,7 @@ var VERSION = readPackageVersion();
 function registerCommanderCommands(program) {
   registerContextCommand(program);
   registerObserveCommand(program);
+  registerReflectCommand(program);
   return program;
 }
 export {
@@ -105,6 +141,8 @@ export {
   SessionWatcher,
   TYPE_TO_CATEGORY,
   VERSION,
+  archiveCommand,
+  archiveObservations,
   buildContext,
   buildOrUpdateMemoryGraphIndex,
   buildSessionRecap,
@@ -127,17 +165,30 @@ export {
   hasQmd,
   inferContextProfile,
   loadMemoryGraphIndex,
+  migrateObservations,
+  migrateObservationsCommand,
   normalizeContextProfileInput,
   observeCommand,
   parseSessionFile,
   qmdEmbed,
   qmdUpdate,
+  rebuildCommand,
+  reflectCommand,
+  registerArchiveCommand,
   registerCommanderCommands,
   registerContextCommand,
+  registerMigrateObservationsCommand,
   registerObserveCommand,
+  registerRebuildCommand,
+  registerReflectCommand,
+  registerReplayCommand,
+  registerSyncBdCommand,
   renderTemplate,
+  replayCommand,
   resolveContextProfile,
   resolveVaultPath,
+  runReflection,
   sessionRecapCommand,
-  setupCommand
+  setupCommand,
+  syncBdCommand
 };

package/hooks/clawvault/HOOK.md

@@ -4,7 +4,7 @@ description: "Context resilience - recovery detection, auto-checkpoint, and sess
 metadata:
   openclaw:
     emoji: "🐘"
-    events: ["gateway:startup", "gateway:heartbeat", "command:new", "session:start", "compaction:memoryFlush"]
+    events: ["gateway:startup", "gateway:heartbeat", "command:new", "session:start", "compaction:memoryFlush", "cron.weekly"]
     requires:
       bins: ["clawvault"]
 ---
@@ -18,6 +18,7 @@ Integrates ClawVault's context death resilience into OpenClaw:
 - **On /new command**: Auto-checkpoints before session reset
 - **On context compaction**: Forces incremental observation flush before context is lost
 - **On session start**: Injects relevant vault context for the initial prompt
+- **On weekly cron**: Runs `clawvault reflect` every Sunday midnight (UTC)
 
 ## Installation
 
@@ -63,7 +64,7 @@ Injection format:
 
 ### Event Compatibility
 
-The hook accepts canonical OpenClaw events (`gateway:startup`, `gateway:heartbeat`, `command:new`, `session:start`, `compaction:memoryFlush`) and tolerates alias payload shapes (`event`, `eventName`, `name`, `hook`, `trigger`) to remain robust across runtime wrappers.
+The hook accepts canonical OpenClaw events (`gateway:startup`, `gateway:heartbeat`, `command:new`, `session:start`, `compaction:memoryFlush`, `cron.weekly`) and tolerates alias payload shapes (`event`, `eventName`, `name`, `hook`, `trigger`) to remain robust across runtime wrappers.
 
 ## No Configuration Needed
 

package/hooks/clawvault/handler.js

@@ -544,6 +544,49 @@ function runActiveObservation(vaultPath, agentId, options = {}) {
   return true;
 }
 
+function extractEventTimestamp(event) {
+  const candidates = [
+    event?.timestamp,
+    event?.scheduledAt,
+    event?.time,
+    event?.context?.timestamp,
+    event?.context?.scheduledAt
+  ];
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    const parsed = new Date(candidate);
+    if (!Number.isNaN(parsed.getTime())) {
+      return parsed;
+    }
+  }
+  return null;
+}
+
+function isSundayMidnightUtc(date) {
+  return date.getUTCDay() === 0 && date.getUTCHours() === 0 && date.getUTCMinutes() === 0;
+}
+
+async function handleWeeklyReflect(event) {
+  const vaultPath = findVaultPath();
+  if (!vaultPath) {
+    console.log('[clawvault] No vault found, skipping weekly reflection');
+    return;
+  }
+
+  const timestamp = extractEventTimestamp(event) || new Date();
+  if (!isSundayMidnightUtc(timestamp)) {
+    console.log('[clawvault] Weekly reflect skipped (not Sunday midnight UTC)');
+    return;
+  }
+
+  const result = runClawvault(['reflect', '-v', vaultPath], { timeoutMs: 120000 });
+  if (!result.success) {
+    console.warn('[clawvault] Weekly reflection failed');
+    return;
+  }
+  console.log('[clawvault] Weekly reflection complete');
+}
+
 // Handle gateway startup - check for context death
 async function handleStartup(event) {
   const vaultPath = findVaultPath();
@@ -724,6 +767,14 @@ const handler = async (event) => {
       return;
     }
 
+    if (
+      eventMatches(event, 'cron', 'weekly')
+      || eventIncludesToken(event, 'cron:weekly')
+    ) {
+      await handleWeeklyReflect(event);
+      return;
+    }
+
     if (
       eventMatches(event, 'gateway', 'heartbeat')
       || eventMatches(event, 'session', 'heartbeat')

package/hooks/clawvault/handler.test.js

@@ -240,4 +240,24 @@ describe('clawvault hook handler', () => {
 
     fs.rmSync(vaultPath, { recursive: true, force: true });
   });
+
+  it('runs weekly reflection on cron.weekly at Sunday midnight', async () => {
+    const vaultPath = makeVaultFixture();
+    process.env.CLAWVAULT_PATH = vaultPath;
+    execFileSyncMock.mockReturnValue('');
+
+    const handler = await loadHandler();
+    await handler({
+      eventName: 'cron.weekly',
+      timestamp: '2026-02-15T00:00:00.000Z'
+    });
+
+    expect(execFileSyncMock).toHaveBeenCalledWith(
+      'clawvault',
+      expect.arrayContaining(['reflect', '-v', vaultPath]),
+      expect.objectContaining({ shell: false })
+    );
+
+    fs.rmSync(vaultPath, { recursive: true, force: true });
+  });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawvault",
-  "version": "2.1.2",
+  "version": "2.2.1",
   "description": "ClawVault™ - 🐘 An elephant never forgets. Structured memory for OpenClaw agents. Context death resilience, Obsidian-compatible markdown, local semantic search.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -29,7 +29,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/observe.ts src/commands/session-recap.ts src/commands/wake.ts src/commands/sleep.ts src/commands/doctor.ts src/commands/compat.ts src/commands/graph.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/observe.ts src/commands/reflect.ts src/commands/archive.ts src/commands/rebuild.ts src/commands/replay.ts src/commands/migrate-observations.ts src/commands/sync-bd.ts src/commands/session-recap.ts src/commands/wake.ts src/commands/sleep.ts src/commands/doctor.ts src/commands/compat.ts src/commands/graph.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",