The .syntic folder

Syntic Code keeps its configuration in two folders named .syntic: one in your home folder for you, and one in a project for everyone who works on it. Runtime data such as saved sessions lives in a third place, your system’s application data folder. This page maps every file and folder Syntic Code reads or writes, so you know where to put things and what is safe to delete.

Three places

Place	Path	Holds	Commit it?
User folder	`~/.syntic/` (move it with `SYNTIC_CONFIG_DIR`, an absolute path)	Your settings, personal memory, credentials and caches.	Never.
Project folder	`<project>/.syntic/`	Settings, instructions, skills and agents shared by the team.	Yes, except the files marked local below.
Data folder	macOS: `~/Library/Application Support/ai.syntic.syntic/` · Linux: `~/.local/share/syntic/` (move it with `SYNTIC_DATA_DIR`)	Session transcripts, background runs, auto memory.	No.

The project folder is the nearest .syntic/ found by walking up from where you start syntic. The walk stops at your home folder, so ~/.syntic is never mistaken for a project. A project without a .syntic/ folder still works; Syntic Code creates one when it first needs to save something there.

Choose the right file

You want to	Put it in
Change a setting for yourself everywhere	`~/.syntic/settings.json`
Share a setting with the team	`.syntic/settings.json`
Override a team setting on your machine only	`.syntic/settings.local.json`
Tell the agent about the project	`SYNTIC.md` at the project root, or `.syntic/SYNTIC.md`
Add rules that only apply to some files	`.syntic/rules/<topic>.md` with a `paths:` filter
Give yourself a reusable `/command`	`~/.syntic/commands/` or `~/.syntic/skills/`
Share a reusable `/command` with the team	`.syntic/commands/` or `.syntic/skills/`
Add a specialist agent	`.syntic/agents/<name>.md` (team) or `~/.syntic/agents/` (you)
Connect an MCP server for the team	`.mcp.json` at the project root
Connect an MCP server for yourself	`~/.syntic/.mcp.json`

The project folder

Path	What it is	Shared
`settings.json`	Project settings (Settings).	Yes
`settings.local.json`	Your own overrides for this checkout. Also where `syntic mcp add` saves servers in the default local scope.	No (Syntic Code adds it to `.syntic/.gitignore`)
`SYNTIC.md`	Project memory. A `SYNTIC.md` at the project root works the same way.	Yes
`rules/`	Rules files, optionally limited to some paths (Memory).	Yes
`skills/<name>/SKILL.md`	Skills the agent can use and you can run as `/name` (Skills).	Yes
`commands/<name>.md`	Custom slash commands. Subfolders become namespaces.	Yes
`agents/<name>.md`	Custom subagents (Subagents).	Yes
`output-styles/`	Output styles for this project (Output styles).	Yes
`hooks.json`, `permissions.json`	Hooks and permission rules kept in their own files instead of `settings.json`.	Yes
`.mcp.json`	MCP servers from older versions. Still loaded, but new servers go to the root `.mcp.json`.	Yes
`agent-memory/<agent>/`	Memory for a custom agent with `memory: project`.	Yes
`agent-memory-local/<agent>/`	Memory for a custom agent with `memory: local`.	No
`worktrees/<name>/`	Git worktrees made by `syntic -w`, background runs and isolated agents (Worktrees).	No (keep it out of git)

Files next to .syntic/ that Syntic Code also reads:

Path	What it is
`.mcp.json`	Project MCP servers, shared through git (MCP servers).
`SYNTIC.local.md`	Your own notes for this checkout. Keep it out of git.
`AGENTS.md`	Read as project memory when a folder has no `SYNTIC.md`.

⚠️

Nothing in a project folder takes effect until you trust the folder. Read a cloned repository’s .syntic/settings.json, hooks.json and .mcp.json before you say yes: hooks and MCP servers run programs on your machine. See Folder trust.

The user folder

Configuration you edit

Path	What it is
`settings.json`	Your settings for every project. `syntic config` and `/config` edit it for you.
`SYNTIC.md`, `rules/`	Personal memory loaded in every project. `/remember <fact>` appends to `SYNTIC.md`.
`skills/`, `commands/`, `agents/`, `output-styles/`	Your personal skills, commands, agents and styles.
`themes/`	Custom color themes (Themes).
`keybindings.json`	Your key bindings (Keybindings).
`hooks.json`, `permissions.json`	Hooks and permission rules in their own files.
`.mcp.json`	MCP servers in the user scope, available in every project.
`update.json`	Update channel and the switch for update checks.

State Syntic Code writes

Path	What it is
`credentials.json`	Your sign-in. Readable by you only.
`trusted_folders`	Folders you said you trust.
`mcp_approvals.json`	Your answers about each project’s MCP servers. `syntic mcp reset-project-choices` clears them for one project.
`history.jsonl`	Prompt history for `↑` and `Ctrl+R`. Turn it off with `SYNTIC_SKIP_PROMPT_HISTORY=1`.
`plans/`	Plans saved from plan mode and `/ultraplan`. Move them with the `plansDirectory` setting.
`file-history/`	Backups of files before each edit, used by rewind.
`cron-jobs.json`	Scheduled routines (move it with `SYNTIC_CRON_FILE`).
`agent-memory/<agent>/`	Memory for custom agents with `memory: user`.
`teams/`	Scratch folders for running agent teams. Removed when a team ends.
`sessions/`	Who-is-running notes and the inbox used by messaging between sessions.
`plugins/`, `mods/`	Installed plugins and mods.
`ide/`	Lock files that editors write so the CLI can find them (`/ide`).
`logs/syntic.log`	Debug logs from interactive sessions (Debug your configuration).
`mcp-tool-cache.json`	Each MCP server’s last tool list, so sessions start faster. Turn it off with `SYNTIC_MCP_TOOL_CACHE=0`.
`remote-managed-settings.json`	The last copy of settings your organization pushes from the server (Server-managed settings).
`bin/`	The `syntic` program, when it was installed into your home folder.

The data folder

Path	What it is
`projects/<project>/`	One folder per project. Each saved session is a subfolder with its transcript, checkpoints and metadata.
`projects/<project>/memory/`	Auto memory: notes the agent keeps for that project, indexed by `MEMORY.md`.
`background/`	The list of background sessions and their logs.

How long things are kept

Data	Kept
Session transcripts	Until removed. Set `"cleanupPeriodDays": N` to delete sessions older than N days automatically.
Logs, plan files, file backups, leftover worktrees of finished agents	Swept by a background cleanup at most once a day, using the same retention window.
Background runs	Until you run `syntic rm <id>` or `syntic sessions --prune`.
Prompt history	Trimmed to a fixed number of recent entries.

Clear local data

To remove	Do
Everything stored about one project (sessions, MCP answers, folder trust)	`syntic project purge [path]`. Add `--dry-run` to see what would go.
One saved session	Delete its folder under `projects/<project>/` in the data folder.
Your sign-in	`syntic auth logout` (or `/logout`).
Finished background runs	`syntic sessions --prune`.
All personal configuration	Delete `~/.syntic/`. You will need to sign in again and re-trust folders.

To keep a single run from being saved at all, start it with syntic --no-session-persistence.

Check what loaded

If a file seems to have no effect:

/memory lists the instruction files loaded in this session.
/context shows how much space each part takes.
/doctor reports settings files with errors, unknown keys, and MCP servers that did not start.
syntic config list --project (or --local) prints what a settings file contains.