To learn more about Local AI topics, check out related posts in the Local AI Series 

Disclaimer: I create this content entirely on my own time, and the views expressed here are mine alone (not my employer’s). Because I love leveraging new tech, I use AI tools like Gemini, NotebookLM, Claude, Perplexity and others as a “digital team” to help research and polish these articles so I can share the best possible insights with you!

You have AgentZero installed and running. Now what? Before you start delegating tasks and building automated workflows, it helps to understand what you actually installed and where everything lives. This guide walks through the file structure, explains how projects work, and shows you where to find the documentation you will inevitably need.

What You Actually Installed

AgentZero is not a single application. It is a framework that lives in /a0/ and splits cleanly into two categories:

• Framework code: Everything in /a0/ that powers the agent loop, tools, and Web UI. This updates when the framework updates.
• Your data: Everything in /a0/usr/ that survives updates and belongs to you.

The distinction matters because you can safely update the framework without touching your customizations, plugins, or project files.

Your Directories Explained

Here is what lives in /a0/usr/, the home for your data:

Directory	Purpose
workdir/	General workspace for scripts, drafts, and working files
projects/	Formal projects with isolated memory, knowledge, and settings
plugins/	Custom plugins you create or install
skills/	Custom skills for specialized tasks
agents/	Subordinate agent profiles you define
memory/	Vector storage for long-term recall
knowledge/	Indexed files for grounded answers
settings.json	Framework configuration
secrets.env	Sensitive credentials (API keys, passwords) — never commit this
.env	Environment variables for local configuration

Please note that you can map the /a0/usr/ folder to your local machine’s drive. (Specifically in this case: it resides on c:\AgentZero\Data\.)

Workdir

Workdir is your legacy workspace. It is a flat directory where you can drop scripts, data files, and experimental code. It works, but it lacks isolation. Everything in workdir shares the same memory and knowledge scope.

Projects

Projects are the modern approach. Each project in /a0/usr/projects/ gets its own .a0proj/ subdirectory containing:

• memory/ — Vector index isolated to this project
• knowledge/ — Files indexed only for this project
• project.json — Project metadata and configuration
• agents.json — Project-specific agent overrides
• skills/ — Project-specific skills and capabilities

When you activate a project, your agent gets scoped memory and knowledge. This prevents cross-contamination between unrelated work. If you are building a marketing automation system, its knowledge should not leak into your personal blog writing project.

Memory and Knowledge: Know the Difference

These terms sound similar but function differently:

• Memory stores facts about you and your preferences. It persists across conversations and tasks. Use it for durable information like your writing style, family details, or recurring workflows.
• Knowledge stores reference documents. The system indexes these files and retrieves relevant chunks when answering questions. Use it for project documentation, research papers, or source material.

Configure your storage locations in settings.json or through the Web UI. Long-term, you will want to move active work into projects with dedicated knowledge folders rather than dumping everything into global memory.

Where Is the Documentation?

Documentation lives in /a0/docs/ with these key guides:

Path	Purpose
guides/usage.md	Comprehensive usage guide
guides/projects.md	Project system explained
guides/memory.md	Memory configuration
guides/skills.md	Creating custom skills
guides/browser.md	Browser automation
setup/installation.md	Installation reference
developer/plugins.md	Plugin development

For quick reference, keep guides/usage.md and guides/projects.md bookmarked. These two files cover 80 percent of what you need to know.

Checking Your Installed Plugins

AgentZero ships with plugins for email, browser automation, memory, and more. Your custom plugins live in /a0/usr/plugins/. To see what is installed, check /a0/plugins/ for framework plugins and /a0/usr/plugins/ for your additions.

Each plugin has a README.md explaining its tools and configuration. Read these before using a plugin for the first time.

Configuration Files You Should Know

• usr/settings.json — Main configuration. Edit through the Web UI or directly.
• usr/secrets.env — API keys and credentials. Never commit this.
• usr/agents/<profile>/ — Agent profile overrides.
• .a0proj/project.json — Per-project settings.

Your Next Steps

1. Move existing work from workdir/ into proper projects
2. Create a project for your current focus and add relevant files to its knowledge/ folder
3. Review docs/guides/projects.md to understand project scoping
4. Check docs/guides/memory.md to configure memory recall thresholds
5. Read docs/guides/skills.md when you are ready to create reusable capabilities

You do not need to master everything today. Start with projects and memory. The rest builds naturally as your workflows grow.

AgentZero Full Structure Example

This document shows a complete example of the AgentZero directory structure with multiple projects, global and project-scoped skills, memory, and knowledge.

Top-Level Structure: /a0/usr/

/a0/usr/
├── agents/                    # Your custom subordinate agent profiles
│   ├── my-researcher/
│   └── my-coder/
│
├── projects/                  # All project workspaces
│   ├── marketing-automation/
│   ├── personal-blog/
│   └── data-analysis/
│
├── skills/                    # GLOBAL skills (available to all projects)
│   ├── email-assistant/
│   │   ├── SKILL.md
│   │   └── templates/
│   └── web-scraper/
│       ├── SKILL.md
│       └── utils.py
│
├── workdir/                   # Legacy/general workspace
│   ├── old-scripts/
│   └── experiments/
│
├── plugins/                   # Your custom plugins
│   └── my-custom-plugin/
│
├── memory/                    # GLOBAL memory (vector store)
│   ├── index.faiss
│   ├── index.pkl
│   └── embedding.json
│
├── knowledge/                 # GLOBAL knowledge (indexed files)
│   ├── reference-docs/
│   └── research-papers/
│
├── settings.json              # Framework configuration
├── secrets.env                # API keys & credentials
└── .env                       # Environment variables

