Last Updated: 2026.07.07

If you've used a modern AI coding tool — Claude Code, OpenAI Codex, Cursor, or similar — you've probably kept a little instruction file at the root of your project that tells the AI how you want it to work: your tone, your formatting rules, the gotchas it should never forget. In the coding world that file has converged on a common name: AGENTS.md.

Sapience supports the exact same idea. Create a file called AGENTS.md at the root of your Sapience files, and every agent you talk to will automatically read it at the start of each conversation — no copy-pasting your preferences into every chat.

Think of AGENTS.md as your standing instructions to every Sapience agent. Write it once; it follows you everywhere.

Every power user eventually finds themselves re-typing the same guidance to their agents:

Retyping that on every new conversation is tedious and easy to forget. AGENTS.md solves it the same way CLAUDE.md solves it for Claude Code: you put your rules in one place, and the system quietly makes sure the agent sees them before it answers your first message.

When you start (or continue) a conversation with any Sapience agent, here's what happens the moment before the agent begins working:

You never see this happen. There's no extra button to press. The file just works, silently, on every conversation.

Getting started takes about a minute.

Create or upload a file named AGENTS.md and place it at the root of your Sapience files (not inside a folder).

AGENTS.md is a plain Markdown file. Write it in whatever structure is natural for you. A good starter looks like this:

The next time you open a conversation with any agent, your instructions are already in play. There's nothing to enable per-agent and nothing to re-attach.

A few behaviours are worth understanding so the feature never surprises you.

BehaviourWhat it means for youUser-scopedYour AGENTS.md applies to every agent in every conversation, across web, desktop, and mobile. It's tied to you, not to a single agent or project.Injected once per conversationThe file is added at the start of a conversation. Editing AGENTS.md affects new conversations; it won't retroactively rewrite a chat that's already underway. Start a fresh conversation to pick up your latest edits.Needs to be "read" firstSapience reads (parses) your uploaded files in the background. On the very first moment after upload, the content may not be parsed yet — in that rare case the agent simply proceeds without it, and the file is picked up automatically on your next conversation.Blank files are ignoredAn empty AGENTS.md is skipped — no harm done.Never breaks your chatIf anything goes wrong reading the file, Sapience logs it quietly and continues. A problem with AGENTS.md will never block or fail your message.

Sapience already has a Memories feature — short, discrete facts an agent can remember about you ("User prefers terse answers", "User's name is Ken"). So how does AGENTS.md relate?

They're complementary, and Sapience uses both together:

MemoriesAGENTS.mdShapeMany small, individual factsOne free-form documentBest forDiscrete things to recall ("my timezone is AEST")Rich, structured guidance ("here's my whole style guide")How you manage itAgents can add/update them for you as you chatYou author and edit it directly, like a documentFeels likeThe agent's memoryYour standing operating manual

When both are present, Sapience injects your Memories first, then your AGENTS.md — so the document you deliberately wrote is treated as the more recent, higher-priority signal. Use Memories for facts that accumulate naturally over time; use AGENTS.md for the deliberate, structured "here's how I want you to work" rules you want to own and edit yourself.

If you already keep an instructions file for a coding assistant, you'll feel right at home. AGENTS.md is part of a broader industry convergence on the idea of "a file that tells the agent how to behave."

ToolIts instructions fileWhere it livesOpenAI CodexAGENTS.mdRoot of your code repositoryClaude Code (Anthropic)CLAUDE.mdRepo root, plus a personal ~/.claude/CLAUDE.mdCursorProject Rules (.cursor/rules/*.mdc, legacy .cursorrules)Inside the projectGitHub Copilot.github/copilot-instructions.mdInside the repositoryGemini CLIGEMINI.mdRepo rootSapienceAGENTS.mdRoot of your Sapience files ✅

The similarity: in all of these, a file of natural-language instructions is loaded into the model's context before it responds, so the assistant follows your rules without you repeating them.

The Sapience twist: the coding tools read the file from a folder on your computer, scoped to one code project. Sapience reads AGENTS.md from the root of your cloud file store, scoped to you — so a single file governs every agent, every conversation, on every device. We deliberately adopted the same AGENTS.md name so that if you already write one for Codex or your other tools, you can reuse the exact same habit (and often the exact same file) here.

QuestionAnswerWhat do I name the file?AGENTS.md (case-insensitive)Where does it go?The root of your Sapience files — not inside a folderWhich agents use it?All of them, automaticallyWhen does an edit take effect?On your next conversationDo I need to attach it each time?No — it's automaticWhat format?Plain MarkdownWhat if it has an error or is empty?It's skipped safely; your chat is never affected

AGENTS.md is your one-file, always-on instruction sheet for every Sapience agent. Write your preferences, style, and reminders once, drop the file at the root of your Sapience files, and every conversation you start — on any device, with any agent — will already know how you like to work.

It's the same idea coding tools like Codex, Claude Code, and Cursor use to shape their assistants — brought to your Sapience agents, and scoped to you rather than a single project.