Add PostgreSQLFileStore — persistent EventLog for ephemeral deployments

[StatPan]

In environments like Cloud Run or containers without persistent volumes, LocalFileStore either fails or falls back to InMemoryFileStore, which means the full EventLog (including tool_call/tool_result events) is lost between requests. This makes proper multi-turn resume impossible.

Proposal: add PostgreSQLFileStore as an optional FileStore backend (pip install openhands-sdk[postgresql]) that persists the EventLog to a PostgreSQL table, namespaced by conversation ID. Locking uses pg_try_advisory_lock so it's safe across multiple processes/instances.

store = PostgreSQLFileStore(dsn=..., namespace=str(conversation_id))
conv = LocalConversation(agent=agent, workspace=workspace, file_store=store)

Happy to open a PR if this direction looks reasonable.

[VascoSch92]

Hey @StatPan

Thanks for filing this

A few thoughts:

1. Surface the silent fallback first. state.py:307-311 silently constructs InMemoryFileStore when persistence_dir isn't provided, with no log. I think that's the actual root cause of the confusion, i.e., users deploy to Cloud Run expecting persistence and get in-memory storage with no warning. A one-line logger.warning here would make the misconfiguration obvious and probably changes what backend people reach for.
2. An EventLog isn't really a file tree. Before we grow more backends behind FileStore, it may be worth asking whether a dedicated EventStore interface with append-only semantics fits better. That affects what the "right" backend even looks like.
3. A Postgres backend is genuinely useful and I don't want to block it, I just think the best home is as a community extra / contrib package rather than core. That lets you ship without waiting on maintainer bandwidth, and it avoids pulling core into N-database-driver territory (same argument will come for MySQL, DynamoDB, Redis, etc.).

Would you like to open a PR for the first point?
I'd be happy to review it.

[StatPan]

Hey @VascoSch92, thanks for the thoughtful response — sorry for the late reply on this issue. I had already jumped ahead and opened #2902 before seeing your comment, and it's been through a round of review with fixes applied.

Some context on where I'm coming from: I'm running agents on Cloud Run with Cloud SQL, so there's no persistent volume for LocalFileStore. That's what motivated the PostgreSQL backend.

That said, I understand the FileStore abstraction was designed around file-system semantics, and bolting a database onto it may not be the right fit for core. I respect that — happy to move it to a contrib/community package if that's the preferred direction.

On point 2 (EventStore) — I'm really curious about this one. Could you elaborate on what you have in mind? Something like an append-only interface with different semantics than read/write/list/delete? I think that could change what the "right" backend looks like, as you said.

And yes, the silent fallback warning is a great standalone improvement — I'll open a separate PR for that.

[VascoSch92]

On point 2 (EventStore) — I'm really curious about this one. Could you elaborate on what you have in mind? Something like an append-only interface with different semantics than read/write/list/delete? I think that could change what the "right" backend looks like, as you said.

Actually, I have nothing in mind. I was just thinking loud. :-)

And yes, the silent fallback warning is a great standalone improvement — I'll open a separate PR for that.

Please do that.