React hooks

Import the hooks from @equationalapplications/react-llm-wiki on the web, or from @equationalapplications/expo-llm-wiki in Expo. They’re the same hooks.

Setup

<WikiProvider wiki={wiki}>
  <App />
</WikiProvider>

useWiki() returns the WikiMemory instance. It throws outside a provider. Use it for any method that has no hook, such as listDrafts, lint, or getInstructions.

Conventions

Mutation hooks share one shape:

{
  execute: (...args) => Promise<TResult>;
  lastResult: TResult | null; // last successful result; null before the first call or after an error
  isPending: boolean;
  error: Error | null;        // cleared on the next execute()
}

Writes don’t refresh reads. After a mutation, call refetch() on any useMemoryRead, useOntologyManifest, or useWikiTraversal that should update.

Read hooks

useMemoryRead

const { data, isPending, error, refetch } = useMemoryRead(entityId, query, options?);
// data: MemoryBundle | null

It fetches on mount, and again when entityId, query, wiki, or relevant options change (maxResults, preFilterLimit, hybridWeight, tierWeights, includeZeroWeightEntities, excludeDrafts). Changing tierFloors, asOf or tokenBudget alone does not refetch; call refetch(). entityId may be an array. An in-flight result always lands before a queued refetch starts.

• A tierWeights entry of 1.0 counts the same as leaving it out, so it doesn’t trigger a refetch.
• includeZeroWeightEntities: false and undefined behave the same. Only switching to true refetches.
• For multi-entity reads, data.metadata is also filled in. data.factScores is conditional: it appears only when the query is non-empty and scored results were captured.

useWikiTraversal

const { nodes, edges, isPending, error, refetch } = useWikiTraversal(entityId, { sourceId, maxDepth: 2 });

Accepts the same options as traverseGraph(). maxDepth is clamped to 1–3. edgeTypes: [] matches nothing, while leaving it out matches every edge type. Pass the result to formatGraphContext({ nodes, edges }) for a prompt-ready block.

useOntologyManifest

const { manifest, mode, isPending, error, refetch } = useOntologyManifest(entityId);

manifest and mode are null when the entity has no persisted or seeded manifest.

useEntityStatus

const { ingesting, librarian, heal } = useEntityStatus(entityId);

It’s push-based, with no polling, and updates on every job transition.

Mutation hooks

Hook	execute(...)	lastResult
useWikiWrite()	(entityId, event)	—
useWikiIngest()	(entityId, params)	IngestResult
useWikiForget()	(entityId, params)	{ deleted: { entries, tasks, events? }, metadataReset? }
useWikiHasChanged()	(entityId, sourceRef, sourceHash)	boolean
useWikiExport()	(entityIds)	MemoryDump
useSetOntologyManifest()	(entityId, manifest, { mode? })	—

useWikiMaintenance

const { runLibrarian, runHeal, runReembed, runPrune, isPending, lastResult, error } = useWikiMaintenance();

• isPending is shared, so it’s true while any of the operations is running.
• lastResult is a discriminated union: { operation: 'librarian' | 'heal' | 'prune', result }. Narrow it by checking operation.
• runReembed deliberately leaves lastResult as null. Use its returned promise instead.

import type { MaintenanceResult } from '@equationalapplications/react-llm-wiki';

if (lastResult?.operation === 'prune') console.log(lastResult.result.entries);