Use

The agent

Omnesis has a built-in chat agent that runs inside the gateway. Ask it a question about your indexed data and it answers with citations to the source documents. This page is for anyone who chats with it: what it can do, what it remembers, how it keeps your tasks, how it is contained, and how to choose the model it runs on. To let an outside AI tool such as Claude, ChatGPT or Codex read your data, see Agents & MCP.

What it does

The agent is part of the gateway process, so there is no extra service to run. Given a question, it works through your data with a small set of tools:

• Search the index, with the same pipeline as Search.
• Read documents in full, not just search snippets.
• Follow event trails: the chronological story of linked documents around a result.
• Look up people by name, email, phone, or handle.
• Count messages: how many messages you exchanged with each person over a period, across every chat and email source, so “who did I message most this week?” is answered from a count rather than from whichever conversations a search returned first.
• Query time: everything dated in a window, such as calendar entries and other dated fields a source publishes, together with the documents whose text names a day in that window, such as an email saying “the lease renews on 14 March”.
• Run SQL over the analytics database (health, activity, finance, and other structured records).

Every answer cites the documents it drew from, and each citation opens the document itself. When a hard question splits into substantial independent parts, the agent can fan out workers in parallel. Each worker gets a fresh context and the same read-only retrieval tools, and reports its evidence; the agent then compares and merges what they found.

Recording a document citation requires the agent to fetch its current contents during the turn. Any supplied quote must match the read body exactly. For a partial read, a quote from the returned passage is required. This checks which source was read, not whether every conclusion is correct.

For a deliberate, fully orchestrated research pass, type / in the composer and choose Deep Research. Omnesis plans the question, runs focused readers in parallel, verifies their cited evidence, and writes one report. Neither needs any setup beyond an assigned model.

Open the agent from Ask in the portal (/portal/agent) or from Ask in the menu of the iOS and Android apps.

Addresses, phone numbers, identifiers and other values intended for reuse can appear in Markdown code formatting. Once the answer finishes, use the copy icon beside a value to put just its contents on the clipboard, without surrounding labels or Markdown. Plain multiline values display as text with the icon after the last line. Copy controls remain available when you reopen a saved conversation. Copying happens only when you press the button. Older clients display the same values as ordinary formatted text.

Memory

Ask the agent to remember a preference, a fact about you or another person, or useful context for a document. It saves the memory as an annotation that cites its evidence, and the annotation stays available across conversations and gateway restarts. Memory needs no model beyond the one the agent already uses. You can ask the agent to correct or forget a remembered fact.

A memory must cite a stored document or a message you wrote. The gateway checks the quoted evidence, and an agent reply never counts as something you said. Person pages show what Omnesis has learned about that person, your own person page shows your profile, and a document's details show its annotations under Enriched by Omnesis. Deleting a conversation does not delete the annotations that cite it. Their evidence from it can no longer be read, so they are marked unverified for re-checking, and one that cites no other stored document is no longer used as memory.

Tasks

In any conversation, the agent works with your Tasks when you ask it to. It can list them, add one, complete, move, strike or edit one, and undo a change it made: “move the dentist call to next week”, “I sent the invoice, tick it off”. It states each change in one line, such as Moved to 2026-10-19: Call the dentist, and the change is recorded in the task's history as made in that conversation, where Undo in the Tasks view also reverses it. It changes a task only when you ask; a question about your tasks gets an answer, not an edit. The journal and these task tools work independently of autonomous background processing. When useful, the agent can search for supporting documents and link them to a task, including one you captured with Tell Omnesis. Tasks created in chat also link the creating conversation as a reference, alongside any supporting documents. Deleting the conversation removes that reference but leaves its tasks in place. Changes to linked documents are recorded and can be undone. Moving a task changes when you plan to do it; its deadline is separate and changes only when explicitly edited. Task tools reject fields that do not apply to an action before making a change. Striking out a task can be undone. Deleting a task permanently removes it and its history.

Chat about a task

Chat about this on a task opens a new conversation about it, titled with the task and showing a card with its state, due day and number of linked documents; the card opens the task. Each reply in that conversation reads the task as it stands at that moment: its title, state, planned time, deadline, description, history, and its linked documents with a short excerpt of each, which the agent can open in full. A change you make to the task between messages is in the next reply's context. If the task is deleted, the conversation stays and the agent is told so. Each tap opens a new conversation; earlier ones stay in the conversation list.

