> ## 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 Injection

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

# Agent Memory & Context Injection

The `MemorySnapshotCapabilityBackground` runs as a background daemon and continuously updates Agent context.

## Overview

* The background reads user-level persistent files and injects every `.md` file into the Agent prompt.
* This makes `.md` files the primary path for ambient context injection.
* The Profile UI exposes persistent 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`.
2. `save_user_profile()` updates `user_profile.md`.
3. `update_agent_prompt()` scans persistent storage (`in_ability_directory=False`) and injects all `.md` files into the live Agent prompt.

Latency from file write to Agent behavior change is typically 60-90 seconds.

## Context Injection Rule

If an ability writes a persistent `.md` file, the Agent will see it on the next background cycle.

* `.md`: injected into Agent prompt
* `.json`, `.txt`, `.log`, `.csv`, `.yaml`, `.yml`: stored only, not injected

## Required Write Pattern for Replaceable Context Files

`write_file()` appends by default. For context files that represent current state, always delete then write:

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

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

These are owned by the memory background.

## Naming and Size Guidance

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

## Stale Context Cleanup

For ephemeral daemon context, clear stale `.md` state at daemon startup before first processing cycle:

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

This prevents old context from being injected after reconnect.

## Dual-Path Response Model

* Ambient path: write `.md` files for background-based prompt injection.
* Urgent path: call `send_interrupt_signal()` first, then `speak()` for immediate intervention.

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

## Profile Tab: Editable Persistent Memory Files

In Dashboard **Profile**, persistent memory files are visible and editable:

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

These files are part of the same persistent memory system consumed by the background. Changes made in Profile are reflected in Agent context after the next background cycle.