agent-relay-server 0.95.1 → 0.96.0

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-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/project-instructions.ts

@@ -44,6 +44,10 @@ interface ComposeProjectInstructionsOptions {
   /** Hard byte cap on the rendered block (UTF-8). Default 8192. The block is truncated
    * deterministically (lowest-priority entries dropped first) to stay within it. */
   maxBytes?: number;
+  /** Header label prefix (#559). Default "Project knowledge"; the scoped stores pass
+   * "Profile memory" / "Operator memory" so an agent can tell role/operator memory from
+   * repo knowledge. The anchor title/slug is still appended. */
+  headerLabel?: string;
 }
 
 interface SpawnInstructionInjectionEvent {
@@ -140,7 +144,7 @@ export function composeProjectInstructions(
 
   // Greedy size-bounded render. Entries are contiguous by kind (primary sort key), so a
   // per-kind `## heading` is emitted once when the first entry of that kind is included.
-  const header = `# Project knowledge: ${project.title?.trim() || project.slug}`;
+  const header = `# ${opts.headerLabel ?? "Project knowledge"}: ${project.title?.trim() || project.slug}`;
   const budget = maxBytes - byteLen(`\n\n${TRUNCATION_NOTICE}`);
   const lines: string[] = [header];
   let bytes = byteLen(header);
@@ -181,18 +185,37 @@ export function composeProjectInstructions(
  * Returns the joined block, or the caller's own systemPromptAppend untouched when no
  * profile/project material applies — so a profile-less spawn stays byte-identical.
  *
- * ── #559 SEAM ──────────────────────────────────────────────────────────────────────────
- * Scoped {profile|user} memory does not exist yet (#559 generalizes Projects' anchor to
- * project|profile|user). When it lands, a profile/user-scoped preamble composes in RIGHT
- * HERE, beside the project preamble — same `composeProjectInstructions`-shaped renderer over
- * the {profile|user} scope union, slotted into `appendBlocks` before the profile system
- * prompt. The runner reports the contributing scopes via AssembledInstructions.scopedKnowledge.
- * Until #559 lands, the only knowledge scope is the project preamble below — a thin add, not
- * a refactor.
+ * ── #559 scoped memory ─────────────────────────────────────────────────────────────────
+ * Scoped {profile|user} memory (#559) composes in beside the project preamble: `profileAnchor`
+ * (role memory) and `userAnchor` (operator memory) each render via the same
+ * `composeProjectInstructions` renderer (scope-agnostic — a profile/user store is just a
+ * `projects` row of a different scope) and slot into `appendBlocks` before the profile system
+ * prompt. Unlike the project preamble they are UNGATED — relay-native, curated, small — so they
+ * inject whenever the resolved anchor holds active (promoted) entries.
  */
+/** Kinds rendered into a scoped {profile|user} memory preamble (#559). Adds `memory` to the
+ * project default (rule/fact) because `memory` is the /remember capture kind — a promoted role
+ * principle or operator preference must reach the spawn. `decision` stays log-only. */
+const SCOPED_MEMORY_KINDS: readonly ProjectEntryKind[] = ["rule", "fact", "memory"];
+
+/** Render a {profile|user}-scoped store's promoted (active) entries into a preamble block, or "".
+ * Unlike the project preamble this is UNGATED by a policy: scoped memory is relay-native, curated
+ * (proposed→promoted), and small, so it always injects when present (#559). */
+function composeScopedKnowledge(
+  anchor: Pick<Project, "id" | "slug" | "title">,
+  headerLabel: string,
+): string {
+  return composeProjectInstructions(anchor, { includeKinds: SCOPED_MEMORY_KINDS, headerLabel });
+}
+
 export function composeSpawnInstructionsWithEvents(input: {
   callerProject?: Pick<Project, "id" | "slug" | "title">;
   projectInstructions?: ProjectInstructionPolicy;
+  /** #559 — the caller's resolved profile-scoped store (role memory), injected when it has
+   * active entries. Inheritance via the contains graph is handled inside the composer. */
+  profileAnchor?: Pick<Project, "id" | "slug" | "title">;
+  /** #559 — the caller's resolved user/operator-scoped store (operator memory). */
+  userAnchor?: Pick<Project, "id" | "slug" | "title">;
   profile?: Pick<AgentProfile, "instructions" | "maxSpawnedAgents">;
   spawnedBy?: string;
   callerSystemPromptAppend?: string;
@@ -217,7 +240,22 @@ export function composeSpawnInstructionsWithEvents(input: {
       });
     }
   }
-  // [#559 seam] profile/user-scoped knowledge preamble composes in here.
+  // [#559] profile/user-scoped knowledge preamble — beside the project preamble, before the
+  // profile system prompt. Ungated: injects whenever the resolved anchor holds active entries.
+  for (const scope of [
+    { anchor: input.profileAnchor, label: "Profile memory", source: "profile-memory" as const, category: "knowledge" as const },
+    { anchor: input.userAnchor, label: "Operator memory", source: "user-memory" as const, category: "knowledge" as const },
+  ]) {
+    if (!scope.anchor) continue;
+    const block = composeScopedKnowledge(scope.anchor, scope.label);
+    if (!block.trim()) continue;
+    appendBlocks.push(block);
+    relayInjectionEvents.push({
+      category: scope.category,
+      summary: `injected ${scope.label.toLowerCase()}: ${scope.anchor.title?.trim() || scope.anchor.slug}`,
+      detail: { source: scope.source, anchor: scope.anchor, content: block },
+    });
+  }
   if (input.spawnedBy) {
     appendBlocks.push(SPAWNED_CHILD_REPORTUP_INSTRUCTION);
     relayInjectionEvents.push({

package/src/routes/agent-profiles.ts

@@ -1,11 +1,12 @@
 // Auto-split from routes.ts (#299). Domain: agent-profiles.
-import { ValidationError } from "../db";
-import { cleanString } from "../validation";
+import { ValidationError, withResolvedProvisioning } from "../db";
+import { cleanString, optionalEnum } from "../validation";
 import { deleteAgentProfile, getAgentProfile, listAgentProfiles, setAgentProfile } from "../config-store";
 import { emitConfigChanged } from "../sse";
-import { error, json, normalizeConfigPathParam, parseBody, type Handler } from "./_shared";
+import { error, isRootCredentialRequest, json, normalizeConfigPathParam, parseBody, type Handler } from "./_shared";
+import { getComponentAuth, hasComponentScope } from "../security";
 import { isRecord } from "agent-relay-sdk";
-import { type AgentProfile } from "../types";
+import { SPAWN_PROVIDERS, type AgentProfile, type SpawnProvider } from "../types";
 
 export const getAgentProfilesRoute: Handler = () => json(listAgentProfiles());
 
@@ -15,6 +16,29 @@ export const getAgentProfileRoute: Handler = (_req, params) => {
   return profile ? json(profile) : error("agent profile not found", 404);
 };
 
+function isAdminProfileRequest(req: Request): boolean {
+  if (isRootCredentialRequest(req)) return true;
+  const component = getComponentAuth(req);
+  return component ? hasComponentScope(component, "system:admin") : false;
+}
+
+export const getResolvedAgentProfileRoute: Handler = (req, params) => {
+  try {
+    if (!isAdminProfileRequest(req)) return error("system admin scope required", 403);
+    const name = normalizeConfigPathParam(params.name, "name");
+    const entry = getAgentProfile(name);
+    if (!entry) return error("agent profile not found", 404);
+    const requestedProvider = new URL(req.url).searchParams.get("provider") ?? undefined;
+    const profileProvider = entry.value.provider === "claude" || entry.value.provider === "codex" ? entry.value.provider : undefined;
+    const provider = optionalEnum(requestedProvider, "provider", SPAWN_PROVIDERS, profileProvider ?? "codex") as SpawnProvider;
+    const profile = withResolvedProvisioning(entry.value, provider);
+    return profile ? json({ provider, profile }) : error("agent profile not found", 404);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
 export const putAgentProfileRoute: Handler = async (req, params) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
@@ -22,9 +46,12 @@ export const putAgentProfileRoute: Handler = async (req, params) => {
     if (!isRecord(parsed.body)) throw new ValidationError("agent profile body required");
     const name = normalizeConfigPathParam(params.name, "name");
     const updatedBy = cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 });
-    const profile = setAgentProfile({ ...parsed.body, name } as AgentProfile, updatedBy);
+    const existing = getAgentProfile(name);
+    const profile = existing?.value.builtIn && isAdminProfileRequest(req)
+      ? setAgentProfile({ ...parsed.body, name } as AgentProfile, updatedBy, { overrideBuiltIn: true })
+      : setAgentProfile({ ...parsed.body, name } as AgentProfile, updatedBy);
     emitConfigChanged(profile.namespace, profile.key, profile.version);
-    return json(profile, profile.version === 1 ? 201 : 200);
+    return json(profile, existing ? 200 : profile.version === 1 ? 201 : 200);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;
@@ -35,9 +62,10 @@ export const deleteAgentProfileRoute: Handler = (req, params) => {
   try {
     const name = normalizeConfigPathParam(params.name, "name");
     const existing = getAgentProfile(name);
-    if (!existing || existing.value.builtIn) return error(existing ? "built-in agent profiles are managed by Relay" : "agent profile not found", existing ? 400 : 404);
+    if (!existing) return error("agent profile not found", 404);
     const updatedBy = cleanString(new URL(req.url).searchParams.get("updatedBy") ?? undefined, "updatedBy", { max: 200 });
-    deleteAgentProfile(name, updatedBy);
+    if (existing.value.builtIn && !isAdminProfileRequest(req)) return error("built-in agent profiles are managed by Relay", 400);
+    deleteAgentProfile(name, updatedBy, { resetBuiltInOverride: existing.value.builtIn });
     emitConfigChanged(existing.namespace, existing.key, existing.version + 1);
     return json({ ok: true });
   } catch (e) {

package/src/routes/index.ts

@@ -1,6 +1,6 @@
 // Auto-split from routes.ts (#299). Router: route table + matchRoute dispatch.
 import { deleteAgentActiveMemories, deleteAgentById, findAgents, getAgentActiveMemories, getAgentById, getAgentChatHistory, getAgentContextSnapshots, getAgentCrashReportRoute, getAgentQuotaSnapshots, getAgentReplyObligations, getAgentTimelineRoute, getAgents, getMessageArtifactsRoute, getTaskArtifactsRoute, patchAgentLabel, patchAgentReady, patchAgentStatus, patchAgentTags, postHeartbeat } from "./agents";
-import { deleteAgentProfileRoute, getAgentProfileRoute, getAgentProfilesRoute, putAgentProfileRoute } from "./agent-profiles";
+import { deleteAgentProfileRoute, getAgentProfileRoute, getAgentProfilesRoute, getResolvedAgentProfileRoute, putAgentProfileRoute } from "./agent-profiles";
 import { deleteAgentTerminalSession, getAgentDrive, getAgentPresence, postAgentAction, postAgentDrive, postAgentPermissionDecision, postAgentPresence, postAgentPrompt, postAgentTerminalSession } from "./agent-sessions";
 import { deleteMyAvatar, deleteUserAvatarById, getMe, getUserAvatar, getUsers, headUserAvatar, patchMe, patchUserById, postMyAvatar, postUserAvatarById } from "./users";
 import { deleteArtifactById, getArtifactById, getArtifactContent, getArtifacts, headArtifactContent, postArtifact } from "./artifacts";
@@ -231,6 +231,7 @@ const routes: Route[] = [
   route("PATCH", "/api/commands/:id", patchCommand),
   route("DELETE", "/api/commands/:id", deleteCommandById),
   route("GET", "/api/agent-profiles", getAgentProfilesRoute),
+  route("GET", "/api/agent-profiles/:name/resolved", getResolvedAgentProfileRoute),
   route("GET", "/api/agent-profiles/:name", getAgentProfileRoute),
   route("PUT", "/api/agent-profiles/:name", putAgentProfileRoute),
   route("DELETE", "/api/agent-profiles/:name", deleteAgentProfileRoute),

package/src/runtime-tokens.ts

@@ -132,6 +132,9 @@ export function issueRunnerRuntimeToken(input: {
       ...(input.spawnedBy ? { spawnedBy: input.spawnedBy } : {}),
       ...(input.teamId ? { teamId: input.teamId } : {}),
       ...(input.projectId ? { projectId: input.projectId } : {}),
+      // #559 — stamp the resolved profile NAME so the scoped-memory tools resolve the
+      // caller's OWN profile store (self-scoped writes). Identity-only, like projectId.
+      ...(input.profile ? { profile: input.profile } : {}),
       ...(toolGroups ? { toolGroups } : {}),
     },
     createdBy: input.createdBy ?? "runtime",

package/src/security.ts

@@ -545,7 +545,7 @@ function isTokenConstraints(value: unknown): value is TokenConstraints {
   for (const [key, item] of Object.entries(record)) {
     if (["terminalAttach", "logsRead", "canDelegate"].includes(key)) {
       if (typeof item !== "boolean") return false;
-    } else if (key === "cwd" || key === "spawnedBy" || key === "teamId" || key === "projectId" || key === "tenantId") {
+    } else if (key === "cwd" || key === "spawnedBy" || key === "teamId" || key === "projectId" || key === "profile" || key === "tenantId") {
       if (typeof item !== "string") return false;
     } else if (key === "maxSpawnedAgents") {
       if (typeof item !== "number") return false;