File Memory
Persist creator-approved agent-wide behavior in a local file and place it in later turns.
Keep an operating rule across turns
What it enables
Store creator-approved, agent-global learned behavior in `learned-behaviors.md` and inject it into later turns.
- Status
- Core
- Availability
- Installed by `
auggy create`.
Contributes
The default provider owns the exact label `learned`. A successful creator-authorized `memory_write` replaces the file content, updates the in-process cache, and makes the new guidance available to subsequent turns. The separate top-level `identity: ./identity.md` shorthand also uses file memory, but it is immutable system context rather than this learned-behavior store.
Generated install
`auggy create <name>` adds `fileMemory` to `agent.yaml`, creates an empty `<agent>/learned-behaviors.md`, and writes this metadata file at `<agent>/augments/fileMemory/augment.yaml`.
type: fileMemory
config:
label: learned
source: ./learned-behaviors.md
mutable: true
origin: operator
writeTrustLevels:
- creator
priority: high
placement: preamble
eviction: dropRelative `source` paths resolve from the agent directory. At boot the provider reads the whole file; a missing primary and fallback source fails startup.
Save a creator-approved behavior
From a creator-authenticated Console turn, ask the agent to retain one durable operating rule. The model-facing write is:
memory_write({
label: "learned",
content: "Always include an explicit timezone when presenting a deadline."
})Treat the write as complete only when the tool returns `PERSISTED:`. The `content` value is the complete new value for the static label, not an append operation.
Runtime surfaces
| Surface | Exact behavior |
|---|---|
| Provider | Static memory label `learned`; resolved augment name `fileMemory`. |
| Context | Operator-origin, high-priority preamble context; persistent TTL and drop-on-eviction. |
`memory_read` | Reads `learned` from the boot-loaded cache. |
`memory_write` | Writes `{ label: "learned", content }`; generated policy requires creator trust. |
`memory_list` | Lists `learned` when the current peer may access operator-origin memory. |
| Admin | Reports the source, mutable state, context defaults, cache state, file size, and modification time in Console capabilities. |
The memory bus contributes the generic memory tools. File Memory itself contributes the provider and context, not a private `fileMemory` tool.
Boundaries
| Area | Boundary |
|---|---|
| Trust | The generated store accepts writes only from runtime-verified creator turns. Public or agent-trust peers cannot update it. |
| Persistence | Writes are serialized and atomically replace the local file. External file edits are not watched; restart to reload them. |
| Deployment | `learned-behaviors.md` is bundled into a Railway image, but it is outside `/app/data`; runtime changes in the container do not survive a replacement or redeploy. |
| Limits | One provider owns one exact label and keeps the whole value in memory. Use Layered Memory for per-peer entries, search, retention, or a database-backed store. |
Do not overlap writable owners
Do not expose `learned-behaviors.md` through a writable Filesystem mount. Filesystem writes do not invalidate File Memory's cache, so later turns can receive stale context.
Verify
cd <agent>
auggy run
# In another terminal after the creator-approved write:
cat learned-behaviors.md- 1Open `
/console/chat` through `auggy run` so the turn is creator-authenticated. - 2Ask the agent to remember the deadline rule and inspect the `
memory_write` result for `PERSISTED:`. - 3Confirm `learned-behaviors.md` contains the exact saved content.
- 4Restart the agent, ask it to present a deadline, and confirm it includes a timezone.
- 5Send the same write request without creator authentication and confirm the store is not changed.