Lesson 3: Session Management

Picoflow uses a NoSQL JSON document to log its execution state. Every round of the conversation is written to this persistent storage. It supports MongoDB-compatible engines, including AWS DocumentDB, and also supports CosmosDB natively.

Let's dissect the following session document:

Each session has an id that is used to restore prior session.
each session has a runStatus indicating if it _completed_ , _aborted_(in case of exceptions), or other interesting statuses.
The session will be expired after the "expireAfter": 50000 in seconds.
the tokens properties captures all tokens used up to the point of observation.

  "tokens": {
    "inputTokens": 451,
    "outputTokens": 47,
    "totalTokens": 617
  }

in the flows section , we see there is a TutorialFlow and its memory captured. The nameSpace is partitioning of these memory that can be fed to a Step when it is executing LLM task. The history array are the messages of a conversation that are used as context window .

"flows": [
    {
      "name": "TutorialFlow",
      "memory": [
        {
          "nameSpace": "default",
          "history": [
            {
              "type": "system",
              "content": "Tell user the chat has ended. Do you engage in further conversation",
              "id": "EndStep|2025-11-14T22:29:44.816Z|8871362917"
            },
          ]
        }
      ]
    }
]

We also see a list of Step including their internal states, and the time it was captured. The model that is used and its corresponding temperature are captured in the Step JSON as well.

 "steps": [
        {
          "name": "HelloStep",
          "isActive": false,
          "state": {
            "name": "Jane Smith",
            "_saveOn": {
              "$date": "2025-11-14T22:29:44.805Z"
            }
          },
          "modelName": "gemini-2.0-flash",
          "temperature": -1
        },
        {
          "name": "EndStep",
          "isActive": true,
          "state": {},
          "modelName": "gemini-2.5-flash",
          "temperature": -1
        }
      ]

If there are any warnings or errors during the LLM execution, they will be captured as well.

session document from previous run:

{
  "_id": {
    "$oid": "6917ad4ac3d31db001ec2393"
  },
  "id": "6917ad4ac3d31db001ec2393",
  "version": 1,
  "runStatus": "completed",
  "createdOn": {
    "$date": "2025-11-14T22:29:30.648Z"
  },
  "saveOn": {
    "$date": "2025-11-14T22:29:45.799Z"
  },
  "expireAfter": 50000,
  "tokens": {
    "inputTokens": 451,
    "outputTokens": 47,
    "totalTokens": 617
  },
  "flows": [
    {
      "name": "TutorialFlow",
      "memory": [
        {
          "nameSpace": "default",
          "history": [
            {
              "type": "system",
              "content": "Tell user the chat has ended. Do you engage in further conversation",
              "id": "EndStep|2025-11-14T22:29:44.816Z|8871362917"
            },
            {
              "type": "human",
              "content": "Hi",
              "id": "HelloStep|2025-11-14T22:29:30.660Z|7849520331",
              "additional_kwargs": {
                "direct": false
              }
            },
            {
              "type": "ai",
              "content": "Hello! What's your name?\n",
              "id": "HelloStep|2025-11-14T22:29:31.215Z|4113612023"
            },
            {
              "type": "human",
              "content": "John Doe",
              "id": "HelloStep|2025-11-14T22:29:36.697Z|9008845602",
              "additional_kwargs": {
                "direct": false
              }
            },
            {
              "type": "ai",
              "content": "",
              "id": "HelloStep|2025-11-14T22:29:37.260Z|9083744487",
              "tool_calls": [
                {
                  "name": "capture_name",
                  "args": {
                    "name": "John Doe"
                  },
                  "id": "38a3ff8e-4a0d-4c65-872a-f5df355a892e"
                }
              ]
            },
            {
              "type": "tool",
              "content": "Cannot accept John Doe, please choose a different name.",
              "id": "HelloStep|2025-11-14T22:29:37.261Z|9187809032",
              "additional_kwargs": {
                "stopTool": true
              },
              "tool_call_id": "38a3ff8e-4a0d-4c65-872a-f5df355a892e",
              "status": "error",
              "name": "capture_name"
            },
            {
              "type": "ai",
              "content": "Sorry, I can't accept that name. Please provide me with a different name.\n",
              "id": "HelloStep|2025-11-14T22:29:37.814Z|7876546485"
            },
            {
              "type": "human",
              "content": "Jane Smith",
              "id": "HelloStep|2025-11-14T22:29:44.213Z|2235981190",
              "additional_kwargs": {
                "direct": false
              }
            },
            {
              "type": "ai",
              "content": "",
              "id": "HelloStep|2025-11-14T22:29:44.804Z|4823980136",
              "tool_calls": [
                {
                  "name": "capture_name",
                  "args": {
                    "name": "Jane Smith"
                  },
                  "id": "8f300d45-11d6-437a-9720-e9607d4acfc3"
                }
              ]
            },
            {
              "type": "tool",
              "content": "input validated",
              "id": "HelloStep|2025-11-14T22:29:44.805Z|3176329009",
              "additional_kwargs": {
                "stopTool": true
              },
              "tool_call_id": "8f300d45-11d6-437a-9720-e9607d4acfc3",
              "status": "success",
              "name": "capture_name"
            },
            {
              "type": "human",
              "content": "I'm done with chat",
              "id": "EndStep|2025-11-14T22:29:44.816Z|1996005382",
              "additional_kwargs": {
                "direct": false
              }
            },
            {
              "type": "ai",
              "content": "Okay, this chat has ended.",
              "id": "EndStep|2025-11-14T22:29:45.798Z|6379701249"
            }
          ]
        }
      ],
      "steps": [
        {
          "name": "HelloStep",
          "isActive": false,
          "state": {
            "name": "Jane Smith",
            "_saveOn": {
              "$date": "2025-11-14T22:29:44.805Z"
            }
          },
          "modelName": "gemini-2.0-flash",
          "temperature": -1
        },
        {
          "name": "EndStep",
          "isActive": true,
          "state": {},
          "modelName": "gemini-2.5-flash",
          "temperature": -1
        }
      ],
      "context": {
        "config": null
      },
      "temperature": -1
    }
  ],
  "log": [],
  "error": [],
  "warn": [],
  "debug": [],
  "verbose": []
}

Wrapping up

This is only a brief introduction to the session document. There are many more advanced features and details that we’ll cover in a later lesson.