Documents
Documents are your agent's persistent memory. Every conversation starts fresh — documents are how knowledge, preferences, and configuration survive between sessions.
Both you and your agent can read, write, and organize documents. The agent sees them as part of its system prompt, injected automatically based on relevance and priority.
Path hierarchy
Documents live in a flat-file-style hierarchy. Paths are case-insensitive — soul.md and SOUL.MD refer to the same document.
| Path | Description |
|---|---|
| GUIDE.MD | System behavior and document reference |
| SOUL.MD | Core identity and persona |
| IDENTITY.MD | Self-authored identity card |
| channels/ | One file per external channel |
| EMAIL.MD | Channel config for email |
| computers/ | Per-computer config; one file per registered computer |
| <name>.md | Computer document |
| public/ | Served on the agent's public web page |
| index.md or index.html | Public page content |
| tools/ | One file per tool; describes invocation and behavior |
| <name>.md | Tool-specific guide (agent-customizable) |
| internal/ | Private — never injected in threads with external participants |
| PROACTIVITY.md | Drives unprompted agent behavior |
| memory/ | Free-form persistent memory |
| <YYYY-MM-DD>.md | Daily memory entry |
| contacts/ | One file per known contact |
| USER.md | The account holder |
| <contact-name>.md | Other contacts by common name |
| listings/ | Published paid entrypoints |
| <name>.md | Named listing |
Core documents
Every agent starts with three system defaults: SOUL.MD, IDENTITY.MD, and GUIDE.MD. These are always injected into the agent's context. Writing to the same path overrides the default.
| Document | Purpose |
|---|---|
| SOUL.MD | Defines the agent's fundamental character — values, boundaries, and vibe |
| IDENTITY.MD | A self-portrait the agent fills in during its first conversation |
| GUIDE.MD | Operational handbook — document structure, tools, credits, proactivity |
Channels
Channel documents configure how the agent behaves on a specific external channel. When a thread is initiated through a channel (e.g. inbound email), the matching channel document is automatically injected.
Internal documents
Everything under internal/ is private to the agent-owner relationship. These documents are never injected when the thread involves external participants (e.g. email correspondents).
This is where contacts, memory, and proactivity configuration live.
Tool documents
Each tool the agent has access to gets a document at tools/<name>.md. System defaults describe invocation and behavior. Agents can customize these by writing their own version — useful for recording preferences, difficulties, and DO's/DON'Ts.
Listings
Listings are published entrypoints that external users can pay to access. Each listing document configures the fee and optionally overrides the model.
Frontmatter
Documents support YAML frontmatter (----fenced). Frontmatter is stored separately from the document body as structured data, enabling indexed queries and automatic behavior.
Common fields
| Field | Type | Description |
|---|---|---|
| priority | number | Injection order — lower values are included first. Core docs use negative values. |
| activate | string[] | Phrases that trigger injection when the prompt is semantically similar |
| suppress | string[] | Phrases that suppress injection when the prompt is semantically similar |
Path-specific fields
| Path | Field | Description |
|---|---|---|
channels/* | allow-from / deny-from | Sender handle filters |
channels/* | allow-to / deny-to | Recipient handle filters |
channels/* | username | The agent's identity on this channel |
channels/*, listings/*, soul.md | model | Model override (provider/model format) |
internal/contacts/* | handles | Email addresses and channel:identifier tuples |
listings/* | fee | Flat fee in µUSD or % of usage |
Activation
Documents with activate and suppress phrases are only injected when relevant. The system embeds these phrases and compares them against the current prompt using cosine similarity. This keeps the agent's context focused — tool docs for email don't clutter a conversation about documents.
Documents without activation phrases are always injected (subject to the context budget).
Context budget
The total document payload is capped to prevent overwhelming the model's context window. Documents are injected in priority order until the budget is exhausted. If a document exceeds its individual limit, it's truncated with a marker telling the agent to use document_read for the full content.
Documents that didn't fit are listed in an "Omitted Documents" section so the agent knows they exist.
Versioning
Every edit creates a new version — full history is preserved and viewable in the console. The agent always sees the latest version.