Agent Project Structure

A minimal agent project usually looks like this:

your-project/
├── PROFILE.md
├── SOUL.md
├── downcity.json
├── .downcity/
└── your application code

PROFILE.md

PROFILE.md defines the agent's outward role, communication style, and behavior boundaries.

Typical content includes:

• who the agent is
• who it serves
• which rules it should follow
• how it should respond

Think of it as the role definition rather than runtime configuration.

SOUL.md

SOUL.md defines deeper, more stable operating principles.

It is a better place for long-term behavioral rules that should persist across many conversations and runtime changes.

downcity.json

downcity.json is the project's structured runtime config.

The fields users change most often are:

• name
• execution
• services.chat.channels.*
• context

If PROFILE.md and SOUL.md are human-readable principles, downcity.json is what the runtime consumes structurally.

.downcity/

.downcity/ is the runtime directory.

It typically contains:

• session messages
• logs
• cache
• task run artifacts
• schema files
• daemon state files

You usually do not edit it manually, but you will inspect it often during troubleshooting.

Which file should you edit?

• change identity or response style: edit PROFILE.md
• change deeper long-term principles: edit SOUL.md
• change model, services, or channel bindings: edit downcity.json
• inspect runtime artifacts or debug state: inspect .downcity/

A good maintenance split

Keeping these concerns separate makes the project much easier to evolve:

1. role and output style: PROFILE.md
2. long-term principles: SOUL.md
3. structured runtime config: downcity.json
4. runtime artifacts: .downcity/

Continue with:

• downcity.json basics
• PROFILE and SOUL
• Storage layout