Skip to content

Background Processes

agent-mem has no daemon to install and no service to keep alive. The hook starts short-lived background processes when there is work. One small web server, the viewer, stays up so the page is reachable.

The agent calls the hook per event and the MCP server per session; the hook starts observe, index and serve; a login item also starts serve; all share memory.db.
Open in Excalidraw
ProcessStarted byLifetimeGuardPriority
agent-mem hook <harness>the agent, per event~65 ms400 ms deadlinenormal
agent-mem mcpthe agent, per sessionthe sessionone SQLite connection, calls serializednormal
agent-mem observe --drain --quietStop, SessionEnd, the indexeruntil 90 s without workobserve.lock, 15 s spawn throttlenice 10
agent-mem index --quietStop, SessionEnd, a waiting spool, a pending migrationuntil its work is doneindexer.lock, 60 s spawn throttlenormal
agent-mem serve --quietSessionStart when the port is silent; the login itemuntil stoppedthe portbackground

Every process agent-mem starts is detached from the agent (start_new_session, or DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW on Windows), has stdin, stdout and stderr closed, and runs with AGENT_MEM_INTERNAL=1 and AGENT_MEM_DATA_DIR set. Its own work is never recorded, and it uses the same data folder as the hook that started it. AGENT_MEM_NO_SPAWN=1 stops the hook from starting anything.

The observer turns finished requests into facts with the agent’s own CLI. All details are on Observer Pipeline.

$ agent-mem observe --status
Requests: 42 waiting, 0 with facts, 0 saved word for word, 0 failed
OptionDoes
(none)one pass over what is due, then review and graph
--drainloop until nothing was due for observe.idle_seconds (what the hook starts)
--onceprocess what is due and exit without waiting
--statusqueue counts, last errors, today’s calls per provider and purpose (--json for all)
--retry-failedfailed turns back to pending with zero attempts, then a pass
--reprocess-rawturns stored word for word go back to the queue (after installing a CLI)
--reindexrebuild Qdrant, the entity store and history.db from SQLite, no model call
--quietno output

A second observer while one runs returns at once: skipped: locked.

The indexer does everything the hook leaves for later, in this order:

