@equationalapplications/core-llm-wiki 4.5.0 → 4.6.0

package/README.md

@@ -9,7 +9,9 @@ Pure TypeScript business logic for LLM Wiki Memory.
 - **Platform-agnostic** — Zero runtime dependencies; works with any SQLite driver via the `SQLiteAdapter` interface
 - **Semantic search** — Vector embeddings via your LLM's `embed` function, ranked by cosine similarity
 - **Keyword fallback** — MiniSearch in-memory index for offline/degraded scenarios when embeddings unavailable
-- **Retrieval tuning** — Per-call overrides for `maxResults`, `preFilterLimit`, and `hybridWeight` blend
+- **Retrieval tuning** — Per-call overrides for `maxResults`, `preFilterLimit`, `hybridWeight`, `tierWeights`, and `includeZeroWeightEntities`
+- **Multi-entity reads** — Search across multiple `entity_id` namespaces in one pass with per-entity score multipliers (`tierWeights`); optional `factScores` and `metadata` for explainability
+- **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
 
@@ -121,6 +123,19 @@ const memory = await wikiMemory.read('user-123', 'my preferences', {
   preFilterLimit: 20,
   hybridWeight: 0.5,
 });
+
+// Multi-entity with tier weights
+const multiMemory = await wikiMemory.read(['tier_wisdom', 'tier_fact', 'tier_working'], 'my preferences', {
+  maxResults: 8,
+  tierWeights: {
+    tier_wisdom: 2,      // high-confidence curated notes boosted 2×
+    tier_fact: 1,        // neutral baseline
+    tier_working: 0.25,  // recent but unvetted context downranked
+  },
+  // includeZeroWeightEntities: true — include 0-weight entities as bottom-ranked filler
+});
+// multiMemory.factScores — optional Record<factId, weightedScore> for returned facts; may be absent/undefined
+// multiMemory.metadata  — optional { query, entityIds, tierWeights }; may be absent/undefined
 ```
 
 **Hybrid scoring blends:**
@@ -130,6 +145,15 @@ const memory = await wikiMemory.read('user-123', 'my preferences', {
 
 True cosine-range pure semantic ranking (including negative cosine values) is used when `hybridWeight` is left `undefined`.
 
+**Tier weights:**
+- `tierWeights` applies a per-entity multiplier after semantic/keyword scoring: `finalScore = retrievalScore × weight`
+- Missing weights default to `1.0`. Negative weights clamp to `0`. Non-finite weights default to `1.0`.
+- `tierWeights[entity] = 0` skips that entity's scored retrieval branch (no compute cost).
+- `includeZeroWeightEntities: true` includes zero-weight entities as bottom-ranked filler instead of skipping them.
+- `factScores` is present for array-shaped `entityId` calls only when the query is non-empty and at least one fact is scored; empty-query ("recent facts") reads leave it absent even when `entityId` is an array. Plain string calls never expose it. `metadata` is present for all array-shaped calls regardless of query.
+- `maxResults` applies globally across all requested entities.
+- Tasks are capped at `min(20 × entityCount, 200)`; events at `min(10 × entityCount, 100)` for multi-entity reads.
+
 **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).
 
@@ -418,7 +442,7 @@ console.log(memory.factScores);
 
 ### Librarian prompt override contract
 
-Core does not own a provider-specific synthesis API, but it exports prompt utilities for applications that synthesize answers from weighted retrieval results.
+Core exports prompt utilities for weighted retrieval-based synthesis. Use `mapLibrarianOptionsToReadOptions()` to map `entityWeights` to `tierWeights`, then hydrate a prompt with `query`, `context`, and `tasks`.
 
 ```ts
 import {
@@ -553,7 +577,7 @@ const adapter: SQLiteAdapter = {
 
 ```mermaid
 flowchart TD
-    A["read(entityId, query)"] --> B{hybridWeight = 0?}
+    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

package/dist/index.js

@@ -1009,7 +1009,7 @@ After running the migration SQL, restart your application.`
   async read(entityId, query, options) {
     const config = this.options.config;
     const entityIds = normalizeEntityIds(entityId);
-    const sanitizedTierWeights = sanitizeTierWeights(entityIds, options?.tierWeights);
+    const sanitizedTierWeights = shouldExposeReadMetadata(entityId) ? sanitizeTierWeights(entityIds, options?.tierWeights) : void 0;
     const exposeMetadata = shouldExposeReadMetadata(entityId);
     if (entityIds.length === 0) {
       const empty = { facts: [], tasks: [], events: [] };
@@ -1064,7 +1064,7 @@ After running the migration SQL, restart your application.`
               );
             }
           }
-          const mismatchScope = this._entityInClause(entityIds);
+          const mismatchScope = this._entityInClause(scoredEntityIds);
           const mismatchedCount = await this.db.getFirstAsync(
             `SELECT COUNT(*) AS cnt FROM ${this.prefix}entries
              WHERE ${mismatchScope.clause} AND deleted_at IS NULL