Method saveFile

src/node/services/memoryService.ts:947–1002

* Whole-file save from the Memory tab. expectedSha256 is the sha captured at * load time (null = "I am creating a new file"); mismatches are conflicts so * concurrent agent edits never get silently overwritten.

(
    ctx: MemoryScopeContext,
    virtualPath: string,
    content: string,
    expectedSha256: string | null,
    actor: MemoryActor
  )

   * concurrent agent edits never get silently overwritten.
   */
  async saveFile(
    ctx: MemoryScopeContext,
    virtualPath: string,
    content: string,
    expectedSha256: string | null,
    actor: MemoryActor
  ): Promise<MemorySaveFileResult> {
    const conflict = (message: string): MemorySaveFileResult => ({
      success: false,
      error: { kind: "conflict", message },
    });
    try {
      const parsed = parseMemoryPath(virtualPath);
      const scope = this.requireFilePath(parsed, virtualPath);
      assertWithinFileSizeCap(content);
      // UI save can create new files: materialize the scope root on first use.
      const store = await this.resolveStore(ctx, scope, parsed.relPath, { createRoot: true });
      return await this.locks.withLock(store.physicalRoot, async () => {
        const kind = await store.kind(parsed.relPath);
        if (kind === "dir") {
          throw new MemoryCommandError(`${virtualPath} is a directory, not a file`);
        }
        if (expectedSha256 === null) {
          if (kind !== null) {
            return conflict(`A file already exists at ${virtualPath}; reload before saving`);
          }
          const files = await store.listFiles();
          if (files.length >= MEMORY_MAX_FILES_PER_SCOPE) {
            throw new MemoryCommandError(
              `The ${scope} memory scope is full (${MEMORY_MAX_FILES_PER_SCOPE} files); delete unused files first`
            );
          }
        } else {
          if (kind === null) {
            return conflict(`${virtualPath} no longer exists; it may have been deleted`);
          }
          const current = await this.readBoundedTextFile(store, parsed.relPath, virtualPath);
          if (sha256Hex(current) !== expectedSha256) {
            return conflict(
              `${virtualPath} changed since it was loaded; reload and re-apply your edits`
            );
          }
        }
        await store.writeFile(parsed.relPath, content);
        await this.recordUsage(ctx, scope, parsed.relPath, { write: true });
        this.emitChange(ctx, scope, parsed.relPath, actor);
        return { success: true as const, data: { sha256: sha256Hex(content) } };
      });
    } catch (error) {
      const message =
        error instanceof MemoryCommandError
          ? error.message
          : `Memory operation failed: ${getErrorMessage(error)}`;
      return { success: false, error: { kind: "error", message } };
    }
  }

  // -------------------------------------------------------------------------