clawvault 3.1.0 → 3.2.0

package/dist/index.d.ts

@@ -1,27 +1,34 @@
 import { Command } from 'commander';
-import { V as VaultConfig, S as StoreOptions, D as Document, a as SearchOptions, b as SearchResult, c as SyncOptions, d as SyncResult, C as Category, M as MemoryType, H as HandoffDocument, e as SessionRecap, E as ExtractedDate, f as ExtractedPreference } from './types-Y2_Um2Ls.js';
-export { g as DEFAULT_CATEGORIES, h as DEFAULT_CONFIG, i as MEMORY_TYPES, T as TYPE_TO_CATEGORY, j as VaultMeta } from './types-Y2_Um2Ls.js';
+import { V as VaultConfig, a as StoreOptions, D as Document, b as SearchOptions, c as SearchResult, d as SyncOptions, e as SyncResult, C as Category, M as MemoryType, H as HandoffDocument, S as SessionRecap } from './types-BbWJoC1c.js';
+export { f as DEFAULT_CATEGORIES, g as DEFAULT_CONFIG, h as MEMORY_TYPES, T as TYPE_TO_CATEGORY, i as VaultMeta } from './types-BbWJoC1c.js';
 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 { KanbanGroupBy, KanbanImportChange, KanbanImportOptions, KanbanImportResult, KanbanLane, KanbanSyncOptions, KanbanSyncResult, ParsedKanbanBoard, ParsedKanbanLane, buildKanbanLanes, extractCardSlug, formatKanbanCard, generateKanbanMarkdown, importKanbanBoard, kanbanCommand, parseKanbanMarkdown, syncKanbanBoard } from './commands/kanban.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 { I as InjectCommandOptions, a as InjectFormat, b as InjectMatch, c as InjectMatchReason, d as InjectMatchSource, e as InjectResult, f as InjectRuntimeOptions, g as InjectSourceCategory, h as InjectableItem, L as LlmCompletionOptions, i as LlmProvider, M as MEMORY_GRAPH_SCHEMA_VERSION, j as MemoryGraph, k as MemoryGraphEdge, l as MemoryGraphEdgeType, m as MemoryGraphIndex, n as MemoryGraphNode, o as MemoryGraphNodeType, p as MemoryGraphStats, q as buildInjectionResult, r as buildOrUpdateMemoryGraphIndex, s as deterministicInjectMatches, t as getMemoryGraph, u as indexInjectableItems, v as injectCommand, w as loadMemoryGraphIndex, x as registerInjectCommand, y as requestLlmCompletion, z as resolveLlmProvider, A as runPromptInjection } from './inject-Bzi5E-By.js';
+import { L as LlmProvider } from './inject-DYUrDqQO.js';
+export { I as InjectCommandOptions, a as InjectFormat, b as InjectMatch, c as InjectMatchReason, d as InjectMatchSource, e as InjectResult, f as InjectRuntimeOptions, g as InjectSourceCategory, h as InjectableItem, i as LlmCompletionOptions, M as MEMORY_GRAPH_SCHEMA_VERSION, j as MemoryGraph, k as MemoryGraphEdge, l as MemoryGraphEdgeType, m as MemoryGraphIndex, n as MemoryGraphNode, o as MemoryGraphNodeType, p as MemoryGraphStats, q as buildInjectionResult, r as buildOrUpdateMemoryGraphIndex, s as deterministicInjectMatches, t as getMemoryGraph, u as indexInjectableItems, v as injectCommand, w as loadMemoryGraphIndex, x as registerInjectCommand, y as requestLlmCompletion, z as resolveLlmProvider, A as runPromptInjection } from './inject-DYUrDqQO.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 { DoctorCheck, DoctorReport, DoctorStatus, doctor } from './commands/doctor.js';
+import { MigrationIssueType } from './commands/doctor.js';
+export { DoctorCheck, DoctorReport, DoctorStatus, MigrationIssue, doctor } from './commands/doctor.js';
 export { EmbedCommandOptions, EmbedCommandResult, embedCommand, registerEmbedCommand } from './commands/embed.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 { registerCliCommands } from './cli/index.js';
 import { TaskStatus } from './lib/task-utils.js';
 export { completeTask, listDependentTasks, listSubtasks, updateTask } from './lib/task-utils.js';
