> ## Documentation Index
> Fetch the complete documentation index at: https://drevon.trysudosu.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Modes

> Hub mode vs Project mode — two ways to organize your AI workspace.

## Overview

Drevon supports two workspace modes, each designed for a different workflow:

|                   | Hub Mode                           | Project Mode           |
| ----------------- | ---------------------------------- | ---------------------- |
| **Best for**      | Multi-project workspaces           | Single codebases       |
| **Users**         | Founders, researchers, generalists | Developers, teams      |
| **Memory**        | Cross-project context              | Project-scoped context |
| **Workspace dir** | `workspace/` for projects          | Not created            |

## Hub Mode

Hub mode creates a **centralized workspace** where you manage multiple projects from a single directory. It's designed for people who context-switch between different projects and need their AI agents to maintain awareness across all of them.

```bash theme={null}
npx drevon init --hub
```

### Directory Structure

```
my-workspace/
├── drevon.config.json
├── .drevon/
│   ├── memory/
│   │   ├── INDEX.md          # Tier 0 — read eagerly at session start (budget-capped)
│   │   ├── topics/           # Tier 1 — read on demand
│   │   │   ├── user.md           # Your preferences & decisions
│   │   │   ├── projects.md       # Registry of all projects
│   │   │   └── systems.md        # Infrastructure & systems
│   │   ├── log/              # Tier 2 — episodic monthly segments, never read eagerly
│   │   └── archive/          # Non-destructive storage for compacted/migrated originals
│   ├── skills/
│   └── prompts/
├── workspace/
│   ├── project-alpha/
│   ├── project-beta/
│   └── landing-page/
├── .github/copilot-instructions.md
├── CLAUDE.md
└── AGENTS.md
```

### Memory Files

| File                 | Purpose                                                                                              | Update via                                  |
| -------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `INDEX.md`           | Workspace one-liner, active focus, topic pointers, recent log headlines — the only file read eagerly | Maintained automatically by `drevon memory` |
| `topics/user.md`     | Your preferences, communication style, confirmed decisions                                           | `drevon memory learn --topic user`          |
| `topics/projects.md` | Registry of all workspace projects with status                                                       | `drevon memory learn --topic projects`      |
| `topics/systems.md`  | Systems, infrastructure, and conventions                                                             | `drevon memory learn --topic systems`       |
| `log/<YYYY-MM>.md`   | Episodic action journal, split into monthly segments                                                 | `drevon memory log`                         |

### Workspace Rules

Hub mode includes a `workspace` section in the config that instructs agents to:

* Keep projects organized in `workspace/` subdirectories
* Name folders after the task
* Never create files outside `workspace/` unless explicitly told
* Register new projects in `topics/projects.md`

## Project Mode

Project mode **embeds AI capabilities into an existing codebase**. It's designed for repositories where a team collaborates and needs consistent AI behavior without affecting the project structure.

```bash theme={null}
cd my-app
npx drevon init --project
```

### Directory Structure

```
my-app/
├── src/                      # Existing code (untouched)
├── package.json              # Existing config (untouched)
├── drevon.config.json
├── .drevon/
│   ├── memory/
│   │   ├── INDEX.md          # Tier 0 — read eagerly at session start (budget-capped)
│   │   ├── topics/           # Tier 1 — read on demand
│   │   │   ├── architecture.md   # Project context, structure, key files
│   │   │   ├── patterns.md       # Code patterns & conventions
│   │   │   └── decisions/        # One file per decision: YYYY-MM-DD-slug.md
│   │   ├── log/              # Tier 2 — episodic monthly segments, never read eagerly
│   │   └── archive/          # Non-destructive storage for compacted/migrated originals
│   ├── skills/
│   └── prompts/
├── .github/copilot-instructions.md
├── CLAUDE.md
└── AGENTS.md
```

### Memory Files

| File                                | Purpose                                                                                            | Update via                                  |
| ----------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `INDEX.md`                          | Project one-liner, active focus, topic pointers, recent log headlines — the only file read eagerly | Maintained automatically by `drevon memory` |
| `topics/architecture.md`            | Project overview, architecture, key files, dependencies                                            | `drevon memory learn --topic architecture`  |
| `topics/patterns.md`                | Code patterns, conventions, anti-patterns, testing patterns                                        | `drevon memory learn --topic patterns`      |
| `topics/decisions/<date>-<slug>.md` | One ADR-style decision record per file                                                             | `drevon memory decide`                      |
| `log/<YYYY-MM>.md`                  | Episodic action journal, split into monthly segments                                               | `drevon memory log`                         |

<Tip>
  Project mode's decision files under `topics/decisions/` follow the [ADR (Architecture Decision Records)](https://adr.github.io/) format — a proven practice for documenting technical decisions with context, options considered, and rationale. One file per decision keeps PR review and merges clean.
</Tip>

## Auto-Detection

When you run `drevon init` without `--hub` or `--project`, Drevon automatically suggests a mode:

| Signal                  | Suggested Mode | Reason                 |
| ----------------------- | -------------- | ---------------------- |
| Git repository detected | Project        | Existing codebase      |
| `package.json` exists   | Project        | Node.js project        |
| `src/` directory exists | Project        | Source code present    |
| `workspace/` exists     | Hub            | Hub structure detected |
| Empty directory         | Hub            | Fresh workspace        |

You can always override the suggestion during the interactive wizard.

## Switching Modes

<Warning>
  Switching modes after initialization requires re-running `drevon init` and will regenerate memory files. Back up any important memory content first.
</Warning>

To switch from hub to project mode (or vice versa):

1. Back up `.drevon/memory/` if it contains important context
2. Edit `mode` in `drevon.config.json`
3. Update `memory.files` to match the new mode's file set
4. Run `drevon sync`
5. Manually create any missing memory files