Skip to main content

​
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: 
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: 
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.
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.