With a model assigned to Agent, notes you capture with Tell Omnesis from the portal, the apps or the CLI are also read and acted on, each by one short agent turn of its own. These turns use the same search, document-link, memory and task abilities as a conversation, with the same feature gates. Editing a captured note uses the same abilities to apply its correction, taking the earlier text and result into account instead of repeating unchanged instructions. Tell Omnesis is available without experimental mode; its note processing does not require autonomous Brain processing or an open chat. Chat and Tell Omnesis use the same Agent model, with a separate bounded turn for each note. Reading starts the first time an Agent model is assigned; notes captured while it is later unassigned are read once it is assigned again. Notes that external agents add through MCP, OpenClaw or Hermes are saved and searchable but never acted on. Act on Tell Omnesis notes in the model's details under Settings → Models, or agent.noteAgent set to false, switches this off; notes captured while it is off are only saved, and are not read when it is switched back on. See Voice and quick capture.

If a clear request in a note cannot be completed safely without clarification, Omnesis keeps the note and opens a normal conversation with the original request and its question. The note's receipt offers Continue in chat, and a notification brings you back to the conversation. Your reply continues with the normal Agent abilities and the context already provided. Requests that can be completed directly remain asynchronous.

Sandboxed by design

The agent reads your documents and writes only its own memory and your tasks. Its retrieval tools (search, documents, trails, people, message counts, time, SQL) read and never change anything:

• There is no shell and no filesystem access.
• It cannot edit the originals in your connected sources.
• The SQL tool runs each request inside a read-only transaction on the gateway's analytics database, with external access disabled: no writes, no network, no reading files from disk.

The tools run against your own gateway only. Even when the model runs on a remote backend, it never touches your data stores directly; it sees only what the gateway's tools return.

Conversations

Conversations persist across gateway restarts. Each one is a plain JSON file under ~/.config/omnesis/conversations/, so your history is ordinary files you can inspect and copy. They are kept until you delete them, unless activityRetention.maxAge is set (see Configuration); pinned conversations are always kept. If the assigned model's backend is unreachable, you can still browse saved conversations; sending a message then shows the backend's error.

Returning to the portal or either mobile app within an hour reopens the conversation you were using. After an hour away, Omnesis opens a fresh conversation with the composer ready, and the previous one stays in the conversation list.

Questions, follow-ups, and corrections

In portal, iOS, and Android chat, the agent can offer selectable answers when it needs clarification. Choose one or write your own reply in the normal message composer. An unanswered question remains available when you reopen the conversation on another device.

You can send a follow-up while an answer is running. The gateway keeps accepted messages together in one queued message. Additional follow-ups grow that message, and the agent receives them together when its current answer finishes. Right-click the queued message in the portal, or long-press it on mobile, and choose Send now to interrupt the current answer and send the queue immediately. You can also select the blue send now beneath the queued message on all three surfaces. In the portal, Interrupt and send stops the current answer and puts your correction ahead of queued follow-ups. Stopping a run does not undo actions it has already completed. A queued message whose answer is stopped, interrupted or cut short by Send now is already in the conversation, so it is not offered for retry; only a message that fails to finish shows Retry.

The portal, iOS, and Android keep unsent drafts on the device, separately for each conversation. Accepted queued messages stay with the gateway when you close the app. After a gateway restart, opening the conversation resumes queued work; a message interrupted by the restart is shown for review instead of silently repeated. Right-click a message in the portal or long-press it on mobile to open its menu. Copy copies a user or agent message to the clipboard. On your own messages, Edit and resend appends a corrected prompt and keeps the original exchange in the history.

These controls require support from both the app and gateway. An app connected to a gateway without queue support keeps ordinary chat available and offers send once the current answer finishes. Older apps can still answer clarification questions in text.

Unread conversations and notifications

A conversation the agent wrote into while you were not looking, such as a slow answer that finished later, is marked unread in the conversation list. Opening it clears the mark on every client, because the gateway holds the read state rather than each client. Only showing the conversation on screen counts; a client that merely synced it in the background has not read it.

When a conversation goes unread while you are away, your phone gets one notification, and tapping it opens that conversation. A turn that writes several messages, or further messages before you look, sends no second notification; the conversation can notify you again only after you have read it. A conversation already open on your screen never notifies. The Notifications page covers delivery.

Past conversations and length limits

Conversations are also indexed back into your data as the omnesis-chat source. Past conversations show up in search like any other document, and the agent can recall what you discussed with it before.

Omnesis never compacts, summarizes, prunes, or silently truncates a conversation to fit a model's context window. When a conversation reaches the model's limit, Omnesis keeps the failed turn and any partial answer, makes the conversation read-only, and asks you to start a new one. It stays read-only on every device, and changing the assigned model does not reopen it. When only a single answer reaches the model's output limit, Omnesis marks that answer as truncated and you can ask a follow-up. An answer the model server stops for another reason, such as a content filter or an aborted generation, fails the turn rather than being kept as a complete answer.

Times and time zones

The portal and the iOS and Android apps send their own time zone when they open a conversation, and the agent answers in that zone. Ask when an evening appointment starts from a laptop at home, then ask again from a phone eight time zones away: each answer is in the hour that device's clock shows.

This matters because the gateway does not move. It stays on the machine that indexes your data, in whatever zone that machine is set to, while you travel. Relative windows follow the same rule: today and this week mean the day and week where you are, not where the gateway is. Two kinds of entry are left alone: an all-day event stays a date, and an event with its own zone (a flight landing abroad) is given in the local time of that place.

Search filters work differently: after: and before: resolve relative words to a UTC calendar date on the gateway's clock, so pass an absolute YYYY-MM-DD when a day boundary matters. The answer API receives no device time zone either, and uses the gateway's.

Pick the model

The agent is off until you assign a model to the agent role. You choose where that model runs:

• Anthropic: assign any model your API key can use. Omnesis lists the models Anthropic makes available to the key.
• Any OpenAI-compatible HTTP server: self-hosted (Ollama, llama-server, vLLM) or a cloud provider preset. The agent's instructions and tools alone take well over ten thousand tokens, so give the server a context window of at least 32k tokens. Ollama trims a longer request to its window instead of refusing it; the agent detects the trimmed count the server reports and fails the turn with prompt_truncated rather than answer from a prompt the model never saw. Start it with OLLAMA_CONTEXT_LENGTH=32768, or set num_ctx in a Modelfile.
• Codex: the agent runs on your ChatGPT subscription through OpenAI's Codex app-server. There is no API key; you sign in once. The privacy reviewer that checks answers for external agents can use the same sign-in and model. The gateway manages its Codex runtime separately from the model list, so refreshing models does not update the runtime; Operating → Models covers runtime status and updates.
• Claude Code: the agent runs on your Claude subscription through the claude command you installed and signed in to on the gateway host. There is no API key, and Omnesis never signs in to Claude or reads its credentials. The privacy reviewer can use the same login; see Claude Code below.

omnesis backend key set anthropic prompts for the key. omnesis model list --role agent prints the model IDs to assign, including anthropic/… entries once the key is set. Without remote inference enabled, the Anthropic assignment is saved but the agent stays off.

codex setup-agent takes a model from the status printed after login. It enables remote inference and assigns that model in one step, but only while the agent role is unassigned; it never replaces an existing assignment. Codex receives the conversation, the relevant Omnesis data, and tool results for these requests. When a codex command is installed and the agent role is unassigned, an interactive install offers to do this for you (see First run).

After assigning an HTTP, Codex or Claude Code model, open its role card in Settings → Models to choose the reasoning settings that model offers, such as a reasoning toggle, an effort level or a token budget; see Reasoning settings.

Nothing leaves your machine by default: cloud backends (Anthropic, Codex, Claude Code) and HTTP backends that do not resolve to loopback stay unused until you enable remote inference. Choosing a cloud model in the portal asks you to confirm before enabling this permission and saving the assignment. The permission covers all configured remote inference backends on the gateway; turn off the Allow cloud inference switch under Settings → Models. Backends, presets, the remote-inference setting, and the other model roles are covered in Operating → Models.

