feat: persist chat conversations server-side (#9432) by TLoE419 · Pull Request #9902 · mudler/LocalAI

TLoE419 · 2026-05-19T21:33:37Z

Description

This PR fixes #9432

Chat conversations in the WebUI previously lived only in browser localStorage. Switching browsers, opening an incognito window, or clearing site data wiped the user's entire chat history. This PR adds server-side persistence so chats survive across browsers / devices when the WebUI is enabled.

What changed

core/services/chathistory — new file-based, per-user persister at {DataPath|DynamicConfigsDir}/chat_history/{userID}/conversations.json (anonymous/ when auth is disabled). Atomic writes via tmp file + os.Rename so a crash mid-save never leaves a corrupted history.
/api/conversations CRUD endpoints — GET / POST / PUT / DELETE plus PUT /api/conversations/bulk for first-time localStorage migration. All endpoints are user-scoped via getUserID(c); callers cannot impersonate other users.
chat_history feature permission (default ON in APIFeatures), registered through the existing RouteFeatureRegistry so the unified feature middleware picks it up automatically.
React useChat hook — probes /api/conversations on mount. Server becomes authoritative when reachable; on 404 the hook silently falls back to the old localStorage-only behaviour, so this is fully backward-compatible.
Tests — Ginkgo/Gomega suite covering round-trip across instances, user isolation, path-traversal rejection, anonymous fallback, and bulk-replace overwrite. Existing api_instructions test updated for the new entry.
Discoverability — new chat-history instruction entry surfaces in /api/instructions, plus matching Swagger tag.

Notes for Reviewers

The issue reporter expected one of (1) chat persists, (2) clear docs, or (3) a configurable option. This PR delivers (1) automatically whenever DataPath resolves — no env vars to set.
Fully backward-compatible: when DisableWebUI=true or no persistence path resolves, Application.ChatHistoryStore() returns nil, route registration is skipped, and the React hook detects 404 to fall back to localStorage. Older deployments and disabled feature both keep working unchanged.
History is stored as json.RawMessage so the server stays agnostic to React message shapes — user / assistant / thinking / tool_call / tool_result roles mixed with text / image_url / audio_url / file attachments all round-trip lossless.
The atomic /bulk endpoint avoids partial-upload states where a retry would skip already-uploaded entries — important for the localStorage migration which only fires when the server is empty.
Auth disabled: all anonymous users share anonymous/conversations.json. Matches expected single-user-deployment behavior; per-user isolation kicks in automatically once auth is enabled.

Test plan

`go test ./core/services/chathistory/...` — passes (Ginkgo/Gomega)
`go test ./core/http/endpoints/localai/...` — passes
`make build` succeeds in a clean worktree
Manual: CRUD via curl against running server
Manual: WebUI in incognito window sees chats persisted by another window (issue feat: persist Chat History server-side #9432 repro)
Manual: `localStorage.clear()` + reload still shows server-side history
Manual: side-by-side vs. older binary (v4.1.3) confirms the React 404 fallback path

Signed commits

Yes, I signed my commits.

mudler · 2026-05-20T20:10:06Z

+
+// userFile returns the on-disk path for a user's conversations file.
+func (s *Store) userFile(userID string) string {
+	return filepath.Join(s.userDir(userID), "conversations.json")


this is fine in the case the user does not specify any DB. but IF we are adding this feature we should be consistent here and store the conversations in the DB

mudler · 2026-05-20T20:10:46Z

+	baseDir string
+
+	mu    sync.Mutex
+	cache map[string]map[string]schema.Conversation // userID -> id -> conv


this calls for a TTL or a mechanism to not grow this idenfinitely in memory

Addresses mudler's review on mudler#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]

Addresses mudler's review on mudler#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>

TLoE419 · 2026-05-26T20:35:11Z

Reworked the store to use Application.authDB via a new ConversationRecord GORM model — addresses your DB-consistency comment and removes the unbounded in-memory map. Also rebased on master so the branch is mergeable.

Addresses mudler's review on mudler#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>

localai-org-maint-bot

Blocking cross-device consistency issue: preserves every local-only conversation, and the next debounced pass writes it back to the server. If a user deletes a conversation on device A, then opens device B with a stale localStorage copy, device B treats that deleted chat as an unsaved draft and silently resurrects it server-side. The server cannot be authoritative across devices without distinguishing a genuinely new local draft from a server-side deletion (for example via migration state/tombstones/versioning). Please address that case and add a UI/API regression for a stale client reconnecting after a remote deletion.

Persist WebUI chat conversations server-side so browser refresh, private windows, or device changes preserve user history (issue mudler#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>

…#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>

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>

mudler#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>

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>

Addresses mudler's review on mudler#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>

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>

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>

localai-org-maint-bot · 2026-09-03T16:41:09Z

Review pass. The build quality is decent and the rebase cost is low, but there is one question we owe you an answer to before asking for more work.

The question you raised and nobody answered. application.go:618 gates the store on !DisableWebUI && a.authDB != nil, and routes/localai.go:494 skips registration otherwise. LocalAI defaults to auth disabled, so for most installs this feature is a no-op and the UI silently stays on localStorage. You flagged exactly this in the 4d144fba commit message. That needs a maintainer decision before the rest matters.

Rebase is not the problem: git merge-tree auto-merges cleanly despite 349 master commits, 82 of which touch react-ui/src.

Open items from the 2026-07-29 review (the 08-03 push was a pure rebase):

Cross-device resurrection. useChat.js:97-104 unconditionally preserves every local-only conversation and :186-200 re-PUTs it on the next debounce. Delete a chat on a laptop, open a phone with stale localStorage, and the chat comes back on both. This needs a design answer (tombstones, or a version), not a patch.
First-load overwrite of in-flight edits. useChat.js:173 makes remote win for any shared id with no updatedAt comparison, and the probe is async and unawaited. On a slow server, a message sent inside the probe window vanishes from state and then from localStorage.
Save-after-delete looks like a 500. Delete (store.go:245-265) soft-deletes; Save (store.go:158) looks up under the soft-delete scope, gets ErrRecordNotFound, then db.Save at :192 should fall through to INSERT and violate the (user_id, conv_id) primary key. That is exactly the path a stale client takes, and no test covers delete-then-save either way. Confirming needs the suite (Docker/testcontainers).
Read-modify-write race in Save. store.go:158 reads and :192 writes outside any transaction, just to recover CreatedAt. The comment at :189-191 claims the upsert keeps Save() race-free, which is true of the write but not of the preceding read. ReplaceAll gets this right with a transaction at :230.
Docs and swagger. No docs/content/ change for seven endpoints and a new default-ON feature permission, no chat-history row in the Available instructions: table at docs/content/features/api-discovery.md:108-120, and swagger/docs.go / swagger.json / swagger.yaml are tracked but untouched, so make swagger was not run.
CI has never run here. Nine runs expired unapproved, so lint, the Go suite, UI E2E and both coverage ratchets are unverified. Coverage is a real risk: chat_history.go is 161 lines and 7 handlers with no unit tests, against a 54.2 baseline with zero tolerance, plus roughly 100 untested lines in useChat.js against a 40.0 UI baseline with no useChat spec in the repo.

Credit where due: the API surface checklist is well done (swagger @Tags, the app.go:126-127 tag block, instructionDefs with the HaveLen(19) to HaveLen(20) bump, RouteFeatureRegistry rows, FeatureChatHistory plus APIFeatureMetas()), capabilities.js is correctly untouched, and skipping MCP tools is right since .agents/localai-assistant-mcp.md scopes that to RequireAdmin endpoints. Worth saying so in the PR body.

One field drift: serializeChat (useChat.js:54-75) omits localaiAssistant, which master's createNewChat now sets and schema.Conversation has no field for, so a chat with the Assistant toggle on comes back off after a server reload.

localai-org-maint-bot

Detailed review findings:

Blocking issues:

Cross-device resurrection (confirmed) — mergeRemoteAndLocal in useChat.js unconditionally preserves local-only conversations. I empirically verified the server-side half: GORM Save after a soft-delete resurrects the row (deleted_at cleared, created_at preserved). A stale client re-PUTting a deleted conversation brings it back for all devices. Needs tombstone/versioning as mudler requested.
First-load overwrite of in-flight edits — useChat.js:~173 remote wins for any shared id with no updatedAt comparison, and the probe is async/unawaited. A message sent during the probe window is clobbered by the stale remote copy.
Docs-with-code rule violated — No docs/content/ update. Swagger files (swagger/docs.go, swagger.json, swagger.yaml) are tracked but untouched → make swagger was never run despite new @Tags/@Router annotations.
Test gaps — No HTTP endpoint tests for chat_history.go (7 handlers), no test for the delete-then-save resurrection path, no useChat.js spec. CI has never run (9 runs expired unapproved).
Default deployment no-op — authDB is only initialized when options.Auth.Enabled; LocalAI defaults to auth disabled → the feature is a no-op in default deployments. Needs a maintainer decision.

Non-blocking: serializeChat omits localaiAssistant field (lost on reload). Save has a read-modify-write race outside a transaction.

Done well: API-surface checklist is exemplary (swagger tags, instructions registry, RouteFeatureRegistry, APIFeatures). Security is sound (no impersonation, regex validation, parameterized queries). DCO + AI-attribution compliant. Architecture fits LocalAI (reuses authDB).

Please address the resurrection/in-flight-edit bugs, regenerate swagger, add docs + tests, and re-run CI.

walcz-de · 2026-10-13T06:57:49Z

Hi @TLoE419, thanks for this PR — server-side chat history is something we'd really like to see land (we run LocalAI with
LOCALAI_AUTH for a small team and the localStorage-only history is the main thing keeping us on a separate chat UI).

The open review points look addressable: tombstones/versioning so a stale client can't resurrect a deleted conversation,
an updatedAt comparison on first load, delete-then-save handling in Save (inside the transaction), plus docs and
swagger. If you don't have the time to pick this up again, would you be OK with us continuing on top of your branch
(keeping your commits and authorship)? @mudler — would that work for you as well, or would you prefer a fresh PR that
references this one?

Happy to coordinate either way.

mudler · 2026-10-13T07:05:32Z

@walcz-de either works for me, I'm happy to help in review and getting merged

walcz-de · 2026-10-13T08:10:28Z

Thanks! We'll give @TLoE419 until Thursday to reply, then open a follow-up PR on top of this branch (keeping their commits) and link it here.

walcz-de · 2026-10-13T08:45:48Z

Since the work was ready earlier, we opened it now as #12663 (on top of this branch, your commits and authorship kept). @TLoE419, happy to hand it back if you want to continue yourself.

TLoE419 · 2026-10-13T23:26:11Z

Hi @walcz-de, thank you for picking this up and helping bring server-side chat history across the finish line! I’m happy for you to continue building on my branch, with my commits and authorship preserved as you proposed. I appreciate your work on the remaining review points and your willingness to coordinate.

…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 03cd9c1'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>

TLoE419 marked this pull request as ready for review May 19, 2026 21:37

mudler reviewed May 20, 2026

View reviewed changes

mudler added the waiting-from-reporter label May 20, 2026

TLoE419 force-pushed the feature/persist-chat-history-server-side branch from 4b37339 to cbb67e8 Compare May 26, 2026 16:52

TLoE419 force-pushed the feature/persist-chat-history-server-side branch from cbb67e8 to e6109ec Compare May 26, 2026 20:31

TLoE419 requested a review from mudler May 26, 2026 20:35

localai-org-maint-bot force-pushed the feature/persist-chat-history-server-side branch from e6109ec to 3fb6546 Compare July 29, 2026 07:08

localai-org-maint-bot requested changes Jul 29, 2026

View reviewed changes

TLoE419 added 8 commits August 3, 2026 18:05

localai-org-maint-bot force-pushed the feature/persist-chat-history-server-side branch from 1197046 to 5719a16 Compare August 3, 2026 18:08

localai-org-maint-bot requested changes Sep 11, 2026

View reviewed changes

walcz-de mentioned this pull request Oct 13, 2026

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

Merged

4 tasks done

walcz-de mentioned this pull request Oct 15, 2026

Server-side MCP tool trail is lost between turns #12712

Open

Navigation Menu

Repository navigation

feat: persist chat conversations server-side (#9432) - #9902

feat: persist chat conversations server-side (#9432)#9902
TLoE419 wants to merge 8 commits into
mudler:masterfrom
shihyunhuang:feature/persist-chat-history-server-side

TLoE419 commented May 19, 2026

Uh oh!

mudler May 20, 2026

Uh oh!

mudler May 20, 2026

Uh oh!

TLoE419 commented May 26, 2026

Uh oh!

localai-org-maint-bot left a comment

Uh oh!

localai-org-maint-bot commented Sep 3, 2026

Uh oh!

localai-org-maint-bot left a comment

Uh oh!

walcz-de commented Oct 13, 2026

Uh oh!

mudler commented Oct 13, 2026

Uh oh!

walcz-de commented Oct 13, 2026

Uh oh!

walcz-de commented Oct 13, 2026

Uh oh!

TLoE419 commented Oct 13, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

TLoE419 commented May 19, 2026

What changed

Notes for Reviewers

Test plan

Uh oh!

mudler May 20, 2026

Choose a reason for hiding this comment

Uh oh!

mudler May 20, 2026

Choose a reason for hiding this comment

Uh oh!

TLoE419 commented May 26, 2026

Uh oh!

localai-org-maint-bot left a comment

Choose a reason for hiding this comment

Uh oh!

localai-org-maint-bot commented Sep 3, 2026

Uh oh!

localai-org-maint-bot left a comment

Choose a reason for hiding this comment

Uh oh!

walcz-de commented Oct 13, 2026

Uh oh!

mudler commented Oct 13, 2026

Uh oh!

walcz-de commented Oct 13, 2026

Uh oh!

walcz-de commented Oct 13, 2026

Uh oh!

TLoE419 commented Oct 13, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants