Skip to main content

​
Hub Files & Structure

Every Hubify workspace follows a reserved file structure that your agent understands immediately. This is Hubify’s answer to “where does everything go?” — a standard layout that works across all platforms (Claude Code, Cursor, OpenClaw, Windsurf) and all templates. When you deploy a workspace, the reserved structure is seeded from your chosen template. Agents read these files on startup, write to them during operation, and rely on them for persistent context.

​
Complete File Tree

workspace/
  HUB.yaml              # Workspace manifest (the brain)
  AGENTS.md             # Agent operational instructions
  SOUL.md               # Agent personality and identity
  USER.md               # Your profile (auto-generated from signup)
  MEMORY.md             # Curated long-term memory
  HEARTBEAT.md          # Proactive checklist
  WELCOME.md            # First-boot welcome message
  BOOTSTRAP.md          # First-run setup (deleted after use)
  IDENTITY.md           # Extended identity (optional)
  TOOLS.md              # Platform-specific notes (optional)
  PROJECTS.md           # Project index (auto-generated)
  TASKS.md              # Task index (read-only, from Convex)
  LEARNINGS.md          # Learnings index
  KNOWLEDGE.md          # Knowledge base index

  .hub/                 # Runtime state (gitignored)
    agents.json
    sync.log
    cache/

  memory/               # Episodic daily files
    YYYY-MM-DD.md       # Daily memory logs

  skills/               # Installed skills
    skill-name/
      SKILL.md

  knowledge/            # Curated evergreen knowledge
    topic-name.md
    INDEX.md

  learnings/            # Extracted learnings
    YYYY-MM-DD.md
    INDEX.md

  projects/             # USER SPACE (anything goes)

​
Reserved Files

​
HUB.yaml — The Workspace Manifest

HUB.yaml is the master configuration file for your entire workspace. Every connected agent reads it on startup. It defines the template, mode, skills, integrations, model routing, privacy settings, and connected agents. 
hub:
  version: "2.0"
  id: "hub_abc123"
  name: "Houston's OS"
  owner: "houston"
  template: "myos"
  created: "2026-02-19T00:00:00Z"

mode: "guided"          # guided | power | open

models:
  default: "anthropic/claude-sonnet-4-6"
  routing:
    orchestrator: "anthropic/claude-sonnet-4-6"
    coder: "anthropic/claude-opus-4-6"
    reviewer: "anthropic/claude-sonnet-4-6"
    automation: "anthropic/claude-haiku-4-5"

skills:
  registry: "hubify"
  installed:
    - { id: "strava", version: "1.2.3" }
    - { id: "github", version: "2.0.1" }
    - { id: "telegram-topics", version: "1.0.0" }

integrations:
  - id: telegram
    status: connected
    mode: auto
  - id: github
    status: connected
    mode: auto

agent:
  heartbeat: "30m"

intelligence:
  global: opt-in

privacy:
  contribute_to_global: false
  vault_shared_across_workspaces: true

context:
  reserved_files:
    - AGENTS.md
    - SOUL.md
    - USER.md
    - MEMORY.md
    - HEARTBEAT.md
  memory_dir: "./memory"
  learnings_dir: "./learnings"
  knowledge_dir: "./knowledge"
HUB.yaml is the single source of truth. If something is configurable in your workspace, it is configured here.
Do not store secrets or API keys in HUB.yaml. Credentials belong in the encrypted vault, referenced via vault://keys/service-name URIs.

​
SOUL.md — Agent Personality

SOUL.md defines who your agent is — its tone, priorities, communication style, values, and decision-making tendencies. Every agent reads this file at the start of every conversation. Templates seed SOUL.md with useful defaults. A Founder OS template ships a SOUL.md tuned for GTM operations. A Dev OS template ships one tuned for code review and deployment. You customize it freely after deployment. Key points:
  • Read by all connected agents on every conversation start
  • Defines identity, not behavior (behavior goes in AGENTS.md)
  • Keep it under 500 words for reliable agent processing
  • Be specific, not generic
See the Customizing Templates guide for examples and writing tips.

​
AGENTS.md — Operational Instructions

AGENTS.md defines behavioral rules for all connected agents — when to ask versus act autonomously, which tools to use, how to handle specific situations, communication channel preferences. Key points:
  • Applies to all agents connected to the workspace (cloud, local, platform-specific)
  • Defines behavior, not identity (identity goes in SOUL.md)
  • Include autonomy rules, tool usage guidelines, and escalation criteria
  • Platform-agnostic — write instructions that work on Claude Code, Cursor, and OpenClaw

​
USER.md — User Profile

USER.md contains your profile information. It is auto-generated during signup with your username and preferences, and auto-updated as you configure your workspace. Your agent reads USER.md to understand who it is working for — your name, timezone, communication preferences, and any personal context you choose to include.

​
MEMORY.md — Long-Term Curated Memory

MEMORY.md is your agent’s curated long-term memory. Unlike the daily memory logs in memory/, this file contains the most important, evergreen context that your agent should always have access to. Key points:
  • Read by agents on every conversation start
  • Curated by both you and your agent (agent suggests additions, you approve)
  • Contains high-signal information: key decisions, important contacts, ongoing projects, personal preferences
  • Not a dumping ground — keep it focused and updated

​
HEARTBEAT.md — Proactive Checklist

HEARTBEAT.md is the checklist your agent reviews on each heartbeat cycle. The heartbeat interval is configured in HUB.yaml (agent.heartbeat: "30m"). Key points:
  • Agent reviews this file on each heartbeat cycle
  • Use priority levels (Blocking, Standard, Low Priority)
  • Blocking items are processed first
  • Low-priority items are skipped when there is active work in progress
See the Customizing Templates guide for heartbeat configuration details.

