@equationalapplications/expo-llm-wiki 7.15.1 → 7.16.0

package/README.md

@@ -10,21 +10,14 @@ Local-first LLM memory for Expo and React Native. Combines the core semantic sea
 
 > Inspired by [Andrej Karpathy's LLM Wiki memory spec](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
 
-## Features
+**📖 Documentation: [equationalapplications.github.io/expo-llm-wiki/packages/expo](https://equationalapplications.github.io/expo-llm-wiki/packages/expo/)**. Start with the [Expo quickstart](https://equationalapplications.github.io/expo-llm-wiki/start/quickstart-expo/).
 
-- **Expo-ready** — Pre-configured for React Native + Expo
-- **Built on `expo-sqlite`** — Stable, well-supported SQLite driver
-- **Hermes-ready** — Secure record ID generation via [`expo-crypto`](https://docs.expo.dev/versions/latest/sdk/crypto/); wired automatically at import (no manual `crypto` polyfill)
-- **Semantic search** — Vector embeddings via `embed` function, with MiniSearch fallback
-- **Retrieval tuning** — Per-call overrides for search behavior (pre-filter, hybrid blend, tier weights)
-- **Multi-entity reads** — Search across multiple `entity_id` namespaces in one pass with `tierWeights`
-- **Source provenance** — `WikiFact.source_type` distinguishes immutable document facts (`immutable_document`) from mutable derived/user facts. Immutable document content is protected from librarian/heal rewriting and only changed by `forget()` or re-ingest.
-- **Seeded ontologies** — Enforce strict taxonomies or allow emergent graph relationship extraction (`useOntologyManifest`, `useSetOntologyManifest`; Strict, Emergent, or Off; defaults to Off).
-- **React hooks** — `WikiProvider`, `useMemoryRead`, `useOntologyManifest`, `useSetOntologyManifest`, `useWikiTraversal`, and all other hooks re-exported from `@equationalapplications/expo-llm-wiki`
-- **Full-featured memory** — Facts, tasks, events, maintenance jobs (librarian, heal, reembed, prune)
-- **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`).
+## Features
 
-- **GraphRAG on React Native** — `useWikiTraversal` + `formatGraphContext` give you the same SQLite-only graph retrieval as the core package; pair with `@equationalapplications/schema-org-llm-wiki` for the canonical ontology. See [root README: GraphRAG](../../README.md#graphrag-sql-only-graph-retrieval).
+- **Expo-ready.** Core plus an `expo-sqlite` adapter, so there's nothing to wire up.
+- **Hermes-ready.** Secure record IDs through [`expo-crypto`](https://docs.expo.dev/versions/latest/sdk/crypto/), registered automatically on import. No `crypto` polyfill needed.
+- **React hooks.** `WikiProvider`, `useMemoryRead`, `useWikiTraversal` and the rest of [`react-llm-wiki`](https://equationalapplications.github.io/expo-llm-wiki/reference/hooks/), re-exported.
+- **Everything in core.** Semantic and keyword search, multi-entity reads, seeded ontologies and [GraphRAG](https://equationalapplications.github.io/expo-llm-wiki/guides/graphrag/), background maintenance, and OKF import and export.
 
 ## Installation
 
@@ -33,435 +26,33 @@ npx expo install expo-sqlite expo-crypto
 npm install @equationalapplications/expo-llm-wiki
 ```
 
-`expo-crypto` is a peer dependency. The package wires its `getRandomValues` into the core engine at module load — Hermes and React Native lack the Web `crypto` global, and wiki writes need a cryptographically secure random source for record IDs. No extra setup is required after install; importing `@equationalapplications/expo-llm-wiki` (or the `/factory` subpath) activates it before any `createWiki()` call.
-
-## Semantic Search
-
-Enable vector-based retrieval by providing an `embed` function:
-
-```typescript
-import { createWiki } from '@equationalapplications/expo-llm-wiki';
-import { openDatabaseSync } from 'expo-sqlite';
-
-const db = openDatabaseSync('wiki.db');
-
-const wiki = createWiki(db, {
-  config: {
-    // Optimize retrieval for large memory stores
-    preFilterLimit: 50,    // Limit cosine scoring to top-50 keyword matches
-    hybridWeight: 0.7,     // Blend semantic (0.7) + keyword (0.3)
-  },
-  llmProvider: {
-    generateText: async ({ systemPrompt, userPrompt }) => {
-      // Your LLM call — must return the model output as a string
-      return 'Model output';
-    },
-    maxOutputTokens: 4096, // optional — your model's output ceiling; lets maintenance passes size their LLM calls
-    embed: async (text: string) => {
-      // Your embedding service (e.g., OpenAI, Cohere)
-      // Use an absolute URL — React Native / Expo apps do not have a browser
-      // origin to resolve relative URLs against on device or simulator.
-      const response = await fetch('https://your-api.example.com/api/embed', { 
-        method: 'POST', 
-        body: JSON.stringify({ text }) 
-      });
-      const { embedding } = await response.json();
-      return embedding; // number[]
-    },
-  },
-  onRetrievalFallback: (error) => {
-    console.warn('Embedding unavailable, using keyword search:', error);
-  },
-});
-
-await wiki.setup();
-
-// Semantic query
-const memory = await wiki.read('user-123', 'what activities should I do this weekend?');
-// Matches facts like "Saturday hiking trip" even with no lexical overlap
-
-// Per-call overrides
-const fasterSearch = await wiki.read('user-123', 'activities', {
-  maxResults: 5,
-  preFilterLimit: 20,      // Tighter pre-filter for speed
-  hybridWeight: 0.5,       // More keyword weight
-});
-
-// Multi-entity with tier weights
-const multiMemory = await wiki.read(['tier_wisdom', 'tier_fact', 'tier_working'], 'activities', {
-  maxResults: 8,
-  tierWeights: {
-    tier_wisdom: 2,      // boost curated notes 2×
-    tier_fact: 1,        // neutral baseline
-    tier_working: 0.25,  // downrank unvetted context
-  },
-  // includeZeroWeightEntities: true — include 0-weight entities as bottom-ranked filler
-});
-// multiMemory.factScores — Record<factId, weightedScore> | undefined (array entityId only, populated when query is non-empty and at least one fact scored)
-// multiMemory.metadata  — { query, entityIds, tierWeights }
-```
-
-## Configuration
-
-All `WikiConfig` fields are optional:
-
-```typescript
-const wiki = createWiki(db, {
-  llmProvider: { /* ... */ },
-  config: {
-    tablePrefix: 'llm_wiki_',          // default: 'llm_wiki_'
-    maxResults: 10,                    // default: 10
-    autoLibrarianThreshold: 20,        // default: 20 — events before librarian auto-runs
-    autoHealThreshold: 100,            // default: 100 — events before heal auto-runs
-    maxChunkLength: 12000,             // default: 12000 (char count per ingestDocument chunk)
-    chunkOverlap: 400,                 // default: 400 (overlap between chunks in characters)
-    chunkConcurrency: 1,               // default: 1 (parallel LLM calls per ingestDocument)
-    pruneRetainSoftDeletedFor: 7,      // default: 7 (days before hard-deleting soft-deleted facts)
-    pruneEventsAfter: 30,              // default: 30 (days before hard-deleting old events)
-    orphanAfterDays: 30,               // default: 30 (days before runHeal flags sourceless facts; null to disable)
-    staleInferredAfterDays: 60,        // default: 60 (days before runHeal downgrades inferred facts; null to disable)
-    preFilterLimit: 50,                // default: undefined — MiniSearch pre-filter before cosine scan; recommended for >500 facts
-    hybridWeight: 0.7,                 // default: undefined — blend semantic (1.0) ↔ keyword (0.0); pure semantic when unset
-    excludeDrafts: false,              // default: false — hide unreviewed drafts from reads; traversal skips discovered drafts (a draft start fact is still returned)
-    grounding: { mode: 'off' },        // default: off — 'draft' stores facts that don't quote their source as drafts
-
-    // Global prompt overrides — librarianSystemPrompt and healSystemPrompt apply to write() auto-runs;
-    // ingestSystemPrompt applies only to explicit ingestDocument() calls.
-    // ⚠ Overrides replace the entire default prompt, including the JSON output contract.
-    // Your prompt must instruct the LLM to return the required JSON shape — see packages/core/README.md#prompt-management--overrides.
-    prompts: {
-      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.`,
-      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.`,
-      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.`,
-    },
-  },
-});
-```
-
-**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).
-
-```tsx
-import { useWiki } from '@equationalapplications/expo-llm-wiki';
+Use `npx expo install` so Expo picks native builds that match your SDK.
 