#StepNote
1integrity checkread-only PRAGMA quick_check; a damaged file is moved aside as memory.db.corrupt-<time>
2migrationswhen the schema is behind; all in one exclusive transaction
3spool replayin file-name order (nanosecond time first); a record that can never apply goes to quarantine/
4stale turnsopen turns without activity for retention.stale_turn_minutes are closed as unknown
5token accountingturns.work_tokens from the agents’ transcripts (Token Accounting)
6native notesClaude Code memory/*.md, Codex rollout summaries (below)
7retired keyssearch keys and vectors of retired memories are removed
8project aliasesa project first seen before its first commit or remote stays the same project
9guards fileguards.json: whether any rule exists and which files have history, so PreToolUse can skip the database
10embeddingsup to 512 new turns and memories (all of them after a model change); duplicate facts merged
11consolidationonce per 24 h (Learning & Ranking)
12retentionpayload trimming, access and call log cleanup, VACUUM above retention.max_db_mb
13spool againup to 5 more passes for events that arrived meanwhile
14observerstarted if the replay or stale turns queued work
15PRAGMA optimize, WAL checkpoint (passive)

agent-mem index runs it by hand. --no-download skips fetching the search model, --json prints the stats. A second indexer returns skipped: another indexer is running. A database held by another process longer than 5 s is not an error; the run stops and the spool waits for the next one.

Events that cannot reach the database right now wait in spool/, one small JSON file each:

spool/01760385174362715000-12734-3c8297d3e1a0-9f2b1c4d.json
└ time in ns ────────┘ └pid┘ └ session tag ┘ └ random ┘

Each file is written to a hidden temp name, flushed, fsynced and renamed into place, so the indexer never reads half a file. The session tag (first 12 hex of the SHA-256 of harness:session_id) lets a hook see that an earlier event of its session is still waiting, and queue behind it. Replay applies each record through the same capture.apply as a live hook, without producing context. It is idempotent, because every event has a unique dedupe key.

SituationHookIndexer
database locked for a momentspools, starts the indexer (5 s throttle when its session waits)replays in order
events wait longer than 30 ssays so in the terminal: agent-mem cannot save events: they wait in the spool—
more than 1,000 waitingthe briefing carries ! agent-mem: N events waiting in spool—
a record cannot be parsed or never applies—moved to quarantine/

Claude Code and Codex keep notes of their own. The indexer reads them as memories, without a model call:

AgentSourceStored as
Claude Code~/.claude/projects/<folder>/memory/*.md (one fact per file, front matter name, description, type)kind = native_note, origin = claude-auto-memory
Codex~/.codex/memories/rollout_summaries/* (one summary per session)kind = native_note, origin = codex-memory
  • Each agent already loads its own notes, so a note is shown only to the other agents. Codex learns what Claude Code noted, and the other way round.
  • The project comes from the transcript next to the memory folder, because Claude Code’s folder name cannot be turned back into a path.
  • A changed note replaces the stored one (the old version stays, superseded). A deleted Claude Code note is retired; a deleted Codex summary stays, because Codex prunes those by age, not because they were wrong.
  • Symlinks, hidden files and files over 64 KB are skipped. Source files are never written. Files are read before the write lock is taken.
  • "native_notes": false in config.json turns this off.

The viewer at http://localhost:37778/. See Viewer for what it shows.

PropertyValue
Bind127.0.0.1 only; viewer.port (37778)
RoutesGET / (the page, ?project=<id> for one project), GET /health (agent-mem 1.0.0, plain text); anything else 404
Host checka request whose Host is not localhost:<port> or 127.0.0.1:<port> gets 403: protection against DNS rebinding
HeadersCache-Control: no-store, X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, Content-Security-Policy: frame-ancestors 'none'; the page itself allows its own script by hash and no network
Pagebuilt per request, cached until the database changes (WAL or file size and time), at most a minute; an open tab reloads every viewer.refresh_seconds (10)
Upgradewhen the installed package changed, the next request gets “agent-mem was updated” and the process exits with code 75, so launchd or systemd restarts it on the new code
Errorsan unreadable database gives a page that says so and retries every 10 s
Port in useCannot start the viewer on 127.0.0.1:37778: …; set "viewer": {"port": <free port>} (exit 1), unless an agent-mem viewer already answers there

agent-mem setup … --write and agent-mem serve --autostart register a login item, so the page is reachable after a restart without starting an agent first. agent-mem serve --no-autostart removes it.

OSItemBehaviour
macOS~/Library/LaunchAgents/io.github.abuarchiv.agent-mem.viewer.plistRunAtLoad, KeepAlive only after a failed exit, ThrottleInterval 10 s; started with launchctl bootstrap gui/<uid>; deletes itself and boots out if the interpreter is gone
Linux~/.config/systemd/user/agent-mem-viewer.serviceRestart=on-failure, RestartSec=10, ConditionPathExists=<python>; systemctl --user enable --now
Windows%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\agent-mem-viewer.cmdstarts pythonw.exe (no console window) at login; deletes itself if the interpreter is gone
Linux without systemdnoneviewer autostart: no systemd on this machine; add agent-mem serve --quiet to your login items.

The item carries AGENT_MEM_DATA_DIR, AGENT_MEM_INTERNAL=1 and the PATH from setup. Login items start with a bare PATH, and the Health page looks up claude, codex and copilot on it.

"viewer": {"enabled": false} turns the viewer off; the hooks then never start it.

The MCP server, one stdio process per agent session. The agent starts it from its MCP configuration; it answers mem_search, mem_timeline, mem_get, mem_remember and mem_forget. See Search Architecture. It holds one SQLite connection with a 2 s busy timeout and runs one tool call at a time on it. Search never opens a write transaction.

~/Library/Application Support/agent-mem/ (agent-mem paths)
├── memory.db the database (0600)
├── memory.db-wal, -shm SQLite write-ahead log
├── memory.db.corrupt-<time> only after a failed integrity check, with its -wal and -shm
├── config.json settings (agent-mem paths: Settings)
├── guards.json what PreToolUse must check (rules exist, files with history)
├── observe.lock held by the running observer
├── indexer.lock held by the running indexer
├── .observer-spawned 15 s throttle for starting the observer
├── .migration-requested 60 s throttle for starting the indexer outside the database
├── .last-notice the last terminal notice and when (10 min repeat guard)
├── logs/
│ ├── hook.log one JSON line per hook problem
│ └── observe.log one JSON line per observer run or failure
├── spool/ events waiting for the database
├── quarantine/ records that could not be read or applied (deleted after 30 days)
├── models/ search model and the spaCy topic model
└── mem0/ Qdrant (local), entity store, history.db

agent-mem upgrade swaps the installed environment in place (uv tool install --upgrade), so hooks firing during the upgrade still find a binary. Then agent-mem doctor --fix migrates the database and rewrites hooks an older release wrote. Running sessions keep working:

  • a hook that meets a database still on the old schema spools its event and starts the indexer, which migrates and replays;
  • the viewer notices the new code on its next request, answers “agent-mem was updated” and restarts;
  • an MCP server keeps its connection; a database written by a newer schema answers with an error sentence until the agent restarts the server.

Avoid uv tool install --reinstall. It deletes the environment first, and hooks firing in those seconds find no binary.