@plur-ai/core 0.9.7 → 0.9.8

package/dist/index.d.ts

@@ -2273,6 +2273,33 @@ declare class Plur {
      * Fast-path hash dedup returns existing on exact match.
      */
     learn(statement: string, context?: LearnContext): Engram;
+    /**
+     * Async learn that returns the canonical engram — server-assigned ID
+     * for remote-routed writes, locally-built engram for local writes.
+     *
+     * Use this from async callers (MCP handlers, OpenClaw plugins, etc.)
+     * when the user later needs to reference the engram by ID (forget,
+     * feedback, history). The sync `learn()` returns a local-placeholder
+     * ID for remote-routed writes — the actual server engram has a
+     * different ID, so feedback/forget against the placeholder fails.
+     *
+     * Local writes: just delegates to sync learn(). Same dedup, same
+     * history append, same return shape.
+     *
+     * Remote writes: bypasses local YAML entirely. POSTs to the remote's
+     * /api/v1/engrams, awaits the server's response, and returns an
+     * Engram with the server-assigned id. Throws on remote failure
+     * (caller knows the write didn't land — better UX than a fire-and-
+     * forget that pretends success and leaves the user with a phantom ID).
+     */
+    learnRouted(statement: string, context?: LearnContext): Promise<Engram>;
+    /**
+     * Build an Engram object without persisting it. Used by learnRouted to
+     * give callers a fully-shaped Engram with the server's ID after the
+     * remote POST completes. Mirrors the construction in learn() but
+     * doesn't acquire the lock or touch disk.
+     */
+    private _buildEngramShape;
     /** Build deps for learn-async module. */
     private _learnAsyncDeps;
     /** Async learn with LLM-driven deduplication (Ideas 1+2+19). */

package/dist/index.js

@@ -1617,8 +1617,23 @@ var RemoteStore = class {
    * 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.
+   *
+   * Returns void to satisfy the EngramStore interface contract. Callers
+   * that need the server-assigned ID (e.g. so the user can later
+   * forget/feedback on it) should use `appendAndGetServerId()` instead.
    */
   async append(engram) {
+    await this.appendAndGetServerId(engram);
+  }
+  /**
+   * Like append() but returns the server-assigned ID. Required because
+   * the server picks its own ID (e.g. ENG-2026-05-06-007) and ignores
+   * any id we'd send. Without this, callers see the local placeholder
+   * ID (e.g. ENG-2026-0506-017) and a later `forget(id)` against that
+   * placeholder will fail — the engram only exists on the server with
+   * the server's ID.
+   */
+  async appendAndGetServerId(engram) {
     const body = JSON.stringify({
       statement: engram.statement,
       scope: engram.scope,
@@ -1634,7 +1649,12 @@ var RemoteStore = class {
       const text = await r.text().catch(() => "");
       throw new Error(`Remote store append failed: ${r.status} ${text}`);
     }
+    const data = await r.json().catch(() => ({}));
+    if (!data.id) {
+      throw new Error(`Remote store append succeeded but server returned no id`);
+    }
     this.cache = null;
+    return { id: data.id };
   }
   /**
    * `save(all)` — used by migrations to bulk-replace. Not supported
@@ -3643,6 +3663,115 @@ var Plur = class {
       return engram;
     });
   }
+  /**
+   * Async learn that returns the canonical engram — server-assigned ID
+   * for remote-routed writes, locally-built engram for local writes.
+   *
+   * Use this from async callers (MCP handlers, OpenClaw plugins, etc.)
+   * when the user later needs to reference the engram by ID (forget,
+   * feedback, history). The sync `learn()` returns a local-placeholder
+   * ID for remote-routed writes — the actual server engram has a
+   * different ID, so feedback/forget against the placeholder fails.
+   *
+   * Local writes: just delegates to sync learn(). Same dedup, same
+   * history append, same return shape.
+   *
+   * Remote writes: bypasses local YAML entirely. POSTs to the remote's
+   * /api/v1/engrams, awaits the server's response, and returns an
+   * Engram with the server-assigned id. Throws on remote failure
+   * (caller knows the write didn't land — better UX than a fire-and-
+   * forget that pretends success and leaves the user with a phantom ID).
+   */
+  async learnRouted(statement, context) {
+    if (!this.config.allow_secrets) {
+      const secrets = detectSecrets(statement);
+      if (secrets.length > 0) {
+        throw new Error(`Secret detected in statement: ${secrets[0].pattern}. Use config.allow_secrets to override.`);
+      }
+    }
+    const scope = context?.scope ?? "global";
+    const remoteDriver = this._resolveRemoteStoreForScope(scope);
+    if (!remoteDriver) {
+      return this.learn(statement, context);
+    }
+    const allEngrams = this._loadAllEngrams();
+    const hashMatch = this._hashDedup(statement, allEngrams);
+    if (hashMatch) return hashMatch;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const localPlaceholder = this._buildEngramShape(statement, scope, context, now);
+    const { id: serverId } = await remoteDriver.appendAndGetServerId(localPlaceholder);
+    const serverEngram = { ...localPlaceholder, id: serverId };
+    appendHistory(this.paths.root, {
+      event: "engram_created",
+      engram_id: serverId,
+      timestamp: now,
+      data: { type: serverEngram.type, scope: serverEngram.scope, source: serverEngram.source, routed_to: "remote" }
+    });
+    return serverEngram;
+  }
+  /**
+   * Build an Engram object without persisting it. Used by learnRouted to
+   * give callers a fully-shaped Engram with the server's ID after the
+   * remote POST completes. Mirrors the construction in learn() but
+   * doesn't acquire the lock or touch disk.
+   */
+  _buildEngramShape(statement, scope, context, now) {
+    const type = context?.type ?? "behavioral";
+    const cogLevel = TYPE_TO_COGNITIVE2[type] ?? "remember";
+    const TYPE_TO_MEMORY_CLASS3 = {
+      behavioral: "semantic",
+      terminological: "semantic",
+      procedural: "procedural",
+      architectural: "semantic"
+    };
+    const memoryClass = context?.memory_class ?? TYPE_TO_MEMORY_CLASS3[type] ?? "semantic";
+    const commitment = context?.commitment ?? "leaning";
+    return {
+      // Placeholder id — overwritten by the server's assigned id before return.
+      // Any consumer that observes this id directly (rather than via learnRouted's
+      // return value) is doing it wrong — log says so.
+      id: "__pending__",
+      version: 2,
+      status: "active",
+      consolidated: false,
+      type,
+      scope,
+      visibility: context?.visibility ?? (context?.domain ? "public" : "private"),
+      statement,
+      rationale: context?.rationale,
+      source: context?.source,
+      domain: context?.domain,
+      activation: {
+        retrieval_strength: 0.7,
+        storage_strength: 1,
+        frequency: 0,
+        last_accessed: now.slice(0, 10)
+      },
+      feedback_signals: { positive: 0, negative: 0, neutral: 0 },
+      knowledge_type: { memory_class: memoryClass, cognitive_level: cogLevel },
+      knowledge_anchors: (context?.knowledge_anchors ?? []).map((a) => ({
+        path: a.path,
+        relevance: a.relevance ?? "supporting",
+        snippet: a.snippet
+      })),
+      associations: [],
+      derivation_count: 1,
+      tags: context?.tags ?? [],
+      pack: null,
+      abstract: context?.abstract ?? null,
+      derived_from: context?.derived_from ?? null,
+      dual_coding: context?.dual_coding,
+      polarity: null,
+      content_hash: computeContentHash(statement),
+      commitment,
+      locked_at: commitment === "locked" ? now : void 0,
+      locked_reason: commitment === "locked" ? context?.locked_reason : void 0,
+      summary: autoSummary(statement, void 0),
+      engram_version: 1,
+      episode_ids: context?.session_episode_id ? [context.session_episode_id] : [],
+      pinned: context?.pinned === true ? true : void 0
+    };
+  }
   /** Build deps for learn-async module. */
   _learnAsyncDeps() {
     return {

package/package.json

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