@equationalapplications/core-llm-wiki 4.14.1 → 4.15.1

package/README.md

@@ -20,6 +20,7 @@ Platform-agnostic TypeScript engine for hybrid LLM memory. Features episodic fac
 - **Immutable vs mutable facts** — Use `WikiFact.source_type` to distinguish document-sourced facts (`immutable_document`) from derived or user-provided facts (`librarian_inferred`, `user_stated`, `user_confirmed`). Immutable document facts are not rewritten by `runLibrarian()` or `runHeal()` and can only be removed by `forget()` or re-ingesting.
 - **Full-featured memory** — Facts, tasks, events, maintenance jobs (librarian, heal, reembed, prune)
 - **Type-safe** — Built with TypeScript, full type exports
+- **Interoperability:** Supports [Open Knowledge Format (OKF) v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) import and export.
 
 ## Installation
 
@@ -444,6 +445,58 @@ Notes:
 - A throwing callback is caught (logged via `console.error`) and does not block other subscribers or the underlying job.
 - Subscriptions are scoped to a single `entityId`. There is no wildcard or "all entities" form.
 
+## OKF Import/Export
+
+The core package integrates with `@equationalapplications/core-okf` to seamlessly adapt wiki data dumps to and from Open Knowledge Format (OKF) v0.1 bundles.
+
+### Exporting an OKF Bundle
+
+Convert an existing wiki dump into a flat array of OKF files, ready to be written to disk or zipped:
+
+```typescript
+import { formatOkfBundle } from '@equationalapplications/core-llm-wiki';
+
+const dump = await wiki.exportDump(['entity-123']);
+const { files } = formatOkfBundle(dump);
+
+// files: Array<{ path: string; content: string }>
+// e.g., [{ path: 'entities/entity-123/facts/fact_abc.md', content: '---\n...' }]
+```
+
+### Importing an OKF Bundle
+
+Parse raw OKF files back into a `MemoryDump` that the wiki can ingest:
+
+```typescript
+import { parseOkfBundle } from '@equationalapplications/core-llm-wiki';
+
+// Assuming you read OKF files for this entity (e.g. under `entities/entity-123/`) from disk/zip into OkfFile[] shape
+const dump = parseOkfBundle('entity-123', files, {
+  defaultSchema: 'fact',
+  typeMapping: {
+    'custom_type': 'fact',
+    'archived': 'ignore', // Skips these concepts
+  },
+});
+
+await wiki.importDump(dump, { merge: true });
+```
+
+**Routing Precedence:** Concepts are routed into either the `entries` (facts) or `tasks` tables based on a three-step fallback:
+
+1. `OkfImportOptions.typeMapping` explicitly mapping an OKF `type` to `'fact'`, `'task'`, or `'ignore'`.
+2. Directory convention (e.g., files in `/facts/` become facts, `/tasks/` become tasks).
+3. The `OkfImportOptions.defaultSchema` (defaults to `'fact'`).
+
+### WikiEdge and Markdown Links
+
+A `WikiEdge` represents a markdown cross-link found inside a concept body, resolved to a `source_id` and `target_id`.
+Edges automatically round-trip during OKF import and export. Because the markdown body is the source of truth for edges in the OKF spec, edges are extracted during `parseOkfBundle()` and persisted via the `EdgeRepository` on `importDump()` — there is no separate edge export step required. The `edges` array is included in bundles returned by `getMemoryBundle()` / `exportDump()` (not by `read()`).
+
+### The `okf_type` Field
+
+Facts and tasks include a nullable `okf_type` column. This preserves the literal OKF `type` string from an imported bundle frontmatter, independent of whether the item was routed to the `entries` or `tasks` table. When `formatOkfBundle` runs, it restores this specific string, falling back to `'fact'` or `'task'` if the field is null (ensuring non-imported rows export cleanly).
+
 ## Security
 
 `@equationalapplications/core-llm-wiki` enforces multiple security layers:
@@ -706,13 +759,14 @@ The flowchart shows:
 
 ## Monorepo Ecosystem
 