+export { CLAWVAULT_SERVE_PATH, DEFAULT_SERVE_PORT, ServeInstance, TailscalePeer, TailscaleServeConfig, TailscaleStatus, TailscaleSyncOptions, TailscaleSyncResult, VaultFileEntry, VaultManifest, checkPeerClawVault, compareManifests, configureTailscaleServe, discoverClawVaultPeers, fetchRemoteFile, fetchRemoteManifest, findPeer, generateVaultManifest, getOnlinePeers, getTailscaleStatus, getTailscaleVersion, hasTailscale, pushFileToRemote, resolvePeerIP, serveVault, stopTailscaleServe, syncWithPeer } from './lib/tailscale.js';
+export { TailscaleDiscoverCommandOptions, TailscaleServeCommandOptions, TailscaleStatusCommandOptions, TailscaleSyncCommandOptions, registerTailscaleCommands, registerTailscaleDiscoverCommand, registerTailscaleServeCommand, registerTailscaleStatusCommand, registerTailscaleSyncCommand, tailscaleDiscoverCommand, tailscaleServeCommand, tailscaleStatusCommand, tailscaleSyncCommand } from './commands/tailscale.js';
 export { TemplateVariables, buildTemplateVariables, renderTemplate } from './lib/template-engine.js';
 export { Project, ProjectFrontmatter, ProjectStatus, archiveProject, createProject, getProjectActivity, getProjectTasks, listProjects, readProject, updateProject } from './lib/project-utils.js';
+import 'child_process';
+import 'http';
 
 /**
  * ClawVault - The elephant's memory
@@ -152,6 +159,16 @@ declare class ClawVault {
      * Parse a handoff document back into structured form
      */
     private parseHandoff;
+    /**
+     * Safely convert a date value to ISO string format.
+     * Handles Date objects, strings, and undefined values.
+     */
+    private toDateString;
+    /**
+     * Extract the date portion (YYYY-MM-DD) from an ISO date string or Date object.
+     * Provides safe handling for various date formats.
+     */
+    private extractDatePart;
     private applyQmdConfig;
     private slugify;
     private saveIndex;
@@ -174,137 +191,52 @@ declare function createVault(vaultPath: string, options?: Partial<VaultConfig>,
     skipGraph?: boolean;
 }): Promise<ClawVault>;
 
