ctx0 Vault Structure

This document defines the folder structure of the ctx0 vault, including locked system folders and flexible user folders.

Overview

The vault is a hierarchical file system stored in Supabase (database + storage). It contains:

• Locked folders: System folders that cannot be renamed or deleted (agents, skills, tools, mcp, .ctx0)
• User folders: Flexible folders that users can create, rename, and organize freely

The structure is represented in ctx0_entries table with actual file content stored in the ctx0-vault storage bucket.

Folder Structure

vault/
├── .ctx0/                        # LOCKED: System configuration (hidden)
│   ├── config.json               # Global ctx0 settings
│   ├── schema_version.json       # Current schema version
│   └── user_id                   # Bytespace user ID
│
├── agents/                       # LOCKED: Agent configurations
│   ├── _index.md                 # Overview of all agents
│   ├── ctx0/                     # Default vault navigator
│   │   ├── AGENT.md              # System prompt
│   │   └── config.json           # Tools, permissions, model
│   ├── curator/                  # Default vault organizer
│   │   ├── AGENT.md
│   │   └── config.json
│   └── {user-agents}/            # User-created agents
│
├── skills/                       # LOCKED: DB-as-skill definitions
│   ├── _index.md                 # Overview of skills
│   ├── gmail/                    # Email sync skill
│   │   ├── SKILL.md              # Schema + query patterns
│   │   └── _results/             # Cached query results
│   ├── slack/
│   ├── calendar/
│   └── {user-skills}/
│
├── tools/                        # LOCKED: Tool definitions
│   ├── _index.md                 # Overview of tools
│   ├── ctx0_remember/
│   │   └── TOOL.md
│   ├── ctx0_retrieve/
│   ├── ctx0_sql/
│   └── {user-tools}/
│
├── mcp/                          # LOCKED: MCP server configurations
│   ├── _index.md                 # Overview of MCP
│   ├── mcp.json                  # Server definitions
│   └── {user-configs}/
│
├── contacts/                     # User folder (flexible)
├── projects/                     # User folder (flexible)
├── knowledge/                    # User folder (flexible)
├── decisions/                    # User folder (flexible)
├── preferences/                  # User folder (flexible)
└── {user-defined}/               # User can create any folders

Locked Folders

These folders are locked - they cannot be renamed, moved, or deleted. The system depends on their structure.

.ctx0/ (Hidden System Config)

Hidden folder containing system-level configuration.

Example config.json:

{
  "embedding_model": "text-embedding-3-small",
  "auto_remember": true,
  "retention_days": 365,
  "sync_interval_minutes": 15
}

agents/

Contains agent configurations. Each agent has its own folder with AGENT.md and config.json.

See ctx0 Agents for the full agent system documentation.

Default agents:

Users can:

• Create new agents in agents/{name}/
• Modify agent configurations
• Cannot delete default agents (is_system=true)

skills/

Contains DB-as-skill definitions. Each skill teaches agents how to query a sync table.

See ctx0 Skills for the full skill system documentation.

Structure per skill:

skills/gmail/
├── SKILL.md              # Schema, examples, query patterns
└── _results/             # Agent-created query result cache
    ├── investor-threads.md
    └── term-sheet-emails.md

Users can:

• Create new skills when they add sync integrations
• Modify skill definitions
• Cannot delete the skill folder structure

tools/

Contains tool definitions that describe available tools for agents.

Structure per tool:

tools/ctx0_remember/
└── TOOL.md               # Description, parameters, examples

Default tools:

mcp/

Contains MCP (Model Context Protocol) server configurations.

Structure:

mcp/
├── _index.md             # Overview of MCP in ctx0
├── mcp.json              # MCP server definitions
└── managed-mcp.json      # Optional: admin-locked configs

Example mcp.json:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

Users can:

• Add new MCP server configurations
• Modify existing configurations
• Cannot delete the mcp folder itself

User Folders

These folders are flexible - users can create, rename, move, and delete them freely.

Default User Folders

Creating User Folders

Users can create any folder structure they want:

vault/
├── work/
│   ├── acme-corp/
│   └── side-projects/
├── personal/
│   ├── health/
│   └── finances/
└── learning/
    ├── courses/
    └── books/

The curator agent helps organize content into appropriate folders.

Entry Types

Each file in the vault has an entry_type that indicates what kind of content it is.

File Formats

AGENT.md Format

See ctx0 Agents for details.

---
name: my-agent
description: What this agent does
tools:
  - ctx0_remember
  - ctx0_retrieve
model: inherit
---

You are my-agent. Your instructions here...

SKILL.md Format

See ctx0 Skills for details.

---
name: gmail
description: Query email data from Gmail sync
table: sync_gmail
---

# Gmail Skill

Schema and query patterns for sync_gmail table...

TOOL.md Format

---
name: ctx0_remember
description: Store new information in the vault
parameters:
  - name: content
    type: string
    required: true
    description: The content to remember
  - name: path
    type: string
    required: false
    description: Suggested path for storage
---

# ctx0_remember

Store new information in the vault for later retrieval...

## Usage

\`\`\`typescript
ctx0_remember({
  content: "Sarah prefers morning meetings",
  path: "/contacts/sarah-chen.md"
})
\`\`\`

User Content Format

User content (contacts, projects, notes) uses markdown with optional YAML frontmatter:

---
title: Sarah Chen
type: contact
tags:
  - investor
  - sequoia
links:
  - /projects/funding-round.md
---

# Sarah Chen

Partner at Sequoia. Met at YC Demo Day 2024.

## Contact Info
- Email: sarah@sequoia.com
- Twitter: @sarahchen

## Notes
- Prefers morning meetings
- Interested in AI infrastructure

System vs User Entries

ctx0 uses a fork-on-edit pattern for system entries. Default entries (agents, folders) are defined in code, not in the database. Users see a merged view of system entries + their customizations.

See ctx0 System Entries for full documentation.

Entry Flags

How It Works

1. System entries are defined in packages/ctx0/src/system-entries/
2. Merged at read time - users see system entries + their own entries
3. Fork on edit - editing a system entry creates a user copy with is_fork=true
4. Reset to default - deleting a fork reverts to the system version

Benefits

• No database seeding required
• Instant updates to all users when code changes
• Users can customize but always reset to defaults
• Clean separation: user table only has their customizations

Vault Initialization

New vaults require no database seeding. System entries are defined in code and merged at read time.

What Exists in Code (System Entries)

These are defined in packages/ctx0/src/system-entries/:

• Locked folders: /agents/, /skills/, /agents/ctx0/, /agents/curator/
• Default agents: ctx0 and curator with AGENT.md and config.json

What Users Create

Users can create entries in their ctx0_entries table:

• Custom agents in /agents/{name}/
• Contacts, projects, knowledge, decisions
• Forks of system entries (customizations)

Legacy Initialization

For backwards compatibility, some systems may still seed:

1. Create suggested user folders (optional)

   • contacts/, projects/, knowledge/, decisions/, preferences/

2. Create .ctx0/ config (if needed)

   • .ctx0/config.json - Global settings

Path Conventions

Reserved prefixes:

• _ (underscore) - System/internal files
• . (dot) - Hidden files/folders

Related Documentation

• ctx0 System Entries - Fork-on-edit pattern for global defaults
• ctx0 Supabase Data Architecture - Database schema
• ctx0 Agents - Agent system design
• ctx0 Skills - DB-as-skill pattern
• ctx0 Sessions - Session/conversation storage