clawvault 2.6.1 → 2.6.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/README.md +352 -20
  2. package/bin/clawvault.js +8 -2
  3. package/bin/command-runtime.js +9 -1
  4. package/bin/register-maintenance-commands.js +19 -0
  5. package/bin/register-query-commands.js +58 -6
  6. package/bin/register-workgraph-commands.js +451 -0
  7. package/dist/{chunk-VXEOHTSL.js → chunk-2JQ3O2YL.js} +1 -1
  8. package/dist/{chunk-VR5NE7PZ.js → chunk-2RAZ4ZFE.js} +1 -1
  9. package/dist/chunk-2ZDO52B4.js +52 -0
  10. package/dist/chunk-4BQTQMJP.js +93 -0
  11. package/dist/{chunk-MAKNAHAW.js → chunk-5PJ4STIC.js} +98 -8
  12. package/dist/{chunk-IEVLHNLU.js → chunk-627Q3QWK.js} +3 -3
  13. package/dist/{chunk-R6SXNSFD.js → chunk-6NYYDNNG.js} +3 -3
  14. package/dist/chunk-ECRZL5XR.js +50 -0
  15. package/dist/chunk-GNJL4YGR.js +79 -0
  16. package/dist/{chunk-OZ7RIXTO.js → chunk-IIOU45CK.js} +1 -1
  17. package/dist/chunk-L4HSSQ6T.js +152 -0
  18. package/dist/{chunk-XAVB4GB4.js → chunk-LIGHWOH6.js} +1 -1
  19. package/dist/{chunk-PBEE567J.js → chunk-LUBZXECN.js} +2 -2
  20. package/dist/{chunk-UEOUADMO.js → chunk-MFL6EEPF.js} +204 -35
  21. package/dist/chunk-MM6QGW3P.js +207 -0
  22. package/dist/{chunk-T76H47ZS.js → chunk-MNPUYCHQ.js} +1 -1
  23. package/dist/{chunk-TLGBDTYT.js → chunk-MPOSMDMU.js} +6 -6
  24. package/dist/{chunk-RVYA52PY.js → chunk-NJYJL5AA.js} +1 -1
  25. package/dist/{chunk-Q2J5YTUF.js → chunk-OQGYFZ4A.js} +669 -33
  26. package/dist/{chunk-ME37YNW3.js → chunk-P7SY3D4E.js} +3 -3
  27. package/dist/chunk-RHISK3SZ.js +189 -0
  28. package/dist/{chunk-3BTHWPMB.js → chunk-S5OJEGFG.js} +2 -2
  29. package/dist/{chunk-MGDEINGP.js → chunk-SS4B7P7V.js} +1 -1
  30. package/dist/chunk-U4O6C46S.js +154 -0
  31. package/dist/{chunk-ITPEXLHA.js → chunk-URXDAUVH.js} +24 -5
  32. package/dist/chunk-WIOLLGAD.js +190 -0
  33. package/dist/chunk-WMGIIABP.js +15 -0
  34. package/dist/{chunk-QVMXF7FY.js → chunk-X3SPPUFG.js} +50 -0
  35. package/dist/{chunk-THRJVD4L.js → chunk-Y6VJKXGL.js} +1 -1
  36. package/dist/{chunk-KL4NAOMO.js → chunk-YDWHS4LJ.js} +49 -9
  37. package/dist/{chunk-4VRIMU4O.js → chunk-YNIPYN4F.js} +4 -4
  38. package/dist/{chunk-HIHOUSXS.js → chunk-YXQCA6B7.js} +105 -1
  39. package/dist/cli/index.js +18 -16
  40. package/dist/commands/archive.js +3 -2
  41. package/dist/commands/backlog.js +1 -0
  42. package/dist/commands/blocked.js +1 -0
  43. package/dist/commands/canvas.js +1 -0
  44. package/dist/commands/checkpoint.js +1 -0
  45. package/dist/commands/compat.js +2 -1
  46. package/dist/commands/context.js +5 -3
  47. package/dist/commands/doctor.d.ts +10 -1
  48. package/dist/commands/doctor.js +11 -8
  49. package/dist/commands/embed.js +5 -3
  50. package/dist/commands/entities.js +2 -1
  51. package/dist/commands/graph.js +3 -2
  52. package/dist/commands/inject.d.ts +1 -1
  53. package/dist/commands/inject.js +4 -3
  54. package/dist/commands/kanban.js +1 -0
  55. package/dist/commands/link.js +2 -1
  56. package/dist/commands/migrate-observations.js +3 -2
  57. package/dist/commands/observe.js +8 -6
  58. package/dist/commands/project.js +1 -0
  59. package/dist/commands/rebuild-embeddings.d.ts +21 -0
  60. package/dist/commands/rebuild-embeddings.js +91 -0
  61. package/dist/commands/rebuild.js +6 -4
  62. package/dist/commands/recover.js +1 -0
  63. package/dist/commands/reflect.js +5 -4
  64. package/dist/commands/repair-session.js +1 -0
  65. package/dist/commands/replay.js +7 -6
  66. package/dist/commands/session-recap.js +1 -0
  67. package/dist/commands/setup.js +3 -2
  68. package/dist/commands/shell-init.js +2 -0
  69. package/dist/commands/sleep.d.ts +1 -1
  70. package/dist/commands/sleep.js +8 -6
  71. package/dist/commands/status.d.ts +2 -0
  72. package/dist/commands/status.js +35 -24
  73. package/dist/commands/sync-bd.js +3 -2
  74. package/dist/commands/tailscale.js +3 -2
  75. package/dist/commands/task.js +1 -0
  76. package/dist/commands/template.js +1 -0
  77. package/dist/commands/wake.d.ts +1 -1
  78. package/dist/commands/wake.js +4 -2
  79. package/dist/index.d.ts +333 -10
  80. package/dist/index.js +320 -33
  81. package/dist/{inject-x65KXWPk.d.ts → inject-DYUrDqQO.d.ts} +2 -2
  82. package/dist/ledger-B7g7jhqG.d.ts +44 -0
  83. package/dist/lib/auto-linker.js +1 -0
  84. package/dist/lib/canvas-layout.js +1 -0
  85. package/dist/lib/config.d.ts +27 -3
  86. package/dist/lib/config.js +4 -1
  87. package/dist/lib/entity-index.js +1 -0
  88. package/dist/lib/project-utils.js +1 -0
  89. package/dist/lib/session-repair.js +1 -0
  90. package/dist/lib/session-utils.js +1 -0
  91. package/dist/lib/tailscale.js +1 -0
  92. package/dist/lib/task-utils.js +1 -0
  93. package/dist/lib/template-engine.js +1 -0
  94. package/dist/lib/webdav.js +1 -0
  95. package/dist/onnxruntime_binding-5QEF3SUC.node +0 -0
  96. package/dist/onnxruntime_binding-BKPKNEGC.node +0 -0
  97. package/dist/onnxruntime_binding-FMOXGIUT.node +0 -0
  98. package/dist/onnxruntime_binding-OI2KMXC5.node +0 -0
  99. package/dist/onnxruntime_binding-UX44MLAZ.node +0 -0
  100. package/dist/onnxruntime_binding-Y2W7N7WY.node +0 -0
  101. package/dist/registry-BR4326o0.d.ts +30 -0
  102. package/dist/store-CA-6sKCJ.d.ts +34 -0
  103. package/dist/thread-B9LhXNU0.d.ts +41 -0
  104. package/dist/transformers.node-A2ZRORSQ.js +46775 -0
  105. package/dist/{types-C74wgGL1.d.ts → types-BbWJoC1c.d.ts} +1 -1
  106. package/dist/workgraph/index.d.ts +5 -0
  107. package/dist/workgraph/index.js +23 -0
  108. package/dist/workgraph/ledger.d.ts +2 -0
  109. package/dist/workgraph/ledger.js +25 -0
  110. package/dist/workgraph/registry.d.ts +2 -0
  111. package/dist/workgraph/registry.js +19 -0
  112. package/dist/workgraph/store.d.ts +2 -0
  113. package/dist/workgraph/store.js +25 -0
  114. package/dist/workgraph/thread.d.ts +2 -0
  115. package/dist/workgraph/thread.js +25 -0
  116. package/dist/workgraph/types.d.ts +54 -0
  117. package/dist/workgraph/types.js +7 -0
  118. package/hooks/clawvault/HOOK.md +34 -4
  119. package/hooks/clawvault/handler.js +751 -8
  120. package/hooks/clawvault/handler.test.js +247 -0
  121. package/hooks/clawvault/openclaw.plugin.json +72 -0
  122. package/openclaw.plugin.json +84 -0
  123. package/package.json +8 -4
  124. package/dist/chunk-4QYGFWRM.js +0 -88
  125. package/dist/chunk-MXSSG3QU.js +0 -42
