Long-term memory

The history lasts one conversation. Long-term memory is what an agent keeps between conversations: the user’s preferences, the state of a project, decisions taken. In Gwenflow it is a set of Markdown files, under a virtual /memories root, that the agent sees in its prompt and edits with tools. Three pieces work on the same files:

Piece	Role
`MemoryToolset`	loads the files, renders them in the agent’s system prompt, and exposes the editing tools
`MemoryConsolidator`	after a conversation, turns its messages into updated notes and topic files, in one cheap LLM call
`MemoryCurator`	from time to time, an agent that merges, deduplicates and archives files

Storage

The files live in a MemoryStore:

from gwenflow.memory import InMemoryMemoryStore, LocalFileMemoryStore, S3MemoryStore

store = LocalFileMemoryStore("./memory")                                  # a local directory
store = S3MemoryStore("my-bucket", prefix="memories", endpoint_url="https://s3.fr-par.scw.cloud")
store = InMemoryMemoryStore()                                              # tests

Writes are versioned: a write checks that the file has not changed since it was read, so two processes editing the same file do not overwrite each other silently. On S3 the version is the object’s ETag, compared before each put; conditional_writes=True also sends If-Match headers, which makes the check atomic on servers that honour them (AWS S3). Paths that try to leave the root are rejected.

An agent with memory

import asyncio
from gwenflow import Agent, ChatOpenAI
from gwenflow.memory import LocalFileMemoryStore, MemoryToolset

USER = "/memories/user/MEMORY.md"

async def main():
    store = LocalFileMemoryStore("./memory")
    question = "Remember that I want answers as bullet points."

    memory = MemoryToolset(
        store,
        always=[USER],                     # rendered in full in the prompt
        browse=["/memories/user/"],        # listed in an index, read on demand
        tools=["read_memory", "memory_edit"],
    )
    await memory.aload(query=question)     # before the run

    agent = Agent(name="Assistant", llm=ChatOpenAI(model="gpt-5-mini"), memory=memory)
    print((await agent.arun(question)).content)

    await memory.aflush()                  # after the run: persist the edits

asyncio.run(main())

always files are rendered in full in a ## Memory block of the system prompt; a missing one starts from a template.
browse prefixes are listed in an index (path and description of each topic file); the agent reads one with read_memory.
aload(query=...) also picks the topic files the request is about, by matching it against the index (file names, descriptions, identifiers) without an LLM call, and renders them in the prompt. recall_limit (3) caps them; recall_stopwords adds the common words of your domain.
The tools work on an in-process copy; aflush() writes the files that changed. After a version conflict, this run’s edits are replayed on a fresh copy.

The memory block is not rendered when the agent has a fixed system_prompt.

The tools

Tool	Does
`read_memory(path)`	read a file
`memory_edit(path, old_str, new_str)`	replace a passage
`memory_write(path, content)`	rewrite a file
`write_topic_file(path, description, content)`	create a topic file, frontmatter generated
`memory_move(old_path, new_path)`	move or archive a file; only with `allow_move=True`, meant for a curator

tools= exposes a subset. A conversational agent typically keeps read_memory and memory_edit and leaves the rest to the consolidator. max_lines (200) caps a file on every write, max_chars caps its rendering in the prompt.

Consolidating after a conversation

from gwenflow.memory import MemoryConsolidator

NOTES = "/memories/thread/demo/NOTES.md"

consolidator = MemoryConsolidator(llm=ChatOpenAI(model="gpt-5-mini"), creatable_prefixes=["/memories/user/projects/"])
result = await consolidator.aupdate(memory, agent.history.messages, writable=[NOTES])
await memory.aflush()

The consolidator updates the writable files and the topic files recalled for the conversation, and may create new ones under creatable_prefixes, never touching a file it was not shown. result.failed tells a failed call from “nothing to change”.

Curating

from gwenflow.memory import MemoryCurator

curator_memory = MemoryToolset(store, always=[USER], browse=["/memories/user/"])
await curator_memory.aload()
await MemoryCurator(llm).arun(curator_memory)
await curator_memory.aflush()

The curator is an agent that merges candidates, removes duplicates and archives files nobody reads. Run it on a schedule rather than after every conversation.

Limits

Long-term memory is not available to durable agents yet, and is never handed down to sub-agents.

Get started

Concepts

Models

Agents

Multi-agent

Extend

Memory

Flows

Knowledge

Production

Project

Storage

An agent with memory

The tools

Consolidating after a conversation

Curating

Limits

​Storage

​An agent with memory

​The tools

​Consolidating after a conversation

​Curating

​Limits

Storage

An agent with memory

The tools

Consolidating after a conversation

Curating

Limits