@plur-ai/core 0.9.3 → 0.9.5

package/README.md

@@ -56,7 +56,7 @@ Next session starts     →  relevant ones injected →  agent remembers
 You rate the result     →  engram strengthens    →  quality improves
 ```
 
-Search is fully local: BM25 over enriched text + BGE-small-en-v1.5 embeddings + Reciprocal Rank Fusion. **86.7% on LongMemEval** — on par with cloud solutions that charge per query.
+Search is fully local: BM25 over enriched text + BGE-small-en-v1.5 embeddings + Reciprocal Rank Fusion. Zero API calls, zero per-query cost. [Benchmark methodology →](https://plur.ai/benchmark.html)
 
 ## Search modes
 

package/dist/{chunk-3ZPTRZE3.js → chunk-EQPTF4JZ.js}

@@ -183,7 +183,17 @@ var EngramSchema = z.object({
   previous_version_ref: PreviousVersionRefSchema.optional(),
   episode_ids: z.array(z.string()).default([]),
   // === SP3: Retrieval & Injection fields ===
-  summary: z.string().max(80).optional()
+  summary: z.string().max(80).optional(),
+  /**
+   * Always-load flag. Pinned engrams bypass the term-hits gate in scoreEngram
+   * and are eligible for injection on every session start, regardless of
+   * keyword overlap with the user's task. Use sparingly: meta-rules,
+   * cross-cutting safety conventions, and core operating principles only.
+   * Pinned engrams still respect the token budget — they bypass per-pack and
+   * per-domain fairness caps in fillTokenBudget so always-load behavior is
+   * honored even if a single pack contributes many.
+   */
+  pinned: z.boolean().optional()
 });
 var EngramSchemaPassthrough = EngramSchema.passthrough();
 

package/dist/{chunk-IGGMRXAB.js → chunk-ZY4R3VEG.js}

@@ -113,21 +113,57 @@ import { existsSync, readFileSync, mkdirSync } from "fs";
 import { join } from "path";
 import { createHash } from "crypto";
 var embedPipeline = null;
+var lastLoadError = null;
 var transformersUnavailable = false;
+function readDisabledFromEnv(env) {
+  const raw = env.PLUR_DISABLE_EMBEDDINGS;
+  if (!raw) return null;
+  const normalized = raw.trim().toLowerCase();
+  if (normalized === "1" || normalized === "true" || normalized === "yes") {
+    return "embeddings disabled by PLUR_DISABLE_EMBEDDINGS env var";
+  }
+  return null;
+}
+var ENV_DISABLED_REASON = readDisabledFromEnv(process.env);
+var embeddingsDisabled = ENV_DISABLED_REASON !== null;
+var disabledReason = ENV_DISABLED_REASON;
+function embedderStatus() {
+  return {
+    available: !embeddingsDisabled && !transformersUnavailable,
+    loaded: embedPipeline !== null,
+    lastError: lastLoadError,
+    disabled: embeddingsDisabled,
+    disabledReason
+  };
+}
+function setEmbeddingsEnabled(enabled, reason) {
+  embeddingsDisabled = !enabled;
+  disabledReason = enabled ? null : reason ?? "embeddings disabled by config";
+  if (!enabled) {
+    embedPipeline = null;
+  }
+}
+function resetEmbedder() {
+  transformersUnavailable = false;
+  lastLoadError = null;
+  embedPipeline = null;
+}
 async function getEmbedder() {
-  if (transformersUnavailable) return null;
-  if (!embedPipeline) {
-    try {
-      const { pipeline } = await import("./transformers.node-PH5YK5EA.js");
-      embedPipeline = await pipeline("feature-extraction", "Xenova/bge-small-en-v1.5", {
-        dtype: "fp32"
-      });
-    } catch {
-      transformersUnavailable = true;
-      return null;
-    }
+  if (embeddingsDisabled) return null;
+  if (embedPipeline) return embedPipeline;
+  try {
+    const { pipeline } = await import("@huggingface/transformers");
+    embedPipeline = await pipeline("feature-extraction", "Xenova/bge-small-en-v1.5", {
+      dtype: "fp32"
+    });
+    transformersUnavailable = false;
+    lastLoadError = null;
+    return embedPipeline;
+  } catch (err) {
+    transformersUnavailable = true;
+    lastLoadError = err instanceof Error ? err.message : String(err);
+    return null;
   }
-  return embedPipeline;
 }
 async function embed(text) {
   const embedder = await getEmbedder();
@@ -226,6 +262,10 @@ export {
   computeIdf,
   ftsScore,
   searchEngrams,
+  readDisabledFromEnv,
+  embedderStatus,
+  setEmbeddingsEnabled,
+  resetEmbedder,
   embed,
   cosineSimilarity,
   embeddingSearch,

package/dist/embeddings-3EXLC3EH.js

@@ -0,0 +1,21 @@
+import {
+  cosineSimilarity,
+  embed,
+  embedderStatus,
+  embeddingSearch,
+  embeddingSearchWithScores,
+  readDisabledFromEnv,
+  resetEmbedder,
+  setEmbeddingsEnabled
+} from "./chunk-ZY4R3VEG.js";
+import "./chunk-PRK3B7WR.js";
+export {
+  cosineSimilarity,
+  embed,
+  embedderStatus,
+  embeddingSearch,
+  embeddingSearchWithScores,
+  readDisabledFromEnv,
+  resetEmbedder,
+  setEmbeddingsEnabled
+};

package/dist/index.d.ts

@@ -320,6 +320,16 @@ declare const EngramSchema: z.ZodObject<{
     }>>;
     episode_ids: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     summary: z.ZodOptional<z.ZodString>;
+    /**
+     * Always-load flag. Pinned engrams bypass the term-hits gate in scoreEngram
+     * and are eligible for injection on every session start, regardless of
+     * keyword overlap with the user's task. Use sparingly: meta-rules,
+     * cross-cutting safety conventions, and core operating principles only.
+     * Pinned engrams still respect the token budget — they bypass per-pack and
+     * per-domain fairness caps in fillTokenBudget so always-load behavior is
+     * honored even if a single pack contributes many.
+     */
+    pinned: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     type: "behavioral" | "architectural" | "procedural" | "terminological";
     status: "active" | "dormant" | "retired" | "candidate";
@@ -425,6 +435,7 @@ declare const EngramSchema: z.ZodObject<{
         changed_at: string;
     } | undefined;
     summary?: string | undefined;
+    pinned?: boolean | undefined;
 }, {
     type: "behavioral" | "architectural" | "procedural" | "terminological";
     status: "active" | "dormant" | "retired" | "candidate";
@@ -530,6 +541,7 @@ declare const EngramSchema: z.ZodObject<{
     } | undefined;
     episode_ids?: string[] | undefined;
     summary?: string | undefined;
+    pinned?: boolean | undefined;
 }>;
 type Engram = z.infer<typeof EngramSchema>;
 type KnowledgeAnchor = z.infer<typeof KnowledgeAnchorSchema>;
@@ -567,12 +579,35 @@ declare function applyBatchDecay(engrams: Engram[], historyRoot: string, options
     modified: Engram[];
 };
 
+interface EmbedderStatus {
+    available: boolean;
+    loaded: boolean;
+    lastError: string | null;
+    /** True when embeddings are explicitly disabled by user (env var or config). */
+    disabled: boolean;
+    /** Human-readable reason when disabled is true; null otherwise. */
+    disabledReason: string | null;
+}
 /** Result with cosine similarity score attached. */
 interface SimilarityResult {
     engram: Engram;
     score: number;
 }
 
+/** Result of a hybrid search call with diagnostic metadata. */
+interface HybridSearchResult {
+    engrams: Engram[];
+    /**
+     * - "hybrid": both BM25 and embeddings contributed (full operation).
+     * - "hybrid-degraded": embeddings were configured to load but failed —
+     *   ran BM25-only as a fallback. Indicates a fault to surface to the user.
+     * - "bm25-only": embeddings are explicitly disabled (env var or
+     *   config.yaml); ran BM25 by design. Not a fault, no remediation needed.
+     */
+    mode: 'hybrid' | 'hybrid-degraded' | 'bm25-only';
+    embedderError: string | null;
+}
+
 declare const EpisodeSchema: z.ZodObject<{
     id: z.ZodString;
     summary: z.ZodString;
@@ -600,19 +635,45 @@ declare const EpisodeSchema: z.ZodObject<{
 }>;
 type Episode = z.infer<typeof EpisodeSchema>;
 
-declare const StoreEntrySchema: z.ZodObject<{
-    path: z.ZodString;
+/**
+ * A store can be either:
+ *   - filesystem (path) — historical default; YAML or SQLite
+ *   - remote (url + token) — speaks to a PLUR Enterprise server over HTTP
+ * Exactly one of path/url must be present.
+ */
+declare const StoreEntrySchema: z.ZodEffects<z.ZodObject<{
+    path: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    token: z.ZodOptional<z.ZodString>;
     scope: z.ZodString;
     shared: z.ZodDefault<z.ZodBoolean>;
     readonly: z.ZodDefault<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
-    path: string;
     scope: string;
     shared: boolean;
     readonly: boolean;
+    path?: string | undefined;
+    url?: string | undefined;
+    token?: string | undefined;
+}, {
+    scope: string;
+    path?: string | undefined;
+    url?: string | undefined;
+    token?: string | undefined;
+    shared?: boolean | undefined;
+    readonly?: boolean | undefined;
+}>, {
+    scope: string;
+    shared: boolean;
+    readonly: boolean;
+    path?: string | undefined;
+    url?: string | undefined;
+    token?: string | undefined;
 }, {
-    path: string;
     scope: string;
+    path?: string | undefined;
+    url?: string | undefined;
+    token?: string | undefined;
     shared?: boolean | undefined;
     readonly?: boolean | undefined;
 }>;
@@ -663,19 +724,46 @@ declare const PlurConfigSchema: z.ZodObject<{
         path?: string | undefined;
         backend?: "yaml" | "sqlite" | undefined;
     }>>>;
-    stores: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodObject<{
-        path: z.ZodString;
+    embeddings: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    }, "strip", z.ZodTypeAny, {
+        enabled?: boolean | undefined;
+    }, {
+        enabled?: boolean | undefined;
+    }>>>;
+    stores: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        token: z.ZodOptional<z.ZodString>;
         scope: z.ZodString;
         shared: z.ZodDefault<z.ZodBoolean>;
         readonly: z.ZodDefault<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
-        path: string;
         scope: string;
         shared: boolean;
         readonly: boolean;
+        path?: string | undefined;
+        url?: string | undefined;
+        token?: string | undefined;
+    }, {
+        scope: string;
+        path?: string | undefined;
+        url?: string | undefined;
+        token?: string | undefined;
+        shared?: boolean | undefined;
+        readonly?: boolean | undefined;
+    }>, {
+        scope: string;
+        shared: boolean;
+        readonly: boolean;
+        path?: string | undefined;
+        url?: string | undefined;
+        token?: string | undefined;
     }, {
-        path: string;
         scope: string;
+        path?: string | undefined;
+        url?: string | undefined;
+        token?: string | undefined;
         shared?: boolean | undefined;
         readonly?: boolean | undefined;
     }>, "many">>>;
@@ -732,11 +820,16 @@ declare const PlurConfigSchema: z.ZodObject<{
         path?: string | undefined;
         backend?: "yaml" | "sqlite" | undefined;
     } | undefined;
+    embeddings?: {
+        enabled?: boolean | undefined;
+    } | undefined;
     stores?: {
-        path: string;
         scope: string;
         shared: boolean;
         readonly: boolean;
+        path?: string | undefined;
+        url?: string | undefined;
+        token?: string | undefined;
     }[] | undefined;
     profile?: {
         enabled?: boolean | undefined;
@@ -772,9 +865,14 @@ declare const PlurConfigSchema: z.ZodObject<{
         path?: string | undefined;
         backend?: "yaml" | "sqlite" | undefined;
     } | undefined;
+    embeddings?: {
+        enabled?: boolean | undefined;
+    } | undefined;
     stores?: {
-        path: string;
         scope: string;
+        path?: string | undefined;
+        url?: string | undefined;
+        token?: string | undefined;
         shared?: boolean | undefined;
         readonly?: boolean | undefined;
     }[] | undefined;
@@ -903,6 +1001,8 @@ interface LearnContext {
     memory_class?: 'semantic' | 'episodic' | 'procedural' | 'metacognitive';
     /** Current session episode ID for episodic anchoring (SP2 Idea 24). */
     session_episode_id?: string;
+    /** Always-load flag — bypass keyword-relevance gate during injection. */
+    pinned?: boolean;
 }
 /** Extended context for async learn with LLM dedup. */
 interface LearnAsyncContext extends LearnContext {
@@ -1846,6 +1946,244 @@ declare function getCachedUpdateCheck(packageName: string): VersionCheckResult |
 /** Clear cache (for testing). */
 declare function clearVersionCache(): void;
 
+declare const CAPSULE_MAGIC: Buffer<ArrayBuffer>;
+declare const CAPSULE_MAGIC_HEX = "50 4c 55 52";
+declare const FORMAT_VERSION_V1 = 1;
+declare const SUPPORTED_FORMAT_VERSIONS: readonly [1];
+declare const CAPSULE_FLAGS: {
+    readonly SIGNED: number;
+    readonly COMPRESSED: number;
+};
+declare const CAPSULE_FLAG_RESERVED_MASK = 65532;
+declare const PREAMBLE_LEN = 12;
+declare const CAPSULE_SIZE_LIMITS: {
+    readonly SOFT_BYTES: number;
+    readonly HARD_BYTES: number;
+};
+declare const ED25519_SIG_LEN = 64;
+declare const ManifestSummarySchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    creator: z.ZodOptional<z.ZodString>;
+    engram_count: z.ZodNumber;
+    domain: z.ZodOptional<z.ZodString>;
+    license: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    license: string;
+    name: string;
+    engram_count: number;
+    domain?: string | undefined;
+    creator?: string | undefined;
+}, {
+    version: string;
+    name: string;
+    engram_count: number;
+    domain?: string | undefined;
+    license?: string | undefined;
+    creator?: string | undefined;
+}>;
+type ManifestSummary = z.infer<typeof ManifestSummarySchema>;
+declare const PayloadDescriptorSchema: z.ZodObject<{
+    compression: z.ZodEnum<["gzip", "none"]>;
+    size_compressed: z.ZodNumber;
+    size_uncompressed: z.ZodNumber;
+    sha256: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    sha256: string;
+    compression: "none" | "gzip";
+    size_compressed: number;
+    size_uncompressed: number;
+}, {
+    sha256: string;
+    compression: "none" | "gzip";
+    size_compressed: number;
+    size_uncompressed: number;
+}>;
+type PayloadDescriptor = z.infer<typeof PayloadDescriptorSchema>;
+declare const ProducerSchema: z.ZodObject<{
+    tool: z.ZodString;
+    version: z.ZodString;
+    agent_id: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    tool: string;
+    agent_id?: string | undefined;
+}, {
+    version: string;
+    tool: string;
+    agent_id?: string | undefined;
+}>;
+type Producer = z.infer<typeof ProducerSchema>;
+declare const SignerSchema: z.ZodObject<{
+    algo: z.ZodLiteral<"ed25519">;
+    public_key: z.ZodString;
+    key_id: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    algo: "ed25519";
+    public_key: string;
+    key_id?: string | undefined;
+}, {
+    algo: "ed25519";
+    public_key: string;
+    key_id?: string | undefined;
+}>;
+type Signer = z.infer<typeof SignerSchema>;
+declare const CapsuleHeaderSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"plur.capsule/1">;
+    product_type: z.ZodEnum<["engram-pack", "skill"]>;
+    manifest_summary: z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        creator: z.ZodOptional<z.ZodString>;
+        engram_count: z.ZodNumber;
+        domain: z.ZodOptional<z.ZodString>;
+        license: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        version: string;
+        license: string;
+        name: string;
+        engram_count: number;
+        domain?: string | undefined;
+        creator?: string | undefined;
+    }, {
+        version: string;
+        name: string;
+        engram_count: number;
+        domain?: string | undefined;
+        license?: string | undefined;
+        creator?: string | undefined;
+    }>;
+    payload: z.ZodObject<{
+        compression: z.ZodEnum<["gzip", "none"]>;
+        size_compressed: z.ZodNumber;
+        size_uncompressed: z.ZodNumber;
+        sha256: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        sha256: string;
+        compression: "none" | "gzip";
+        size_compressed: number;
+        size_uncompressed: number;
+    }, {
+        sha256: string;
+        compression: "none" | "gzip";
+        size_compressed: number;
+        size_uncompressed: number;
+    }>;
+    created_at: z.ZodString;
+    producer: z.ZodObject<{
+        tool: z.ZodString;
+        version: z.ZodString;
+        agent_id: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        version: string;
+        tool: string;
+        agent_id?: string | undefined;
+    }, {
+        version: string;
+        tool: string;
+        agent_id?: string | undefined;
+    }>;
+    signer: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        algo: z.ZodLiteral<"ed25519">;
+        public_key: z.ZodString;
+        key_id: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        algo: "ed25519";
+        public_key: string;
+        key_id?: string | undefined;
+    }, {
+        algo: "ed25519";
+        public_key: string;
+        key_id?: string | undefined;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    schema: "plur.capsule/1";
+    product_type: "engram-pack" | "skill";
+    manifest_summary: {
+        version: string;
+        license: string;
+        name: string;
+        engram_count: number;
+        domain?: string | undefined;
+        creator?: string | undefined;
+    };
+    payload: {
+        sha256: string;
+        compression: "none" | "gzip";
+        size_compressed: number;
+        size_uncompressed: number;
+    };
+    created_at: string;
+    producer: {
+        version: string;
+        tool: string;
+        agent_id?: string | undefined;
+    };
+    signer: {
+        algo: "ed25519";
+        public_key: string;
+        key_id?: string | undefined;
+    } | null;
+}, {
+    schema: "plur.capsule/1";
+    product_type: "engram-pack" | "skill";
+    manifest_summary: {
+        version: string;
+        name: string;
+        engram_count: number;
+        domain?: string | undefined;
+        license?: string | undefined;
+        creator?: string | undefined;
+    };
+    payload: {
+        sha256: string;
+        compression: "none" | "gzip";
+        size_compressed: number;
+        size_uncompressed: number;
+    };
+    created_at: string;
+    producer: {
+        version: string;
+        tool: string;
+        agent_id?: string | undefined;
+    };
+    signer?: {
+        algo: "ed25519";
+        public_key: string;
+        key_id?: string | undefined;
+    } | null | undefined;
+}>;
+type CapsuleHeader = z.infer<typeof CapsuleHeaderSchema>;
+interface CapsulePreamble {
+    formatVersion: number;
+    flags: number;
+    headerLen: number;
+}
+declare function parseCapsulePreamble(buf: Buffer): CapsulePreamble;
+declare function serializeCapsulePreamble(p: CapsulePreamble): Buffer;
+declare function hasFlag(flags: number, flag: number): boolean;
+
+interface WriteCapsuleOptions {
+    payload: Buffer;
+    manifestSummary: ManifestSummary;
+    producer: Producer;
+    productType?: 'engram-pack' | 'skill';
+    compression?: 'gzip' | 'none';
+    sizeUncompressed?: number;
+    createdAt?: string;
+    signer?: Signer | null;
+    signature?: Buffer;
+}
+interface ReadCapsuleResult {
+    header: CapsuleHeader;
+    payload: Buffer;
+    signature: Buffer | null;
+}
+declare function writeCapsule(opts: WriteCapsuleOptions): Buffer;
+declare function readCapsule(buf: Buffer): ReadCapsuleResult;
+declare function verifyCapsuleIntegrity(buf: Buffer): boolean;
+
 interface IngestOptions {
     source?: string;
     extract_only?: boolean;
@@ -1887,6 +2225,21 @@ declare class Plur {
     private _loadAllEngrams;
     /** Load engrams from a path with mtime-based caching */
     private _loadCached;
+    /**
+     * 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.
+     */
+    private _remoteStores;
+    private _loadRemoteCached;
     /**
      * Write engrams to disk and invalidate the cache for that path.
      *
@@ -1935,6 +2288,16 @@ declare class Plur {
     recallSemantic(query: string, options?: Omit<RecallOptions, 'mode' | 'llm'>): Promise<Engram[]>;
     /** Hybrid search: BM25 + embeddings merged via Reciprocal Rank Fusion. Async, no API calls. */
     recallHybrid(query: string, options?: Omit<RecallOptions, 'mode' | 'llm'>): Promise<Engram[]>;
+    /**
+     * 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.
+     */
+    recallHybridWithMeta(query: string, options?: Omit<RecallOptions, 'mode' | 'llm'>): Promise<HybridSearchResult>;
+    /** Inspect embedder availability without forcing a load. */
+    embedderStatus(): EmbedderStatus;
+    /** Reset cached embedder failure state — next call will retry the model load. */
+    resetEmbedder(): void;
     /** Embedding search returning {engram, score}[] with cosine similarity scores. Async, no API calls. */
     similaritySearch(query: string, options?: {
         limit?: number;
@@ -1972,6 +2335,13 @@ declare class Plur {
     };
     /** Update an existing engram in the store by ID. Returns true if found and updated. */
     updateEngram(updated: Engram): boolean;
+    /**
+     * Toggle the always-load (pinned) flag for an engram.
+     * Returns the updated engram on success, null if not found.
+     */
+    setPinned(id: string, pinned: boolean): Engram | null;
+    /** List engrams that have pinned: true. */
+    listPinned(): Engram[];
     /** Set engram status to 'retired'. Supports primary and store engrams. */
     forget(id: string, reason?: string): void;
     /** Remove retired engrams from storage. Returns count of removed and remaining. */
@@ -2045,10 +2415,23 @@ declare class Plur {
     }>;
     /** Return system health info. */
     status(): StatusResult;
-    /** 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: string, scope: string, options?: {
         shared?: boolean;
         readonly?: boolean;
+        url?: string;
+        token?: string;
     }): void;
     /**
      * Auto-discover .plur/engrams.yaml in CWD and parent dirs (up to git root).
@@ -2061,7 +2444,8 @@ declare class Plur {
     }>;
     /** List all configured stores. */
     listStores(): Array<{
-        path: string;
+        path?: string;
+        url?: string;
         scope: string;
         shared: boolean;
         readonly: boolean;
@@ -2069,4 +2453,4 @@ declare class Plur {
     }>;
 }
 
-export { ALL_MIGRATIONS, type AlignmentResult, type Association, type AutoSearchResult, type BatchDecayOptions, type BatchDecayResult, type BoundedRecallResult, COMMITMENT_MULTIPLIER, CURRENT_SCHEMA_VERSION, type CaptureContext, type DecayTransition, type DedupConfig, type DedupDecision, type DomainCoverage, DomainCoverageSchema, type Engram, type EngramCluster, type EngramStore, type Episode, type EvidenceEntry, EvidenceEntrySchema, type ExtractOptions, type ExtractionResult, type Falsification, FalsificationSchema, type HierarchyPosition, HierarchyPositionSchema, type HistoryEvent, IndexedStorage, type IngestCandidate, type IngestOptions, type InjectOptions, type InjectionLayer, type InjectionResult, type KnowledgeAnchor, type LearnAsyncContext, type LearnAsyncResult, type LearnBatchResult, type LearnContext, type LlmFunction, type LlmTierConfig, type MemberAlignment, type MetaConfidence, MetaConfidenceSchema, type MetaField, MetaFieldSchema, type Migration, type MigrationResult, type ModelTier, PLATITUDE_PATTERNS, type PackManifest, Plur, type PlurConfig, type PlurPaths, type PreviewResult, type PreviousVersionRef, type PrivacyIssue, type PrivacyScanResult, type ProfileCache, type RecallBudget, type RecallOptions, type RegistryEntry, type RelationalAnalysis, type RelationalTriple, type SearchStrategy, SessionBreadcrumbs, type SimilarityResult, SqliteStore, type StatusResult, type StorageBackend, type StorageConfig, type StoreEntry, type StructuralTemplate, StructuralTemplateSchema, type SyncResult, type SyncStatus, type TimelineQuery, type TypedRole, type ValidationResult, type VersionCheckResult, YamlStore, alignCluster, analyzeStructure, appendHistory, applyBatchDecay, assignLayer, asyncAtomicWrite, autoSummary, buildBatchDedupPrompt, buildDedupPrompt, checkForUpdate, classifyPolarity, clearVersionCache, clusterByStructure, computeConfidence, computeContentHash, computeMetaConfidence, confidenceBand, createStore, detectPlurStorage, detectSecrets, engramSearchText, extractMetaEngrams, formatLayer1, formatLayer2, formatLayer3, formatWithLayer, formulateMetaEngram, freshTailBoost, generateEventId, generateGuardrails, generateProfile, generateSummary, getCachedUpdateCheck, getProfileForInjection, getSchemaVersion, isPlatitude, listHistoryMonths, loadProfileCache, markProfileDirty, migrateStore, needsSummary, normalizeStatement, organizeHierarchy, parseDedupResponse, profileNeedsRegeneration, readHistory, readHistoryForEngram, recallAuto, resolveOperationTier, rollbackMigrations, runMigrations, saveProfileCache, selectModel, selectModelForOperation, setSchemaVersion, strengthToStatus, tokenSimilarity, validateMetaEngram, withAsyncLock };
+export { ALL_MIGRATIONS, type AlignmentResult, type Association, type AutoSearchResult, type BatchDecayOptions, type BatchDecayResult, type BoundedRecallResult, CAPSULE_FLAGS, CAPSULE_FLAG_RESERVED_MASK, CAPSULE_MAGIC, CAPSULE_MAGIC_HEX, CAPSULE_SIZE_LIMITS, COMMITMENT_MULTIPLIER, CURRENT_SCHEMA_VERSION, type CapsuleHeader, CapsuleHeaderSchema, type CapsulePreamble, type CaptureContext, type DecayTransition, type DedupConfig, type DedupDecision, type DomainCoverage, DomainCoverageSchema, ED25519_SIG_LEN, type Engram, type EngramCluster, type EngramStore, type Episode, type EvidenceEntry, EvidenceEntrySchema, type ExtractOptions, type ExtractionResult, FORMAT_VERSION_V1, type Falsification, FalsificationSchema, type HierarchyPosition, HierarchyPositionSchema, type HistoryEvent, IndexedStorage, type IngestCandidate, type IngestOptions, type InjectOptions, type InjectionLayer, type InjectionResult, type KnowledgeAnchor, type LearnAsyncContext, type LearnAsyncResult, type LearnBatchResult, type LearnContext, type LlmFunction, type LlmTierConfig, type ManifestSummary, ManifestSummarySchema, type MemberAlignment, type MetaConfidence, MetaConfidenceSchema, type MetaField, MetaFieldSchema, type Migration, type MigrationResult, type ModelTier, PLATITUDE_PATTERNS, PREAMBLE_LEN, type PackManifest, type PayloadDescriptor, PayloadDescriptorSchema, Plur, type PlurConfig, type PlurPaths, type PreviewResult, type PreviousVersionRef, type PrivacyIssue, type PrivacyScanResult, type Producer, ProducerSchema, type ProfileCache, type ReadCapsuleResult, type RecallBudget, type RecallOptions, type RegistryEntry, type RelationalAnalysis, type RelationalTriple, SUPPORTED_FORMAT_VERSIONS, type SearchStrategy, SessionBreadcrumbs, type Signer, SignerSchema, type SimilarityResult, SqliteStore, type StatusResult, type StorageBackend, type StorageConfig, type StoreEntry, type StructuralTemplate, StructuralTemplateSchema, type SyncResult, type SyncStatus, type TimelineQuery, type TypedRole, type ValidationResult, type VersionCheckResult, type WriteCapsuleOptions, YamlStore, alignCluster, analyzeStructure, appendHistory, applyBatchDecay, assignLayer, asyncAtomicWrite, autoSummary, buildBatchDedupPrompt, buildDedupPrompt, checkForUpdate, classifyPolarity, clearVersionCache, clusterByStructure, computeConfidence, computeContentHash, computeMetaConfidence, confidenceBand, createStore, detectPlurStorage, detectSecrets, engramSearchText, extractMetaEngrams, formatLayer1, formatLayer2, formatLayer3, formatWithLayer, formulateMetaEngram, freshTailBoost, generateEventId, generateGuardrails, generateProfile, generateSummary, getCachedUpdateCheck, getProfileForInjection, getSchemaVersion, hasFlag, isPlatitude, listHistoryMonths, loadProfileCache, markProfileDirty, migrateStore, needsSummary, normalizeStatement, organizeHierarchy, parseCapsulePreamble, parseDedupResponse, profileNeedsRegeneration, readCapsule, readHistory, readHistoryForEngram, recallAuto, resolveOperationTier, rollbackMigrations, runMigrations, saveProfileCache, selectModel, selectModelForOperation, serializeCapsulePreamble, setSchemaVersion, strengthToStatus, tokenSimilarity, validateMetaEngram, verifyCapsuleIntegrity, withAsyncLock, writeCapsule };