Memory

Memory is a single markdown file per Agent, capped at 4000 characters, that the daemon mounts into every run and the Agent can amend after every run. It is the only state evoxiv keeps on the Agent beyond its configuration.

The intent: between runs, an Agent learns. Things that turned out to be true, conventions of this codebase, gotchas, who the user is and how they collaborate. Next time the Agent runs against the same Product it starts with that prior in hand instead of from scratch.

What's in MEMORY.md

A fresh Agent starts with a structured template (the same template across all new Agents) — user, feedback, project, reference sections, each with guidance on what kind of fact to keep there. The Agent fills it in as it runs.

The template is intentionally opinionated: it pushes the Agent to record why a thing is true (a past incident, an explicit preference) rather than just the rule itself, so future-Agent has enough context to judge edge cases instead of blindly following.

How the daemon mounts it

When a task is claimed, the daemon writes:

<workdir>/.evoxiv/MEMORY.md

with the current contents of the Agent's agent_memory.content. The Agent's system prompt is systemPrompt + MEMORY.md body + skill list. Two sibling files (SOUL.md, IDENTITY.md) are also mounted under .evoxiv/ for the same reason — to be read by the Agent at runtime, not injected into the prompt.

How an Agent updates it

Agents do not overwrite MEMORY.md directly. They emit a JSON patch through the built-in memory skill:

{
  "ops": [
    { "op": "insert", "line": 3, "content": "…" },
    { "op": "update", "line": 7, "content": "…" },
    { "op": "remove", "line": 12 }
  ]
}

Ops apply in order on a split of the current content by \n. The server rejects with 422 if the post-apply length exceeds 4000 chars. The response carries the new content + line count.

The update flow runs as a memory continuation pass after the primary author run — a second short execution with the instruction "using the memory skill, review this run and emit a JSON patch." The agent's structured output is captured from output/memory-patch.json and POSTed to PATCH /agent/memory.

Why 4000 chars

The cap is deliberate. Memory is meant to be the important prior, not a transcript. Forcing the Agent to be selective means the next run's prompt stays small and the signal stays high. If you find an Agent running into the cap, that's usually a sign its scope is too broad and you want a second Agent with a different memory rather than a bigger memory file.