feat(harness): memfs-less worker agents and explicit per-session memory scopes (#3285)

Author: sarahwooders

src/settings-manager.ts

@@ -1688,9 +1688,10 @@ class SettingsManager {
             ? (updates.systemPromptVersion ?? undefined)
             : existing.systemPromptVersion,
       };
-      // Clean up undefined/false values
+      // Clean up undefined/false values (explicit memfs:false is kept — it
+      // marks deliberately memfs-less worker agents; see isMemfsExplicitlyDisabled)
       if (!updated.pinned) delete updated.pinned;
-      if (!updated.memfs) delete updated.memfs;
+      if (updated.memfs === undefined) delete updated.memfs;
       if (!updated.toolset || updated.toolset === "auto")
         delete updated.toolset;
       if (!updated.systemPromptPreset) delete updated.systemPromptPreset;
@@ -1707,9 +1708,9 @@ class SettingsManager {
         systemPromptHash: updates.systemPromptHash ?? undefined,
         systemPromptVersion: updates.systemPromptVersion ?? undefined,
       };
-      // Clean up undefined/false values
+      // Clean up undefined/false values (explicit memfs:false is kept)
       if (!newAgent.pinned) delete newAgent.pinned;
-      if (!newAgent.memfs) delete newAgent.memfs;
+      if (newAgent.memfs === undefined) delete newAgent.memfs;
       if (!newAgent.toolset || newAgent.toolset === "auto")
         delete newAgent.toolset;
       if (!newAgent.systemPromptPreset) delete newAgent.systemPromptPreset;
@@ -1731,6 +1732,17 @@ class SettingsManager {
     return this.getAgentSettings(agentId, memfsServerKey)?.memfs === true;
   }
 
+  /**
+   * Whether memfs was EXPLICITLY disabled for this agent (memfs: false in
+   * settings) — distinct from "never configured". Worker-style agents
+   * created memfs-less record this so lazy repair paths don't re-enable.
+   */
+  isMemfsExplicitlyDisabled(agentId: string): boolean {
+    const settings = this.getSettings();
+    const memfsServerKey = getCurrentMemfsServerKey(settings);
+    return this.getAgentSettings(agentId, memfsServerKey)?.memfs === false;
+  }
+
   /**
    * Enable or disable memory filesystem for an agent on the current server.
    */

src/tools/impl/shell-env.ts

@@ -398,8 +398,31 @@ export function getShellEnv(): NodeJS.ProcessEnv {
                   ),
               )
             : false;
-
-        if (inheritedMemoryDir && inheritedMemoryIsParentScoped) {
+        // An EXPLICIT memory scope (LETTA_MEMORY_DIR_EXPLICIT=1, set by a
+        // launcher that deliberately points this session's memory at an
+        // isolated copy — e.g. an SDK dream batch's memfs clone) is honored
+        // when it lies outside the agents' memory store: such a path cannot
+        // be another agent's memory, which is what this guard protects.
+        // Without the marker, a non-parent-scoped inherited value is treated
+        // as stale leakage and stripped, as before.
+        const inheritedMemoryExplicit =
+          process.env.LETTA_MEMORY_DIR_EXPLICIT === "1";
+        const memoryStoreDir = path.dirname(
+          path.dirname(getScopedMemoryFilesystemRoot(agentId)),
+        );
+        const inheritedMemoryOutsideStore = Boolean(
+          inheritedMemoryPath &&
+            !inheritedMemoryPath.startsWith(
+              `${path.resolve(memoryStoreDir)}${path.sep}`,
+            ) &&
+            inheritedMemoryPath !== path.resolve(memoryStoreDir),
+        );
+
+        if (
+          inheritedMemoryDir &&
+          (inheritedMemoryIsParentScoped ||
+            (inheritedMemoryExplicit && inheritedMemoryOutsideStore))
+        ) {
           env.MEMORY_DIR = inheritedMemoryDir;
           env.LETTA_MEMORY_DIR = inheritedLettaMemoryDir || inheritedMemoryDir;
         } else {

src/tools/shell-env.test.ts

@@ -384,6 +384,71 @@ test("getShellEnv does not inject MEMORY_DIR aliases when memfs is disabled", ()
   });
 });
 
