NovaOS MCP
Field guide

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 (filter instance_id, status active|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_ms accepted 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 memory in permissions.tools makes 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_id on 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.