JsonDb

Store sessions, memories, metrics, knowledge, evals, and traces in local JSON files.

JsonDb is a class that implements the Db interface using JSON files as the backend storage system. It provides simple, file-based storage with each table stored as a separate JSON file.

ParameterTypeDefaultDescription
idOptional[str]-Database ID. Derived deterministically from database path when omitted.
db_pathOptional[str]-Path to the directory where JSON files will be stored.
session_tableOptional[str]-Name of the JSON file to store sessions (without .json extension).
runs_tableOptional[str]NoneStorage name for individual runs. Defaults to agno_runs, or <session_table>_runs when a custom session name is supplied.
memory_tableOptional[str]-Name of the JSON file to store memories.
metrics_tableOptional[str]-Name of the JSON file to store metrics.
eval_tableOptional[str]-Name of the JSON file to store evaluation runs.
knowledge_tableOptional[str]-Name of the JSON file to store knowledge content.
traces_tableOptional[str]-Name of the JSON file to store traces.
spans_tableOptional[str]-Name of the JSON file to store spans.

Methods

upsert_sessions

Upsert multiple sessions in one method call.

Parameters:

  • sessions (List[Session]): List of sessions to upsert
  • deserialize (Optional[bool]): Whether to deserialize the sessions. Defaults to True
  • preserve_updated_at (bool): Request preservation of the sessions' existing updated_at timestamps; see adapter limitations below. Defaults to False

Returns: List[Union[Session, Dict[str, Any]]]

upsert_memories

Upsert multiple memories in one method call.

Parameters:

  • memories (List[UserMemory]): List of memories to upsert
  • deserialize (Optional[bool]): Whether to deserialize the memories. Defaults to True
  • preserve_updated_at (bool): Request preservation of the memories' existing updated_at timestamps; see adapter limitations below. Defaults to False

Returns: List[Union[UserMemory, Dict[str, Any]]]

Timestamp preservation by adapter

JsonDb, GcsJsonDb, FirestoreDb, RedisDb, DynamoDb, and InMemoryDb accept preserve_updated_at but do not forward it to their individual upserts. Their bulk methods replace timestamps even when it is True.

PostgresDb, SingleStoreDb, and ValkeyDb honor the flag. MySQLDb, SqliteDb, and MongoDb honor it on their optimized bulk path; their per-record fallback paths do not forward it. Verify timestamps when a migration depends on preserving them.

In the current implementation, JsonDb.upsert_sessions() and JsonDb.upsert_memories() declare preserve_updated_at, but the JSON backend does not forward it to individual upserts. JsonDb does not preserve supplied updated_at values when this argument is True.