Configuration
Circle is configured by files: a data folder for your account-level settings and resources, and folders inside each project for things that belong to that project.
Where Circle keeps things
The data folder is ~/.circle. Set CIRCLE_HOME to use another location, and run circle --print-home to see which one is in use.
| Path | What it is |
|---|---|
settings.json |
Model, endpoint, trusted folders, MCP servers. See Settings. |
credentials.json |
Your API key. Readable only by you. |
history |
Your prompt history, last 1,000 messages. |
circle.sqlite |
Every session: its messages, branches and titles, for /resume and circle -c. See Sessions. |
approvals.json |
Your own approval rules: a tool, a pattern, and allow or deny. Readable only by you. |
approvals/ |
“Allow for this session” rules, one file per session. |
schedules/ |
Scheduled tasks: one folder per schedule (schedule.json, run logs under runs/, history.jsonl), plus the background scheduler’s daemon.json and daemon.log. |
projects/<folder>-<id>/ |
Per project: the messages a summary replaced (conversation_history/), tool output too long for the conversation (large_tool_results/), the output of commands and background jobs (background_jobs/, one folder per run of Circle, removed a day after that run ended), plan mode’s plans (session_plans/, one per conversation, removed with it), and pictures: screenshots (screenshots/), pictures pasted in the terminal (pasted_images/) and pictures sent with a message for a model that does not read images (images/). See Images and screenshots. |
cache/models-dev.json |
The copy of models.dev that context windows and prices come from. See Models. |
update-check.json |
The answer of the daily update check. |
secret_requests/ |
Requests for secrets waiting to be typed; each is removed once collected. |
extension_secrets/ |
Values extensions keep with api.secrets, one <extension>.secrets.json each, readable only by you. |
extension_data/ |
A folder for each extension that asked for one (api.dataDir). |
exports/, shares/ |
Output of /export, /copy (fallback) and /share. |
skills/ |
Your skills. |
hooks.json |
Your hooks. A project’s hooks are .circle/hooks.json. They run in a trusted folder after you approve that version of the file. hook-trust.json in this folder remembers the digest. |
commands/, prompts/ |
Your custom commands. |
extensions/ |
Your extensions. |
AGENTS.md and friends |
Your personal instruction files. |
keybindings.json |
Your own keys for Circle’s actions. See Keyboard and mouse. |
Circle creates most of these when it first needs them. Hook runs are appended to hooks.log; see Hooks.
Instruction files
Instruction files tell Circle how to work: build commands, conventions, things to avoid. Circle reads them when a session opens and puts them in the system prompt, in this order:
| Where | Which files |
|---|---|
| The workspace folder | AGENTS.override.md, AGENTS.md, CLAUDE.md |
| The data folder | AGENTS.md, CLAUDE.md, MEMORY.md, agents.md, memory/AGENTS.md |
| Your home | ~/.agents/AGENTS.md, CLAUDE.md, MEMORY.md, agents.md, and ~/.deepagents/AGENTS.md |
| The workspace | MEMORY.md, agents.md, .agent/AGENTS.md, .circle/AGENTS.md, .deepagents/AGENTS.md |
Project instruction files come from the workspace folder only. A parent checkout’s AGENTS.md is not applied to a session opened in a subdirectory. Your personal files, in the data folder and under your home directory, still apply in every folder. Each file goes into the prompt once: a file reached under two names (as AGENTS.md and agents.md are on macOS) is read once. Only the first 24,000 bytes of each file go in; a note in the prompt says when the rest was left out.
Circle reads them again when you start a new session, open another one, or switch models. The prompt then tells the model that any of those files that exist are already included, and not to call read_file to look for one that is not.
To have Circle write a starting AGENTS.md for a project, run /init. It reads the repository and drafts one. Add a focus after it, for example /init testing conventions.
circle --no-context-files (-nc) leaves out every AGENTS.md, AGENTS.override.md and CLAUDE.md for one run. MEMORY.md is still read.
Memory Circle writes
MEMORY.md is read like the files above and, unlike them, Circle can write it too: one dated line per fact, for what a session learns and the next one should not have to find out again.
# Memory
- 2026-10-30 · the release branch is 9.3
/memory lists those lines, /memory add <note> writes one, /memory remove <number> takes one back. /memory add account <note> writes to the data folder’s MEMORY.md, for what applies to anything you work on rather than this repository alone. The list counts the workspace’s lines first and the data folder’s after, and only lines Circle wrote: text you put in the same file stays yours, is not offered for removal, and is not rewritten by one. A line about the project waits for the folder to be trusted (/trust), the same as any other write into it; the account file needs no trust, being Circle’s own folder.
Three limits, each with its reason:
| Limit | Why |
|---|---|
one line per add, with runs of whitespace and newlines folded to one line |
the note has to stay one line, so the list can show it and a removal can find it again |
| 240 characters at most, counting the date | one fact per line; the refusal says how far over it came |
| the file is never grown past 24,000 bytes | that is all the prompt reads, so a line past the end would be written and never seen · trim it, or remove a line |
Nothing is captured on its own: a line appears when you say so. The add notice carries the number that takes it back, because removing a line moves the ones under it up.
-nc does not leave these out. --no-context-files is about instructions; a dated note is memory, and both MEMORY.md files are still read with it.
System prompt
Circle’s system prompt starts with its own instructions, then the instruction files, the environment (folder, platform, date) and anything appended. Two files change it, the way pi’s do, in a project’s .circle/ folder or in the data folder:
| File | What it does |
|---|---|
SYSTEM.md |
Replaces Circle’s own instructions and guidelines. The instruction files and the environment still follow. |
APPEND_SYSTEM.md |
Is added at the end of the prompt. |
The project’s file wins over the data folder’s. On the command line, --system-prompt wins over both SYSTEM.md files and --append-system-prompt over both APPEND_SYSTEM.md files, for that run. An empty file, or an empty --system-prompt "", leaves Circle’s own. See CLI.
Replacing the instructions also removes what they say about approvals, plans and tools, so the model may use its tools less well. Start from a copy of what you replace: Circle’s own are in src/prompts/session/ and src/prompts/circle_guidelines.md in its repository.
Project folders
Inside a project, Circle looks in these folders. Circle works only in a folder you have trusted, and trusting it is what lets these apply.
| Folder | What |
|---|---|
.circle/skills, .agent/skills, .agents/skills |
Skills. See Skills for all locations and their order. |
.circle/agents, .agents/agents, .claude/agents |
Subagents the model can call with task. |
.circle/commands, .circle/prompts |
Custom commands |
.circle/extensions/<name>/extension.ts (or .mjs, .js) |
Extensions |
.circle/AGENTS.md, .agent/AGENTS.md |
Instructions |
.circle/SYSTEM.md, .circle/APPEND_SYSTEM.md |
The system prompt for this project |
.circle/settings.json |
Settings for this project |
.circle/hooks.json |
Hooks for this project. They run after you trust the folder and approve this version of the file. |
.circle/approvals.json |
Approval rules for this project. A project’s rule can only deny. |
Trusting a folder writes nothing into it. The trusted folders are listed in settings.json in the data folder.
Other tools’ folders
Circle reads the folders of other agents, so what you set up once works in several tools: .claude, .opencode, .pi and .agents for skills, .opencode and .pi for commands. The exact list is in Skills and Custom commands.
Reload
/reload re-reads settings.json, the project’s settings, hooks.json, keybindings.json and the model credentials, reconnects MCP servers, reloads extensions, and rebuilds the model and the system prompt, which re-reads the instruction files and the skills. It does not run session_start hooks again, and it does not re-read credential_files. It is refused while a turn is running.