File Locations

CompozyOS uses one user home directory plus optional personal-profile and workspace-local .compozy/ directories. The user home defaults to ~/.compozy and can be changed with COMPOZY_HOME.

Quick Reference

Profile resource discovery is most-specific first: workspace named profile, workspace base, personal profile, then user. A workspace named profile activates only when its directory name matches the active profile; unmatched directories stay dormant.

Global Home

EnsureHomeLayout creates the root, agents, skills, loops, profiles, the default profile directory and its memory directory, sessions, logs, and gateway directories. Individual files are created by the features that own them.

Profile Files

Profile config.toml and mcp.json files whose directory name is absent from the profile catalog are ignored and reported as config_profile_layer_orphaned. Creating the named profile adopts them.

What a profile does and does not own is explained in Profiles; the repository-side folders are how a division of contexts travels with a checkout.

Global Runtime Files

Provider Home Files

When a provider sets home_policy = "isolated", CompozyOS creates a private provider home under $COMPOZY_HOME/providers/<provider> with 0700 permissions. The launch environment points HOME, PROVIDER_HOME, XDG directories, and known provider-specific variables such as CLAUDE_CONFIG_DIR, CODEX_HOME, and OPENCODE_CONFIG_DIR at that directory. CompozyOS never copies credentials from the operator home into an isolated provider home.

The default home_policy = "operator" does not create this directory and lets native ACP CLIs use their existing login/session state.

Session Files

Live sessions own a directory under $COMPOZY_HOME/sessions/<session-id>/. After session stop, CompozyOS materializes a read-only forensic JSONL ledger under $COMPOZY_HOME/sessions/<workspace_id>/<session_id>/ledger.jsonl. Unbound sessions (no resolved workspace) materialize under $COMPOZY_HOME/sessions/_unbound/<session_id>/.

~/.compozy/sessions/<session-id>/
  events.db
  meta.json

~/.compozy/sessions/<workspace_id>/<session_id>/
  ledger.jsonl

~/.compozy/sessions/_unbound/<session_id>/
  ledger.jsonl

The forensic ledger is never a memory scope, never queried by recall, and never accepted as a controller write target — it is operator-readable history only. After materialization, live events.db rows for the same session are purged once [memory.session] events_purge_grace elapses.

When a stopped session resumes, CompozyOS removes its materialized ledger before accepting new events. The append-only events.db remains the source of truth, and the next stop writes a new ledger with the complete history. A failed provider resume restores the stopped projection.

Agent Files

Agent discovery order is workspace root, additional roots in registered order, then global home. First name wins.

Skill Files

Two more families of skill directories are scanned when configuration turns them on. Folder conventions from other agent tools come from skills.sources, and free-form directories come from skills.custom_sources:

Preset roots are fixed paths CompozyOS knows; custom roots are the exact directories you list, with no .compozy/skills suffix appended. A custom source takes its display name from the directory's own name. Exposure links are the only files CompozyOS writes outside its own folders, and it writes them only when you ask.

Skill filesystem precedence is bundled, marketplace, user, personal profile, additional root, workspace, workspace named profile, then the winning agent's skills/ directory as a final overlay. Enabled extensions can also register runtime-owned skills into the live registry. Those overlays do not come from a filesystem path, so they are documented in Skills Overview rather than in this file-path table.

Every <group>/.../ segment above is optional and organizational. CompozyOS discovers skill leaves at any depth, and the name in each leaf's frontmatter remains its resolver identity.

Workspace Files

my-project/
  .env
  .agents/
    skills/                 # scanned when skills.sources includes "agents"
  .claude/
    skills/                 # scanned when skills.sources includes "claude"
  .compozy/
    workspace.toml
    config.toml
    mcp.json
    agents/
    skills/
    memory/
      MEMORY.md
      _system/

CompozyOS only loads the .compozy/config.toml for the resolved primary workspace root. Additional roots are resource discovery roots for agents and skills; they do not contribute config overlays.

Memory Files

Memory v2 lives in three scopes: profile, workspace, and agent (with agent_tier = {workspace, global} — the agent tier is a separate axis and keeps the word global). Curated entries are Markdown-authoritative on disk; SQLite catalogs, FTS5 indexes, decision WAL rows, and memory_events are derived from controller activity. The _system/ directory in every scope hosts machine-managed artifacts (dreaming, extractor failures, ad-hoc notes) and is never injected into prompts.

~/.compozy/profiles/<name>/memory/
  MEMORY.md
  user_review-style.md
  feedback_test-integrity.md
  _inbox/
  _system/
    dreaming/
    extractor/
    extractor/failures/
    ad_hoc/

~/.compozy/agents/<agent>/memory/
  MEMORY.md
  user_pedro-style.md
  _system/

<workspace>/.compozy/memory/
  MEMORY.md
  project_runtime-docs.md
  reference_session-events.md
  _system/

<workspace>/.compozy/agents/<agent>/memory/
  MEMORY.md
  project_repo-rules.md
  _system/

Extension Files

Extension registry records are stored in the global database, not in a separate user-authored config file.

Path Overrides

Special Cases

Related Pages

• config.toml documents the schema for global and workspace config files.
• mcp.json documents JSON sidecars.
• Workspace Resolver explains how CompozyOS finds the primary workspace root.