@plur-ai/core 0.9.4 → 0.9.6

package/dist/index.d.ts

@@ -635,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;
 }>;
@@ -705,19 +731,39 @@ declare const PlurConfigSchema: z.ZodObject<{
     }, {
         enabled?: boolean | undefined;
     }>>>;
-    stores: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodObject<{
-        path: z.ZodString;
+    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;
     }, {
-        path: string;
         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;
+    }, {
+        scope: string;
+        path?: string | undefined;
+        url?: string | undefined;
+        token?: string | undefined;
         shared?: boolean | undefined;
         readonly?: boolean | undefined;
     }>, "many">>>;
@@ -778,10 +824,12 @@ declare const PlurConfigSchema: z.ZodObject<{
         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;
@@ -821,8 +869,10 @@ declare const PlurConfigSchema: z.ZodObject<{
         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;
@@ -2175,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.
      *
@@ -2187,6 +2252,16 @@ declare class Plur {
      * freshness and closes the race. See issue #25.
      */
     private _writeEngrams;
+    /**
+     * Resolve a remote store for a write scope. Returns the RemoteStore driver
+     * if the engram's scope matches a registered remote entry, else null.
+     *
+     * Match rule (pilot scope): exact-match `entry.scope === engramScope`. We
+     * intentionally don't do prefix-match yet — agents that want to write to a
+     * narrower scope than they registered must explicitly register the narrower
+     * scope. Keeps routing predictable and prevents accidental cross-team writes.
+     */
+    private _resolveRemoteStoreForScope;
     /** Find which store owns an engram by ID. For namespaced IDs, strips prefix to find in store. */
     private _findEngramStore;
     /** Content hash fast-path dedup. */
@@ -2350,10 +2425,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).
@@ -2366,7 +2454,8 @@ declare class Plur {
     }>;
     /** List all configured stores. */
     listStores(): Array<{
-        path: string;
+        path?: string;
+        url?: string;
         scope: string;
         shared: boolean;
         readonly: boolean;

package/dist/index.js

@@ -177,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);
@@ -223,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"),
@@ -1516,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);
@@ -3220,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)) {
@@ -3263,6 +3401,32 @@ var Plur = class {
     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.
    *
@@ -3278,6 +3442,31 @@ var Plur = class {
     saveEngrams(path3, engrams);
     this._engramCache.delete(path3);
   }
+  /**
+   * Resolve a remote store for a write scope. Returns the RemoteStore driver
+   * if the engram's scope matches a registered remote entry, else null.
+   *
+   * Match rule (pilot scope): exact-match `entry.scope === engramScope`. We
+   * intentionally don't do prefix-match yet — agents that want to write to a
+   * narrower scope than they registered must explicitly register the narrower
+   * scope. Keeps routing predictable and prevents accidental cross-team writes.
+   */
+  _resolveRemoteStoreForScope(scope) {
+    const stores = this.config.stores ?? [];
+    for (const entry of stores) {
+      if (!entry.url) continue;
+      if (entry.readonly === true) continue;
+      if (entry.scope !== scope) continue;
+      const key = `${entry.url}::${entry.scope}`;
+      let driver = this._remoteStores.get(key);
+      if (!driver) {
+        driver = new RemoteStore(entry.url, entry.token ?? "", entry.scope);
+        this._remoteStores.set(key, driver);
+      }
+      return driver;
+    }
+    return null;
+  }
   /** Find which store owns an engram by ID. For namespaced IDs, strips prefix to find in store. */
   _findEngramStore(id) {
     const primaryEngrams = this._loadCached(this.paths.engrams);
@@ -3286,6 +3475,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)) {
@@ -3407,6 +3597,19 @@ var Plur = class {
         } : void 0,
         pinned: context?.pinned === true ? true : void 0
       };
+      const remoteDriver = this._resolveRemoteStoreForScope(scope);
+      if (remoteDriver) {
+        void remoteDriver.append(engram).catch((err) => {
+          logger.error(`[plur:learn] remote append failed for ${engram.id} (scope=${scope}): ${err.message}`);
+        });
+        appendHistory(this.paths.root, {
+          event: "engram_created",
+          engram_id: engram.id,
+          timestamp: now,
+          data: { type: engram.type, scope: engram.scope, source: engram.source, routed_to: "remote" }
+        });
+        return engram;
+      }
       engrams.push(engram);
       this._writeEngrams(this.paths.engrams, engrams);
       this._syncIndex();
@@ -4130,17 +4333,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");
@@ -4208,11 +4432,25 @@ 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];
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plur-ai/core",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",