# Storage Structure

Complete reference for mehrhof storage layout.

## Overview

Mehrhof uses a split storage structure:

**In project** (`.mehrhof/`):
- `config.yaml` - Workspace configuration (safe to commit)
- `.env` - Project-specific secrets (gitignored)

**In home directory** (`~/.valksor/mehrhof/workspaces/<project-id>/`):
- `.active_task` - Current active task reference
- `work/` - Task work directories

```
project/
└── .mehrhof/
    ├── config.yaml              # Workspace configuration
    └── .env                     # Secrets (gitignored)

~/.valksor/mehrhof/workspaces/<project-id>/
├── .active_task                # Current active task reference
└── work/                       # Task work directories
    └── <task-id>/
        ├── work.yaml            # Task metadata
        ├── notes.md             # User notes
        ├── source/              # Source files (task content)
        ├── specifications/      # Specifications
        ├── reviews/             # Code reviews
        └── sessions/            # Agent conversation logs
```

The `<project-id>` is automatically derived from your git remote (e.g., `github.com-user-repo`).

## Project Files

### config.yaml

Workspace-level configuration (in project):

```yaml
git:
  auto_commit: true
  commit_prefix: "[task]"
  branch_pattern: task/{task_id}

agent:
  default: claude
  timeout: 300

workflow:
  session_retention_days: 30
```

### .env

Project-specific secrets (in project, gitignored):

```bash
ANTHROPIC_API_KEY=sk-ant-...
GITHUB_TOKEN=ghp_...
```

## Home Directory Files

### .active_task

Currently active task reference (in home directory, YAML):

```yaml
id: cb9a54db
ref: file:task.md
work_dir: ~/.valksor/mehrhof/workspaces/github.com-user-repo/work/cb9a54db
state: idle
branch: task/cb9a54db
use_git: true
worktree_path: null
started: 2025-01-15T10:30:00Z
```

**Fields:**

| Field           | Description                        |
|-----------------|------------------------------------|
| `id`            | 8-character task identifier        |
| `ref`           | Source reference (file:, dir:)     |
| `work_dir`      | Path to work directory (in home)   |
| `state`         | Current workflow state             |
| `branch`        | Git branch name                    |
| `use_git`       | Whether git operations are enabled |
| `worktree_path` | Path if using git worktree         |
| `started`       | Task start timestamp               |

## Work Directory

Each task has a work directory in `~/.valksor/mehrhof/workspaces/<project-id>/work/<task-id>/`.

### work.yaml

Task metadata and source information:

```yaml
version: "1"
metadata:
  id: cb9a54db
  title: Add Health Endpoint
  created_at: 2025-01-15T10:30:00Z
  updated_at: 2025-01-15T11:45:00Z
source:
  type: file
  ref: task.md
  read_at: 2025-01-15T10:30:00Z
  files:
    - source/task.md
git:
  branch: task/cb9a54db
  base_branch: main
  created_at: 2025-01-15T10:30:00Z
```

**Sections:**

#### metadata

| Field        | Description              |
|--------------|--------------------------|
| `id`         | Task identifier          |
| `title`      | Task title (from source) |
| `created_at` | Creation timestamp       |
| `updated_at` | Last modification        |

#### source

| Field     | Description                                       |
|-----------|---------------------------------------------------|
| `type`    | Source type (file, directory, github, jira, etc.) |
| `ref`     | Original reference                                |
| `read_at` | When source was read                              |
| `files`   | Paths to source files in `source/` directory      |

The `source/` directory contains the actual source files:

```
source/
├── task.md           # Main task content (file provider)
├── issue.md           # Issue content (GitHub/Jira/Linear)
├── comments.md        # Comments (GitHub)
├── notes.md           # Notes (GitLab)
└── linked/            # Linked issues (GitHub)
    └── issue-123.md
```

#### git

| Field         | Description          |
|---------------|----------------------|
| `branch`      | Task branch name     |
| `base_branch` | Branch created from  |
| `created_at`  | Branch creation time |

### notes.md

User notes accumulated through `mehr note`:

```markdown
# Notes

## 2025-01-15 10:45:00 [idle]

Use the existing HTTP router, don't create a new one.

## 2025-01-15 11:00:00 [idle]

The handler should return JSON, not plain text.
Make sure to set Content-Type header.

## 2025-01-15 11:30:00 [waiting]

**Q:** Should we use dependency injection?
**A:** Yes, use dependency injection for the version service.
```

Each entry includes:

- Timestamp
- State when note was added
- User's note (or Q&A format when answering agent questions)

### specifications/ Directory

Implementation specifications:

```
specifications/
├── specification-1.md
├── specification-2.md
└── specification-3.md
```

Filenames follow the `specification.filename_pattern` config (default: `specification-{n}.md`).

See [Specification File Format](specification-format.md) for details.

### reviews/ Directory

Code review results:

```
reviews/
├── review-1.txt
├── review-2.txt
└── security-review.txt
```