-function DraftReview({ entityId }: { entityId: string }) {
-  const wiki = useWiki(); // the WikiMemory instance; throws outside <WikiProvider>
-  const loadDrafts = () => wiki.listDrafts(entityId, { limit: 20 }); // → { facts, nextCursor }
-  // ...
-}
-```
+| Peer dependency | Range |
+|---|---|
+| `expo-sqlite` | `^14 \|\| ^15 \|\| ^55 \|\| ^56 \|\| ^57 \|\| ^58` |
+| `expo-crypto` | `>=12` |
+| `react` | `>=17` |
 
-`useWiki()` also exposes the read-only health and instruction APIs for components that need them:
+## Quick look
 
 ```tsx
-function HealthAndInstructions({ entityId, batch }: { entityId: string; batch: Array<{ sourceRef: string; sourceHash: string }> }) {
-  const wiki = useWiki();
+import * as SQLite from 'expo-sqlite';
+import { createWiki, WikiProvider, useMemoryRead } from '@equationalapplications/expo-llm-wiki';
 
-  // Lint: read-only health report for one entity (dangling edges, manifest violations, drafts, etc.)
-  const loadReport = () => wiki.lint(entityId);
-  // → { danglingEdges, manifestViolations, untypedFacts, drafts, unverifiedInferred,
-  //     sample: { danglingEdgeIds, manifestViolationEdgeIds } }
-
-  // pendingSources: per-input change status including the partial-ingest state.
-  const loadStatuses = () => wiki.pendingSources(entityId, batch);
-  // → Array<{ sourceRef: string; status: 'new' | 'changed' | 'partial' | 'current' }>
-
-  // getInstructions: effective system prompts for each writer, with overrides applied.
-  const loadInstructions = () => wiki.getInstructions(entityId);
-  // → { ingest, librarian, heal, ontologyBackfill }
-}
-```
-
-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).
-
-## Retrieval Tuning
-
-Optimize `read()` performance and blend retrieval strategies:
-
-```typescript
-const config = {
-  // Limit cosine similarity scoring to top-K MiniSearch keyword candidates
-  preFilterLimit: 50,
-  
-  // Blend semantic and keyword scores (0.0 = pure keyword, 1.0 = pure semantic)
-  hybridWeight: 0.7,
-  
-  // Max results returned per read
-  maxResults: 10,
-};
-
-const wiki = createWiki(db, {
-  config,
-  llmProvider: { /* ... */ },
-});
-```
-
-**Hybrid scoring blends:**
-- `hybridWeight: 1.0` → pure semantic ranking among the candidates being scored; if `preFilterLimit` is set, semantic scoring is still limited to the top-K MiniSearch matches
-- `hybridWeight: 0.5` → balanced semantic + keyword (50/50 blend)
-- `hybridWeight: 0.0` → pure keyword ranking, skips `embed()` entirely (no LLM API cost)
-
-**Pre-filtering optimization:**
-When `preFilterLimit: 50` is set with 1000 facts, cosine similarity is computed only for the top 50 MiniSearch keyword matches, reducing O(N) scoring to O(50).
-
-## Usage
-
-```typescript
-import { createWiki } from '@equationalapplications/expo-llm-wiki';
-import { openDatabaseSync } from 'expo-sqlite';
-
-const db = openDatabaseSync('wiki.db');
-
-const wiki = createWiki(db, {
-  llmProvider: {
-    generateText: async ({ systemPrompt, userPrompt }) => {
-      // Your LLM call — must return the model output as a string
-      return 'Model output';
-    },
-  },
-});
-
-// Initialize tables (call once on app startup)
+const db = await SQLite.openDatabaseAsync('app.db');
+const wiki = createWiki(db, { llmProvider }); // pass the expo-sqlite database directly
 await wiki.setup();
 
