@equationalapplications/react-llm-wiki 7.15.1 → 7.16.0

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 (2) hide show
  1. package/README.md +21 -543
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -10,562 +10,40 @@ In-browser LLM memory for React web apps. Bring your own SQLite adapter (e.g., [
10
10
 
11
11
  > Inspired by [Andrej Karpathy's LLM Wiki memory spec](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
12
12
 
13
+ **📖 Documentation: [equationalapplications.github.io/expo-llm-wiki/packages/react](https://equationalapplications.github.io/expo-llm-wiki/packages/react/)**. Start with the [React quickstart](https://equationalapplications.github.io/expo-llm-wiki/start/quickstart-react/), or see the [hooks reference](https://equationalapplications.github.io/expo-llm-wiki/reference/hooks/).
14
+
13
15
  ## Features
14
16
 
15
- - **Semantic search** — Vector embeddings with optional `embed` function and MiniSearch fallback
16
- - **Retrieval tuning** — Per-call overrides for hybrid scoring, pre-filtering, result limits, and tier weights
17
- - **Multi-entity reads** — Search across multiple `entity_id` namespaces in one pass with `tierWeights` and optional `includeZeroWeightEntities`
18
- - **Source provenance** — `WikiFact.source_type` distinguishes immutable document facts (`immutable_document`) from mutable derived/user facts (`librarian_inferred`, `user_stated`, `user_confirmed`). Immutable document facts are preserved from librarian/heal rewriting and only removed by `forget()` or by re-ingesting the source.
19
- - **Seeded ontologies** — Enforce strict taxonomies or allow emergent graph relationship extraction (`useOntologyManifest`, `useSetOntologyManifest`; Strict, Emergent, or Off; defaults to Off).
20
- - **Graph traversal (GraphRAG)** — Walk the knowledge graph N hops from a fact and format the result for LLM prompts (`useWikiTraversal`, `formatGraphContext`). This is the React-web surface of the GraphRAG retrieval layer; pair with `@equationalapplications/schema-org-llm-wiki` for the canonical ontology. See [root README: GraphRAG](../../README.md#graphrag-sql-only-graph-retrieval).
21
- - **Reactive reads** — Auto-refetch on `entityId`, query, or `options` changes
22
- - **Mutation hooks** — `useWikiWrite`, `useWikiIngest`, `useWikiForget`, `useWikiMaintenance`, `useSetOntologyManifest`, etc.
23
- - **Shared context** — Single `WikiProvider` per app, use anywhere
24
- - **Full-featured memory** — Facts, tasks, events, maintenance jobs (librarian, heal, reembed, prune)
25
- - **Interoperability:** Supports [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) v0.1 + v0.2 import and export via the [llm-wiki OKF profiles](https://github.com/equationalapplications/expo-llm-wiki/blob/main/docs/okf-profile.md) (default `llm-wiki/2`, back-compat `llm-wiki/1`).
17
+ - **Runs in the browser.** SQLite compiled to WebAssembly ([`sql.js`](https://github.com/sql-js/sql.js)) means no server is needed. Any other `SQLiteAdapter` works too.
18
+ - **Reactive reads.** `useMemoryRead` refetches when the entity, query or options change.
19
+ - **Mutation hooks.** `useWikiWrite`, `useWikiIngest`, `useWikiForget`, `useWikiMaintenance`, `useWikiExport` and more.
20
+ - **GraphRAG.** `useWikiTraversal` plus `formatGraphContext` for prompt-ready graph context, and `useOntologyManifest` / `useSetOntologyManifest` for [seeded ontologies](https://equationalapplications.github.io/expo-llm-wiki/guides/ontologies/).
21
+ - **Live job status** with `useEntityStatus`.
22
+ - **Everything in core**, re-exported in full.
26
23
 
27
24
  ## Installation
28
25
 
29
26
  ```bash
30
- npm install @equationalapplications/react-llm-wiki
27
+ npm install @equationalapplications/react-llm-wiki sql.js
31
28
  ```
32
29
 
33
- ## Semantic Search Setup
34
-
35
- Enable vector-based retrieval by providing an `embed` function in `WikiOptions`:
36
-
37
- ```typescript
38
- import { WikiProvider, createWiki } from '@equationalapplications/react-llm-wiki';
39
-
40
- const wiki = createWiki(adapter, {
41
- config: {
42
- preFilterLimit: 50, // Optimize for wikis with 500+ facts
43
- hybridWeight: 0.7, // Blend semantic (70%) + keyword (30%)
44
- },
45
- llmProvider: {
46
- generateText: async ({ systemPrompt, userPrompt }) => {
47
- // Your LLM
48
- return 'Model output';
49
- },
50
- maxOutputTokens: 4096, // optional — your model's output ceiling; lets maintenance passes size their LLM calls
51
- embed: async (text: string) => {
52
- // Your embedding service
53
- const res = await fetch('https://your-app.example.com/api/embed', {
54
- method: 'POST',
55
- body: JSON.stringify({ text })
56
- });
57
- const { embedding } = await res.json();
58
- return embedding; // number[]
59
- },
60
- },
61
- onRetrievalFallback: (error) => {
62
- console.warn('Embeddings unavailable, using keyword search:', error);
63
- },
64
- });
65
-
66
- await wiki.setup();
67
-
68
- <WikiProvider wiki={wiki}>
69
- <App />
70
- </WikiProvider>
71
- ```
72
-
73
- ## Setup
74
-
75
- **React** (with any `SQLiteAdapter`):
30
+ Peer dependency: `react >=17`. Requires Node.js 20 or later for tooling and server-side use.
76
31
 
77
- ```typescript
78
- import { WikiProvider, createWiki } from '@equationalapplications/react-llm-wiki';
79
-
80
- // Create wiki instance and initialize tables
81
- const wiki = createWiki(adapter, options);
82
- await wiki.setup();
83
-
84
- // Wrap app
85
- <WikiProvider wiki={wiki}>
86
- <App />
87
- </WikiProvider>
88
- ```
89
-
90
- **Expo / React Native** (`@equationalapplications/expo-llm-wiki` re-exports both `createWiki` and `WikiProvider`). See [`packages/expo/README.md`](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/expo/README.md) for peer dependencies (`expo-sqlite`, `expo-crypto`).
91
-
92
- ```typescript
93
- import { createWiki, WikiProvider } from '@equationalapplications/expo-llm-wiki';
94
- import { openDatabaseSync } from 'expo-sqlite';
95
-
96
- const db = openDatabaseSync('wiki.db');
97
- const wiki = createWiki(db, options);
98
- await wiki.setup();
99
-
100
- <WikiProvider wiki={wiki}>
101
- <App />
102
- </WikiProvider>
103
- ```
104
-
105
- ## Configuration
106
-
107
- All `WikiConfig` fields are optional:
108
-
109
- ```typescript
110
- const wiki = createWiki(adapter, {
111
- llmProvider: { /* ... */ },
112
- config: {
113
- tablePrefix: 'llm_wiki_', // default: 'llm_wiki_'
114
- maxResults: 10, // default: 10
115
- autoLibrarianThreshold: 20, // default: 20 — events before librarian auto-runs
116
- autoHealThreshold: 100, // default: 100 — events before heal auto-runs
117
- maxChunkLength: 12000, // default: 12000 (char count per ingestDocument chunk)
118
- chunkOverlap: 400, // default: 400 (overlap between chunks in characters)
119
- chunkConcurrency: 1, // default: 1 (parallel LLM calls per ingestDocument)
120
- pruneRetainSoftDeletedFor: 7, // default: 7 (days before hard-deleting soft-deleted facts)
121
- pruneEventsAfter: 30, // default: 30 (days before hard-deleting old events)
122
- orphanAfterDays: 30, // default: 30 (days before runHeal flags sourceless facts; null to disable)
123
- staleInferredAfterDays: 60, // default: 60 (days before runHeal downgrades inferred facts; null to disable)
124
- preFilterLimit: 50, // default: undefined — MiniSearch pre-filter before cosine scan; recommended for >500 facts
125
- hybridWeight: 0.7, // default: undefined — blend semantic (1.0) ↔ keyword (0.0); pure semantic when unset
126
- excludeDrafts: false, // default: false — hide unreviewed drafts from reads; traversal skips discovered drafts (a draft start fact is still returned)
127
- grounding: { mode: 'off' }, // default: off — 'draft' stores facts that don't quote their source as drafts
128
-
129
- // Global prompt overrides — librarianSystemPrompt and healSystemPrompt apply to write() auto-runs;
130
- // ingestSystemPrompt applies only to explicit ingestDocument() calls.
131
- // ⚠ Overrides replace the entire default prompt, including the JSON output contract.
132
- // Your prompt must instruct the LLM to return the required JSON shape — see packages/core/README.md#prompt-management--overrides.
133
- prompts: {
134
- ingestSystemPrompt: `Extract core facts from this document: {{documentChunk}}\n\nReturn ONLY valid JSON: { "facts": [{ "title": "string", "body": "string", "tags": ["string"], "confidence": "certain|inferred|tentative" }] }. No markdown.`,
135
- librarianSystemPrompt: `Synthesize these thoughts into insights:\n{{events}}\n\nReturn ONLY valid JSON: { "facts": [{ "title": "string", "body": "string", "tags": ["string"], "confidence": "certain|inferred|tentative" }], "tasks": [{ "description": "string", "priority": 0 }] }. No markdown.`,
136
- healSystemPrompt: `Fix the memory graph based on these candidates: {{healCandidates}}\n\nReturn ONLY valid JSON: { "downgraded": ["factId"], "deleted": ["factId"], "newFacts": [{ "title": "string", "body": "string", "tags": ["string"], "confidence": "certain|inferred|tentative" }] }. No markdown.`,
137
- },
138
- },
139
- });
140
- ```
141
-
142
- **Diagnostics and draft review.** Pass `onDiagnostic` beside `llmProvider` (not inside `config`) to receive typed, content-free reports of dropped chunks, facts, edges and failed background jobs. `useMemoryRead` and `useWikiTraversal` accept `excludeDrafts` per call, which overrides the config default. There are no dedicated hooks for listing or promoting drafts yet: call `listDrafts` / `promoteDraft` on the `WikiMemory` instance from `useWiki()`, as shown below. With `grounding` on, facts that don't quote their source land as drafts; see [core: Grounding](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/core/README.md#grounding). See [core: Diagnostics](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/core/README.md#diagnostics) and [core: Draft Review](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/core/README.md#draft-review). Other `WikiConfig` fields, such as `ontology`, are documented in the [core README](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/core/README.md#configuration).
143
-
144
- ```tsx
145
- import { useWiki } from '@equationalapplications/react-llm-wiki';
146
-
147
- function DraftReview({ entityId }: { entityId: string }) {
148
- const wiki = useWiki(); // the WikiMemory instance; throws outside <WikiProvider>
149
- const loadDrafts = () => wiki.listDrafts(entityId, { limit: 20 }); // → { facts, nextCursor }
150
- // ...
151
- }
152
- ```
153
-
154
- `useWiki()` also exposes the read-only health and instruction APIs for components that need them:
32
+ ## Quick look
155
33
 
156
34
  ```tsx
157
- function HealthAndInstructions({ entityId, batch }: { entityId: string; batch: Array<{ sourceRef: string; sourceHash: string }> }) {
158
- const wiki = useWiki();
159
-
160
- // Lint: read-only health report for one entity (dangling edges, manifest violations, drafts, etc.)
161
- const loadReport = () => wiki.lint(entityId);
162
- // → { danglingEdges, manifestViolations, untypedFacts, drafts, unverifiedInferred,
163
- // sample: { danglingEdgeIds, manifestViolationEdgeIds } }
164
-
165
- // pendingSources: per-input change status including the partial-ingest state.
166
- const loadStatuses = () => wiki.pendingSources(entityId, batch);
167
- // → Array<{ sourceRef: string; status: 'new' | 'changed' | 'partial' | 'current' }>
168
-
169
- // getInstructions: effective system prompts for each writer, with overrides applied.
170
- const loadInstructions = () => wiki.getInstructions(entityId);
171
- // → { ingest, librarian, heal, ontologyBackfill }
35
+ import { useMemoryRead } from '@equationalapplications/react-llm-wiki';
36
+
37
+ // Inside a <WikiProvider wiki={wiki}> tree:
38
+ function Preferences() {
39
+ const { data, isPending, error } = useMemoryRead('user-123', 'preferences');
40
+ if (isPending) return <p>Loading…</p>;
41
+ if (error) return <p>{error.message}</p>;
42
+ return <ul>{data?.facts.map((f) => <li key={f.id}>{f.title}</li>)}</ul>;
172
43
  }
173
44
  ```
174
45
 
175
- See [core: Lint](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/core/README.md#lint), [core: Batch Change Detection](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/core/README.md#batch-change-detection), and [core: Effective instructions](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/core/README.md#effective-instructions-getinstructions).
176
-
177
- ## Retrieval Tuning
178
-
179
- Optimize `read()` performance and blend retrieval strategies:
180
-
181
- ```typescript
182
- const config = {
183
- // Limit cosine similarity scoring to top-K MiniSearch keyword candidates
184
- preFilterLimit: 50,
185
-
186
- // Blend semantic and keyword scores (0.0 = pure keyword, 1.0 = pure semantic)
187
- hybridWeight: 0.7,
188
-
189
- // Max results returned per read
190
- maxResults: 10,
191
- };
192
-
193
- const wiki = createWiki(adapter, {
194
- config,
195
- llmProvider: { /* ... */ },
196
- });
197
- ```
198
-
199
- **Hybrid scoring blends:**
200
- - `hybridWeight: 1.0` → pure semantic scoring among the candidates being scored; if `preFilterLimit` is set, semantic scoring is still limited to the top-K MiniSearch matches
201
- - `hybridWeight: 0.5` → balanced semantic + keyword (50/50 blend)
202
- - `hybridWeight: 0.0` → pure keyword ranking, skips `embed()` entirely (no LLM API cost)
203
-
204
- **Per-call overrides:**
205
-
206
- ```typescript
207
- const { data } = useMemoryRead('user-123', 'preferences', {
208
- maxResults: 5,
209
- preFilterLimit: 20, // Tighter pre-filter for speed
210
- hybridWeight: 0.5, // More keyword weight
211
- });
212
-
213
- // Multi-entity hook — pass array entityId + tierWeights
214
- const { data: multiData } = useMemoryRead(
215
- ['tier_wisdom', 'tier_fact', 'tier_working'],
216
- 'preferences',
217
- {
218
- maxResults: 8,
219
- tierWeights: {
220
- tier_wisdom: 2,
221
- tier_fact: 1,
222
- tier_working: 0.25,
223
- },
224
- // includeZeroWeightEntities: true — include 0-weight entities as bottom-ranked filler
225
- }
226
- );
227
- // multiData?.factScores — Record<factId, weightedScore> | undefined (array entityId only, populated when query is non-empty and at least one fact scored)
228
- // multiData?.metadata — { query, entityIds, tierWeights }
229
- ```
230
-
231
- ## Hooks
232
-
233
- ### `useMemoryRead(entityId, query, options?)`
234
-
235
- Fetch memory reactively. `entityId` accepts a string or string array for multi-entity reads. Auto-refetches when `entityId`, `query`, `wiki`, or `options` change on a behavioral level: `maxResults`, `preFilterLimit`, `hybridWeight`, and `tierWeights` are tracked. `tierWeights` entries at the default weight (`1.0`) are normalized to omission (passing `1.0` explicitly is spec-equivalent to omitting that key). `includeZeroWeightEntities: false` and `undefined` are equivalent in core (both skip zero-weight entities); only toggling to `true` triggers a refetch.
236
-
237
- ```typescript
238
- const { data, isPending, error, refetch } = useMemoryRead('user-123', 'preferences');
239
- // data: MemoryBundle | null
240
-
241
- // Multi-entity
242
- const { data: multi } = useMemoryRead(['tier_wisdom', 'tier_fact'], 'preferences');
243
- // multi?.factScores, multi?.metadata available when entityId is array
244
-
245
- if (isPending) return <div>Loading...</div>;
246
- if (error) return <div>Error: {error.message}</div>;
247
-
248
- return (
249
- <div>
250
- {data?.facts.map(fact => (
251
- <div key={fact.id}>
252
- <strong>{fact.title}</strong>: {fact.body}
253
- </div>
254
- ))}
255
- </div>
256
- );
257
- ```
258
-
259
- **With tuning overrides:**
260
-
261
- ```typescript
262
- const { data } = useMemoryRead('user-123', 'preferences', {
263
- maxResults: 5,
264
- hybridWeight: 0.8,
265
- });
266
- ```
267
-
268
- ### `useWikiWrite()`
269
-
270
- Record observations and events. The librarian job extracts facts from accumulated events. This does not currently invalidate `useMemoryRead()` results automatically, so existing readers keep their previous `data` until their inputs change or `refetch()` is called.
271
-
272
- ```typescript
273
- const { execute, isPending, error } = useWikiWrite();
274
-
275
- const handleSave = async () => {
276
- try {
277
- await execute('user-123', {
278
- event_type: 'observation',
279
- summary: 'User prefers async/await'
280
- });
281
- } catch (e) {
282
- console.error('Write failed:', e);
283
- }
284
- };
285
-
286
- return <button onClick={handleSave} disabled={isPending}>Save</button>;
287
- ```
288
-
289
- ### `useWikiIngest()`
290
-
291
- Ingest documents into memory. Parses facts and tasks from document chunks.
292
-
293
- ```typescript
294
- const { execute, isPending, error } = useWikiIngest();
295
-
296
- const handleIngest = async (document: string) => {
297
- const sourceHash = await calculateHash(document);
298
- try {
299
- await execute('user-123', {
300
- sourceRef: 'doc-readme',
301
- sourceHash,
302
- documentChunk: document,
303
- // Optional: runtime override for this specific ingest call only.
304
- // Must include the JSON output contract — overrides replace the entire default prompt.
305
- promptOverride: `Strict technical extraction. Focus on APIs: {{documentChunk}}\n\nReturn ONLY valid JSON: { "facts": [{ "title": "string", "body": "string", "tags": ["string"], "confidence": "certain|inferred|tentative" }] }. No markdown.`,
306
- });
307
- } catch (e) {
308
- console.error('Ingest failed:', e);
309
- }
310
- };
311
- ```
312
-
313
- ### `useWikiForget()`
314
-
315
- Delete entries from memory by ID.
316
-
317
- ```typescript
318
- const { execute, isPending, error } = useWikiForget();
319
-
320
- const handleDelete = async (factId: string) => {
321
- try {
322
- await execute('user-123', { entryId: factId });
323
- } catch (e) {
324
- console.error('Delete failed:', e);
325
- }
326
- };
327
- ```
328
-
329
- ### `useWikiMaintenance()`
330
-
331
- Run background maintenance jobs: librarian (deduplication/fact extraction), heal (LLM-driven fact review: removes orphaned facts, downgrades stale inferences, repairs incorrect facts), reembed (convert TEXT embeddings to BLOB / update after model change), prune (hard-delete soft-deleted entries/tasks after the retention window and prune old events).
332
-
333
- ```typescript
334
- const { runLibrarian, runHeal, runReembed, runPrune, isPending, error, lastResult } = useWikiMaintenance();
335
-
336
- // Deduplicate and consolidate facts from events
337
- await runLibrarian('user-123');
338
-
339
- // Run with a one-off runtime override (applies only to this call, not future auto-runs).
340
- // Must include the JSON output contract — overrides replace the entire default prompt.
341
- await runLibrarian('user-123', {
342
- promptOverride: `One-off extraction task:\n{{events}}\n\nReturn ONLY valid JSON: { "facts": [{ "title": "string", "body": "string", "tags": ["string"], "confidence": "certain|inferred|tentative" }], "tasks": [{ "description": "string", "priority": 0 }] }. No markdown.`,
343
- });
344
-
345
- // LLM-driven fact review: remove orphaned/stale facts, repair incorrect inferences
346
- await runHeal('user-123');
347
-
348
- // Re-embed all facts with the current provider (e.g. after switching models or
349
- // enabling an embed provider for the first time — default always re-embeds all):
350
- const { embedded, skipped, failed } = await runReembed('user-123');
351
- // After a round-trip export/import on the same model, skip facts that already have vectors:
352
- const { embedded: embeddedRoundtrip, skipped: skippedRoundtrip, failed: failedRoundtrip } = await runReembed('user-123', { skipExisting: true });
353
-
354
- // Hard-delete soft-deleted entries/tasks after retention and prune old events
355
- await runPrune('user-123');
356
- ```
357
-
358
- > **`lastResult` note**: `runLibrarian`, `runHeal`, and `runPrune` each update `lastResult` on success. `runReembed` intentionally does not — it clears `lastResult` to null at start but leaves it null on completion. This avoids a source-breaking change to the `MaintenanceResult` type for consumers that exhaustively switch on `lastResult.operation`. Use the `Promise` return value to inspect reembed results.
359
-
360
- ### `useWikiHasChanged()`
361
-
362
- Check if a source document has changed since last ingest.
363
-
364
- ```typescript
365
- const { execute, lastResult, isPending, error } = useWikiHasChanged();
366
-
367
- const handleCheckChanges = async (sourceRef: string, sourceHash: string) => {
368
- const changed = await execute('user-123', sourceRef, sourceHash);
369
- if (changed) {
370
- console.log('Document has been updated, re-ingest recommended');
371
- }
372
- };
373
- ```
374
-
375
- ### `useWikiExport()`
376
-
377
- Export memory dump.
378
-
379
- ```typescript
380
- const { execute, lastResult, isPending, error } = useWikiExport();
381
- await execute(['user-123']);
382
- // lastResult: MemoryDump | null
383
- ```
384
-
385
- ### `useEntityStatus(entityId)`
386
-
387
- Live status for an entity's background jobs (ingest, librarian, heal). Updates whenever a transition occurs — no polling.
388
-
389
- ```typescript
390
- const { ingesting, librarian, heal } = useEntityStatus('user-123');
391
-
392
- if (ingesting || librarian || heal) {
393
- return <Spinner label={ingesting ? 'Ingesting…' : librarian ? 'Organizing…' : 'Healing…'} />;
394
- }
395
- ```
396
-
397
- ### `useOntologyManifest(entityId)`
398
-
399
- Reactive read — fetches on mount and when `entityId` or `wiki` changes:
400
-
401
- ```typescript
402
- import { useOntologyManifest } from '@equationalapplications/react-llm-wiki';
403
-
404
- const { manifest, mode, isPending, error, refetch } = useOntologyManifest('user-123');
405
- // manifest: OntologyManifest | null
406
- // mode: OntologyMode | null ('strict' | 'emergent' | 'off' when present)
407
- ```
408
-
409
- Note: `manifest` and `mode` are `null` when the entity has no persisted or seeded manifest (`getOntologyManifest` returned `null`). Call `refetch()` after mutations to refresh.
410
-
411
- ### `useSetOntologyManifest()`
412
-
413
- Mutation — same `{ execute, isPending, error, lastResult }` contract as `useWikiWrite`:
414
-
415
- ```typescript
416
- import { useOntologyManifest, useSetOntologyManifest } from '@equationalapplications/react-llm-wiki';
417
-
418
- export function OntologySettings({ entityId }: { entityId: string }) {
419
- const { manifest, mode, refetch } = useOntologyManifest(entityId);
420
- const { execute, isPending, error } = useSetOntologyManifest();
421
-
422
- const handleSave = async () => {
423
- await execute(entityId, {
424
- node_types: [{ type: 'person', description: 'An individual.' }],
425
- edge_types: [{
426
- type: 'reports_to',
427
- source_type: 'person',
428
- target_type: 'person',
429
- description: 'Reporting hierarchy.',
430
- }],
431
- }, { mode: 'strict' });
432
- refetch();
433
- };
434
-
435
- // render manifest/mode; wire handleSave to a save button
436
- }
437
- ```
438
-
439
- Global defaults and `seedManifests` bootstrap are configured at construction time via `createWiki(..., { config: { ontology: ... } })`. See the [core package README § Per-Entity Seeded Ontology](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/core/README.md#per-entity-seeded-ontology) for mode semantics and manifest schema.
440
-
441
- `useSetOntologyManifest` does not automatically refresh `useOntologyManifest` — call `refetch()` after a successful `execute()`, same as `useWikiWrite` + `useMemoryRead`.
442
-
443
- ### `useWikiTraversal(entityId, options)`
444
-
445
- Reactive read — fetches on mount and whenever `entityId` or `options` change. Walks the knowledge graph N hops outward from a fact (`options.sourceId`) using edges written by `runLibrarian()`/`ingestDocument()`'s Seeded Ontology extraction pass:
446
-
447
- ```typescript
448
- import { useWikiTraversal, formatGraphContext } from '@equationalapplications/react-llm-wiki';
449
-
450
- const { nodes, edges, isPending, error, refetch } = useWikiTraversal('user-123', {
451
- sourceId: 'fact_42',
452
- maxDepth: 2,
453
- direction: 'both',
454
- });
455
-
456
- const promptContext = formatGraphContext({ nodes, edges });
457
- ```
458
-
459
- - `maxDepth` is clamped to `[1, 3]` regardless of input.
460
- - `edgeTypes: []` (explicit empty array) matches nothing; omitting it matches all edge types.
461
- - Defaults (`maxTraversalNodes`, `minTraversalConfidence`, `traversalDirection`, `excludeSourceTypes`) can be set globally via `createWiki(..., { config: { maxTraversalNodes: 20, ... } })` and overridden per-call.
462
- - `formatGraphContext()` is a pure function — call it with the hook's `{ nodes, edges }` to get a dense text block suitable for prompt injection.
463
-
464
- ## Multi-Entity Reads
465
-
466
- `useMemoryRead` accepts a single entity ID or an array to search across namespaces in one pass. Pass `tierWeights` to apply per-entity score multipliers before the global top-K slice:
467
-
468
- ```typescript
469
- const { data } = useMemoryRead(
470
- ['tier_wisdom', 'tier_fact', 'tier_working'],
471
- 'What are my preferences?',
472
- {
473
- maxResults: 8,
474
- tierWeights: {
475
- tier_wisdom: 2, // boost curated notes 2×
476
- tier_fact: 1, // neutral
477
- tier_working: 0.25, // downrank unvetted context
478
- },
479
- }
480
- );
481
-
482
- if (data) {
483
- console.log(data.facts); // merged, globally ranked
484
- console.log(data.factScores); // Record<factId, weightedScore>
485
- console.log(data.metadata); // { query, entityIds, tierWeights }
486
- }
487
-
488
- For full details on `{{mustache}}` prompt templating and the strict distinction between global auto-runs and runtime overrides, see [Prompt Management & Overrides](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/core/README.md#prompt-management--overrides) in `@equationalapplications/core-llm-wiki`.
489
-
490
- ## Component Lifecycle
491
-
492
- ```mermaid
493
- flowchart TD
494
- A["<WikiProvider wiki={wiki}>"] --> B["App Components"]
495
- B --> C{"Use Hook?"}
496
- C -->|"useMemoryRead(entityId, query, options?)"| D["[Read Memory]"]
497
- C -->|"useWikiWrite()"| E["[Write Memory]"]
498
- C -->|"useWikiIngest()"| F["[Ingest Document]"]
499
- C -->|"useWikiForget()"| G["[Delete Memory]"]
500
- C -->|"useWikiMaintenance()"| H["[Run Jobs]"]
501
- C -->|"useOntologyManifest(entityId)"| S["[Read Ontology]"]
502
- C -->|"useSetOntologyManifest()"| T["[Update Ontology]"]
503
- D --> I{"entityId, query,<br/>ReadOptions, or wiki changed?"}
504
- I -->|"Yes"| J["Auto-refetch"]
505
- I -->|"No"| K["Return cached data"]
506
- J --> L["Trigger read()"]
507
- L --> M["Embed query<br/>if embed available"]
508
- M --> N["Phase 1: Score facts<br/>Phase 2: Fetch winners"]
509
- N --> O["Update component state"]
510
- O --> P["Re-render with data"]
511
- S --> I2{"entityId or wiki changed?"}
512
- I2 -->|"Yes"| J2["Auto-refetch"]
513
- I2 -->|"No"| K2["Return cached manifest/mode"]
514
- J2 --> L2["Trigger getOntologyManifest()"]
515
- L2 --> O2["Update component state"]
516
- O2 --> P2["Re-render with manifest/mode"]
517
- E --> Q["Execute write()"]
518
- F --> Q
519
- G --> Q
520
- H --> Q
521
- T --> Q
522
- Q --> R["Write completes"]
523
- ```
524
-
525
- **Data flow:**
526
- 1. **Wrap app** with `<WikiProvider wiki={wiki}>` — provides wiki context
527
- 2. **Use hooks** in components — access memory reactively
528
- 3. **Read operations** auto-refetch when `entityId`, `query`, `wiki`, or `ReadOptions` values change; call `refetch()` to refresh manually
529
- 4. **Ontology reads** auto-refetch when `entityId` or `wiki` changes; call `refetch()` manually after ontology mutations
530
- 5. **Write operations** (write, ingest, forget, maintenance) do not automatically re-trigger `useMemoryRead`; call `refetch()` after a write to refresh read results
531
- 6. **Ontology writes** (`useSetOntologyManifest`) do not automatically re-trigger `useOntologyManifest` in the same component unless `refetch()` is called after `execute()` succeeds
532
- 7. **Re-render** with new data flowing back to UI
533
-
534
- ## Retrieval Engine Internals
535
-
536
- ```mermaid
537
- flowchart TD
538
- A["read(entityId | entityId[], query, options?)"] --> B{hybridWeight = 0?}
539
- B -->|Yes| C["MiniSearch only<br/>(skip embed)"]
540
- B -->|No| D{embed available?}
541
- D -->|No| C
542
- D -->|Yes| F["Embed query"]
543
- F -->|throws| E["onRetrievalFallback<br/>callback"]
544
- E --> C
545
- F -->|succeeds| G{preFilterLimit<br/>active?}
546
- G -->|Yes| H["MiniSearch pre-filter<br/>top K candidates"]
547
- H --> I["Phase 1: Cosine score<br/>top K candidates"]
548
- G -->|No| J["Phase 1: Cosine score<br/>all facts"]
549
- J --> K["Cache vectors<br/>in-memory<br/>(full scan only)"]
550
- K --> L{hybridWeight = 1?}
551
- I --> L
552
- L -->|Yes| M["Pure semantic<br/>ranking"]
553
- L -->|No| N["Hybrid blend:<br/>semantic + keyword<br/>via MiniSearch"]
554
- M --> O["Phase 2: Fetch full rows<br/>top maxResults"]
555
- N --> O
556
- C --> P["MiniSearch ranking"]
557
- P --> O
558
- O --> R["Track access"]
559
- R --> Q["Return MemoryBundle"]
560
- ```
561
-
562
- The flowchart shows:
563
- 1. **Fast-path** when `hybridWeight = 0` (pure keyword, no embed cost)
564
- 2. **Fallback chain** when embed unavailable (MiniSearch silently) or throws (`onRetrievalFallback` callback, then MiniSearch)
565
- 3. **Pre-filtering** to limit cosine scoring to top-K keyword matches (O(N) → O(K))
566
- 4. **Two-phase SELECT**: phase 1 scores all/filtered facts with minimal columns, phase 2 fetches full rows for winners
567
- 5. **Hybrid scoring** to blend semantic and keyword rankings
568
- 6. **Vector caching** on full scans only; reads with `preFilterLimit` active skip cache population
46
+ The [React quickstart](https://equationalapplications.github.io/expo-llm-wiki/start/quickstart-react/) shows the sql.js adapter and `WikiProvider` setup. Not using React? See [vanilla JavaScript](https://equationalapplications.github.io/expo-llm-wiki/start/quickstart-react/#not-using-react).
569
47
 
570
48
  ## Monorepo Ecosystem
571
49
 
@@ -587,4 +65,4 @@ MIT
587
65
 
588
66
  ---
589
67
 
590
- Made with ❤️ by Equational Applications LLC. [https://equationalapplications.com/](https://equationalapplications.com/)
68
+ Made with ❤️ by Equational Applications LLC. [https://equationalapplications.com/](https://equationalapplications.com/)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@equationalapplications/react-llm-wiki",
3
- "version": "7.15.1",
3
+ "version": "7.16.0",
4
4
  "description": "In-browser LLM memory for React web apps. Bring your own SQLite adapter (e.g., sql.js WebAssembly) for a complete, zero-server RAG experience.",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",
@@ -50,13 +50,13 @@
50
50
  "bugs": {
51
51
  "url": "https://github.com/equationalapplications/expo-llm-wiki/issues"
52
52
  },
53
- "homepage": "https://github.com/equationalapplications/expo-llm-wiki/tree/main/packages/react#readme",
53
+ "homepage": "https://equationalapplications.github.io/expo-llm-wiki/packages/react/",
54
54
  "publishConfig": {
55
55
  "access": "public",
56
56
  "registry": "https://registry.npmjs.org"
57
57
  },
58
58
  "dependencies": {
59
- "@equationalapplications/core-llm-wiki": "7.15.1"
59
+ "@equationalapplications/core-llm-wiki": "7.16.0"
60
60
  },
61
61
  "engines": {
62
62
  "node": ">=20"