Filenames follow the `review.filename_pattern` config (default: `review-{n}.txt`).

Files are plain text with review findings.

## Project-Local Storage (Optional)

When `storage.save_in_project` is enabled, all work files (specs, reviews) are stored in your project directory instead of the home directory:

```
project/
├── .mehrhof/
│   ├── config.yaml
│   └── .env
└── tickets/                    # storage.project_dir
    └── A-123/                  # task ID
        ├── SPEC-1.md           # specification.filename_pattern
        ├── SPEC-2.md
        ├── CODERABBIT-1.txt    # review.filename_pattern
        └── CODERABBIT-2.txt
```

**Configuration example:**

```yaml
storage:
  save_in_project: true         # Store work in project (default: false = global)
  project_dir: "tickets"        # Directory for work (default: ".mehrhof/work")

specification:
  filename_pattern: "SPEC-{n}.md"

review:
  filename_pattern: "CODERABBIT-{n}.txt"
```

**Storage locations:**

| Config                                             | Work Location                                            |
|----------------------------------------------------|----------------------------------------------------------|
| `save_in_project: false`                           | `~/.valksor/mehrhof/workspaces/<name>/work/<taskid>/...` |
| `save_in_project: true`                            | `.mehrhof/work/<taskid>/...`                             |
| `save_in_project: true` + `project_dir: "tickets"` | `tickets/<taskid>/...`                                   |

### sessions/ Directory

Agent conversation logs:

```
sessions/
├── 2025-01-15T10-30-00-planning.yaml
├── 2025-01-15T11-00-00-implementing.yaml
└── 2025-01-15T11-30-00-reviewing.yaml
```

**Filename format:** `<timestamp>-<type>.yaml`

**Session file structure:**

```yaml
version: "1"
kind: Session
metadata:
  started_at: 2025-01-15T10:30:00Z
  ended_at: 2025-01-15T10:35:00Z
  type: planning
  agent: claude
  state: idle
usage:
  input_tokens: 1200
  output_tokens: 3500
  cached_tokens: 0
  cost_usd: 0.045
exchanges:
  - role: user
    timestamp: 2025-01-15T10:30:00Z
    content: "[prompt content]"
  - role: agent
    timestamp: 2025-01-15T10:30:15Z
    content: "[response content]"
    files_changed:
      - path: internal/api/health.go
        operation: create
```

**Exchange roles:**

- `user` - User prompt or system prompt
- `agent` - Agent response
- `system` - System message

**File operations:**

- `create` - New file created
- `update` - Existing file modified
- `delete` - File removed

## Planned Directory

Standalone planning sessions (from `mehr plan --standalone`):

```
planned/
└── xyz789ab/
    ├── plan.yaml
    └── PLAN_HISTORY.md
```

### plan.yaml

Planning session metadata:

```yaml
version: "1"
metadata:
  id: xyz789ab
  topic: "Design authentication system"
  created_at: 2025-01-15T10:30:00Z
  agent: claude
```

### PLAN_HISTORY.md

Conversation history in markdown:

```markdown
# Planning Session

Topic: Design authentication system

## User

How should I implement user authentication?

## Agent

For user authentication, I recommend...

## User

What about JWT tokens?

## Agent

JWT tokens are a good choice...
```

## File Ownership

| File/Directory       | Managed By | Editable    |
|----------------------|------------|-------------|
| config.yaml          | User       | Yes         |
| .active_task         | Mehrhof    | No          |
| work.yaml            | Mehrhof    | No          |
| source/              | Mehrhof    | Read-only   |
| notes.md             | User       | Yes         |
| specifications/\*.md | Mehrhof    | Read-only\* |
| reviews/\*.txt       | Mehrhof    | Read-only   |
| sessions/\*.yaml     | Mehrhof    | No          |

\*Specification files can be manually edited, but changes may be overwritten by `mehr plan`.

## Gitignore Recommendations

Add to `.gitignore`:

```gitignore
# Mehrhof secrets (task data is in home directory)
.mehrhof/.env
```

Keep tracked:

```
.mehrhof/config.yaml
```

## Backup and Recovery

### Backup Task Data

```bash
cp -r ~/.valksor/mehrhof/workspaces/<project-id>/work/abc12345 ~/backup/
```

### Recovery

1. Restore work directory
2. Update `.active_task` in home directory manually
3. Checkout task branch

## Cleanup

### Remove Old Sessions

Sessions older than `session_retention_days` can be cleaned:

```bash
find ~/.valksor/mehrhof/workspaces/*/work/*/sessions/ -mtime +30 -delete
```

### Remove Completed Tasks

After `mehr finish`, work directories are removed based on the `workflow.delete_work_on_finish` config setting (default: `false`/keep). For manual cleanup:

```bash
rm -rf ~/.valksor/mehrhof/workspaces/<project-id>/work/abc12345/
```

For automatic cleanup on finish, configure:

```yaml
workflow:
  delete_work_on_finish: true   # Auto-delete work dirs on finish
```
