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:
- Read
pool.json. If it parses, done. - If it does not, read
pool.json.bak, use it, and repairpool.jsonfrom it. - 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,Characterand its schema. Validated against v2.9.0, 2026-08-17.core/scheduler/json_store.go— whole-file rewrite, unboundedtask_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.