feat(chat-history): server-side chat history with tombstones (follow-up to #9902) (#12663)

* feat(schema): add Conversation schema for chat history (#9432)

Persist WebUI chat conversations server-side so browser refresh, private
windows, or device changes preserve user history (issue #9432). This
commit adds the on-disk representation:

- Conversation holds id, name, model, opaque history, MCP / sampling
  settings, and timestamps.
- ConversationsFile is the per-user list serialised to JSON.

History is stored as json.RawMessage so the server stays agnostic to
React message shapes (user / assistant / thinking / tool_call /
tool_result mixed with text / image_url / audio_url / file attachments).

Assisted-by: Claude:claude-opus-4-7

Signed-off-by: TLoE419 <tloemizuchizu@gmail.com>

* feat(chathistory): add file-based per-user conversation store (#9432)

File-backed persister for chat history. Each user's conversations live
under {baseDir}/{userID}/conversations.json (anonymous/ when auth is
disabled).

Design choices:
- In-memory cache backed by sync.Mutex so concurrent saves don't
  interleave writes.
- Atomic write via tmp file + os.Rename so a crash mid-save never
  leaves a corrupted history.
- ID validation regex blocks path-traversal payloads at the store
  boundary, in addition to the auth context constraint.

Tests cover round-trip persistence across instances, user isolation,
unsafe-ID rejection, bulk replace migration, and the anonymous fallback
path.

Assisted-by: Claude:claude-opus-4-7

Signed-off-by: TLoE419 <tloemizuchizu@gmail.com>

* feat(api): expose chat conversation CRUD endpoints (#9432)

Wire the chathistory store into the HTTP layer. New endpoints under
/api/conversations:

- GET    /api/conversations        list
- POST   /api/conversations        upsert (id in body)
- DELETE /api/conversations        delete all
- PUT    /api/conversations/bulk   replace entire set (localStorage migration)
- GET    /api/conversations/:id    fetch one
- PUT    /api/conversations/:id    upsert (id in path; path id wins over body)
- DELETE /api/conversations/:id    delete one

All endpoints scope queries to the authenticated user via getUserID(c)
- callers cannot impersonate other users by passing a user_id in the
body. The endpoints are gated behind the new chat_history feature
permission (default ON in APIFeatures), registered through the existing
RouteFeatureRegistry so the unified feature middleware picks them up
automatically.

Application.ChatHistoryStore() returns nil when DisableWebUI is set or
no persistence path is configured, in which case route registration is
skipped entirely rather than registering handlers that always 503.

Also adds the chat-history instruction entry and Swagger tag so the
endpoint surfaces in /api/instructions and /swagger.

Assisted-by: Claude:claude-opus-4-7

Signed-off-by: TLoE419 <tloemizuchizu@gmail.com>

* feat(react-ui): sync chat history to server with localStorage fallback (#9432)

useChat now probes /api/conversations on mount. When the endpoint
responds 200, the server becomes the authoritative source: the hook
merges remote conversations into local state and pushes per-chat PUT
updates on each debounced save. When the endpoint 404s - older LocalAI
deploys or the feature disabled - the hook silently keeps the old
localStorage-only behaviour, so the change is backward-compatible.

Migration: when the server is reachable but empty and the browser has
local conversations with history, the hook fires a single
PUT /api/conversations/bulk to seed the server. The atomic bulk endpoint
avoids partial-upload states where a retry would skip already-uploaded
entries.

Delete operations propagate to the server when it's available; failures
are silently swallowed so the local UI stays responsive on transient
network errors.

Assisted-by: Claude:claude-opus-4-7

Signed-off-by: TLoE419 <tloemizuchizu@gmail.com>

* test(chathistory): rewrite tests in Ginkgo/Gomega

The initial test file used the stdlib testing package (t.Fatalf /
t.Errorf), which is forbidden by the forbidigo linter rule in
.golangci.yml — LocalAI mandates Ginkgo/Gomega for all Go tests (see
.agents/coding-style.md).

Restructured the same six scenarios into Describe / Context / It blocks,
with a chathistory_suite_test.go bootstrap that registers the Ginkgo
fail handler. Test coverage is unchanged: basic CRUD round-trip, cross-
instance persistence, user isolation, unsafe ID rejection (now via
DescribeTable), bulk replace overwrite, and the anonymous fallback
path.

Assisted-by: Claude:claude-opus-4-7

Signed-off-by: TLoE419 <tloemizuchizu@gmail.com>

* refactor(chathistory): switch store to GORM-backed authDB

Addresses mudler's review on #9902. Chat history was the only per-user
state in LocalAI sitting in a separate filesystem store instead of the
shared GORM database — AgentStore and JobStore both live there. Move
it onto Application.authDB so per-user state stays in one place.

* ConversationRecord (GORM model) with composite primary key
  (user_id, conv_id) — React mints IDs locally with no global
  coordination so per-user uniqueness is the natural shape.
* Store.New(db *gorm.DB) replaces Store.New(baseDir string).
  Save / Get / List / Delete / DeleteAll / ReplaceAll keep their
  signatures so HTTP handlers and the React UI are untouched.
* ReplaceAll runs in a transaction with an Unscoped() pre-clear so a
  future retention sweep cannot resurrect a stale ID on re-upload.
* gorm.DeletedAt in the schema means a future retention pruner is a
  one-line query — addresses the second half of the review (unbounded
  in-memory map). The map is gone: reads go straight to the DB.

Trade-off worth flagging in the PR reply: chat history persistence
now requires auth.Enabled = true (that's what initialises
Application.authDB). With auth disabled the React UI transparently
falls back to localStorage, the same path the original PR took on
404. Consistent with AgentStore / JobStore; if a "chat history
always on" mode is preferred we can pull DB init out of auth.InitDB
into a shared helper.

Assisted-by: Claude:claude-opus-4-7 [Read Edit Bash]
Signed-off-by: TLoE419 <tloemizuchizu@gmail.com>

* refactor(schema): drop now-unused ConversationsFile envelope

ConversationsFile was the JSON wrapper for the old file-based chat
history store — a {Conversations: [...], UpdatedAt: ...} pair
serialised to disk under {baseDir}/{userID}/conversations.json. The
previous commit replaced that store with a GORM-backed one that
writes rows directly as ConversationRecord, leaving the envelope
without a consumer.

Assisted-by: Claude:claude-opus-4-7 [Read Edit Bash]
Signed-off-by: TLoE419 <tloemizuchizu@gmail.com>

* test(chathistory): switch tests to testutil.SetupTestDB

Mirror the AgentStore test setup: spin up a PostgreSQL 16 container
via testutil.SetupTestDB(), construct a Store on top of it, exercise
CRUD round-trips. The previous file-based fixtures (TempDir,
filepath.Join checks) are no longer meaningful now that the store
talks GORM.

Tests are skipped on macOS (testcontainers needs Docker) and run on
CI, same as the other GORM-backed suites in the repo.

Also reframed two cases:
* "unsafe IDs" → "malformed IDs" — the DB-backed store doesn't care
  about path traversal, but idRegex still rejects whitespace /
  control characters so IDs stay safe in logs and HTTP responses.
* "anonymous user" no longer pins a directory path (no directory
  exists anymore); instead it checks the round-trip plus the
  per-user isolation guarantee.

Added a DeleteAll round-trip to cover the bulk-clear endpoint.

Assisted-by: Claude:claude-opus-4-7 [Read Edit Bash]
Signed-off-by: TLoE419 <tloemizuchizu@gmail.com>

* test(chathistory): cover the conversation HTTP handlers

The seven /api/conversations handlers had no tests. Inject the
*chathistory.Store into the handlers instead of the whole Application and
move the route table into RegisterChatHistoryRoutes, so a spec can drive
the real registration and middleware chain (auth.Middleware plus the
chat_history feature gate) against an in-memory SQLite auth database.

The new specs cover 401 without credentials on every route, 403 when an
admin revoked chat_history, the CRUD round trip, path id over body id,
400 on malformed ids and bodies, per-user isolation, bulk replace and
delete-all, and that a nil store registers nothing (the UI then falls
back to localStorage).

The handlers' nil-store branches are gone: the routes are only
registered with a store, so those branches could never run.

Assisted-by: Claude Code:claude-opus-5-5
Signed-off-by: Stefan Walcz <stefan.walcz@walcz.de>

* fix(chathistory): make deletions final with tombstones and versions

A conversation deleted on one device came back as soon as a client with
a stale copy wrote it again: Delete soft-deleted the row, and the next
Save went through GORM's upsert, which cleared deleted_at and resurrected
it for every device. The lookup that recovered CreatedAt also ran outside
any transaction, so concurrent writers raced on it.

The server is now authoritative over deletions:

* Delete turns the row into a tombstone: content dropped, deleted_at
  set. It is idempotent, and deleting an id the server has not seen yet
  still records a tombstone, so a delete that overtakes the UI's
  in-flight debounced save of the same chat still wins.
* Save runs in a transaction, refuses a tombstoned id with ErrDeleted
  (HTTP 410 Gone), and bumps the version with a single
  UPDATE ... SET version = version + 1 guarded by deleted_at IS NULL,
  so concurrent writers each count and a delete committed between the
  lookup and the write still wins. Two concurrent first writes of the
  same id retry once (ON CONFLICT DO NOTHING, then update).
* Every row carries a server-assigned version (1 on the first save,
  +1 per write including the delete), returned to the client. A non-zero
  version tells the UI the server has seen a conversation, which is how
  it can tell a never-synced draft from a server-side deletion.
* GET /api/conversations returns the tombstones under "deleted".
* DeleteAll and ReplaceAll leave tombstones too. ReplaceAll no longer
  hard-deletes everything first; it upserts the payload, skips ids that
  were deleted (reported in "skipped"), and tombstones the rest.
* createdAt/updatedAt are stored as the client sends them (only zero
  values are stamped), so clients compare updatedAt from their own
  clocks rather than against the server's.

The store specs now run against PostgreSQL (testcontainers) and, with
the auth tag, SQLite through auth.InitDB, since both back the auth
database. The API specs cover a stale client reconnecting after a remote
deletion. Swagger is regenerated with swag v1.16.6 (json.RawMessage
fields get swaggertype), and the feature is documented, including that
it needs user auth.

Assisted-by: Claude Code:claude-opus-5-5
Signed-off-by: Stefan Walcz <stefan.walcz@walcz.de>

* fix(react-ui): let the server decide which chats were deleted

mergeRemoteAndLocal kept every chat that was only in the browser and
let the server copy win for every shared id. A stale browser therefore
uploaded chats deleted on another device as if they were new drafts,
and a message sent while the list request was still in flight was
replaced by the older server copy and then lost from localStorage too.

The first load now reconciles with the server's tombstones and versions:

* a chat the server lists under "deleted" is dropped locally;
* a chat on both sides keeps the copy with the newer updatedAt, so an
  edit made during the load wins and is uploaded afterwards;
* a chat only in the browser is uploaded only if it was never synced
  (no version). With a version the server has seen it and no longer
  has it, so it is dropped instead of resurrected (this also keeps one
  account's cached chats out of another account on a shared browser);
* deletes made while the list is loading are queued and sent once it
  arrives.

Saves record the version the server returns, and a 410 on save drops
the chat locally instead of retrying it forever. Chats received from
the server count as already sent, so adopting a server copy no longer
echoes it straight back. The bulk localStorage migration is gone: it
replaced the whole server set from a possibly stale browser, and the
per-chat saves already upload never-synced drafts through the tombstone
check.

The Playwright spec drives each case against a stubbed
/api/conversations that follows the server contract.

Assisted-by: Claude Code:claude-opus-5-5
Signed-off-by: Stefan Walcz <stefan.walcz@walcz.de>

* fix(chathistory): keep the LocalAI Assistant toggle on synced chats

master's createNewChat sets localaiAssistant, but serializeChat did not
send it and schema.Conversation had no field for it, so a chat with the
Assistant mode on came back with it off after a reload from the server
(and the local cache dropped it too). Add the field on both sides. The
other fields createNewChat sets were already covered; a handler spec now
round-trips all of them, and the UI spec checks the toggle on the way up
and in the local cache.

Assisted-by: Claude Code:claude-opus-5-5
Signed-off-by: Stefan Walcz <stefan.walcz@walcz.de>

* fix(react-ui): scope chat cache per account, retry unconfirmed deletes

Two gaps in the client half of server-side chat history, both found in
review:

The browser cache was one shared localStorage key. A draft that one
account could not upload (a failed first save) stayed in it, and after
that account signed out and another signed in, the reconcile kept the
unversioned draft and the save pass uploaded it into the second
account. The cache now lives under localai_chats_data:<user id>, Chat
remounts its state when the account changes, and nothing is synced
without a signed-in account. The shared key is left for browser-only
use without auth and is not uploaded when signed in, because nothing
tells which account it belongs to.

Deletes were dropped locally and their DELETE errors swallowed; only
deletes made while the first list was loading were queued, and not
persisted. A delete made while the server was unreachable therefore
came back with the next list. Deletes (single, delete all, and deletes
on the Home page) are now kept as pending deletes in the account's
cache until the server confirms them, override the server list in the
reconcile, and are sent again on the next change, on the online event
and on the next load. While a delete-all is pending no conversation is
uploaded, so a chat started after it is not caught by it.

The Playwright specs replay both review scenarios (account switch after
a failed first save; delete and delete-all while offline) with
counter-checks that the same account keeps and uploads its own draft
and that a confirmed delete is neither re-sent nor resurrected.

Assisted-by: Claude Code:claude-opus-5-5
Signed-off-by: Stefan Walcz <stefan.walcz@walcz.de>

* fix(react-ui): persist cleared chats immediately

Navigation cancels the debounced cache write and can restore unsynced
chats after Clear all. Save the cleared list with its pending deletion
before returning, and cover immediate navigation in the browser spec.

Assisted-by: Codex:GPT-6
Signed-off-by: Stefan Walcz <stefan.walcz@walcz.de>

* test(react-ui): make the chat history sync specs deterministic

- "clear all persists before navigation" opened a single chat, and the menu
  offers no Clear all for one chat, so the spec timed out in every run. It
  now opens two unsynced chats and checks that neither survives. Reverting
  03cd9c115's save in clearAllChats turns it red again.
- "a delete the server confirmed is not sent again" reopened the page as
  soon as the server had the request, before the page had the answer; the
  unconfirmed delete was then rightly sent again (4 of 5 runs). It now waits
  until the cache holds no pending delete.

Docs-Not-Needed: test-only change.

Assisted-by: Claude Code:claude-opus-5-5
Signed-off-by: Stefan Walcz <stefan.walcz@walcz.de>

* fix(chathistory): keep the chat's reasoning effort on the server

reasoningEffort (#12700, #12716) is part of the chat the UI syncs since the
master merge, but schema.Conversation had no field for it, so the server
dropped it and a reload from the server reset the setting. Add the field.

The handler spec that round-trips every chat field now includes
reasoningEffort. A schema test reads serializeChat in useChat.js and fails
for any key the UI sends that schema.Conversation cannot hold, so the next
such drift shows up as a failing test rather than in review (it reports
reasoningEffort on the previous head). Swagger and docs updated.

Assisted-by: Claude Code:claude-opus-5-5
Signed-off-by: Stefan Walcz <stefan.walcz@walcz.de>

* test(chat): use Ginkgo for the schema drift guard

The new drift guard uses testing methods forbidden by repository lint.
Keep its field coverage and fail-fast parser checks in Ginkgo/Gomega.

Assisted-by: nib:gpt-6.1-sol

---------

Signed-off-by: TLoE419 <tloemizuchizu@gmail.com>
Signed-off-by: Stefan Walcz <stefan.walcz@walcz.de>
Co-authored-by: TLoE419 <tloemizuchizu@gmail.com>
Co-authored-by: localai-org-maint-bot <306269227+localai-org-maint-bot@users.noreply.github.com>
Co-authored-by: mudler-agent <mudler-bot@c3os.io>

core/application/application.go

@@ -15,6 +15,7 @@ import (
 	mcpTools "github.com/mudler/LocalAI/core/http/endpoints/mcp"
 	"github.com/mudler/LocalAI/core/services/advisorylock"
 	"github.com/mudler/LocalAI/core/services/agentpool"
+	"github.com/mudler/LocalAI/core/services/chathistory"
 	"github.com/mudler/LocalAI/core/services/cloudproxy/mitm"
 	"github.com/mudler/LocalAI/core/services/facerecognition"
 	"github.com/mudler/LocalAI/core/services/failover"
@@ -69,6 +70,7 @@ type Application struct {
 	faceRegistry         facerecognition.Registry
 	voiceRegistry        voicerecognition.Registry
 	voiceProfileStore    *voiceprofile.Store
+	chatHistoryStore     *chathistory.Store
 	authDB               *gorm.DB
 	metricsService       *monitoring.LocalAIMetricsService
 	statsRecorder        *billing.Recorder
@@ -291,6 +293,13 @@ func (a *Application) VoiceProfileStore() *voiceprofile.Store {
 	return a.voiceProfileStore
 }
 
+// ChatHistoryStore returns the server-side WebUI chat history store, or nil
+// when the feature is disabled (LOCALAI_DISABLE_WEBUI=true or persistence
+// path could not be resolved).
+func (a *Application) ChatHistoryStore() *chathistory.Store {
+	return a.chatHistoryStore
+}
+
 // AuthDB returns the auth database connection, or nil if auth is not enabled.
 func (a *Application) AuthDB() *gorm.DB {
 	return a.authDB
@@ -667,6 +676,21 @@ func (a *Application) start() error {
 
 	a.agentJobService = agentJobService
 
+	// Initialize chat history store for the WebUI (issue #9432). Reuses the
+	// shared auth database so per-user chat history sits alongside agent
+	// configs and jobs in one place — mudler's review on #9902 called out
+	// the file-based store as inconsistent with the rest of LocalAI's
+	// per-user state. When auth is disabled the store stays nil and the
+	// React UI falls back to localStorage.
+	if !a.applicationConfig.DisableWebUI && a.authDB != nil {
+		store, err := chathistory.New(a.authDB)
+		if err != nil {
+			xlog.Warn("Chat history persistence disabled: failed to initialise store", "error", err)
+		} else {
+			a.chatHistoryStore = store
+		}
+	}
+
 	return nil
 }
 

core/http/app.go

@@ -193,6 +193,8 @@ func setModelLoadingRetryAfter(loadErr *nodes.ModelLoadingError, c echo.Context)
 // @tag.description Document reranking
 // @tag.name instructions
 // @tag.description API instruction discovery — browse instruction areas and get endpoint guides
+// @tag.name chat-history
+// @tag.description Server-side persistence of WebUI chat conversations
 
 func API(application *application.Application) (*echo.Echo, error) {
 	e := echo.New()
@@ -512,7 +514,8 @@ func API(application *application.Application) (*echo.Echo, error) {
 	}
 
 	mcpMw := auth.RequireFeature(application.AuthDB(), auth.FeatureMCP)
-	routes.RegisterLocalAIRoutes(e, requestExtractor, application.ModelConfigLoader(), application.ModelLoader(), application.ApplicationConfig(), application.GalleryService(), opcache, application.TemplatesEvaluator(), application, adminMiddleware, mcpJobsMw, mcpMw)
+	chatHistoryMw := auth.RequireFeature(application.AuthDB(), auth.FeatureChatHistory)
+	routes.RegisterLocalAIRoutes(e, requestExtractor, application.ModelConfigLoader(), application.ModelLoader(), application.ApplicationConfig(), application.GalleryService(), opcache, application.TemplatesEvaluator(), application, adminMiddleware, mcpJobsMw, mcpMw, chatHistoryMw)
 	routes.RegisterAgentPoolRoutes(e, application, agentsMw, skillsMw, collectionsMw)
 	// Fine-tuning routes
 	fineTuningMw := auth.RequireFeature(application.AuthDB(), auth.FeatureFineTuning)

core/http/auth/features.go

@@ -158,6 +158,15 @@ var RouteFeatureRegistry = []RouteFeature{
 	{"POST", "/api/pii/analyze", FeaturePIIFilter},
 	{"POST", "/api/pii/redact", FeaturePIIFilter},
 
+	// Chat History (server-side persistence of WebUI conversations, #9432)
+	{"GET", "/api/conversations", FeatureChatHistory},
+	{"DELETE", "/api/conversations", FeatureChatHistory},
+	{"POST", "/api/conversations", FeatureChatHistory},
+	{"PUT", "/api/conversations/bulk", FeatureChatHistory},
+	{"GET", "/api/conversations/:id", FeatureChatHistory},
+	{"PUT", "/api/conversations/:id", FeatureChatHistory},
+	{"DELETE", "/api/conversations/:id", FeatureChatHistory},
+
 	// Quantization
 	{"POST", "/api/quantization/jobs", FeatureQuantization},
 	{"GET", "/api/quantization/jobs", FeatureQuantization},
@@ -222,5 +231,6 @@ func APIFeatureMetas() []FeatureMeta {
 		{FeatureAudioTransform, "Audio Transform", true},
 		{FeaturePIIFilter, "PII Analyze / Redact", true},
 		{FeatureDecisions, "Decisions", true},
+		{FeatureChatHistory, "Chat History", true},
 	}
 }

core/http/auth/permissions.go

@@ -64,7 +64,8 @@ const (
 	// FeaturePIIFilter gates the synchronous PII analyze/redact service
 	// (POST /api/pii/{analyze,redact}). Default ON like the other API
 	// features; the admin-only events log is gated separately in-handler.
-	FeaturePIIFilter = "pii_filter"
+	FeaturePIIFilter   = "pii_filter"
+	FeatureChatHistory = "chat_history"
 )
 
 // AgentFeatures lists agent-related features (default OFF).
@@ -81,6 +82,7 @@ var APIFeatures = []string{
 	FeatureRealtime, FeatureModeration, FeatureRerank, FeatureTokenize, FeatureMCP, FeatureStores,
 	FeatureFaceRecognition, FeatureVoiceRecognition, FeatureAudioTransform,
 	FeaturePIIFilter, FeatureDecisions,
+	FeatureChatHistory,
 }
 
 // AllFeatures lists all known features (used by UI and validation).

core/http/endpoints/localai/api_instructions.go

@@ -149,6 +149,12 @@ var instructionDefs = []instructionDef{
 		Tags:        []string{"router"},
 		Intro:       "Add a `router:` block to a ModelConfig to turn it into a routing model. The block declares a classifier (`score` — a small model ranks each policy label, Arch-Router-style; `colbert` — a reranker scores policy descriptions against the prompt; `knn` — similarity-weighted vote over a curated corpus of labelled example prompts), `policies` (the label vocabulary), `candidates` (downstream model + labels it serves; first candidate whose labels cover the active set wins, so order small → large), and a `fallback`. The knn classifier needs a `knn: { embedding_model }` block instead of a classifier_model, and reads a persisted corpus seeded via POST /api/router/{name}/corpus with `{entries: [{text, labels}]}` (admin-only; texts are embedded server-side, persisted under the state dir, and NEVER returned by any endpoint — GET /api/router/{name}/corpus/stats reports label counts only, DELETE /api/router/{name}/corpus wipes it). knn routes to the fallback whenever the prompt is less similar than knn.similarity_threshold to every corpus entry — out-of-corpus prompts are treated as undecidable rather than guessed. When a client addresses the routing model, the RouteModel middleware invokes the classifier, picks a candidate, and rewrites input.Model — the standard model-resolution path then runs ACL, disabled-state, and per-model PII against the chosen target. Depth-1 invariant: candidates must NOT themselves carry a `router:` block; runtime check returns 500 on violation. Decisions are logged to GET /api/router/decisions and surfaced in the /app/middleware Routing tab. POST /api/router/decide is the programmatic decision-oracle: external routers (e.g. an organisation-wide router service) send `{router, input}` and receive the classifier's label set + candidate model WITHOUT LocalAI rewriting, forwarding, or recording the call. Shares the classifier cache with the in-band path so warm-up costs are paid once.",
 	},
+	{
+		Name:        "chat-history",
+		Description: "Server-side persistence of WebUI chat conversations",
+		Tags:        []string{"chat-history"},
+		Intro:       "Per-user CRUD over chat conversations; only registered when user auth is enabled, and gated by the `chat_history` feature. POST /api/conversations and PUT /api/conversations/{id} upsert and return the conversation with a server-assigned `version` (1 on the first save, +1 per write). createdAt/updatedAt are client Unix milliseconds stored as sent, so clients compare updatedAt to pick the newer copy. Deletes are final: DELETE leaves a tombstone (idempotent, also for ids never saved), any later write of that id returns 410 Gone, and GET /api/conversations returns tombstones under `deleted` so a client drops stale local copies instead of re-uploading them. PUT /api/conversations/bulk makes the payload the live set (others are tombstoned) and reports refused deleted ids in `skipped`.",
+	},
 }
 
 // swaggerState holds parsed swagger spec data, initialised once.

core/http/endpoints/localai/api_instructions_test.go

@@ -39,7 +39,7 @@ var _ = Describe("API Instructions Endpoints", func() {
 
 			instructions, ok := resp["instructions"].([]any)
 			Expect(ok).To(BeTrue())
-			Expect(instructions).To(HaveLen(22))
+			Expect(instructions).To(HaveLen(23))
 
 			// Verify each instruction has required fields and correct URL format
 			for _, s := range instructions {
@@ -83,6 +83,7 @@ var _ = Describe("API Instructions Endpoints", func() {
 				"3d",
 				"failover",
 				"decisions",
+				"chat-history",
 				"motion",
 			))
 		})

core/http/endpoints/localai/chat_history.go

@@ -0,0 +1,189 @@
+package localai
+
+import (
+	"errors"
+	"net/http"
+
+	"github.com/labstack/echo/v4"
+	"github.com/mudler/LocalAI/core/schema"
+	"github.com/mudler/LocalAI/core/services/chathistory"
+)
+
+// chatHistoryError maps store errors onto HTTP status codes. A deleted
+// conversation is 410 Gone, so a client holding a stale copy can tell it
+// apart from a transient failure and drop the copy instead of retrying.
+func chatHistoryError(c echo.Context, err error) error {
+	switch {
+	case errors.Is(err, chathistory.ErrInvalidID), errors.Is(err, chathistory.ErrInvalidUserID):
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+	case errors.Is(err, chathistory.ErrNotFound):
+		return c.JSON(http.StatusNotFound, map[string]string{"error": err.Error()})
+	case errors.Is(err, chathistory.ErrDeleted):
+		return c.JSON(http.StatusGone, map[string]string{"error": err.Error()})
+	case errors.Is(err, chathistory.ErrConflict):
+		return c.JSON(http.StatusConflict, map[string]string{"error": err.Error()})
+	default:
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+}
+
+// ListConversationsEndpoint lists the current user's conversations, plus the
+// ids of conversations the user deleted (tombstones).
+//
+//	@Summary		List chat conversations
+//	@Description	Returns the live conversations, newest first, and in `deleted` the conversations the user deleted. A client must drop any local copy whose id appears in `deleted` instead of uploading it again.
+//	@Tags			chat-history
+//	@Produce		json
+//	@Success		200	{object}	schema.ConversationList
+//	@Router			/api/conversations [get]
+func ListConversationsEndpoint(store *chathistory.Store) echo.HandlerFunc {
+	return func(c echo.Context) error {
+		userID := getUserID(c)
+		convs, err := store.List(userID)
+		if err != nil {
+			return chatHistoryError(c, err)
+		}
+		deleted, err := store.Tombstones(userID)
+		if err != nil {
+			return chatHistoryError(c, err)
+		}
+		return c.JSON(http.StatusOK, schema.ConversationList{Conversations: convs, Deleted: deleted})
+	}
+}
+
+// GetConversationEndpoint returns a single conversation by ID.
+//
+//	@Summary	Get a chat conversation
+//	@Tags		chat-history
+//	@Produce	json
+//	@Param		id	path		string	true	"Conversation ID"
+//	@Success	200	{object}	schema.Conversation
+//	@Failure	404	{object}	map[string]string	"Never existed"
+//	@Failure	410	{object}	map[string]string	"Deleted"
+//	@Router		/api/conversations/{id} [get]
+func GetConversationEndpoint(store *chathistory.Store) echo.HandlerFunc {
+	return func(c echo.Context) error {
+		conv, err := store.Get(getUserID(c), c.Param("id"))
+		if err != nil {
+			return chatHistoryError(c, err)
+		}
+		return c.JSON(http.StatusOK, conv)
+	}
+}
+
+// SaveConversationEndpoint upserts a conversation. The body's id field is the
+// canonical identifier; a path id is also accepted and overrides the body
+// when both are present (so PUT /api/conversations/<id> works as expected).
+//
+//	@Summary		Save a chat conversation (upsert)
+//	@Description	Stores the conversation and returns it with its new server-assigned `version`. `createdAt`/`updatedAt` are kept as sent (Unix ms). Writing a conversation the user deleted returns 410 and does not bring it back.
+//	@Tags			chat-history
+//	@Accept			json
+//	@Produce		json
+//	@Param			body	body		schema.Conversation	true	"Conversation payload"
+//	@Success		200		{object}	schema.Conversation
+//	@Failure		400		{object}	map[string]string	"Invalid id or body"
+//	@Failure		410		{object}	map[string]string	"Deleted"
+//	@Router			/api/conversations [post]
+func SaveConversationEndpoint(store *chathistory.Store) echo.HandlerFunc {
+	return func(c echo.Context) error {
+		var conv schema.Conversation
+		if err := c.Bind(&conv); err != nil {
+			return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+		}
+		if pathID := c.Param("id"); pathID != "" {
+			conv.ID = pathID
+		}
+		saved, err := store.Save(getUserID(c), conv)
+		if err != nil {
+			return chatHistoryError(c, err)
+		}
+		return c.JSON(http.StatusOK, saved)
+	}
+}
+
+// SaveConversationByIDEndpoint is SaveConversationEndpoint under its own
+// name so the PUT route gets its own swagger entry.
+//
+//	@Summary	Save a chat conversation by id (upsert)
+//	@Tags		chat-history
+//	@Accept		json
+//	@Produce	json
+//	@Param		id		path		string				true	"Conversation ID (overrides the body id)"
+//	@Param		body	body		schema.Conversation	true	"Conversation payload"
+//	@Success	200		{object}	schema.Conversation
+//	@Failure	400		{object}	map[string]string	"Invalid id or body"
+//	@Failure	410		{object}	map[string]string	"Deleted"
+//	@Router		/api/conversations/{id} [put]
+func SaveConversationByIDEndpoint(store *chathistory.Store) echo.HandlerFunc {
+	return SaveConversationEndpoint(store)
+}
+
+// BulkReplaceConversationsEndpoint replaces the user's live conversation set
+// in one transaction.
+//
+//	@Summary		Replace all chat conversations
+//	@Description	Upserts every conversation in the payload and deletes the user's other live conversations. Ids the user deleted earlier are not written and are listed in `skipped`.
+//	@Tags			chat-history
+//	@Accept			json
+//	@Produce		json
+//	@Param			body	body		schema.ConversationBulkRequest	true	"Conversations"
+//	@Success		200		{object}	schema.ConversationBulkResponse
+//	@Failure		400		{object}	map[string]string	"Invalid id or body"
+//	@Router			/api/conversations/bulk [put]
+func BulkReplaceConversationsEndpoint(store *chathistory.Store) echo.HandlerFunc {
+	return func(c echo.Context) error {
+		var payload schema.ConversationBulkRequest
+		if err := c.Bind(&payload); err != nil {
+			return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+		}
+		skipped, err := store.ReplaceAll(getUserID(c), payload.Conversations)
+		if err != nil {
+			return chatHistoryError(c, err)
+		}
+		if skipped == nil {
+			skipped = []string{}
+		}
+		return c.JSON(http.StatusOK, schema.ConversationBulkResponse{
+			Status:  "ok",
+			Count:   len(payload.Conversations) - len(skipped),
+			Skipped: skipped,
+		})
+	}
+}
+
+// DeleteConversationEndpoint deletes a single conversation, leaving a
+// tombstone. Idempotent.
+//
+//	@Summary		Delete a chat conversation
+//	@Description	Deletes the conversation and keeps a tombstone so no client can write it back. Deleting an unknown or already deleted id succeeds.
+//	@Tags			chat-history
+//	@Produce		json
+//	@Param			id	path		string	true	"Conversation ID"
+//	@Success		200	{object}	map[string]string
+//	@Failure		400	{object}	map[string]string	"Invalid id"
+//	@Router			/api/conversations/{id} [delete]
+func DeleteConversationEndpoint(store *chathistory.Store) echo.HandlerFunc {
+	return func(c echo.Context) error {
+		if err := store.Delete(getUserID(c), c.Param("id")); err != nil {
+			return chatHistoryError(c, err)
+		}
+		return c.JSON(http.StatusOK, map[string]string{"status": "ok"})
+	}
+}
+
+// DeleteAllConversationsEndpoint deletes the user's entire chat history.
+//
+//	@Summary	Delete all chat conversations for the current user
+//	@Tags		chat-history
+//	@Produce	json
+//	@Success	200	{object}	map[string]string
+//	@Router		/api/conversations [delete]
+func DeleteAllConversationsEndpoint(store *chathistory.Store) echo.HandlerFunc {
+	return func(c echo.Context) error {
+		if err := store.DeleteAll(getUserID(c)); err != nil {
+			return chatHistoryError(c, err)
+		}
+		return c.JSON(http.StatusOK, map[string]string{"status": "ok"})
+	}
+}

core/http/react-ui/e2e/chat-history-sync.spec.js

@@ -0,0 +1,505 @@
+import { test, expect } from './coverage-fixtures.js'
+import { mockChat, chatOf, pair, answerWith, CHATS_KEY } from './chat-fixtures.js'
+
+// Server-side chat history (see docs/content/features/chat-history.md). The
+// server keeps a tombstone for every deleted conversation and refuses to
+// write it again; these specs pin the client half: a stale browser must drop
+// what the server deleted, and must not lose what it typed while the list
+// was loading.
+
+const T0 = new Date('2026-10-09T12:00:00Z').getTime()
+
+// A stand-in for /api/conversations with the server's contract: tombstones
+// in the list, 410 for a write of a deleted id, versions on every write.
+// `hiddenDeleted` are tombstones the list does not report yet (deleted on
+// another device after this tab loaded the list). `holdList` keeps the list
+// request pending until release() is called.
+async function fakeHistoryServer(page, { conversations = [], deleted = [], hiddenDeleted = [], holdList = false } = {}) {
+  const live = new Map(conversations.map(c => [c.id, c]))
+  const tombs = new Map(deleted.map(id => [id, { id, version: 9, deletedAt: T0 }]))
+  const hidden = new Set(hiddenDeleted)
+  const requests = []
+  let release = () => {}
+  const listGate = holdList ? new Promise(resolve => { release = resolve }) : Promise.resolve()
+
+  let down = false
+
+  await page.route(/\/api\/conversations(\/[^?]*)?(\?.*)?$/, async (route) => {
+    if (down) return route.abort('internetdisconnected')
+    const req = route.request()
+    const path = new URL(req.url()).pathname
+    const rest = path.slice(path.indexOf('/api/conversations') + '/api/conversations'.length)
+    const id = rest.startsWith('/') ? decodeURIComponent(rest.slice(1)) : null
+    const method = req.method()
+    const body = method === 'PUT' || method === 'POST' ? req.postDataJSON() : null
+    requests.push({ method, id, body })
+
+    if (method === 'GET' && !id) {
+      await listGate
+      return route.fulfill({ json: { conversations: [...live.values()], deleted: [...tombs.values()] } })
+    }
+    if (method === 'PUT' && id && id !== 'bulk') {
+      if (tombs.has(id) || hidden.has(id)) {
+        return route.fulfill({ status: 410, json: { error: 'conversation was deleted' } })
+      }
+      const saved = { ...body, id, version: (live.get(id)?.version || 0) + 1 }
+      live.set(id, saved)
+      return route.fulfill({ json: saved })
+    }
+    if (method === 'DELETE' && id) {
+      live.delete(id)
+      tombs.set(id, { id, version: 9, deletedAt: T0 })
+      return route.fulfill({ json: { status: 'ok' } })
+    }
+    if (method === 'DELETE' && !id) {
+      for (const liveId of live.keys()) tombs.set(liveId, { id: liveId, version: 9, deletedAt: T0 })
+      live.clear()
+      return route.fulfill({ json: { status: 'ok' } })
+    }
+    return route.fulfill({ status: 404, json: { error: 'not found' } })
+  })
+
+  return {
+    release: () => release(),
+    setDown: (value) => { down = value },
+    liveIds: () => [...live.keys()].sort(),
+    saves: (id) => requests.filter(r => r.method === 'PUT' && (id === undefined || r.id === id)),
+    deletes: (id) => requests.filter(r => r.method === 'DELETE' && r.id === id),
+    deleteAlls: () => requests.filter(r => r.method === 'DELETE' && !r.id),
+    bulk: () => requests.filter(r => r.id === 'bulk'),
+  }
+}
+
+// Signs the browser in as `who()`, read on every request so a spec can sign
+// one account out and another in on the same browser.
+async function signedInAs(page, who) {
+  await page.route('**/api/auth/status', route => route.fulfill({
+    json: { authEnabled: true, staticApiKeyRequired: false, providers: ['local'], hasUsers: true, user: who() },
+  }))
+}
+
+const ALICE = { id: 'u-alice', name: 'Alice', email: 'alice@example.com', role: 'admin', permissions: {} }
+const BOB = { id: 'u-bob', name: 'Bob', email: 'bob@example.com', role: 'admin', permissions: {} }
+
+// Each account has its own browser cache (src/utils/chatStore.js).
+const keyOf = (user) => `${CHATS_KEY}:${user.id}`
+
+const storedChats = (page, user = ALICE) =>
+  page.evaluate((key) => JSON.parse(localStorage.getItem(key) || '{}'), keyOf(user))
+
+// Open Chat signed in as Alice with these conversations in her cache.
+async function openChat(page, chats, active = chats[0]?.id) {
+  await page.addInitScript(([key, data]) => {
+    if (!localStorage.getItem(key)) localStorage.setItem(key, JSON.stringify(data))
+  }, [keyOf(ALICE), { chats, activeChatId: active, lastSaved: Date.now() }])
+  await page.goto('/app/chat')
+  await page.getByTestId('chat-composer').waitFor()
+}
+
+// The server half per account: the session decides whose conversations a
+// request reads and writes. Saves for an account in `failSaves` answer 500,
+// as a first save that does not get through.
+async function fakeAccountServer(page, who, { failSaves = [] } = {}) {
+  const accounts = new Map()
+  const failing = new Set(failSaves)
+  const requests = []
+  const of = (userId) => {
+    if (!accounts.has(userId)) accounts.set(userId, new Map())
+    return accounts.get(userId)
+  }
+  await page.route(/\/api\/conversations(\/[^?]*)?(\?.*)?$/, async (route) => {
+    const req = route.request()
+    const user = who().id
+    const live = of(user)
+    const path = new URL(req.url()).pathname
+    const rest = path.slice(path.indexOf('/api/conversations') + '/api/conversations'.length)
+    const id = rest.startsWith('/') ? decodeURIComponent(rest.slice(1)) : null
+    const method = req.method()
+    const body = method === 'PUT' ? req.postDataJSON() : null
+    requests.push({ user, method, id, body })
+    if (method === 'GET' && !id) return route.fulfill({ json: { conversations: [...live.values()], deleted: [] } })
+    if (method === 'PUT' && id) {
+      if (failing.has(user)) return route.fulfill({ status: 500, json: { error: 'database is locked' } })
+      const saved = { ...body, id, version: (live.get(id)?.version || 0) + 1 }
+      live.set(id, saved)
+      return route.fulfill({ json: saved })
+    }
+    return route.fulfill({ status: 404, json: { error: 'not found' } })
+  })
+  return {
+    recover: (userId) => failing.delete(userId),
+    saves: (userId) => requests.filter(r => r.user === userId && r.method === 'PUT'),
+    liveTexts: (userId) => [...of(userId).values()].map(c => JSON.stringify(c.history)),
+  }
+}
+
+const storedIds = async (page) => (await storedChats(page)).chats.map(c => c.id)
+
+async function openMenu(page) {
+  await page.keyboard.press('Control+k')
+  await expect(page.getByTestId('chats-menu')).toBeVisible()
+}
+
+test.describe('Chat history sync with the server', () => {
+  test.beforeEach(async ({ page }) => {
+    await mockChat(page)
+    await signedInAs(page, () => ALICE)
+  })
+
+  test('a stale client drops a chat deleted on another device instead of uploading it again', async ({ page }) => {
+    const server = await fakeHistoryServer(page, {
+      conversations: [chatOf('kept', 'Kept on the server', 'qwen3-8b', pair('q', 'a'), { version: 1 }, T0)],
+      deleted: ['gone'],
+    })
+    await openChat(page, [
+      chatOf('gone', 'Deleted on the laptop', 'qwen3-8b', pair('old q', 'old a'), { version: 2 }, T0 + 5_000),
+      chatOf('kept', 'Kept on the server', 'qwen3-8b', pair('q', 'a'), { version: 1 }, T0),
+      chatOf('draft', 'Never synced draft', 'qwen3-8b', pair('draft q', 'draft a'), {}, T0 - 5_000),
+    ], 'gone')
+
+    // The draft is uploaded: that is the save pass the deleted chat must not be in.
+    await expect.poll(() => server.saves('draft').length).toBe(1)
+    expect(server.saves('gone')).toHaveLength(0)
+    await expect.poll(() => storedIds(page)).toEqual(['kept', 'draft'])
+
+    await openMenu(page)
+    await expect(page.getByTestId('chats-row').filter({ hasText: 'Deleted on the laptop' })).toHaveCount(0)
+    await expect(page.getByTestId('chats-row').filter({ hasText: 'Never synced draft' })).toHaveCount(1)
+  })
+
+  test('a synced chat the server no longer has is dropped, not resurrected', async ({ page }) => {
+    // Another account signed in on this browser, or an admin purge: the chat
+    // has a version, so it was on the server, and the server does not list it.
+    const server = await fakeHistoryServer(page, { conversations: [] })
+    await openChat(page, [
+      chatOf('synced', 'Synced earlier', 'qwen3-8b', pair('q', 'a'), { version: 3 }, T0),
+      chatOf('draft', 'Fresh draft', 'qwen3-8b', pair('q', 'a'), {}, T0 - 1_000),
+    ])
+    await expect.poll(() => server.saves('draft').length).toBe(1)
+    expect(server.saves('synced')).toHaveLength(0)
+    // An empty server list is no reason to replace the server's set with
+    // this browser's cache.
+    expect(server.bulk()).toHaveLength(0)
+    await expect.poll(() => storedIds(page)).toEqual(['draft'])
+  })
+
+  test('a 410 on save drops the chat locally', async ({ page }) => {
+    // Deleted on another device after this tab loaded the list.
+    const server = await fakeHistoryServer(page, { hiddenDeleted: ['late'] })
+    await openChat(page, [
+      chatOf('late', 'Deleted meanwhile', 'qwen3-8b', pair('q', 'a'), {}, T0),
+      chatOf('other', 'Still here', 'qwen3-8b', pair('q', 'a'), {}, T0 - 1_000),
+    ])
+    await expect.poll(() => server.saves('late').length).toBe(1)
+    await expect.poll(() => storedIds(page)).toEqual(['other'])
+    // Dropped, not retried.
+    await page.waitForTimeout(1_000)
+    expect(server.saves('late')).toHaveLength(1)
+  })
+
+  test('a message sent while the list is loading survives the older server copy', async ({ page }) => {
+    const server = await fakeHistoryServer(page, {
+      holdList: true,
+      conversations: [chatOf('x', 'Release notes', 'qwen3-8b', pair('first question', 'first answer'), { version: 4 }, T0)],
+    })
+    await answerWith(page, 'Answer written during the probe')
+    await openChat(page, [chatOf('x', 'Release notes', 'qwen3-8b', pair('first question', 'first answer'), { version: 4 }, T0)])
+
+    await page.getByTestId('chat-input').fill('Question typed while loading')
+    await page.getByTestId('chat-input').press('Enter')
+    await expect(page.getByText('Answer written during the probe')).toBeVisible()
+
+    server.release()
+    // The newer local copy wins and is uploaded with the new turn in it.
+    await expect.poll(() => server.saves('x').map(r => JSON.stringify(r.body.history)).join('\n'))
+      .toContain('Question typed while loading')
+    await expect(page.getByText('Question typed while loading')).toBeVisible()
+    await expect(page.getByText('Answer written during the probe')).toBeVisible()
+  })
+
+  test('a newer copy from the server replaces the older local one', async ({ page }) => {
+    const remote = chatOf('x', 'Release notes', 'qwen3-8b',
+      [...pair('first question', 'first answer'), ...pair('asked on the phone', 'answered on the phone')], { version: 5 }, T0 + 60_000)
+    const server = await fakeHistoryServer(page, { conversations: [remote] })
+    await openChat(page, [chatOf('x', 'Release notes', 'qwen3-8b', pair('first question', 'first answer'), { version: 4 }, T0)])
+
+    await expect(page.getByText('answered on the phone')).toBeVisible()
+    // Adopting the server copy is not a change to send back.
+    await page.waitForTimeout(1_000)
+    expect(server.saves('x')).toHaveLength(0)
+  })
+
+  test('a delete made while the list is loading reaches the server and wins', async ({ page }) => {
+    const server = await fakeHistoryServer(page, {
+      holdList: true,
+      conversations: [
+        chatOf('a', 'Keep me', 'qwen3-8b', pair('q', 'a'), { version: 1 }, T0),
+        chatOf('b', 'Delete me', 'qwen3-8b', pair('q', 'b'), { version: 1 }, T0 - 1_000),
+      ],
+    })
+    await openChat(page, [
+      chatOf('a', 'Keep me', 'qwen3-8b', pair('q', 'a'), { version: 1 }, T0),
+      chatOf('b', 'Delete me', 'qwen3-8b', pair('q', 'b'), { version: 1 }, T0 - 1_000),
+    ])
+
+    await openMenu(page)
+    const row = page.getByTestId('chats-row').filter({ hasText: 'Delete me' })
+    await row.hover()
+    await row.getByTitle('Delete chat').click()
+    const toast = page.getByTestId('chat-undo-toast')
+    await toast.getByRole('button', { name: 'Dismiss' }).click()
+    await expect(toast).toHaveCount(0)
+
+    server.release()
+    await expect.poll(() => server.deletes('b').length).toBe(1)
+    // The server still listed it when the answer left; the local delete wins.
+    await expect.poll(() => storedIds(page)).toEqual(['a'])
+    await expect(page.getByTestId('chats-row').filter({ hasText: 'Delete me' })).toHaveCount(0)
+    expect(server.saves('b')).toHaveLength(0)
+  })
+
+  test('the LocalAI Assistant toggle survives the trip to the server and back', async ({ page }) => {
+    const server = await fakeHistoryServer(page, {
+      conversations: [chatOf('remote', 'Assistant on the phone', 'qwen3-8b', pair('q', 'a'), { version: 1, localaiAssistant: true }, T0)],
+    })
+    await openChat(page, [chatOf('local', 'Assistant draft', 'qwen3-8b', pair('q', 'a'), { localaiAssistant: true }, T0 + 1_000)])
+
+    await expect.poll(() => server.saves('local').length).toBe(1)
+    expect(server.saves('local')[0].body.localaiAssistant).toBe(true)
+    await expect.poll(async () => (await storedChats(page)).chats.map(c => [c.id, !!c.localaiAssistant]))
+      .toEqual([['local', true], ['remote', true]])
+  })
+})
+
+test.describe('Chat history belongs to the signed-in account', () => {
+  test.beforeEach(async ({ page }) => {
+    await mockChat(page)
+  })
+
+  test('a draft one account could not save is not uploaded into the next account on this browser', async ({ page }) => {
+    let who = ALICE
+    await signedInAs(page, () => who)
+    const server = await fakeAccountServer(page, () => who, { failSaves: [ALICE.id] })
+    await answerWith(page, 'Answer meant for Alice')
+
+    await page.goto('/app/chat')
+    await page.getByTestId('chat-composer').waitFor()
+    await page.getByTestId('chat-input').fill('Alice private question')
+    await page.getByTestId('chat-input').press('Enter')
+    await expect(page.getByText('Answer meant for Alice')).toBeVisible()
+    // The first save of Alice's chat does not get through.
+    await expect.poll(() => server.saves(ALICE.id).some(r => JSON.stringify(r.body).includes('Alice private question'))).toBe(true)
+
+    // Alice signs out, Bob signs in on the same browser. His list is empty.
+    who = BOB
+    await page.goto('/app/chat')
+    await page.getByTestId('chat-composer').waitFor()
+
+    // Bob's first save pass is the one Alice's draft must not be part of.
+    await expect.poll(() => server.saves(BOB.id).length).toBeGreaterThan(0)
+    await page.waitForTimeout(1_000)
+    expect(server.saves(BOB.id).filter(r => JSON.stringify(r.body).includes('Alice private'))).toHaveLength(0)
+    expect(server.liveTexts(BOB.id).join('\n')).not.toContain('Alice private')
+    await openMenu(page)
+    await expect(page.getByTestId('chats-row').filter({ hasText: 'Alice private question' })).toHaveCount(0)
+  })
+
+  test('the same account still gets its unsaved draft back and uploads it', async ({ page }) => {
+    let who = ALICE
+    await signedInAs(page, () => who)
+    const server = await fakeAccountServer(page, () => who, { failSaves: [ALICE.id] })
+    await answerWith(page, 'Answer meant for Alice')
+
+    await page.goto('/app/chat')
+    await page.getByTestId('chat-composer').waitFor()
+    await page.getByTestId('chat-input').fill('Alice private question')
+    await page.getByTestId('chat-input').press('Enter')
+    await expect(page.getByText('Answer meant for Alice')).toBeVisible()
+    await expect.poll(() => server.saves(ALICE.id).length).toBeGreaterThan(0)
+
+    // Bob uses the browser in between; then Alice signs in again and the
+    // server takes writes again.
+    who = BOB
+    await page.goto('/app/chat')
+    await page.getByTestId('chat-composer').waitFor()
+    await expect.poll(() => server.saves(BOB.id).length).toBeGreaterThan(0)
+
+    who = ALICE
+    server.recover(ALICE.id)
+    await page.goto('/app/chat')
+    await page.getByTestId('chat-composer').waitFor()
+    await expect.poll(() => server.liveTexts(ALICE.id).join('\n')).toContain('Alice private question')
+    await openMenu(page)
+    await expect(page.getByTestId('chats-row').filter({ hasText: 'Alice private question' })).toHaveCount(1)
+  })
+})
+
+test.describe('Deletes stay pending until the server confirms them', () => {
+  const remote = () => [
+    chatOf('a', 'Keep me', 'qwen3-8b', pair('q', 'a'), { version: 1 }, T0),
+    chatOf('b', 'Delete me', 'qwen3-8b', pair('q', 'b'), { version: 1 }, T0 - 1_000),
+  ]
+
+  test.beforeEach(async ({ page }) => {
+    await mockChat(page)
+    await signedInAs(page, () => ALICE)
+  })
+
+  // Opens Chat with nothing in the browser and waits until the list has been
+  // reconciled: the empty chat Chat starts with is uploaded only after that.
+  async function openSynced(page, server) {
+    await page.goto('/app/chat')
+    await page.getByTestId('chat-composer').waitFor()
+    await expect.poll(() => server.saves().length).toBeGreaterThan(0)
+    await openMenu(page)
+    await expect(page.getByTestId('chats-row').filter({ hasText: 'Delete me' })).toHaveCount(1)
+  }
+
+  async function deleteRow(page, name) {
+    const row = page.getByTestId('chats-row').filter({ hasText: name })
+    await row.hover()
+    await row.getByTitle('Delete chat').click()
+    const toast = page.getByTestId('chat-undo-toast')
+    await toast.getByRole('button', { name: 'Dismiss' }).click()
+    await expect(toast).toHaveCount(0)
+  }
+
+  async function reopen(page) {
+    await page.goto('/app/chat')
+    await page.getByTestId('chat-composer').waitFor()
+    await openMenu(page)
+  }
+
+  test('a delete made while the server is unreachable is sent later and the chat does not come back', async ({ page, context }) => {
+    const server = await fakeHistoryServer(page, { conversations: remote() })
+    await openSynced(page, server)
+
+    server.setDown(true)
+    await context.setOffline(true)
+    await deleteRow(page, 'Delete me')
+    await expect(page.getByTestId('chats-row').filter({ hasText: 'Delete me' })).toHaveCount(0)
+    await page.waitForTimeout(500)
+
+    server.setDown(false)
+    await context.setOffline(false)
+    await reopen(page)
+    await expect.poll(() => server.liveIds().filter(id => id === 'a' || id === 'b')).toEqual(['a'])
+    await expect(page.getByTestId('chats-row').filter({ hasText: 'Keep me' })).toHaveCount(1)
+    await expect(page.getByTestId('chats-row').filter({ hasText: 'Delete me' })).toHaveCount(0)
+  })
+
+  test('"clear all" made while the server is unreachable is sent later and nothing comes back', async ({ page, context }) => {
+    const server = await fakeHistoryServer(page, { conversations: remote() })
+    await openSynced(page, server)
+
+    server.setDown(true)
+    await context.setOffline(true)
+    await page.getByRole('button', { name: 'Clear all' }).click()
+    await page.getByRole('button', { name: 'Delete all' }).click()
+    await page.waitForTimeout(500)
+
+    server.setDown(false)
+    await context.setOffline(false)
+    await reopen(page)
+    await expect.poll(() => server.liveIds().filter(id => id === 'a' || id === 'b')).toEqual([])
+    await expect(page.getByTestId('chats-row').filter({ hasText: 'Keep me' })).toHaveCount(0)
+    await expect(page.getByTestId('chats-row').filter({ hasText: 'Delete me' })).toHaveCount(0)
+  })
+
+  test('clear all persists before navigation can cancel the debounced save', async ({ page }) => {
+    const server = await fakeHistoryServer(page)
+    server.setDown(true)
+    // Two chats: with a single chat the menu offers no Clear all.
+    await openChat(page, [
+      chatOf('draft', 'Unsynced draft', 'qwen3-8b', pair('private draft', 'answer'), {}, T0),
+      chatOf('other', 'Other draft', 'qwen3-8b', pair('second draft', 'answer'), {}, T0 - 1000),
+    ])
+    await openMenu(page)
+    // Freeze the debounce: assert the cache produced by the delete itself.
+    await page.clock.install()
+    await page.clock.pauseAt(new Date())
+    await page.getByRole('button', { name: 'Clear all' }).click()
+    await page.getByRole('button', { name: 'Delete all' }).click()
+    const stored = await storedChats(page)
+    expect(stored.chats.map(c => c.id)).not.toContain('draft')
+    expect(stored.chats.map(c => c.id)).not.toContain('other')
+    expect(stored.pendingDeletes).toEqual(['*'])
+
+    await page.clock.resume()
+    server.setDown(false)
+    await reopen(page)
+    await expect.poll(() => server.deleteAlls().length).toBe(1)
+    await page.waitForTimeout(1_000)
+    expect(server.saves('draft')).toHaveLength(0)
+    expect(server.saves('other')).toHaveLength(0)
+    await expect(page.getByTestId('chats-row').filter({ hasText: 'Unsynced draft' })).toHaveCount(0)
+  })
+
+  test('a delete the server confirmed is not sent again and does not come back', async ({ page }) => {
+    const server = await fakeHistoryServer(page, { conversations: remote() })
+    await openSynced(page, server)
+
+    await deleteRow(page, 'Delete me')
+    await expect.poll(() => server.deletes('b').length).toBe(1)
+    expect(server.liveIds()).not.toContain('b')
+    // The server has the request; wait until the page has its answer too.
+    // Reopening earlier leaves the delete unconfirmed, and it is rightly sent again.
+    await expect.poll(async () => (await storedChats(page)).pendingDeletes).toEqual([])
+
+    await reopen(page)
+    await expect(page.getByTestId('chats-row').filter({ hasText: 'Keep me' })).toHaveCount(1)
+    await expect(page.getByTestId('chats-row').filter({ hasText: 'Delete me' })).toHaveCount(0)
+    await page.waitForTimeout(1_000)
+    expect(server.deletes('b')).toHaveLength(1)
+  })
+})
+
+test.describe('Chat history from Home and without an account', () => {
+  test('a delete on the Home page reaches the server through Chat', async ({ page }) => {
+    await mockChat(page)
+    await signedInAs(page, () => ALICE)
+    const server = await fakeHistoryServer(page, {
+      conversations: [
+        chatOf('a', 'Keep me', 'qwen3-8b', pair('q', 'kept answer'), { version: 1 }, T0),
+        chatOf('b', 'Delete me', 'qwen3-8b', pair('q', 'deleted answer'), { version: 1 }, T0 - 1_000),
+      ],
+    })
+    await page.addInitScript(([key, data]) => {
+      if (!localStorage.getItem(key)) localStorage.setItem(key, JSON.stringify(data))
+    }, [keyOf(ALICE), {
+      chats: [
+        chatOf('a', 'Keep me', 'qwen3-8b', pair('q', 'kept answer'), { version: 1 }, Date.now()),
+        chatOf('b', 'Delete me', 'qwen3-8b', pair('q', 'deleted answer'), { version: 1 }, Date.now() - 1_000),
+      ],
+      activeChatId: 'a',
+    }])
+
+    await page.goto('/app')
+    const row = page.getByTestId('home-conversation').filter({ hasText: 'Delete me' })
+    await row.hover()
+    await row.getByRole('button', { name: /delete conversation/i }).click()
+    await expect(page.getByTestId('home-undo-toast')).toBeVisible()
+    // Resuming another chat makes the delete final and opens Chat.
+    await page.getByTestId('home-conversation').filter({ hasText: 'Keep me' }).locator('.home-row__open').click()
+    await expect(page).toHaveURL(/\/app\/chat/)
+
+    await expect.poll(() => server.deletes('b').length).toBe(1)
+    await openMenu(page)
+    await expect(page.getByTestId('chats-row').filter({ hasText: 'Keep me' })).toHaveCount(1)
+    await expect(page.getByTestId('chats-row').filter({ hasText: 'Delete me' })).toHaveCount(0)
+  })
+
+  test('nobody signed in: chats stay in the browser and nothing is sent', async ({ page }) => {
+    await mockChat(page)
+    const server = await fakeHistoryServer(page, {})
+    await page.addInitScript(([key, data]) => {
+      if (!localStorage.getItem(key)) localStorage.setItem(key, JSON.stringify(data))
+    }, [CHATS_KEY, { chats: [chatOf('local', 'Browser only', 'qwen3-8b', pair('q', 'a'), {}, T0)], activeChatId: 'local' }])
+    await page.goto('/app/chat')
+    await page.getByTestId('chat-composer').waitFor()
+    await openMenu(page)
+    await expect(page.getByTestId('chats-row').filter({ hasText: 'Browser only' })).toHaveCount(1)
+    await page.waitForTimeout(1_000)
+    expect(server.saves()).toHaveLength(0)
+  })
+})

core/http/react-ui/src/hooks/useChat.js

@@ -1,8 +1,11 @@
-import { useState, useCallback, useRef } from 'react'
+import { useState, useCallback, useRef, useEffect } from 'react'
 import { API_CONFIG } from '../utils/config'
 import { apiUrl } from '../utils/basePath'
 import { effectiveSystemPrompt } from '../utils/systemPrompt'
 import { useDebouncedEffect } from './useDebounce'
+import { chatHistoryApi } from '../utils/api'
+import { useAuth } from '../context/AuthContext'
+import { chatsStorageKey, readChatStore, writeChatStore } from '../utils/chatStore'
 
 const thinkingTagRegex = /<thinking>([\s\S]*?)<\/thinking>|<think>([\s\S]*?)<\/think>|<\|channel>thought([\s\S]*?)<channel\|>/g
 const openThinkTagRegex = /<thinking>|<think>|<\|channel>thought/
@@ -96,58 +99,75 @@ function extractThinking(text) {
 
 import { generateId } from '../utils/format'
 
-const CHATS_STORAGE_KEY = 'localai_chats_data'
-
-function loadChats() {
-  try {
-    const stored = localStorage.getItem(CHATS_STORAGE_KEY)
-    if (stored) {
-      const data = JSON.parse(stored)
-      if (data && Array.isArray(data.chats)) {
-        // Older chats stored a separate reasoningOff flag. It now means
-        // reasoning_effort 'none'.
-        data.chats = data.chats.map(({ reasoningOff, ...chat }) => (
-          reasoningOff ? { ...chat, reasoningEffort: 'none' } : chat
-        ))
-        return data
-      }
-    }
-  } catch (_e) {
-    localStorage.removeItem(CHATS_STORAGE_KEY)
+// serializeChat strips React-only state (streaming flags, transient UI bits)
+// before persistence. This is what goes to the server; `version` is the
+// server's and is never sent back.
+function serializeChat(chat) {
+  return {
+    id: chat.id,
+    name: chat.name,
+    model: chat.model,
+    history: chat.history,
+    systemPrompt: chat.systemPrompt,
+    mcpMode: chat.mcpMode,
+    mcpServers: chat.mcpServers,
+    mcpResources: chat.mcpResources,
+    clientMCPServers: chat.clientMCPServers,
+    localaiAssistant: chat.localaiAssistant,
+    temperature: chat.temperature,
+    topP: chat.topP,
+    topK: chat.topK,
+    reasoningEffort: chat.reasoningEffort,
+    tokenUsage: chat.tokenUsage,
+    contextSize: chat.contextSize,
+    createdAt: chat.createdAt,
+    updatedAt: chat.updatedAt,
   }
-  return null
 }
 
-function saveChats(chats, activeChatId) {
-  try {
-    const data = {
-      chats: chats.map(chat => ({
-        id: chat.id,
-        name: chat.name,
-        model: chat.model,
-        history: chat.history,
-        systemPrompt: chat.systemPrompt,
-        mcpMode: chat.mcpMode,
-        mcpServers: chat.mcpServers,
-        clientMCPServers: chat.clientMCPServers,
-        temperature: chat.temperature,
-        topP: chat.topP,
-        topK: chat.topK,
-        reasoningEffort: chat.reasoningEffort,
-        tokenUsage: chat.tokenUsage,
-        contextSize: chat.contextSize,
-        createdAt: chat.createdAt,
-        updatedAt: chat.updatedAt,
-      })),
-      activeChatId,
-      lastSaved: Date.now(),
-    }
-    localStorage.setItem(CHATS_STORAGE_KEY, JSON.stringify(data))
-  } catch (err) {
-    if (err.name === 'QuotaExceededError' || err.code === 22) {
-      console.warn('localStorage quota exceeded')
+function saveChats(key, chats, activeChatId, pendingDeletes) {
+  writeChatStore(key, {
+    // The local cache keeps the server version: it is how the next load
+    // tells a chat the server has seen from a never-synced draft.
+    chats: chats.map(chat => ({ ...serializeChat(chat), version: chat.version })),
+    activeChatId,
+    pendingDeletes: [...pendingDeletes],
+  })
+}
+
+// The server omits empty fields; the UI expects a history array.
+function fromServer(conv) {
+  return { ...conv, history: Array.isArray(conv.history) ? conv.history : [] }
+}
+
+// reconcileWithServer merges the server's list into the chats this tab
+// already has (from localStorage, plus anything typed while the list was
+// loading). The server is authoritative about deletions:
+//   - a chat the server lists as deleted is dropped, whatever this tab has;
+//   - a chat on both sides keeps the copy with the newer updatedAt, so an
+//     edit made during the load is not overwritten by the older server copy;
+//   - a chat only here is kept when it was never synced (no version) and
+//     uploaded afterwards. With a version the server has seen it and no
+//     longer has it, so it is dropped rather than resurrected;
+//   - a chat only on the server is added.
+function reconcileWithServer(remote, deleted, local) {
+  const gone = new Set(deleted.map(t => t.id))
+  const remoteById = new Map(remote.map(c => [c.id, fromServer(c)]))
+  const out = []
+  for (const c of local) {
+    if (gone.has(c.id)) continue
+    const r = remoteById.get(c.id)
+    if (r) {
+      remoteById.delete(c.id)
+      out.push((c.updatedAt || 0) > (r.updatedAt || 0) ? { ...c, version: r.version } : r)
+    } else if (!c.version) {
+      out.push(c)
     }
   }
+  for (const r of remoteById.values()) {
+    if (!gone.has(r.id)) out.push(r)
+  }
+  return out.sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0))
 }
 
 function createNewChat(model = '', systemPrompt = '', mcpMode = false) {
@@ -178,17 +198,33 @@ function createNewChat(model = '', systemPrompt = '', mcpMode = false) {
 }
 
 export function useChat(initialModel = '') {
+  // The cache and the server sync belong to the signed-in account. Chat
+  // remounts this hook when the account changes, so the key is fixed for the
+  // hook's lifetime. Without an account there is no server history and the
+  // chats stay in the browser only.
+  const { user } = useAuth()
+  const accountId = user?.id || ''
+  const storageKey = chatsStorageKey(accountId)
+  const storedRef = useRef(undefined)
+  if (storedRef.current === undefined) storedRef.current = readChatStore(storageKey)
+
+  // Deletes the server has not confirmed yet ('*' = delete all). They are
+  // persisted with the cache and sent again until the server answers, so a
+  // delete made while the server is unreachable is not undone by the next
+  // list.
+  const pendingDeletesRef = useRef(null)
+  if (pendingDeletesRef.current === null) {
+    pendingDeletesRef.current = new Set(accountId ? (storedRef.current?.pendingDeletes || []) : [])
+  }
+
   const [chats, setChats] = useState(() => {
-    const stored = loadChats()
-    if (stored && stored.chats.length > 0) return stored.chats
+    const pending = pendingDeletesRef.current
+    const stored = (storedRef.current?.chats || []).filter(c => !pending.has(c.id))
+    if (stored.length > 0) return stored
     return [createNewChat(initialModel)]
   })
 
-  const [activeChatId, setActiveChatId] = useState(() => {
-    const stored = loadChats()
-    if (stored && stored.activeChatId) return stored.activeChatId
-    return chats[0]?.id
-  })
+  const [activeChatId, setActiveChatId] = useState(() => storedRef.current?.activeChatId || chats[0]?.id)
 
   const [isStreaming, setIsStreaming] = useState(false)
   const [streamingChatId, setStreamingChatId] = useState(null)
@@ -208,7 +244,145 @@ export function useChat(initialModel = '') {
 
   const activeChat = chats.find(c => c.id === activeChatId) || chats[0]
 
-  useDebouncedEffect(() => saveChats(chats, activeChatId), [chats, activeChatId])
+  // Server-side persistence. serverEnabledRef is null while we are still
+  // probing, true once a successful list arrives, false on any error
+  // (feature disabled, auth off, denied, network down) and when nobody is
+  // signed in. serializedSentRef caches the JSON last pushed (or received)
+  // per chat so unchanged chats are not written again. deletesInFlightRef
+  // holds the pending deletes with a request on the way; deleteAllSeqRef
+  // counts "delete all" requests, so the answer to an older one does not
+  // clear a newer one.
+  const serverEnabledRef = useRef(null)
+  const serializedSentRef = useRef(new Map())
+  const deletesInFlightRef = useRef(new Set())
+  const deleteAllSeqRef = useRef(0)
+  // Bumped when a confirmed "delete all" lets the held-back saves go out.
+  const [syncTick, setSyncTick] = useState(0)
+
+  const persistPending = useCallback(() => {
+    const data = readChatStore(storageKey) || { chats: [], activeChatId: null }
+    writeChatStore(storageKey, { ...data, pendingDeletes: [...pendingDeletesRef.current] })
+  }, [storageKey])
+
+  // flushPendingDeletes sends every pending delete that has no request on the
+  // way. A delete leaves the queue only when the server confirms it (DELETE
+  // is idempotent server-side); on any other outcome it stays and is sent
+  // again with the next change, when the browser comes back online, or on
+  // the next load.
+  const flushPendingDeletes = useCallback(() => {
+    if (serverEnabledRef.current !== true) return
+    const inFlight = deletesInFlightRef.current
+    for (const id of pendingDeletesRef.current) {
+      if (inFlight.has(id)) continue
+      inFlight.add(id)
+      const seq = deleteAllSeqRef.current
+      const request = id === '*' ? chatHistoryApi.deleteAll() : chatHistoryApi.delete(id)
+      request
+        .then(() => true, err => err?.status === 400) // 400: an id the server never accepts
+        .then(done => {
+          inFlight.delete(id)
+          if (!done) return
+          if (id === '*' && seq !== deleteAllSeqRef.current) {
+            flushPendingDeletes()
+            return
+          }
+          pendingDeletesRef.current.delete(id)
+          persistPending()
+          if (id === '*') setSyncTick(t => t + 1)
+        })
+    }
+  }, [persistPending])
+
+  // Every path that empties the list must leave one chat to show.
+  const nonEmpty = useCallback((list) => (list.length > 0 ? list : [createNewChat(initialModel)]), [initialModel])
+
+  const dropChatLocally = useCallback((chatId) => {
+    serializedSentRef.current.delete(chatId)
+    setChats(prev => (prev.some(c => c.id === chatId) ? nonEmpty(prev.filter(c => c.id !== chatId)) : prev))
+  }, [nonEmpty])
+
+  useEffect(() => {
+    if (!accountId) {
+      serverEnabledRef.current = false
+      return
+    }
+    let cancelled = false
+    chatHistoryApi.list()
+      .then(resp => {
+        if (cancelled) return
+        const remote = Array.isArray(resp?.conversations) ? resp.conversations : []
+        const deleted = Array.isArray(resp?.deleted) ? [...resp.deleted] : []
+        // A pending delete wins over the list: the server may still have the
+        // chat because the delete has not reached it yet.
+        const pending = pendingDeletesRef.current
+        if (pending.has('*')) {
+          for (const c of remote) deleted.push({ id: c.id })
+        }
+        for (const id of pending) {
+          if (id !== '*') deleted.push({ id })
+        }
+        // What the server holds counts as sent, so adopting a server copy
+        // does not echo it straight back.
+        for (const c of remote) {
+          serializedSentRef.current.set(c.id, JSON.stringify(serializeChat(fromServer(c))))
+        }
+        serverEnabledRef.current = true
+        setChats(prev => nonEmpty(reconcileWithServer(remote, deleted, prev)))
+        flushPendingDeletes()
+      })
+      .catch(() => {
+        if (!cancelled) serverEnabledRef.current = false
+      })
+    return () => { cancelled = true }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  useEffect(() => {
+    window.addEventListener('online', flushPendingDeletes)
+    return () => window.removeEventListener('online', flushPendingDeletes)
+  }, [flushPendingDeletes])
+
+  // The reconcile can remove the open chat.
+  useEffect(() => {
+    if (chats.length > 0 && !chats.some(c => c.id === activeChatId)) {
+      setActiveChatId(chats[0].id)
+    }
+  }, [chats, activeChatId])
+
+  useDebouncedEffect(() => {
+    saveChats(storageKey, chats, activeChatId, pendingDeletesRef.current)
+    if (serverEnabledRef.current !== true) return
+    flushPendingDeletes()
+    // Until a "delete all" is confirmed, a chat saved now would be caught by
+    // it when it lands. The confirmation bumps syncTick and the saves follow.
+    if (pendingDeletesRef.current.has('*')) return
+    for (const chat of chats) {
+      if (pendingDeletesRef.current.has(chat.id)) continue
+      const serialized = serializeChat(chat)
+      const json = JSON.stringify(serialized)
+      if (serializedSentRef.current.get(chat.id) === json) continue
+      serializedSentRef.current.set(chat.id, json)
+      chatHistoryApi.save(serialized)
+        .then(saved => {
+          if (!saved?.version) return
+          setChats(prev => {
+            if (!prev.some(c => c.id === saved.id && c.version !== saved.version)) return prev
+            return prev.map(c => (c.id === saved.id ? { ...c, version: saved.version } : c))
+          })
+        })
+        .catch(err => {
+          if (err?.status === 410) {
+            // Deleted on another device: the server keeps it deleted, so
+            // drop this copy instead of retrying it forever.
+            dropChatLocally(chat.id)
+            return
+          }
+          // Keep localStorage as the copy on transient server failures;
+          // the next change retries.
+          serializedSentRef.current.delete(chat.id)
+        })
+    }
+  }, [chats, activeChatId, syncTick])
 
   const addChat = useCallback((model = '', systemPrompt = '', mcpMode = false) => {
     const chat = createNewChat(model, systemPrompt, mcpMode)
@@ -253,7 +427,12 @@ export function useChat(initialModel = '') {
       }
       return filtered
     })
-  }, [activeChatId])
+    serializedSentRef.current.delete(chatId)
+    if (!accountId) return
+    pendingDeletesRef.current.add(chatId)
+    persistPending()
+    flushPendingDeletes()
+  }, [activeChatId, accountId, persistPending, flushPendingDeletes])
 
   const deleteAllChats = useCallback(() => {
     const chat = createNewChat(activeChat?.model || '')
@@ -264,7 +443,16 @@ export function useChat(initialModel = '') {
     setStreamingToolCalls([])
     setTokensPerSecond(null)
     setMaxTokensPerSecond(null)
-  }, [activeChat?.model])
+    serializedSentRef.current.clear()
+    if (!accountId) return
+    // Covers every delete still pending before it.
+    pendingDeletesRef.current = new Set(['*'])
+    deleteAllSeqRef.current += 1
+    // Navigation cancels the debounced save; persist the cleared list with
+    // its delete intent so an unsynced draft cannot return on the next load.
+    saveChats(storageKey, [chat], chat.id, pendingDeletesRef.current)
+    flushPendingDeletes()
+  }, [activeChat?.model, accountId, storageKey, flushPendingDeletes])
 
   const renameChat = useCallback((chatId, name) => {
     setChats(prev => prev.map(c =>

core/http/react-ui/src/pages/Chat.jsx

@@ -98,7 +98,16 @@ function formatLoadEta(seconds) {
   return `${Math.floor(minutes / 60)}h ${minutes % 60}m`
 }
 
+// One chat state per account: useChat binds its browser cache and its server
+// sync to the signed-in account, so a different account gets a fresh mount
+// instead of the previous account's chats.
 export default function Chat() {
+  const { user } = useAuth()
+  return <ChatPage key={user?.id || ''} />
+}
+
+// eslint-disable-next-line no-unused-vars -- used as JSX above
+function ChatPage() {
   const { model: urlModel } = useParams()
   const { addToast } = useOutletContext()
   const navigate = useNavigate()

core/http/react-ui/src/pages/Home.jsx

@@ -32,6 +32,7 @@ import { greetingKey } from '../utils/greeting'
 import {
   listConversations, setActiveConversation, removeConversation,
 } from '../utils/homeConversations'
+import { chatsStorageKey } from '../utils/chatStore'
 // eslint-disable-next-line no-unused-vars
 import Skeleton from '../components/Skeleton'
 import { staggerStyle } from '../hooks/useStagger'
@@ -56,7 +57,9 @@ export default function Home() {
   const navigate = useNavigate()
   const { addToast } = useOutletContext()
   const { t, i18n } = useTranslation('home')
-  const { isAdmin } = useAuth()
+  const { isAdmin, user } = useAuth()
+  // The signed-in account's own chat cache (see chatStore).
+  const chatsKey = chatsStorageKey(user?.id)
   const branding = useBranding()
   const { resources } = useResources()
   const { operations } = useOperations()
@@ -92,7 +95,7 @@ export default function Home() {
   const [distributedMode, setDistributedMode] = useState(false)
   const [clusterData, setClusterData] = useState(null)
   const [stripOpen, setStripOpen] = useState(false)
-  const [conversations, setConversations] = useState(() => listConversations())
+  const [conversations, setConversations] = useState(() => listConversations(chatsKey))
   const [leavingId, setLeavingId] = useState(null)
   const [pendingDelete, setPendingDelete] = useState(null)
   const textareaRef = useRef(null)
@@ -366,19 +369,19 @@ export default function Home() {
 
   // ----- Conversations -----------------------------------------------------
 
-  const refreshConversations = useCallback(() => setConversations(listConversations()), [])
+  const refreshConversations = useCallback(() => setConversations(listConversations(chatsKey)), [chatsKey])
 
   // Another tab can write chats, and Chat writes them after a short delay. Read
   // again when the tab changes or comes back into focus.
   useEffect(() => {
-    const onStorage = (e) => { if (!e.key || e.key === 'localai_chats_data') refreshConversations() }
+    const onStorage = (e) => { if (!e.key || e.key === chatsKey) refreshConversations() }
     window.addEventListener('storage', onStorage)
     window.addEventListener('focus', refreshConversations)
     return () => {
       window.removeEventListener('storage', onStorage)
       window.removeEventListener('focus', refreshConversations)
     }
-  }, [refreshConversations])
+  }, [chatsKey, refreshConversations])
 
   // A delete is final when its undo time ends. Until then the chat stays in
   // storage and only the row is hidden.
@@ -386,10 +389,10 @@ export default function Home() {
     const id = pendingRef.current
     if (!id) return
     pendingRef.current = null
-    removeConversation(id)
+    removeConversation(id, chatsKey)
     setPendingDelete(null)
     refreshConversations()
-  }, [refreshConversations])
+  }, [chatsKey, refreshConversations])
 
   const commitRef = useRef(commitDelete)
   commitRef.current = commitDelete
@@ -421,9 +424,9 @@ export default function Home() {
 
   const resumeConversation = useCallback((conv) => {
     commitDelete()
-    if (setActiveConversation(conv.id)) navigate('/app/chat')
+    if (setActiveConversation(conv.id, chatsKey)) navigate('/app/chat')
     else refreshConversations()
-  }, [commitDelete, navigate, refreshConversations])
+  }, [chatsKey, commitDelete, navigate, refreshConversations])
 
   const visibleConversations = useMemo(
     () => conversations.filter(c => c.id !== pendingDelete?.id),

core/http/react-ui/src/utils/api.js

@@ -157,6 +157,25 @@ export const chatApi = {
   mcpComplete: (body) => postJSON(API_CONFIG.endpoints.mcpChatCompletions, body),
 }
 
+// Chat History API — server-side conversation persistence (#9432).
+// Endpoints return 404 when the WebUI's chat history feature is disabled, so
+// every call here is best-effort: callers should fall back to localStorage on
+// failure rather than surfacing a user-visible error.
+export const chatHistoryApi = {
+  list: () => fetchJSON(API_CONFIG.endpoints.conversations),
+  get: (id) => fetchJSON(API_CONFIG.endpoints.conversation(id)),
+  save: (conv) => fetchJSON(API_CONFIG.endpoints.conversation(conv.id), {
+    method: 'PUT',
+    body: JSON.stringify(conv),
+  }),
+  bulkReplace: (conversations) => fetchJSON(API_CONFIG.endpoints.conversationsBulk, {
+    method: 'PUT',
+    body: JSON.stringify({ conversations }),
+  }),
+  delete: (id) => fetchJSON(API_CONFIG.endpoints.conversation(id), { method: 'DELETE' }),
+  deleteAll: () => fetchJSON(API_CONFIG.endpoints.conversations, { method: 'DELETE' }),
+}
+
 // MCP API
 export const mcpApi = {
   listServers: (model) => fetchJSON(API_CONFIG.endpoints.mcpServers(model)),

core/http/react-ui/src/utils/chatStore.js

@@ -0,0 +1,50 @@
+// The browser cache of the Chat page's conversations. Chat writes it, Home
+// reads it.
+//
+// Signed in, every account has its own entry: a draft one account could not
+// upload must never be found, and uploaded, by the next account that signs in
+// on the same browser. Without an account (auth disabled) the original key is
+// used, so existing browser-only histories keep working.
+//
+// Besides the chats the entry holds `pendingDeletes`: ids the user deleted
+// that the server has not confirmed yet ('*' = delete all). They survive a
+// reload and are sent again until the server answers.
+
+export const CHATS_STORAGE_KEY = 'localai_chats_data'
+
+export function chatsStorageKey(accountId) {
+  return accountId ? `${CHATS_STORAGE_KEY}:${accountId}` : CHATS_STORAGE_KEY
+}
+
+export function isChatsStorageKey(key) {
+  return key === CHATS_STORAGE_KEY || (typeof key === 'string' && key.startsWith(`${CHATS_STORAGE_KEY}:`))
+}
+
+export function readChatStore(key) {
+  try {
+    const raw = localStorage.getItem(key)
+    if (!raw) return null
+    const data = JSON.parse(raw)
+    if (!data || !Array.isArray(data.chats)) return null
+    // Older chats stored a separate reasoningOff flag. It now means
+    // reasoning_effort 'none'.
+    const chats = data.chats.map(({ reasoningOff, ...chat }) => (
+      reasoningOff ? { ...chat, reasoningEffort: 'none' } : chat
+    ))
+    return { ...data, chats, pendingDeletes: Array.isArray(data.pendingDeletes) ? data.pendingDeletes : [] }
+  } catch {
+    return null
+  }
+}
+
+export function writeChatStore(key, data) {
+  try {
+    localStorage.setItem(key, JSON.stringify({ ...data, lastSaved: Date.now() }))
+    return true
+  } catch (err) {
+    if (err?.name === 'QuotaExceededError' || err?.code === 22) {
+      console.warn('localStorage quota exceeded')
+    }
+    return false
+  }
+}

core/http/react-ui/src/utils/config.js

@@ -57,6 +57,11 @@ export const API_CONFIG = {
     p2pStats: '/api/p2p/stats',
     p2pToken: '/api/p2p/token',
 
+    // Chat history (server-side persistence, #9432)
+    conversations: '/api/conversations',
+    conversation: (id) => `/api/conversations/${encodeURIComponent(id)}`,
+    conversationsBulk: '/api/conversations/bulk',
+
     // Agent jobs
     agentTasks: '/api/agent/tasks',
     agentTask: (id) => `/api/agent/tasks/${id}`,

core/http/react-ui/src/utils/homeConversations.js

@@ -1,33 +1,15 @@
 // Conversations on the Home page: read from the same browser storage the Chat
-// page writes (see useChat), grouped by day for the "Jump back in" list.
+// page writes (see useChat and chatStore), grouped by day for the "Jump back
+// in" list. Every function takes the storage key of the signed-in account
+// (chatsStorageKey); without one it reads the browser-only key.
 //
 // Home only reads, resumes and deletes. It never writes a chat's content, so a
 // stored conversation keeps the exact shape Chat expects.
 
-export const CHATS_STORAGE_KEY = 'localai_chats_data'
+import { CHATS_STORAGE_KEY, readChatStore, writeChatStore } from './chatStore'
 
 const DAY_MS = 24 * 60 * 60 * 1000
 
-function readStore() {
-  try {
-    const raw = localStorage.getItem(CHATS_STORAGE_KEY)
-    if (!raw) return null
-    const data = JSON.parse(raw)
-    return data && Array.isArray(data.chats) ? data : null
-  } catch {
-    return null
-  }
-}
-
-function writeStore(data) {
-  try {
-    localStorage.setItem(CHATS_STORAGE_KEY, JSON.stringify({ ...data, lastSaved: Date.now() }))
-    return true
-  } catch {
-    return false
-  }
-}
-
 // A message body is a string, or a list of blocks ({type:'text'|'image_url'|...}).
 function messageText(message) {
   const content = message?.content
@@ -94,8 +76,8 @@ export function conversationsFromChats(chats) {
 }
 
 // Chats that hold at least one message, newest first.
-export function listConversations() {
-  const data = readStore()
+export function listConversations(key = CHATS_STORAGE_KEY) {
+  const data = readChatStore(key)
   return data ? conversationsFromChats(data.chats) : []
 }
 
@@ -130,19 +112,23 @@ export function groupConversations(items, now = Date.now()) {
 }
 
 // Make a stored chat the one Chat opens on.
-export function setActiveConversation(id) {
-  const data = readStore()
+export function setActiveConversation(id, key = CHATS_STORAGE_KEY) {
+  const data = readChatStore(key)
   if (!data || !data.chats.some(c => c.id === id)) return false
-  return writeStore({ ...data, activeChatId: id })
+  return writeChatStore(key, { ...data, activeChatId: id })
 }
 
 // Remove a chat from storage. Home keeps the chat until its undo time ends
-// and calls this only then, so there is nothing to put back afterwards.
-export function removeConversation(id) {
-  const data = readStore()
+// and calls this only then, so there is nothing to put back afterwards. The
+// id is queued as a pending delete: Home does not talk to the server, so the
+// Chat page sends the delete the next time it syncs. Without that a synced
+// chat removed here would come straight back from the server.
+export function removeConversation(id, key = CHATS_STORAGE_KEY) {
+  const data = readChatStore(key)
   if (!data || !data.chats.some(c => c.id === id)) return false
   const chats = data.chats.filter(c => c.id !== id)
   let activeChatId = data.activeChatId
   if (activeChatId === id) activeChatId = chats[0]?.id
-  return writeStore({ ...data, chats, activeChatId })
+  const pendingDeletes = data.pendingDeletes.includes(id) ? data.pendingDeletes : [...data.pendingDeletes, id]
+  return writeChatStore(key, { ...data, chats, activeChatId, pendingDeletes })
 }

core/http/routes/chat_history_auth_test.go

@@ -0,0 +1,287 @@
+// SPDX-License-Identifier: MIT
+//go:build auth
+
+package routes_test
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+
+	"github.com/labstack/echo/v4"
+	"github.com/mudler/LocalAI/core/config"
+	"github.com/mudler/LocalAI/core/http/auth"
+	"github.com/mudler/LocalAI/core/http/routes"
+	"github.com/mudler/LocalAI/core/services/chathistory"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"gorm.io/gorm"
+)
+
+// chatHistoryServer drives the conversation endpoints through the same
+// registration function and middleware chain the real server uses, against
+// an in-memory SQLite auth database.
+type chatHistoryServer struct {
+	e        *echo.Echo
+	db       *gorm.DB
+	sessions map[string]string
+}
+
+func newChatHistoryServer() *chatHistoryServer {
+	db, err := auth.InitDB(":memory:")
+	Expect(err).NotTo(HaveOccurred())
+	sqlDB, err := db.DB()
+	Expect(err).NotTo(HaveOccurred())
+	DeferCleanup(sqlDB.Close)
+
+	store, err := chathistory.New(db)
+	Expect(err).NotTo(HaveOccurred())
+
+	s := &chatHistoryServer{e: echo.New(), db: db, sessions: map[string]string{}}
+	for _, id := range []string{"alice", "bob", "carol"} {
+		user := &auth.User{ID: id, Email: id + "@example.test", Name: id, Role: auth.RoleUser, Status: auth.StatusActive, Provider: auth.ProviderLocal}
+		Expect(db.Create(user).Error).To(Succeed())
+		session, err := auth.CreateSession(db, id, "")
+		Expect(err).NotTo(HaveOccurred())
+		s.sessions[id] = session
+	}
+	// carol had the default-on feature revoked by an admin.
+	Expect(auth.UpdateUserPermissions(db, "carol", auth.PermissionMap{auth.FeatureChatHistory: false})).To(Succeed())
+
+	s.e.Use(auth.Middleware(db, config.NewApplicationConfig()))
+	routes.RegisterChatHistoryRoutes(s.e, store, auth.RequireFeature(db, auth.FeatureChatHistory))
+	return s
+}
+
+// do sends a request as user (empty = unauthenticated) and returns the
+// recorder; body may be nil.
+func (s *chatHistoryServer) do(user, method, path string, body any) *httptest.ResponseRecorder {
+	var payload *strings.Reader
+	if body == nil {
+		payload = strings.NewReader("")
+	} else if raw, ok := body.(string); ok {
+		payload = strings.NewReader(raw)
+	} else {
+		data, err := json.Marshal(body)
+		Expect(err).NotTo(HaveOccurred())
+		payload = strings.NewReader(string(data))
+	}
+	req := httptest.NewRequest(method, path, payload)
+	req.Header.Set(echo.HeaderContentType, echo.MIMEApplicationJSON)
+	if user != "" {
+		req.AddCookie(&http.Cookie{Name: "session", Value: s.sessions[user]})
+	}
+	rec := httptest.NewRecorder()
+	s.e.ServeHTTP(rec, req)
+	return rec
+}
+
+func decodeJSON(rec *httptest.ResponseRecorder) map[string]any {
+	var out map[string]any
+	Expect(json.Unmarshal(rec.Body.Bytes(), &out)).To(Succeed(), rec.Body.String())
+	return out
+}
+
+func listedIDs(rec *httptest.ResponseRecorder) []string {
+	Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String())
+	ids := []string{}
+	for _, c := range decodeJSON(rec)["conversations"].([]any) {
+		ids = append(ids, c.(map[string]any)["id"].(string))
+	}
+	return ids
+}
+
+func conversationBody(id, name string) map[string]any {
+	return map[string]any{
+		"id":      id,
+		"name":    name,
+		"model":   "test-model",
+		"history": []map[string]any{{"role": "user", "content": "hi"}},
+	}
+}
+
+var _ = Describe("Chat history endpoints", func() {
+	var s *chatHistoryServer
+
+	BeforeEach(func() {
+		s = newChatHistoryServer()
+	})
+
+	DescribeTable("require authentication on every route",
+		func(method, path string) {
+			Expect(s.do("", method, path, nil).Code).To(Equal(http.StatusUnauthorized))
+		},
+		Entry("list", http.MethodGet, "/api/conversations"),
+		Entry("create", http.MethodPost, "/api/conversations"),
+		Entry("delete all", http.MethodDelete, "/api/conversations"),
+		Entry("bulk", http.MethodPut, "/api/conversations/bulk"),
+		Entry("get", http.MethodGet, "/api/conversations/c1"),
+		Entry("save", http.MethodPut, "/api/conversations/c1"),
+		Entry("delete", http.MethodDelete, "/api/conversations/c1"),
+	)
+
+	DescribeTable("honour a revoked chat_history permission",
+		func(method, path string) {
+			Expect(s.do("carol", method, path, nil).Code).To(Equal(http.StatusForbidden))
+		},
+		Entry("list", http.MethodGet, "/api/conversations"),
+		Entry("save", http.MethodPut, "/api/conversations/c1"),
+		Entry("bulk", http.MethodPut, "/api/conversations/bulk"),
+	)
+
+	It("registers nothing without a store, so the UI falls back to localStorage", func() {
+		e := echo.New()
+		routes.RegisterChatHistoryRoutes(e, nil, auth.NoopMiddleware())
+		req := httptest.NewRequest(http.MethodGet, "/api/conversations", nil)
+		rec := httptest.NewRecorder()
+		e.ServeHTTP(rec, req)
+		Expect(rec.Code).To(Equal(http.StatusNotFound))
+	})
+
+	It("saves, lists, gets and deletes a conversation", func() {
+		rec := s.do("alice", http.MethodPut, "/api/conversations/c1", conversationBody("c1", "First"))
+		Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String())
+		saved := decodeJSON(rec)
+		Expect(saved["createdAt"]).NotTo(BeZero())
+		Expect(saved["updatedAt"]).NotTo(BeZero())
+
+		rec = s.do("alice", http.MethodPost, "/api/conversations", conversationBody("c2", "Second"))
+		Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String())
+
+		Expect(listedIDs(s.do("alice", http.MethodGet, "/api/conversations", nil))).To(ConsistOf("c1", "c2"))
+
+		rec = s.do("alice", http.MethodGet, "/api/conversations/c1", nil)
+		Expect(rec.Code).To(Equal(http.StatusOK))
+		got := decodeJSON(rec)
+		Expect(got["name"]).To(Equal("First"))
+		Expect(got["history"]).To(HaveLen(1))
+
+		Expect(s.do("alice", http.MethodDelete, "/api/conversations/c1", nil).Code).To(Equal(http.StatusOK))
+		Expect(listedIDs(s.do("alice", http.MethodGet, "/api/conversations", nil))).To(ConsistOf("c2"))
+	})
+
+	It("round-trips every field the UI stores on a chat", func() {
+		body := conversationBody("c1", "Assistant chat")
+		body["localaiAssistant"] = true
+		body["mcpMode"] = true
+		body["mcpServers"] = []string{"github"}
+		body["mcpResources"] = []string{"res://a"}
+		body["clientMCPServers"] = []map[string]any{{"id": "local", "url": "http://localhost:9000"}}
+		body["systemPrompt"] = "be brief"
+		body["temperature"] = 0.2
+		body["contextSize"] = 8192
+		body["reasoningEffort"] = "low"
+		Expect(s.do("alice", http.MethodPut, "/api/conversations/c1", body).Code).To(Equal(http.StatusOK))
+
+		rec := s.do("alice", http.MethodGet, "/api/conversations/c1", nil)
+		Expect(rec.Code).To(Equal(http.StatusOK))
+		got := decodeJSON(rec)
+		for _, key := range []string{"localaiAssistant", "mcpMode", "mcpServers", "mcpResources", "clientMCPServers", "systemPrompt", "temperature", "contextSize", "reasoningEffort"} {
+			Expect(got).To(HaveKey(key), "field %q was dropped", key)
+		}
+		Expect(got["localaiAssistant"]).To(BeTrue())
+		Expect(got["reasoningEffort"]).To(Equal("low"))
+	})
+
+	It("takes the id from the path over the body", func() {
+		rec := s.do("alice", http.MethodPut, "/api/conversations/from-path", conversationBody("from-body", "x"))
+		Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String())
+		Expect(listedIDs(s.do("alice", http.MethodGet, "/api/conversations", nil))).To(ConsistOf("from-path"))
+	})
+
+	It("returns 404 for an unknown conversation", func() {
+		Expect(s.do("alice", http.MethodGet, "/api/conversations/nope", nil).Code).To(Equal(http.StatusNotFound))
+	})
+
+	It("rejects malformed ids and bodies with 400", func() {
+		Expect(s.do("alice", http.MethodPut, "/api/conversations/bad!id", conversationBody("x", "x")).Code).To(Equal(http.StatusBadRequest))
+		Expect(s.do("alice", http.MethodGet, "/api/conversations/bad!id", nil).Code).To(Equal(http.StatusBadRequest))
+		Expect(s.do("alice", http.MethodDelete, "/api/conversations/bad!id", nil).Code).To(Equal(http.StatusBadRequest))
+		Expect(s.do("alice", http.MethodPost, "/api/conversations", `{"id":`).Code).To(Equal(http.StatusBadRequest))
+		Expect(s.do("alice", http.MethodPut, "/api/conversations/bulk", `{"conversations":`).Code).To(Equal(http.StatusBadRequest))
+		Expect(s.do("alice", http.MethodPut, "/api/conversations/bulk", map[string]any{
+			"conversations": []any{conversationBody("ok", "ok"), conversationBody("bad id", "x")},
+		}).Code).To(Equal(http.StatusBadRequest))
+	})
+
+	It("keeps users apart", func() {
+		Expect(s.do("alice", http.MethodPut, "/api/conversations/a1", conversationBody("a1", "alice")).Code).To(Equal(http.StatusOK))
+		Expect(listedIDs(s.do("bob", http.MethodGet, "/api/conversations", nil))).To(BeEmpty())
+		Expect(s.do("bob", http.MethodGet, "/api/conversations/a1", nil).Code).To(Equal(http.StatusNotFound))
+	})
+
+	It("replaces the whole set in bulk and wipes it on delete-all", func() {
+		Expect(s.do("alice", http.MethodPut, "/api/conversations/old", conversationBody("old", "old")).Code).To(Equal(http.StatusOK))
+
+		rec := s.do("alice", http.MethodPut, "/api/conversations/bulk", map[string]any{
+			"conversations": []any{conversationBody("n1", "n1"), conversationBody("n2", "n2")},
+		})
+		Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String())
+		Expect(decodeJSON(rec)["count"]).To(BeNumerically("==", 2))
+		Expect(listedIDs(s.do("alice", http.MethodGet, "/api/conversations", nil))).To(ConsistOf("n1", "n2"))
+
+		Expect(s.do("alice", http.MethodDelete, "/api/conversations", nil).Code).To(Equal(http.StatusOK))
+		Expect(listedIDs(s.do("alice", http.MethodGet, "/api/conversations", nil))).To(BeEmpty())
+	})
+
+	// Review on #9902: a conversation deleted on device A must not come back
+	// when device B, holding a stale copy, reconnects and writes it again.
+	Context("a stale client reconnecting after a remote deletion", func() {
+		It("gets 410 for the write, and the deletion stays visible to everyone", func() {
+			// Device A and device B both have c1.
+			Expect(s.do("alice", http.MethodPut, "/api/conversations/c1", conversationBody("c1", "shared")).Code).To(Equal(http.StatusOK))
+			// Device A deletes it.
+			Expect(s.do("alice", http.MethodDelete, "/api/conversations/c1", nil).Code).To(Equal(http.StatusOK))
+
+			// Device B comes back with its stale copy and pushes it.
+			rec := s.do("alice", http.MethodPut, "/api/conversations/c1", conversationBody("c1", "stale copy"))
+			Expect(rec.Code).To(Equal(http.StatusGone), rec.Body.String())
+			rec = s.do("alice", http.MethodPost, "/api/conversations", conversationBody("c1", "stale copy"))
+			Expect(rec.Code).To(Equal(http.StatusGone), rec.Body.String())
+
+			// The list keeps it out and tells B why, so B can drop its copy
+			// instead of treating it as an unsynced draft.
+			rec = s.do("alice", http.MethodGet, "/api/conversations", nil)
+			Expect(listedIDs(rec)).To(BeEmpty())
+			deleted := decodeJSON(rec)["deleted"].([]any)
+			Expect(deleted).To(HaveLen(1))
+			tomb := deleted[0].(map[string]any)
+			Expect(tomb["id"]).To(Equal("c1"))
+			Expect(tomb["deletedAt"]).To(BeNumerically(">", 0))
+			Expect(tomb["version"]).To(BeNumerically("==", 2))
+
+			Expect(s.do("alice", http.MethodGet, "/api/conversations/c1", nil).Code).To(Equal(http.StatusGone))
+		})
+
+		It("is not undone by a bulk upload either", func() {
+			Expect(s.do("alice", http.MethodPut, "/api/conversations/c1", conversationBody("c1", "shared")).Code).To(Equal(http.StatusOK))
+			Expect(s.do("alice", http.MethodDelete, "/api/conversations", nil).Code).To(Equal(http.StatusOK))
+
+			rec := s.do("alice", http.MethodPut, "/api/conversations/bulk", map[string]any{
+				"conversations": []any{conversationBody("c1", "stale"), conversationBody("fresh", "new")},
+			})
+			Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String())
+			body := decodeJSON(rec)
+			Expect(body["count"]).To(BeNumerically("==", 1))
+			Expect(body["skipped"]).To(ConsistOf("c1"))
+			Expect(listedIDs(s.do("alice", http.MethodGet, "/api/conversations", nil))).To(ConsistOf("fresh"))
+		})
+
+		It("holds even when the delete reached the server before the first save", func() {
+			Expect(s.do("alice", http.MethodDelete, "/api/conversations/never-saved", nil).Code).To(Equal(http.StatusOK))
+			Expect(s.do("alice", http.MethodPut, "/api/conversations/never-saved", conversationBody("never-saved", "late")).Code).To(Equal(http.StatusGone))
+		})
+
+		It("leaves a genuinely new conversation alone", func() {
+			Expect(s.do("alice", http.MethodPut, "/api/conversations/gone", conversationBody("gone", "x")).Code).To(Equal(http.StatusOK))
+			Expect(s.do("alice", http.MethodDelete, "/api/conversations/gone", nil).Code).To(Equal(http.StatusOK))
+
+			rec := s.do("alice", http.MethodPut, "/api/conversations/draft", conversationBody("draft", "new draft"))
+			Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String())
+			Expect(decodeJSON(rec)["version"]).To(BeNumerically("==", 1))
+			// A tombstone is per user: bob may use the same id.
+			Expect(s.do("bob", http.MethodPut, "/api/conversations/gone", conversationBody("gone", "bob")).Code).To(Equal(http.StatusOK))
+		})
+	})
+})

core/http/routes/localai.go

@@ -9,6 +9,7 @@ import (
 	mcpTools "github.com/mudler/LocalAI/core/http/endpoints/mcp"
 	"github.com/mudler/LocalAI/core/http/middleware"
 	"github.com/mudler/LocalAI/core/schema"
+	"github.com/mudler/LocalAI/core/services/chathistory"
 	compressionservice "github.com/mudler/LocalAI/core/services/compression"
 	"github.com/mudler/LocalAI/core/services/galleryop"
 	"github.com/mudler/LocalAI/core/services/monitoring"
@@ -33,7 +34,8 @@ func RegisterLocalAIRoutes(router *echo.Echo,
 	app *application.Application,
 	adminMiddleware echo.MiddlewareFunc,
 	mcpJobsMw echo.MiddlewareFunc,
-	mcpMw echo.MiddlewareFunc) {
+	mcpMw echo.MiddlewareFunc,
+	chatHistoryMw echo.MiddlewareFunc) {
 
 	// Themed index first, then the library's wildcard for its own assets.
 	RegisterSwaggerTheme(router)
@@ -572,4 +574,25 @@ func RegisterLocalAIRoutes(router *echo.Echo,
 		router.POST("/api/agent/tasks/:name/execute", localai.ExecuteTaskByNameEndpoint(app), mcpJobsMw)
 	}
 
+	// Chat history persistence (#9432). Skipped entirely when the store is
+	// nil (WebUI disabled or no auth database) — registering routes that
+	// could only ever fail adds surface area for nothing.
+	if app != nil {
+		RegisterChatHistoryRoutes(router, app.ChatHistoryStore(), chatHistoryMw)
+	}
+}
+
+// RegisterChatHistoryRoutes wires the per-user conversation endpoints. A nil
+// store registers nothing, so the React UI sees 404 and stays on localStorage.
+func RegisterChatHistoryRoutes(router *echo.Echo, store *chathistory.Store, chatHistoryMw echo.MiddlewareFunc) {
+	if store == nil {
+		return
+	}
+	router.GET("/api/conversations", localai.ListConversationsEndpoint(store), chatHistoryMw)
+	router.POST("/api/conversations", localai.SaveConversationEndpoint(store), chatHistoryMw)
+	router.DELETE("/api/conversations", localai.DeleteAllConversationsEndpoint(store), chatHistoryMw)
+	router.PUT("/api/conversations/bulk", localai.BulkReplaceConversationsEndpoint(store), chatHistoryMw)
+	router.GET("/api/conversations/:id", localai.GetConversationEndpoint(store), chatHistoryMw)
+	router.PUT("/api/conversations/:id", localai.SaveConversationByIDEndpoint(store), chatHistoryMw)
+	router.DELETE("/api/conversations/:id", localai.DeleteConversationEndpoint(store), chatHistoryMw)
 }

core/schema/chat_conversation.go

@@ -0,0 +1,78 @@
+package schema
+
+import (
+	"encoding/json"
+)
+
+// Conversation represents a chat conversation persisted server-side.
+// Issue #9432: enables chat history to survive browser refresh / device switch.
+//
+// The History field is intentionally json.RawMessage so the server stays
+// agnostic to message shape — the React UI mixes user / assistant / thinking /
+// tool_call / tool_result entries with text, image_url, audio_url, and file
+// attachments, and storing them opaquely avoids lossy round-trips.
+type Conversation struct {
+	ID               string          `json:"id"`
+	Name             string          `json:"name"`
+	Model            string          `json:"model,omitempty"`
+	History          json.RawMessage `json:"history,omitempty" swaggertype:"array,object"`
+	SystemPrompt     string          `json:"systemPrompt,omitempty"`
+	MCPMode          bool            `json:"mcpMode,omitempty"`
+	MCPServers       []string        `json:"mcpServers,omitempty"`
+	MCPResources     []string        `json:"mcpResources,omitempty"`
+	ClientMCPServers json.RawMessage `json:"clientMCPServers,omitempty" swaggertype:"array,object"`
+	// LocalAIAssistant wires the chat to the in-process admin MCP server
+	// (the LocalAI Assistant mode of the Chat page).
+	LocalAIAssistant bool     `json:"localaiAssistant,omitempty"`
+	Temperature      *float64 `json:"temperature,omitempty"`
+	TopP             *float64 `json:"topP,omitempty"`
+	TopK             *float64 `json:"topK,omitempty"`
+	// ReasoningEffort is the chat's reasoning_effort choice ('' = model config,
+	// 'none' also hides reasoning traces).
+	ReasoningEffort string            `json:"reasoningEffort,omitempty"`
+	TokenUsage      *ConvTokenUsage   `json:"tokenUsage,omitempty"`
+	ContextSize     *int              `json:"contextSize,omitempty"`
+	Metadata        map[string]string `json:"metadata,omitempty"`
+	CreatedAt       int64             `json:"createdAt"`
+	UpdatedAt       int64             `json:"updatedAt"`
+	// Version is assigned by the server: 1 on the first save, +1 on every
+	// later write including the delete. Clients use a non-zero version to
+	// tell a conversation the server has seen from a never-synced draft.
+	// Ignored on input.
+	Version int64 `json:"version,omitempty"`
+}
+
+// ConversationTombstone marks a conversation the user deleted. The server
+// keeps it (without content) so a client holding a stale copy can learn the
+// conversation is gone instead of uploading it again.
+type ConversationTombstone struct {
+	ID        string `json:"id"`
+	Version   int64  `json:"version"`
+	DeletedAt int64  `json:"deletedAt"` // Unix milliseconds
+}
+
+// ConversationList is the GET /api/conversations response.
+type ConversationList struct {
+	Conversations []Conversation          `json:"conversations"`
+	Deleted       []ConversationTombstone `json:"deleted"`
+}
+
+// ConversationBulkRequest is the PUT /api/conversations/bulk payload.
+type ConversationBulkRequest struct {
+	Conversations []Conversation `json:"conversations"`
+}
+
+// ConversationBulkResponse reports how many conversations a bulk replace
+// stored and which ids it refused because they had been deleted.
+type ConversationBulkResponse struct {
+	Status  string   `json:"status"`
+	Count   int      `json:"count"`
+	Skipped []string `json:"skipped"`
+}
+
+// ConvTokenUsage mirrors the React UI's tokenUsage object on each chat.
+type ConvTokenUsage struct {
+	Prompt     int `json:"prompt"`
+	Completion int `json:"completion"`
+	Total      int `json:"total"`
+}

core/schema/chat_conversation_ui_test.go

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT
+package schema_test
+
+import (
+	"os"
+	"reflect"
+	"regexp"
+	"strings"
+
+	"github.com/mudler/LocalAI/core/schema"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// Every key serializeChat sends needs a JSON field so persistence cannot
+// silently discard a chat setting.
+var _ = Describe("Conversation UI schema", func() {
+	It("keeps every field the UI sends", func() {
+		src, err := os.ReadFile("../http/react-ui/src/hooks/useChat.js")
+		Expect(err).NotTo(HaveOccurred(), "read useChat.js")
+		body := regexp.MustCompile(`(?s)function serializeChat\(chat\) \{\s*return \{(.*?)\n  \}`).FindSubmatch(src)
+		Expect(body).NotTo(BeNil(), "serializeChat not found in useChat.js")
+		sent := regexp.MustCompile(`(?m)^\s*(\w+):`).FindAllSubmatch(body[1], -1)
+		Expect(len(sent)).To(BeNumerically(">=", 10), "the serializeChat pattern no longer matches")
+
+		known := map[string]bool{}
+		ty := reflect.TypeOf(schema.Conversation{})
+		for i := 0; i < ty.NumField(); i++ {
+			if name := strings.Split(ty.Field(i).Tag.Get("json"), ",")[0]; name != "" {
+				known[name] = true
+			}
+		}
+		for _, m := range sent {
+			key := string(m[1])
+			Expect(known).To(HaveKey(key), "serializeChat sends %q but schema.Conversation has no field for it; the server drops it", key)
+		}
+	})
+})

core/services/chathistory/chathistory_suite_test.go

@@ -0,0 +1,13 @@
+package chathistory_test
+
+import (
+	"testing"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestChatHistory(t *testing.T) {
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "ChatHistory test suite")
+}

core/services/chathistory/store.go

@@ -0,0 +1,432 @@
+// Package chathistory implements server-side persistence of WebUI chat
+// conversations (GitHub issue #9432). Conversations live in the same
+// GORM-backed database as the rest of the per-user state (AgentStore,
+// JobStore): the store reuses Application.authDB so chat history,
+// agent configs and jobs land in one place. When auth is disabled the
+// store is not initialised and the React UI transparently falls back to
+// localStorage.
+package chathistory
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"regexp"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"github.com/mudler/LocalAI/core/schema"
+)
+
+var (
+	// ErrNotFound is returned when a conversation does not exist.
+	ErrNotFound = errors.New("conversation not found")
+	// ErrInvalidID is returned for malformed conversation IDs.
+	ErrInvalidID = errors.New("invalid conversation id")
+	// ErrInvalidUserID is returned for malformed user IDs.
+	ErrInvalidUserID = errors.New("invalid user id")
+	// ErrDeleted is returned when a conversation was deleted. Its tombstone
+	// stays so a client with a stale copy cannot write it back.
+	ErrDeleted = errors.New("conversation was deleted")
+	// ErrConflict is returned when concurrent writers kept racing on the
+	// same conversation and the write could not be settled.
+	ErrConflict = errors.New("conversation changed concurrently, retry")
+
+	// errRaced makes a transaction start over: another writer created the
+	// row between our lookup and our insert.
+	errRaced = errors.New("chathistory: raced with a concurrent create")
+)
+
+// maxTxAttempts bounds the retry loop for errRaced. One retry settles the
+// only race we expect (two first writes of the same id); the rest is margin.
+const maxTxAttempts = 3
+
+// idRegex constrains conversation IDs so they fit into the conv_id column
+// (size 128) and cannot smuggle whitespace or control characters into log
+// lines / responses. The React UI uses crypto-random IDs
+// (utils/format.generateId) which fit comfortably inside this class.
+var idRegex = regexp.MustCompile(`^[A-Za-z0-9._-]{1,128}$`)
+
+// userIDMaxLen caps the user ID length to match the user_id column size.
+// We don't constrain the character class because the auth subsystem chooses
+// the shape (UUID, OAuth subject, etc.) and SQL parameter binding already
+// prevents injection.
+const userIDMaxLen = 128
+
+// ConversationRecord is the GORM row representation of a chat conversation.
+//
+// The primary key is (UserID, ConvID): React mints conversation IDs locally
+// with no global coordination so they're only unique per user. A composite
+// key makes per-user partitioning fall out naturally — anonymous users
+// (UserID == "") get their own slice with no special-case code path.
+//
+// A row with DeletedAt set is a tombstone: the user deleted the conversation,
+// Content is emptied, and the row only stays so that no later write can
+// bring the conversation back. Version counts every write to the row.
+type ConversationRecord struct {
+	UserID    string         `gorm:"primaryKey;size:128;column:user_id"`
+	ConvID    string         `gorm:"primaryKey;size:128;column:conv_id"`
+	Content   string         `gorm:"type:text;column:content"`
+	Version   int64          `gorm:"not null;default:0;column:version"`
+	CreatedAt time.Time      `gorm:"column:created_at"`
+	UpdatedAt time.Time      `gorm:"index;column:updated_at"`
+	DeletedAt gorm.DeletedAt `gorm:"index;column:deleted_at"`
+}
+
+// TableName returns the database table name for ConversationRecord.
+func (ConversationRecord) TableName() string { return "chat_conversations" }
+
+// Store persists conversations to a GORM-backed database, partitioned by
+// userID. The empty string is treated as the anonymous (no-auth) user.
+type Store struct {
+	db *gorm.DB
+}
+
+// New creates a new Store backed by db and auto-migrates the schema. The
+// caller is expected to pass the shared authDB so chat history sits in
+// the same database as the other per-user state in LocalAI.
+func New(db *gorm.DB) (*Store, error) {
+	if db == nil {
+		return nil, errors.New("chathistory: nil *gorm.DB")
+	}
+	if err := db.AutoMigrate(&ConversationRecord{}); err != nil {
+		return nil, fmt.Errorf("chathistory: auto-migrate: %w", err)
+	}
+	return &Store{db: db}, nil
+}
+
+func validateID(id string) error {
+	if !idRegex.MatchString(id) {
+		return ErrInvalidID
+	}
+	return nil
+}
+
+func validateUserID(id string) error {
+	if len(id) > userIDMaxLen {
+		return ErrInvalidUserID
+	}
+	return nil
+}
+
+// List returns the live conversations for userID, sorted newest-updated first.
+// Deleted conversations are reported by Tombstones instead.
+func (s *Store) List(userID string) ([]schema.Conversation, error) {
+	if err := validateUserID(userID); err != nil {
+		return nil, err
+	}
+	var rows []ConversationRecord
+	if err := s.db.
+		Where("user_id = ?", userID).
+		Order("updated_at DESC").
+		Find(&rows).Error; err != nil {
+		return nil, fmt.Errorf("chathistory: list: %w", err)
+	}
+	out := make([]schema.Conversation, 0, len(rows))
+	for _, r := range rows {
+		c, err := decodeRecord(r)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, *c)
+	}
+	return out, nil
+}
+
+// Tombstones returns the conversations userID deleted, newest deletion first.
+func (s *Store) Tombstones(userID string) ([]schema.ConversationTombstone, error) {
+	if err := validateUserID(userID); err != nil {
+		return nil, err
+	}
+	var rows []ConversationRecord
+	if err := s.db.Unscoped().
+		Select("conv_id", "version", "deleted_at").
+		Where("user_id = ? AND deleted_at IS NOT NULL", userID).
+		Order("deleted_at DESC").
+		Find(&rows).Error; err != nil {
+		return nil, fmt.Errorf("chathistory: tombstones: %w", err)
+	}
+	out := make([]schema.ConversationTombstone, 0, len(rows))
+	for _, r := range rows {
+		out = append(out, schema.ConversationTombstone{
+			ID:        r.ConvID,
+			Version:   r.Version,
+			DeletedAt: r.DeletedAt.Time.UnixMilli(),
+		})
+	}
+	return out, nil
+}
+
+// Get returns a single conversation: ErrNotFound if it never existed,
+// ErrDeleted if the user deleted it.
+func (s *Store) Get(userID, id string) (*schema.Conversation, error) {
+	if err := validateUserID(userID); err != nil {
+		return nil, err
+	}
+	if err := validateID(id); err != nil {
+		return nil, err
+	}
+	row, err := lookup(s.db, userID, id)
+	if err != nil {
+		return nil, err
+	}
+	if row == nil {
+		return nil, ErrNotFound
+	}
+	if row.DeletedAt.Valid {
+		return nil, ErrDeleted
+	}
+	return decodeRecord(*row)
+}
+
+// Save upserts a conversation and returns it with its new Version. A
+// conversation the user deleted is never written again: Save returns
+// ErrDeleted, so a client holding a stale copy cannot resurrect it.
+//
+// CreatedAt and UpdatedAt are client-managed Unix milliseconds and are
+// stored as sent; the UI compares UpdatedAt across devices, so the server
+// clock must not replace it. Zero values are stamped with the current time,
+// and a zero CreatedAt on an update keeps the stored one.
+func (s *Store) Save(userID string, conv schema.Conversation) (*schema.Conversation, error) {
+	if err := validateUserID(userID); err != nil {
+		return nil, err
+	}
+	if err := validateID(conv.ID); err != nil {
+		return nil, err
+	}
+	var saved *schema.Conversation
+	err := s.transaction(func(tx *gorm.DB) error {
+		var err error
+		saved, err = saveInTx(tx, userID, conv)
+		return err
+	})
+	if err != nil {
+		return nil, err
+	}
+	return saved, nil
+}
+
+// saveInTx does the lookup and the write in the caller's transaction. The
+// version bump is a single UPDATE ... SET version = version + 1 guarded by
+// deleted_at IS NULL, so concurrent writers each count, and a delete that
+// commits between the lookup and the write still wins.
+func saveInTx(tx *gorm.DB, userID string, conv schema.Conversation) (*schema.Conversation, error) {
+	existing, err := lookup(tx, userID, conv.ID)
+	if err != nil {
+		return nil, err
+	}
+	if existing != nil && existing.DeletedAt.Valid {
+		return nil, ErrDeleted
+	}
+
+	now := time.Now().UnixMilli()
+	if conv.CreatedAt == 0 {
+		conv.CreatedAt = now
+		if existing != nil {
+			// Best-effort: a malformed previous row just gets a fresh stamp.
+			if prev, derr := decodeRecord(*existing); derr == nil && prev.CreatedAt != 0 {
+				conv.CreatedAt = prev.CreatedAt
+			}
+		}
+	}
+	if conv.UpdatedAt == 0 {
+		conv.UpdatedAt = now
+	}
+	// The version lives in its own column; keep it out of the stored JSON.
+	conv.Version = 0
+	data, err := json.Marshal(conv)
+	if err != nil {
+		return nil, fmt.Errorf("chathistory: marshal: %w", err)
+	}
+
+	if existing == nil {
+		res := tx.Clauses(clause.OnConflict{DoNothing: true}).Create(&ConversationRecord{
+			UserID:  userID,
+			ConvID:  conv.ID,
+			Content: string(data),
+			Version: 1,
+		})
+		if res.Error != nil {
+			return nil, fmt.Errorf("chathistory: insert: %w", res.Error)
+		}
+		if res.RowsAffected == 0 {
+			return nil, errRaced
+		}
+		conv.Version = 1
+		return &conv, nil
+	}
+
+	// The default scope adds deleted_at IS NULL.
+	res := tx.Model(&ConversationRecord{}).
+		Where("user_id = ? AND conv_id = ?", userID, conv.ID).
+		Updates(map[string]any{
+			"content": string(data),
+			"version": gorm.Expr("version + 1"),
+		})
+	if res.Error != nil {
+		return nil, fmt.Errorf("chathistory: update: %w", res.Error)
+	}
+	if res.RowsAffected == 0 {
+		return nil, ErrDeleted
+	}
+	var version int64
+	if err := tx.Model(&ConversationRecord{}).
+		Select("version").
+		Where("user_id = ? AND conv_id = ?", userID, conv.ID).
+		Scan(&version).Error; err != nil {
+		return nil, fmt.Errorf("chathistory: read version: %w", err)
+	}
+	conv.Version = version
+	return &conv, nil
+}
+
+// ReplaceAll makes convs the user's live conversation set in one
+// transaction: each one is upserted, and every other live conversation is
+// deleted (tombstoned, so the deletion reaches other devices too). Ids the
+// user already deleted are not written and are returned in skipped.
+func (s *Store) ReplaceAll(userID string, convs []schema.Conversation) (skipped []string, err error) {
+	if err := validateUserID(userID); err != nil {
+		return nil, err
+	}
+	for _, c := range convs {
+		if err := validateID(c.ID); err != nil {
+			return nil, err
+		}
+	}
+
+	err = s.transaction(func(tx *gorm.DB) error {
+		skipped = skipped[:0]
+		keep := make(map[string]struct{}, len(convs))
+		for _, c := range convs {
+			keep[c.ID] = struct{}{}
+			if _, err := saveInTx(tx, userID, c); err != nil {
+				if errors.Is(err, ErrDeleted) {
+					skipped = append(skipped, c.ID)
+					continue
+				}
+				return err
+			}
+		}
+
+		var live []string
+		if err := tx.Model(&ConversationRecord{}).
+			Where("user_id = ?", userID).
+			Pluck("conv_id", &live).Error; err != nil {
+			return fmt.Errorf("chathistory: replace list: %w", err)
+		}
+		var drop []string
+		for _, id := range live {
+			if _, ok := keep[id]; !ok {
+				drop = append(drop, id)
+			}
+		}
+		if len(drop) == 0 {
+			return nil
+		}
+		return tombstone(tx.Where("conv_id IN ?", drop), userID)
+	})
+	if err != nil {
+		return nil, err
+	}
+	return skipped, nil
+}
+
+// Delete deletes a conversation by turning it into a tombstone. Deleting is
+// idempotent, and deleting an id the server has not seen yet still records
+// a tombstone: the UI deletes immediately while a debounced save of the same
+// conversation may still be in flight, and that save must not win.
+func (s *Store) Delete(userID, id string) error {
+	if err := validateUserID(userID); err != nil {
+		return err
+	}
+	if err := validateID(id); err != nil {
+		return err
+	}
+	return s.transaction(func(tx *gorm.DB) error {
+		existing, err := lookup(tx, userID, id)
+		if err != nil {
+			return err
+		}
+		if existing == nil {
+			res := tx.Clauses(clause.OnConflict{DoNothing: true}).Create(&ConversationRecord{
+				UserID:    userID,
+				ConvID:    id,
+				Version:   1,
+				DeletedAt: gorm.DeletedAt{Time: time.Now(), Valid: true},
+			})
+			if res.Error != nil {
+				return fmt.Errorf("chathistory: delete: %w", res.Error)
+			}
+			if res.RowsAffected == 0 {
+				return errRaced
+			}
+			return nil
+		}
+		if existing.DeletedAt.Valid {
+			return nil
+		}
+		return tombstone(tx.Where("conv_id = ?", id), userID)
+	})
+}
+
+// DeleteAll deletes every conversation of a user, leaving tombstones so the
+// deletion reaches the user's other devices.
+func (s *Store) DeleteAll(userID string) error {
+	if err := validateUserID(userID); err != nil {
+		return err
+	}
+	return tombstone(s.db, userID)
+}
+
+// tombstone turns the user's live rows matched by scope into tombstones:
+// content dropped, version bumped, deleted_at set.
+func tombstone(scope *gorm.DB, userID string) error {
+	err := scope.Unscoped().
+		Model(&ConversationRecord{}).
+		Where("user_id = ? AND deleted_at IS NULL", userID).
+		Updates(map[string]any{
+			"content":    "",
+			"version":    gorm.Expr("version + 1"),
+			"deleted_at": time.Now(),
+		}).Error
+	if err != nil {
+		return fmt.Errorf("chathistory: delete: %w", err)
+	}
+	return nil
+}
+
+// transaction runs fn in a transaction and starts over when it lost a race
+// with a concurrent first write of the same id.
+func (s *Store) transaction(fn func(tx *gorm.DB) error) error {
+	for range maxTxAttempts {
+		err := s.db.Transaction(fn)
+		if !errors.Is(err, errRaced) {
+			return err
+		}
+	}
+	return ErrConflict
+}
+
+// lookup returns the row for (userID, id) including tombstones, or nil.
+func lookup(db *gorm.DB, userID, id string) (*ConversationRecord, error) {
+	var row ConversationRecord
+	err := db.Unscoped().Where("user_id = ? AND conv_id = ?", userID, id).Take(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("chathistory: lookup: %w", err)
+	}
+	return &row, nil
+}
+
+func decodeRecord(r ConversationRecord) (*schema.Conversation, error) {
+	var c schema.Conversation
+	if err := json.Unmarshal([]byte(r.Content), &c); err != nil {
+		return nil, fmt.Errorf("chathistory: unmarshal %q/%q: %w", r.UserID, r.ConvID, err)
+	}
+	c.Version = r.Version
+	return &c, nil
+}

core/services/chathistory/store_sqlite_test.go

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MIT
+//go:build auth
+
+package chathistory_test
+
+import (
+	"path/filepath"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"gorm.io/gorm"
+
+	"github.com/mudler/LocalAI/core/http/auth"
+)
+
+// SQLite is the default auth database. Opening it through auth.InitDB keeps
+// the production DSN (busy timeout, immediate transactions).
+var _ = Describe("Store on SQLite", func() {
+	describeStore(func() *gorm.DB {
+		db, err := auth.InitDB(filepath.Join(GinkgoT().TempDir(), "auth.db"))
+		Expect(err).NotTo(HaveOccurred())
+		sqlDB, err := db.DB()
+		Expect(err).NotTo(HaveOccurred())
+		DeferCleanup(sqlDB.Close)
+		return db
+	})
+})

core/services/chathistory/store_test.go

@@ -0,0 +1,365 @@
+package chathistory_test
+
+import (
+	"encoding/json"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	"gorm.io/gorm"
+
+	"github.com/mudler/LocalAI/core/schema"
+	"github.com/mudler/LocalAI/core/services/chathistory"
+	"github.com/mudler/LocalAI/core/services/testutil"
+)
+
+func newConv(id, name string) schema.Conversation {
+	history, _ := json.Marshal([]map[string]any{
+		{"role": "user", "content": "hi"},
+		{"role": "assistant", "content": "hello"},
+	})
+	return schema.Conversation{
+		ID:      id,
+		Name:    name,
+		Model:   "test-model",
+		History: history,
+	}
+}
+
+// The store runs on whichever database backs auth: SQLite by default,
+// PostgreSQL in distributed setups. Every spec runs against both so the
+// tombstone and version SQL cannot drift into one dialect.
+var _ = Describe("Store on PostgreSQL", func() {
+	describeStore(testutil.SetupTestDB)
+})
+
+func describeStore(openDB func() *gorm.DB) {
+	var (
+		db    *gorm.DB
+		store *chathistory.Store
+	)
+
+	BeforeEach(func() {
+		db = openDB()
+		var err error
+		store, err = chathistory.New(db)
+		Expect(err).NotTo(HaveOccurred())
+	})
+
+	Context("basic CRUD", func() {
+		const userID = "alice"
+
+		It("saves, lists, gets, and deletes a conversation", func() {
+			_, err := store.Save(userID, newConv("c1", "First"))
+			Expect(err).NotTo(HaveOccurred())
+			_, err = store.Save(userID, newConv("c2", "Second"))
+			Expect(err).NotTo(HaveOccurred())
+
+			list, err := store.List(userID)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(list).To(HaveLen(2))
+
+			got, err := store.Get(userID, "c1")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(got.Name).To(Equal("First"))
+			Expect(got.CreatedAt).NotTo(BeZero(), "Save should populate CreatedAt")
+			Expect(got.UpdatedAt).NotTo(BeZero(), "Save should populate UpdatedAt")
+
+			Expect(store.Delete(userID, "c1")).To(Succeed())
+			_, err = store.Get(userID, "c1")
+			Expect(err).To(MatchError(chathistory.ErrDeleted))
+		})
+	})
+
+	Context("persistence across Store instances", func() {
+		// Two Stores sharing the same *gorm.DB simulate a process restart:
+		// no shared in-memory state, so the second must read what the first
+		// wrote for the round-trip to succeed.
+		It("loads conversations written by a previous instance", func() {
+			first, err := chathistory.New(db)
+			Expect(err).NotTo(HaveOccurred())
+			_, err = first.Save("bob", newConv("x", "Hi"))
+			Expect(err).NotTo(HaveOccurred())
+
+			second, err := chathistory.New(db)
+			Expect(err).NotTo(HaveOccurred())
+			got, err := second.Get("bob", "x")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(got.Name).To(Equal("Hi"))
+		})
+	})
+
+	Context("user isolation", func() {
+		It("never leaks one user's data to another", func() {
+			_, err := store.Save("alice", newConv("a1", "alice's chat"))
+			Expect(err).NotTo(HaveOccurred())
+			_, err = store.Save("bob", newConv("b1", "bob's chat"))
+			Expect(err).NotTo(HaveOccurred())
+
+			bobList, err := store.List("bob")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(bobList).To(HaveLen(1))
+			Expect(bobList[0].ID).To(Equal("b1"))
+
+			_, err = store.Get("bob", "a1")
+			Expect(err).To(MatchError(chathistory.ErrNotFound))
+		})
+	})
+
+	Context("malformed IDs", func() {
+		// The DB-backed store no longer needs to defend against path
+		// traversal, but idRegex still rejects whitespace / control
+		// characters so IDs stay safe in logs and HTTP responses. The
+		// same payloads exercise the empty-string and over-length cases.
+		DescribeTable("rejects",
+			func(badID string) {
+				_, err := store.Save("alice", schema.Conversation{ID: badID, Name: "x"})
+				Expect(err).To(HaveOccurred())
+			},
+			Entry("path traversal", "../etc/passwd"),
+			Entry("forward slash", "a/b"),
+			Entry("back slash", "a\\b"),
+			Entry("empty id", ""),
+			Entry("contains spaces", "id with spaces"),
+		)
+	})
+
+	Context("ReplaceAll", func() {
+		// Bulk migration scenario: client uploads its entire conversation
+		// set in one shot, the store should overwrite anything previously
+		// there instead of merging.
+		It("overwrites the entire conversation set", func() {
+			const userID = "alice"
+			for _, id := range []string{"a", "b", "c"} {
+				_, err := store.Save(userID, newConv(id, id))
+				Expect(err).NotTo(HaveOccurred())
+			}
+
+			// Second return value (error) must be nil; the skipped list empty.
+			Expect(store.ReplaceAll(userID, []schema.Conversation{newConv("z", "z")})).To(BeEmpty())
+
+			list, err := store.List(userID)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(list).To(HaveLen(1))
+			Expect(list[0].ID).To(Equal("z"))
+		})
+	})
+
+	Context("anonymous user", func() {
+		// UserID == "" maps to the anonymous slice. We can no longer pin a
+		// directory layout (the previous file-based store wrote
+		// anonymous/conversations.json), so the test checks the round-trip
+		// and the per-user isolation guarantee instead.
+		It("stores and retrieves conversations for an empty user ID", func() {
+			_, err := store.Save("", newConv("solo", "anon chat"))
+			Expect(err).NotTo(HaveOccurred())
+
+			got, err := store.Get("", "solo")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(got.Name).To(Equal("anon chat"))
+
+			// And the conversation must NOT leak to a logged-in user.
+			_, err = store.Get("alice", "solo")
+			Expect(err).To(MatchError(chathistory.ErrNotFound))
+		})
+	})
+
+	Context("DeleteAll", func() {
+		It("wipes the user's entire chat history without touching others", func() {
+			_, err := store.Save("alice", newConv("a1", "alice 1"))
+			Expect(err).NotTo(HaveOccurred())
+			_, err = store.Save("alice", newConv("a2", "alice 2"))
+			Expect(err).NotTo(HaveOccurred())
+			_, err = store.Save("bob", newConv("b1", "bob 1"))
+			Expect(err).NotTo(HaveOccurred())
+
+			Expect(store.DeleteAll("alice")).To(Succeed())
+
+			aliceList, err := store.List("alice")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(aliceList).To(BeEmpty())
+
+			bobList, err := store.List("bob")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(bobList).To(HaveLen(1))
+		})
+	})
+	// A conversation deleted on one device must stay deleted when a client
+	// with a stale copy writes it again (review on #9902). Deletes leave a
+	// tombstone the store refuses to overwrite.
+	Context("tombstones", func() {
+		const userID = "alice"
+
+		It("rejects a save after delete instead of resurrecting the row", func() {
+			_, err := store.Save(userID, newConv("c1", "First"))
+			Expect(err).NotTo(HaveOccurred())
+			Expect(store.Delete(userID, "c1")).To(Succeed())
+
+			_, err = store.Save(userID, newConv("c1", "stale copy"))
+			Expect(err).To(MatchError(chathistory.ErrDeleted))
+
+			list, err := store.List(userID)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(list).To(BeEmpty())
+			Expect(tombstoneIDs(store, userID)).To(ConsistOf("c1"))
+			_, err = store.Get(userID, "c1")
+			Expect(err).To(MatchError(chathistory.ErrDeleted))
+		})
+
+		It("drops the content of a deleted conversation", func() {
+			_, err := store.Save(userID, newConv("c1", "secret"))
+			Expect(err).NotTo(HaveOccurred())
+			Expect(store.Delete(userID, "c1")).To(Succeed())
+
+			var row chathistory.ConversationRecord
+			Expect(db.Unscoped().Where("user_id = ? AND conv_id = ?", userID, "c1").Take(&row).Error).To(Succeed())
+			Expect(row.DeletedAt.Valid).To(BeTrue())
+			Expect(row.Content).To(BeEmpty())
+		})
+
+		It("records a delete that arrives before the conversation's first save", func() {
+			// The UI deletes right away while a debounced PUT may still be in
+			// flight; whichever lands second must not bring the chat back.
+			Expect(store.Delete(userID, "early")).To(Succeed())
+			_, err := store.Save(userID, newConv("early", "late write"))
+			Expect(err).To(MatchError(chathistory.ErrDeleted))
+		})
+
+		It("treats a repeated delete as success", func() {
+			_, err := store.Save(userID, newConv("c1", "First"))
+			Expect(err).NotTo(HaveOccurred())
+			Expect(store.Delete(userID, "c1")).To(Succeed())
+			Expect(store.Delete(userID, "c1")).To(Succeed())
+			Expect(tombstoneIDs(store, userID)).To(ConsistOf("c1"))
+		})
+
+		It("tombstones every conversation on DeleteAll", func() {
+			for _, id := range []string{"a", "b"} {
+				_, err := store.Save(userID, newConv(id, id))
+				Expect(err).NotTo(HaveOccurred())
+			}
+			_, err := store.Save("bob", newConv("a", "bob's a"))
+			Expect(err).NotTo(HaveOccurred())
+
+			Expect(store.DeleteAll(userID)).To(Succeed())
+			Expect(tombstoneIDs(store, userID)).To(ConsistOf("a", "b"))
+			_, err = store.Save(userID, newConv("a", "stale"))
+			Expect(err).To(MatchError(chathistory.ErrDeleted))
+
+			// bob shares the id, not the tombstone.
+			_, err = store.Save("bob", newConv("a", "bob again"))
+			Expect(err).NotTo(HaveOccurred())
+		})
+
+		It("does not let ReplaceAll resurrect deleted ids and tombstones what it replaces", func() {
+			for _, id := range []string{"a", "b"} {
+				_, err := store.Save(userID, newConv(id, id))
+				Expect(err).NotTo(HaveOccurred())
+			}
+			Expect(store.Delete(userID, "b")).To(Succeed())
+
+			skipped, err := store.ReplaceAll(userID, []schema.Conversation{newConv("b", "stale b"), newConv("c", "c")})
+			Expect(err).NotTo(HaveOccurred())
+			Expect(skipped).To(ConsistOf("b"))
+
+			list, err := store.List(userID)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(list).To(HaveLen(1))
+			Expect(list[0].ID).To(Equal("c"))
+			// "a" was replaced away: other devices must see it as deleted too.
+			Expect(tombstoneIDs(store, userID)).To(ConsistOf("a", "b"))
+		})
+	})
+
+	Context("versions", func() {
+		const userID = "alice"
+
+		It("starts at 1 and bumps on every write, including the delete", func() {
+			Expect(savedVersion(store, userID, newConv("c1", "v1"))).To(Equal(int64(1)))
+			Expect(savedVersion(store, userID, newConv("c1", "v2"))).To(Equal(int64(2)))
+
+			list, err := store.List(userID)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(list[0].Version).To(Equal(int64(2)))
+
+			Expect(store.Delete(userID, "c1")).To(Succeed())
+			tombs, err := store.Tombstones(userID)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(tombs).To(HaveLen(1))
+			Expect(tombs[0].Version).To(Equal(int64(3)))
+			Expect(tombs[0].DeletedAt).NotTo(BeZero())
+		})
+
+		It("ignores a client-supplied version", func() {
+			conv := newConv("c1", "x")
+			conv.Version = 41
+			Expect(savedVersion(store, userID, conv)).To(Equal(int64(1)))
+		})
+
+		It("counts every one of many concurrent writes", func() {
+			Expect(savedVersion(store, userID, newConv("hot", "seed"))).To(Equal(int64(1)))
+			const writers = 8
+			errs := make(chan error, writers)
+			for i := 0; i < writers; i++ {
+				go func() {
+					defer GinkgoRecover()
+					_, err := store.Save(userID, newConv("hot", "concurrent"))
+					errs <- err
+				}()
+			}
+			for i := 0; i < writers; i++ {
+				Expect(<-errs).NotTo(HaveOccurred())
+			}
+			got, err := store.Get(userID, "hot")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(got.Version).To(Equal(int64(1 + writers)))
+		})
+	})
+
+	Context("timestamps", func() {
+		const userID = "alice"
+
+		// The UI decides which copy is newer by comparing updatedAt across
+		// devices, so the server must store the client's value rather than
+		// its own clock.
+		It("keeps the client's updatedAt and createdAt", func() {
+			conv := newConv("c1", "x")
+			conv.CreatedAt = 1000
+			conv.UpdatedAt = 2000
+			_, err := store.Save(userID, conv)
+			Expect(err).NotTo(HaveOccurred())
+			got, err := store.Get(userID, "c1")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(got.CreatedAt).To(Equal(int64(1000)))
+			Expect(got.UpdatedAt).To(Equal(int64(2000)))
+		})
+
+		It("keeps the original createdAt when an update omits it", func() {
+			conv := newConv("c1", "x")
+			conv.CreatedAt = 1000
+			_, err := store.Save(userID, conv)
+			Expect(err).NotTo(HaveOccurred())
+			_, err = store.Save(userID, newConv("c1", "y"))
+			Expect(err).NotTo(HaveOccurred())
+			got, err := store.Get(userID, "c1")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(got.CreatedAt).To(Equal(int64(1000)))
+		})
+	})
+}
+
+func savedVersion(store *chathistory.Store, userID string, conv schema.Conversation) int64 {
+	saved, err := store.Save(userID, conv)
+	ExpectWithOffset(1, err).NotTo(HaveOccurred())
+	return saved.Version
+}
+
+func tombstoneIDs(store *chathistory.Store, userID string) []string {
+	tombs, err := store.Tombstones(userID)
+	ExpectWithOffset(1, err).NotTo(HaveOccurred())
+	ids := []string{}
+	for _, t := range tombs {
+		ids = append(ids, t.ID)
+	}
+	return ids
+}

docs/content/features/api-discovery.md

@@ -119,6 +119,7 @@ Returns a compact list of instruction areas:
 | `mcp` | Model Context Protocol - tool-augmented chat with MCP servers |
 | `agents` | Agent task and job management |
 | `video` | Video generation from text prompts |
+| `chat-history` | Server-side persistence of web UI chat conversations, with tombstones for deletions (auth only) |
 
 ### Get an instruction guide
 

docs/content/features/chat-history.md

@@ -0,0 +1,96 @@
++++
+disableToc = false
+title = "Chat History"
+weight = 49
+url = "/features/chat-history/"
++++
+
+Chat history keeps the conversations of the web UI [Chat]({{%relref "features/chat" %}}) page on the server, per user, so they survive a browser reset and follow you to another device. It is built on the [user authentication system]({{%relref "features/authentication" %}}): conversations live in the same database as users, sessions and API keys (SQLite by default, PostgreSQL when `LOCALAI_AUTH_DATABASE_URL` points at one).
+
+{{% notice note %}}
+Chat history is only active when user authentication is enabled (`LOCALAI_AUTH=true`). Without it, or with only legacy API keys, the endpoints below are not registered and the web UI keeps conversations in the browser (`localai_chats_data` in `localStorage`), as before. With it, the browser copy is kept per account (see [One browser cache per account](#one-browser-cache-per-account)). Disabling the web UI (`LOCALAI_DISABLE_WEBUI=true`) also disables chat history.
+{{% /notice %}}
+
+## Permission
+
+Access is controlled by the `chat_history` feature permission. Like the other API features it is **on by default** for new users; an admin can turn it off per user under **Settings → Users and keys**. A user without it gets `403` from every endpoint, and their web UI falls back to browser storage.
+
+## Deletions are final
+
+A deleted conversation must not come back because another device still has a copy. The server therefore keeps a **tombstone** for every deleted conversation: the row stays, its content is dropped, and it is marked deleted.
+
+- Writing a conversation that has a tombstone returns `410 Gone`. Nothing is written.
+- `GET /api/conversations` lists tombstones under `deleted`, so a client can drop its local copies of those ids instead of uploading them again.
+- `DELETE` is idempotent, and deleting an id the server has never seen still records a tombstone. A delete that overtakes an in-flight save of the same conversation therefore still wins.
+- Tombstones are per user. Another user can use the same id.
+
+Every conversation also carries a server-assigned `version`: `1` after the first save, then one more for every write, including the delete. A client that has a non-zero version for a conversation knows the server has seen it; a conversation without one is a draft that was never uploaded.
+
+Within a live conversation the last write wins: there is no merge of two devices editing the same conversation at the same time. `createdAt` and `updatedAt` (Unix milliseconds) are stored as the client sends them, so clients can compare `updatedAt` to pick the newer copy; the server only fills them in when they are `0`.
+
+## How the web UI syncs
+
+On load the Chat page asks the server for the list and reconciles it with what the browser has:
+
+- A conversation the server reports as deleted is removed locally.
+- A conversation on both sides keeps the copy with the newer `updatedAt`. A message you send while the list is still loading is kept, and uploaded afterwards.
+- A conversation only in the browser is uploaded if it has never been synced (no `version`). If it has a version but the server no longer has it, it is removed locally: it was synced before, so the server dropped it (or the browser now belongs to another account).
+- A conversation only on the server is added.
+- A conversation you delete while the list is still loading is deleted on the server once the list arrives.
+
+After that, every change is saved on its own (debounced, only conversations that changed). When a save returns `410`, the UI removes that conversation locally. On any other error it keeps the browser copy and tries again with the next change. `localStorage` stays a cache of the last state either way. The web UI does not use the bulk endpoint: every upload goes through the per-conversation save, so the tombstone check applies to each one.
+
+### Deletes wait for the server
+
+A delete (one conversation, **Clear all**, or a delete on the Home page) is removed from the screen at once, and kept in the browser as a pending delete until the server confirms it. If the server cannot be reached, the delete is sent again with the next change, when the browser comes back online, and on the next load; until then the list from the server cannot bring the conversation back. While a **Clear all** is pending, no conversation is uploaded, so a chat started after it is not caught by it.
+
+Clearing all chats immediately updates the browser cache, including unsynced drafts. You can leave the page without waiting for the server to confirm deletion.
+
+### One browser cache per account
+
+The browser cache belongs to the signed-in account: it is stored under `localai_chats_data:<user id>`, together with that account's pending deletes. When one account signs out and another signs in on the same browser, the second account starts from its own cache and its own server list. A conversation the first account could not upload yet (for example because its first save failed) stays in the first account's cache and is uploaded when that account signs in again; it is never uploaded into another account. Signing out does not delete the cache.
+
+Conversations stored in the browser before chat history was enabled live under the shared key `localai_chats_data`. When you are signed in, the Chat page does not read that key and does not upload it, because the browser cannot tell which account it belongs to. Without user authentication the web UI keeps using it, as before.
+
+## API
+
+All endpoints act on the conversations of the calling user and need a session or API key.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/conversations` | Live conversations (`conversations`, newest first) and tombstones (`deleted`) |
+| `POST` | `/api/conversations` | Save (upsert) the conversation in the body |
+| `PUT` | `/api/conversations/{id}` | Save (upsert); the path id overrides the body id |
+| `GET` | `/api/conversations/{id}` | One conversation; `404` if it never existed, `410` if it was deleted |
+| `DELETE` | `/api/conversations/{id}` | Delete, leaving a tombstone. Idempotent |
+| `DELETE` | `/api/conversations` | Delete all of the user's conversations, leaving tombstones |
+| `PUT` | `/api/conversations/bulk` | Make the payload the user's live set: upsert each conversation, delete (tombstone) the others. Ids that were deleted earlier are not written and come back in `skipped` |
+
+Status codes: `400` for a malformed id or body, `401` without credentials, `403` without the `chat_history` permission, `409` when concurrent writers kept racing on the same id (retry), `410` for a deleted conversation.
+
+Conversation ids are 1 to 128 characters from `A-Z a-z 0-9 . _ -`. A conversation carries what the Chat page keeps per chat: name, model, system prompt, sampling and reasoning-effort settings, MCP and LocalAI Assistant settings, token usage and context size (`schema.Conversation` in `/swagger`). The message list (`history`) is stored as sent, so every message shape the UI uses (text, images, audio, files, tool calls, thinking) survives the round trip.
+
+### Example
+
+```bash
+# Save a conversation
+curl -X PUT http://localhost:8080/api/conversations/3f9c2a \
+  -H "Authorization: Bearer $LOCALAI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"id":"3f9c2a","name":"Release notes","model":"qwen3-8b",
+       "history":[{"role":"user","content":"Summarise the changes"}],
+       "updatedAt":1760342400000}'
+# -> {"id":"3f9c2a", ..., "createdAt":1760342400000, "updatedAt":1760342400000, "version":1}
+
+# Delete it, then try to write it again from a stale client
+curl -X DELETE http://localhost:8080/api/conversations/3f9c2a -H "Authorization: Bearer $LOCALAI_API_KEY"
+curl -X PUT http://localhost:8080/api/conversations/3f9c2a \
+  -H "Authorization: Bearer $LOCALAI_API_KEY" -H "Content-Type: application/json" \
+  -d '{"id":"3f9c2a","name":"Release notes"}'
+# -> 410 {"error":"conversation was deleted"}
+
+curl http://localhost:8080/api/conversations -H "Authorization: Bearer $LOCALAI_API_KEY"
+# -> {"conversations":[],"deleted":[{"id":"3f9c2a","version":2,"deletedAt":1760342460000}]}
+```
+
+The machine-readable description is under the `chat-history` tag in the [API discovery]({{%relref "features/api-discovery" %}}) instructions (`GET /api/instructions/chat-history`) and in `/swagger`.

docs/content/features/chat.md

@@ -54,7 +54,7 @@ The microphone button dictates: click it to record, click again to stop, and the
 
 Press `Ctrl+K` (`Cmd+K`) or **Chats** to open the list of conversations, grouped by day like **Jump back in** on Home. Type to search names and message text. Arrow keys move, `Enter` opens, `F2` renames and `Delete` removes. Each row also offers rename, duplicate, copy and export. Removing a chat hides it and shows an **Undo** toast; the chat is deleted for good when the toast goes away. The name in the header can be renamed with a click.
 
-The history is stored in this browser (`localai_chats_data`), not on the server.
+The history is stored in this browser (`localai_chats_data`). When [user authentication]({{%relref "features/authentication" %}}) is enabled it is also kept on the server for each user and follows you to other devices; see [Chat History]({{%relref "features/chat-history" %}}).
 
 ## Settings
 

swagger/docs.go

@@ -881,6 +881,280 @@ const docTemplate = `{
                 }
             }
         },
+        "/api/conversations": {
+            "get": {
+                "description": "Returns the live conversations, newest first, and in ` + "`" + `deleted` + "`" + ` the conversations the user deleted. A client must drop any local copy whose id appears in ` + "`" + `deleted` + "`" + ` instead of uploading it again.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "chat-history"
+                ],
+                "summary": "List chat conversations",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/schema.ConversationList"
+                        }
+                    }
+                }
+            },
+            "post": {
+                "description": "Stores the conversation and returns it with its new server-assigned ` + "`" + `version` + "`" + `. ` + "`" + `createdAt` + "`" + `/` + "`" + `updatedAt` + "`" + ` are kept as sent (Unix ms). Writing a conversation the user deleted returns 410 and does not bring it back.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "chat-history"
+                ],
+                "summary": "Save a chat conversation (upsert)",
+                "parameters": [
+                    {
+                        "description": "Conversation payload",
+                        "name": "body",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/schema.Conversation"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/schema.Conversation"
+                        }
+                    },
+                    "400": {
+                        "description": "Invalid id or body",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    },
+                    "410": {
+                        "description": "Deleted",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                }
+            },
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "chat-history"
+                ],
+                "summary": "Delete all chat conversations for the current user",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/api/conversations/bulk": {
+            "put": {
+                "description": "Upserts every conversation in the payload and deletes the user's other live conversations. Ids the user deleted earlier are not written and are listed in ` + "`" + `skipped` + "`" + `.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "chat-history"
+                ],
+                "summary": "Replace all chat conversations",
+                "parameters": [
+                    {
+                        "description": "Conversations",
+                        "name": "body",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/schema.ConversationBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/schema.ConversationBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Invalid id or body",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/api/conversations/{id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "chat-history"
+                ],
+                "summary": "Get a chat conversation",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Conversation ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/schema.Conversation"
+                        }
+                    },
+                    "404": {
+                        "description": "Never existed",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    },
+                    "410": {
+                        "description": "Deleted",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                }
+            },
+            "put": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "chat-history"
+                ],
+                "summary": "Save a chat conversation by id (upsert)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Conversation ID (overrides the body id)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Conversation payload",
+                        "name": "body",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/schema.Conversation"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/schema.Conversation"
+                        }
+                    },
+                    "400": {
+                        "description": "Invalid id or body",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    },
+                    "410": {
+                        "description": "Deleted",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                }
+            },
+            "delete": {
+                "description": "Deletes the conversation and keeps a tombstone so no client can write it back. Deleting an unknown or already deleted id succeeds.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "chat-history"
+                ],
+                "summary": "Delete a chat conversation",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Conversation ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "Invalid id",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                }
+            }
+        },
         "/api/failover": {
             "get": {
                 "produces": [
@@ -6148,6 +6422,163 @@ const docTemplate = `{
                 }
             }
         },
+        "schema.ConvTokenUsage": {
+            "type": "object",
+            "properties": {
+                "completion": {
+                    "type": "integer"
+                },
+                "prompt": {
+                    "type": "integer"
+                },
+                "total": {
+                    "type": "integer"
+                }
+            }
+        },
+        "schema.Conversation": {
+            "type": "object",
+            "properties": {
+                "clientMCPServers": {
+                    "type": "array",
+                    "items": {
+                        "type": "object"
+                    }
+                },
+                "contextSize": {
+                    "type": "integer"
+                },
+                "createdAt": {
+                    "type": "integer"
+                },
+                "history": {
+                    "type": "array",
+                    "items": {
+                        "type": "object"
+                    }
+                },
+                "id": {
+                    "type": "string"
+                },
+                "localaiAssistant": {
+                    "description": "LocalAIAssistant wires the chat to the in-process admin MCP server\n(the LocalAI Assistant mode of the Chat page).",
+                    "type": "boolean"
+                },
+                "mcpMode": {
+                    "type": "boolean"
+                },
+                "mcpResources": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "mcpServers": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "metadata": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                },
+                "model": {
+                    "type": "string"
+                },
+                "name": {
+                    "type": "string"
+                },
+                "reasoningEffort": {
+                    "description": "ReasoningEffort is the chat's reasoning_effort choice ('' = model config,\n'none' also hides reasoning traces).",
+                    "type": "string"
+                },
+                "systemPrompt": {
+                    "type": "string"
+                },
+                "temperature": {
+                    "type": "number"
+                },
+                "tokenUsage": {
+                    "$ref": "#/definitions/schema.ConvTokenUsage"
+                },
+                "topK": {
+                    "type": "number"
+                },
+                "topP": {
+                    "type": "number"
+                },
+                "updatedAt": {
+                    "type": "integer"
+                },
+                "version": {
+                    "description": "Version is assigned by the server: 1 on the first save, +1 on every\nlater write including the delete. Clients use a non-zero version to\ntell a conversation the server has seen from a never-synced draft.\nIgnored on input.",
+                    "type": "integer"
+                }
+            }
+        },
+        "schema.ConversationBulkRequest": {
+            "type": "object",
+            "properties": {
+                "conversations": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/schema.Conversation"
+                    }
+                }
+            }
+        },
+        "schema.ConversationBulkResponse": {
+            "type": "object",
+            "properties": {
+                "count": {
+                    "type": "integer"
+                },
+                "skipped": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "status": {
+                    "type": "string"
+                }
+            }
+        },
+        "schema.ConversationList": {
+            "type": "object",
+            "properties": {
+                "conversations": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/schema.Conversation"
+                    }
+                },
+                "deleted": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/schema.ConversationTombstone"
+                    }
+                }
+            }
+        },
+        "schema.ConversationTombstone": {
+            "type": "object",
+            "properties": {
+                "deletedAt": {
+                    "description": "Unix milliseconds",
+                    "type": "integer"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "version": {
+                    "type": "integer"
+                }
+            }
+        },
         "schema.DecisionAnswer": {
             "type": "object",
             "properties": {

swagger/swagger.json

@@ -878,6 +878,280 @@
                 }
             }
         },
+        "/api/conversations": {
+            "get": {
+                "description": "Returns the live conversations, newest first, and in `deleted` the conversations the user deleted. A client must drop any local copy whose id appears in `deleted` instead of uploading it again.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "chat-history"
+                ],
+                "summary": "List chat conversations",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/schema.ConversationList"
+                        }
+                    }
+                }
+            },
+            "post": {
+                "description": "Stores the conversation and returns it with its new server-assigned `version`. `createdAt`/`updatedAt` are kept as sent (Unix ms). Writing a conversation the user deleted returns 410 and does not bring it back.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "chat-history"
+                ],
+                "summary": "Save a chat conversation (upsert)",
+                "parameters": [
+                    {
+                        "description": "Conversation payload",
+                        "name": "body",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/schema.Conversation"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/schema.Conversation"
+                        }
+                    },
+                    "400": {
+                        "description": "Invalid id or body",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    },
+                    "410": {
+                        "description": "Deleted",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                }
+            },
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "chat-history"
+                ],
+                "summary": "Delete all chat conversations for the current user",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/api/conversations/bulk": {
+            "put": {
+                "description": "Upserts every conversation in the payload and deletes the user's other live conversations. Ids the user deleted earlier are not written and are listed in `skipped`.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "chat-history"
+                ],
+                "summary": "Replace all chat conversations",
+                "parameters": [
+                    {
+                        "description": "Conversations",
+                        "name": "body",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/schema.ConversationBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/schema.ConversationBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Invalid id or body",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/api/conversations/{id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "chat-history"
+                ],
+                "summary": "Get a chat conversation",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Conversation ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/schema.Conversation"
+                        }
+                    },
+                    "404": {
+                        "description": "Never existed",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    },
+                    "410": {
+                        "description": "Deleted",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                }
+            },
+            "put": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "chat-history"
+                ],
+                "summary": "Save a chat conversation by id (upsert)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Conversation ID (overrides the body id)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Conversation payload",
+                        "name": "body",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/schema.Conversation"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/schema.Conversation"
+                        }
+                    },
+                    "400": {
+                        "description": "Invalid id or body",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    },
+                    "410": {
+                        "description": "Deleted",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                }
+            },
+            "delete": {
+                "description": "Deletes the conversation and keeps a tombstone so no client can write it back. Deleting an unknown or already deleted id succeeds.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "chat-history"
+                ],
+                "summary": "Delete a chat conversation",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Conversation ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "Invalid id",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                }
+            }
+        },
         "/api/failover": {
             "get": {
                 "produces": [
@@ -6145,6 +6419,163 @@
                 }
             }
         },
+        "schema.ConvTokenUsage": {
+            "type": "object",
+            "properties": {
+                "completion": {
+                    "type": "integer"
+                },
+                "prompt": {
+                    "type": "integer"
+                },
+                "total": {
+                    "type": "integer"
+                }
+            }
+        },
+        "schema.Conversation": {
+            "type": "object",
+            "properties": {
+                "clientMCPServers": {
+                    "type": "array",
+                    "items": {
+                        "type": "object"
+                    }
+                },
+                "contextSize": {
+                    "type": "integer"
+                },
+                "createdAt": {
+                    "type": "integer"
+                },
+                "history": {
+                    "type": "array",
+                    "items": {
+                        "type": "object"
+                    }
+                },
+                "id": {
+                    "type": "string"
+                },
+                "localaiAssistant": {
+                    "description": "LocalAIAssistant wires the chat to the in-process admin MCP server\n(the LocalAI Assistant mode of the Chat page).",
+                    "type": "boolean"
+                },
+                "mcpMode": {
+                    "type": "boolean"
+                },
+                "mcpResources": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "mcpServers": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "metadata": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                },
+                "model": {
+                    "type": "string"
+                },
+                "name": {
+                    "type": "string"
+                },
+                "reasoningEffort": {
+                    "description": "ReasoningEffort is the chat's reasoning_effort choice ('' = model config,\n'none' also hides reasoning traces).",
+                    "type": "string"
+                },
+                "systemPrompt": {
+                    "type": "string"
+                },
+                "temperature": {
+                    "type": "number"
+                },
+                "tokenUsage": {
+                    "$ref": "#/definitions/schema.ConvTokenUsage"
+                },
+                "topK": {
+                    "type": "number"
+                },
+                "topP": {
+                    "type": "number"
+                },
+                "updatedAt": {
+                    "type": "integer"
+                },
+                "version": {
+                    "description": "Version is assigned by the server: 1 on the first save, +1 on every\nlater write including the delete. Clients use a non-zero version to\ntell a conversation the server has seen from a never-synced draft.\nIgnored on input.",
+                    "type": "integer"
+                }
+            }
+        },
+        "schema.ConversationBulkRequest": {
+            "type": "object",
+            "properties": {
+                "conversations": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/schema.Conversation"
+                    }
+                }
+            }
+        },
+        "schema.ConversationBulkResponse": {
+            "type": "object",
+            "properties": {
+                "count": {
+                    "type": "integer"
+                },
+                "skipped": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "status": {
+                    "type": "string"
+                }
+            }
+        },
+        "schema.ConversationList": {
+            "type": "object",
+            "properties": {
+                "conversations": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/schema.Conversation"
+                    }
+                },
+                "deleted": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/schema.ConversationTombstone"
+                    }
+                }
+            }
+        },
+        "schema.ConversationTombstone": {
+            "type": "object",
+            "properties": {
+                "deletedAt": {
+                    "description": "Unix milliseconds",
+                    "type": "integer"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "version": {
+                    "type": "integer"
+                }
+            }
+        },
         "schema.DecisionAnswer": {
             "type": "object",
             "properties": {

swagger/swagger.yaml

@@ -1013,6 +1013,118 @@ definitions:
       summary_tokens:
         type: integer
     type: object
+  schema.ConvTokenUsage:
+    properties:
+      completion:
+        type: integer
+      prompt:
+        type: integer
+      total:
+        type: integer
+    type: object
+  schema.Conversation:
+    properties:
+      clientMCPServers:
+        items:
+          type: object
+        type: array
+      contextSize:
+        type: integer
+      createdAt:
+        type: integer
+      history:
+        items:
+          type: object
+        type: array
+      id:
+        type: string
+      localaiAssistant:
+        description: |-
+          LocalAIAssistant wires the chat to the in-process admin MCP server
+          (the LocalAI Assistant mode of the Chat page).
+        type: boolean
+      mcpMode:
+        type: boolean
+      mcpResources:
+        items:
+          type: string
+        type: array
+      mcpServers:
+        items:
+          type: string
+        type: array
+      metadata:
+        additionalProperties:
+          type: string
+        type: object
+      model:
+        type: string
+      name:
+        type: string
+      reasoningEffort:
+        description: |-
+          ReasoningEffort is the chat's reasoning_effort choice ('' = model config,
+          'none' also hides reasoning traces).
+        type: string
+      systemPrompt:
+        type: string
+      temperature:
+        type: number
+      tokenUsage:
+        $ref: '#/definitions/schema.ConvTokenUsage'
+      topK:
+        type: number
+      topP:
+        type: number
+      updatedAt:
+        type: integer
+      version:
+        description: |-
+          Version is assigned by the server: 1 on the first save, +1 on every
+          later write including the delete. Clients use a non-zero version to
+          tell a conversation the server has seen from a never-synced draft.
+          Ignored on input.
+        type: integer
+    type: object
+  schema.ConversationBulkRequest:
+    properties:
+      conversations:
+        items:
+          $ref: '#/definitions/schema.Conversation'
+        type: array
+    type: object
+  schema.ConversationBulkResponse:
+    properties:
+      count:
+        type: integer
+      skipped:
+        items:
+          type: string
+        type: array
+      status:
+        type: string
+    type: object
+  schema.ConversationList:
+    properties:
+      conversations:
+        items:
+          $ref: '#/definitions/schema.Conversation'
+        type: array
+      deleted:
+        items:
+          $ref: '#/definitions/schema.ConversationTombstone'
+        type: array
+    type: object
+  schema.ConversationTombstone:
+    properties:
+      deletedAt:
+        description: Unix milliseconds
+        type: integer
+      id:
+        type: string
+      version:
+        type: integer
+    type: object
   schema.DecisionAnswer:
     properties:
       choice:
@@ -4371,6 +4483,193 @@ paths:
       summary: Upload a branding asset
       tags:
       - branding
+  /api/conversations:
+    delete:
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties:
+              type: string
+            type: object
+      summary: Delete all chat conversations for the current user
+      tags:
+      - chat-history
+    get:
+      description: Returns the live conversations, newest first, and in `deleted`
+        the conversations the user deleted. A client must drop any local copy whose
+        id appears in `deleted` instead of uploading it again.
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/schema.ConversationList'
+      summary: List chat conversations
+      tags:
+      - chat-history
+    post:
+      consumes:
+      - application/json
+      description: Stores the conversation and returns it with its new server-assigned
+        `version`. `createdAt`/`updatedAt` are kept as sent (Unix ms). Writing a conversation
+        the user deleted returns 410 and does not bring it back.
+      parameters:
+      - description: Conversation payload
+        in: body
+        name: body
+        required: true
+        schema:
+          $ref: '#/definitions/schema.Conversation'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/schema.Conversation'
+        "400":
+          description: Invalid id or body
+          schema:
+            additionalProperties:
+              type: string
+            type: object
+        "410":
+          description: Deleted
+          schema:
+            additionalProperties:
+              type: string
+            type: object
+      summary: Save a chat conversation (upsert)
+      tags:
+      - chat-history
+  /api/conversations/{id}:
+    delete:
+      description: Deletes the conversation and keeps a tombstone so no client can
+        write it back. Deleting an unknown or already deleted id succeeds.
+      parameters:
+      - description: Conversation ID
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties:
+              type: string
+            type: object
+        "400":
+          description: Invalid id
+          schema:
+            additionalProperties:
+              type: string
+            type: object
+      summary: Delete a chat conversation
+      tags:
+      - chat-history
+    get:
+      parameters:
+      - description: Conversation ID
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/schema.Conversation'
+        "404":
+          description: Never existed
+          schema:
+            additionalProperties:
+              type: string
+            type: object
+        "410":
+          description: Deleted
+          schema:
+            additionalProperties:
+              type: string
+            type: object
+      summary: Get a chat conversation
+      tags:
+      - chat-history
+    put:
+      consumes:
+      - application/json
+      parameters:
+      - description: Conversation ID (overrides the body id)
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: Conversation payload
+        in: body
+        name: body
+        required: true
+        schema:
+          $ref: '#/definitions/schema.Conversation'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/schema.Conversation'
+        "400":
+          description: Invalid id or body
+          schema:
+            additionalProperties:
+              type: string
+            type: object
+        "410":
+          description: Deleted
+          schema:
+            additionalProperties:
+              type: string
+            type: object
+      summary: Save a chat conversation by id (upsert)
+      tags:
+      - chat-history
+  /api/conversations/bulk:
+    put:
+      consumes:
+      - application/json
+      description: Upserts every conversation in the payload and deletes the user's
+        other live conversations. Ids the user deleted earlier are not written and
+        are listed in `skipped`.
+      parameters:
+      - description: Conversations
+        in: body
+        name: body
+        required: true
+        schema:
+          $ref: '#/definitions/schema.ConversationBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/schema.ConversationBulkResponse'
+        "400":
+          description: Invalid id or body
+          schema:
+            additionalProperties:
+              type: string
+            type: object
+      summary: Replace all chat conversations
+      tags:
+      - chat-history
   /api/failover:
     get:
       produces: