@tpsdev-ai/flair 0.44.4 → 0.44.5

package/dist/resources/mcp-tools.js

@@ -115,6 +115,30 @@ async function unwrap(value) {
     }
     return value;
 }
+/**
+ * flair#1188 — remove the raw `embedding` vector from a record before it is
+ * returned over the MCP surface. A stored memory carries a 768-float
+ * `embedding` (the HNSW vector); inlined into a tool result that is thousands
+ * of noise tokens per record on chat connectors that have a fixed context
+ * budget, and the caller can never do anything useful with it. Returns a
+ * shallow copy WITHOUT `embedding` (never mutates the source record), and
+ * passes through anything that is not a plain record — null, primitives,
+ * arrays, and the `{ error, status }` shapes `unwrap` produces — untouched.
+ *
+ * `memory_search` already projects with an explicit select that omits
+ * `embedding` (resources/semantic-retrieval-core.ts's DEFAULT_SELECT), and
+ * `bootstrap` uses the same select-without-embedding pushdown, so this is only
+ * needed on the FULL-record read/write paths (memory_get, and the write
+ * responses that echo the stored row).
+ */
+function stripEmbedding(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return value;
+    if (!("embedding" in value))
+        return value;
+    const { embedding, ...rest } = value;
+    return rest;
+}
 // ── Tool implementations (thin wrappers over existing handlers) ──────────────
 //
 // Each takes the resolved agent + the parsed tool arguments and returns a plain
@@ -190,7 +214,10 @@ async function memoryStore(agent, args) {
         }
         body.visibility = args.visibility;
     }
-    return unwrap(await h.post(body));
+    // flair#1188 — memory_store's response goes through the same buildWriteResponse
+    // echo as memory_update; strip the server-regenerated embedding so no write
+    // tool ever inlines the vector. No-op when the response carries none.
+    return stripEmbedding(await unwrap(await h.post(body)));
 }
 /**
  * memory_update — id-targeted, dedup-BYPASSED overwrite/version path (memory-
@@ -240,6 +267,20 @@ async function memoryUpdate(agent, args) {
         delete record.validFrom;
         delete record.validTo;
         delete record.archivedAt;
+        // flair#1189 — retrievalCount and lastRetrieved are RECORD-scoped, not
+        // lineage-scoped: a brand-new successor record has no retrieval history of
+        // its OWN, so it must start with none. Inheriting them from the superseded
+        // record via the `...existing` spread produced a successor whose
+        // lastRetrieved PREDATED its own createdAt ("retrieved 8h before it
+        // existed"), silently corrupting any recency/usage-based ranking that reads
+        // these fields. Reset both here, at succession construction — NOT server-
+        // side, because `supersedes` is a PERMANENT property of every successor and
+        // legitimate later retrievalCount bumps route through put() on a record that
+        // still carries it. Usage/citation-ledger counters (usageCount, the #1147
+        // citation ledger) are a SEPARATE, arguably lineage-scoped question and are
+        // deliberately left untouched here (#1147's usage loop is currently inert).
+        record.retrievalCount = 0;
+        delete record.lastRetrieved;
         // flair#718 authorship-provenance — see memoryStore's comment: forward
         // the resolved OAuth client_id (never forgeable via args) so the NEW
         // version's provenance records which client authored this update.
@@ -247,7 +288,10 @@ async function memoryUpdate(agent, args) {
             record.claimedClient = agent.clientId;
         // A create needs a COLLECTION-bound instance (see resources/in-process.ts).
         const coll = await collectionResource(Cls, delegationContext(agent));
-        return unwrap(await coll.post(record));
+        // flair#1188 — the write response echoes the stored row (Memory.post
+        // regenerates the embedding server-side), so strip the vector before it
+        // returns over the MCP surface. No-op when the response carries none.
+        return stripEmbedding(await unwrap(await coll.post(record)));
     }
     const merged = { ...existing, content, updatedAt: new Date().toISOString() };
     delete merged.embedding;
@@ -264,7 +308,9 @@ async function memoryUpdate(agent, args) {
     // the same unloaded-instance defect on the write. The static form loads the
     // row by `merged.id` and threads the context, then dispatches through
     // Memory.put()'s own ownership gate — no scope change, same as the read.
-    return unwrap(await Cls.put(merged, delegationContext(agent)));
+    // flair#1188 — strip the embedding from the echoed write response (Memory.put
+    // regenerates the vector server-side); no-op when the response carries none.
+    return stripEmbedding(await unwrap(await Cls.put(merged, delegationContext(agent))));
 }
 async function memoryGet(agent, args) {
     const Cls = await handler("Memory");
@@ -286,7 +332,13 @@ async function memoryGet(agent, args) {
     // a plain `{ id, includeTrust }` property — Memory.get()'s wantsTrust() reads
     // it there (the in-process shape alongside the HTTP query-param shape).
     const target = args?.includeTrust === true ? { id: args?.id, includeTrust: true } : args?.id;
-    return unwrap(await Cls.get(target, delegationContext(agent)));
+    const result = await unwrap(await Cls.get(target, delegationContext(agent)));
+    // flair#1188 — a by-id get loads the FULL record, including the 768-float
+    // `embedding` vector (search/bootstrap project it out; a raw get does not).
+    // Strip it by default so a chat connector isn't flooded with thousands of
+    // useless tokens per record; return it only when the caller explicitly opts
+    // in via includeEmbedding.
+    return args?.includeEmbedding === true ? result : stripEmbedding(result);
 }
 async function memoryDelete(agent, args) {
     const Cls = await handler("Memory");
@@ -514,13 +566,14 @@ export const TOOLS = {
     memory_get: {
         def: {
             name: "memory_get",
-            description: "Retrieve a specific memory by ID.",
+            description: "Retrieve a specific memory by ID. The record's raw embedding vector is omitted by default (it is large and not useful to a caller); pass includeEmbedding=true to include it.",
             annotations: { readOnlyHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
                     id: { type: "string", description: "Memory ID" },
                     includeTrust: { type: "boolean", description: "Attach a trust-evidence block (provenance, author, usage, freshness, supersession) to the record. Default false." },
+                    includeEmbedding: { type: "boolean", description: "Include the raw embedding vector (hundreds of floats) in the returned record. Omitted by default because it is large and rarely useful to a caller. Default false." },
                 },
                 required: ["id"],
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.44.4",
+  "version": "0.44.5",
   "packageManager": "bun@1.3.10",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",