package/dist/index.d.ts CHANGED
@@ -1,17 +1,19 @@
1
1
  import { Command } from 'commander';
2
- 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';
3
- 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';
2
+ 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';
3
+ 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';
4
4
  export { setupCommand } from './commands/setup.js';
5
5
  export { CompatCheck, CompatCommandOptions, CompatReport, CompatStatus, checkOpenClawCompatibility, compatCommand, compatibilityExitCode } from './commands/compat.js';
6
6
  export { GraphSummary, graphCommand, graphSummary } from './commands/graph.js';
7
7
  export { KanbanGroupBy, KanbanImportChange, KanbanImportOptions, KanbanImportResult, KanbanLane, KanbanSyncOptions, KanbanSyncResult, ParsedKanbanBoard, ParsedKanbanLane, buildKanbanLanes, extractCardSlug, formatKanbanCard, generateKanbanMarkdown, importKanbanBoard, kanbanCommand, parseKanbanMarkdown, syncKanbanBoard } from './commands/kanban.js';
8
8
  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';
9
- 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';
9
+ import { L as LlmProvider } from './inject-DYUrDqQO.js';
10
+ 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';
10
11
  export { ObserveCommandOptions, observeCommand, registerObserveCommand } from './commands/observe.js';
11
12
  export { ReflectCommandOptions, reflectCommand, registerReflectCommand } from './commands/reflect.js';
