@tpsdev-ai/flair-mcp 0.49.0 → 0.50.0

package/README.md

@@ -41,12 +41,13 @@ Once configured, Claude Code (or any MCP client) gets these tools:
 | Tool | Description |
 |------|-------------|
 | `memory_search` | Semantic search across memories. Understands "what happened today". |
-| `memory_store` | Save a memory with type (lesson/decision/fact) and durability. |
+| `memory_store` | Save a memory with type (lesson/decision/fact) and durability. Optional `usedMemoryIds` cites memories that informed the write. |
 | `memory_get` | Retrieve a specific memory by ID. |
 | `memory_delete` | Delete a memory. |
 | `bootstrap` | Cold-start context — soul + recent memories in one call. |
 | `soul_set` | Set personality or project context (included in every bootstrap). |
 | `soul_get` | Get a personality or project context entry. |
+| `record_usage` | Report that recalled memories were actually used (drives `usageCount`). |
 
 ## Environment Variables
 

package/dist/index.d.ts

@@ -14,6 +14,7 @@
  *   - soul_get       — get a personality/context entry
  *   - flair_workspace_set — write own WorkspaceState (Office Space coordination)
  *   - flair_orgevent      — publish an OrgEvent attributed to self (no forging)
+ *   - record_usage        — report that recalled memories were actually used (flair#1147)
  *
  * Auto-presence (flair#598): every tool call above triggers a fire-and-forget,
  * rate-limited `POST /Presence` heartbeat for the calling agent (see
@@ -38,4 +39,5 @@
  * — the silent `npx -y @tpsdev-ai/flair-mcp` failure. The shim checks the Node
  * version FIRST, then dynamically imports this module and calls runMcp().
  */
+export declare function classifyError(err: unknown, flairUrl: string): string;
 export declare function runMcp(): Promise<void>;

package/dist/index.js

@@ -14,6 +14,7 @@
  *   - soul_get       — get a personality/context entry
  *   - flair_workspace_set — write own WorkspaceState (Office Space coordination)
  *   - flair_orgevent      — publish an OrgEvent attributed to self (no forging)
+ *   - record_usage        — report that recalled memories were actually used (flair#1147)
  *
  * Auto-presence (flair#598): every tool call above triggers a fire-and-forget,
  * rate-limited `POST /Presence` heartbeat for the calling agent (see
@@ -40,26 +41,27 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { FlairClient, FlairError } from "@tpsdev-ai/flair-client";
+import { FlairClient, FlairError, formatKeyLookup, inspectKeyLookup } from "@tpsdev-ai/flair-client";
 import { z } from "zod";
 import { deriveActivity, postPresenceSafe, resolveHeartbeatIntervalMs, resolvePresenceTimeoutMs, shouldSendHeartbeat, } from "./presence.js";
 import { readEnvOrUnset, stripInterpolationLiteralsFromEnv } from "./env-guard.js";
+import { buildRecordUsageBody, citationIds, withCiteNudge } from "./usage.js";
 import { serverInfo } from "./version.js";
 // ─── Error helpers ──────────────────────────────────────────────────────────
-function classifyError(err, flairUrl) {
+export function classifyError(err, flairUrl) {
     if (err instanceof FlairError) {
         const { status, body } = err;
         if (status === 400)
             return `validation_error: ${body}`;
         if (status === 401 || status === 403) {
-            // Auth failure on a previously-working session usually means the daemon
-            // restarted (config reload, Harper alter_user, port change). Tell the
-            // operator how to recover instead of just surfacing the raw 401 body.
-            return `auth_error: ${body}\n` +
-                `(Hint: this often follows a Flair daemon restart. Try:\n` +
-                `  1. Restart your MCP host (Claude Code, Cursor, etc) to spawn a fresh flair-mcp.\n` +
-                `  2. Check daemon: 'flair status' or 'curl ${flairUrl}/Health'.\n` +
-                `  3. Verify your agent key still matches the registered Agent record.)`;
+            // flair#1271: name the agent, the paths that were looked in, and the
+            // remedy. A cached-miss / wrong-HOME 401 is not a daemon-restart hint.
+            const lookup = err.keyLookup ?? {
+                ...inspectKeyLookup(readEnvOrUnset("FLAIR_AGENT_ID") ?? "", readEnvOrUnset("FLAIR_KEY_PATH")),
+                signed: false,
+                authMethod: "none",
+            };
+            return `auth_error: ${body}\n${formatKeyLookup(lookup)}`;
         }
         if (status === 413)
             return `payload_too_large: ${body}`;
@@ -233,7 +235,7 @@ export async function runMcp() {
                 return `${i + 1}. ${r.content}${meta ? ` (${meta})` : ""}`;
             })
                 .join("\n");
-            return { content: [{ type: "text", text }] };
+            return { content: [{ type: "text", text: withCiteNudge(text) }] };
         }
         catch (err) {
             return errorResult(err, flair.url);
@@ -252,7 +254,9 @@ export async function runMcp() {
             "permanent/persistent -> shared, standard/ephemeral -> private). " +
             "private -- never visible to another agent, even one with a memory grant. " +
             "shared -- visible to the owner and any agent holding a read/search grant."),
-    }, async ({ content, type, durability, tags, visibility }) => {
+        usedMemoryIds: z.array(z.string()).optional().describe("IDs of memories that informed this write (citation-on-write). Credited via the same " +
+            "deduped usage ledger as record_usage. Optional."),
+    }, async ({ content, type, durability, tags, visibility, usedMemoryIds }) => {
         heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
         try {
             const result = await flair.memory.write(content, {
@@ -262,6 +266,7 @@ export async function runMcp() {
                 visibility: visibility,
                 dedup: true,
                 dedupThreshold: 0.95,
+                usedMemoryIds: citationIds(usedMemoryIds),
             });
             // The server's conservative dedup gate NEVER suppresses a write
             // (memory-integrity fix, flair#526) — `result.deduplicated` is a
@@ -305,10 +310,15 @@ export async function runMcp() {
         content: z.string().describe("New content"),
         preserveHistory: z.coerce.boolean().optional().default(false)
             .describe("Write a new supersedes-linked version instead of overwriting in place (default false)"),
-    }, async ({ id, content, preserveHistory }) => {
+        usedMemoryIds: z.array(z.string()).optional().describe("IDs of memories that informed this update (citation-on-write). Credited via the same " +
+            "deduped usage ledger as record_usage. Optional."),
+    }, async ({ id, content, preserveHistory, usedMemoryIds }) => {
         heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
         try {
-            const result = await flair.memory.update(id, content, { preserveHistory });
+            const result = await flair.memory.update(id, content, {
+                preserveHistory,
+                usedMemoryIds: citationIds(usedMemoryIds),
+            });
             const text = preserveHistory
                 ? `Memory updated: new version stored (id: ${result.id}), supersedes ${id}.`
                 : `Memory updated (id: ${id}).`;
@@ -404,7 +414,7 @@ export async function runMcp() {
             if (!result.context) {
                 return { content: [{ type: "text", text: "No context available." }] };
             }
-            return { content: [{ type: "text", text: result.context }] };
+            return { content: [{ type: "text", text: withCiteNudge(result.context) }] };
         }
         catch (err) {
             return errorResult(err, flair.url);
@@ -504,6 +514,38 @@ export async function runMcp() {
             return errorResult(err, flair.url);
         }
     });
+    // ─── Usage feedback (flair#1147) ─────────────────────────────────────────────
+    //
+    // POST /RecordUsage already existed; native /mcp already wrapped it. The
+    // stdio package did not, so a Claude Code / Cursor client could not close
+    // the usageCount loop. Identity is taken from the signed request — the body
+    // carries only memory id(s) + optional attribution, never agentId.
+    server.tool("record_usage", "Report that one or more memories were actually USED — cited or relied on to ground an answer or decision. " +
+        "Distinct from search (surfacing a memory is not usage). Dedup'd (you can only count once per memory) and rate-limited.", {
+        memoryId: z.string().optional().describe("A single memory id that was used"),
+        memoryIds: z.array(z.string()).optional().describe("IDs of the memories that were used (max 20 per call)"),
+        attribution: z.string().optional().describe("Optional one-line note on how it was used (opaque — stored for audit only)"),
+    }, async ({ memoryId, memoryIds, attribution }) => {
+        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
+        try {
+            const body = buildRecordUsageBody({ memoryId, memoryIds, attribution });
+            if (!body) {
+                return {
+                    content: [{ type: "text", text: "record_usage requires memoryId or memoryIds." }],
+                    isError: true,
+                };
+            }
+            const result = await flair.request("POST", "/RecordUsage", body);
+            const text = result?.recorded === true ? "Usage recorded." : "Usage request accepted.";
+            return {
+                content: [{ type: "text", text }],
+                structuredContent: { recorded: result?.recorded === true },
+            };
+        }
+        catch (err) {
+            return errorResult(err, flair.url);
+        }
+    });
     // ─── Start ───────────────────────────────────────────────────────────────────
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/session-start-hook.d.ts

@@ -68,7 +68,7 @@
  *     "hooks": {
  *       "SessionStart": [
  *         { "hooks": [ { "type": "command",
- *           "command": "sh -c 'out=$(FLAIR_AGENT_ID=me npx -y @tpsdev-ai/flair-mcp flair-session-start 2>/dev/null) && printf %s \"$out\" || true'" } ] }
+ *           "command": "sh -c 'out=$(FLAIR_AGENT_ID=me npx -y -p @tpsdev-ai/flair-mcp@<version> flair-session-start 2>/dev/null) && printf %s \"$out\" || true'" } ] }
  *       ]
  *     }
  *   }

package/dist/session-start-hook.js

@@ -68,7 +68,7 @@
  *     "hooks": {
  *       "SessionStart": [
  *         { "hooks": [ { "type": "command",
- *           "command": "sh -c 'out=$(FLAIR_AGENT_ID=me npx -y @tpsdev-ai/flair-mcp flair-session-start 2>/dev/null) && printf %s \"$out\" || true'" } ] }
+ *           "command": "sh -c 'out=$(FLAIR_AGENT_ID=me npx -y -p @tpsdev-ai/flair-mcp@<version> flair-session-start 2>/dev/null) && printf %s \"$out\" || true'" } ] }
  *       ]
  *     }
  *   }

package/dist/usage.d.ts

@@ -0,0 +1,54 @@
+/**
+ * flair#1147 — the usage-feedback loop on the stdio MCP surface.
+ *
+ * Native `/mcp` already exposes `record_usage` and `memory_store.usedMemoryIds`.
+ * The stdio package (`@tpsdev-ai/flair-mcp`) did not, so a Claude Code / Cursor
+ * client had no way to reach POST /RecordUsage. These helpers are the thin
+ * client-side half: body construction for that endpoint, citation passthrough
+ * on write, and the one-line "cite what you use" nudge on recalled ids.
+ *
+ * Identity is NEVER in the body — RecordUsage attributes from the signed
+ * request, same no-forge contract as flair_workspace_set / flair_orgevent.
+ */
+/** One-line instruction on recalled ids (issue ask #3). Search/bootstrap hits are not usage. */
+export declare const CITE_USAGE_NUDGE = "Cite memories you actually use via record_usage (or memory_store.usedMemoryIds). A search or bootstrap hit is not usage.";
+export declare function withCiteNudge(text: string): string;
+/**
+ * Build the POST /RecordUsage body from the MCP tool args.
+ * Accepts singular `memoryId` and/or `memoryIds`. Returns null when there is
+ * nothing to send (the tool should fail locally rather than POST an empty list).
+ * Never includes agentId — the server attributes from the signature.
+ *
+ * MERGE vs PREFER (deliberate, named — Sherlock/Kern #1404):
+ * This helper MERGES `memoryId` + `memoryIds`, then dedupes. Native `/mcp`
+ * `recordUsage` (resources/mcp-tools.ts) PREFERS `memoryIds` and drops
+ * `memoryId` when both are supplied. The HTTP endpoint does the same:
+ * `RecordUsage.post()` is `data?.memoryIds ?? [data?.memoryId]` — PREFER,
+ * not union. If `memoryIds` is present (even `[]`, which is truthy),
+ * `memoryId` is never read.
+ *
+ * The stdio merge is load-bearing because it flattens first: we send only
+ * a single `memoryIds` array, so the server's prefer is never exercised
+ * on two fields. A future path that POSTs both fields through to
+ * `/RecordUsage` without flattening would silently drop `memoryId`
+ * (delivered-but-uncounted; empty `memoryIds: []` alongside a real
+ * `memoryId` would 400 rather than fall through).
+ *
+ * Native prefer is a pre-existing delivered-but-uncounted bug on a
+ * different surface, tracked in flair#1410 — not a regression from this
+ * PR, and not a blocker for #1147. Do not "align" this helper to prefer.
+ */
+export declare function buildRecordUsageBody(args: {
+    memoryId?: string;
+    memoryIds?: string[];
+    attribution?: string;
+}): {
+    memoryIds: string[];
+    attribution?: string;
+} | null;
+/**
+ * Citation-on-write passthrough. Only returns a list when the caller actually
+ * supplied a non-empty array of non-empty strings — omitted/empty is undefined
+ * so the write body stays byte-identical to a pre-#1147 write.
+ */
+export declare function citationIds(usedMemoryIds?: string[]): string[] | undefined;

package/dist/usage.js

@@ -0,0 +1,76 @@
+/**
+ * flair#1147 — the usage-feedback loop on the stdio MCP surface.
+ *
+ * Native `/mcp` already exposes `record_usage` and `memory_store.usedMemoryIds`.
+ * The stdio package (`@tpsdev-ai/flair-mcp`) did not, so a Claude Code / Cursor
+ * client had no way to reach POST /RecordUsage. These helpers are the thin
+ * client-side half: body construction for that endpoint, citation passthrough
+ * on write, and the one-line "cite what you use" nudge on recalled ids.
+ *
+ * Identity is NEVER in the body — RecordUsage attributes from the signed
+ * request, same no-forge contract as flair_workspace_set / flair_orgevent.
+ */
+/** One-line instruction on recalled ids (issue ask #3). Search/bootstrap hits are not usage. */
+export const CITE_USAGE_NUDGE = "Cite memories you actually use via record_usage (or memory_store.usedMemoryIds). A search or bootstrap hit is not usage.";
+export function withCiteNudge(text) {
+    if (!text)
+        return text;
+    return `${text}\n\n${CITE_USAGE_NUDGE}`;
+}
+/**
+ * Build the POST /RecordUsage body from the MCP tool args.
+ * Accepts singular `memoryId` and/or `memoryIds`. Returns null when there is
+ * nothing to send (the tool should fail locally rather than POST an empty list).
+ * Never includes agentId — the server attributes from the signature.
+ *
+ * MERGE vs PREFER (deliberate, named — Sherlock/Kern #1404):
+ * This helper MERGES `memoryId` + `memoryIds`, then dedupes. Native `/mcp`
+ * `recordUsage` (resources/mcp-tools.ts) PREFERS `memoryIds` and drops
+ * `memoryId` when both are supplied. The HTTP endpoint does the same:
+ * `RecordUsage.post()` is `data?.memoryIds ?? [data?.memoryId]` — PREFER,
+ * not union. If `memoryIds` is present (even `[]`, which is truthy),
+ * `memoryId` is never read.
+ *
+ * The stdio merge is load-bearing because it flattens first: we send only
+ * a single `memoryIds` array, so the server's prefer is never exercised
+ * on two fields. A future path that POSTs both fields through to
+ * `/RecordUsage` without flattening would silently drop `memoryId`
+ * (delivered-but-uncounted; empty `memoryIds: []` alongside a real
+ * `memoryId` would 400 rather than fall through).
+ *
+ * Native prefer is a pre-existing delivered-but-uncounted bug on a
+ * different surface, tracked in flair#1410 — not a regression from this
+ * PR, and not a blocker for #1147. Do not "align" this helper to prefer.
+ */
+export function buildRecordUsageBody(args) {
+    const ids = [];
+    if (Array.isArray(args.memoryIds)) {
+        for (const id of args.memoryIds) {
+            if (typeof id === "string" && id.length > 0)
+                ids.push(id);
+        }
+    }
+    if (typeof args.memoryId === "string" && args.memoryId.length > 0) {
+        ids.push(args.memoryId);
+    }
+    const memoryIds = [...new Set(ids)];
+    if (memoryIds.length === 0)
+        return null;
+    const body = { memoryIds };
+    if (typeof args.attribution === "string" && args.attribution.length > 0) {
+        body.attribution = args.attribution;
+    }
+    return body;
+}
+/**
+ * Citation-on-write passthrough. Only returns a list when the caller actually
+ * supplied a non-empty array of non-empty strings — omitted/empty is undefined
+ * so the write body stays byte-identical to a pre-#1147 write.
+ */
+export function citationIds(usedMemoryIds) {
+    if (!Array.isArray(usedMemoryIds) || usedMemoryIds.length === 0)
+        return undefined;
+    if (!usedMemoryIds.every((id) => typeof id === "string" && id.length > 0))
+        return undefined;
+    return usedMemoryIds;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair-mcp",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "description": "MCP server for Flair — persistent memory for Claude Code, Cursor, and any MCP client.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.27.1",
-    "@tpsdev-ai/flair-client": "0.49.0",
+    "@tpsdev-ai/flair-client": "0.50.0",
     "zod": "4.3.6"
   },
   "license": "Apache-2.0",