Memory

Memory lets every Dawn agent route read the same workspace-level facts without adding a database or a custom prompt loader.

It is intentionally simple: if workspace/AGENTS.md exists and has content, Dawn injects that content into the agent system prompt on every model turn.

Use memory for stable, project-level context that should follow all agent routes: repository conventions, product facts, user preferences, account assumptions for a local workspace, or anything else that should be visible before the model chooses tools.

Quick start

Create a workspace memory file:

workspace/
  AGENTS.md

Add concise instructions:

# Workspace Memory
 
- Use pnpm for package commands.
- Prefer short, direct customer replies.
- Escalate billing exceptions to the finance queue.

Run any agent() route. Dawn adds a # Memory prompt fragment after the route's systemPrompt and before the current conversation messages.

You do not import anything in the route to enable this. The presence of the file is the opt-in.

What Dawn injects

Dawn renders memory like this:

# Memory
 
The block below is the live contents of `workspace/AGENTS.md`, re-read on every turn.
...
 
---
 
<trimmed file contents>

The exact instructional text is owned by Dawn, but the important behavior is stable:

• The file path is workspace/AGENTS.md under the app root (context.appRoot), which equals the project directory under dawn dev.
• The feature applies to agent() routes during route preparation.
• Empty files are skipped.
• Files larger than 64 KiB are not loaded; the prompt says the file exceeded the limit.
• Files that cannot be read are skipped.
• The file is re-read when the prompt fragment renders, so a later model turn can see an updated file.

Because the memory file is workspace-level, it is shared by all agent routes in the same running app. It is not route-local.

If you run Dawn from a different working directory while pointing at an app root explicitly, remember that memory follows context.appRoot, not the test runner's working directory. In-process test harnesses that pass an explicit appRoot activate memory relative to that root.

Updating memory

When a workspace/ directory exists, the workspace tools capability provides a writeFile tool that is path-jailed to that directory. Dawn's injected system-prompt instruction already tells the agent to update memory by calling writeFile({ path: "AGENTS.md", content: "..." }) — no extra tooling is required.

Because memory is workspace-level, an update affects every agent route in the same running app. Keep write access intentional and the content concise.

If your app does not use a workspace/ directory, you can expose a narrow custom tool that writes the file. Prefer the workspace capability whenever possible; it handles path safety automatically.

Under the hood

The runtime applies built-in agent behavior in prepareRouteExecution before invoking an agent route. For memory, Dawn registers createAgentsMdMarker().

That marker always participates for agent routes, but its rendered prompt fragment returns an empty string unless the file exists and has usable content.

When @dawn-ai/langchain materializes an agent() descriptor, it uses a function-form prompt if any prompt fragments exist. That function calls every fragment renderer with the current state before each model call, then builds:

[{ role: "system", content: composedSystemPrompt }, ...messages]

Memory is one of those prompt fragments. That is why the file can be re-read across turns without rebuilding the route.

What memory is not

Memory is not a vector store, retrieval system, or per-user profile service. It is not automatically summarized. It is not scoped by tenant, route, or session.

If you need tenant-specific or user-specific memory, keep that in your own storage and expose it through route-local tools. Use workspace/AGENTS.md for facts that are safe and useful across the whole workspace.

Related