类class io.agentscope.harness.agent.memory.session 2.x

SessionTree

public class SessionTree

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:79–804

会话树，在多次调用之间保存和恢复会话与记忆数据。位于 io.agentscope.harness.agent.memory.session 包。核心成员包括 awaitMirrorQuiescence、setRuntimeContext、setTranscriptStore、load、syncFromRemote、append。

Manages an append-only JSONL session tree (pi-mono-inspired).

The session file is a JSONL file where each line is a JSON-serialized SessionEntry. Entries form a tree via id/parentId links. A companion .log.jsonl file stores the full history for grep-ability (dual-file pattern from pi-mono mom).

File layout


agents/{agentId}/sessions/{sessionId}.jsonl — LLM context (compacted)
agents/{agentId}/sessions/{sessionId}.log.jsonl — full history (append-only, never compacted)

Persistence model The local file is the working copy. Cross-replica durability uses one of:

TranscriptStore (preferred) — each flush writes an immutable segment; concurrent writers never overwrite each other.
AbstractFilesystem full-file mirror (legacy) — O(N²) uploads and last-writer-wins across replicas; kept for backward compatibility when no TranscriptStore is set.

Deferred persistence Entries are buffered in memory and only flushed to disk on the first call to #flush() (typically after the first assistant message). This avoids partial session files from failed/short interactions.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`public` `SessionTree(Path contextFile, Path workspaceRoot, AbstractFilesystem filesystem)`	初始化 `SessionTree` 实例。 Creates a SessionTree backed by the given filesystem for remote mirroring.
`public` `SessionTree(Path contextFile, Path workspaceRoot, AbstractFilesystem filesystem, WorkspaceIndex index)`	初始化 `SessionTree` 实例。 Creates a new instance.
`public` `SessionTree(Path contextFile, Path workspaceRoot, AbstractFilesystem filesystem, WorkspaceIndex index, String contextRelativePath)`	初始化 `SessionTree` 实例。 Creates a SessionTree with optional best-effort workspace index support.

方法摘要Method Summary

方法Method	说明Description
`public static boolean awaitMirrorQuiescence(long timeout, TimeUnit unit)` static	执行 `awaitMirrorQuiescence` 方法。 Blocks until all remote-mirror tasks submitted before this call have finished.
`public` `SessionTree setRuntimeContext(RuntimeContext rc)`	设置运行时上下文。 Binds a `RuntimeContext` to this tree so that all subsequent remote filesystem reads and writes (including async mirror operations) propagate the caller's identity into namespace-aware stores.
`public` `SessionTree setTranscriptStore(TranscriptStore store, TranscriptRef ref)`	设置 `setTranscriptStore`。 Binds a `TranscriptStore` for segmented remote persistence.
`public void load()`	从持久化存储恢复数据。 Loads existing entries from the local context file into the in-memory tree.
`public void syncFromRemote()`	执行同步来自远程相关操作。 Pulls remote entries and union-merges any not yet present locally.
`public` `SessionEntry append(SessionEntry entry)`	设置追加。 Appends an entry to the in-memory tree.
`public void flush()`	执行刷新相关操作。 Flushes pending entries to the local context and log files, then schedules asynchronous remote mirrors.
`public boolean isFlushed()`	判断是否 `isFlushed`。 Returns whether `#flush()` has been called at least once.
`public List<SessionEntry> buildContext()`	构建模型可见的上下文来自会话树。 Builds the LLM-visible context from the session tree.
`public List<SessionEntry> getAllEntries()`	获取所有条目。 Returns all entries in append order (full history).
`public List<SessionEntry.MessageEntry> getMessageEntries()`	获取消息条目。 Returns only message entries in append order.
`public int size()`	返回大小。 Returns the size.
`public Path getContextFile()`	获取上下文文件。 Returns the context file.
`public Path getLogFile()`	获取日志文件。 Returns the log file.
`public int syncFromLog()`	返回同步来自日志。 Syncs entries from the log file that are not yet in the context file.

构造器详情Constructor Detail

SessionTree

public SessionTree(Path contextFile, Path workspaceRoot, AbstractFilesystem filesystem)

初始化 SessionTree 实例。

Creates a SessionTree backed by the given filesystem for remote mirroring.

参数Parameters

名称Name	类型Type	说明Description
`contextFile`	Path	上下文文件（类型 `Path`）。path to the `.jsonl` context file (LLM-facing, compacted)
`workspaceRoot`	Path	工作区根（类型 `Path`）。root of the agent workspace; used to derive workspace-relative paths
`filesystem`	AbstractFilesystem	文件系统（类型 `AbstractFilesystem`）。`AbstractFilesystem` used for remote read/write; may be `null` to disable remote mirroring (local-only mode)

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:156–158

SessionTree

public SessionTree(Path contextFile, Path workspaceRoot, AbstractFilesystem filesystem, WorkspaceIndex index)

初始化 SessionTree 实例。

Creates a new instance.

参数Parameters

名称Name	类型Type	说明Description
`contextFile`	Path	上下文文件（类型 `Path`）。The context file.
`workspaceRoot`	Path	工作区根（类型 `Path`）。The workspace root.
`filesystem`	AbstractFilesystem	文件系统（类型 `AbstractFilesystem`）。The filesystem.
`index`	WorkspaceIndex	索引（类型 `WorkspaceIndex`）。The index.

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:160–166

