session.snapshot()

A local Session fixes its system in memory the first time it is generated. Later Agent instruction or plugin registry changes do not alter an existing Session's system; newly created Sessions use the latest configuration.

Call snapshot() to explicitly persist the complete system as the Session's instruction.md:

await session.snapshot();

The file is stored at:

<project_root>/.downcity/agents/<agent_id>/sessions/<session_id>/instruction.md

When restoring the Session, the SDK reads this file first. If it does not exist, the Session regenerates its system from the Agent's current instruction and plugins. Deleting instruction.md cancels persistence and restores that behavior.

snapshot() writes the complete system, including custom instruction, SDK core, plugin system, and Session context. It does not persist message history, model, or environment variables. Multiple system blocks are merged in order into one Markdown document, and later calls atomically replace the existing file.

To regenerate from the Agent's current configuration before persisting, call await session.syncshot() followed by await session.snapshot(). If instruction.md already exists, syncshot() also overwrites it directly.

This method is available only on local AgentSession instances. A remote Session's instruction persistence policy belongs to its server host.