12
13
  export { ArchiveCommandOptions, archiveCommand, registerArchiveCommand } from './commands/archive.js';
13
14
  export { RebuildCommandOptions, rebuildCommand, registerRebuildCommand } from './commands/rebuild.js';
14
- export { DoctorCheck, DoctorReport, DoctorStatus, doctor } from './commands/doctor.js';
15
+ import { MigrationIssueType } from './commands/doctor.js';
16
+ export { DoctorCheck, DoctorReport, DoctorStatus, MigrationIssue, doctor } from './commands/doctor.js';
15
17
  export { EmbedCommandOptions, EmbedCommandResult, embedCommand, registerEmbedCommand } from './commands/embed.js';
16
18
  export { ReplayCommandOptions, registerReplayCommand, replayCommand } from './commands/replay.js';
17
19
  export { MigrateObservationsOptions, MigrateObservationsResult, migrateObservations, migrateObservationsCommand, registerMigrateObservationsCommand } from './commands/migrate-observations.js';
@@ -157,6 +159,16 @@ declare class ClawVault {
157
159
  * Parse a handoff document back into structured form
158
160
  */
159
161
  private parseHandoff;
162
+ /**
163
+ * Safely convert a date value to ISO string format.
164
+ * Handles Date objects, strings, and undefined values.
165
+ */
166
+ private toDateString;
167
+ /**
168
+ * Extract the date portion (YYYY-MM-DD) from an ISO date string or Date object.
169
+ * Provides safe handling for various date formats.
170
+ */
171
+ private extractDatePart;
160
172
  private applyQmdConfig;
161
173
  private slugify;
162
174
  private saveIndex;
@@ -179,6 +191,29 @@ declare function createVault(vaultPath: string, options?: Partial<VaultConfig>,
179
191
  skipGraph?: boolean;
180
192
  }): Promise<ClawVault>;
181
193
 