-interface ReweaveCommandOptions {
+interface MigrateCommandOptions {
     vaultPath?: string;
-    since?: string;
     dryRun?: boolean;
-    threshold?: number;
+    force?: boolean;
+    json?: boolean;
 }
-declare function reweaveCommand(options: ReweaveCommandOptions): Promise<void>;
-declare function registerReweaveCommand(program: Command): void;
-
-declare const OBSERVATION_TYPES: readonly ["decision", "preference", "fact", "commitment", "task", "todo", "commitment-unresolved", "milestone", "lesson", "relationship", "project"];
-type ObservationType = typeof OBSERVATION_TYPES[number];
-type LegacyObservationPriority = '🔴' | '🟡' | '🟢';
-type ObservationLineKind = 'scored' | 'emoji';
-interface ParsedObservationRecord {
-    date: string;
-    type: ObservationType;
-    confidence: number;
-    importance: number;
-    content: string;
-    format: ObservationLineKind;
-    priority?: LegacyObservationPriority;
-    time?: string;
-    rawLine: string;
-}
-
-/**
- * Reweave — Backward memory consolidation for ClawVault
- *
- * When new observations are written, reweave performs a backward pass over
- * existing observations to detect knowledge updates (same entity, new value).
- * Older observations are marked as superseded so search always returns the
- * latest version of a fact.
- *
- * Design inspired by Ars Contexta's "notes are hypotheses" philosophy —
- * every observation is a claim that can be superseded by newer evidence.
- */
-
-interface SupersessionRecord {
-    /** The older observation that was superseded */
-    oldObservation: ParsedObservationRecord;
-    /** The newer observation that supersedes it */
-    newObservation: ParsedObservationRecord;
-    /** File path of the older observation */
-    oldFile: string;
-    /** File path of the newer observation */
-    newFile: string;
-    /** Reason for supersession */
-    reason: string;
-    /** Timestamp of detection */
-    detectedAt: string;
-}
-interface ReweaveResult {
-    /** Number of observation files scanned */
-    filesScanned: number;
-    /** Number of individual observations checked */
-    observationsChecked: number;
-    /** Supersession records found/applied */
-    supersessions: SupersessionRecord[];
-    /** Whether this was a dry run */
-    dryRun: boolean;
+interface MigrationAction {
+    type: MigrationIssueType;
+    description: string;
+    success: boolean;
+    error?: string;
 }
-interface ReweaveOptions {
+interface MigrateResult {
     vaultPath: string;
-    /** Only process observations since this date (YYYY-MM-DD) */
-    since?: string;
-    /** Dry run — report but don't write */
-    dryRun?: boolean;
-    /** Similarity threshold for entity matching (0-1). Default 0.6 */
-    similarityThreshold?: number;
+    issuesFound: number;
+    issuesFixed: number;
+    actions: MigrationAction[];
+    dryRun: boolean;
 }
-declare function isSuperseded(line: string): boolean;
-declare function getSupersessionInfo(line: string): {
-    supersededBy: string;
-    detectedAt: string;
-} | null;
-/**
- * Extract key entities/subjects from an observation for matching.
- * Returns normalized tokens that represent the "what" of the observation.
- */
-declare function extractEntities(content: string): string[];
-/**
- * Compute similarity between two observations based on entity overlap.
- * Returns 0-1 where 1 = identical entities.
- */
-declare function entitySimilarity(a: string[], b: string[]): number;
-/**
- * Check if two observations represent a knowledge update.
- * Both must be about the same entity/subject but with different values.
- *
- * Heuristic: high entity overlap + different observation content = update.
- * Same content = duplicate, not update.
- */
-declare function isKnowledgeUpdate(older: ParsedObservationRecord, newer: ParsedObservationRecord, threshold?: number): {
-    isUpdate: boolean;
-    reason: string;
-};
-/**
- * Run backward consolidation across observations.
- *
- * For each newer observation, check all older observations for knowledge updates.
- * When found, mark the older one as superseded.
- */
-declare function reweave(options: ReweaveOptions): ReweaveResult;
-/**
- * Filter search results to prefer latest versions of superseded observations.
- * When multiple observations cover the same entity, only keep the newest.
- *
- * This is called from the search pipeline to boost knowledge update accuracy.
- */
-declare function filterSuperseded(lines: string[]): string[];
-/**
- * Given observation markdown content, return only non-superseded lines.
- * Preserves date headings and structure.
- */
-declare function stripSupersededObservations(markdown: string): string;
+declare function migrate(options?: MigrateCommandOptions): Promise<MigrateResult>;
+declare function migrateCommand(options?: MigrateCommandOptions): Promise<MigrateResult>;
+declare function registerMigrateCommand(program: Command): void;
 
 /**
  * ClawVault Search Engine - qmd Backend
  * Uses qmd CLI for BM25 and vector search
- *
- * v2.7.0 enhancements:
- *   1. Chunk-level BM25 pre-filtering (from eval v4 adapter)
- *   2. Exhaustive threshold-based retrieval (from eval v6 adapter)
- *   3. Preference extraction pipeline (from eval v3 adapter)
- *   4. Temporal date indexing at ingest time (from eval v8 design)
  */
 
 declare const QMD_INSTALL_URL = "https://github.com/tobi/qmd";
 declare const QMD_INSTALL_COMMAND = "bun install -g github:tobi/qmd";
+type QmdErrorCode = 'NOT_INSTALLED' | 'NOT_CONFIGURED' | 'COLLECTION_NOT_FOUND' | 'EXECUTION_FAILED';
+interface QmdErrorDetails {
+    code: QmdErrorCode;
+    message: string;
+    hint: string;
+}
 declare class QmdUnavailableError extends Error {
-    constructor(message?: string);
+    readonly code: QmdErrorCode;
+    readonly hint: string;
+    constructor(code?: QmdErrorCode, additionalContext?: string);
+    toUserMessage(): string;
+}
+declare function getQmdErrorDetails(code: QmdErrorCode): QmdErrorDetails;
+declare class QmdConfigurationError extends Error {
+    readonly hint?: string | undefined;
+    constructor(message: string, hint?: string | undefined);
 }
 /**
  * Check if qmd is available
@@ -318,31 +250,6 @@ declare function qmdUpdate(collection?: string, indexName?: string): void;
  * Trigger qmd embed (create/update vector embeddings)
  */
 declare function qmdEmbed(collection?: string, indexName?: string): void;
-/**
- * Split text into ~maxChars sentence-aligned chunks with overlap.
- */
-declare function sentenceChunk(text: string, maxChars?: number, overlapSentences?: number): string[];
-/**
- * BM25-rank chunks within a document by keyword overlap.
- * Returns the top `max` chunks sorted by relevance, always including the
- * first chunk (session context) when available.
- */
-declare function bm25RankChunks(chunks: string[], terms: string[], max?: number): {
-    text: string;
-    score: number;
-}[];
-/**
- * Extract all date references from text content. Designed to run at ingest
- * time so temporal queries can use structured dates + JS arithmetic instead
- * of relying on LLM date math at query time.
- */
-declare function extractDates(text: string, sessionDateStr?: string): ExtractedDate[];
-/**
- * Extract user preferences from conversation text. Runs at ingest time to
- * build a structured preference index for personalised recommendations.
- */
-declare function extractPreferences(text: string, documentId?: string): ExtractedPreference[];
-declare function classifyQuestion(q: string): 'preference' | 'temporal' | 'aggregation' | 'default';
 /**
  * QMD Search Engine - wraps qmd CLI
  */
@@ -352,16 +259,14 @@ declare class SearchEngine {
     private vaultPath;
     private collectionRoot;
     private qmdIndexName?;
-    /** v2.7 — Per-document date index built at ingest time */
-    private dateIndex;
-    /** v2.7 — Per-document preference index built at ingest time */
-    private preferenceIndex;
-    /** v2.7 — Per-document chunk cache for BM25 pre-filtering */
-    private chunkCache;
     /**
      * Set the collection name (usually vault name)
      */
     setCollection(name: string): void;
+    /**
+     * Get the current collection name
+     */
+    getCollection(): string;
     /**
      * Set the vault path for file resolution
      */
@@ -375,8 +280,7 @@ declare class SearchEngine {
      */
     setIndexName(indexName?: string): void;
     /**
-     * Add or update a document in the local cache.
-     * v2.7: also extracts dates, preferences, and chunks at ingest time.
+     * Add or update a document in the local cache
      * Note: qmd indexing happens via qmd update command
      */
     addDocument(doc: Document): void;
@@ -401,32 +305,6 @@ declare class SearchEngine {
      */
     query(query: string, options?: SearchOptions): SearchResult[];
     private runQmdQuery;
-    /**
-     * v2.7 — Chunk-level BM25 pre-filtered search. Ranks chunks within each
-     * document by keyword relevance before semantic ranking, so relevant
-     * content deep in long documents isn't missed.
-     *
-     * Returns results with snippets from the best-matching chunks.
-     */
-    chunkPrefilterSearch(query: string, options?: SearchOptions): SearchResult[];
-    /**
-     * v2.7 — Exhaustive threshold-based search for aggregation queries.
-     * Keeps pulling results until relevance drops below threshold.
-     */
-    exhaustiveSearch(query: string, threshold?: number, maxResults?: number): SearchResult[];
-    /**
-     * v2.7 — Get all extracted dates, optionally filtered by document ids.
-     */
-    getDates(documentIds?: string[]): ExtractedDate[];
-    /**
-     * v2.7 — Get all extracted preferences, optionally filtered by document ids.
-     */
-    getPreferences(documentIds?: string[]): ExtractedPreference[];
-    /**
-     * v2.7 — Search with automatic strategy selection based on question type.
-     * Classifies the query and routes to the appropriate pipeline.
-     */
-    smartQuery(query: string, options?: SearchOptions): SearchResult[];
     /**
      * Convert qmd results to ClawVault SearchResult format
      */
@@ -437,11 +315,6 @@ declare class SearchEngine {
      * Convert qmd:// URI to file path
      */
     private qmdUriToPath;
-    /**
-     * v2.8 — Filter superseded observation lines from snippet text.
-     * Ensures search results prefer the latest version of knowledge.
-     */
-    private stripSupersededFromSnippet;
     /**
      * Clean up qmd snippet format
      */
@@ -455,7 +328,7 @@ declare class SearchEngine {
      */
     get size(): number;
     /**
-     * Clear the local document cache and all v2.7 indices
+     * Clear the local document cache
      */
     clear(): void;
     /**
@@ -480,15 +353,93 @@ declare function extractWikiLinks(content: string): string[];
  */
 declare function extractTags(content: string): string[];
 
-declare const OBSERVE_PROVIDERS: readonly ["anthropic", "openai", "gemini"];
-declare const OBSERVER_COMPRESSION_PROVIDERS: readonly ["anthropic", "openai", "gemini", "openai-compatible", "ollama"];
+/**
+ * ClawVault Hybrid Search — BM25 + Semantic Embeddings + RRF
+ *
+ * Proven in LongMemEval benchmarks:
+ * - v28 pipeline: 57.0% overall (up from 52.6% with BM25-only)
+ * - Multi-session: 45.9% (up from 28.6%)
+ * - Single-session-user: 85.7% (up from 72.9%)
+ *
+ * Architecture:
+ * 1. BM25 via existing qmd search
+ * 2. Semantic via @huggingface/transformers (all-MiniLM-L6-v2)
+ * 3. Reciprocal Rank Fusion (k=60)
+ */
+
+/**
+ * Compute embedding for a text string
+ */
+declare function embed(text: string): Promise<Float32Array>;
+/**
+ * Compute embeddings for multiple texts
+ */
+declare function embedBatch(texts: string[]): Promise<Float32Array[]>;
+/**
+ * Cosine similarity between two normalized vectors
+ */
+declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+/**
+ * Embedding cache — stores embeddings on disk alongside vault files
+ */
+declare class EmbeddingCache {
+    private cachePath;
+    private cache;
+    private dirty;
+    constructor(vaultPath: string);
+    /**
+     * Load cache from disk
+     */
+    load(): void;
+    /**
+     * Save cache to disk
+     */
+    save(): void;
+    get(key: string): Float32Array | undefined;
+    set(key: string, embedding: Float32Array): void;
+    has(key: string): boolean;
+    entries(): IterableIterator<[string, Float32Array]>;
+    get size(): number;
+}
+/**
+ * Reciprocal Rank Fusion of two ranked lists
+ */
+declare function reciprocalRankFusion(list1: {
+    id: string;
+    score: number;
+}[], list2: {
+    id: string;
+    score: number;
+}[], k?: number): {
+    id: string;
+    score: number;
+}[];
+/**
+ * Semantic search against embedding cache
+ */
+declare function semanticSearch(query: string, cache: EmbeddingCache, topK?: number): Promise<{
+    id: string;
+    score: number;
+}[]>;
+/**
+ * Hybrid search: combines BM25 results with semantic results via RRF
+ */
+declare function hybridSearch(query: string, bm25Results: SearchResult[], cache: EmbeddingCache, options?: {
+    topK?: number;
+    rrfK?: number;
+}): Promise<SearchResult[]>;
+
+declare const OBSERVE_PROVIDERS: readonly ["anthropic", "openai", "gemini", "xai", "openclaw"];
+declare const OBSERVER_COMPRESSION_PROVIDERS: readonly ["anthropic", "openai", "gemini", "xai", "openai-compatible", "ollama", "openclaw", "minimax", "zai"];
 declare const THEMES: readonly ["neural", "minimal", "none"];
 declare const CONTEXT_PROFILES: readonly ["default", "planning", "incident", "handoff", "auto"];
+declare const FACT_EXTRACTION_MODES: readonly ["off", "rule", "llm", "hybrid"];
 type ObserveProvider = (typeof OBSERVE_PROVIDERS)[number];
 type ObserverCompressionProvider = (typeof OBSERVER_COMPRESSION_PROVIDERS)[number];
 type Theme = (typeof THEMES)[number];
 type ContextProfile = (typeof CONTEXT_PROFILES)[number];
-type ManagedConfigKey = 'name' | 'categories' | 'theme' | 'observe.model' | 'observe.provider' | 'observer.compression.provider' | 'observer.compression.model' | 'observer.compression.baseUrl' | 'observer.compression.apiKey' | 'context.maxResults' | 'context.defaultProfile' | 'graph.maxHops' | 'inject.maxResults' | 'inject.useLlm' | 'inject.scope';
+type FactExtractionMode$1 = (typeof FACT_EXTRACTION_MODES)[number];
+type ManagedConfigKey = 'name' | 'categories' | 'theme' | 'observe.model' | 'observe.provider' | 'observer.compression.provider' | 'observer.compression.model' | 'observer.compression.baseUrl' | 'observer.compression.apiKey' | 'observer.factExtractionMode' | 'context.maxResults' | 'context.defaultProfile' | 'graph.maxHops' | 'inject.maxResults' | 'inject.useLlm' | 'inject.scope';
 interface RouteRule {
     pattern: string;
     target: string;
@@ -509,6 +460,198 @@ declare function removeRouteRule(vaultPath: string, pattern: string): boolean;
 declare function matchRouteRule(text: string, routes: RouteRule[]): RouteRule | null;
 declare function testRouteRule(vaultPath: string, text: string): RouteRule | null;
 
+/**
+ * LLM Adapter for fact extraction.
+ *
+ * Provides a unified interface for calling LLMs to extract facts from text.
+ * Currently supports Gemini Flash as the primary adapter, with fallback to
+ * the existing LLM provider infrastructure.
+ */
+
+type FactExtractionMode = 'off' | 'rule' | 'llm' | 'hybrid';
+interface LlmAdapterOptions {
+    provider?: LlmProvider | null;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    fetchImpl?: typeof fetch;
+}
+interface LlmAdapter {
+    /**
+     * Call the LLM with a prompt and return the response text.
+     */
+    call(prompt: string): Promise<string>;
+    /**
+     * Check if the adapter is available (has valid credentials).
+     */
+    isAvailable(): boolean;
+    /**
+     * Get the provider name for this adapter.
+     */
+    getProvider(): LlmProvider | null;
+}
+/**
+ * Create a Gemini Flash adapter for fact extraction.
+ * Uses the Gemini API with the flash model optimized for speed.
+ */
+declare function createGeminiFlashAdapter(options?: LlmAdapterOptions): LlmAdapter;
+/**
+ * Create an LLM adapter using the default provider resolution.
+ * Falls back through providers: openclaw -> anthropic -> openai -> gemini -> xai
+ */
+declare function createDefaultAdapter(options?: LlmAdapterOptions): LlmAdapter;
+/**
+ * Create an LLM adapter for fact extraction based on configuration.
+ *
+ * Priority:
+ * 1. If provider is explicitly specified, use that
+ * 2. If Gemini API key is available, prefer Gemini Flash for speed
+ * 3. If Ollama is running locally, use Ollama (free, always available)
+ * 4. Fall back to default provider resolution
+ */
+declare function createFactExtractionAdapter(options?: LlmAdapterOptions): LlmAdapter;
+/**
+ * Create an LLM function compatible with extractFactsLlm.
+ * This wraps the adapter into the function signature expected by fact-extractor.ts.
+ */
+declare function createLlmFunction(adapter: LlmAdapter): ((prompt: string) => Promise<string>) | undefined;
+/**
+ * Resolve the effective fact extraction mode based on configuration and availability.
+ *
+ * - 'off': Never extract facts
+ * - 'rule': Only use rule-based extraction (no LLM)
+ * - 'llm': Prefer LLM extraction, fall back to rules if LLM unavailable
+ * - 'hybrid': Use both LLM and rules, merge results (future enhancement)
+ */
+declare function resolveFactExtractionMode(configuredMode: FactExtractionMode | undefined, adapter?: LlmAdapter): {
+    mode: FactExtractionMode;
+    useLlm: boolean;
+};
+
+/**
+ * Write-time fact extraction for ClawVault v3.
+ *
+ * When a memory is stored, this module extracts structured facts:
+ *   (entity, relation, value, timestamp, confidence)
+ *
+ * Two modes:
+ *   1. LLM extraction (accurate but requires API key)
+ *   2. Rule-based extraction (fast, no deps, lower quality)
+ *
+ * Extracted facts are stored alongside raw markdown in .clawvault/facts.jsonl
+ * and used to build the entity-relationship graph.
+ */
+interface ExtractedFact {
+    /** Unique ID for this fact */
+    id: string;
+    /** The entity this fact is about (person, place, thing) */
+    entity: string;
+    /** Normalized entity name for dedup */
+    entityNorm: string;
+    /** Relationship type (e.g., "prefers", "works_at", "lives_in", "bought") */
+    relation: string;
+    /** The value/object of the relation */
+    value: string;
+    /** When this fact was established */
+    validFrom: string;
+    /** When this fact was superseded (null = still current) */
+    validUntil: string | null;
+    /** Confidence 0-1 */
+    confidence: number;
+    /** Category: preference, fact, decision, entity, event */
+    category: 'preference' | 'fact' | 'decision' | 'entity' | 'event' | 'other';
+    /** Source file path (relative to vault) */
+    source: string;
+    /** Raw text this was extracted from */
+    rawText: string;
+}
+interface ExtractionResult {
+    facts: ExtractedFact[];
+    /** Number of conflicts resolved (existing facts updated) */
+    conflictsResolved: number;
+    /** Processing time in ms */
+    durationMs: number;
+}
+/**
+ * Normalize an entity name for dedup matching.
+ * "Pedro Sobral" -> "pedro sobral"
+ * "pedro" -> "pedro"
+ * "Dr. Smith" -> "dr smith"
+ */
+declare function normalizeEntity(name: string): string;
+/**
+ * Generate a deterministic fact ID from entity + relation + value.
+ */
+declare function factId(entity: string, relation: string, value: string): string;
+/**
+ * Extract facts from raw text using rule-based patterns.
+ * Fast, no LLM needed, but lower quality.
+ */
+declare function extractFactsRuleBased(text: string, source: string, timestamp?: string): ExtractedFact[];
+/**
+ * Extract facts using an LLM. Higher quality but requires API key.
+ * Falls back to rule-based if LLM unavailable.
+ */
+declare function extractFactsLlm(text: string, source: string, timestamp?: string, llmFn?: (prompt: string) => Promise<string>): Promise<ExtractedFact[]>;
+
+/**
+ * Fact Store — persistent storage + conflict resolution for extracted facts.
+ *
+ * Facts are stored in .clawvault/facts.jsonl (append-only log).
+ * An in-memory index enables fast lookup by entity, relation, category.
+ * Conflict resolution: when a new fact matches an existing one by entity+relation,
+ * the old fact gets validUntil set and the new fact replaces it.
+ */
+
+interface FactStoreStats {
+    totalFacts: number;
+    activeFacts: number;
+    supersededFacts: number;
+    entities: number;
+    relations: number;
+}
+declare class FactStore {
+    private facts;
+    private byEntity;
+    private byRelation;
+    private byCategory;
+    private factsPath;
+    private dirty;
+    constructor(vaultPath: string);
+    /** Load facts from disk */
+    load(): void;
+    /** Add facts with conflict resolution. Returns number of conflicts resolved. */
+    addFacts(newFacts: ExtractedFact[]): number;
+    /** Find an existing fact that conflicts with the new one */
+    private findConflict;
+    /** Check if two values are similar enough to be considered the same fact */
+    private isSimilarValue;
+    /** Relations where only one value can be active at a time */
+    private isExclusiveRelation;
+    /** Index a fact in all lookup maps */
+    private indexFact;
+    /** Save facts to disk (full rewrite for consistency) */
+    save(): void;
+    /** Append new facts to disk (faster than full rewrite) */
+    append(facts: ExtractedFact[]): void;
+    /** Get all active facts for an entity */
+    getEntityFacts(entity: string): ExtractedFact[];
+    /** Get all active facts for a relation */
+    getRelationFacts(relation: string): ExtractedFact[];
+    /** Get all active facts in a category */
+    getCategoryFacts(category: string): ExtractedFact[];
+    /** Get all active preferences */
+    getPreferences(): ExtractedFact[];
+    /** Search facts by text query (simple keyword match) */
+    searchFacts(query: string): ExtractedFact[];
+    /** Get facts valid at a specific time */
+    getFactsAt(timestamp: string): ExtractedFact[];
+    /** Get stats */
+    stats(): FactStoreStats;
+    /** Get all facts (for testing/debugging) */
+    getAllFacts(): ExtractedFact[];
+}
+
 /**
  * Transition Ledger for ClawVault
  * Logs task status transitions to JSONL files and supports querying.
@@ -565,7 +708,7 @@ interface CompressorOptions {
     now?: () => Date;
     fetchImpl?: typeof fetch;
 }
-type CompressionProvider = 'anthropic' | 'openai' | 'gemini' | 'openai-compatible' | 'ollama';
+type CompressionProvider = 'anthropic' | 'openai' | 'gemini' | 'xai' | 'openai-compatible' | 'ollama' | 'minimax' | 'zai';
 declare class Compressor {
     private readonly provider?;
     private readonly model?;
@@ -575,6 +718,13 @@ declare class Compressor {
     private readonly fetchImpl;
     constructor(options?: CompressorOptions);
     compress(messages: string[], existingObservations: string): Promise<string>;
+    private sanitizeIncomingMessages;
+    private sanitizeIncomingMessage;
+    private normalizeMessageRole;
+    private isConversationRolePrefix;
+    private shouldDropMessageRole;
+    private stripNoisyData;
+    private isLikelyStructuredNoise;
     private resolveProvider;
     private resolveConfiguredProvider;
     private resolveProviderFromEnv;
@@ -588,6 +738,7 @@ declare class Compressor {
     private extractOpenAIContent;
     private callAnthropic;
     private callOpenAI;
+    private callXAI;
     private callOpenAICompatible;
     private callGemini;
     private normalizeLlmOutput;
@@ -696,7 +847,6 @@ interface ActiveObserveOptions {
     reflectThreshold?: number;
     model?: string;
     extractTasks?: boolean;
-    maxSessions?: number;
 }
 interface ActiveObservationCandidate {
     sessionId: string;
@@ -851,4 +1001,4 @@ declare function runReflection(options: ReflectOptions): Promise<ReflectResult>;
 declare const VERSION: string;
 declare function registerCommanderCommands(program: Command): Command;
 
-export { type ActiveObservationCandidate, type ActiveObservationFailure, type ActiveObserveOptions, type ActiveObserveResult, type ArchiveObservationsOptions, type ArchiveObservationsResult, Category, ClawVault, type CompressionProvider, Compressor, type CompressorOptions, type ContextProfile as ConfigDefaultProfile, Document, ExtractedDate, ExtractedPreference, HandoffDocument, type ManagedConfigKey, MemoryType, type ObserveCursorEntry, type ObserveCursorStore, type ObserveProvider, Observer, type ObserverCompressionProvider, type ObserverCompressor, type ObserverOptions, type ObserverReflector, type ObserverStalenessResult, QMD_INSTALL_COMMAND, QMD_INSTALL_URL, QmdUnavailableError, type ReflectOptions, type ReflectResult, Reflector, type ReflectorOptions, type ReweaveOptions, type ReweaveResult, type RouteRule, SUPPORTED_CONFIG_KEYS, SearchEngine, SearchOptions, SearchResult, SessionRecap, SessionWatcher, type SessionWatcherOptions, StoreOptions, type SupersessionRecord, SyncOptions, SyncResult, type Theme, type TransitionEvent, VERSION, VaultConfig, addRouteRule, appendTransition, archiveObservations, bm25RankChunks, buildTransitionEvent, classifyQuestion, countBlockedTransitions, createVault, entitySimilarity, extractDates, extractEntities, extractPreferences, extractTags, extractWikiLinks, filterSuperseded, findVault, formatTransitionsTable, getConfig, getConfigValue, getObserverStaleness, getScaledObservationThresholdBytes, getSupersessionInfo, hasQmd, isKnowledgeUpdate, isRegression, isSuperseded, listConfig, listRouteRules, matchRouteRule, observeActiveSessions, parseSessionFile, parseSessionSourceLabel, qmdEmbed, qmdUpdate, queryTransitions, readAllTransitions, registerCommanderCommands, registerReweaveCommand, removeRouteRule, resetConfig, reweave, reweaveCommand, runReflection, sentenceChunk, setConfigValue, stripSupersededObservations, testRouteRule };
+export { type ActiveObservationCandidate, type ActiveObservationFailure, type ActiveObserveOptions, type ActiveObserveResult, type ArchiveObservationsOptions, type ArchiveObservationsResult, Category, ClawVault, type CompressionProvider, Compressor, type CompressorOptions, type ContextProfile as ConfigDefaultProfile, Document, EmbeddingCache, type ExtractedFact, type ExtractionResult, type FactExtractionMode$1 as FactExtractionMode, FactStore, type FactStoreStats, HandoffDocument, type LlmAdapter, type LlmAdapterOptions, LlmProvider, type ManagedConfigKey, MemoryType, type MigrateCommandOptions, type MigrateResult, type MigrationAction, MigrationIssueType, type ObserveCursorEntry, type ObserveCursorStore, type ObserveProvider, Observer, type ObserverCompressionProvider, type ObserverCompressor, type ObserverOptions, type ObserverReflector, type ObserverStalenessResult, QMD_INSTALL_COMMAND, QMD_INSTALL_URL, QmdConfigurationError, type QmdErrorCode, type QmdErrorDetails, QmdUnavailableError, type ReflectOptions, type ReflectResult, Reflector, type ReflectorOptions, type RouteRule, SUPPORTED_CONFIG_KEYS, SearchEngine, SearchOptions, SearchResult, SessionRecap, SessionWatcher, type SessionWatcherOptions, StoreOptions, SyncOptions, SyncResult, type Theme, type TransitionEvent, VERSION, VaultConfig, addRouteRule, appendTransition, archiveObservations, buildTransitionEvent, cosineSimilarity, countBlockedTransitions, createDefaultAdapter, createFactExtractionAdapter, createGeminiFlashAdapter, createLlmFunction, createVault, embed, embedBatch, extractFactsLlm, extractFactsRuleBased, extractTags, extractWikiLinks, factId, findVault, formatTransitionsTable, getConfig, getConfigValue, getObserverStaleness, getQmdErrorDetails, getScaledObservationThresholdBytes, hasQmd, hybridSearch, isRegression, listConfig, listRouteRules, matchRouteRule, migrate, migrateCommand, normalizeEntity, observeActiveSessions, parseSessionFile, parseSessionSourceLabel, qmdEmbed, qmdUpdate, queryTransitions, readAllTransitions, reciprocalRankFusion, registerCommanderCommands, registerMigrateCommand, removeRouteRule, resetConfig, resolveFactExtractionMode, runReflection, semanticSearch, setConfigValue, testRouteRule };