​
WELCOME.md — First-Boot Message

WELCOME.md is displayed to the user on first login after workspace deployment. It introduces the workspace, explains what was set up, and provides next steps. Templates include their own WELCOME.md with template-specific onboarding guidance.

​
BOOTSTRAP.md — First-Run Setup

BOOTSTRAP.md contains one-time setup instructions that the agent executes on first boot. After the bootstrap tasks complete, this file is automatically deleted. Examples of bootstrap tasks:
  • Installing initial skills from the template
  • Seeding memory with template defaults
  • Running first-time integration configuration

​
IDENTITY.md — Extended Identity (Optional)

IDENTITY.md is an optional file for extended agent identity information that does not fit in SOUL.md. Use it for detailed background context, domain expertise descriptions, or extended personality parameters.

​
TOOLS.md — Platform-Specific Notes (Optional)

TOOLS.md stores platform-specific notes and configuration guidance. If your agent needs to behave differently on Claude Code versus Cursor versus OpenClaw, document those differences here.

​
PROJECTS.md — Project Index

PROJECTS.md is auto-generated and provides an index of projects in your workspace. Agents write project entries here as they track ongoing work.

​
TASKS.md — Task Index (Read-Only)

TASKS.md is read-only and auto-generated from the Convex task store. Agents write tasks to the API, not to this file directly. The file is regenerated on every sync. This prevents the “tasks in markdown that nothing reads” problem. The real task data lives in Convex; this file is a human-readable view of it.
Do not edit TASKS.md manually. Changes will be overwritten on the next sync. To create or update tasks, use the API or CLI.

​
LEARNINGS.md — Learnings Index

LEARNINGS.md is an auto-updated index of extracted learnings from agent executions. It links to the detailed learning files in the learnings/ directory.

​
KNOWLEDGE.md — Knowledge Base Index

KNOWLEDGE.md is the index for your curated knowledge base. It links to topic files in the knowledge/ directory.

​
Reserved Directories

​
.hub/ — Runtime State

The .hub/ directory stores runtime state used by the Hubify sync system. It is gitignored and managed automatically.
FilePurpose
agents.jsonLive registry of all connected agents (cloud, local, platform-specific)
sync.logSync history — what was pushed and pulled, when
cache/Local intelligence cache for fast access to frequently used data
You should not edit files in .hub/ manually. The sync system manages this directory.

​
memory/ — Episodic Daily Files

The memory/ directory stores time-based episodic memory. Your agent creates a new file each day using the YYYY-MM-DD.md naming convention. 
memory/
  2026-02-21.md
  2026-02-22.md
  2026-02-23.md
Each daily file contains what happened that day — tasks completed, decisions made, conversations had, learnings captured. Agents write to today’s file throughout the day and read from recent files for context. Memory files are synced between local and cloud agents via Convex, so both your local agent and your cloud agent contribute to and read from the same memory store.

​
skills/ — Installed Skills

The skills/ directory contains installed skills from the Hubify registry. Each skill has its own subdirectory with a SKILL.md file describing what it does, its inputs, outputs, and execution instructions. 
skills/
  strava-sync/
    SKILL.md
  github-pr-reviewer/
    SKILL.md
  telegram-topics/
    SKILL.md
Skills are installed via hubify install <skill-name> or through the web dashboard. The registry currently contains 5,892+ skills.

​
knowledge/ — Curated Evergreen Knowledge

The knowledge/ directory stores curated, evergreen knowledge that is not time-bound (unlike memory, which is episodic). Topics live in individual markdown files, and INDEX.md provides a searchable index. 
knowledge/
  INDEX.md
  react-patterns.md
  client-onboarding-process.md
  api-design-guidelines.md
Your agent curates this directory over time, extracting reusable knowledge from daily work and organizing it by topic.

​
learnings/ — Extracted Learnings

The learnings/ directory stores structured lessons learned from agent executions. These are extracted automatically when an agent completes a task, encounters an error, or discovers a better approach. 
learnings/
  INDEX.md
  2026-02-21.md
  2026-02-22.md
  2026-02-23.md
Learnings can optionally be contributed to the global intelligence layer (the Singularity) if contribute_to_global: true is set in HUB.yaml. Otherwise, they stay private to your workspace.

​
projects/ — User Space

The projects/ directory is your space. It is not part of the reserved structure — you can organize it however you want. Your agent will not modify files in projects/ without explicit permission. Use it for:
  • Code repositories
  • Client deliverables
  • Personal files
  • Anything that does not fit the reserved structure

​
Reserved vs. User Space

Everything in the reserved structure (the files and directories listed above) is managed by a combination of you, your agent, and the Hubify sync system. Agents know how to read and write these files because the format is standardized across all workspaces. Everything outside the reserved structure is your space. You organize it however you want. Agents interact with user-space files only when you explicitly ask them to.
ReservedUser Space
HUB.yaml, SOUL.md, AGENTS.md, etc.projects/ and any custom directories
memory/, skills/, knowledge/, learnings/Your code repositories
Managed by agents + sync systemManaged by you
Standardized formatAny format you want
If you are not sure where something goes: if it is context your agent needs to do its job, it goes in the reserved structure. If it is your work product, it goes in projects/ or your own directories.

​
Open Mode

Users can disable the reserved structure entirely by setting mode: "open" in HUB.yaml. In Open Mode, all reserved files and directories become optional. The workspace becomes raw OpenClaw with no template constraints. Toggling back to Guided or Power mode re-scaffolds any missing reserved files without overwriting existing ones.

​
Next Steps

Customizing Templates

Edit SOUL.md, AGENTS.md, skills, model routing, and more

Guardrails & Safety

Control what your agent can do autonomously

Templates

Browse templates that seed this file structure

Hub File Format Reference

Full HUB.yaml specification reference