194
+ interface MigrateCommandOptions {
195
+ vaultPath?: string;
196
+ dryRun?: boolean;
197
+ force?: boolean;
198
+ json?: boolean;
199
+ }
200
+ interface MigrationAction {
201
+ type: MigrationIssueType;
202
+ description: string;
203
+ success: boolean;
204
+ error?: string;
205
+ }
206
+ interface MigrateResult {
207
+ vaultPath: string;
208
+ issuesFound: number;
209
+ issuesFixed: number;
210
+ actions: MigrationAction[];
211
+ dryRun: boolean;
212
+ }
213
+ declare function migrate(options?: MigrateCommandOptions): Promise<MigrateResult>;
214
+ declare function migrateCommand(options?: MigrateCommandOptions): Promise<MigrateResult>;
215
+ declare function registerMigrateCommand(program: Command): void;
216
+
182
217
  /**
183
218
  * ClawVault Search Engine - qmd Backend
184
219
  * Uses qmd CLI for BM25 and vector search
@@ -186,8 +221,22 @@ declare function createVault(vaultPath: string, options?: Partial<VaultConfig>,
186
221
 
187
222
  declare const QMD_INSTALL_URL = "https://github.com/tobi/qmd";
188
223
  declare const QMD_INSTALL_COMMAND = "bun install -g github:tobi/qmd";
224
+ type QmdErrorCode = 'NOT_INSTALLED' | 'NOT_CONFIGURED' | 'COLLECTION_NOT_FOUND' | 'EXECUTION_FAILED';
225
+ interface QmdErrorDetails {
226
+ code: QmdErrorCode;
227
+ message: string;
228
+ hint: string;
229
+ }
189
230
  declare class QmdUnavailableError extends Error {
190
- constructor(message?: string);
231
+ readonly code: QmdErrorCode;
232
+ readonly hint: string;
233
+ constructor(code?: QmdErrorCode, additionalContext?: string);
234
+ toUserMessage(): string;
235
+ }
236
+ declare function getQmdErrorDetails(code: QmdErrorCode): QmdErrorDetails;
237
+ declare class QmdConfigurationError extends Error {
238
+ readonly hint?: string | undefined;
239
+ constructor(message: string, hint?: string | undefined);
191
240
  }
192
241
  /**
193
242
  * Check if qmd is available
@@ -214,6 +263,10 @@ declare class SearchEngine {
214
263
  * Set the collection name (usually vault name)
215
264
  */
216
265
  setCollection(name: string): void;
266
+ /**
267
+ * Get the current collection name
268
+ */
269
+ getCollection(): string;
217
270
  /**
218
271
  * Set the vault path for file resolution
219
272
  */
@@ -300,15 +353,93 @@ declare function extractWikiLinks(content: string): string[];
300
353
  */
301
354
  declare function extractTags(content: string): string[];
302
355
 
303
- declare const OBSERVE_PROVIDERS: readonly ["anthropic", "openai", "gemini"];
304
- declare const OBSERVER_COMPRESSION_PROVIDERS: readonly ["anthropic", "openai", "gemini", "openai-compatible", "ollama"];
356
+ /**
357
+ * ClawVault Hybrid Search BM25 + Semantic Embeddings + RRF
358
+ *
359
+ * Proven in LongMemEval benchmarks:
360
+ * - v28 pipeline: 57.0% overall (up from 52.6% with BM25-only)
361
+ * - Multi-session: 45.9% (up from 28.6%)
362
+ * - Single-session-user: 85.7% (up from 72.9%)
363
+ *
364
+ * Architecture:
365
+ * 1. BM25 via existing qmd search
366
+ * 2. Semantic via @huggingface/transformers (all-MiniLM-L6-v2)
367
+ * 3. Reciprocal Rank Fusion (k=60)
368
+ */
369
+
370
+ /**
371
+ * Compute embedding for a text string
372
+ */
373
+ declare function embed(text: string): Promise<Float32Array>;
374
+ /**
375
+ * Compute embeddings for multiple texts
376
+ */
377
+ declare function embedBatch(texts: string[]): Promise<Float32Array[]>;
378
+ /**
379
+ * Cosine similarity between two normalized vectors
380
+ */
381
+ declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
382
+ /**
383
+ * Embedding cache — stores embeddings on disk alongside vault files
384
+ */
385
+ declare class EmbeddingCache {
386
+ private cachePath;
387
+ private cache;
388
+ private dirty;
389
+ constructor(vaultPath: string);
390
+ /**
391
+ * Load cache from disk
392
+ */
393
+ load(): void;
394
+ /**
395
+ * Save cache to disk
396
+ */
397
+ save(): void;
398
+ get(key: string): Float32Array | undefined;
399
+ set(key: string, embedding: Float32Array): void;
400
+ has(key: string): boolean;
401
+ entries(): IterableIterator<[string, Float32Array]>;
402
+ get size(): number;
403
+ }
404
+ /**
405
+ * Reciprocal Rank Fusion of two ranked lists
406
+ */
407
+ declare function reciprocalRankFusion(list1: {
408
+ id: string;
409
+ score: number;
410
+ }[], list2: {
411
+ id: string;
412
+ score: number;
413
+ }[], k?: number): {
414
+ id: string;
415
+ score: number;
416
+ }[];
417
+ /**
418
+ * Semantic search against embedding cache
419
+ */
420
+ declare function semanticSearch(query: string, cache: EmbeddingCache, topK?: number): Promise<{
421
+ id: string;
422
+ score: number;
423
+ }[]>;
424
+ /**
425
+ * Hybrid search: combines BM25 results with semantic results via RRF
426
+ */
427
+ declare function hybridSearch(query: string, bm25Results: SearchResult[], cache: EmbeddingCache, options?: {
428
+ topK?: number;
429
+ rrfK?: number;
430
+ }): Promise<SearchResult[]>;
431
+
432
+ declare const OBSERVE_PROVIDERS: readonly ["anthropic", "openai", "gemini", "xai", "openclaw"];
433
+ declare const OBSERVER_COMPRESSION_PROVIDERS: readonly ["anthropic", "openai", "gemini", "xai", "openai-compatible", "ollama", "openclaw", "minimax", "zai"];
305
434
  declare const THEMES: readonly ["neural", "minimal", "none"];
