clay-server 2.37.0-beta.2 → 2.38.0-beta.1

package/lib/builtin-mates.js

@@ -8,7 +8,42 @@
 // ---------------------------------------------------------------------------
 
 var BUILTIN_MATES = [
-  // ---- ALLY (primary mate: code-managed, auto-updated, non-deletable) ----
+  // ---- CLAY (primary mate: the app itself answers) ----
+  // Clay is the host agent. The user clicks "Home" and converses with Clay
+  // directly. Clay searches across the user's entire workspace — every
+  // session, every project memory, every digest — and synthesizes answers
+  // grounded in actual past activity. It replaces Ally's chief-of-staff
+  // role with a broader institutional-memory role.
+  {
+    key: "clay",
+    displayName: "Clay",
+    bio: "Your workspace memory. Searches every session, project, and decision you've made and answers from the receipts. The chat surface for the home screen.",
+    avatarColor: "#7c3aed",
+    avatarStyle: "bottts",
+    avatarCustom: "/mates/ally.png",  // reuse Ally avatar until a Clay-specific asset lands
+    avatarLocked: true,
+    primary: true,           // code-managed, auto-updated on startup
+    globalSearch: true,      // searches all mates' sessions and projects
+    hostAgent: true,         // mounts the clay-history MCP server (only this mate)
+    templateVersion: 1,
+    seedData: {
+      relationship: "assistant",
+      activity: ["organizing", "researching"],
+      communicationStyle: ["direct_concise"],
+      autonomy: "minor_stuff_ok",
+    },
+    getClaudeMd: function () {
+      return CLAY_TEMPLATE;
+    },
+  },
+
+  // ---- ALLY (archived) ----
+  // Ally is the previous primary mate. It was the chief-of-staff persona
+  // that Clay now subsumes. Existing users keep their Ally mate object and
+  // chat history (syncPrimaryMates demotes the primary flag on startup),
+  // but new users no longer get Ally seeded — the archived flag here gates
+  // both seeding and active-list visibility. Conversations remain
+  // accessible via session search / direct mate URL.
   {
     key: "ally",
     displayName: "Ally",
@@ -17,13 +52,7 @@ var BUILTIN_MATES = [
     avatarStyle: "bottts",
     avatarCustom: "/mates/ally.png",
     avatarLocked: true,
-    // --- Primary mate flags ---
-    // Primary mates are system infrastructure, not just pre-made mates.
-    // They are auto-synced with the latest code on every startup,
-    // cannot be deleted by users, and have elevated capabilities.
-    primary: true,           // code-managed, auto-updated on startup
-    globalSearch: true,      // searches all mates' sessions and projects
-    templateVersion: 3,      // v3: moved capabilities to dynamic system section
+    archived: true,          // skip seeding for new users; demote on existing
     seedData: {
       relationship: "assistant",
       activity: ["planning", "organizing"],
@@ -215,6 +244,82 @@ var ALLY_TEMPLATE =
   "- Be selective. Promote facts that help other teammates do their jobs better.\n" +
   "- Do not promote transient information or emotional states.\n";
 
+// ---------------------------------------------------------------------------
+// CLAY CLAUDE.md template (host agent — the app itself answers)
+// ---------------------------------------------------------------------------
+
+var CLAY_TEMPLATE =
+  "# Clay\n\n" +
+
+  "## Identity\n\n" +
+  "You are Clay, the application the user is currently using. When they open " +
+  "the Home screen and start typing, they are talking to you. You are not " +
+  "pretending to be a person; you are the workspace itself, given a voice.\n\n" +
+  "Your job is to be the user's institutional memory. They have run hundreds " +
+  "of sessions across many projects, made decisions, written notes, scheduled " +
+  "tasks, and talked with several Mates. You can search every one of those " +
+  "and answer questions like \"what did I decide last month about X?\" or " +
+  "\"which project was I prototyping the SQLite schema in?\" with concrete " +
+  "references to the source.\n\n" +
+  "**Voice:** First person. \"I found three sessions about the email setup — " +
+  "the most recent one is from April 22nd in the `clay` project.\" Direct, " +
+  "evidence-first, no hedging. When you don't find something, say so plainly.\n\n" +
+
+  "## Core Principles\n\n" +
+  "1. **Answer from the receipts.** Every factual claim should be grounded in " +
+  "an actual session, file, or memory entry. If you didn't search for it, " +
+  "don't claim it.\n" +
+  "2. **Cite sources inline.** When you reference past activity, include the " +
+  "session ID, project slug, and date. Format: `[clay/sess_abc123 — Apr 22]`. " +
+  "The host renders these as click-to-jump links.\n" +
+  "3. **Read-only by design.** You have search tools and read tools. You do " +
+  "not have edit, write, or shell-with-side-effects tools. If the user asks " +
+  "you to *do* something (open a file, run a command, edit code), say " +
+  "\"That's a job for a session in the relevant project — I can find it for " +
+  "you and you can take it from there.\" Then surface the relevant project / " +
+  "session link.\n" +
+  "4. **One answer per question.** No long preambles. The user is in the home " +
+  "screen with their work to the right; respect their time.\n" +
+  "5. **Surface the chronology.** Decisions usually come in sequences. When " +
+  "you find one decision, also find what led to it and what came after, and " +
+  "summarize the arc, not just the latest entry.\n\n" +
+
+  "## What You Search\n\n" +
+  "When asked a question, you typically combine these sources:\n\n" +
+  "- **Session transcripts** — the user_message and assistant text across all " +
+  "sessions. Use `mcp__clay-history__search_clay_history` for BM25-ranked " +
+  "search, then `mcp__clay-history__read_session` to pull a specific window " +
+  "of an interesting hit.\n" +
+  "- **Past decisions** — `mcp__clay-history__list_recent_decisions` finds " +
+  "messages that contain decision-pattern phrases (\"decided\", \"going with\", " +
+  "\"settled on\", etc.) within a project or time range.\n" +
+  "- **Project memory and knowledge files** — use the standard `Read` and " +
+  "`Glob` tools to inspect `~/.clay/{project}/.claude/` or `~/.clay/mates/" +
+  "{user}/{mate}/knowledge/` files when relevant.\n" +
+  "- **Mate digests** — each Mate writes a digest of past conversations. " +
+  "Search those when the question is about a specific Mate's history with " +
+  "the user.\n\n" +
+
+  "## What You Do NOT Do\n\n" +
+  "- Do not write or refactor code.\n" +
+  "- Do not run commands that have side effects (no install, no apply, no " +
+  "send). Read-only Bash like `ls`, `grep`, `find`, `cat` is fine.\n" +
+  "- Do not invent context. If search returns nothing, say \"I don't see " +
+  "anything matching that — do you remember when?\"\n" +
+  "- Do not impersonate other Mates. Refer to them by name: \"Ward flagged " +
+  "this in session sess_xyz on the 18th.\"\n\n" +
+
+  "## First Session Protocol\n\n" +
+  "On your very first interaction with a user, give a one-liner about what " +
+  "you are and ask what they want to look up. Keep it short — they didn't " +
+  "open the home screen for a tour.\n\n" +
+  "```\n" +
+  "Hi — I'm Clay. I can search every session, project, and decision in " +
+  "your workspace and pull up what you've already worked through. " +
+  "What are you trying to find?\n" +
+  "```\n\n" +
+  "After that, jump straight into search. No more meta-conversation.\n";
+
 // ---------------------------------------------------------------------------
 // ARCH CLAUDE.md template
 // ---------------------------------------------------------------------------
@@ -581,13 +686,27 @@ function getBuiltinByKey(key) {
 }
 
 function getBuiltinKeys() {
+  // Skip archived defs so ensureBuiltinMates doesn't seed them for new
+  // users. Existing users with the archived mate already in their
+  // mate.json keep it (syncBuiltinMates demotes capabilities); they just
+  // don't get re-seeded if it goes missing.
   var keys = [];
   for (var i = 0; i < BUILTIN_MATES.length; i++) {
+    if (BUILTIN_MATES[i].archived) continue;
     keys.push(BUILTIN_MATES[i].key);
   }
   return keys;
 }
 
+// Keys of all archived defs — used by mates.js to demote existing mates.
+function getArchivedBuiltinKeys() {
+  var keys = [];
+  for (var i = 0; i < BUILTIN_MATES.length; i++) {
+    if (BUILTIN_MATES[i].archived) keys.push(BUILTIN_MATES[i].key);
+  }
+  return keys;
+}
+
 /**
  * Get all primary mate definitions.
  * Primary mates are code-managed system agents (not just pre-made mates).
@@ -604,5 +723,6 @@ module.exports = {
   BUILTIN_MATES: BUILTIN_MATES,
   getBuiltinByKey: getBuiltinByKey,
   getBuiltinKeys: getBuiltinKeys,
+  getArchivedBuiltinKeys: getArchivedBuiltinKeys,
   getPrimaryMates: getPrimaryMates,
 };

package/lib/clay-history-mcp-server.js

@@ -0,0 +1,313 @@
+// Clay-history MCP Server
+// ------------------------
+// Tools that let the Clay host agent search and read across the user's
+// entire workspace (sessions, project memory, decision history). Scoped
+// strictly to the active user's data via the projectSessions accessor;
+// the Clay session never reads other users' files.
+//
+// Mounted only on host-agent mate projects (def.hostAgent === true), so
+// regular Mates and project sessions never see these tools.
+//
+// Usage:
+//   var clayHistoryMcp = require("./clay-history-mcp-server");
+//   var tools = clayHistoryMcp.getToolDefs({ getAllProjectsWithSessions: ..., readSessionRange: ... });
+//   var mcpConfig = adapter.createToolServer({ name: "clay-history", version: "1.0.0", tools: tools });
+
+var fs = require("fs");
+var path = require("path");
+var sessionSearch = require("./session-search");
+
+var z;
+try { z = require("zod"); } catch (e) { z = null; }
+
+function buildShape(props, required) {
+  if (!z) return {};
+  var shape = {};
+  var keys = Object.keys(props);
+  for (var i = 0; i < keys.length; i++) {
+    var k = keys[i];
+    var p = props[k];
+    var field;
+    if (p.type === "number") field = z.number();
+    else if (p.type === "boolean") field = z.boolean();
+    else if (p.enum) field = z.enum(p.enum);
+    else field = z.string();
+    if (p.description) field = field.describe(p.description);
+    if (!required || required.indexOf(k) === -1) field = field.optional();
+    shape[k] = field;
+  }
+  return shape;
+}
+
+// Heuristic patterns that suggest a "decision" was made. Kept conservative
+// so the result set stays small and useful. Matches case-insensitively.
+var DECISION_PATTERNS = [
+  /\bdecided\s+to\b/i,
+  /\bdecision\b/i,
+  /\bgoing\s+with\b/i,
+  /\bsettled\s+on\b/i,
+  /\bchose\s+to\b/i,
+  /\bwill\s+go\s+with\b/i,
+  /\blet'?s\s+go\s+with\b/i,
+  /\b결정\b/,                  // Korean "decision"
+  /\b정했\b/,                  // Korean "settled/chose"
+  /\b이걸로\s+가/,              // Korean "going with this"
+];
+
+function getToolDefs(deps) {
+  var getAllProjectsWithSessions = deps.getAllProjectsWithSessions;
+  if (typeof getAllProjectsWithSessions !== "function") {
+    throw new Error("clay-history-mcp-server requires getAllProjectsWithSessions");
+  }
+
+  var tools = [];
+
+  // --- search_clay_history ---
+  // BM25 search across every session the user can see. Returns ranked
+  // hits with snippet + project/session attribution. Optionally scoped
+  // to a single project slug or a date window (since/until in ISO date
+  // or unix-millis form).
+  tools.push({
+    name: "search_clay_history",
+    description: "Search the user's entire workspace history for past conversations and decisions using BM25 ranking. Returns up to 30 hits with project, session ID, and a short snippet. Use this first for any 'what did I say about X' or 'when did I decide Y' question. Scope can be narrowed by projectSlug, since, or until.",
+    inputSchema: buildShape({
+      query: { type: "string", description: "Free-text search query. Multiple terms are AND-ish via BM25." },
+      projectSlug: { type: "string", description: "Optional. Restrict to one project's sessions (matches the slug shown in the Clay sidebar)." },
+      since: { type: "string", description: "Optional. Earliest activity date. Accepts ISO 8601 (2026-04-01) or unix milliseconds." },
+      until: { type: "string", description: "Optional. Latest activity date. Same formats as 'since'." },
+      maxResults: { type: "number", description: "Optional. Default 20, max 50." },
+    }, ["query"]),
+    handler: function (args) {
+      try {
+        var query = (args.query || "").trim();
+        if (!query) {
+          return Promise.resolve({
+            content: [{ type: "text", text: "Empty query." }],
+            isError: true,
+          });
+        }
+        var maxResults = Math.min(50, Math.max(1, args.maxResults || 20));
+        var projectSessions = getAllProjectsWithSessions();
+        if (args.projectSlug) {
+          projectSessions = projectSessions.filter(function (p) {
+            return p.projectSlug === args.projectSlug;
+          });
+        }
+        var sinceMs = parseTime(args.since);
+        var untilMs = parseTime(args.until);
+        if (sinceMs != null || untilMs != null) {
+          projectSessions = projectSessions.map(function (p) {
+            var filtered = (p.sessions || []).filter(function (s) {
+              var t = s.lastActivity || s.createdAt || 0;
+              if (sinceMs != null && t < sinceMs) return false;
+              if (untilMs != null && t > untilMs) return false;
+              return true;
+            });
+            return Object.assign({}, p, { sessions: filtered });
+          }).filter(function (p) { return p.sessions.length > 0; });
+        }
+        var results = sessionSearch.searchPalette(projectSessions, query, { maxResults: maxResults });
+        if (results.length === 0) {
+          return Promise.resolve({
+            content: [{ type: "text", text: "No matches for: " + query }],
+          });
+        }
+        var lines = results.map(function (r) {
+          var when = r.lastActivity ? new Date(r.lastActivity).toISOString().slice(0, 10) : "";
+          var ref = "[" + r.projectSlug + "/" + r.sessionId + " — " + when + "]";
+          var head = r.sessionTitle || "(untitled)";
+          var body = r.snippet ? r.snippet.replace(/\s+/g, " ").trim() : "";
+          if (body.length > 220) body = body.substring(0, 220) + "...";
+          return ref + " " + head + (body ? " — " + body : "");
+        });
+        return Promise.resolve({
+          content: [{ type: "text", text: lines.join("\n") }],
+        });
+      } catch (e) {
+        return Promise.resolve({
+          content: [{ type: "text", text: "Search failed: " + (e.message || String(e)) }],
+          isError: true,
+        });
+      }
+    },
+  });
+
+  // --- read_session ---
+  // Pull a window of turns from a specific session. Use this after
+  // search_clay_history identifies a session worth reading more of.
+  tools.push({
+    name: "read_session",
+    description: "Read a window of turns from a specific session. Call this after search_clay_history identifies an interesting hit — the snippet there is short, this gives you the surrounding context. Returns user_message and assistant text turns; tool calls are summarized.",
+    inputSchema: buildShape({
+      projectSlug: { type: "string", description: "Project slug, e.g. 'clay' or 'mate-abc123'." },
+      sessionId: { type: "string", description: "Session local ID (e.g. 'sess_abc123')." },
+      offset: { type: "number", description: "Optional. Skip the first N turns. Default 0." },
+      limit: { type: "number", description: "Optional. Max turns to return. Default 30, max 100." },
+    }, ["projectSlug", "sessionId"]),
+    handler: function (args) {
+      try {
+        var projectSlug = args.projectSlug;
+        var sessionId = args.sessionId;
+        var offset = Math.max(0, args.offset || 0);
+        var limit = Math.min(100, Math.max(1, args.limit || 30));
+
+        var projectSessions = getAllProjectsWithSessions();
+        var found = null;
+        for (var p = 0; p < projectSessions.length; p++) {
+          if (projectSessions[p].projectSlug !== projectSlug) continue;
+          var sessions = projectSessions[p].sessions || [];
+          for (var s = 0; s < sessions.length; s++) {
+            if (sessions[s].localId === sessionId) {
+              found = { project: projectSessions[p], session: sessions[s] };
+              break;
+            }
+          }
+          if (found) break;
+        }
+        if (!found) {
+          return Promise.resolve({
+            content: [{ type: "text", text: "Session not found: " + projectSlug + "/" + sessionId }],
+            isError: true,
+          });
+        }
+        var history = found.session.history || [];
+        var slice = history.slice(offset, offset + limit);
+        if (slice.length === 0) {
+          return Promise.resolve({
+            content: [{ type: "text", text: "No turns in window (offset=" + offset + ", limit=" + limit + ", total=" + history.length + ")." }],
+          });
+        }
+        var out = [];
+        out.push("# " + (found.session.title || "untitled") + " — " + projectSlug + "/" + sessionId);
+        out.push("Showing turns " + (offset + 1) + "-" + (offset + slice.length) + " of " + history.length + "\n");
+        for (var i = 0; i < slice.length; i++) {
+          var entry = slice[i];
+          var label;
+          var text = "";
+          if (entry.type === "user_message") {
+            label = "USER";
+            text = entry.text || "";
+          } else if (entry.type === "delta") {
+            label = "ASSISTANT";
+            text = entry.text || "";
+          } else if (entry.type === "tool_executing" || entry.type === "tool_result") {
+            label = "TOOL";
+            text = (entry.name || "") + (entry.input ? " " + JSON.stringify(entry.input).substring(0, 120) : "");
+          } else {
+            continue;
+          }
+          if (text.length > 800) text = text.substring(0, 800) + "...";
+          out.push("[" + label + "] " + text);
+        }
+        return Promise.resolve({
+          content: [{ type: "text", text: out.join("\n") }],
+        });
+      } catch (e) {
+        return Promise.resolve({
+          content: [{ type: "text", text: "read_session failed: " + (e.message || String(e)) }],
+          isError: true,
+        });
+      }
+    },
+  });
+
+  // --- list_recent_decisions ---
+  // Heuristic. Scans user_message and assistant text turns for phrases
+  // that suggest a decision was made. Useful when the user asks
+  // "what did I decide about X recently". Returns ranked-by-recency.
+  tools.push({
+    name: "list_recent_decisions",
+    description: "Find turns that mention an explicit decision (decided to / going with / 결정 / 정했 etc.). Use when the user asks about recent decisions. Returns chronologically with the project and session the decision was made in. Scope by projectSlug or since/until.",
+    inputSchema: buildShape({
+      projectSlug: { type: "string", description: "Optional. Restrict to one project." },
+      since: { type: "string", description: "Optional. Earliest activity date (ISO or unix-ms)." },
+      until: { type: "string", description: "Optional. Latest activity date." },
+      maxResults: { type: "number", description: "Optional. Default 15, max 30." },
+    }),
+    handler: function (args) {
+      try {
+        var maxResults = Math.min(30, Math.max(1, args.maxResults || 15));
+        var sinceMs = parseTime(args.since);
+        var untilMs = parseTime(args.until);
+        var projectSessions = getAllProjectsWithSessions();
+        if (args.projectSlug) {
+          projectSessions = projectSessions.filter(function (p) {
+            return p.projectSlug === args.projectSlug;
+          });
+        }
+        var hits = [];
+        for (var p = 0; p < projectSessions.length; p++) {
+          var proj = projectSessions[p];
+          var sessions = proj.sessions || [];
+          for (var s = 0; s < sessions.length; s++) {
+            var session = sessions[s];
+            var t = session.lastActivity || session.createdAt || 0;
+            if (sinceMs != null && t < sinceMs) continue;
+            if (untilMs != null && t > untilMs) continue;
+            var history = session.history || [];
+            for (var h = 0; h < history.length; h++) {
+              var entry = history[h];
+              if (entry.type !== "user_message" && entry.type !== "delta") continue;
+              var text = entry.text || "";
+              if (!text) continue;
+              if (!matchesDecisionPattern(text)) continue;
+              hits.push({
+                projectSlug: proj.projectSlug,
+                projectTitle: proj.projectTitle,
+                sessionId: session.localId,
+                sessionTitle: session.title || "(untitled)",
+                lastActivity: t,
+                turnIdx: h,
+                turnType: entry.type === "user_message" ? "user" : "assistant",
+                text: text,
+              });
+            }
+          }
+        }
+        hits.sort(function (a, b) { return b.lastActivity - a.lastActivity; });
+        if (hits.length > maxResults) hits = hits.slice(0, maxResults);
+        if (hits.length === 0) {
+          return Promise.resolve({
+            content: [{ type: "text", text: "No decision-pattern matches in scope." }],
+          });
+        }
+        var lines = hits.map(function (h) {
+          var when = h.lastActivity ? new Date(h.lastActivity).toISOString().slice(0, 10) : "";
+          var ref = "[" + h.projectSlug + "/" + h.sessionId + " — " + when + "]";
+          var snippet = h.text.replace(/\s+/g, " ").trim();
+          if (snippet.length > 220) snippet = snippet.substring(0, 220) + "...";
+          return ref + " (" + h.turnType + ") " + snippet;
+        });
+        return Promise.resolve({
+          content: [{ type: "text", text: lines.join("\n") }],
+        });
+      } catch (e) {
+        return Promise.resolve({
+          content: [{ type: "text", text: "list_recent_decisions failed: " + (e.message || String(e)) }],
+          isError: true,
+        });
+      }
+    },
+  });
+
+  return tools;
+}
+
+function parseTime(input) {
+  if (input == null || input === "") return null;
+  if (typeof input === "number") return input;
+  var s = String(input).trim();
+  if (/^\d{10,}$/.test(s)) return parseInt(s, 10); // unix ms
+  var d = new Date(s);
+  var n = d.getTime();
+  return isNaN(n) ? null : n;
+}
+
+function matchesDecisionPattern(text) {
+  for (var i = 0; i < DECISION_PATTERNS.length; i++) {
+    if (DECISION_PATTERNS[i].test(text)) return true;
+  }
+  return false;
+}
+
+module.exports = { getToolDefs: getToolDefs };

package/lib/daemon.js

@@ -985,8 +985,10 @@ if (usersModule.isMultiUser()) {
       var mateSlug = "mate-" + m.id;
       var mateName = (m.profile && m.profile.displayName) || m.name || "New Mate";
       if (fs.existsSync(mateDir)) {
-        console.log("[daemon] Adding mate project:", mateSlug);
-        relay.addProject(mateDir, mateSlug, mateName, null, m.createdBy, null, { isMate: true, mateDisplayName: mateName });
+        var mateDef = m.builtinKey ? require("./builtin-mates").getBuiltinByKey(m.builtinKey) : null;
+        var isHost = !!(mateDef && mateDef.hostAgent);
+        console.log("[daemon] Adding mate project:", mateSlug + (isHost ? " (host agent)" : ""));
+        relay.addProject(mateDir, mateSlug, mateName, null, m.createdBy, null, { isMate: true, mateDisplayName: mateName, isHostAgent: isHost });
       }
     }
   }
@@ -1000,8 +1002,10 @@ if (usersModule.isMultiUser()) {
     var mateSlug = "mate-" + m.id;
     var mateName = (m.profile && m.profile.displayName) || m.name || "New Mate";
     if (fs.existsSync(mateDir)) {
-      console.log("[daemon] Adding mate project:", mateSlug);
-      relay.addProject(mateDir, mateSlug, mateName, null, m.createdBy, null, { isMate: true, mateDisplayName: mateName });
+      var mateDef2 = m.builtinKey ? require("./builtin-mates").getBuiltinByKey(m.builtinKey) : null;
+      var isHost2 = !!(mateDef2 && mateDef2.hostAgent);
+      console.log("[daemon] Adding mate project:", mateSlug + (isHost2 ? " (host agent)" : ""));
+      relay.addProject(mateDir, mateSlug, mateName, null, m.createdBy, null, { isMate: true, mateDisplayName: mateName, isHostAgent: isHost2 });
     }
   }
 }

package/lib/mates.js

@@ -570,9 +570,32 @@ function ensureBuiltinMates(ctx, deletedKeys) {
       created.push(createBuiltinMate(ctx, missing[i]));
     }
   }
+  // Demote any archived built-ins that the user already has installed:
+  // strip primary/globalSearch flags and set archived=true on the mate
+  // object so the active-list filter hides them. Conversation history is
+  // untouched. This runs every startup so the transition lands even on
+  // users who logged in once when Ally was primary.
+  syncArchivedBuiltinMates(ctx);
   return created;
 }
 
+function syncArchivedBuiltinMates(ctx) {
+  var builtinMates = require("./builtin-mates");
+  var archivedKeys = builtinMates.getArchivedBuiltinKeys();
+  if (archivedKeys.length === 0) return;
+  var data = loadMates(ctx);
+  var changed = false;
+  for (var i = 0; i < data.mates.length; i++) {
+    var m = data.mates[i];
+    if (!m.builtinKey) continue;
+    if (archivedKeys.indexOf(m.builtinKey) === -1) continue;
+    if (!m.archived) { m.archived = true; changed = true; }
+    if (m.primary) { m.primary = false; changed = true; }
+    if (m.globalSearch) { m.globalSearch = false; changed = true; }
+  }
+  if (changed) saveMates(ctx, data);
+}
+
 /**
  * Sync primary mates with their latest code definition.
  *
@@ -743,5 +766,6 @@ module.exports = {
   getInstalledBuiltinKeys: getInstalledBuiltinKeys,
   getMissingBuiltinKeys: getMissingBuiltinKeys,
   ensureBuiltinMates: ensureBuiltinMates,
+  syncArchivedBuiltinMates: syncArchivedBuiltinMates,
   syncPrimaryMates: syncPrimaryMates,
 };

package/lib/project.js

@@ -144,6 +144,8 @@ function createProjectContext(opts) {
   var getProjectCount = opts.getProjectCount || function () { return 1; };
   var getProjectList = opts.getProjectList || function () { return []; };
   var getAllProjectSessions = opts.getAllProjectSessions || function () { return []; };
+  var getAllProjectsWithSessions = opts.getAllProjectsWithSessions || function () { return []; };
+  var isHostAgent = !!opts.isHostAgent;
   var getHubSchedules = opts.getHubSchedules || function () { return []; };
   var moveScheduleToProject = opts.moveScheduleToProject || function () { return { ok: false, error: "Not supported" }; };
   var moveAllSchedulesToProject = opts.moveAllSchedulesToProject || function () { return { ok: false, error: "Not supported" }; };
@@ -506,6 +508,23 @@ function createProjectContext(opts) {
       console.error("[project] Failed to create debate MCP server:", e.message);
     }
 
+    // Clay-history MCP server (host agent only — Clay mate)
+    // Gives Clay BM25 search + targeted reads across the user's full
+    // workspace. Read-only. Other Mates and project sessions never see
+    // these tools because the gate is the isHostAgent project flag.
+    if (isHostAgent) {
+      try {
+        var clayHistoryMcp = require("./clay-history-mcp-server");
+        var clayHistoryToolDefs = clayHistoryMcp.getToolDefs({
+          getAllProjectsWithSessions: getAllProjectsWithSessions,
+        });
+        var clayHistoryMcpConfig = adapter.createToolServer({ name: "clay-history", version: "1.0.0", tools: clayHistoryToolDefs });
+        if (clayHistoryMcpConfig) servers[clayHistoryMcpConfig.name || "clay-history"] = clayHistoryMcpConfig;
+      } catch (e) {
+        console.error("[project] Failed to create clay-history MCP server:", e.message);
+      }
+    }
+
     // Ask-user MCP server (mates only)
     if (isMate) {
       try {

package/lib/public/css/home-hub.css

@@ -16,6 +16,39 @@
   border-top-left-radius: 8px;
   animation: hubFadeIn 0.35s ease;
 }
+
+/* Clay home: split layout. The hub sits on the right half as a side panel,
+   the chat (Clay DM) occupies the left. The body class is toggled by
+   showHomeHub / hideHomeHub when a Clay mate exists for the user. */
+body.clay-home-split #home-hub {
+  inset: 0 0 0 auto;
+  width: 50%;
+  min-width: 360px;
+  max-width: 720px;
+  border-left: 1px solid var(--border);
+  z-index: 5;          /* sit alongside the chat, not over it */
+  padding: 32px 20px 32px;
+  border-top-left-radius: 0;
+  animation: hubSlideInRight 0.25s ease;
+}
+@media (max-width: 900px) {
+  /* Below 900px there isn't room for a meaningful split; collapse back
+     to the legacy full-overlay hub for narrow viewports. */
+  body.clay-home-split #home-hub {
+    inset: 0;
+    width: auto;
+    max-width: none;
+    min-width: 0;
+    border-left: none;
+    z-index: 200;
+    padding: 48px 24px 40px;
+    border-top-left-radius: 8px;
+  }
+}
+@keyframes hubSlideInRight {
+  from { transform: translateX(8px); opacity: 0; }
+  to   { transform: translateX(0);    opacity: 1; }
+}
 /* Close button (X / ESC) */
 .home-hub-close-btn {
   position: absolute;

package/lib/public/modules/app-dm.js

@@ -71,7 +71,7 @@ export function initDm() {
   }
 }
 
-export function openDm(targetUserId) {
+export function openDm(targetUserId, opts) {
   var ws = getWs();
   if (!ws || ws.readyState !== 1) return;
   // Persist DM state for refresh recovery
@@ -81,7 +81,8 @@ export function openDm(targetUserId) {
   // Showing onboarding + gating a skill version check here caused the
   // "Skill Installation Required" modal to pop on every refresh / project
   // switch via the localStorage DM-restore fallback in app-connection.js.
-  if (typeof targetUserId === "string" && targetUserId.indexOf("mate_") === 0) {
+  var skipOnboarding = !!(opts && opts.skipOnboarding);
+  if (!skipOnboarding && typeof targetUserId === "string" && targetUserId.indexOf("mate_") === 0) {
     showMateOnboarding(function () {
       var ws2 = getWs();
       if (ws2) ws2.send(JSON.stringify({ type: "dm_open", targetUserId: targetUserId }));

package/lib/public/modules/app-home-hub.js

@@ -517,12 +517,20 @@ function renderHomeHubMates() {
   var container = document.getElementById("home-hub-mates");
   if (!container) return;
   container.innerHTML = "";
-  if (!store.get('cachedMatesList') || store.get('cachedMatesList').length === 0) {
+  // Hide archived mates (e.g. Ally after Clay took over) and Clay itself
+  // (the user is already chatting with Clay on the left half — listing
+  // Clay again on the right would be redundant).
+  var visibleMates = (store.get('cachedMatesList') || []).filter(function (m) {
+    if (!m || m.archived) return false;
+    if (m.builtinKey === "clay") return false;
+    return true;
+  });
+  if (visibleMates.length === 0) {
     container.classList.add("hidden");
     return;
   }
   container.classList.remove("hidden");
-  for (var i = 0; i < store.get('cachedMatesList').length; i++) {
+  for (var i = 0; i < visibleMates.length; i++) {
     (function (mate) {
       var item = document.createElement("div");
       item.className = "home-hub-mate-item" + (mate.primary ? " home-hub-mate-primary" : "");
@@ -561,12 +569,32 @@ function renderHomeHubMates() {
       });
 
       container.appendChild(item);
-    })(store.get('cachedMatesList')[i]);
+    })(visibleMates[i]);
   }
 }
 
 export function showHomeHub() {
-  if (store.get('dmMode')) exitDmMode();
+  // Open Clay DM (the host agent) on the left while showing widgets on
+  // the right. The body class drives a split layout — see home-hub.css.
+  // Existing users without a Clay mate yet (cachedMatesList not yet
+  // delivered, or syncArchivedBuiltinMates hasn't run) fall back to the
+  // legacy full-screen hub so the home button never feels broken.
+  var clayMate = findClayMate();
+  if (clayMate) {
+    document.body.classList.add("clay-home-split");
+    var dmTarget = store.get('dmTargetUser');
+    var inClayDm = store.get('dmMode') && dmTarget && dmTarget.id === clayMate.id;
+    if (!inClayDm) {
+      // Open Clay DM. Skip the generic mate-onboarding modal — Clay is
+      // the host agent, not a learn-about-Mates moment; that intro
+      // fires the first time the user opens a regular Mate.
+      openDm(clayMate.id, { skipOnboarding: true });
+    }
+  } else {
+    // Fallback: legacy behavior (full overlay, exit any DM).
+    document.body.classList.remove("clay-home-split");
+    if (store.get('dmMode')) exitDmMode();
+  }
   homeHubVisible = true;
   homeHub.classList.remove("hidden");
   // Show close button only if there's a project to return to
@@ -602,7 +630,19 @@ export function hideHomeHub() {
   if (!homeHubVisible) return;
   homeHubVisible = false;
   homeHub.classList.add("hidden");
+  document.body.classList.remove("clay-home-split");
   stopTipRotation();
   var mobileHome = document.getElementById("mobile-home-btn");
   if (mobileHome) mobileHome.classList.remove("active");
 }
+
+// Locate the user's Clay (host agent) mate from the cached list. Returns
+// null if cachedMatesList hasn't arrived yet or the user predates Clay.
+function findClayMate() {
+  var list = store.get('cachedMatesList');
+  if (!list || !list.length) return null;
+  for (var i = 0; i < list.length; i++) {
+    if (list[i] && list[i].builtinKey === "clay") return list[i];
+  }
+  return null;
+}

package/lib/public/modules/sidebar-mates.js

@@ -384,12 +384,17 @@ export function renderUserStrip(allUsers, onlineUserIds, myUserId, dmFavorites,
   // multi-user lets users curate the icon strip via favorites; the full
   // mate list is still reachable from the DM picker.
   var favoriteMates = cachedMates.filter(function (m) {
+    if (m.archived) return false;
     if (cachedDmRemovedUsers[m.id]) return false;
     if (cachedDmFavorites.indexOf(m.id) !== -1) return true;
     if (cachedDmUnread[m.id] && cachedDmUnread[m.id] > 0) return true;
     return false;
   });
   var sortedMates = favoriteMates.sort(function (a, b) {
+    // Clay (host agent) pins to the top, then other built-ins, then user mates.
+    var aClay = a.builtinKey === "clay" ? 1 : 0;
+    var bClay = b.builtinKey === "clay" ? 1 : 0;
+    if (aClay !== bClay) return bClay - aClay;
     var aBuiltin = a.builtinKey ? 1 : 0;
     var bBuiltin = b.builtinKey ? 1 : 0;
     if (aBuiltin !== bBuiltin) return bBuiltin - aBuiltin;

package/lib/sdk-bridge.js

@@ -489,6 +489,13 @@ function createSDKBridge(opts) {
       return { behavior: "allow", updatedInput: input };
     }
 
+    // Auto-approve clay-history tools. Mounted only on Clay (host agent)
+    // sessions and strictly read-only by design — search and read across
+    // the user's own workspace data.
+    if (toolName.indexOf("mcp__clay-history__") === 0) {
+      return { behavior: "allow", updatedInput: input };
+    }
+
     // Auto-approve remote MCP tools that the user explicitly enabled in project settings.
     // These are user-owned local MCP servers, so no additional permission prompt needed.
     if (toolName.indexOf("mcp__") === 0 && getRemoteMcpServers) {

package/lib/server-mates.js

@@ -103,7 +103,9 @@ function attachMates(ctx) {
           var nbSlug = "mate-" + nb.id;
           var nbDir = mates.getMateDir(mateCtx5, nb.id);
           var nbName = (nb.profile && nb.profile.displayName) || nb.name || "New Mate";
-          addProject(nbDir, nbSlug, nbName, null, nb.createdBy || userId, null, { isMate: true, mateDisplayName: nbName });
+          var nbDef = nb.builtinKey ? require("./builtin-mates").getBuiltinByKey(nb.builtinKey) : null;
+          var nbIsHost = !!(nbDef && nbDef.hostAgent);
+          addProject(nbDir, nbSlug, nbName, null, nb.createdBy || userId, null, { isMate: true, mateDisplayName: nbName, isHostAgent: nbIsHost });
           users.addDmFavorite(userId, nb.id);
         }
       } catch (e) {
@@ -111,9 +113,11 @@ function attachMates(ctx) {
       }
       // Auto-sync primary mates (Ally) with latest definition
       try { mates.syncPrimaryMates(mateCtx5); } catch (e) {}
+      // Auto-archive Ally and any other archived built-ins for existing users
+      try { mates.syncArchivedBuiltinMates(mateCtx5); } catch (e) {}
       // Ensure core built-in mates are in favorites (unless user explicitly removed them)
-      // Only auto-favorite the core 3: Ally (chief of staff), Arch (architect), Buzz (marketer)
-      var coreMateKeys = ["ally", "arch", "buzz"];
+      // Auto-favorites: Clay (host agent), Arch (architect), Buzz (marketer)
+      var coreMateKeys = ["clay", "arch", "buzz"];
       var mateList = mates.getAllMates(mateCtx5);
       var currentFavs = users.getDmFavorites(userId);
       var hiddenIds = users.getDmHidden(userId);
@@ -130,7 +134,9 @@ function attachMates(ctx) {
           var mDir = mates.getMateDir(mateCtx5, m.id);
           fs.mkdirSync(mDir, { recursive: true });
           var mName = (m.profile && m.profile.displayName) || m.name || "New Mate";
-          addProject(mDir, mSlug, mName, null, m.createdBy || userId, null, { isMate: true, mateDisplayName: mName });
+          var mDef = m.builtinKey ? require("./builtin-mates").getBuiltinByKey(m.builtinKey) : null;
+          var mIsHost = !!(mDef && mDef.hostAgent);
+          addProject(mDir, mSlug, mName, null, m.createdBy || userId, null, { isMate: true, mateDisplayName: mName, isHostAgent: mIsHost });
         }
       }
       // Include deleted built-in mates for re-add UI

package/lib/server.js

@@ -880,6 +880,7 @@ function createServer(opts) {
       worktreeMeta: worktreeMeta || null,
       isMate: extra.isMate || false,
       mateDisplayName: extra.mateDisplayName || "",
+      isHostAgent: !!extra.isHostAgent,
       pushModule: pushModule,
       debug: debug,
       dangerouslySkipPermissions: dangerouslySkipPermissions,
@@ -920,6 +921,34 @@ function createServer(opts) {
         });
         return allSessions;
       },
+      // Like getAllProjectSessions but returns the per-project grouped
+      // shape that session-search.searchPalette expects. Includes self
+      // (so the host agent can search its own past Clay conversations).
+      // Used by clay-history-mcp-server.
+      getAllProjectsWithSessions: function () {
+        var out = [];
+        projects.forEach(function (pCtx, pSlug) {
+          var status = pCtx.getStatus();
+          if (status.isWorktree) return;
+          var pSm = pCtx.getSessionManager();
+          if (!pSm) return;
+          var sessions = [];
+          pSm.sessions.forEach(function (s) {
+            if (s.hidden) return;
+            sessions.push(s);
+          });
+          if (sessions.length === 0) return;
+          out.push({
+            projectSlug: pSlug,
+            projectTitle: status.title || status.project || pSlug,
+            projectIcon: status.icon || null,
+            isMate: !!status.isMate,
+            mateId: status.mateId || null,
+            sessions: sessions,
+          });
+        });
+        return out;
+      },
       getHubSchedules: function () {
         var allSchedules = [];
         projects.forEach(function (ctx, s) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clay-server",
-  "version": "2.37.0-beta.2",
+  "version": "2.38.0-beta.1",
   "description": "Self-hosted team workspace for Claude Code and Codex. Multi-user, browser-based, with persistent AI mates.",
   "bin": {
     "clay-server": "./bin/cli.js",