@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.
- package/README.md +21 -543
- 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
|
-
- **
|
|
16
|
-
- **
|
|
17
|
-
- **
|
|
18
|
-
- **
|
|
19
|
-
- **
|
|
20
|
-
- **
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
const
|
|
162
|
-
|
|
163
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|
|
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.
|
|
59
|
+
"@equationalapplications/core-llm-wiki": "7.16.0"
|
|
60
60
|
},
|
|
61
61
|
"engines": {
|
|
62
62
|
"node": ">=20"
|