@plur-ai/core 0.9.3 → 0.9.5

package/dist/index.js

@@ -1,12 +1,15 @@
 import {
   computeIdf,
+  embedderStatus,
   embeddingSearch,
   embeddingSearchWithScores,
   engramSearchText,
   ftsScore,
   ftsTokenize,
-  searchEngrams
-} from "./chunk-IGGMRXAB.js";
+  resetEmbedder,
+  searchEngrams,
+  setEmbeddingsEnabled
+} from "./chunk-ZY4R3VEG.js";
 import {
   EngramSchemaPassthrough,
   appendHistory,
@@ -26,19 +29,18 @@ import {
   readHistoryForEngram,
   saveEngrams,
   storePrefix
-} from "./chunk-3ZPTRZE3.js";
+} from "./chunk-EQPTF4JZ.js";
 import {
   atomicWrite,
   getSyncStatus,
   sync,
   withLock
 } from "./chunk-PRK3B7WR.js";
-import "./chunk-2ZDO52B4.js";
 
 // src/index.ts
 import * as fs4 from "fs";
-import * as os from "os";
-import * as path3 from "path";
+import { tmpdir } from "os";
+import { join as join5, dirname as dirname2, basename as basename2 } from "path";
 import yaml6 from "js-yaml";
 
 // src/storage.ts