306
435
  declare const CONTEXT_PROFILES: readonly ["default", "planning", "incident", "handoff", "auto"];
436
+ declare const FACT_EXTRACTION_MODES: readonly ["off", "rule", "llm", "hybrid"];
307
437
  type ObserveProvider = (typeof OBSERVE_PROVIDERS)[number];
308
438
  type ObserverCompressionProvider = (typeof OBSERVER_COMPRESSION_PROVIDERS)[number];
309
439
  type Theme = (typeof THEMES)[number];
310
440
  type ContextProfile = (typeof CONTEXT_PROFILES)[number];
311
- 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';
441
+ type FactExtractionMode$1 = (typeof FACT_EXTRACTION_MODES)[number];
442
+ 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';
312
443
  interface RouteRule {
313
444
  pattern: string;
314
445
  target: string;
@@ -329,6 +460,197 @@ declare function removeRouteRule(vaultPath: string, pattern: string): boolean;
329
460
  declare function matchRouteRule(text: string, routes: RouteRule[]): RouteRule | null;
330
461
  declare function testRouteRule(vaultPath: string, text: string): RouteRule | null;
331
462
 
463
+ /**
464
+ * LLM Adapter for fact extraction.
465
+ *
466
+ * Provides a unified interface for calling LLMs to extract facts from text.
467
+ * Currently supports Gemini Flash as the primary adapter, with fallback to
468
+ * the existing LLM provider infrastructure.
469
+ */
470
+
471
+ type FactExtractionMode = 'off' | 'rule' | 'llm' | 'hybrid';
472
+ interface LlmAdapterOptions {
473
+ provider?: LlmProvider | null;
474
+ model?: string;
475
+ temperature?: number;
476
+ maxTokens?: number;
477
+ fetchImpl?: typeof fetch;
478
+ }
479
+ interface LlmAdapter {
480
+ /**
481
+ * Call the LLM with a prompt and return the response text.
482
+ */
483
+ call(prompt: string): Promise<string>;
484
+ /**
485
+ * Check if the adapter is available (has valid credentials).
486
+ */
487
+ isAvailable(): boolean;
488
+ /**
489
+ * Get the provider name for this adapter.
490
+ */
491
+ getProvider(): LlmProvider | null;
492
+ }
493
+ /**
494
+ * Create a Gemini Flash adapter for fact extraction.
495
+ * Uses the Gemini API with the flash model optimized for speed.
496
+ */
497
+ declare function createGeminiFlashAdapter(options?: LlmAdapterOptions): LlmAdapter;
498
+ /**
499
+ * Create an LLM adapter using the default provider resolution.
500
+ * Falls back through providers: openclaw -> anthropic -> openai -> gemini -> xai
501
+ */
502
+ declare function createDefaultAdapter(options?: LlmAdapterOptions): LlmAdapter;
503
+ /**
504
+ * Create an LLM adapter for fact extraction based on configuration.
505
+ *
506
+ * Priority:
507
+ * 1. If provider is explicitly specified, use that
508
+ * 2. If Gemini API key is available, prefer Gemini Flash for speed
509
+ * 3. Fall back to default provider resolution
510
+ */
511
+ declare function createFactExtractionAdapter(options?: LlmAdapterOptions): LlmAdapter;
512
+ /**
513
+ * Create an LLM function compatible with extractFactsLlm.
514
+ * This wraps the adapter into the function signature expected by fact-extractor.ts.
515
+ */
516
+ declare function createLlmFunction(adapter: LlmAdapter): ((prompt: string) => Promise<string>) | undefined;
517
+ /**
518
+ * Resolve the effective fact extraction mode based on configuration and availability.
519
+ *
520
+ * - 'off': Never extract facts
521
+ * - 'rule': Only use rule-based extraction (no LLM)
522
+ * - 'llm': Prefer LLM extraction, fall back to rules if LLM unavailable
523
+ * - 'hybrid': Use both LLM and rules, merge results (future enhancement)
524
+ */
525
+ declare function resolveFactExtractionMode(configuredMode: FactExtractionMode | undefined, adapter?: LlmAdapter): {
526
+ mode: FactExtractionMode;
527
+ useLlm: boolean;
528
+ };
529
+
530
+ /**
531
+ * Write-time fact extraction for ClawVault v3.
532
+ *
533
+ * When a memory is stored, this module extracts structured facts:
534
+ * (entity, relation, value, timestamp, confidence)
535
+ *
536
+ * Two modes:
537
+ * 1. LLM extraction (accurate but requires API key)
538
+ * 2. Rule-based extraction (fast, no deps, lower quality)
539
+ *
540
+ * Extracted facts are stored alongside raw markdown in .clawvault/facts.jsonl
541
+ * and used to build the entity-relationship graph.
542
+ */
543
+ interface ExtractedFact {
544
+ /** Unique ID for this fact */
545
+ id: string;
546
+ /** The entity this fact is about (person, place, thing) */
547
+ entity: string;
548
+ /** Normalized entity name for dedup */
549
+ entityNorm: string;
550
+ /** Relationship type (e.g., "prefers", "works_at", "lives_in", "bought") */
551
+ relation: string;
552
+ /** The value/object of the relation */
553
+ value: string;
554
+ /** When this fact was established */
555
+ validFrom: string;
556
+ /** When this fact was superseded (null = still current) */
557
+ validUntil: string | null;
558
+ /** Confidence 0-1 */
559
+ confidence: number;
560
+ /** Category: preference, fact, decision, entity, event */
561
+ category: 'preference' | 'fact' | 'decision' | 'entity' | 'event' | 'other';
562
+ /** Source file path (relative to vault) */
563
+ source: string;
564
+ /** Raw text this was extracted from */
565
+ rawText: string;
566
+ }
567
+ interface ExtractionResult {
568
+ facts: ExtractedFact[];
569
+ /** Number of conflicts resolved (existing facts updated) */
570
+ conflictsResolved: number;
571
+ /** Processing time in ms */
572
+ durationMs: number;
573
+ }
574
+ /**
575
+ * Normalize an entity name for dedup matching.
576
+ * "Pedro Sobral" -> "pedro sobral"
577
+ * "pedro" -> "pedro"
578
+ * "Dr. Smith" -> "dr smith"
579
+ */
580
+ declare function normalizeEntity(name: string): string;
581
+ /**
582
+ * Generate a deterministic fact ID from entity + relation + value.
583
+ */
584
+ declare function factId(entity: string, relation: string, value: string): string;
585
+ /**
586
+ * Extract facts from raw text using rule-based patterns.
587
+ * Fast, no LLM needed, but lower quality.
588
+ */
589
+ declare function extractFactsRuleBased(text: string, source: string, timestamp?: string): ExtractedFact[];
590
+ /**
591
+ * Extract facts using an LLM. Higher quality but requires API key.
592
+ * Falls back to rule-based if LLM unavailable.
593
+ */
594
+ declare function extractFactsLlm(text: string, source: string, timestamp?: string, llmFn?: (prompt: string) => Promise<string>): Promise<ExtractedFact[]>;
595
+
596
+ /**
597
+ * Fact Store — persistent storage + conflict resolution for extracted facts.
598
+ *
599
+ * Facts are stored in .clawvault/facts.jsonl (append-only log).
600
+ * An in-memory index enables fast lookup by entity, relation, category.
601
+ * Conflict resolution: when a new fact matches an existing one by entity+relation,
602
+ * the old fact gets validUntil set and the new fact replaces it.
603
+ */
604
+
605
+ interface FactStoreStats {
606
+ totalFacts: number;
607
+ activeFacts: number;
608
+ supersededFacts: number;
609
+ entities: number;
610
+ relations: number;
611
+ }
612
+ declare class FactStore {
613
+ private facts;
614
+ private byEntity;
615
+ private byRelation;
616
+ private byCategory;
617
+ private factsPath;
618
+ private dirty;
619
+ constructor(vaultPath: string);
620
+ /** Load facts from disk */
621
+ load(): void;
622
+ /** Add facts with conflict resolution. Returns number of conflicts resolved. */
623
+ addFacts(newFacts: ExtractedFact[]): number;
624
+ /** Find an existing fact that conflicts with the new one */
625
+ private findConflict;
626
+ /** Check if two values are similar enough to be considered the same fact */
627
+ private isSimilarValue;
628
+ /** Relations where only one value can be active at a time */
629
+ private isExclusiveRelation;
630
+ /** Index a fact in all lookup maps */
631
+ private indexFact;
632
+ /** Save facts to disk (full rewrite for consistency) */
633
+ save(): void;
634
+ /** Append new facts to disk (faster than full rewrite) */
635
+ append(facts: ExtractedFact[]): void;
636
+ /** Get all active facts for an entity */
637
+ getEntityFacts(entity: string): ExtractedFact[];
638
+ /** Get all active facts for a relation */
639
+ getRelationFacts(relation: string): ExtractedFact[];
640
+ /** Get all active facts in a category */
641
+ getCategoryFacts(category: string): ExtractedFact[];
642
+ /** Get all active preferences */
643
+ getPreferences(): ExtractedFact[];
644
+ /** Search facts by text query (simple keyword match) */
645
+ searchFacts(query: string): ExtractedFact[];
646
+ /** Get facts valid at a specific time */
647
+ getFactsAt(timestamp: string): ExtractedFact[];
648
+ /** Get stats */
649
+ stats(): FactStoreStats;
650
+ /** Get all facts (for testing/debugging) */
651
+ getAllFacts(): ExtractedFact[];
652
+ }
653
+
332
654
  /**
333
655
  * Transition Ledger for ClawVault
334
656
  * Logs task status transitions to JSONL files and supports querying.
@@ -385,7 +707,7 @@ interface CompressorOptions {
385
707
  now?: () => Date;
386
708
  fetchImpl?: typeof fetch;
387
709
  }
388
- type CompressionProvider = 'anthropic' | 'openai' | 'gemini' | 'openai-compatible' | 'ollama';
710
+ type CompressionProvider = 'anthropic' | 'openai' | 'gemini' | 'xai' | 'openai-compatible' | 'ollama' | 'minimax' | 'zai';
389
711
  declare class Compressor {
390
712
  private readonly provider?;
391
713
  private readonly model?;
@@ -408,6 +730,7 @@ declare class Compressor {
408
730
  private extractOpenAIContent;
409
731
  private callAnthropic;
410
732
  private callOpenAI;
733
+ private callXAI;
411
734
  private callOpenAICompatible;
412
735
  private callGemini;
413
736
  private normalizeLlmOutput;
@@ -670,4 +993,4 @@ declare function runReflection(options: ReflectOptions): Promise<ReflectResult>;
670
993
  declare const VERSION: string;
671
994
  declare function registerCommanderCommands(program: Command): Command;
672
995
 
673
- 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, 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, countBlockedTransitions, createVault, extractTags, extractWikiLinks, findVault, formatTransitionsTable, getConfig, getConfigValue, getObserverStaleness, getScaledObservationThresholdBytes, hasQmd, isRegression, listConfig, listRouteRules, matchRouteRule, observeActiveSessions, parseSessionFile, parseSessionSourceLabel, qmdEmbed, qmdUpdate, queryTransitions, readAllTransitions, registerCommanderCommands, removeRouteRule, resetConfig, runReflection, setConfigValue, testRouteRule };
996
+ 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 };