clawvault 2.6.3 → 2.6.5

package/dist/index.d.ts

@@ -1,17 +1,19 @@
 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 } from './types-C74wgGL1.js';
-export { f as DEFAULT_CATEGORIES, g as DEFAULT_CONFIG, h as MEMORY_TYPES, T as TYPE_TO_CATEGORY, i as VaultMeta } from './types-C74wgGL1.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-x65KXWPk.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';
@@ -189,6 +191,29 @@ declare function createVault(vaultPath: string, options?: Partial<VaultConfig>,
     skipGraph?: boolean;
 }): Promise<ClawVault>;
 
+interface MigrateCommandOptions {
+    vaultPath?: string;
+    dryRun?: boolean;
+    force?: boolean;
+    json?: boolean;
+}
+interface MigrationAction {
+    type: MigrationIssueType;
+    description: string;
+    success: boolean;
+    error?: string;
+}
+interface MigrateResult {
+    vaultPath: string;
+    issuesFound: number;
+    issuesFixed: number;
+    actions: MigrationAction[];
+    dryRun: boolean;
+}
+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
@@ -196,8 +221,22 @@ declare function createVault(vaultPath: string, options?: Partial<VaultConfig>,
 
 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
@@ -224,6 +263,10 @@ declare class SearchEngine {
      * 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
      */
@@ -386,15 +429,17 @@ declare function hybridSearch(query: string, bm25Results: SearchResult[], cache:
     rrfK?: number;
 }): Promise<SearchResult[]>;
 
-declare const OBSERVE_PROVIDERS: readonly ["anthropic", "openai", "gemini"];
-declare const OBSERVER_COMPRESSION_PROVIDERS: readonly ["anthropic", "openai", "gemini", "openai-compatible", "ollama"];
+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;
@@ -415,6 +460,197 @@ 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. 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.
@@ -471,7 +707,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?;
@@ -481,6 +717,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;
@@ -494,6 +737,7 @@ declare class Compressor {
     private extractOpenAIContent;
     private callAnthropic;
     private callOpenAI;
+    private callXAI;
     private callOpenAICompatible;
     private callGemini;
     private normalizeLlmOutput;
@@ -756,4 +1000,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, EmbeddingCache, 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 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, createVault, embed, embedBatch, extractTags, extractWikiLinks, findVault, formatTransitionsTable, getConfig, getConfigValue, getObserverStaleness, getScaledObservationThresholdBytes, hasQmd, hybridSearch, isRegression, listConfig, listRouteRules, matchRouteRule, observeActiveSessions, parseSessionFile, parseSessionSourceLabel, qmdEmbed, qmdUpdate, queryTransitions, readAllTransitions, reciprocalRankFusion, registerCommanderCommands, removeRouteRule, resetConfig, runReflection, semanticSearch, setConfigValue, 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 };