@@ -175,6 +177,7 @@ var IndexedStorage = class {
         allSyncedIds.add(e.id);
       }
       for (const store of this.stores) {
+        if (!store.path) continue;
         validSources.add(store.path);
         const storeEngrams = loadEngrams(store.path);
         const prefix = storePrefix(store.scope);
@@ -221,11 +224,17 @@ import yaml from "js-yaml";
 // src/schemas/config.ts
 import { z } from "zod";
 var StoreEntrySchema = z.object({
-  path: z.string(),
+  path: z.string().optional(),
+  url: z.string().url().optional(),
+  token: z.string().optional(),
+  // Bearer for remote stores; ignored for path
   scope: z.string(),
   shared: z.boolean().default(false),
   readonly: z.boolean().default(false)
-});
+}).refine(
+  (s) => Boolean(s.path) !== Boolean(s.url),
+  { message: "StoreEntry requires exactly one of path or url" }
+);
 var LlmTierConfigSchema = z.object({
   dedup_tier: z.enum(["fast", "balanced", "thorough"]).default("fast"),
   profile_tier: z.enum(["fast", "balanced", "thorough"]).default("balanced"),
@@ -244,6 +253,9 @@ var StorageConfigSchema = z.object({
   backend: z.enum(["yaml", "sqlite"]).default("yaml"),
   path: z.string().optional()
 }).partial();
+var EmbeddingsConfigSchema = z.object({
+  enabled: z.boolean().default(true)
+}).partial();
 var PlurConfigSchema = z.object({
   auto_learn: z.boolean().default(true),
   auto_capture: z.boolean().default(true),
@@ -261,6 +273,7 @@ var PlurConfigSchema = z.object({
   allow_secrets: z.boolean().default(false),
   index: z.boolean().default(true),
   storage: StorageConfigSchema.default({}),
+  embeddings: EmbeddingsConfigSchema.default({}),
   stores: z.array(StoreEntrySchema).default([]),
   llm: LlmTierConfigSchema.default({}),
   profile: ProfileConfigSchema.default({}),
@@ -450,6 +463,7 @@ var DEFAULT_MAX_TOKENS = 8e3;
 var DEFAULT_MIN_RELEVANCE = 0.3;
 var MAX_PER_PACK = 5;
 var MAX_PER_DOMAIN = 10;
+var PINNED_TOKEN_BUDGET_RATIO = 0.5;
 var DIP19_CONSIDER_MAX = 5;
 var DIP19_CONSIDER_BUDGET = 200;
 function getPackMetadata(manifest) {
@@ -528,7 +542,11 @@ function scoreEngram(engram, promptLower, promptWords, packMatchTerms, scopeFilt
   for (const word of promptWords) {
     if (statementWords.has(word)) termHits += 0.5;
   }
-  if (termHits === 0) return 0;
+  const isPinned = engram.pinned === true;
+  if (termHits === 0 && !isPinned) return 0;
+  if (termHits === 0 && isPinned) {
+    termHits = 0.5;
+  }
   let rs = isPack ? engram.activation.retrieval_strength : decayedStrength(engram.activation.retrieval_strength, daysSince(engram.activation.last_accessed));
   if (!isPack) {
     const fb = engram.feedback_signals;
@@ -543,6 +561,7 @@ function scoreEngram(engram, promptLower, promptWords, packMatchTerms, scopeFilt
     else if (netFeedback < 0) score *= Math.max(1 + netFeedback * 0.1, 0.5);
   }
   if (engram.consolidated) score *= 1.1;
+  if (isPinned) score *= 2;
   const emotionalWeight = engram.episodic?.emotional_weight ?? 5;
   score *= 1 + (emotionalWeight - 5) * 0.04;
   return score;
@@ -552,7 +571,21 @@ function fillTokenBudget(scored, maxTokens) {
   const packCounts = /* @__PURE__ */ new Map();
   const domainCounts = /* @__PURE__ */ new Map();
   let tokensUsed = 0;
-  for (const engram of scored) {
+  const pinned = scored.filter((e) => e.pinned === true);
+  const unpinned = scored.filter((e) => e.pinned !== true);
+  const pinnedBudget = Math.floor(maxTokens * PINNED_TOKEN_BUDGET_RATIO);
+  for (const engram of pinned) {
+    const cost = estimateTokens(engram);
+    if (tokensUsed + cost > maxTokens) continue;
+    if (tokensUsed + cost > pinnedBudget) continue;
+    result.push(engram);
+    tokensUsed += cost;
+    const pack = engram.pack ?? "__personal__";
+    packCounts.set(pack, (packCounts.get(pack) ?? 0) + 1);
+    const topDomain = (engram.domain ?? "__none__").split(".")[0];
+    domainCounts.set(topDomain, (domainCounts.get(topDomain) ?? 0) + 1);
+  }
+  for (const engram of unpinned) {
     const cost = estimateTokens(engram);
     if (tokensUsed + cost > maxTokens) continue;
     const pack = engram.pack ?? "__personal__";
@@ -586,7 +619,7 @@ function selectAndSpread(ctx, personalEngrams, packs, config, embeddingBoosts) {
     engramMap.set(engram.id, engram);
     let raw = scoreEngram(engram, promptLower, promptWords, [], ctx.scope, false);
     const embBoost = embeddingBoosts?.get(engram.id) ?? 0;
-    if (raw === 0 && embBoost > 0.3) {
+    if (raw === 0 && embBoost > 0.5) {
       raw = embBoost * 2;
     } else if (raw > 0 && embBoost > 0) {
       raw += embBoost;
@@ -611,7 +644,7 @@ function selectAndSpread(ctx, personalEngrams, packs, config, embeddingBoosts) {
       engramMap.set(engram.id, engram);
       let raw = scoreEngram(engram, promptLower, promptWords, matchTerms, ctx.scope, true);
       const embBoost = embeddingBoosts?.get(engram.id) ?? 0;
-      if (raw === 0 && embBoost > 0.3) {
+      if (raw === 0 && embBoost > 0.5) {
         raw = embBoost * 2;
       } else if (raw > 0 && embBoost > 0) {
         raw += embBoost;
@@ -631,7 +664,7 @@ function selectAndSpread(ctx, personalEngrams, packs, config, embeddingBoosts) {
     aBoosts.set(e.id, aBoost);
     e.score = e.keyword_match + aBoost;
   }
-  const filtered = scored.filter((s) => s.score >= minRelevance);
+  const filtered = scored.filter((s) => s.pinned === true || s.score >= minRelevance);
   filtered.sort((a, b) => b.score - a.score);
   const { selected: directives, tokens_used: directiveTokens } = fillTokenBudget(filtered, maxTokens);
   const directiveIds = new Set(directives.map((e) => e.id));
@@ -772,8 +805,8 @@ function generateEpisodeId() {
   const rand = Math.random().toString(36).slice(2, 6);
   return `EP-${ts}-${rand}`;
 }
-function captureEpisode(path4, summary, context) {
-  const episodes = loadEpisodes(path4);
+function captureEpisode(path3, summary, context) {
+  const episodes = loadEpisodes(path3);
   const episode = {
     id: generateEpisodeId(),
     summary,
@@ -784,11 +817,11 @@ function captureEpisode(path4, summary, context) {
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   };
   episodes.push(episode);
-  atomicWrite(path4, yaml2.dump(episodes, { lineWidth: 120, noRefs: true }));
+  atomicWrite(path3, yaml2.dump(episodes, { lineWidth: 120, noRefs: true }));
   return episode;
 }
-function queryTimeline(path4, query) {
-  let episodes = loadEpisodes(path4);
+function queryTimeline(path3, query) {
+  let episodes = loadEpisodes(path3);
   if (query?.since) episodes = episodes.filter((e) => new Date(e.timestamp) >= query.since);
   if (query?.until) episodes = episodes.filter((e) => new Date(e.timestamp) <= query.until);
   if (query?.agent) episodes = episodes.filter((e) => e.agent === query.agent);
@@ -799,10 +832,10 @@ function queryTimeline(path4, query) {
   }
   return episodes;
 }
-function loadEpisodes(path4) {
-  if (!existsSync4(path4)) return [];
+function loadEpisodes(path3) {
+  if (!existsSync4(path3)) return [];
   try {
-    const raw = yaml2.load(readFileSync2(path4, "utf8"));
+    const raw = yaml2.load(readFileSync2(path3, "utf8"));
     return Array.isArray(raw) ? raw : [];
   } catch {
     return [];
@@ -903,7 +936,13 @@ function isAggregationQuery(query) {
   return AGGREGATION_PATTERNS.some((p) => p.test(query));
 }
 async function hybridSearch(engrams, query, limit, storagePath) {
-  if (engrams.length === 0) return [];
+  const result = await hybridSearchWithMeta(engrams, query, limit, storagePath);
+  return result.engrams;
+}
+async function hybridSearchWithMeta(engrams, query, limit, storagePath) {
+  if (engrams.length === 0) {
+    return { engrams: [], mode: "hybrid", embedderError: null };
+  }
   const exhaustive = isAggregationQuery(query);
   const effectiveLimit = exhaustive ? Math.max(limit, 50) : limit;
   const bm25Limit = Math.min(engrams.length, exhaustive ? effectiveLimit * 5 : effectiveLimit * 3);
@@ -912,8 +951,23 @@ async function hybridSearch(engrams, query, limit, storagePath) {
     Promise.resolve(searchEngrams(engrams, query, bm25Limit)),
     embeddingSearch(engrams, query, embLimit, storagePath)
   ]);
+  const status = embedderStatus();
+  let mode;
+  let embedderError = null;
+  if (status.disabled) {
+    mode = "bm25-only";
+  } else if (!status.available || embResults.length === 0 && !!status.lastError) {
+    mode = "hybrid-degraded";
+    embedderError = status.lastError;
+  } else {
+    mode = "hybrid";
+  }
   const merged = rrfMerge([bm25Results, embResults]);
-  return merged.slice(0, effectiveLimit);
+  return {
+    engrams: merged.slice(0, effectiveLimit),
+    mode,
+    embedderError
+  };
 }
 
 // src/query-expansion.ts
@@ -1469,6 +1523,137 @@ function computePackHash(packDir) {
   return hash.digest("hex");
 }
 
+// src/store/remote-store.ts
+var RemoteStore = class {
+  constructor(url, token, scope, opts = {}) {
+    this.url = url;
+    this.token = token;
+    this.scope = scope;
+    this.opts = opts;
+  }
+  cache = null;
+  inFlight = null;
+  get apiBase() {
+    return this.url.replace(/\/sse\/?$/, "").replace(/\/$/, "") + "/api/v1";
+  }
+  get ttlMs() {
+    return this.opts.ttlMs ?? 6e4;
+  }
+  headers(extra = {}) {
+    return {
+      Authorization: `Bearer ${this.token}`,
+      Accept: "application/json",
+      ...extra
+    };
+  }
+  /**
+   * Load all engrams visible to this token at this scope. Cached up to
+   * ttlMs; in-flight calls deduplicate to avoid thundering-herd on
+   * the remote when 5 things ask for engrams at once.
+   */
+  async load() {
+    const now = Date.now();
+    if (this.cache && now - this.cache.ts < this.ttlMs) return this.cache.engrams;
+    if (this.inFlight) return this.inFlight;
+    this.inFlight = (async () => {
+      try {
+        const all = [];
+        let offset = 0;
+        const limit = 200;
+        const maxPages = 50;
+        for (let i = 0; i < maxPages; i++) {
+          const u = `${this.apiBase}/engrams?scope=${encodeURIComponent(this.scope)}&limit=${limit}&offset=${offset}`;
+          const r = await fetch(u, { headers: this.headers() });
+          if (!r.ok) {
+            if (r.status >= 500) console.error(`[plur:remote-store] ${this.url} returned ${r.status} loading scope ${this.scope}`);
+            break;
+          }
+          const body = await r.json();
+          for (const row of body.rows) {
+            const d = row.data ?? {};
+            all.push({
+              id: row.id,
+              scope: row.scope,
+              status: row.status,
+              ...d
+            });
+          }
+          if (all.length >= body.total_count || body.rows.length < limit) break;
+          offset += limit;
+        }
+        this.cache = { ts: Date.now(), engrams: all };
+        return all;
+      } catch (err) {
+        console.error(`[plur:remote-store] ${this.url} load failed: ${err.message}`);
+        return this.cache?.engrams ?? [];
+      } finally {
+        this.inFlight = null;
+      }
+    })();
+    return this.inFlight;
+  }
+  /**
+   * Append a single engram to the remote store. POST /api/v1/engrams
+   * carries statement + scope + domain + type — the server handles
+   * ID assignment, content_hash, status.
+   */
+  async append(engram) {
+    const body = JSON.stringify({
+      statement: engram.statement,
+      scope: engram.scope,
+      domain: engram.domain,
+      type: engram.type
+    });
+    const r = await fetch(`${this.apiBase}/engrams`, {
+      method: "POST",
+      headers: this.headers({ "Content-Type": "application/json" }),
+      body
+    });
+    if (!r.ok) {
+      const text = await r.text().catch(() => "");
+      throw new Error(`Remote store append failed: ${r.status} ${text}`);
+    }
+    this.cache = null;
+  }
+  /**
+   * `save(all)` — used by migrations to bulk-replace. Not supported
+   * on remote: the server keeps an audit trail and we don't want a
+   * single client to be able to nuke + replace the whole store. Throws.
+   */
+  async save(_engrams) {
+    throw new Error("Remote store does not support bulk save() \u2014 use append()/remove() per engram");
+  }
+  async getById(id) {
+    try {
+      const r = await fetch(`${this.apiBase}/engrams/${encodeURIComponent(id)}`, { headers: this.headers() });
+      if (r.status === 404) return null;
+      if (!r.ok) return null;
+      const row = await r.json();
+      return { id: row.id, scope: row.scope, status: row.status, ...row.data ?? {} };
+    } catch {
+      return null;
+    }
+  }
+  /** Remove → DELETE /api/v1/engrams/:id (server soft-retires). */
+  async remove(id) {
+    const r = await fetch(`${this.apiBase}/engrams/${encodeURIComponent(id)}`, {
+      method: "DELETE",
+      headers: this.headers()
+    });
+    if (!r.ok) return false;
+    this.cache = null;
+    return true;
+  }
+  async count(filter) {
+    const all = await this.load();
+    if (filter?.status) return all.filter((e) => e.status === filter.status).length;
+    return all.length;
+  }
+  async close() {
+    this.cache = null;
+  }
+};
+
 // src/meta/sanitize.ts
 function sanitizeForPrompt(text) {
   return text.replace(/```/g, "~~~").replace(/\n{3,}/g, "\n\n").replace(/^(system|assistant|user):/gim, "$1 -").slice(0, 2e3);
@@ -1585,7 +1770,7 @@ async function computeSimilarityMatrix(templates) {
   const n = templates.length;
   const matrix = Array.from({ length: n }, () => Array(n).fill(0));
   try {
-    const { embed, cosineSimilarity } = await import("./embeddings-ZRT6IRPA.js");
+    const { embed, cosineSimilarity } = await import("./embeddings-3EXLC3EH.js");
     const embeddings = [];
     for (const t of templates) {
       embeddings.push(await embed(t));
@@ -2936,6 +3121,192 @@ function isNewer(a, b) {
   return false;
 }
 
+// src/schemas/capsule.ts
+import { z as z3 } from "zod";
+var CAPSULE_MAGIC = Buffer.from([80, 76, 85, 82]);
+var CAPSULE_MAGIC_HEX = "50 4c 55 52";
+var FORMAT_VERSION_V1 = 1;
+var SUPPORTED_FORMAT_VERSIONS = [FORMAT_VERSION_V1];
+var CAPSULE_FLAGS = {
+  SIGNED: 1 << 0,
+  COMPRESSED: 1 << 1
+};
+var CAPSULE_FLAG_RESERVED_MASK = 65532;
+var PREAMBLE_LEN = 12;
+var CAPSULE_SIZE_LIMITS = {
+  SOFT_BYTES: 100 * 1024 * 1024,
+  HARD_BYTES: 1024 * 1024 * 1024
+};
+var ED25519_SIG_LEN = 64;
+var ManifestSummarySchema = z3.object({
+  name: z3.string().min(1),
+  version: z3.string().min(1),
+  creator: z3.string().optional(),
+  engram_count: z3.number().int().min(0),
+  domain: z3.string().optional(),
+  license: z3.string().default("cc-by-sa-4.0")
+});
+var PayloadDescriptorSchema = z3.object({
+  compression: z3.enum(["gzip", "none"]),
+  size_compressed: z3.number().int().min(0),
+  size_uncompressed: z3.number().int().min(0),
+  sha256: z3.string().regex(/^[0-9a-f]{64}$/, "sha256 must be 64 lowercase hex chars")
+});
+var ProducerSchema = z3.object({
+  tool: z3.string().min(1),
+  version: z3.string().min(1),
+  agent_id: z3.string().optional()
+});
+var SignerSchema = z3.object({
+  algo: z3.literal("ed25519"),
+  public_key: z3.string().min(1),
+  key_id: z3.string().optional()
+});
+var CapsuleHeaderSchema = z3.object({
+  schema: z3.literal("plur.capsule/1"),
+  product_type: z3.enum(["engram-pack", "skill"]),
+  manifest_summary: ManifestSummarySchema,
+  payload: PayloadDescriptorSchema,
+  created_at: z3.string().datetime({ offset: true }),
+  producer: ProducerSchema,
+  signer: SignerSchema.nullable().default(null)
+});
+function parseCapsulePreamble(buf) {
+  if (buf.length < PREAMBLE_LEN) {
+    throw new Error(`capsule: truncated preamble (got ${buf.length} bytes, need ${PREAMBLE_LEN})`);
+  }
+  if (buf.compare(CAPSULE_MAGIC, 0, 4, 0, 4) !== 0) {
+    throw new Error(`capsule: bad magic (expected ${CAPSULE_MAGIC_HEX})`);
+  }
+  const formatVersion = buf.readUInt16LE(4);
+  if (!SUPPORTED_FORMAT_VERSIONS.includes(formatVersion)) {
+    throw new Error(`capsule: unsupported FormatVersion 0x${formatVersion.toString(16).padStart(4, "0")}`);
+  }
+  const flags = buf.readUInt16LE(6);
+  if ((flags & CAPSULE_FLAG_RESERVED_MASK) !== 0) {
+    throw new Error(`capsule: reserved flag bits set (flags=0x${flags.toString(16).padStart(4, "0")})`);
+  }
+  const headerLen = buf.readUInt32LE(8);
+  if (headerLen === 0) {
+    throw new Error("capsule: HeaderLen must be > 0");
+  }
+  if (headerLen > CAPSULE_SIZE_LIMITS.HARD_BYTES) {
+    throw new Error(`capsule: HeaderLen ${headerLen} exceeds hard size limit`);
+  }
+  return { formatVersion, flags, headerLen };
+}
+function serializeCapsulePreamble(p) {
+  const buf = Buffer.alloc(PREAMBLE_LEN);
+  CAPSULE_MAGIC.copy(buf, 0);
+  buf.writeUInt16LE(p.formatVersion, 4);
+  buf.writeUInt16LE(p.flags, 6);
+  buf.writeUInt32LE(p.headerLen, 8);
+  return buf;
+}
+function hasFlag(flags, flag) {
+  return (flags & flag) === flag;
+}
+
+// src/capsule.ts
+import { createHash as createHash2 } from "crypto";
+function writeCapsule(opts) {
+  const compression = opts.compression ?? "gzip";
+  const productType = opts.productType ?? "engram-pack";
+  const createdAt = opts.createdAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const signer = opts.signer ?? null;
+  if (signer !== null && (!opts.signature || opts.signature.length !== ED25519_SIG_LEN)) {
+    throw new Error(`writeCapsule: signer set but signature missing or not ${ED25519_SIG_LEN} bytes`);
+  }
+  if (signer === null && opts.signature) {
+    throw new Error("writeCapsule: signature provided without signer \u2014 refuse ambiguous envelope");
+  }
+  const sha256 = createHash2("sha256").update(opts.payload).digest("hex");
+  const sizeCompressed = opts.payload.length;
+  const sizeUncompressed = opts.sizeUncompressed ?? sizeCompressed;
+  const header = CapsuleHeaderSchema.parse({
+    schema: "plur.capsule/1",
+    product_type: productType,
+    manifest_summary: opts.manifestSummary,
+    payload: {
+      compression,
+      size_compressed: sizeCompressed,
+      size_uncompressed: sizeUncompressed,
+      sha256
+    },
+    created_at: createdAt,
+    producer: opts.producer,
+    signer
+  });
+  const headerJson = Buffer.from(JSON.stringify(header), "utf-8");
+  let flags = 0;
+  if (compression === "gzip") flags |= CAPSULE_FLAGS.COMPRESSED;
+  if (signer !== null) flags |= CAPSULE_FLAGS.SIGNED;
+  const preamble = serializeCapsulePreamble({
+    formatVersion: FORMAT_VERSION_V1,
+    flags,
+    headerLen: headerJson.length
+  });
+  const totalLen = PREAMBLE_LEN + headerJson.length + opts.payload.length + (signer !== null ? ED25519_SIG_LEN : 0);
+  if (totalLen > CAPSULE_SIZE_LIMITS.HARD_BYTES) {
+    throw new Error(`writeCapsule: capsule size ${totalLen} exceeds hard limit`);
+  }
+  const parts = [preamble, headerJson, opts.payload];
+  if (signer !== null && opts.signature) parts.push(opts.signature);
+  return Buffer.concat(parts, totalLen);
+}
+function readCapsule(buf) {
+  if (buf.length > CAPSULE_SIZE_LIMITS.HARD_BYTES) {
+    throw new Error(`readCapsule: capsule size ${buf.length} exceeds hard limit`);
+  }
+  const preamble = parseCapsulePreamble(buf);
+  const headerStart = PREAMBLE_LEN;
+  const headerEnd = headerStart + preamble.headerLen;
+  if (buf.length < headerEnd) {
+    throw new Error(`readCapsule: truncated header (need ${headerEnd} bytes, got ${buf.length})`);
+  }
+  const headerJson = buf.subarray(headerStart, headerEnd).toString("utf-8");
+  let parsedHeader;
+  try {
+    parsedHeader = JSON.parse(headerJson);
+  } catch (err) {
+    throw new Error(`readCapsule: malformed header JSON \u2014 ${err.message}`);
+  }
+  const header = CapsuleHeaderSchema.parse(parsedHeader);
+  const isSigned = hasFlag(preamble.flags, CAPSULE_FLAGS.SIGNED);
+  const sigLen = isSigned ? ED25519_SIG_LEN : 0;
+  const payloadEnd = buf.length - sigLen;
+  if (payloadEnd < headerEnd) {
+    throw new Error("readCapsule: payload region underflow");
+  }
+  const payload = buf.subarray(headerEnd, payloadEnd);
+  const signature = isSigned ? buf.subarray(payloadEnd) : null;
+  if (payload.length !== header.payload.size_compressed) {
+    throw new Error(
+      `readCapsule: payload size mismatch (header=${header.payload.size_compressed}, actual=${payload.length})`
+    );
+  }
+  const actualSha = createHash2("sha256").update(payload).digest("hex");
+  if (actualSha !== header.payload.sha256) {
+    throw new Error(`readCapsule: integrity mismatch (header=${header.payload.sha256}, actual=${actualSha})`);
+  }
+  const compressionFlagSet = hasFlag(preamble.flags, CAPSULE_FLAGS.COMPRESSED);
+  const headerSaysCompressed = header.payload.compression === "gzip";
+  if (compressionFlagSet !== headerSaysCompressed) {
+    throw new Error(
+      `readCapsule: COMPRESSED flag (${compressionFlagSet}) disagrees with header.payload.compression (${header.payload.compression})`
+    );
+  }
+  return { header, payload: Buffer.from(payload), signature: signature ? Buffer.from(signature) : null };
+}
+function verifyCapsuleIntegrity(buf) {
+  try {
+    readCapsule(buf);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/index.ts
 var COMMITMENT_MULTIPLIER = {
   locked: 1,
@@ -2973,6 +3344,9 @@ var Plur = class {
     if (this.config.index) {
       this.indexedStorage = new IndexedStorage(this.paths.engrams, this.paths.db, this.config.stores);
     }
+    if (this.config.embeddings?.enabled === false) {
+      setEmbeddingsEnabled(false, "embeddings disabled in config.yaml (embeddings.enabled = false)");
+    }
   }
   /**
    * Load engrams from primary store + all configured stores, with mtime-based caching.
@@ -2984,7 +3358,7 @@ var Plur = class {
     const stores = this.config.stores ?? [];
     const all = [...primary];
     for (const store of stores) {
-      const storeEngrams = this._loadCached(store.path);
+      const storeEngrams = store.url ? this._loadRemoteCached(store) : this._loadCached(store.path);
       const prefix = storePrefix(store.scope);
       for (const e of storeEngrams) {
         if (e.scope !== "global" && e.scope !== store.scope && !e.scope.startsWith(store.scope)) {
@@ -3014,19 +3388,45 @@ var Plur = class {
     return all;
   }
   /** Load engrams from a path with mtime-based caching */
-  _loadCached(path4) {
+  _loadCached(path3) {
     let mtime;
     try {
-      mtime = fs4.statSync(path4, { bigint: true }).mtimeNs;
+      mtime = fs4.statSync(path3, { bigint: true }).mtimeNs;
     } catch {
       return [];
     }
-    const cached = this._engramCache.get(path4);
+    const cached = this._engramCache.get(path3);
     if (cached && cached.mtime === mtime) return cached.engrams;
-    const engrams = loadEngrams(path4);
-    this._engramCache.set(path4, { mtime, engrams });
+    const engrams = loadEngrams(path3);
+    this._engramCache.set(path3, { mtime, engrams });
     return engrams;
   }
+  /**
+   * Per-instance pool of RemoteStore drivers, keyed by url+scope.
+   * RemoteStore holds its own internal TTL cache so repeated load()
+   * within ttlMs returns the same array without a network call.
+   *
+   * Note `_loadAllEngrams` is sync but RemoteStore.load() is async.
+   * We bridge that by returning whatever's in the driver's cache
+   * synchronously and triggering a background refresh on cache miss.
+   * The first call after server start returns [] for that store; the
+   * call after the first refresh sees the data. For our pilot this
+   * is acceptable — recall is expected to be tried more than once
+   * in any real session.
+   */
+  _remoteStores = /* @__PURE__ */ new Map();
+  _loadRemoteCached(store) {
+    const key = `${store.url}::${store.scope}`;
+    let driver = this._remoteStores.get(key);
+    if (!driver) {
+      driver = new RemoteStore(store.url, store.token ?? "", store.scope);
+      this._remoteStores.set(key, driver);
+    }
+    const cached = driver.cache;
+    void driver.load().catch(() => {
+    });
+    return cached?.engrams ?? [];
+  }
   /**
    * Write engrams to disk and invalidate the cache for that path.
    *
@@ -3038,9 +3438,9 @@ var Plur = class {
    * invalidation on write removes the filesystem as a source of cache
    * freshness and closes the race. See issue #25.
    */
-  _writeEngrams(path4, engrams) {
-    saveEngrams(path4, engrams);
-    this._engramCache.delete(path4);
+  _writeEngrams(path3, engrams) {
+    saveEngrams(path3, engrams);
+    this._engramCache.delete(path3);
   }
   /** Find which store owns an engram by ID. For namespaced IDs, strips prefix to find in store. */
   _findEngramStore(id) {
@@ -3050,6 +3450,7 @@ var Plur = class {
     }
     const stores = this.config.stores ?? [];
     for (const store of stores) {
+      if (!store.path) continue;
       const prefix = storePrefix(store.scope);
       const nsPattern = new RegExp(`^(ENG|ABS|META)-${prefix}-`);
       if (nsPattern.test(id)) {
@@ -3168,7 +3569,8 @@ var Plur = class {
           narrower: [],
           related: [],
           conflicts: conflictIds
-        } : void 0
+        } : void 0,
+        pinned: context?.pinned === true ? true : void 0
       };
       engrams.push(engram);
       this._writeEngrams(this.paths.engrams, engrams);
@@ -3201,12 +3603,12 @@ var Plur = class {
   }
   /** Async learn with LLM-driven deduplication (Ideas 1+2+19). */
   async learnAsync(statement, context) {
-    const { learnAsync: learnAsyncImpl } = await import("./learn-async-R5KZ5EWF.js");
+    const { learnAsync: learnAsyncImpl } = await import("./learn-async-IISWD7HC.js");
     return learnAsyncImpl(this._learnAsyncDeps(), statement, context);
   }
   /** Batch learn with LLM dedup. */
   async learnBatch(statements, llm) {
-    const { learnBatch: learnBatchImpl } = await import("./learn-async-R5KZ5EWF.js");
+    const { learnBatch: learnBatchImpl } = await import("./learn-async-IISWD7HC.js");
     return learnBatchImpl(this._learnAsyncDeps(), statements, llm);
   }
   /**
@@ -3247,6 +3649,26 @@ var Plur = class {
     this._reactivateResults(results);
     return results;
   }
+  /**
+   * Hybrid search with diagnostic metadata — returns both the engrams and
+   * whether embeddings actually contributed (mode: "hybrid" vs "hybrid-degraded").
+   * Use this when you want to surface degraded-mode warnings to users.
+   */
+  async recallHybridWithMeta(query, options) {
+    const filtered = this._filterEngrams(options);
+    const limit = options?.limit ?? 20;
+    const result = await hybridSearchWithMeta(filtered, query, limit, this.paths.root);
+    this._reactivateResults(result.engrams);
+    return result;
+  }
+  /** Inspect embedder availability without forcing a load. */
+  embedderStatus() {
+    return embedderStatus();
+  }
+  /** Reset cached embedder failure state — next call will retry the model load. */
+  resetEmbedder() {
+    resetEmbedder();
+  }
   /** Embedding search returning {engram, score}[] with cosine similarity scores. Async, no API calls. */
   async similaritySearch(query, options) {
     const filtered = this._filterEngrams(options);
@@ -3375,11 +3797,16 @@ var Plur = class {
     let embeddingBoosts;
     try {
       const engrams = this._loadAllEngrams().filter((e) => e.status === "active");
-      const results = await embeddingSearch(engrams, task, engrams.length, this.paths.root);
+      const results = await embeddingSearchWithScores(
+        engrams,
+        task,
+        engrams.length,
+        this.paths.root
+      );
       if (results.length > 0) {
         embeddingBoosts = /* @__PURE__ */ new Map();
-        for (let i = 0; i < results.length; i++) {
-          embeddingBoosts.set(results[i].id, 1 / (1 + i * 0.1));
+        for (const r of results) {
+          embeddingBoosts.set(r.engram.id, r.score);
         }
       }
     } catch {
@@ -3510,6 +3937,28 @@ var Plur = class {
       return true;
     });
   }
+  /**
+   * Toggle the always-load (pinned) flag for an engram.
+   * Returns the updated engram on success, null if not found.
+   */
+  setPinned(id, pinned) {
+    return withLock(this.paths.engrams, () => {
+      const engrams = loadEngrams(this.paths.engrams);
+      const idx = engrams.findIndex((e2) => e2.id === id);
+      if (idx === -1) return null;
+      const e = engrams[idx];
+      const updated = { ...e, pinned: pinned === true ? true : void 0 };
+      engrams[idx] = updated;
+      this._writeEngrams(this.paths.engrams, engrams);
+      this._syncIndex();
+      return updated;
+    });
+  }
+  /** List engrams that have pinned: true. */
+  listPinned() {
+    const all = this._loadAllEngrams();
+    return all.filter((e) => e.pinned === true && e.status === "active");
+  }
   /** Set engram status to 'retired'. Supports primary and store engrams. */
   forget(id, reason) {
     const foundInPrimary = withLock(this.paths.engrams, () => {
@@ -3846,17 +4295,38 @@ Generate an improved version of the procedure that prevents this failure. Return
       versioned_engram_count: versionedCount
     };
   }
-  /** Register an additional engram store. */
+  /**
+   * Register an additional engram store.
+   *
+   * Two shapes — exactly one of `pathOrUrl` semantics applies:
+   *   - filesystem (default): pass a path. `options.url` undefined.
+   *   - remote (PLUR Enterprise / any compatible REST API):
+   *     pass any string for the first arg (it goes into a slot we
+   *     never read), set `options.url` + `options.token`.
+   *
+   * Backwards compatible: existing call sites that pass a filesystem
+   * path keep working.
+   */
   addStore(storePath, scope, options) {
     const config = loadConfig(this.paths.config);
-    const existing = config.stores?.find((s) => s.path === storePath);
+    const isRemote = Boolean(options?.url);
+    const dedupKey = isRemote ? options.url : storePath;
+    const existing = config.stores?.find((s) => isRemote ? s.url === dedupKey : s.path === dedupKey);
     if (existing) return;
-    const stores = [...config.stores ?? [], {
+    const newEntry = isRemote ? {
+      url: options.url,
+      token: options.token,
+      scope,
+      shared: options?.shared ?? true,
+      // remote stores are shared by definition
+      readonly: options?.readonly ?? false
+    } : {
       path: storePath,
       scope,
       shared: options?.shared ?? false,
       readonly: options?.readonly ?? false
-    }];
+    };
+    const stores = [...config.stores ?? [], newEntry];
     let configData = {};
     try {
       const raw = fs4.readFileSync(this.paths.config, "utf8");
@@ -3875,20 +4345,19 @@ Generate an improved version of the procedure that prevents this failure. Return
   autoDiscoverStores(cwd) {
     const startDir = cwd || process.cwd();
     const discovered = [];
-    const tmpDir = os.tmpdir();
+    const tmpDir = tmpdir();
     if (this.paths.root.startsWith(tmpDir) || this.paths.root.startsWith("/tmp/")) {
       return discovered;
     }
     const knownPaths = new Set((this.config.stores ?? []).map((s) => s.path));
-    const primaryDir = path3.dirname(this.paths.engrams);
+    const primaryDir = dirname2(this.paths.engrams);
     let dir = startDir;
-    const { join: join5, dirname: dirname3, basename: basename2 } = path3;
     const visited = /* @__PURE__ */ new Set();
     while (dir && !visited.has(dir)) {
       visited.add(dir);
       const candidate = join5(dir, ".plur", "engrams.yaml");
       if (join5(dir, ".plur") === primaryDir) {
-        dir = dirname3(dir);
+        dir = dirname2(dir);
         continue;
       }
       if (fs4.existsSync(candidate) && !knownPaths.has(candidate)) {
@@ -3907,7 +4376,7 @@ Generate an improved version of the procedure that prevents this failure. Return
         logger.info(`Auto-discovered project store: ${candidate} (${scope})`);
       }
       if (fs4.existsSync(join5(dir, ".git"))) break;
-      const parent = dirname3(dir);
+      const parent = dirname2(dir);
       if (parent === dir) break;
       dir = parent;
     }
@@ -3925,29 +4394,57 @@ Generate an improved version of the procedure that prevents this failure. Return
     };
     const additional = stores.map((s) => {
       let count = 0;
-      try {
-        count = this._loadCached(s.path).filter((e) => e.status !== "retired").length;
-      } catch {
+      if (s.url) {
+        try {
+          count = this._loadRemoteCached(s).filter((e) => e.status !== "retired").length;
+        } catch {
+        }
+      } else if (s.path) {
+        try {
+          count = this._loadCached(s.path).filter((e) => e.status !== "retired").length;
+        } catch {
+        }
       }
-      return { ...s, engram_count: count };
+      return {
+        path: s.path,
+        url: s.url,
+        scope: s.scope,
+        shared: s.shared,
+        readonly: s.readonly,
+        engram_count: count
+      };
     });
     return [primary, ...additional];
   }
 };
 export {
   ALL_MIGRATIONS,
+  CAPSULE_FLAGS,
+  CAPSULE_FLAG_RESERVED_MASK,
+  CAPSULE_MAGIC,
+  CAPSULE_MAGIC_HEX,
+  CAPSULE_SIZE_LIMITS,
   COMMITMENT_MULTIPLIER,
   CURRENT_SCHEMA_VERSION,
+  CapsuleHeaderSchema,
   DomainCoverageSchema,
+  ED25519_SIG_LEN,
   EvidenceEntrySchema,
+  FORMAT_VERSION_V1,
   FalsificationSchema,
   HierarchyPositionSchema,
   IndexedStorage,
+  ManifestSummarySchema,
   MetaConfidenceSchema,
   MetaFieldSchema,
   PLATITUDE_PATTERNS,
+  PREAMBLE_LEN,
+  PayloadDescriptorSchema,
   Plur,
+  ProducerSchema,
+  SUPPORTED_FORMAT_VERSIONS,
   SessionBreadcrumbs,
+  SignerSchema,
   SqliteStore,
   StructuralTemplateSchema,
   YamlStore,
@@ -3986,6 +4483,7 @@ export {
   getCachedUpdateCheck,
   getProfileForInjection,
   getSchemaVersion,
+  hasFlag,
   isPlatitude,
   listHistoryMonths,
   loadProfileCache,
@@ -3994,8 +4492,10 @@ export {
   needsSummary,
   normalizeStatement,
   organizeHierarchy,
+  parseCapsulePreamble,
   parseDedupResponse,
   profileNeedsRegeneration,
+  readCapsule,
   readHistory,
   readHistoryForEngram,
   recallAuto,
@@ -4005,9 +4505,12 @@ export {
   saveProfileCache,
   selectModel,
   selectModelForOperation,
+  serializeCapsulePreamble,
   setSchemaVersion,
   strengthToStatus,
   tokenSimilarity,
   validateMetaEngram,
-  withAsyncLock
+  verifyCapsuleIntegrity,
+  withAsyncLock,
+  writeCapsule
 };