Project 1: marketing-automation

/a0/usr/projects/marketing-automation/
├── .a0proj/                          # Project metadata & isolation
│   ├── project.json                  # Project configuration
│   ├── agents.json                   # Per-project agent overrides
│   ├── variables.env                 # Project variables
│   ├── secrets.env                   # Project secrets
│   │
│   ├── memory/                       # PROJECT-SPECIFIC memory
│   │   ├── index.faiss
│   │   ├── index.pkl
│   │   └── embedding.json
│   │
│   ├── knowledge/                    # PROJECT-SPECIFIC knowledge
│   │   ├── brand-guidelines.pdf
│   │   ├── competitor-analysis/
│   │   └── marketing-playbooks/
│   │
│   └── skills/                       # PROJECT-SPECIFIC skills
│       ├── ab-test-setup/
│       │   ├── SKILL.md
│       │   └── sample-code.py
│       ├── email-sequence/
│       │   ├── SKILL.md
│       │   └── templates/
│       └── ad-creative/
│           ├── SKILL.md
│           └── assets/
│               ├── headline-formulas.txt
│               └── image-templates/
│
├── campaigns/                        # Project work files
├── analytics/
└── content-calendar/

Project 2: personal-blog

/a0/usr/projects/personal-blog/
├── .a0proj/
│   ├── project.json
│   ├── agents.json
│   ├── variables.env
│   ├── secrets.env
│   │
│   ├── memory/                       # Isolated blog memory
│   │   ├── index.faiss
│   │   ├── index.pkl
│   │   └── embedding.json
│   │
│   ├── knowledge/                    # Blog-specific knowledge
│   │   ├── previous-posts/
│   │   ├── style-guide.md
│   │   └── topic-ideas/
│   │
│   └── skills/                       # Blog-specific skills
│       └── wordpress-publish/
│           ├── SKILL.md
│           └── wordpress-api.py
│
├── drafts/
├── published/
└── images/

Project 3: data-analysis

/a0/usr/projects/data-analysis/
├── .a0proj/
│   ├── project.json
│   ├── agents.json
│   ├── variables.env
│   ├── secrets.env
│   │
│   ├── memory/                       # Analysis project memory
│   │   ├── index.faiss
│   │   ├── index.pkl
│   │   └── embedding.json
│   │
│   ├── knowledge/                    # Domain knowledge
│   │   ├── datasets/
│   │   ├── methodology-docs/
│   │   └── visualization-examples/
│   │
│   └── skills/                       # Analysis skills
│       ├── data-cleaning/
│       │   ├── SKILL.md
│       │   └── cleaning-scripts/
│       └── reporting/
│           ├── SKILL.md
│           └── report-templates/
│
├── raw-data/
├── processed-data/
└── outputs/

Key Structure Summary

Location	Scope	Purpose
/a0/usr/skills/<skill>/	Global	Available to all agents and projects
/a0/usr/memory/	Global	Shared long-term memory
/a0/usr/knowledge/	Global	Shared reference documents
/a0/usr/projects/<project>/.a0proj/skills/<skill>/	Project	Only available within that project
/a0/usr/projects/<project>/.a0proj/memory/	Project	Isolated memory for that project
/a0/usr/projects/<project>/.a0proj/knowledge/	Project	Knowledge specific to that project

How It Works

Global Skills

• Located in /a0/usr/skills/
• Available to all projects and the main agent
• Use for reusable capabilities like “email-assistant” or “web-scraper”

Project-Specific Skills

• Located in project/.a0proj/skills/
• Only available when that project is active
• Use for domain-specific capabilities that don’t belong in global scope
• Keep assets and scripts in the skill folder

Memory Isolation

• Global memory: /a0/usr/memory/ — shared across all work
• Project memory: project/.a0proj/memory/ — isolated to that project
• When you activate a project, only that project’s memory is available

Knowledge Scoping

• Global knowledge: /a0/usr/knowledge/ — reference for all work
• Project knowledge: project/.a0proj/knowledge/ — reference for specific project
• Knowledge files are indexed and retrieved when relevant to the query

Best Practices

1. Use global skills for truly reusable capabilities
2. Use project skills when the skill is tightly coupled to project knowledge
3. Keep work files at project root, metadata in .a0proj/
4. Scope memory carefully — sensitive or unrelated data should live in project memory
5. Index knowledge appropriately — put files where the agent should find them

Example Workflow

1. Create project: "marketing-automation"
2. Add global skills: use email-assistant from /a0/usr/skills/
3. Create project skills: ab-test-setup in .a0proj/skills/
4. Add knowledge: upload competitor reports to .a0proj/knowledge/
5. Activate project: agent now has isolated memory + scoped knowledge + project skills
6. Work: agent recalls project context, uses appropriate skills, references right documents

Written with the help of Agent Zero

Have questions, ideas to share, or just want to connect? I’d love to hear from you! Check out my About Page to learn more about me or connect with me.