Persist Sessions

In-memory sessions vanish when your process exits. For agents that power a web service, a scheduled job, or a long-lived assistant, you need conversations that outlive a single run. Persisting a session means writing enough state to durable storage — a file, a key-value store, or a database — that you can reconstruct the conversation later and let Amara pick up exactly where it left off.

What to store

A persistable session comes down to its identifier and the record of the exchange. The SDK exposes the session identifier and the message history through the stream, so persisting is a matter of capturing those and saving them under a key you control, such as a user ID or a ticket number.

import { query } from "@syntic/agent-sdk";
import { writeFile } from "node:fs/promises";
 
const transcript: unknown[] = [];
let sessionId: string | undefined;
 
for await (const message of query({
  prompt: "Start reviewing the payments module.",
  options: { cwd: process.cwd() },
})) {
  transcript.push(message);
  if (message.type === "system") sessionId = message.sessionId;
}
 
await writeFile(
  `sessions/${sessionId}.json`,
  JSON.stringify({ sessionId, transcript }),
);

Resuming from storage

To continue, load the saved record and pass its identifier back on a fresh query. Amara rehydrates the conversation and treats the new prompt as the next turn.

import asyncio, json
from pathlib import Path
from syntic_agent_sdk import query
 
async def main():
    saved = json.loads(Path("sessions/current.json").read_text())
    async for message in query(
        prompt="Continue where we left off and open a fix.",
        options={"cwd": ".", "resume": saved["session_id"]},
    ):
        if message.type == "result":
            print(message.result)
 
asyncio.run(main())

Choosing a backend

For local tools and prototypes, JSON files on disk are simple and transparent. For production services, prefer a store that fits your access patterns — a relational table keyed by session ID, a document store, or a cache with a sensible expiry. Whichever you choose, treat session records as sensitive: they can contain file contents, command output, and other project details. Encrypt at rest and scope access the same way you would any other user data. With durable sessions in place, you can pair them with checkpointing to roll a conversation back to an earlier known-good state.