-| Package | Description |
-|---------|-------------|
-| **`@equationalapplications/core-llm-wiki`** | Pure TypeScript core — DB-agnostic, bring your own SQLite adapter |
-| [`@equationalapplications/expo-llm-wiki`](https://www.npmjs.com/package/@equationalapplications/expo-llm-wiki) | Expo / React Native adapter with `expo-sqlite` |
-| [`@equationalapplications/react-llm-wiki`](https://www.npmjs.com/package/@equationalapplications/react-llm-wiki) | React hooks + web adapter with `sql.js` |
-| [`@equationalapplications/prisma-outbox`](https://www.npmjs.com/package/@equationalapplications/prisma-outbox) | Sync SQLite outbox events to Prisma in a transaction |
-| [`@equationalapplications/core-llm-tools`](https://www.npmjs.com/package/@equationalapplications/core-llm-tools) | Platform-agnostic Gemini tool schemas + capability scope injector |
+| Package | Purpose |
+| ----- | ----- |
+| **@equationalapplications/core-llm-wiki** | Persistent episodic memory |
+| [@equationalapplications/expo-llm-wiki](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/expo/README.md) | Persistent episodic memory for Expo/React Native |
+| [@equationalapplications/react-llm-wiki](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/react/README.md) | Persistent episodic memory for Web |
+| [@equationalapplications/prisma-outbox](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/prisma-outbox/README.md) | Sync SQLite outbox events to Prisma |
+| [@equationalapplications/core-llm-tools](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/core-llm-tools/README.md) | Gemini tool schemas and capability injector |
+| [@equationalapplications/core-okf](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/okf/README.md) | Zero-dependency Open Knowledge Format (OKF) v0.1 primitives — parse and produce interoperable knowledge bundles. |
 
 ## License
 

package/dist/{chunk-24ANTHZB.mjs → chunk-J4GBC6CP.mjs}

@@ -1428,11 +1428,12 @@ var MAX_EMBEDDING_BLOB_BYTES = 32 * 1024;
 var IMPORT_TITLE_MAX = 500;
 var IMPORT_BODY_MAX = 8e3;
 var ImportExportService = class {
-  constructor(db, entryRepo, taskRepo, eventRepo, metadataRepo, searchService, jobManager, embeddingService) {
+  constructor(db, entryRepo, taskRepo, eventRepo, edgeRepo, metadataRepo, searchService, jobManager, embeddingService) {
     this.db = db;
     this.entryRepo = entryRepo;
     this.taskRepo = taskRepo;
     this.eventRepo = eventRepo;
+    this.edgeRepo = edgeRepo;
     this.metadataRepo = metadataRepo;
     this.searchService = searchService;
     this.jobManager = jobManager;
@@ -1477,10 +1478,11 @@ var ImportExportService = class {
     }
   }
   async getFullBundle(entityId, opts) {
-    const [factsRaw, tasks, events] = await Promise.all([
+    const [factsRaw, tasks, events, edges] = await Promise.all([
       opts?.includeBlobs ? this.entryRepo.findAllByEntityIdWithBlobs(entityId) : this.entryRepo.findAllByEntityId(entityId),
       this.taskRepo.findAllByEntityId(entityId),
-      this.eventRepo.getByEntityId(entityId, opts?.maxEvents)
+      this.eventRepo.getByEntityId(entityId, opts?.maxEvents),
+      this.edgeRepo.getByEntityId(entityId)
     ]);
     const facts = factsRaw.map((f) => {
       const {
@@ -1499,7 +1501,7 @@ var ImportExportService = class {
         tags: typeof factBase.tags === "string" ? JSON.parse(factBase.tags) : factBase.tags
       };
     });
-    return { facts, tasks, events };
+    return { facts, tasks, events, edges };
   }
   /** Single-entity import transaction + post-processing; package-internal hook for tests. */
   async doImportEntity(entityId, bundle, merge) {
@@ -1521,6 +1523,7 @@ var ImportExportService = class {
         softDeletedFactIds.push(...deletedLiveFactIds);
         await this.entryRepo.bulkSoftDeleteByEntityId(entityId, tx);
         await this.taskRepo.bulkSoftDeleteByEntityId(entityId, tx);
+        await this.edgeRepo.bulkDeleteByEntityId(entityId, tx);
         await this.metadataRepo.deleteCheckpoint(entityId, tx);
       }
       const factIds = bundle.facts.map((fact) => fact.id);
@@ -1618,7 +1621,8 @@ var ImportExportService = class {
           last_accessed_at: fact.last_accessed_at,
           access_count: fact.access_count,
           deleted_at: fact.deleted_at,
-          embedding_blob: blobData ?? void 0
+          embedding_blob: blobData ?? void 0,
+          okf_type: fact.okf_type ?? null
         };
         await this.entryRepo.upsertForImport(factObj, tx);
         if (blobData != null) {
@@ -1667,7 +1671,8 @@ var ImportExportService = class {
             created_at: task.created_at,
             updated_at: safeUpdatedAt,
             resolved_at: task.resolved_at,
-            deleted_at: task.deleted_at
+            deleted_at: task.deleted_at,
+            okf_type: task.okf_type ?? null
           },
           tx,
           safeUpdatedAt
@@ -1691,6 +1696,19 @@ var ImportExportService = class {
           tx
         );
       }
+      for (const edge of bundle.edges ?? []) {
+        await this.edgeRepo.addIgnoreDuplicate(
+          {
+            id: edge.id,
+            entity_id: entityId,
+            source_id: edge.source_id,
+            target_id: edge.target_id,
+            edge_type: edge.edge_type,
+            created_at: edge.created_at
+          },
+          tx
+        );
+      }
     });
     await this.searchService.sync(entityId);
     for (const fact of bundle.facts) {
@@ -2007,7 +2025,7 @@ var RetrievalService = class {
     const sanitizedTierWeights = shouldExposeReadMetadata(entityId) ? sanitizeTierWeights(entityIds, options?.tierWeights) : void 0;
     const exposeMetadata = shouldExposeReadMetadata(entityId);
     if (entityIds.length === 0) {
-      const empty = { facts: [], tasks: [], events: [] };
+      const empty = { facts: [], tasks: [], events: [], edges: [] };
       if (exposeMetadata) {
         empty.metadata = { query, entityIds: [] };
         if (sanitizedTierWeights && Object.keys(sanitizedTierWeights).length > 0) empty.metadata.tierWeights = sanitizedTierWeights;
@@ -2397,7 +2415,7 @@ var RetrievalService = class {
     if (exposeMetadata && trimmedQuery && scoreByFactId) {
       factScores = Object.fromEntries(facts.map((fact) => [fact.id, scoreByFactId.get(fact.id) ?? 0]));
     }
-    const bundle = { facts, tasks, events: events.reverse() };
+    const bundle = { facts, tasks, events: events.reverse(), edges: [] };
     if (exposeMetadata) {
       bundle.metadata = { query, entityIds };
       if (sanitizedTierWeights && Object.keys(sanitizedTierWeights).length > 0) bundle.metadata.tierWeights = sanitizedTierWeights;
@@ -2597,5 +2615,5 @@ var WriteService = class {
 };
 
 export { EmbeddingService, HOOK_TIMEOUT_MARKER, ImportExportService, IngestionService, JobManager, MaintenanceService, PromptService, PrunePartialFailureError, RetrievalService, SearchService, WikiBusyError, WriteService, __privateAdd, __privateGet, __privateSet, generateId, normalizeSourceHash, normalizeSourceRef, parseEmbedding };
-//# sourceMappingURL=chunk-24ANTHZB.mjs.map
-//# sourceMappingURL=chunk-24ANTHZB.mjs.map
+//# sourceMappingURL=chunk-J4GBC6CP.mjs.map
+//# sourceMappingURL=chunk-J4GBC6CP.mjs.map