How agents remember
Memory fundamentally shapes the identity of an agent. It determines whether the system operates as a transient calculator, a collaborative colleague, or a permanent keeper of record. In melchizedek, this identity is defined by a single line of YAML through the memory_system parameter, offering three distinct tiers of retention.
internal-only represents intentional transience. State lives solely within the active process and expires the moment it concludes. This setting is perfect for test environments, batch jobs, and isolated pipelines where historical context would introduce contamination rather than wisdom.
session-only persists the immediate conversation. Every interaction writes securely to Postgres, allowing a system restart to seamlessly resume mid-thought. A crucial structural detail protects this process: session rows are keyed by a composite of application, user, and session. This ensures that parallel subagents working under a global session remain perfectly isolated, preventing the corrupted context that often unravels multi-agent systems.
long-term allows memory to accumulate into true identity. When a session concludes, a model reads the transcript and distills it into structured records. Each record carries a tag such as [FACT], [PREFERENCE], or [CORRECTION], along with the date it is about, the source who asserted it, its exact values with units, its active or historical status, and the index keys it is filed under. These records are embedded as 768-dimension vectors and written to a pgvector table, scoped securely to that specific application and user, where the parsed fields live beside the vector as queryable columns.
recall operates as a search problem
Retrieval directly mirrors the storage process. When a new query arrives, it undergoes identical embedding, and a cosine-similarity search identifies the nearest relevant records. The structured fields then sharpen the ranking: a record gains standing when the query names one of its index keys or the month it is dated to, and an active record outranks one that a later correction has retired. These records merge into the agent’s context before it forms a response. The agent bypasses absolute chronological recall in favor of associative relevance. The past emerges strictly when it aligns with the present context.
The record also evolves. When a user corrects an earlier fact, the correction names the outdated claim, and the store retires the old record: marked superseded, linked to its replacement, preserved as history. A retired record that resurfaces in a search arrives clearly labeled, so an old value can never wear the authority of the current one.
Observe the complete lifecycle as a fact is shared, distilled, and subsequently recalled:
This architecture demands intentional design choices. The distillation process inherently filters information, meaning discarded details are permanently lost. Furthermore, the embedding dimension creates a strict dependency; altering the embedding model requires rebuilding the entire memory store. Finally, retrieved facts provide context rather than absolute truth, meaning a memory recorded incorrectly will persist incorrectly.
Memory acts as the definitive bridge between a utilitarian tool and a genuine relationship. It creates the distinction between a simple search interface and a patient advocate capable of recalling vital lab results at the precise moment they are needed. Cultivating an agent that remembers a person requires deep responsibility, as it holds a fragile piece of their human experience.