> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhome.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Memory & Context

> How persistent .md files are injected into the Agent prompt, and how to build Abilities around that behavior.

OpenHome Agents have a persistent memory system powered by `MemorySnapshotCapabilityBackground` — a background daemon that continuously updates Agent context with information from persistent files.

## How It Works

* The background reads user-level persistent files and injects every `.md` file into the Agent prompt.
* `.md` files are the primary path for ambient context injection into Agent behavior.
* The Profile UI exposes key memory files (`user_profile.md`, `user_summary.md`) as editable content.

## Background Cycle

The background runs sequentially every \~60–90 seconds:

1. `save_user_summary()` — updates `user_summary.md` with a rolling conversation summary.
2. `save_user_profile()` — updates `user_profile.md` with durable user facts.
3. `update_agent_prompt()` — scans persistent storage and injects all `.md` files into the live Agent prompt.

**Latency**: Changes to files typically appear in Agent behavior after the next background cycle (60–90 seconds).

## What Gets Injected

Only `.md` files in persistent storage are injected into the Agent prompt. Other file types are stored but not injected:

| File type                                        | Behavior                                 |
| ------------------------------------------------ | ---------------------------------------- |
| `.md`                                            | Injected into Agent prompt on next cycle |
| `.json`, `.txt`, `.log`, `.csv`, `.yaml`, `.yml` | Stored only, not injected                |

## Writing Context Files

`write_file()` appends by default. For context files that represent **current state** (not history), always delete then write to avoid stale content accumulating:

```python theme={"system"}
async def write_context_file(self, filename: str, content: str):
    exists = await self.capability_worker.check_if_file_exists(filename, in_ability_directory=False)
    if exists:
        await self.capability_worker.delete_file(filename, in_ability_directory=False)
    await self.capability_worker.write_file(filename, content, in_ability_directory=False)
```

Use this pattern for files like `audio_emotion.md`, `upcoming_schedule.md`, and `home_state.md`.

## Reserved Files

Do not write these from custom Abilities — they are owned and managed by the memory background:

* `user_profile.md`
* `user_summary.md`

## Naming and Size Guidance

* **Namespace filenames by feature**: use `audio_emotion.md`, not `context.md`.
* **Keep files concise**: target under 200 words per injected `.md` file.
* **Write current state**, not long history logs.

## Cleaning Up Stale Context

For ephemeral daemon context, clear stale `.md` state at daemon startup before the first processing cycle to prevent old context from being injected after reconnect:

```python theme={"system"}
exists = await self.capability_worker.check_if_file_exists("audio_emotion.md", in_ability_directory=False)
if exists:
    await self.capability_worker.delete_file("audio_emotion.md", in_ability_directory=False)
```

## Dual-Path Response Model

There are two ways an Ability can affect the Agent:

* **Ambient path**: Write `.md` files for background-based prompt injection. The Agent absorbs this context over the next 60–90 seconds and incorporates it naturally into conversation.
* **Urgent path**: Call `send_interrupt_signal()` first, then `speak()` for immediate intervention when the Agent needs to act right now.

```python theme={"system"}
await self.capability_worker.send_interrupt_signal()
await self.capability_worker.speak("You seem stressed. Want a quick breather?")
```

Use the ambient path for ongoing context (mood, schedule, home state). Use the urgent path when something time-sensitive needs immediate attention.

## Editing Memory Files in the Dashboard

In **Dashboard → Profile**, persistent memory files are visible and editable directly from the UI:

* `user_profile.md` — durable user facts (name, role, location, preferences)
* `user_summary.md` — rolling summary of recent conversation context
* `user_goals.md` — user-defined goals the Agent should keep in mind

Changes made in the Profile UI are reflected in Agent behavior after the next background cycle (\~60–90 seconds).