File Locations

AGH uses one global home directory plus optional workspace-local .agh/ directories. The global home defaults to ~/.agh and can be changed with AGH_HOME.

Quick Reference

Global Home

EnsureHomeLayout creates the root, agents, skills, memory, sessions, and logs directories. Individual files are created by the features that own them.

Global Runtime Files

Provider Home Files

When a provider sets home_policy = "isolated", AGH creates a private provider home under $AGH_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. AGH 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 $AGH_HOME/sessions/<session-id>/. After session stop, AGH materializes a read-only forensic JSONL ledger under $AGH_HOME/sessions/<workspace_id>/<session_id>/ledger.jsonl. Unbound sessions (no resolved workspace) materialize under $AGH_HOME/sessions/_unbound/<session_id>/.

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

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

~/.agh/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.

Agent Files

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

Skill Files

Skill filesystem precedence is bundled, marketplace, user, additional root, then workspace, with the winning agent's skills/ directory applied 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.

Workspace Files

my-project/
  .env
  .agh/
    workspace.toml
    config.toml
    mcp.json
    agents/
    skills/
    memory/
      MEMORY.md
      _system/

AGH only loads the .agh/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: global, workspace, and agent (with agent_tier = {workspace, 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.

~/.agh/memory/
  MEMORY.md
  user_review-style.md
  feedback_test-integrity.md
  _inbox/
  _system/
    dreaming/
    extractor/
    extractor/failures/
    ad_hoc/

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

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

<workspace>/.agh/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 AGH finds the primary workspace root.