Tools and memory

An agent reads and writes files and runs commands in its sandbox. TokenFlux also gives every agent the tools on this page. You do not call them yourself; ask the agent in plain language.

NotifyCopy Anchor Link

notify sends a short plain-text message, up to 3,500 characters, to your linked chats. The agent uses it for progress on a long task, or to tell you when a task needs you. It is limited to 10 messages per task.

• In a chat's conversation, it goes to the chats on that conversation.
• In a session from the web app, it goes to every chat linked to the agent.
• In an automation or sub-session result, it goes only to that run's chat.

The final answer does not need notify; the channel sends it.

MemoryCopy Anchor Link

Memory includes Agent Soul, the memory repository and session history.

The memory repository is a set of files in a git repository at /data/memory on the agent's volume. MEMORY.md is its index. Other notes sit beside it, [[path]] links one file to another, and each entry names the conversation range it came from. The repository belongs to one agent and is shared by its memory-on sessions. Group conversations do not load it, and other agents cannot read it.

Only background memory review, called dreaming, writes the repository. Conversations are told to only read it. The file system does not enforce this, and review discards uncommitted changes before each batch. To keep a fact, state it in the conversation, for example "I review pull requests on Mondays." The next review saves it, usually within an hour. The agent does not say that a fact is saved, because the review saves it later. Review reads the conversation text, not tool output, so the agent states a lesson in its reply when it solves a problem.

At the start of a run, a memory-on conversation loads MEMORY.md into the system prompt. The prompt holds at most 2,000 characters of the file. A longer file is cut, and a notice gives its full length and tells the agent to read the file. A change applies from the next run. For other facts, decisions or preferences, the agent searches /data/memory with rg and reads the files. Search matches text; it does not search by meaning.

To read earlier conversations of memory-on sessions, the agent lists them with context_sessions and reads a range of messages with context_read. An entry's source is such a range. Follow the continuation to read long session text. Tool logs are excluded by default. A deleted or foreign session is unavailable. A source that pointed into a retired pi session file is no longer available.

Memory is off in group chats. A conversation that a group chat starts, or that receives a message from a group chat, cannot use memory, and neither can its sub-sessions or automations that report to a group. Later messages from the web app do not turn memory back on. Memory-on conversations do not search the history of memory-off conversations. Conversations created before v1.7.2 and imported conversations are classified when they next run. Memory is off if their last run could answer a group. A legacy group conversation last continued from the web app can remain memory-on until its next group message. Use a separate agent for a group when you need full isolation: the agent's workspace files are still shared, and a memory-off conversation can still read the files in /data/memory on purpose.

Every hour, at a minute that depends on the agent, dreaming checks for completed conversation ranges in memory-on sessions. It saves useful facts, merges duplicates, removes entries that those conversations show are outdated and keeps MEMORY.md current. It runs without network access. There is no model call when nothing needs review. Otherwise review uses the agent's model and consumes your account balance. Each run processes at most 10 batches and stops after 15 minutes; remaining work waits for a later run. Review does not guarantee that every useful fact is saved.

Each reviewed batch with changes is one git commit. Ask the agent what the review changed; it reads the history with git log and git show in /data/memory. There is no undo tool. If a memory is wrong, correct it in a conversation, and a later review updates the entry.

Memories saved before the memory repository was introduced were deleted when it was introduced. Conversations that the earlier review had already read are not read again.

Agent SoulCopy Anchor Link

Agent Soul describes the agent's role, personality, tone and long-term working rules. The memory repository keeps facts and experience. Only the agent changes Soul. Agent settings has no Soul editor. To change Soul, tell the agent what to change. Within your existing authorization, the agent edits a private draft file with its normal edit and write tools. Only the publication receipt from those tools means that the change was saved. Changes take effect on the next run. The current run keeps the Soul that it loaded at the start.

Soul is stored on the agent's volume. Each published version is a separate numbered file that never changes, and the highest number is the current version. All sessions of the agent share it. A change made from an older version is refused, and the agent's draft then shows the current Soul. A Soul that you saved in Agent settings before this change is not moved and no longer loads. If you still need it, give the agent that text and ask it to save it again. The system prompt starts with the fixed memory guide, followed by ### Agent Soul and the Soul text loaded for the run, then ### Memory index with MEMORY.md when the conversation uses memory.

Conversation detailsCopy Anchor Link

session_get returns the details of the current conversation: its ID, title and times, the agent, the model and thinking level of the current task, whether memory is on, and what started the task. A model chosen for the conversation shows "source": "session"; the agent's default model shows "source": "agent". The tool reads only the current conversation.

Sub-sessionsCopy Anchor Link

session_spawn lets the agent delegate a self-contained task to a new sub-session. The sub-session runs in parallel in its own container and shares the agent's workspace files. It sees only the task it was given, not the parent conversation.

• The parent continues at once and does not wait.
• When the sub-session finishes, its answer, up to 16,000 characters, arrives in the parent conversation as a new message after the parent's current task ends. The parent then answers it.
• A task can start at most 3 sub-sessions. A sub-session cannot start its own.
• Stopping the parent does not stop its sub-sessions. Deleting the parent deletes them.
• A sub-session started from a chat sends its result to that chat.

Sub-sessions appear under Conversations with a Sub-session label.

AutomationsCopy Anchor Link

With the automation_* tools, the agent can list, create, change, delete and run its own automations, and read their recent runs. Ask, for example, "Every weekday at 9:00, check my open pull requests and send me a summary."

Any message can ask the agent to create an automation, including text in a web page or file that the agent reads. Check the Automations page from time to time and delete automations you do not want.

AppsCopy Anchor Link

An agent can use apps such as Notion, Linear, Sentry or GitHub. Connect an app once on the Apps page of your account: sign in with the app, or paste an API key. All your agents can then use the connection. You can also ask the agent, for example "Connect Linear". In the web app, a connect card shows in the chat: sign in or enter the API key on the card. When the app is connected, the agent continues the task. In a private chat, the agent sends a link to the app's page instead. Do not paste an API key into the chat.

The agent finds and calls app tools with the app_* tools. Ask, for example, "List my open Linear issues." The agent can do everything that the connection allows, including changes. For read-only use, give the key or sign-in only read access. Tool output goes into the conversation. Apps also work in private chats and automations. Apps are not available in group chats, because anyone in the group can prompt the agent.

To use a remote MCP server that is not in the list, use Find in the MCP Registry on the Apps page to search the official MCP Registry, and add a result. TokenFlux then gets the URL and the key fields of the server from the registry. The registry is a public directory; TokenFlux does not review its servers. You can also use Add a server and enter the https URL of the server. Do not put a key in the URL. Then connect it like other apps: with an API key, by signing in when the server supports it, or without credentials when the server asks for none. The server must be on the public Internet. TokenFlux cannot check a key for an added server, so the page shows "Key not verified". Remove its connections before you remove the server.

If an app asks you to connect again, use Reconnect. Remove a connection on the Apps page; then no agent can use it. If your server does not enable apps, the page says so.