Chat, memory and databases
Conversation management, NovaOS Memory (and why apps keep their own), app databases with org isolation, and where state may live.
Conversations
- Platform store:
GET /api/v1/conversations(filterinstance_id,statusactive|archived|deleted),GET /conversations/{id},GET /conversations/{id}/messages,PATCH /conversations/{id}(title,context_summary,token_budget,context_strategy). Tools:novaos_conversations,novaos_conversation_get,novaos_conversation_update. - Limitation: assistant messages hold only the first stream frame of each reply; service accounts cannot list conversations.
- Pattern that works: the app owns sessions/messages/runs/events in its DB; each run input carries recent history (e.g. last 20-40 turns) plus a rolling summary; the agent is stateless. Never pass your thread id as the NovaOS
conversation_id. - One answer per client message: unique (session, role, client_message_id); a second tab waits for the first; the turn keeps running and saves even if the browser leaves.
- Serialize turns on the same thread (advisory lock), else concurrent pods answer out of order.
NovaOS Memory
API (inside a run, execution token only): MemoryClient / ctx.tools.memory write/query/update/forget/hint/assemble_context; scopes user | agent | run | task | conversation | tenant; agents cannot write user; tenant is admin-only; quotas ~1000/user, 500/agent, 5000/tenant (QUOTA_EXCEEDED -> NovaOSQuotaExceededError).
Findings from production review (why newer apps keep memory themselves):
- M1 no memory types beyond scope; M2
token_budget/latency_budget_msaccepted but ignored; M3 corrected facts are added next to old ones (no update/retire); M4 tag/date filters ignored (only classification applies, filters after vector top-k); M5 several correctness bugs (e.g. conversation_id dropped by assemble); M6 fact extraction on gpt-4o-mini and embeddings outside the gateway. - Declaring
memoryinpermissions.toolsmakes SDK 2.x call Memory before EVERY turn: remove it unless used. - Memory accepts only the RS256 execution token (not SA/Logto tokens). Writes from the agent door to user scope are refused. Recommendation: app-owned memory (episodic window + rolling summary + semantic facts keyed by stable ids, with remember/forget/purge), NovaOS Memory off; revisit when M3/M5 are fixed.
Databases
- Agent pods have no database and a read-only filesystem (only /tmp). Give agents data through read-named MCP tools backed by your app backend ("agent-tools" deployment, separate from the UI so agent load does not slow the UI).
- Tenancy that held up:
org_idon every tenant row; org taken only from a validated token (client headers may only repeat it); Postgres RLS:
ALTER TABLE t ENABLE ROW LEVEL SECURITY; ALTER TABLE t FORCE ROW LEVEL SECURITY;
CREATE POLICY org_isolation ON t USING (org_id = current_setting('app.tenant_id', true))
WITH CHECK (org_id = current_setting('app.tenant_id', true));
per transaction: SELECT set_config('role','app_tenant',true), set_config('app.tenant_id', :org, true) (superusers bypass RLS even with FORCE, so switch to a NOLOGIN role). Another org's row should answer 404, not 403. Raw SQL from agents: typed reads only, never accept SQL from the model.
- Writes from USER runs come back as returned writes and are applied by the backend under the user's org, idempotently (dedupe by hash).
- LangGraph-style checkpoints/stores in the backend: thread key
"{org}:{thread}", namespaces prefixed by org.