@desplega.ai/agent-swarm 1.98.0 → 1.99.0

package/src/be/scripts/typecheck.ts

@@ -51,8 +51,8 @@ export interface SwarmConfig {
 
 export interface SwarmSdk {
   // --- memory ---
-  memory_search(args: { query: string; scope?: "all" | "agent" | "swarm"; limit?: number; source?: string }): Promise<unknown>;
-  memory_get(args: { memoryId: string }): Promise<unknown>;
+  memory_search(args: { query: string; intent: string; scope?: "all" | "agent" | "swarm"; limit?: number; source?: string }): Promise<unknown>;
+  memory_get(args: { memoryId: string; intent: string }): Promise<unknown>;
   memory_rate(args: { id: string; useful: boolean; note?: string }): Promise<unknown>;
   // --- tasks ---
   task_list(args?: Record<string, unknown>): Promise<unknown>;
@@ -176,6 +176,7 @@ export interface SwarmSdk {
   // --- skills ---
   skill_list(args?: { scope?: string; scopeId?: string; includeBuiltin?: boolean }): Promise<unknown>;
   skill_get(args: { id: string }): Promise<unknown>;
+  skill_getFile(args: { skillId: string; path: string }): Promise<unknown>;
   skill_search(args: { query: string; limit?: number }): Promise<unknown>;
   skill_create(args: Record<string, unknown>): Promise<unknown>;
   skill_update(args: Record<string, unknown>): Promise<unknown>;

package/src/be/seed-pricing.ts

@@ -2,7 +2,9 @@
  * Phase 2 of the cost-tracking plan — seed the `pricing` table at server boot.
  *
  * The vendored models.dev snapshot at `src/be/modelsdev-cache.json` is the
- * single source of truth for per-token rates. We project it into rows keyed by
+ * cold-start fallback for per-token rates. Runtime freshness is owned by
+ * `src/be/pricing-refresh.ts`, which fetches models.dev after boot and inserts
+ * newer effective rows when prices change. We project both sources into rows keyed by
  * `(provider, model, token_class)` so the recompute path in
  * `src/http/session-data.ts` can rebuild USD from tokens regardless of which
  * adapter wrote the row.
@@ -74,7 +76,7 @@ const ANTHROPIC_SHORTNAME_TO_MODELSDEV: Record<string, string> = {
   haiku: "claude-haiku-4-5",
 };
 
-interface PricingSeedRow {
+export interface PricingSeedRow {
   provider: PricingProvider;
   model: string;
   tokenClass: PricingTokenClass;
@@ -127,7 +129,7 @@ function projectCostBlock(
  * "what the adapter writes for `model`" and "what models.dev keys by" is
  * explicit and auditable.
  */
-function buildModelsDevSeedRows(cache: ModelsDevCache): PricingSeedRow[] {
+export function buildModelsDevSeedRows(cache: ModelsDevCache): PricingSeedRow[] {
   const rows: PricingSeedRow[] = [];
 
   // ---- Anthropic / claude family ----------------------------------------

package/src/commands/profile-sync.ts

@@ -34,6 +34,42 @@ export const IDENTITY_MD_PATH = "/workspace/IDENTITY.md";
 export const TOOLS_MD_PATH = "/workspace/TOOLS.md";
 export const HEARTBEAT_MD_PATH = "/workspace/HEARTBEAT.md";
 export const SETUP_SCRIPT_PATH = "/workspace/start-up.sh";
+
+// ──────────────────────────────────────────────────────────────────────────
+// Identity-file baseline hashes — prevents session-end sync from clobbering
+// DB-side edits made by Lead (via update-profile) during a running session.
+//
+// Flow:
+//   1. Runner writes DB content → /workspace/*.md at session start.
+//   2. Runner records SHA-256 hashes of the written content (the "baselines").
+//   3. At session end, sync compares current file hash against its baseline.
+//      - Hash matches → file untouched by the agent → skip sync (preserves
+//        any DB-side edits Lead made during the session).
+//      - Hash differs → agent modified the file → sync it back to DB.
+// ──────────────────────────────────────────────────────────────────────────
+export const IDENTITY_BASELINES_PATH = "/tmp/identity-baselines.json";
+
+export type IdentityBaselines = Record<string, string>;
+
+export function contentSha256(content: string): string {
+  return new Bun.CryptoHasher("sha256").update(content).digest("hex");
+}
+
+export async function writeIdentityBaselines(baselines: IdentityBaselines): Promise<void> {
+  await Bun.write(IDENTITY_BASELINES_PATH, JSON.stringify(baselines));
+}
+
+export async function readIdentityBaselines(
+  readFile: FileReader = readFileIfExists,
+): Promise<IdentityBaselines | null> {
+  try {
+    const raw = await readFile(IDENTITY_BASELINES_PATH);
+    if (!raw) return null;
+    return JSON.parse(raw) as IdentityBaselines;
+  } catch {
+    return null;
+  }
+}
 /**
  * Claude Code's personal-file CLAUDE.md path. This is what the Claude plugin
  * Stop hook reads and owns — the runner only uses it as a backstop for an
@@ -135,18 +171,27 @@ export function extractSetupScriptContent(raw: string): string | null {
  * the trim / max-length guards and the SOUL/IDENTITY min-length guard. Returns
  * an empty object when nothing is syncable (callers should skip the POST).
  * `undefined` inputs mean the file was absent.
+ *
+ * When `baselines` is provided, skips any field whose content hash matches the
+ * baseline (i.e. the file was not modified during the session). This prevents
+ * session-end sync from clobbering DB-side edits made by Lead.
  */
-export function buildIdentityPayload(files: {
-  soulMd?: string;
-  identityMd?: string;
-  toolsMd?: string;
-  heartbeatMd?: string;
-}): Record<string, string> {
+export function buildIdentityPayload(
+  files: {
+    soulMd?: string;
+    identityMd?: string;
+    toolsMd?: string;
+    heartbeatMd?: string;
+  },
+  baselines?: IdentityBaselines | null,
+): Record<string, string> {
   const updates: Record<string, string> = {};
 
   if (files.soulMd !== undefined) {
     const content = files.soulMd;
-    if (content.trim() && content.length <= MAX_FILE_LENGTH) {
+    if (baselines?.soulMd && contentSha256(content) === baselines.soulMd) {
+      // File unchanged during session — skip to preserve Lead's DB edits
+    } else if (content.trim() && content.length <= MAX_FILE_LENGTH) {
       if (content.length < IDENTITY_FILE_MIN_LENGTH) {
         console.error(
           `[profile-sync] Skipping SOUL.md sync: content too short (${content.length} chars, minimum ${IDENTITY_FILE_MIN_LENGTH}). This prevents accidental profile corruption.`,
@@ -159,7 +204,9 @@ export function buildIdentityPayload(files: {
 
   if (files.identityMd !== undefined) {
     const content = files.identityMd;
-    if (content.trim() && content.length <= MAX_FILE_LENGTH) {
+    if (baselines?.identityMd && contentSha256(content) === baselines.identityMd) {
+      // File unchanged during session — skip to preserve Lead's DB edits
+    } else if (content.trim() && content.length <= MAX_FILE_LENGTH) {
       if (content.length < IDENTITY_FILE_MIN_LENGTH) {
         console.error(
           `[profile-sync] Skipping IDENTITY.md sync: content too short (${content.length} chars, minimum ${IDENTITY_FILE_MIN_LENGTH}). This prevents accidental profile corruption.`,
@@ -172,14 +219,18 @@ export function buildIdentityPayload(files: {
 
   if (files.toolsMd !== undefined) {
     const content = files.toolsMd;
-    if (content.trim() && content.length <= MAX_FILE_LENGTH) {
+    if (baselines?.toolsMd && contentSha256(content) === baselines.toolsMd) {
+      // File unchanged during session — skip
+    } else if (content.trim() && content.length <= MAX_FILE_LENGTH) {
       updates.toolsMd = content;
     }
   }
 
   if (files.heartbeatMd !== undefined) {
     const content = files.heartbeatMd;
-    if (content.length <= MAX_FILE_LENGTH) {
+    if (baselines?.heartbeatMd && contentSha256(content) === baselines.heartbeatMd) {
+      // File unchanged during session — skip
+    } else if (content.length <= MAX_FILE_LENGTH) {
       updates.heartbeatMd = content;
     }
   }
@@ -205,6 +256,12 @@ async function readFileIfExists(path: string): Promise<string | undefined> {
  * Collect the profile-update POST bodies to send. Each entry is one POST.
  * `fields` selects which groups to include. The file reader is injectable so
  * the field-selection / guard logic can be unit-tested without touching the FS.
+ *
+ * When `changeSource` is `"session_sync"`, loads baseline hashes written at
+ * session start and skips identity fields whose content hasn't changed — this
+ * prevents blind-overwriting DB-side edits made by Lead during the session.
+ * On-edit syncs (`"self_edit"`) bypass baselines entirely since the agent
+ * explicitly changed the file and the new content should propagate.
  */
 export async function collectProfilePayloads(
   fields: ProfileSyncField[],
@@ -214,13 +271,18 @@ export async function collectProfilePayloads(
 ): Promise<ProfilePayload[]> {
   const payloads: ProfilePayload[] = [];
 
+  const baselines = changeSource === "session_sync" ? await readIdentityBaselines(readFile) : null;
+
   if (fields.includes("identity")) {
-    const updates = buildIdentityPayload({
-      soulMd: await readFile(SOUL_MD_PATH),
-      identityMd: await readFile(IDENTITY_MD_PATH),
-      toolsMd: await readFile(TOOLS_MD_PATH),
-      heartbeatMd: await readFile(HEARTBEAT_MD_PATH),
-    });
+    const updates = buildIdentityPayload(
+      {
+        soulMd: await readFile(SOUL_MD_PATH),
+        identityMd: await readFile(IDENTITY_MD_PATH),
+        toolsMd: await readFile(TOOLS_MD_PATH),
+        heartbeatMd: await readFile(HEARTBEAT_MD_PATH),
+      },
+      baselines,
+    );
     if (Object.keys(updates).length > 0) {
       payloads.push({ label: "identity", body: { ...updates, changeSource } });
     }
@@ -229,7 +291,11 @@ export async function collectProfilePayloads(
   if (fields.includes("claude")) {
     const raw = await readFile(claudeMdPath);
     if (raw?.trim() && raw.length <= MAX_FILE_LENGTH) {
-      payloads.push({ label: "claude", body: { claudeMd: raw, changeSource } });
+      if (baselines?.claudeMd && contentSha256(raw) === baselines.claudeMd) {
+        // CLAUDE.md unchanged during session — skip to preserve Lead's DB edits
+      } else {
+        payloads.push({ label: "claude", body: { claudeMd: raw, changeSource } });
+      }
     }
   }
 

package/src/commands/runner.ts

@@ -57,7 +57,12 @@ import { validateJsonSchema } from "../workflows/json-schema-validator.ts";
 import { interpolate } from "../workflows/template.ts";
 import { buildContextPreamble, buildResumeContextPreamble } from "./context-preamble.ts";
 import { awaitCredentials, BootMaxWaitExceededError, EX_CONFIG } from "./credential-wait.ts";
-import { resolveClaudeMdPath, syncProfileFilesToServer } from "./profile-sync.ts";
+import {
+  contentSha256,
+  resolveClaudeMdPath,
+  syncProfileFilesToServer,
+  writeIdentityBaselines,
+} from "./profile-sync.ts";
 import {
   buildCredStatusReport,
   buildLatestModelReport,
@@ -1312,6 +1317,7 @@ async function getPausedTasksFromAPI(config: ApiConfig): Promise<
     finishedAt?: string;
     output?: string;
     status?: string;
+    contextKey?: string;
   }>
 > {
   const headers: Record<string, string> = {
@@ -2324,6 +2330,7 @@ async function fetchRelevantMemories(
   agentId: string,
   taskDescription: string,
   taskId?: string,
+  contextKey?: string,
 ): Promise<string | null> {
   try {
     const headers: Record<string, string> = {
@@ -2336,11 +2343,12 @@ async function fetchRelevantMemories(
     // memories they surface against this task's session_logs at completion.
     // Plan: thoughts/taras/plans/2026-05-05-memory-rater-v1.5/step-2.md §2
     if (taskId) headers["X-Source-Task-ID"] = taskId;
+    if (contextKey) headers["X-Context-Key"] = contextKey;
 
     const response = await fetch(`${apiUrl}/api/memory/search`, {
       method: "POST",
       headers,
-      body: JSON.stringify({ query: taskDescription, limit: 5 }),
+      body: JSON.stringify({ query: taskDescription, limit: 5, intent: "pre-task memory recall" }),
     });
 
     if (!response.ok) return null;
@@ -2595,6 +2603,7 @@ async function spawnProviderProcess(
     harnessProvider: ProviderName;
     cwd?: string;
     vcsRepo?: string;
+    contextKey?: string;
   },
   logDir: string,
   isYolo: boolean,
@@ -2683,6 +2692,7 @@ async function spawnProviderProcess(
     // Propagate the selected OAuth slot so the adapter refreshes back to the
     // correct pool key. Undefined for non-codex providers and single-cred deploys.
     codexSlot: oauthSelection?.index,
+    contextKey: opts.contextKey,
   };
 
   // Create the long-lived `worker.session` span up front so the provider
@@ -4307,6 +4317,23 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
     }
   }
 
+  // Record baseline hashes of identity files as written from DB. Session-end
+  // sync compares current file content against these baselines: unchanged files
+  // are skipped, which prevents clobbering DB-side edits made by Lead via
+  // update-profile during the running session.
+  try {
+    const baselines: Record<string, string> = {};
+    if (agentSoulMd) baselines.soulMd = contentSha256(agentSoulMd);
+    if (agentIdentityMd) baselines.identityMd = contentSha256(agentIdentityMd);
+    if (agentToolsMd) baselines.toolsMd = contentSha256(agentToolsMd);
+    if (agentHeartbeatMd) baselines.heartbeatMd = contentSha256(agentHeartbeatMd);
+    if (agentClaudeMd) baselines.claudeMd = contentSha256(agentClaudeMd);
+    await writeIdentityBaselines(baselines);
+    console.log(`[${role}] Recorded identity file baselines for session-end sync`);
+  } catch {
+    // Non-fatal — worst case, session-end sync proceeds as before (blind overwrite)
+  }
+
   // ========== Boot-time skill load (signature-gated, replaces the standalone
   // skill-fetch + FS sync blocks). The polling loop below calls the same
   // helper per task to hot-reload skills mid-flight. Skipped for
@@ -4390,6 +4417,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
           agentId,
           task.task,
           task.id,
+          (task as { contextKey?: string }).contextKey,
         );
         if (resumeMemoryContext) {
           resumePrompt += resumeMemoryContext;
@@ -4515,6 +4543,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
               harnessProvider: state.harnessProvider,
               cwd: resumeCwd,
               vcsRepo: task.vcsRepo,
+              contextKey: (task as { contextKey?: string }).contextKey,
             },
             logDir,
             isYolo,
@@ -4780,7 +4809,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
         if (trigger.type === "task_assigned" || trigger.type === "task_offered") {
           const task =
             trigger.task && typeof trigger.task === "object" && "task" in trigger.task
-              ? (trigger.task as { task: string; id?: string })
+              ? (trigger.task as { task: string; id?: string; contextKey?: string })
               : null;
           if (task?.task) {
             const memoryContext = await fetchRelevantMemories(
@@ -4789,6 +4818,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
               agentId,
               task.task,
               task.id,
+              task.contextKey,
             );
             if (memoryContext) {
               triggerPrompt += memoryContext;
@@ -4848,6 +4878,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
         // Extract model from task data for per-task model selection
         const taskModel = (trigger.task as { model?: string } | undefined)?.model;
         const taskModelTier = (trigger.task as { modelTier?: string } | undefined)?.modelTier;
+        const taskContextKey = (trigger.task as { contextKey?: string } | undefined)?.contextKey;
 
         // Detect Slack context for conditional prompt sections
         const taskSlackChannelId = (trigger.task as { slackChannelId?: string } | undefined)
@@ -4994,6 +5025,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
               harnessProvider: state.harnessProvider,
               cwd: effectiveCwd,
               vcsRepo: taskVcsRepo,
+              contextKey: taskContextKey,
             },
             logDir,
             isYolo,

package/src/e2b/dispatch.ts

@@ -361,6 +361,11 @@ export async function startDetachedProcess(opts: StartDetachedOptions): Promise<
     cwd: opts.cwd ?? "/",
     envs: opts.env,
     background: true,
+    // CRITICAL: the SDK's default `timeoutMs` is 60s and applies to background
+    // commands too — envd kills the whole tracked tree (entrypoint + children)
+    // when it expires, silently stopping the worker runner ~60s after boot.
+    // 0 disables the limit; sandbox lifetime is governed by its own TTL.
+    timeoutMs: 0,
   });
 
   // Early liveness poll: give the entrypoint a moment to fault, then check the

package/src/hooks/hook.ts

@@ -9,6 +9,7 @@ import {
   postRatings,
   type RetrievalRow,
 } from "../be/memory/raters/llm";
+import { contentSha256, readIdentityBaselines } from "../commands/profile-sync";
 import type { Agent } from "../types";
 import { getApiKey } from "../utils/api-key";
 import { getMcpBaseUrl } from "../utils/constants";
@@ -581,7 +582,12 @@ export async function handleHook(): Promise<void> {
   const IDENTITY_FILE_MIN_LENGTH = 500;
 
   /**
-   * Sync SOUL.md and IDENTITY.md content back to the server
+   * Sync SOUL.md and IDENTITY.md content back to the server.
+   *
+   * When `changeSource` is `"session_sync"` (the Stop-hook default), loads
+   * baseline hashes written at session start and skips any file whose content
+   * hasn't changed. This prevents the session-end sync from clobbering DB-side
+   * edits that Lead made via `update-profile` during the running session.
    */
   const syncIdentityFilesToServer = async (
     agentId: string,
@@ -589,12 +595,16 @@ export async function handleHook(): Promise<void> {
   ): Promise<void> => {
     if (!mcpConfig) return;
 
+    const baselines = changeSource === "session_sync" ? await readIdentityBaselines() : null;
+
     const updates: Record<string, string> = {};
 
     const soulFile = Bun.file(SOUL_MD_PATH);
     if (await soulFile.exists()) {
       const content = await soulFile.text();
-      if (content.trim() && content.length <= 65536) {
+      if (baselines?.soulMd && contentSha256(content) === baselines.soulMd) {
+        // Unchanged during session — skip to preserve Lead's DB edits
+      } else if (content.trim() && content.length <= 65536) {
         if (content.length < IDENTITY_FILE_MIN_LENGTH) {
           console.error(
             `[hook] Skipping SOUL.md sync: content too short (${content.length} chars, minimum ${IDENTITY_FILE_MIN_LENGTH}). This prevents accidental profile corruption.`,
@@ -608,7 +618,9 @@ export async function handleHook(): Promise<void> {
     const identityFile = Bun.file(IDENTITY_MD_PATH);
     if (await identityFile.exists()) {
       const content = await identityFile.text();
-      if (content.trim() && content.length <= 65536) {
+      if (baselines?.identityMd && contentSha256(content) === baselines.identityMd) {
+        // Unchanged during session — skip
+      } else if (content.trim() && content.length <= 65536) {
         if (content.length < IDENTITY_FILE_MIN_LENGTH) {
           console.error(
             `[hook] Skipping IDENTITY.md sync: content too short (${content.length} chars, minimum ${IDENTITY_FILE_MIN_LENGTH}). This prevents accidental profile corruption.`,
@@ -622,7 +634,9 @@ export async function handleHook(): Promise<void> {
     const toolsMdFile = Bun.file(TOOLS_MD_PATH);
     if (await toolsMdFile.exists()) {
       const content = await toolsMdFile.text();
-      if (content.trim() && content.length <= 65536) {
+      if (baselines?.toolsMd && contentSha256(content) === baselines.toolsMd) {
+        // Unchanged during session — skip
+      } else if (content.trim() && content.length <= 65536) {
         updates.toolsMd = content;
       }
     }
@@ -630,7 +644,9 @@ export async function handleHook(): Promise<void> {
     const heartbeatFile = Bun.file(HEARTBEAT_MD_PATH);
     if (await heartbeatFile.exists()) {
       const content = await heartbeatFile.text();
-      if (content.length <= 65536) {
+      if (baselines?.heartbeatMd && contentSha256(content) === baselines.heartbeatMd) {
+        // Unchanged during session — skip
+      } else if (content.length <= 65536) {
         updates.heartbeatMd = content;
       }
     }

package/src/http/index.ts

@@ -451,6 +451,8 @@ try {
 try {
   const { seedPricingFromModelsDev } = await import("../be/seed-pricing");
   seedPricingFromModelsDev();
+  const { startPricingRefreshLoop } = await import("../be/pricing-refresh");
+  startPricingRefreshLoop();
 } catch (err) {
   console.error("[startup] Failed to seed pricing rows:", err);
 }

package/src/http/memory.ts

@@ -1,10 +1,11 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import { chunkContent } from "../be/chunking";
-import { getTaskById } from "../be/db";
+import { getDb, getTaskById } from "../be/db";
 import { getEmbeddingProvider, getMemoryStore } from "../be/memory";
 import { CANDIDATE_SET_MULTIPLIER } from "../be/memory/constants";
 import { listEdgesForAgent } from "../be/memory/edges-store";
+import { storeLinks } from "../be/memory/link-resolver";
 import { recordRetrievals } from "../be/memory/raters/retrieval";
 import { applyRating, ExplicitSelfDuplicateError } from "../be/memory/raters/store";
 import {
@@ -37,6 +38,7 @@ const indexMemory = route({
     sourcePath: z.string().optional(),
     tags: z.array(z.string()).optional(),
     persistMemory: z.boolean().optional(),
+    contextKey: z.string().optional(),
   }),
   responses: {
     202: { description: "Content queued for embedding" },
@@ -53,6 +55,13 @@ const searchMemory = route({
   auth: { apiKey: true, agentId: true },
   body: z.object({
     query: z.string().min(1),
+    intent: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        "Why you are searching. Required for agent recall-edge tracking; omit for UI browse/search calls.",
+      ),
     limit: z.number().int().min(1).max(20).default(5),
     scope: z.enum(["agent", "swarm", "all"]).default("all"),
     source: z.enum(["manual", "file_index", "session_summary", "task_completion"]).optional(),
@@ -149,6 +158,15 @@ const getMemoryById = route({
   tags: ["Memory"],
   auth: { apiKey: true, agentId: true },
   params: z.object({ id: z.string().uuid() }),
+  query: z.object({
+    intent: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        "Why you are retrieving this memory. Required for agent recall-edge tracking; omit for UI browse calls.",
+      ),
+  }),
   responses: {
     200: { description: "Memory details" },
     404: { description: "Memory not found" },
@@ -266,8 +284,18 @@ export async function handleMemory(
     const parsed = await indexMemory.parse(req, res, pathSegments, new URLSearchParams());
     if (!parsed) return true;
 
-    const { agentId, content, name, scope, source, sourceTaskId, sourcePath, tags, persistMemory } =
-      parsed.body;
+    const {
+      agentId,
+      content,
+      name,
+      scope,
+      source,
+      sourceTaskId,
+      sourcePath,
+      tags,
+      persistMemory,
+      contextKey,
+    } = parsed.body;
 
     if (source === "session_summary" && sourceTaskId) {
       const sourceTask = getTaskById(sourceTaskId);
@@ -296,6 +324,13 @@ export async function handleMemory(
       store.deleteBySourcePath(sourcePath, agentId);
     }
 
+    // Derive contextKey from body or X-Context-Key header
+    const headerContextKey = req.headers["x-context-key"];
+    const resolvedContextKey =
+      contextKey ??
+      (Array.isArray(headerContextKey) ? headerContextKey[0] : headerContextKey) ??
+      undefined;
+
     // Atomic batch insert — all chunks or none
     const memories = store.storeBatch(
       contentChunks.map((chunk) => ({
@@ -309,9 +344,24 @@ export async function handleMemory(
         chunkIndex: chunk.chunkIndex,
         totalChunks: chunk.totalChunks,
         tags: tags || [],
+        contextKey: resolvedContextKey ?? null,
       })),
     );
 
+    // Resolve and store deterministic links (wikilinks, PR refs, agent-fs paths)
+    if (agentId) {
+      for (const memory of memories) {
+        try {
+          storeLinks(memory.id, agentId, memory.content);
+        } catch (err) {
+          console.error(
+            `[memory] Link resolution failed for ${memory.id}:`,
+            (err as Error).message,
+          );
+        }
+      }
+    }
+
     // Async batch embed (fire and forget)
     (async () => {
       try {
@@ -339,7 +389,7 @@ export async function handleMemory(
     const parsed = await searchMemory.parse(req, res, pathSegments, new URLSearchParams());
     if (!parsed) return true;
 
-    const { query, limit, scope, source } = parsed.body;
+    const { query, intent, limit, scope, source } = parsed.body;
 
     try {
       const provider = getEmbeddingProvider();
@@ -369,12 +419,16 @@ export async function handleMemory(
       const sourceTaskId = Array.isArray(sourceTaskIdHeader)
         ? sourceTaskIdHeader[0]
         : sourceTaskIdHeader;
-      if (sourceTaskId) {
+      const contextKeyHeader = req.headers["x-context-key"];
+      const contextKey = Array.isArray(contextKeyHeader) ? contextKeyHeader[0] : contextKeyHeader;
+      if (sourceTaskId && intent) {
         try {
           recordRetrievals(
             sourceTaskId,
             myAgentId,
             ranked.map((r) => ({ memoryId: r.id, similarity: r.similarity })),
+            undefined,
+            { intent, contextKey, eventType: "search" },
           );
         } catch (err) {
           console.error("[memory-search] recordRetrievals failed:", (err as Error).message);
@@ -620,7 +674,11 @@ export async function handleMemory(
           reasoning: e.reasoning,
           ...(e.referencesSource !== undefined ? { referencesSource: e.referencesSource } : {}),
         }));
-        const result = applyRating(ratingEvents, { taskId });
+        const rateContextKeyHeader = req.headers["x-context-key"];
+        const rateContextKey = Array.isArray(rateContextKeyHeader)
+          ? rateContextKeyHeader[0]
+          : rateContextKeyHeader;
+        const result = applyRating(ratingEvents, { taskId, contextKey: rateContextKey });
         applied += result.applied;
         for (const r of result.rejected) {
           rejected.push({ memoryId: r.event.memoryId, reason: r.reason });
@@ -671,7 +729,8 @@ export async function handleMemory(
   }
 
   if (getMemoryById.match(req.method, pathSegments)) {
-    const parsed = await getMemoryById.parse(req, res, pathSegments, new URLSearchParams());
+    const queryParams = parseQueryParams(req.url || "");
+    const parsed = await getMemoryById.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
 
     const memory = getMemoryStore().get(parsed.params.id);
@@ -680,6 +739,27 @@ export async function handleMemory(
       return true;
     }
 
+    const { intent } = parsed.query;
+    const sourceTaskIdHeader = req.headers["x-source-task-id"];
+    const sourceTaskId = Array.isArray(sourceTaskIdHeader)
+      ? sourceTaskIdHeader[0]
+      : sourceTaskIdHeader;
+    const contextKeyHeader = req.headers["x-context-key"];
+    const contextKey = Array.isArray(contextKeyHeader) ? contextKeyHeader[0] : contextKeyHeader;
+    if (sourceTaskId && myAgentId && intent) {
+      try {
+        recordRetrievals(
+          sourceTaskId,
+          myAgentId,
+          [{ memoryId: memory.id, similarity: 1.0 }],
+          undefined,
+          { intent, contextKey, eventType: "get" },
+        );
+      } catch (err) {
+        console.error("[memory-get] recordRetrievals failed:", (err as Error).message);
+      }
+    }
+
     json(res, { memory });
     return true;
   }
@@ -692,6 +772,23 @@ export async function handleMemory(
 const MEMORY_GC_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
 let memoryGcTimer: ReturnType<typeof setInterval> | null = null;
 
+const SEARCH_RETRIEVAL_TTL_DAYS = 90;
+
+function purgeStaleSearchRetrievals(): number {
+  try {
+    const cutoff = new Date(
+      Date.now() - SEARCH_RETRIEVAL_TTL_DAYS * 24 * 60 * 60 * 1000,
+    ).toISOString();
+    const result = getDb()
+      .prepare("DELETE FROM memory_retrieval WHERE eventType = 'search' AND retrievedAt < ?")
+      .run(cutoff);
+    return result.changes;
+  } catch (err) {
+    console.error("[memory-gc] Search retrieval purge failed:", (err as Error).message);
+    return 0;
+  }
+}
+
 export function startMemoryGc(intervalMs = MEMORY_GC_INTERVAL_MS): void {
   if (memoryGcTimer) return;
 
@@ -701,6 +798,12 @@ export function startMemoryGc(intervalMs = MEMORY_GC_INTERVAL_MS): void {
     if (purged > 0) {
       console.log(`[memory-gc] Initial purge removed ${purged} expired memory row(s)`);
     }
+    const searchPurged = purgeStaleSearchRetrievals();
+    if (searchPurged > 0) {
+      console.log(
+        `[memory-gc] Initial purge removed ${searchPurged} stale search retrieval row(s)`,
+      );
+    }
   } catch (err) {
     console.error("[memory-gc] Initial purge failed:", err);
   }
@@ -711,6 +814,12 @@ export function startMemoryGc(intervalMs = MEMORY_GC_INTERVAL_MS): void {
       if (purged > 0) {
         console.log(`[memory-gc] Periodic purge removed ${purged} expired memory row(s)`);
       }
+      const searchPurged = purgeStaleSearchRetrievals();
+      if (searchPurged > 0) {
+        console.log(
+          `[memory-gc] Periodic purge removed ${searchPurged} stale search retrieval row(s)`,
+        );
+      }
     } catch (err) {
       console.error("[memory-gc] Periodic purge failed:", err);
     }