If the agent already has a cloud model assigned but cloud inference is disabled, the portal offers Enable cloud inference with confirmation, or Choose a local model. Enabling it sends your messages, conversation context, relevant Omnesis data, and tool results to the selected provider when you use the agent. After enabling it, use Retry message to send a failed message. No gateway restart or JSON editing is needed.

Claude Code

The Claude Code backend runs the claude command on the gateway host, Claude Code 2.1.259 or later, so the agent draws on that installation's Claude subscription. An assignment reads claude-code/<model>, where the model is any value claude --model accepts: sonnet, opus, haiku, fable or a full model ID. The model list comes from the installed CLI's own catalog.

Omnesis never signs in to Claude, and never stores or reads Claude credentials. Install Claude Code on the gateway host and run claude auth login there as the user the gateway runs as. On a host without a browser, run claude setup-token and export the token it prints as CLAUDE_CODE_OAUTH_TOKEN in the gateway service's environment; CLAUDE_CONFIG_DIR is honoured when your login lives outside ~/.claude. API-key variables such as ANTHROPIC_API_KEY are never passed to the CLI, so usage counts against the subscription rather than API billing. Then refresh the backend under Settings → Models → Backends (Add backend → Claude Code → Check again before it is listed), or with omnesis claude-code refresh. A Claude Code older than 2.1.259 is reported as too old, with the hint to run claude update; refresh again once it is updated.

omnesis claude-code setup-agent <model> checks the model against the signed-in CLI, enables remote inference and assigns the model to the agent, only while the agent role is unassigned. omnesis claude-code status shows the installation, sign-in, plan and models. Claude Code is listed among the backends whenever the CLI is signed in; to stop using it, assign the roles that use it to another model. Claude receives the conversation, the relevant Omnesis data and tool results. When a claude command is installed and the agent role is unassigned, an interactive install offers to set this up (see First run).

Each turn runs in isolation from the rest of your Claude Code use. It is a fresh claude -p process in an empty working directory that Omnesis owns, claude-code-workspace in the configuration directory. Every built-in Claude Code tool is removed, so the model has no shell, file, web search, web fetch or sub-agent tools. Omnesis loads none of your settings files, so plugins, hooks and MCP servers that settings enable stay off, and your CLAUDE.md files, auto memory, skills and slash commands are not loaded either; Claude Code's own built-in plugins are switched off. Omnesis serves its own tools to the CLI in-process over the CLI's control channel, denies every permission prompt, and does not let Claude Code persist the session. Omnesis checks the session the CLI reports and fails the turn if any tool outside Omnesis is offered or attempted, or if any skill, sub-agent, slash command or plugin from outside the CLI itself was loaded, or if Claude Code runs a hook, a background task or any tool Omnesis did not call. Each turn replays the conversation from Omnesis' own transcript store.

Managed policy settings that an administrator installs for Claude Code on the gateway host apply whatever Omnesis asks for. When they make Claude Code run commands of its own (hooks, credential helpers, a status line, plugins or environment variables), Omnesis refuses to run Claude Code and says which settings are in the way. Settings a Claude for Work organization manages from its admin console are not stored on the host, so Omnesis cannot read them; the checks above still stop any tool they would add.

Standing instructions

OMNESIS.md is an optional Markdown file in the gateway's config directory. If it exists, the agent reads it on every run. Use it for what you would otherwise repeat in every conversation: who you are, how you want to be answered, conventions you expect it to keep.

Edit it in the portal under Settings → OMNESIS.md, or open the file in any editor. The file on disk is the only copy, so whichever wrote last is what the agent reads. There is no version history; backups include it.

# House rules

- I work in engineering; assume technical vocabulary.
- Dates as YYYY-MM-DD, distances in kilometres.
- When you cite a message thread, name who sent it.

The file reaches the agent you chat with, the workers it delegates research to, and answers served to a connected external agent. It does not reach the privacy reviewer or the check on memory quotes, so nothing you write in OMNESIS.md can loosen your privacy policy.

The file is capped at 16 KB. Past that, only the first 16 KB reaches the agent, marked so the agent knows it is reading a fragment, and the portal says the file is over the cap. A file over 256 KB is not read at all, and the portal shows its size instead of opening an editor. The file is written readable by its owner only.

Changes take effect on the next run. A conversation already open keeps the instructions it started with, so start a new conversation to see an edit take hold.