-// Auto-runs: uses config.prompts for background librarian/heal triggers
-await wiki.write('user-123', { event_type: 'observation', summary: '...' });
-
-// Manual executions: runtime promptOverride applies only to this single call.
-// Must include the JSON output contract — overrides replace the entire default prompt.
-await wiki.runLibrarian('user-123', {
-  promptOverride: `Strict domain 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.`,
-});
-
-await wiki.ingestDocument('user-123', {
-  sourceRef: 'doc-1',
-  sourceHash: sha256(content),
-  documentChunk: content,
-  promptOverride: `Focus strictly on technical APIs: {{documentChunk}}\n\nReturn ONLY valid JSON: { "facts": [{ "title": "string", "body": "string", "tags": ["string"], "confidence": "certain|inferred|tentative" }] }. No markdown.`,
-});
-```
-
-## With React
-
-`@equationalapplications/expo-llm-wiki` re-exports all hooks and `WikiProvider` from `@equationalapplications/react-llm-wiki`:
-
-```typescript
-import { WikiProvider } from '@equationalapplications/expo-llm-wiki';
-
-<WikiProvider wiki={wiki}>
-  <MyApp />
-</WikiProvider>
-```
-
-Then use hooks in components:
-
-```typescript
-import { useMemoryRead } from '@equationalapplications/expo-llm-wiki';
-
-export function UserProfile({ userId }: { userId: string }) {
-  const { data, isPending } = useMemoryRead(userId, 'preferences');
-  
-  if (isPending) return <Text>Loading...</Text>;
-  return <Text>{data?.facts.map(f => f.title).join(', ')}</Text>;
-}
-```
-
-For live background-job status (e.g. a loading spinner while a document ingests or the librarian runs):
-
-```typescript
-import { useEntityStatus } from '@equationalapplications/expo-llm-wiki';
-
-export function EntityLoadingSpinner({ entityId }: { entityId: string }) {
-  const { ingesting, librarian, heal } = useEntityStatus(entityId);
-  if (!ingesting && !librarian && !heal) return null;
-  return <Spinner label={ingesting ? 'Ingesting…' : librarian ? 'Organizing…' : 'Healing…'} />;
-}
-```
-
-### `useOntologyManifest(entityId)`
-
-Reactive read — fetches on mount and when `entityId` or `wiki` changes:
-
-```typescript
-import { useOntologyManifest } from '@equationalapplications/expo-llm-wiki';
-
-const { manifest, mode, isPending, error, refetch } = useOntologyManifest('user-123');
-// manifest: OntologyManifest | null
-// mode: OntologyMode | null ('strict' | 'emergent' | 'off' when present)
-```
-
-Note: `manifest` and `mode` are `null` when the entity has no persisted or seeded manifest (`getOntologyManifest` returned `null`). Call `refetch()` after mutations to refresh.
-
-### `useSetOntologyManifest()`
-
-Mutation — same `{ execute, isPending, error, lastResult }` contract as `useWikiWrite`:
-
-```typescript
-import { useOntologyManifest, useSetOntologyManifest } from '@equationalapplications/expo-llm-wiki';
-
-export function OntologySettings({ entityId }: { entityId: string }) {
-  const { manifest, mode, refetch } = useOntologyManifest(entityId);
-  const { execute, isPending, error } = useSetOntologyManifest();
-
-  const handleSave = async () => {
-    await execute(entityId, {
-      node_types: [{ type: 'person', description: 'An individual.' }],
-      edge_types: [{
-        type: 'reports_to',
-        source_type: 'person',
-        target_type: 'person',
-        description: 'Reporting hierarchy.',
-      }],
-    }, { mode: 'strict' });
-    refetch();
-  };
-
-  // render manifest/mode; wire handleSave to a save button
+function App() {
+  const { data, isPending } = useMemoryRead('user-123', 'preferences');
+  // ...
 }
-```
-
-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.
-
-`useSetOntologyManifest` does not automatically refresh `useOntologyManifest` — call `refetch()` after a successful `execute()`, same as `useWikiWrite` + `useMemoryRead`.
-
-### `useWikiTraversal(entityId, options)`
-
-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:
-
-```typescript
-import { useWikiTraversal, formatGraphContext } from '@equationalapplications/expo-llm-wiki';
-
-const { nodes, edges, isPending, error, refetch } = useWikiTraversal('user-123', {
-  sourceId: 'fact_42',
-  maxDepth: 2,
-  direction: 'both',
-});
-
-const promptContext = formatGraphContext({ nodes, edges });
-```
-
-- `maxDepth` is clamped to `[1, 3]` regardless of input.
-- `edgeTypes: []` (explicit empty array) matches nothing; omitting it matches all edge types.
-- Defaults (`maxTraversalNodes`, `minTraversalConfidence`, `traversalDirection`, `excludeSourceTypes`) can be set globally via `createWiki(..., { config: { maxTraversalNodes: 20, ... } })` and overridden per-call.
-- `formatGraphContext()` is a pure function — call it with the hook's `{ nodes, edges }` to get a dense text block suitable for prompt injection.
-
-## Component Lifecycle
-
-```mermaid
-flowchart TD
-    A["<WikiProvider wiki={wiki}>"] --> B["App Components"]
-    B --> C{"Use Hook?"}
-    C -->|"useMemoryRead(entityId, query, options?)"| D["[Read Memory]"]
-    C -->|"useWikiWrite()"| E["[Write Memory]"]
-    C -->|"useWikiIngest()"| F["[Ingest Document]"]
-    C -->|"useWikiForget()"| G["[Delete Memory]"]
-    C -->|"useWikiMaintenance()"| H["[Run Jobs]"]
-    C -->|"useOntologyManifest(entityId)"| S["[Read Ontology]"]
-    C -->|"useSetOntologyManifest()"| T["[Update Ontology]"]
-    D --> I{"entityId, query, wiki,<br/>or ReadOptions changed?"}
-    I -->|"Yes"| J["Auto-refetch"]
-    I -->|"No"| K["Return cached data"]
-    J --> L["Trigger read()"]
-    L --> M["Embed query<br/>if embed available"]
-    M --> N["Phase 1: Score facts<br/>Phase 2: Fetch winners"]
-    N --> O["Update component state"]
-    O --> P["Re-render with data"]
-    S --> I2{"entityId or wiki changed?"}
-    I2 -->|"Yes"| J2["Auto-refetch"]
-    I2 -->|"No"| K2["Return cached manifest/mode"]
-    J2 --> L2["Trigger getOntologyManifest()"]
-    L2 --> O2["Update component state"]
-    O2 --> P2["Re-render with manifest/mode"]
-    E --> Q["Execute write()"]
-    F --> Q
-    G --> Q
-    H --> Q
-    T --> Q
-    Q --> R["Write completes"]
-```
-
-**Data flow:**
-1. **Wrap app** with `<WikiProvider wiki={wiki}>` — provides wiki context
-2. **Use hooks** in components — access memory reactively
-3. **Read operations** auto-refetch when `entityId`, `query`, `wiki`, or `ReadOptions` values change; call `refetch()` to refresh manually
-4. **Ontology reads** auto-refetch when `entityId` or `wiki` changes; call `refetch()` manually after ontology mutations
-5. **Write operations** (write, ingest, forget, maintenance) do not automatically re-trigger `useMemoryRead`; call `refetch()` after a write to refresh read results
-6. **Ontology writes** (`useSetOntologyManifest`) do not automatically re-trigger `useOntologyManifest` in the same component unless `refetch()` is called after `execute()` succeeds
-7. **Re-render** with new data flowing back to UI
-
-## Retrieval Engine Internals
-
-```mermaid
-flowchart TD
-    A["read(entityId | entityId[], query, options?)"] --> B{hybridWeight = 0?}
-    B -->|Yes| C["MiniSearch only<br/>(skip embed)"]
-    B -->|No| D{embed available?}
-    D -->|No| C
-    D -->|Yes| F["Embed query"]
-    F -->|throws| E["onRetrievalFallback<br/>callback"]
-    E --> C
-    F -->|succeeds| G{preFilterLimit<br/>active?}
-    G -->|Yes| H["MiniSearch pre-filter<br/>top K candidates"]
-    H --> I["Phase 1: Cosine score<br/>top K candidates"]
-    G -->|No| J["Phase 1: Cosine score<br/>all facts"]
-    J --> K["Cache vectors<br/>in-memory<br/>(full scan only)"]
-    K --> L{hybridWeight = 1?}
-    I --> L
-    L -->|Yes| M["Pure semantic<br/>ranking"]
-    L -->|No| N["Hybrid blend:<br/>semantic + keyword<br/>via MiniSearch"]
-    M --> O["Phase 2: Fetch full rows<br/>top maxResults"]
-    N --> O
-    C --> P["MiniSearch ranking"]
-    P --> O
-    O --> R["Track access"]
-    R --> Q["Return MemoryBundle"]
-```
-
-The flowchart shows:
-1. **Fast-path** when `hybridWeight = 0` (pure keyword, no embed cost)
-2. **Fallback chain** when embed unavailable (MiniSearch silently) or throws (`onRetrievalFallback` callback, then MiniSearch)
-3. **Pre-filtering** to limit cosine scoring to top-K keyword matches (O(N) → O(K))
-4. **Two-phase SELECT**: phase 1 scores all/filtered facts with minimal columns, phase 2 fetches full rows for winners
-5. **Hybrid scoring** to blend semantic and keyword rankings
-6. **Vector caching** on full scans only; reads with `preFilterLimit` active skip cache population
 
-## Multi-Entity Reads
-
-`read()` accepts a single entity ID or an array to search across namespaces in one retrieval pass. Pass `tierWeights` to control per-entity ranking before the final top-K results:
-
-```typescript
-const memory = await wiki.read(
-  ['tier_wisdom', 'tier_fact', 'tier_working'],
-  'What do I know about this topic?',
-  {
-    maxResults: 8,
-    tierWeights: {
-      tier_wisdom: 2,      // boost curated notes 2×
-      tier_fact: 1,        // neutral
-      tier_working: 0.25,  // downrank unvetted context
-    },
-  }
-);
-// memory.factScores — Record<factId, weightedScore> | undefined
-//   attached for array-shaped reads when the query is non-empty and at least one fact is scored
-// memory.metadata  — { query, entityIds, tierWeights }
-// tasks capped at min(20 × entityCount, 200); events at min(10 × entityCount, 100)
+// <WikiProvider wiki={wiki}><App /></WikiProvider>
 ```
 
-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`.
-
-## Concurrency
-
-All write APIs are safe to call from concurrent async contexts. Transactions are
-serialized internally on the single database connection — you never need to know that
-SQLite forbids nested `BEGIN`, and you never need to throttle callers yourself.
-
-- One connection per database file per process is the supported topology.
-- Non-transactional reads are **not** serialized, so read latency is unaffected.
-- Inside a transaction callback, use only the provided `tx` handle — never the outer
-  database handle. Using the outer handle deadlocks; opening a nested transaction throws.
-
-Driver errors that escape a transaction surface as `WikiTransactionError` (re-exported
-from `@equationalapplications/core-llm-wiki`) with a top-level `sqliteErrorCode`.
+See the [Expo quickstart](https://equationalapplications.github.io/expo-llm-wiki/start/quickstart-expo/) for a complete app, including the `llmProvider`. On React Native, give `embed` an absolute URL.
 
 ## Monorepo Ecosystem
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equationalapplications/expo-llm-wiki",
-  "version": "7.15.1",
+  "version": "7.16.0",
   "description": "Local-first LLM memory for Expo and React Native. Combines the core semantic search and extraction engine with expo-sqlite and ready-to-use React hooks.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -49,14 +49,14 @@
   "bugs": {
     "url": "https://github.com/equationalapplications/expo-llm-wiki/issues"
   },
-  "homepage": "https://github.com/equationalapplications/expo-llm-wiki/tree/main/packages/expo#readme",
+  "homepage": "https://equationalapplications.github.io/expo-llm-wiki/packages/expo/",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@equationalapplications/core-llm-wiki": "7.15.1",
-    "@equationalapplications/react-llm-wiki": "7.15.1"
+    "@equationalapplications/core-llm-wiki": "7.16.0",
+    "@equationalapplications/react-llm-wiki": "7.16.0"
   },
   "peerDependencies": {
     "expo-crypto": ">=12",