+test("getShellEnv honors an explicit MEMORY_DIR scope outside the memory store", () => {
+  withTemporaryAgentEnv(`agent-test-${Date.now()}`, () => {
+    withTemporaryEnv(
+      {
+        MEMORY_DIR: "/tmp/dream-batch-clone/output",
+        LETTA_MEMORY_DIR: "/tmp/dream-batch-clone/output",
+        LETTA_MEMORY_DIR_EXPLICIT: "1",
+      },
+      () => {
+        const originalIsMemfsEnabled =
+          settingsManager.isMemfsEnabled.bind(settingsManager);
+        (
+          settingsManager as unknown as {
+            isMemfsEnabled: (id: string) => boolean;
+          }
+        ).isMemfsEnabled = () => false;
+        try {
+          const env = getShellEnv();
+          expect(env.MEMORY_DIR).toBe("/tmp/dream-batch-clone/output");
+          expect(env.LETTA_MEMORY_DIR).toBe("/tmp/dream-batch-clone/output");
+        } finally {
+          (
+            settingsManager as unknown as {
+              isMemfsEnabled: (id: string) => boolean;
+            }
+          ).isMemfsEnabled = originalIsMemfsEnabled;
+        }
+      },
+    );
+  });
+});
+
+test("getShellEnv strips an explicit scope pointing into another agent's memory", () => {
+  const otherAgentMemory = getMemoryFilesystemRoot(`agent-other-${Date.now()}`);
+  withTemporaryAgentEnv(`agent-test-${Date.now()}`, () => {
+    withTemporaryEnv(
+      {
+        MEMORY_DIR: otherAgentMemory,
+        LETTA_MEMORY_DIR: otherAgentMemory,
+        LETTA_MEMORY_DIR_EXPLICIT: "1",
+      },
+      () => {
+        const originalIsMemfsEnabled =
+          settingsManager.isMemfsEnabled.bind(settingsManager);
+        (
+          settingsManager as unknown as {
+            isMemfsEnabled: (id: string) => boolean;
+          }
+        ).isMemfsEnabled = () => false;
+        try {
+          const env = getShellEnv();
+          expect(env.MEMORY_DIR).toBeUndefined();
+          expect(env.LETTA_MEMORY_DIR).toBeUndefined();
+        } finally {
+          (
+            settingsManager as unknown as {
+              isMemfsEnabled: (id: string) => boolean;
+            }
+          ).isMemfsEnabled = originalIsMemfsEnabled;
+        }
+      },
+    );
+  });
+});
+
 test("getShellEnv preserves inherited parent MEMORY_DIR for subagents", () => {
   const parentAgentId = `agent-parent-${Date.now()}`;
   const childAgentId = `agent-child-${Date.now()}`;

src/types/protocol_v2.ts

@@ -782,6 +782,12 @@ export interface RuntimeStartCreateAgentOptions {
   body: AgentCreateParams;
   /** Whether to pin the created agent globally. Defaults to true. */
   pin_global?: boolean;
+  /**
+   * Whether to set up the memory filesystem for the created agent (tag
+   * stamp + settings + repo clone). Defaults to true; false creates a
+   * worker-style agent whose memory scope is provided per session.
+   */
+  memfs?: boolean;
 }
 
 export interface RuntimeStartCreateConversationOptions {

src/websocket/listener/commands/runtime-start.ts

@@ -134,16 +134,23 @@ async function resolveRuntimeStartAgent(
 ): Promise<AgentState> {
   const backend = getBackend();
   if (parsed.create_agent) {
+    const withMemfs = parsed.create_agent.memfs !== false;
     const { prepareRawCreateAgentBodyForMemfs, enableMemfsIfCloud } =
       await import("@/agent/memory-filesystem");
-    const body = await prepareRawCreateAgentBodyForMemfs(
-      parsed.create_agent.body,
-    );
+    const body = withMemfs
+      ? await prepareRawCreateAgentBodyForMemfs(parsed.create_agent.body)
+      : parsed.create_agent.body;
     const agent = await backend.createAgent(body);
-    // Finish memfs setup (settings, repo clone, legacy tool detach) without
-    // blocking runtime start. The tag is already stamped at creation, so
-    // lazy sync paths can complete this even if the process dies here.
-    void enableMemfsIfCloud(agent.id);
+    if (withMemfs) {
+      // Finish memfs setup (settings, repo clone, legacy tool detach) without
+      // blocking runtime start. The tag is already stamped at creation, so
+      // lazy sync paths can complete this even if the process dies here.
+      void enableMemfsIfCloud(agent.id);
+    } else {
+      // Worker-style agent: no memfs of its own; a memory scope may be
+      // provided per session (MEMORY_DIR + LETTA_MEMORY_DIR_EXPLICIT).
+      settingsManager.setMemfsEnabled(agent.id, false);
+    }
     created.agent = true;
     if (parsed.create_agent.pin_global !== false) {
       settingsManager.pinAgent(agent.id);

src/websocket/listener/memfs-sync.ts

@@ -14,6 +14,17 @@ import type { ListenerRuntime } from "./types";
  * Core sync logic — fetches agent, checks tag, clones/pulls repo.
  */
 async function syncMemfsForAgent(agentId: string): Promise<void> {
+  const { settingsManager } = await import("@/settings-manager");
+  if (settingsManager.isMemfsExplicitlyDisabled(agentId)) {
+    // Worker-style agent deliberately created without a memfs (e.g. dream
+    // reflectors) — its memory scope arrives per session via MEMORY_DIR.
+    // Not a broken agent; do not "repair" it.
+    debugLog(
+      "memfs-sync",
+      `Agent ${agentId} is explicitly memfs-disabled, skipping sync`,
+    );
+    return;
+  }
   const { getBackend } = await import("@/backend");
   // `include: ["agent.tags"]` is required — without it the API can return
   // empty tags for a correctly tagged agent, which previously made the

src/websocket/listener/protocol-inbound.ts

@@ -410,7 +410,8 @@ function isRuntimeStartCreateAgentOptions(value: unknown): boolean {
   if (!isObjectRecord(value)) return false;
   return (
     isObjectRecord(value.body) &&
-    (value.pin_global === undefined || typeof value.pin_global === "boolean")
+    (value.pin_global === undefined || typeof value.pin_global === "boolean") &&
+    (value.memfs === undefined || typeof value.memfs === "boolean")
   );
 }