agent-relay-server 0.95.1 → 0.97.0

package/src/db/project-entries.ts

@@ -9,7 +9,7 @@ import { PROJECT_ENTRY_KINDS, PROJECT_ENTRY_SOURCES, type BlackboardEntryKind, t
 // a parallel copy (not folded with blackboard) because the two scopes have different
 // lifetimes and column sets; the duplication is intentional and ratchet-noted.
 
-const PROJECT_ENTRY_STATUSES = ["active", "superseded", "retracted"] as const;
+const PROJECT_ENTRY_STATUSES = ["proposed", "active", "superseded", "retracted"] as const;
 
 interface ProjectEntryRow {
   id: string;
@@ -37,6 +37,30 @@ interface WriteProjectEntryInput {
   supersedes?: string;
   source?: ProjectEntrySource;
   originRef?: string;
+  /** Initial status. Default `active` (#403 behavior). The scoped-memory capture path (#559)
+   * passes `proposed` so a write lands in the curation tier and is NOT injected until promoted. */
+  status?: ProjectEntryStatus;
+  /** #559 — when true, auto-supersede the latest active|proposed entry of the same kind whose
+   * (normalized) title matches, in the same project. Implements "a new principle supersedes the
+   * prior one" (curated memory doesn't just stack). Ignored when `supersedes` is given explicitly. */
+  supersedePriorByTitle?: boolean;
+}
+
+function normalizeTitle(title: string): string {
+  return title.trim().toLowerCase().replace(/\s+/g, " ");
+}
+
+/** Latest active|proposed entry of `kind` in `projectId` whose title matches (normalized).
+ * The supersede anchor for the auto-supersede capture path. */
+function latestEntryByTitle(projectId: string, kind: ProjectEntryKind, title: string): ProjectEntry | null {
+  const rows = getDb().query(`
+    SELECT * FROM project_entries
+    WHERE project_id = ? AND kind = ? AND status IN ('active', 'proposed')
+    ORDER BY updated_at DESC, created_at DESC, id DESC
+  `).all(projectId, kind) as ProjectEntryRow[];
+  const target = normalizeTitle(title);
+  const match = rows.find((row) => normalizeTitle(row.title) === target);
+  return match ? rowToEntry(match) : null;
 }
 
 function projectEntryId(): string {
@@ -88,27 +112,36 @@ export function writeProjectEntry(input: WriteProjectEntryInput): ProjectEntry {
   assertKind(input.kind);
   const source = input.source ?? "manual";
   assertSource(source);
+  const status = input.status ?? "active";
+  assertStatus(status);
+  // Resolve the supersede target: an explicit id wins; otherwise the auto-by-title anchor
+  // (#559) so a re-write of the same principle supersedes rather than stacks.
+  let supersedes = input.supersedes;
+  if (!supersedes && input.supersedePriorByTitle) {
+    supersedes = latestEntryByTitle(input.projectId, input.kind, input.title)?.id;
+  }
   const id = projectEntryId();
   const now = Date.now();
   getDb().transaction(() => {
-    if (input.supersedes) {
-      const previous = getProjectEntry(input.supersedes);
-      if (!previous) throw new ValidationError(`project entry ${input.supersedes} not found`);
+    if (supersedes) {
+      const previous = getProjectEntry(supersedes);
+      if (!previous) throw new ValidationError(`project entry ${supersedes} not found`);
       if (previous.projectId !== input.projectId) throw new ValidationError("superseded entry belongs to another project");
       if (previous.status === "retracted") throw new ValidationError("cannot supersede a retracted entry");
       getDb().query("UPDATE project_entries SET status = 'superseded', updated_at = ? WHERE id = ?")
-        .run(now, input.supersedes);
+        .run(now, supersedes);
     }
     getDb().query(`
       INSERT INTO project_entries (id, project_id, kind, title, body, status, supersedes, tags, author_id, source, origin_ref, created_at, updated_at)
-      VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
       id,
       input.projectId,
       input.kind,
       input.title,
       input.body ?? null,
-      input.supersedes ?? null,
+      status,
+      supersedes ?? null,
       input.tags?.length ? JSON.stringify([...new Set(input.tags)]) : null,
       input.authorId,
       source,
@@ -120,6 +153,20 @@ export function writeProjectEntry(input: WriteProjectEntryInput): ProjectEntry {
   return getProjectEntry(id)!;
 }
 
+/** Promote a `proposed` entry to `active` (#559) — the curation gate that makes a captured
+ * memory injectable. Idempotent on an already-active entry; rejects superseded/retracted. */
+export function promoteProjectEntry(id: string): ProjectEntry | null {
+  const existing = getProjectEntry(id);
+  if (!existing) return null;
+  if (existing.status === "active") return existing;
+  if (existing.status !== "proposed") {
+    throw new ValidationError(`cannot promote a ${existing.status} entry`);
+  }
+  getDb().query("UPDATE project_entries SET status = 'active', updated_at = ? WHERE id = ?")
+    .run(Date.now(), id);
+  return getProjectEntry(id);
+}
+
 export function getProjectEntry(id: string): ProjectEntry | null {
   const row = getDb().query("SELECT * FROM project_entries WHERE id = ?").get(id) as ProjectEntryRow | undefined;
   return row ? rowToEntry(row) : null;
@@ -139,16 +186,23 @@ export function getProjectEntryChain(id: string): ProjectEntry[] {
 
 export function listProjectEntries(
   projectId: string,
-  opts: { kind?: ProjectEntryKind; includeInactive?: boolean } = {},
+  opts: { kind?: ProjectEntryKind; includeInactive?: boolean; status?: ProjectEntryStatus } = {},
 ): ProjectEntry[] {
   if (opts.kind) assertKind(opts.kind);
+  if (opts.status) assertStatus(opts.status);
   const conditions = ["project_id = ?"];
   const params: string[] = [projectId];
   if (opts.kind) {
     conditions.push("kind = ?");
     params.push(opts.kind);
   }
-  if (!opts.includeInactive) conditions.push("status = 'active'");
+  // An explicit `status` filter wins; otherwise the default keeps #403 behavior (active only).
+  if (opts.status) {
+    conditions.push("status = ?");
+    params.push(opts.status);
+  } else if (!opts.includeInactive) {
+    conditions.push("status = 'active'");
+  }
   const rows = getDb().query(`
     SELECT * FROM project_entries
     WHERE ${conditions.join(" AND ")}

package/src/db/projects.ts

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { getDb, ValidationError } from "./connection.ts";
 import { listProjectEntries } from "./project-entries.ts";
 import { isPathWithinBase } from "../utils";
-import { PROJECT_EDGE_KINDS, type Project, type ProjectEdge, type ProjectEdgeKind, type ProjectEntryKind, type ProjectRoot, type ResolvedProjectEntry } from "../types";
+import { PROJECT_EDGE_KINDS, PROJECT_SCOPES, type Project, type ProjectEdge, type ProjectEdgeKind, type ProjectEntryKind, type ProjectRoot, type ProjectScope, type ResolvedProjectEntry } from "../types";
 
 // Projects entity CRUD + roots + cwd→project resolution (#405). Templated on
 // src/db/teams.ts; the durable analog of a team. project_entries CRUD lives in
@@ -15,6 +15,8 @@ interface ProjectRow {
   description: string | null;
   tenant_id: string | null;
   issue_repo: string | null;
+  scope: ProjectScope;
+  anchor_key: string | null;
   status: Project["status"];
   created_at: number;
   updated_at: number;
@@ -38,6 +40,8 @@ function rowToProject(row: ProjectRow): Project {
     ...(row.description ? { description: row.description } : {}),
     ...(row.tenant_id ? { tenantId: row.tenant_id } : {}),
     ...(row.issue_repo ? { issueRepo: row.issue_repo } : {}),
+    scope: row.scope ?? "project",
+    ...(row.anchor_key ? { anchorKey: row.anchor_key } : {}),
     status: row.status,
     createdAt: row.created_at,
     updatedAt: row.updated_at,
@@ -63,11 +67,22 @@ export function resolveProject(ref: string): Project | null {
   return getProject(ref) ?? getProjectBySlug(ref);
 }
 
-export function listProjects(opts: { includeArchived?: boolean } = {}): Project[] {
-  const where = opts.includeArchived ? "" : "WHERE status = 'active' ";
+/** List projects. Defaults to the `project` scope only so #403 callers (the project list)
+ * never see profile/user anchors; pass an explicit `scope` to list a scoped store, or
+ * `scope: "any"` for every scope. */
+export function listProjects(opts: { includeArchived?: boolean; scope?: ProjectScope | "any" } = {}): Project[] {
+  const conditions: string[] = [];
+  const params: string[] = [];
+  if (!opts.includeArchived) conditions.push("status = 'active'");
+  const scope = opts.scope ?? "project";
+  if (scope !== "any") {
+    conditions.push("scope = ?");
+    params.push(scope);
+  }
+  const where = conditions.length ? `WHERE ${conditions.join(" AND ")} ` : "";
   const rows = getDb()
     .query(`SELECT * FROM projects ${where}ORDER BY created_at ASC, id ASC`)
-    .all() as ProjectRow[];
+    .all(...params) as ProjectRow[];
   return rows.map(rowToProject);
 }
 
@@ -131,6 +146,63 @@ export function ensureProject(input: EnsureProjectInput): Project {
   return getProject(id)!;
 }
 
+// ── Scoped anchors (#559) ───────────────────────────────────────────────────
+// A profile/user knowledge store is a `projects` row with scope!='project' and an
+// anchor_key (the profile name / operator id). The slug carries the scope prefix so it
+// stays globally unique alongside project slugs (`profile:coordinator`, `user:edin`).
+// These are the get-or-create entry points the spawn path and the scoped-memory tools
+// use; entries/edges/cascade then operate on the returned project id, scope-agnostic.
+
+const SCOPED_SLUG_PREFIX: Record<Exclude<ProjectScope, "project">, string> = {
+  profile: "profile:",
+  user: "user:",
+};
+
+/** Find a scoped anchor by (scope, anchor_key) — the profile name or operator id. Null
+ * when none exists yet (the caller decides whether to create it). */
+export function resolveScopedAnchor(scope: Exclude<ProjectScope, "project">, anchorKey: string): Project | null {
+  const key = anchorKey.trim();
+  if (!key) return null;
+  const row = getDb()
+    .query("SELECT * FROM projects WHERE scope = ? AND anchor_key = ? LIMIT 1")
+    .get(scope, key) as ProjectRow | undefined;
+  return row ? rowToProject(row) : null;
+}
+
+/** Get-or-create a scoped anchor (profile/user store). Idempotent on (scope, anchor_key);
+ * the create-on-first-write analog of ensureProject for the non-repo scopes. */
+export function ensureScopedAnchor(
+  scope: Exclude<ProjectScope, "project">,
+  anchorKey: string,
+  opts: { title?: string } = {},
+): Project {
+  if (!PROJECT_SCOPES.includes(scope)) throw new ValidationError(`scope must be one of: ${PROJECT_SCOPES.join(", ")}`);
+  const key = anchorKey.trim();
+  if (!key) throw new ValidationError("anchorKey required");
+  const existing = resolveScopedAnchor(scope, key);
+  if (existing) return existing;
+  const id = projectId();
+  const now = Date.now();
+  const slug = `${SCOPED_SLUG_PREFIX[scope]}${key}`;
+  getDb().query(`
+    INSERT INTO projects (id, slug, title, description, tenant_id, issue_repo, scope, anchor_key, status, created_at, updated_at)
+    VALUES (?, ?, ?, NULL, NULL, NULL, ?, ?, 'active', ?, ?)
+    ON CONFLICT(slug) DO NOTHING
+  `).run(id, slug, opts.title ?? null, scope, key, now, now);
+  // Re-resolve to absorb a concurrent insert that won the slug race.
+  return resolveScopedAnchor(scope, key) ?? getProjectBySlug(slug)!;
+}
+
+/** The profile-scoped knowledge store for a profile NAME (role memory). */
+export function ensureProfileAnchor(profileName: string): Project {
+  return ensureScopedAnchor("profile", profileName, { title: `Profile: ${profileName.trim()}` });
+}
+
+/** The user/operator-scoped knowledge store for an operator identity (cross-project memory). */
+export function ensureUserAnchor(operatorId: string): Project {
+  return ensureScopedAnchor("user", operatorId, { title: `Operator: ${operatorId.trim()}` });
+}
+
 /** Set (or clear, with null) a project's `issueRepo` (#533). With `onlyIfNull`, a value is
  * written only when none is set yet — the mechanism for the git-remote AUTO-DERIVE to fill
  * a fresh project without ever clobbering an explicit override or a prior derivation. */

package/src/db/schema.ts

@@ -239,6 +239,9 @@ export function initDb(path: string = "agent-relay.db"): Database {
     -- Projects (#403/#405) — the durable knowledge scope. projects/project_roots/project_entries
     -- re-scope the teams/blackboard_entries pair above (team_id → project_id); project_entries
     -- adds source/origin_ref so a promoted or ingested entry tracks where it came from.
+    -- #559 — scope generalizes the anchor from repo-root to {project|profile|user}.
+    -- A profile/user store is a projects row with scope!='project' and anchor_key = the
+    -- profile name / operator id. Existing rows default scope='project' (zero regression).
     CREATE TABLE IF NOT EXISTS projects (
       id TEXT PRIMARY KEY,
       slug TEXT NOT NULL UNIQUE,
@@ -246,10 +249,15 @@ export function initDb(path: string = "agent-relay.db"): Database {
       description TEXT,
       tenant_id TEXT,
       issue_repo TEXT,
+      scope TEXT NOT NULL DEFAULT 'project',
+      anchor_key TEXT,
       status TEXT NOT NULL DEFAULT 'active',
       created_at INTEGER NOT NULL,
       updated_at INTEGER NOT NULL
     );
+    -- idx_projects_scope_anchor is created in applyMigrations() AFTER the scope/anchor_key ALTER —
+    -- never inline here (#483/#559: an inline index over a not-yet-migrated column crashes initDb
+    -- on an existing DB whose projects table predates the scope columns).
     CREATE TABLE IF NOT EXISTS project_roots (
       project_id TEXT NOT NULL,
       root_path TEXT NOT NULL,

package/src/mcp/index.ts

@@ -7,7 +7,7 @@ import { createActivityEvent, ValidationError } from "../db";
 import { PLAN_TOOLS, relayPlanTool } from "../mcp-plan-tools";
 import { TEAM_TOOLS, relayTeamTool } from "../mcp-team-tools";
 import { BLACKBOARD_TOOLS, relayBlackboardTool } from "../mcp-blackboard-tools";
-import { PROJECT_TOOLS, relayProjectTool } from "../mcp-project-tools"; import { ISSUE_REF_TOOLS, relayIssueRefTool } from "../mcp-issue-ref-tools"; import { ISSUE_ASSOCIATION_TOOLS, relayIssueAssociationTool } from "../mcp-issue-association-tools"; import { ISSUE_ACTIVITY_TOOLS, relayIssueActivityTool } from "../mcp-issue-activity-tools"; import { ISSUE_LIFECYCLE_TOOLS, relayIssueLifecycleTool } from "../mcp-issue-lifecycle-tools";
+import { PROJECT_TOOLS, relayProjectTool } from "../mcp-project-tools"; import { MEMORY_TOOLS, relayMemoryTool } from "../mcp-memory-tools"; import { ISSUE_REF_TOOLS, relayIssueRefTool } from "../mcp-issue-ref-tools"; import { ISSUE_ASSOCIATION_TOOLS, relayIssueAssociationTool } from "../mcp-issue-association-tools"; import { ISSUE_ACTIVITY_TOOLS, relayIssueActivityTool } from "../mcp-issue-activity-tools"; import { ISSUE_LIFECYCLE_TOOLS, relayIssueLifecycleTool } from "../mcp-issue-lifecycle-tools";
 import { NOTIFICATION_SUBSCRIPTION_TOOLS, relayNotificationSubscriptionTool } from "../mcp-notification-subscription-tools"; import { MERGE_TOOLS, relayMergeTool } from "../mcp-merge-tools";
 import { NTFY_TOOLS, relayNotifyNtfy } from "../mcp-ntfy-tools";
 import { AGENT_ACTION_TOOL, relayAgentAction } from "../mcp-agent-action"; import { providerCatalogToolInputSchema } from "../mcp-provider-catalog";
@@ -35,6 +35,7 @@ const TOOLS: ToolDefinition[] = [
   ...PLAN_TOOLS, ...ISSUE_REF_TOOLS, ...ISSUE_ASSOCIATION_TOOLS, ...ISSUE_ACTIVITY_TOOLS, ...ISSUE_LIFECYCLE_TOOLS,
   ...BLACKBOARD_TOOLS,
   ...PROJECT_TOOLS,
+  ...MEMORY_TOOLS,
   ...NOTIFICATION_SUBSCRIPTION_TOOLS,
   ...NTFY_TOOLS,
 ];
@@ -44,7 +45,7 @@ const TOOLS: ToolDefinition[] = [
 // top of scope-gating — scope enforcement at tools/call stays authoritative.
 export const RELAY_TOOL_GROUPS: Record<string, readonly string[]> = {
   core: ["relay_whoami", "relay_send_message", "relay_reply", "relay_get_message", "relay_get_thread", "relay_find_agents"],
-  memory: ["relay_recall", "relay_compact_and_resume"],
+  memory: ["relay_recall", "relay_compact_and_resume", "relay_memory_write", "relay_memory_promote", "relay_memory_retract", "relay_memory_read", "relay_memory_search"],
   artifacts: ["relay_upload_artifact", "relay_attach_artifact"],
   workspace: ["relay_workspace_status", "relay_workspace_ready", "relay_workspace_deps", "relay_workspace_list", "relay_workspace_claim", "relay_workspace_release", "relay_workspace_land", "relay_merge_pause", "relay_merge_pauses", "relay_merge_renew", "relay_merge_resume"],
   "spawn-lifecycle": ["relay_spawn_agent", "relay_spawn_targets", "relay_my_agents", "relay_shutdown_agent", "relay_agent_action", "relay_agent_status", "relay_agent_crash_report", "relay_schedule_timer", "relay_list_timers", "relay_cancel_timer"],
@@ -166,7 +167,7 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name.startsWith("relay_merge_")) result = relayMergeTool(auth, name, args); else if (name.startsWith("relay_team_")) result = await relayTeamTool(auth, name, args);
     else if (name.startsWith("relay_plan_")) result = relayPlanTool(auth, name, args);
     else if (name.startsWith("relay_blackboard_")) result = relayBlackboardTool(auth, name, args);
-    else if (name.startsWith("relay_project_")) result = relayProjectTool(auth, name, args); else if (name.startsWith("relay_issue_ref_")) result = relayIssueRefTool(auth, name, args); else if (name.startsWith("relay_issue_association_")) result = relayIssueAssociationTool(auth, name, args); else if (name.startsWith("relay_issue_activity_")) result = relayIssueActivityTool(auth, name, args); else if (name.startsWith("relay_issue_lifecycle_")) result = await relayIssueLifecycleTool(auth, name, args);
+    else if (name.startsWith("relay_project_")) result = relayProjectTool(auth, name, args); else if (name.startsWith("relay_memory_")) result = relayMemoryTool(auth, name, args); else if (name.startsWith("relay_issue_ref_")) result = relayIssueRefTool(auth, name, args); else if (name.startsWith("relay_issue_association_")) result = relayIssueAssociationTool(auth, name, args); else if (name.startsWith("relay_issue_activity_")) result = relayIssueActivityTool(auth, name, args); else if (name.startsWith("relay_issue_lifecycle_")) result = await relayIssueLifecycleTool(auth, name, args);
     else if (name === "relay_subscribe" || name === "relay_unsubscribe" || name === "relay_list_subscriptions" || name === "relay_why_notified" || name === "relay_notification_preview") result = relayNotificationSubscriptionTool(auth, name, args);
     else if (name === "relay_notify_ntfy") result = await relayNotifyNtfy(args);
     else throw new ValidationError(`unknown tool: ${name}`);

package/src/mcp/tools-spawn.ts

@@ -1,4 +1,4 @@
-import { spawnAgent, type SpawnAgentInput } from "../services/spawn-agent";
+import { spawnAgent, summarizeSpawnCommandForCaller, type SpawnAgentInput } from "../services/spawn-agent";
 import { authContextFromMcp } from "../services/auth-context";
 import { ShutdownAuthError, ShutdownTargetError, shutdownAgent } from "../services/shutdown-agent";
 import { buildSpawnTargets } from "../spawn-targets";
@@ -162,7 +162,18 @@ export async function relaySpawnAgent(auth: McpAuthContext, args: Record<string,
     resumeWorkspace: parseResumeWorkspace(args.resumeWorkspace),
   };
   const result = await spawnAgent(input, authContextFromMcp(auth));
-  return { ...result };
+  // #734 — return the lean shape callers need (spawnRequestId + agentId for idempotency/shutdown)
+  // plus a sanitized command summary. The full resolved provisioning already went to the
+  // orchestrator on the dispatched command; echoing it here blows the MCP result token cap.
+  return {
+    ok: result.ok,
+    spawnRequestId: result.spawnRequestId,
+    orchestratorId: result.orchestratorId,
+    provider: result.provider,
+    agentId: result.agentId,
+    registered: result.registered,
+    command: summarizeSpawnCommandForCaller(result.command),
+  };
 }
 
 export function relaySpawnTargets(auth: McpAuthContext): Record<string, unknown> {

package/src/mcp-memory-tools.ts

@@ -0,0 +1,239 @@
+import {
+  ensureProfileAnchor,
+  ensureUserAnchor,
+  getProjectEntry,
+  listProjectEntries,
+  promoteProjectEntry,
+  resolveAgentOwnership,
+  resolveProjectEntries,
+  resolveScopedAnchor,
+  retractProjectEntry,
+  searchProjectEntries,
+  ValidationError,
+  writeProjectEntry,
+} from "./db";
+import { DEFAULT_USER_ID } from "agent-relay-sdk";
+import { McpNotFoundError } from "./mcp-errors";
+import { authContextFromMcp, type AuthContext } from "./services/auth-context";
+import { cleanString, cleanStringArray, optionalEnum } from "./validation";
+import { PROJECT_ENTRY_KINDS, type Project, type ProjectEntryKind } from "./types";
+
+// Scoped-memory capture tools (#559) — the relay-owned, vanilla-safe replacement for host
+// claude-mneme's /remember. They write/read knowledge in the {profile|user} scopes that
+// src/db/projects.ts now anchors. The store underneath IS project_entries (same CRUD, same
+// supersede chain, same spawn-time injection), so these tools are a thin self-scoped front:
+//
+//  • SELF-SCOPED WRITES — a write/promote/retract targets the caller's OWN profile store
+//    (resolved from the token's `constraints.profile`, never a name the caller passes) or the
+//    caller's OWN operator store (resolved from agent ownership). One role can't poison another.
+//  • CURATED — a capture lands `status:'proposed'` (NOT injected); `relay_memory_promote` flips
+//    it to `active` so it renders into the next spawn's preamble. `promote:true` on write is the
+//    confident shortcut. A re-write of the same title supersedes the prior (no stacking).
+//  • READS are not a poison risk, so `relay_memory_read`/`search` accept an optional `profile`
+//    name to inspect another role's store; writes never do.
+
+const MEMORY_SCOPES = ["profile", "user"] as const;
+type MemoryScope = (typeof MEMORY_SCOPES)[number];
+
+const MEMORY_ENTRY_STATUSES = ["proposed", "active", "superseded", "retracted"] as const;
+
+export const MEMORY_TOOLS = [
+  {
+    name: "relay_memory_write",
+    description:
+      "Capture a scoped memory (the relay-owned /remember). Writes to the caller's OWN store: `scope:'profile'` = its role memory (resolved from the token's profile), `scope:'user'` = operator memory. Lands as `proposed` (NOT injected) until promoted — pass `promote:true` to activate immediately. A write whose title matches an existing entry of the same kind supersedes it (curated, not stacked). Default kind `memory`.",
+    requiredScopes: ["project:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: { type: "string", enum: MEMORY_SCOPES, description: "Which of the caller's own stores: profile (role) or user (operator). Default profile." },
+        kind: { type: "string", enum: PROJECT_ENTRY_KINDS, description: "Entry kind; default `memory`. rule/fact/memory are injected at spawn." },
+        title: { type: "string" },
+        body: { type: "string" },
+        tags: { type: "array", items: { type: "string" } },
+        promote: { type: "boolean", description: "Write straight to `active` (injectable) instead of the default `proposed` tier." },
+      },
+      required: ["title"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_memory_promote",
+    description: "Promote a `proposed` memory in the caller's own store to `active` so it is injected at the next spawn. Self-scoped: the entry must belong to the caller's profile or user store.",
+    requiredScopes: ["project:write"],
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string", description: "The pe_… entry id to promote." } },
+      required: ["id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_memory_retract",
+    description: "Retract a memory in the caller's own store without deleting its ledger row. Self-scoped.",
+    requiredScopes: ["project:write"],
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string" } },
+      required: ["id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_memory_read",
+    description: "Read scoped memory entries. Defaults to the caller's own `profile` store; pass `scope:'user'` for operator memory, or an explicit `profile` name to inspect another role's store (read-only). Includes entries inherited via the `contains` graph (each tagged `inherited:true`) unless `includeInherited:false`. `status` filters the tier (e.g. `proposed` to review pending captures); default active only.",
+    requiredScopes: ["project:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: { type: "string", enum: MEMORY_SCOPES },
+        profile: { type: "string", description: "Inspect a specific profile's store by name (read-only). Overrides `scope`." },
+        kind: { type: "string", enum: PROJECT_ENTRY_KINDS },
+        status: { type: "string", enum: MEMORY_ENTRY_STATUSES, description: "Filter by tier; default active only." },
+        includeInherited: { type: "boolean" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_memory_search",
+    description: "Search scoped memory by title, body, or tags. Defaults to the caller's own `profile` store; `scope:'user'` or an explicit `profile` name select another store (read-only).",
+    requiredScopes: ["project:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: { type: "string", enum: MEMORY_SCOPES },
+        profile: { type: "string" },
+        query: { type: "string" },
+        kind: { type: "string", enum: PROJECT_ENTRY_KINDS },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+  },
+] satisfies Array<{ name: string; description: string; requiredScopes: string[]; inputSchema: Record<string, unknown> }>;
+
+type McpAuthLike = Parameters<typeof authContextFromMcp>[0];
+
+function cleanScope(value: unknown): MemoryScope {
+  return (optionalEnum(value, "scope", MEMORY_SCOPES) as MemoryScope | undefined) ?? "profile";
+}
+
+function cleanKind(value: unknown): ProjectEntryKind | undefined {
+  return optionalEnum(value, "kind", PROJECT_ENTRY_KINDS) as ProjectEntryKind | undefined;
+}
+
+/** The caller's profile NAME, from the signed token constraints. Self-scoped writes resolve the
+ * store from THIS — never a name the caller passes — so an agent can only write its own role's
+ * memory. Throws when the token carries no profile (e.g. a human/admin token). */
+function callerProfileName(ctx: AuthContext): string {
+  const profile = ctx.constraints?.profile;
+  if (!profile) throw new ValidationError("no profile on this token: scoped profile memory is writable only by a spawned agent with a resolved profile");
+  return profile;
+}
+
+/** The caller's operator identity for the `user` scope — the owner of the calling agent, falling
+ * back to the default (single-tenant) operator. */
+function callerOperatorId(ctx: AuthContext): string {
+  if (ctx.callerAgentId) return resolveAgentOwnership(ctx.callerAgentId).ownerUserId;
+  if (ctx.actor.kind === "user" && ctx.actor.id && ctx.actor.id !== "anonymous") return ctx.actor.id;
+  return DEFAULT_USER_ID;
+}
+
+/** Resolve the caller's OWN store for a write/promote/retract — get-or-create. */
+function ownAnchor(ctx: AuthContext, scope: MemoryScope): Project {
+  return scope === "profile" ? ensureProfileAnchor(callerProfileName(ctx)) : ensureUserAnchor(callerOperatorId(ctx));
+}
+
+/** Resolve the store for a READ — own store by default, or an explicitly-named profile (read-only
+ * transparency). Returns null when a named profile has no store yet. */
+function readAnchor(ctx: AuthContext, scope: MemoryScope, explicitProfile: string | undefined): Project | null {
+  if (explicitProfile) return resolveScopedAnchor("profile", explicitProfile);
+  if (scope === "profile") return resolveScopedAnchor("profile", callerProfileName(ctx));
+  return resolveScopedAnchor("user", callerOperatorId(ctx));
+}
+
+function authorId(ctx: AuthContext): string {
+  return ctx.callerAgentId ?? ctx.actor.id;
+}
+
+/** Confirm an entry belongs to the caller's own store before mutating it (self-scoped guard). */
+function ownEntryProjectId(ctx: AuthContext, entryId: string): string {
+  const entry = getProjectEntry(entryId);
+  if (!entry) throw new McpNotFoundError("memory entry not found");
+  const profileStore = resolveScopedAnchor("profile", callerProfileNameOrNull(ctx) ?? "");
+  const userStore = resolveScopedAnchor("user", callerOperatorId(ctx));
+  if (entry.projectId === profileStore?.id || entry.projectId === userStore?.id) return entry.projectId;
+  throw new McpNotFoundError("memory entry not found");
+}
+
+function callerProfileNameOrNull(ctx: AuthContext): string | null {
+  return ctx.constraints?.profile ?? null;
+}
+
+export function relayMemoryTool(auth: McpAuthLike, name: string, args: Record<string, unknown>): Record<string, unknown> {
+  const ctx = authContextFromMcp(auth);
+
+  if (name === "relay_memory_write") {
+    const scope = cleanScope(args.scope);
+    const anchor = ownAnchor(ctx, scope);
+    const kind = cleanKind(args.kind) ?? "memory";
+    return writeProjectEntry({
+      projectId: anchor.id,
+      authorId: authorId(ctx),
+      kind,
+      title: cleanString(args.title, "title", { required: true, max: 240 })!,
+      body: cleanString(args.body, "body", { max: 16_000 }),
+      tags: cleanStringArray(args.tags, "tags", { itemMax: 80, maxItems: 32 }),
+      status: args.promote === true ? "active" : "proposed",
+      supersedePriorByTitle: true,
+    }) as unknown as Record<string, unknown>;
+  }
+
+  if (name === "relay_memory_promote") {
+    const id = cleanString(args.id, "id", { required: true, max: 120 })!;
+    ownEntryProjectId(ctx, id);
+    const entry = promoteProjectEntry(id);
+    if (!entry) throw new McpNotFoundError("memory entry not found");
+    return entry as unknown as Record<string, unknown>;
+  }
+
+  if (name === "relay_memory_retract") {
+    const id = cleanString(args.id, "id", { required: true, max: 120 })!;
+    ownEntryProjectId(ctx, id);
+    const entry = retractProjectEntry(id);
+    if (!entry) throw new McpNotFoundError("memory entry not found");
+    return entry as unknown as Record<string, unknown>;
+  }
+
+  if (name === "relay_memory_read") {
+    const scope = cleanScope(args.scope);
+    const explicitProfile = cleanString(args.profile, "profile", { max: 200 });
+    const anchor = readAnchor(ctx, scope, explicitProfile);
+    if (!anchor) return { entries: [] };
+    const status = optionalEnum(args.status, "status", MEMORY_ENTRY_STATUSES) as (typeof MEMORY_ENTRY_STATUSES)[number] | undefined;
+    const kind = cleanKind(args.kind);
+    // A status filter (e.g. reviewing the `proposed` tier) reads the OWN store only — proposed
+    // captures never cascade. The default active read uses the contains-graph cascade so a profile
+    // inherits its umbrella's promoted principles (each tagged `inherited:true`).
+    if (status) {
+      return { entries: listProjectEntries(anchor.id, { ...(kind ? { kind } : {}), status }) };
+    }
+    return {
+      entries: resolveProjectEntries(anchor.id, {
+        ...(kind ? { kind } : {}),
+        includeInherited: args.includeInherited !== false,
+      }),
+    };
+  }
+
+  if (name === "relay_memory_search") {
+    const scope = cleanScope(args.scope);
+    const explicitProfile = cleanString(args.profile, "profile", { max: 200 });
+    const anchor = readAnchor(ctx, scope, explicitProfile);
+    if (!anchor) return { entries: [] };
+    return { entries: searchProjectEntries(anchor.id, cleanString(args.query, "query", { required: true, max: 240 })!, { kind: cleanKind(args.kind) }) };
+  }
+
+  throw new ValidationError(`unknown tool: ${name}`);
+}

package/src/mcp-team-template-tools.ts

@@ -2,6 +2,7 @@ import { APPROVAL_MODES, VALID_AGENT_LIFECYCLES, VALID_WORKSPACE_MODES } from "a
 import { McpAuthError } from "./mcp-errors";
 import { authContextFromMcp } from "./services/auth-context";
 import { deleteTeamTemplate, getTeamTemplate, instantiateTeamTemplate, listTeamTemplates, saveTeamTemplate } from "./services/team-templates";
+import { summarizeSpawnCommandForCaller } from "./services/spawn-agent";
 import { ValidationError } from "./db";
 
 const COMPOSITION_ENTRY_SCHEMA = {
@@ -123,7 +124,13 @@ export async function relayTeamTemplateTool(auth: McpAuthLike, name: string, arg
   }
   if (name === "relay_team_spawn_from_template") {
     requireScope(auth, "teams:write");
-    return await instantiateTeamTemplate({ ...args, slug: slugArg(args) }, authContextFromMcp(auth)) as unknown as Record<string, unknown>;
+    const instantiated = await instantiateTeamTemplate({ ...args, slug: slugArg(args) }, authContextFromMcp(auth));
+    // #734 — each spawned result echoes its full resolved agentProfile; strip the heavy inlined
+    // provisioning file contents (multiplied by N spawned agents here) before returning to the caller.
+    return {
+      ...instantiated,
+      spawned: instantiated.spawned.map((s) => ({ ...s, command: summarizeSpawnCommandForCaller(s.command) })),
+    } as unknown as Record<string, unknown>;
   }
   throw new ValidationError(`unknown tool: ${name}`);
 }