# File Memory

Canonical: https://auggy.dev/docs/augment-file-memory
Status: Published
Package: auggy 0.5.0

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:** `memory provider`, `preamble context`

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`.

**augments/fileMemory/augment.yaml**

```yaml
type: fileMemory
config:
  label: learned
  source: ./learned-behaviors.md
  mutable: true
  origin: operator
  writeTrustLevels:
    - creator
  priority: high
  placement: preamble
  eviction: drop
```

Relative `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:

**Model tool call**

```
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. |

> **Warning: 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

**Run and inspect the store**

```bash
cd <agent>
auggy run
# In another terminal after the creator-approved write:
cat learned-behaviors.md
```

1. Open ``/console/chat`` through ``auggy run`` so the turn is creator-authenticated.
2. Ask the agent to remember the deadline rule and inspect the ``memory_write`` result for ``PERSISTED`:`.
3. Confirm `learned-behaviors.md` contains the exact saved content.
4. Restart the agent, ask it to present a deadline, and confirm it includes a timezone.
5. Send the same write request without creator authentication and confirm the store is not changed.

## Related

- [Memory and knowledge](https://auggy.dev/docs/memory-and-knowledge/markdown)
- [Layered Memory](https://auggy.dev/docs/augment-layered-memory/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)