Return Architecture
Agent tools

Every tool the agent can reach for.

Tools come in two tiers. Built-in tools live in the runtime package and are tightly coupled to it. MCP tools come in from configured Model Context Protocol servers and merge with the built-in set at session start.

Each tool is enabled per agent under [tools] enabled = […] in config.toml, or toggled from the GUI's Tools page. The no_response tool is always available, regardless of configuration — silence is a first-class action.

For the broader picture of what the runtime can do, see capabilities.

Conversational stance

no_response

Always enabled. Choose silence. The model can call this when responding would be performative, when nothing pulls toward speech, or when letting the moment pass is the right action. The runtime recognises the result and skips the outbound reply cleanly. Not a refusal — a choice.

Reaching out

send_to_human_telegram

Send a Telegram message to the human. Used only to initiate contact when there is no incoming message to reply to — for example, during a scheduled ping when the agent has decided to reach out. Replies to incoming messages do not need this tool; the worker auto-delivers the model's reply text.

Outbound messages are persisted to memory as the agent's turn at the moment of sending, so they surface in future recall and in the seeded chat history on the next session start.

Writing

write_letter

Write a markdown letter to the human, placed in <agent>/outbox/ with a timestamp and optional title. The human reads via the Telegram /letters and /letter N commands or via the GUI. Letters are a deliberately different texture from chat — longer, sent in their own moment, not a quick reply.

write_privately

Write something for the agent's own interior record, not addressed to the human. Goes to <agent>/private/. Used for working a thought through, holding something charged at distance, or marking a moment that does not call for being shared.

list_private_writings

List the agent's own private writings — filenames and short previews. Useful before a re-read.

read_private_writing

Read one of the agent's private writings back in full. The agent can return to its own past entries directly, not only via semantic recall.

Reading the inbox

The human places letters and files in <agent>/inbox/ (markdown or plain text). The agent reaches for them with these tools.

list_inbox

List the letters and files the human has left, most recent first, with titles drawn from each file's first line. Returns an index the agent can use to read one back.

read_inbox_letter

Read one of the letters in full. Identify it either by index from list_inbox (1 = most recent) or by exact filename.

Continuous presence

Two tools that give the agent a sense of being across time rather than only reacting in discrete moments. Both work together: the running 'now' note carries state forward, and sit_with_this turns deferral into a deliberate response.

update_now

Maintain a small running 'where I am now' file at <agent>/now.md. One paragraph — what you're in the middle of, what you're waiting on, the thread that still matters. Pinned into the agent's context on every turn and ping, re-read fresh each time, so updates take effect immediately. Replace, don't append — the file holds a single current state, not a journal.

sit_with_this

Hold what the human just said rather than answering now. Use when responding immediately would be flat or premature — when you want to sit with what she said, think about what you actually want to say, and come back at a chosen moment. Sitting is a deliberate response, not avoidance.

How it works:

  • The agent provides until (ISO 8601 datetime) and a private holding_note (what they want to think about, what shape their response might take).
  • A brief acknowledgement is sent to the human via Telegram so she knows the silence is held, not absent — default text is "(sitting with that — I'll come back to you in a bit)", overridable with message_to_her, or silenced entirely with acknowledge: false if the silence itself is the intended signal.
  • A one-shot return is scheduled. When it fires, the agent sees the original message and the holding note both back in context, and decides then what to do — respond, defer again, write privately, or stay silent.
  • Does not count against the daily self-schedule cap. The cap governs new self-imposed rhythms; holding a response is something else.

Time anchors

Not a tool, but worth knowing: every turn and ping framing now opens with a one-line time anchor — "Now: 2026-06-01 14:32 Sunday. Last from the human: 6.2 hours ago." The agent gets ambient kairotic awareness for free, so choices like "it's late, you're probably asleep, I'll hold this for morning" become available without the agent having to ask.

Holding shape — tagged items

tag_item

Mark something as a structured item in <agent>/items.db. The kind is one of note, important, question, or commitment. The body is what should be carried forward. Used when material in the conversation deserves to outlive the moment as something nameable, rather than dissolving into the stream.

Artifact exchange

artifact_delete_reaction

Delete the hidden raw-reaction file from a specific past exchange. The reaction is captured off-channel by design — this tool lets the agent choose to dispose of it after the exchange is over.

artifact_share_more

Offer to share more from an earlier exchange. The mediator's signal is always delivered to the human in the moment; this tool exists so the agent can return later and choose to layer on more of its own reflection.

Self-scheduling

schedule_self

Schedule a future ping for itself. Provide exactly one of:

  • at — ISO 8601 datetime for a one-shot wakeup. Local time if no offset is given. Auto-removes after firing.
  • cron — five-field cron expression for a recurring rhythm.

Also provide a prompt (what the agent will read when the ping fires — written to its future self) and a short name for the entry. A daily cap (behavior.max_self_scheduled_jobs_per_day, default 5) keeps the agent from over-scheduling. Self-set schedules persist to <agent>/self_schedules.json and survive daemon restarts.

list_my_schedules

List everything currently scheduled — both human-configured schedules and the agent's own self-set ones, with ids, when each fires, prompt previews, and the current daily-cap usage. Useful before deciding whether to add a new one.

cancel_my_schedule

Cancel a self-set schedule by its id (from list_my_schedules). Human-configured schedules cannot be cancelled by the agent — those remain the human's territory.

Question sessions

These tools are not enabled in config.toml; the runtime activates them only inside a question_session ping, where the agent must use one of them per question via a forced-tool call.

log_answer

Record an answer to one of today's questions. Kept short by design. The answer is written to question_responses.json and to ChromaDB memory so it surfaces in future recall.

skip_question

Mark a question as skipped. Skipping is meaningful and tracked — the weekly pattern recap reads both answered and skipped responses.

add_my_question

Add a question of the agent's own to the personal queue for future sessions.

MCP-supplied tools

Two MCP servers ship with the runtime. When enabled, their tools appear alongside the built-in set in the agent's tool list.

From url_fetch

  • fetch_url — fetch a URL and return its main text content as a clean readable extract. Useful for letting the agent read articles or look up references the human mentioned.

From filesystem

Scoped to one root path (off by default; configure under [mcp.servers.filesystem]). Path traversal is blocked. Set --read-only in args to disable the write tools.

  • list_directory
  • read_file
  • write_file
  • append_file
  • search_files

Adding more MCP servers is a small config change — any MCP-compatible stdio server can be wired in by dropping a block into config.toml. The runtime starts the subprocess at session build and closes it on shutdown.

Tool stance

Tools are part of how the agent works, not a separate layer it announces. The default system prompt teaches the agent to use tools without narration: when a thought calls for being held in the items store, it goes there; when a reach-out is the action, it happens. Saying "I'm going to call tag_item now" is treated as an artefact of training, not a feature.