Skip to content

State and persistence

There is no database. Every piece of agent state LocalAGI owns is a JSON file under one directory, written by the process that runs the pool. The only database in a LocalAGI deployment is PostgreSQL as a vector store for LocalRecall, and it is optional.

The state directory

LOCALAGI_STATE_DIR, defaulting to $CWD/pool and created on startup (cmd/serve.go:38-46). Running the binary from a different directory gives you a different, empty set of agents — a common way to lose work.

Embedded in LocalAI the same code resolves the directory differently: cmp.Or(cfg.StateDir, appConfig.DataPath, appConfig.DynamicConfigsDir, "agents") (LocalAI/core/services/agentpool/agent_pool.go:247), which in the stock container is /data.

Every file

Path Contents Written by
pool.json map[agentName]AgentConfig — the agent registry AgentPool.save, core/state/pool.go:899-919
pool.json.bak Byte-identical backup, rewritten after every save core/state/pool.go:913-917
pool.json.tmp Transient staging file for the atomic write core/state/pool.go:904-912
<name>.state.json types.AgentInternalState — goal, now-doing, doing-next, history, memories Agent.SaveState, core/agent/state.go:103-111
<name>.character.json The generated or configured Character Agent.SaveCharacter, core/agent/state.go:113-120
scheduler-<name>.json {tasks: [], task_runs: []} scheduler.JSONStore.save, core/scheduler/json_store.go:209-218
conversations/ Per-conversation JSON transcripts — only when conversation logging is on core/agent/knowledgebase.go:113-124
collections/ The vector store (chromem files, or metadata for postgres) LocalRecall, via cmd/serve.go:48-50
assets/ Original uploaded knowledge-base files LocalRecall, via cmd/serve.go:51-53
skills/ Skill directories and the git-repo configuration services/skills/service.go:19,39-41

<name> is the agent name with / and space replaced by _ (core/state/pool.go:192-195). That substitution is applied in CreateAgent but not in RecreateAgent or StartAgentStandalone (core/state/pool.go:199,211,224), so an unusual name can produce different paths depending on how the agent got started.

pool.json is written carefully and read defensively

Save (core/state/pool.go:899-919): marshal → write pool.json.tmp → os.Rename over pool.json → best-effort write of pool.json.bak. The rename is atomic on a POSIX filesystem, so a crash mid-save leaves either the old file or the new one, never a truncated one.

Load (core/state/pool.go:154-167) is self-healing:

  1. Read pool.json. If it parses, done.
  2. If it does not, read pool.json.bak, use it, and repair pool.json from it.
  3. If both fail, start with an empty pool rather than refusing to boot.

Step 3 deserves attention on an unattended deployment: a corrupted registry presents as "all my agents disappeared", not as a startup failure.

Configuration versus runtime state

Two structs, two files, two different authors.

state.AgentConfig (pool.json) is declarative: model, actions, connectors, feature flags. Written by you, by the UI, or by the API.

types.AgentInternalState (<name>.state.json) is cognition: NowDoing, DoingNext, Goal, DoneHistory, Memories. Written only by the model, through the update_state tool (core/agent/agent.go:1236-1283) — and that tool only exists when hud is enabled (core/agent/actions.go:154-155,166-167, 172-174).

So an agent with hud: false never writes a .state.json file at all, and the "agent state" a reader expects to inspect does not exist. The fields are rendered back into the prompt through the HUD template (core/agent/templates.go:99-105); that is their only consumer.

Character (<name>.character.json) holds Name, Age, Occupation, Hobbies, MusicTaste, Sex (core/agent/state.go:23-30). With random_identity set, it is generated by the LLM against a JSON schema at construction and then persisted, so the identity is stable across restarts.

The scheduler store

One scheduler per agent, one file: scheduler-<name>.json (core/state/pool.go:399).

Task (core/scheduler/task.go:52-65): id, agent_name, prompt, schedule_type, schedule_value, status, next_run, last_run, context_mode (default "agent"), metadata. TaskRun (:68-76): id, task_id, run_at, duration_ms, status, result, error.

schedule_type schedule_value Notes
cron 5-field cron expression Minute/hour/dom/month/dow — no seconds field
interval milliseconds, as a string Next run = last run + interval
once a duration, 2h30m, 1d, 2d12h Task is deleted after it runs

The store rewrites the entire file on every mutation, under an RWMutex (core/scheduler/json_store.go:209-218).

task_runs grows without bound. LogRun appends and never prunes (core/scheduler/json_store.go:153-159); only reads are limited. A long-lived agent on a one-minute cron accumulates run records forever, and the whole file is rewritten on each one. See troubleshooting.

What is transient and lost on restart

State Lifetime Where
AgentSharedState in memory, 5-minute TTL core/state/pool.go:140-143
Per-agent Status — action results in memory, rolling window of ~10 core/state/pool.go:79-94
Observable history in memory, 500-entry ring core/agent/observer.go:23-96
SSE managers and their replay history in memory, per agent core/sse/sse.go:98-236
/v1/responses conversation tracker in memory, TTL from LOCALAGI_CONVERSATION_DURATION, 1 hour on a parse error webui/routes.go:81, webui/options.go:42-50
counter action values in memory, mutex-guarded map services/actions/counter.go:13-16
Job queue contents and in-flight jobs in memory core/agent/agent.go:106
MCP sessions and discovered tool lists in memory, established at agent construction core/agent/mcp.go:139-228

The row that surprises API users is the conversation tracker: chaining requests with previous_response_id works until the process restarts or the TTL expires, and then the id is simply unknown. See the Responses API.

The row that surprises operators is the counter action — it looks like persistent bookkeeping and is not.

Conversation logging is opt-in

LOCALAGI_ENABLE_CONVERSATIONS_LOGGING must be the literal string "true" (cmd/env.go:59). With it unset, no transcript is written anywhere: the conversation exists on the job, is handed to connectors and the API, and is then discarded. Writing it to disk is saveCurrentConversation (core/agent/knowledgebase.go:126-183), which is also the function that pushes conversation content into the knowledge base when long-term or summary memory is enabled — two different destinations, two different switches. See memory.

Note the third possibility: with logging off and long-term memory on, your only record of a conversation is a set of embedded chunks in a vector store.

One known leak

A goroutine started per agent pushes the hud SSE event once per second, forever (core/state/pool.go:692-699). It captures the agent and its SSE manager and has no ctx.Done() branch. Every RecreateAgent — that is, every config save — starts another. Whether the old ones are collected is not established without running the process; the code has no exit condition.

Upstream references

  • core/state/pool.go — atomic save, self-healing load, state file naming, shared-state TTL, the HUD goroutine. Validated against v2.9.0, 2026-08-17.
  • core/agent/state.go — SaveState, SaveCharacter, Character and its schema. Validated against v2.9.0, 2026-08-17.
  • core/scheduler/json_store.go — whole-file rewrite, unbounded task_runs. Validated against v2.9.0, 2026-08-17.
  • core/scheduler/task.go — task shapes, schedule types, the extended duration parser. Validated against v2.9.0, 2026-08-17.
  • core/agent/knowledgebase.go — transcript writing and knowledge write-back. Validated against v2.9.0, 2026-08-17.
  • cmd/serve.go — state directory defaulting and derived paths. Validated against v2.9.0, 2026-08-17.
  • core/sse/sse.go — broadcast manager and replay history. Validated against v2.9.0, 2026-08-17.
  • LocalAI core/services/agentpool/agent_pool.go — state directory resolution when embedded. Validated against v4.8.2, 2026-08-17.