@tpsdev-ai/flair-mcp 0.21.0 → 0.22.0

package/dist/index.d.ts

@@ -8,6 +8,7 @@
  *   - memory_update  — update an existing memory by ID (dedup-bypassed)
  *   - memory_get     — retrieve a specific memory by ID
  *   - memory_delete  — delete a memory
+ *   - relationship_store — assert a subject/predicate/object relationship triple
  *   - bootstrap      — cold-start context (soul + recent memories)
  *   - soul_set       — set a personality/context entry
  *   - soul_get       — get a personality/context entry

package/dist/index.js

@@ -8,6 +8,7 @@
  *   - memory_update  — update an existing memory by ID (dedup-bypassed)
  *   - memory_get     — retrieve a specific memory by ID
  *   - memory_delete  — delete a memory
+ *   - relationship_store — assert a subject/predicate/object relationship triple
  *   - bootstrap      — cold-start context (soul + recent memories)
  *   - soul_set       — set a personality/context entry
  *   - soul_get       — get a personality/context entry
@@ -334,6 +335,41 @@ export async function runMcp() {
             return errorResult(err, flair.url);
         }
     });
+    server.tool("relationship_store", "Record that <subject> <predicate> <object> — an explicit entity-to-entity relationship triple " +
+        "(e.g. 'nathan manages flair', 'flint reviews cli'), distinct from a free-text memory. " +
+        "ASSERT/UPSERT semantics: writing the SAME triple again (same subject/predicate/object) updates the " +
+        "existing row in place (confidence/validTo/source refresh) rather than creating a duplicate — safe to " +
+        "re-assert. Predicate is free text (no fixed enum) but prefer a small, consistent vocabulary so the graph " +
+        "stays queryable: manages, works_on, reviews, depends_on, replaces, owns, reports_to, advises. " +
+        "TO CONTRADICT a prior relationship: (a) re-asserting the identical triple just updates it — fine. " +
+        "(b) changing validTo on the SAME subject/predicate/object overwrites the old validTo (the graph tracks " +
+        "current state, not full history). (c) changing the PREDICATE (e.g. 'nathan manages flair' -> 'nathan " +
+        "advises flair') creates a SEPARATE relationship — it does NOT automatically close the old one. Close it " +
+        "yourself first: re-assert the OLD triple with a validTo set to now (or call relationship's delete), THEN " +
+        "store the new one.", {
+        subject: z.string().describe("Source entity — a person, project, or service (e.g. 'nathan')"),
+        predicate: z.string().describe("Relationship type, free text. Recommended vocabulary: manages, works_on, reviews, depends_on, " +
+            "replaces, owns, reports_to, advises — consistency helps recall, but any short verb phrase works."),
+        object: z.string().describe("Target entity — a person, project, or service (e.g. 'flair')"),
+        confidence: z.coerce.number().optional().describe("0.0-1.0, how certain (default 1.0 = explicitly stated)"),
+        validFrom: z.string().optional().describe("ISO timestamp this relationship became true (default: now)"),
+        validTo: z.string().optional().describe("ISO timestamp this relationship ended. Leave unset for an active relationship; set it (via a re-assert " +
+            "of this SAME subject/predicate/object) to close out a relationship you're contradicting with a new predicate."),
+        source: z.string().optional().describe("Where this was learned from (a memory ID, conversation, etc.)"),
+    }, async ({ subject, predicate, object, confidence, validFrom, validTo, source }) => {
+        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
+        try {
+            const result = await flair.relationship.write({ subject, predicate, object, confidence, validFrom, validTo, source });
+            const confStr = confidence !== undefined ? ` (confidence: ${confidence})` : "";
+            return {
+                content: [{ type: "text", text: `Relationship recorded: ${subject} → ${predicate} → ${object}${confStr} (id: ${result.id})` }],
+                structuredContent: { id: result.id, subject, predicate, object, written: true },
+            };
+        }
+        catch (err) {
+            return errorResult(err, flair.url);
+        }
+    });
     server.tool("bootstrap", "Get session context: soul + memories + predicted context. Run at session start. Pass subjects for predictive loading.", {
         maxTokens: z.coerce.number().optional().default(4000).describe("Max tokens in output"),
         currentTask: z.string().optional().describe("Current task description — enables semantic search for relevant memories"),

package/dist/presence.d.ts

@@ -19,16 +19,23 @@
  * of those decisions without sharing any actual state.
  */
 /** Mirrors VALID_ACTIVITIES in resources/Presence.ts — keep in sync. */
-export type PresenceActivity = "coding" | "reviewing" | "planning" | "idle";
+export type PresenceActivity = "coding" | "reviewing" | "planning" | "debugging" | "idle";
 /**
  * Derive a presence `activity` from the SAME context signals the `bootstrap`
  * tool and the SessionStart hook already receive (channel/surface) — no new
- * inputs, no separate classifier call. Two narrow, name-based overrides for
+ * inputs, no separate classifier call. Three narrow, name-based overrides for
  * the surfaces that are unambiguous on their own; everything else (including
  * no surface at all, e.g. the session-start hook) falls through to "coding",
  * since an MCP tool call is, definitionally, an agent doing something — never
  * "idle" (idle/offline are purely functions of elapsed time since the last
  * heartbeat; see derivePresenceStatus() in resources/Presence.ts).
+ *
+ * "debug"/"investigat"/"incident" is checked FIRST, ahead of "review" and
+ * "plan" — an active incident investigation (flair#613: the flagship
+ * collision-detection use case) is the most unambiguous and highest-signal
+ * surface name an agent can report, and previously had no matching bucket at
+ * all, silently falling into "coding" (or "reviewing" if the surface also
+ * happened to contain that substring — e.g. "incident-review").
  */
 export declare function deriveActivity(ctx?: {
     surface?: string;
@@ -82,6 +89,14 @@ export declare function resolvePresenceTimeoutMs(): number;
  * omitted (not sent as null/empty) when absent, so callers that don't know a
  * task can still heartbeat without explicitly clearing one that was set
  * earlier — see postPresenceSafe()'s doc comment for why that matters.
+ *
+ * Natural-presence: this body always carries `activity`, and the server stamps
+ * `activityUpdatedAt` (resources/Presence.ts, buildPresenceRecord) on any beat
+ * that asserts activity/task — so a working agent keeps activity fresh, and one
+ * that stops lets it decay to last-known automatically (no manual clear). A
+ * future liveness-only beat (this body without `activity`) would refresh
+ * lastHeartbeatAt without re-stamping activity — the server treats the two
+ * independently.
  */
 export declare function buildPresenceBody(activity: PresenceActivity, currentTask?: string): Record<string, unknown>;
 /** Minimal surface a presence write needs from a Flair client — matches

package/dist/presence.js

@@ -21,15 +21,24 @@
 /**
  * Derive a presence `activity` from the SAME context signals the `bootstrap`
  * tool and the SessionStart hook already receive (channel/surface) — no new
- * inputs, no separate classifier call. Two narrow, name-based overrides for
+ * inputs, no separate classifier call. Three narrow, name-based overrides for
  * the surfaces that are unambiguous on their own; everything else (including
  * no surface at all, e.g. the session-start hook) falls through to "coding",
  * since an MCP tool call is, definitionally, an agent doing something — never
  * "idle" (idle/offline are purely functions of elapsed time since the last
  * heartbeat; see derivePresenceStatus() in resources/Presence.ts).
+ *
+ * "debug"/"investigat"/"incident" is checked FIRST, ahead of "review" and
+ * "plan" — an active incident investigation (flair#613: the flagship
+ * collision-detection use case) is the most unambiguous and highest-signal
+ * surface name an agent can report, and previously had no matching bucket at
+ * all, silently falling into "coding" (or "reviewing" if the surface also
+ * happened to contain that substring — e.g. "incident-review").
  */
 export function deriveActivity(ctx = {}) {
     const surface = (ctx.surface ?? "").toLowerCase();
+    if (surface.includes("debug") || surface.includes("investigat") || surface.includes("incident"))
+        return "debugging";
     if (surface.includes("review"))
         return "reviewing";
     if (surface.includes("plan") || surface.includes("spec") || surface.includes("design"))
@@ -123,6 +132,14 @@ function withTimeout(promise, ms) {
  * omitted (not sent as null/empty) when absent, so callers that don't know a
  * task can still heartbeat without explicitly clearing one that was set
  * earlier — see postPresenceSafe()'s doc comment for why that matters.
+ *
+ * Natural-presence: this body always carries `activity`, and the server stamps
+ * `activityUpdatedAt` (resources/Presence.ts, buildPresenceRecord) on any beat
+ * that asserts activity/task — so a working agent keeps activity fresh, and one
+ * that stops lets it decay to last-known automatically (no manual clear). A
+ * future liveness-only beat (this body without `activity`) would refresh
+ * lastHeartbeatAt without re-stamping activity — the server treats the two
+ * independently.
  */
 export function buildPresenceBody(activity, currentTask) {
     const body = { activity };

package/package.json

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