agentscope-ai / agentscope-ai/agentscope-java

[Question] Inconsistent persistence semantics: sessions/*.jsonl (local-first) vs MEMORY.md (sandbox-only) in e2b scenario

Open
#2,654 1 comment 0 reactions 0 assignees View on GitHub
area/core/memory area/extensions question
Dominant language
Java
Stars
5.6k
Forks
1.3k
Avg merge
4d 12h
Merged PRs (30d)
77

Description

## Question

Is the current persistence design for runtime workspace files intentional? Two classes of runtime files (sessions and MEMORY.md) currently follow **two completely different persistence paths**, which leads to inconsistent on-host vs. in-sandbox visibility.

## Observations

In the e2b sandbox scenario, `sessions/*.jsonl` files are visible on the host's local disk, but `MEMORY.md` is **never** persisted on the host — it only exists inside the sandbox.

## Root cause analysis

### `sessions/*.jsonl` — local-first, remote-as-mirror

Managed by `SessionTree`. `flush()` writes directly to the host-local path `agents//sessions/` via `Files.newBufferedWriter`, then asynchronously mirrors the files up to the remote filesystem via `scheduleMirror()`.

- `SessionTree.java:310-322` — `flush()` calls `appendToFile()` (host-local write) then `scheduleMirror()`
- `SessionTree.java:534-570` — `Files.newBufferedWriter` writes to the local workspace root
- `SessionTree.java:459-467` — `scheduleMirror()` uploads to the remote filesystem best-effort, fire-and-forget

So session files land on the host first, then get mirrored into the sandbox.

### `MEMORY.md` — filesystem-only, never on host

Written by `MemoryConsolidator` via `WorkspaceManager.writeUtf8WorkspaceRelative()`. The Javadoc at `WorkspaceManager.java:717` states "All writes go through the filesystem" — it calls `filesystem.uploadFiles(...)` directly (`WorkspaceManager.java:729`). In the e2b scenario this filesystem is `E2bSandboxFilesystem`, so `MEMORY.md` goes only into the sandbox and never hits the host disk.

### Read path

`WorkspaceManager.java:67-73` documents a two-layer read architecture: filesystem is queried first, local disk is the fallback. Hence the sandbox can read `MEMORY.md` while the host has no local copy.

## The question

- Is this divergence between "session = local-first + async mirror" and "memory = sandbox-only" intentional design, or an oversight?
- Runtime files like `MEMORY.md`, `memory/` ledgers, and watermark state are also workspace-relative writes routed through the same `writeUtf8WorkspaceRelative()` → `uploadFiles()` path. Is there a documented contract for which runtime files should have a host-local copy and which should only live in the remote filesystem?
- In the e2b case, if the sandbox is torn down without a TAR/NATIVE snapshot, host-side runtime state (memory) would be lost while session history survives. Is that the intended durability story?

Environment: e2b sandbox (`E2bSandboxFilesystem`), harness runtime.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.