agentscope-ai / agentscope-ai/agentscope-java
[Question] Inconsistent persistence semantics: sessions/*.jsonl (local-first) vs MEMORY.md (sandbox-only) in e2b scenario
- Langage dominant
- Java
- Étoiles
- 5.6k
- Forks
- 1.3k
- Merge moyen
- 4 j 12 h
- PR mergées (30 j)
- 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.
Guide de contribution
Ouvrir le guide de contribution
Évaluation
Cette issue n'a pas encore été évaluée.