Skip to content

Memory

Memory

Bases: Capability

Read and generate sandbox memory artifacts for an agent.

Shell is required for memory reads. Filesystem is required when live updates are enabled.

Source code in src/agents/sandbox/capabilities/memory.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
class Memory(Capability):
    """Read and generate sandbox memory artifacts for an agent.

    `Shell` is required for memory reads. `Filesystem` is required when live updates are enabled.
    """

    type: Literal["memory"] = "memory"
    layout: MemoryLayoutConfig = Field(default_factory=MemoryLayoutConfig)
    """Filesystem layout used for rollout and memory files."""
    read: MemoryReadConfig | None = Field(default_factory=MemoryReadConfig)
    """Read-side configuration. Set to `None` to disable memory reads."""
    generate: MemoryGenerateConfig | None = Field(default_factory=MemoryGenerateConfig)
    """Generation configuration. Set to `None` to disable background memory generation."""

    def clone(self) -> Memory:
        """Return a per-run copy without deep-copying stateful memory model objects."""
        return self.model_copy(deep=False, update={"session": None})

    def model_post_init(self, context: object, /) -> None:
        _ = context
        if self.read is None and self.generate is None:
            raise ValueError("Memory requires at least one of `read` or `generate`.")
        _validate_relative_path(name="layout.memories_dir", path=Path(self.layout.memories_dir))
        _validate_relative_path(name="layout.sessions_dir", path=Path(self.layout.sessions_dir))

    def required_capability_types(self) -> set[str]:
        if self.read is None:
            return set()
        if self.read.live_update:
            return {"filesystem", "shell"}
        return {"shell"}

    async def instructions(self, manifest: Manifest) -> str | None:
        _ = manifest
        if self.read is None:
            return None
        if self.session is None:
            raise ValueError("Memory capability is not bound to a SandboxSession")

        memory_summary_path = Path(self.layout.memories_dir) / "memory_summary.md"
        try:
            handle = await self.session.read(memory_summary_path, user=self.run_as)
        except WorkspaceReadNotFoundError:
            return None

        try:
            payload = handle.read()
        finally:
            handle.close()

        memory_summary = truncate_text(
            cast(bytes, payload).decode("utf-8", errors="replace").strip(),
            TruncationPolicy.tokens(_MEMORY_SUMMARY_MAX_TOKENS),
        )
        if not memory_summary:
            return None

        return render_memory_read_prompt(
            memory_dir=self.layout.memories_dir,
            memory_summary=memory_summary,
            live_update=self.read.live_update,
        )

layout class-attribute instance-attribute 

layout: MemoryLayoutConfig = Field(
    default_factory=MemoryLayoutConfig
)

Filesystem layout used for rollout and memory files.

read class-attribute instance-attribute 

read: MemoryReadConfig | None = Field(
    default_factory=MemoryReadConfig
)

Read-side configuration. Set to None to disable memory reads.

generate class-attribute instance-attribute 

generate: MemoryGenerateConfig | None = Field(
    default_factory=MemoryGenerateConfig
)

Generation configuration. Set to None to disable background memory generation.

clone 

clone() -> Memory

Return a per-run copy without deep-copying stateful memory model objects.

Source code in src/agents/sandbox/capabilities/memory.py 
32
33
34
def clone(self) -> Memory:
    """Return a per-run copy without deep-copying stateful memory model objects."""
    return self.model_copy(deep=False, update={"session": None})

bind 

bind(session: BaseSandboxSession) -> None

Bind a live session to this plugin (default no-op).

Source code in src/agents/sandbox/capabilities/capability.py 
29
30
31
def bind(self, session: BaseSandboxSession) -> None:
    """Bind a live session to this plugin (default no-op)."""
    self.session = session

bind_run_as 

bind_run_as(user: User | None) -> None

Bind the sandbox user identity for model-facing operations.

Source code in src/agents/sandbox/capabilities/capability.py 
33
34
35
def bind_run_as(self, user: User | None) -> None:
    """Bind the sandbox user identity for model-facing operations."""
    self.run_as = user

sampling_params 

sampling_params(
    sampling_params: dict[str, Any],
) -> dict[str, Any]

Return additional model request parameters needed for this capability.

Source code in src/agents/sandbox/capabilities/capability.py 
52
53
54
55
def sampling_params(self, sampling_params: dict[str, Any]) -> dict[str, Any]:
    """Return additional model request parameters needed for this capability."""
    _ = sampling_params
    return {}

process_context 

process_context(
    context: list[TResponseInputItem],
) -> list[TResponseInputItem]

Transform the model input context before sampling.

Source code in src/agents/sandbox/capabilities/capability.py 
57
58
59
def process_context(self, context: list[TResponseInputItem]) -> list[TResponseInputItem]:
    """Transform the model input context before sampling."""
    return context