SessionTree

public SessionTree(Path contextFile, Path workspaceRoot, AbstractFilesystem filesystem, WorkspaceIndex index, String contextRelativePath)

初始化 SessionTree 实例。

Creates a SessionTree with optional best-effort workspace index support.

参数Parameters

名称Name	类型Type	说明Description
`contextFile`	Path	上下文文件（类型 `Path`）。path to the `.jsonl` context file
`workspaceRoot`	Path	智能体工作区的根。root of the agent workspace
`filesystem`	AbstractFilesystem	文件系统（类型 `AbstractFilesystem`）。remote filesystem; may be `null`
`index`	WorkspaceIndex	索引（类型 `WorkspaceIndex`）。best-effort workspace index; may be `null`
`contextRelativePath`	String	上下文 Relative 路径（类型 `String`）。workspace-relative path for the context file WITHOUT namespace prefix (e.g. `agents/X/sessions/Y.jsonl`); when non-null, used for filesystem mirror/restore instead of computing via `#toWorkspaceRelative(Path)`

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:180–204

方法详情Method Detail

awaitMirrorQuiescence

public static boolean awaitMirrorQuiescence(long timeout, TimeUnit unit)

static

执行 awaitMirrorQuiescence 方法。

Blocks until all remote-mirror tasks submitted before this call have finished.

参数Parameters

名称Name	类型Type	说明Description
`timeout`	long	超时时间（类型 `long`）。maximum time to wait
`unit`	TimeUnit	unit（类型 `TimeUnit`）。time unit of `timeout`

返回Returns boolean

返回布尔值，表示判断结果。`true` if the mirrors quiesced within the timeout

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:114–125

setRuntimeContext

public SessionTree setRuntimeContext(RuntimeContext rc)

设置运行时上下文。

Binds a RuntimeContext to this tree so that all subsequent remote filesystem reads and writes (including async mirror operations) propagate the caller's identity into namespace-aware stores.

参数Parameters

名称Name	类型Type	说明Description
`rc`	RuntimeContext	rc（类型 `RuntimeContext`）。the runtime context to bind; `null` resets to empty

返回Returns SessionTree

返回SessionTree。this tree, for fluent chaining

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:214–217

setTranscriptStore

public SessionTree setTranscriptStore(TranscriptStore store, TranscriptRef ref)

设置 setTranscriptStore。

Binds a TranscriptStore for segmented remote persistence.

参数Parameters

名称Name	类型Type	说明Description
`store`	TranscriptStore	存储实例（类型 `TranscriptStore`）。segment store; `null` disables segmented persistence
`ref`	TranscriptRef	引用（类型 `TranscriptRef`）。transcript identity; required when `store` is non-null

返回Returns SessionTree

返回SessionTree。this tree, for fluent chaining

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:229–233

load

public void load()

从持久化存储恢复数据。

Loads existing entries from the local context file into the in-memory tree.

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:245–266

syncFromRemote

public void syncFromRemote()

执行同步来自远程相关操作。

Pulls remote entries and union-merges any not yet present locally.

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:276–298

append

public SessionEntry append(SessionEntry entry)

设置追加。

Appends an entry to the in-memory tree.

参数Parameters

名称Name	类型Type	说明Description
`entry`	SessionEntry	条目（类型 `SessionEntry`）。The entry.

返回Returns SessionEntry

返回SessionEntry。the entry (for chaining)

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:306–317

flush

public void flush()

执行刷新相关操作。

Flushes pending entries to the local context and log files, then schedules asynchronous remote mirrors.

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:326–347

isFlushed

public boolean isFlushed()

判断是否 isFlushed。

Returns whether #flush() has been called at least once.

返回Returns boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:352–354

buildContext

public List<SessionEntry> buildContext()

构建模型可见的上下文来自会话树。

Builds the LLM-visible context from the session tree.

返回Returns List<SessionEntry>

返回列出。Returns list.

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:366–395

getAllEntries

public List<SessionEntry> getAllEntries()

获取所有条目。

Returns all entries in append order (full history).

返回Returns List<SessionEntry>

返回列出。Returns list.

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:400–402

getMessageEntries

public List<SessionEntry.MessageEntry> getMessageEntries()

获取消息条目。

Returns only message entries in append order.

返回Returns List<SessionEntry.MessageEntry>

返回列出。Returns list.

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:407–412

size

public int size()

返回大小。

Returns the size.

返回Returns int

返回数值结果。Returns a numeric result.

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:414–416

getContextFile

public Path getContextFile()

获取上下文文件。

Returns the context file.

返回Returns Path

返回路径。Returns path.

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:418–420

getLogFile

public Path getLogFile()

获取日志文件。

Returns the log file.

返回Returns Path

返回路径。Returns path.

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:422–424

syncFromLog

public int syncFromLog()

返回同步来自日志。

Syncs entries from the log file that are not yet in the context file.

返回Returns int

返回数值结果。the number of new entries synced

源码Source io/agentscope/harness/agent/memory/session/SessionTree.java:433–473