# How AutoResearch Handles Long-Horizon Research Tasks with Project-Local State in DeepSeek-Reasonix

> Discover how AutoResearch tackles long-horizon research tasks using project-local state. Learn how it creates durable, isolated workflows without altering global project files. Explore DeepSeek-Reasonix today.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: how-to-guide
- Published: 2026-06-22

---

**AutoResearch upgrades standard `/goal` commands into durable research workflows by creating isolated project-local state directories under `.reasonix/autoresearch/` that capture the entire research lifecycle without mutating global project files.**

AutoResearch is the runtime strategy that DeepSeek-Reasonix activates when detecting long-horizon research, debugging, optimization, or implementation tasks. The system creates persistent, collision-resistant task directories that isolate mutable research state from your repository's main project files, ensuring that extended autonomous operations remain transparent and reversible.

## Detecting AutoResearch Signals and Upgrading Goals

The AutoResearch workflow initiates when the host detects specific trigger phrases or explicit path signals. According to [`internal/control/input.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/control/input.go) (lines 209–211), the system recognizes cues like "keep researching", "debug until the root cause is clear", or explicit paths matching `.reasonix/autoresearch/…`.

When detected, the controller **upgrades** the ordinary `/goal` command by inserting the `--research` flag (or equivalent `--auto-research`/`--deep` flags). This upgrade modifies the `Goal` struct defined in [`internal/control/goal.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/control/goal.go) (lines 37–58), which stores a `ResearchMode` boolean flag alongside the task ID and path.

```go
// Triggering AutoResearch from the host UI or CLI
fmt.Println("/goal --research investigate memory-leak in cache layer")

```

## Project-Local State Directory Structure

Upon activation, AutoResearch creates a dedicated workspace under:

```

.reasonix/autoresearch/YYYYMMDD-HHMMSS-slug/

```

The **task identifier** combines a timestamp with a slug derived from the goal text. If a collision occurs, the system appends "-2", "-3", and so forth until finding a unique name. Users can override this by providing the full `.reasonix/autoresearch/<task-id>/` path.

Inside this directory, the controller writes five state files that constitute the only mutable research state:

- **[`task_spec.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/task_spec.md)** – Original research objective and user constraints
- **[`progress.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/progress.json)** – Current step, sub-tasks, and completion percentage  
- **`findings.jsonl`** – Individual information gathered from code, web, or tools
- **[`directions_tried.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/directions_tried.json)** – Explored directions that were discarded
- **`iteration_log.jsonl`** – Chronological record of each reasoning and tool-call iteration

```bash

# Directory structure created by the controller

$ tree .reasonix/autoresearch/20231112-154830-investigate-memory-leak
.reasonix/autoresearch/20231112-154830-investigate-memory-leak/
├── task_spec.md
├── progress.json
├── findings.jsonl
├── directions_tried.json
└── iteration_log.jsonl

```

## State Isolation and Lifecycle Enforcement

The controller enforces strict **state isolation** by ensuring that [`REASONIX.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/REASONIX.md), [`AGENTS.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/AGENTS.md), and system prompts remain read-only during research operations. This prevents pollution of the global prompt cache and keeps long-running tasks sandboxed.

According to [`internal/control/controller.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/control/controller.go) (lines 494–567), the system monitors for stale iterations—situations where directions are tried repeatedly without progress—and can automatically **pivot** to new structural approaches. Completion validation occurs by auditing whether the evidence recorded in `findings.jsonl` satisfies the original objective stated in [`task_spec.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/task_spec.md).

## Security Boundaries and Tool Permissions

Despite running as an autonomous loop, AutoResearch maintains strict security gates. As implemented in [`internal/skill/builtins.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/skill/builtins.go), the research sub-agent operates with a **read-only** toolset by default:

```go
const builtinResearchBody = `You are running as a research subagent. Gather information from code AND the web, synthesize it, and return one focused conclusion.
The 'task' the parent gave you is the research question. Stay on it.`

```

Any tool performing public, destructive, or credentialed actions must pass through standard approval, privacy, and caching gates. Write-capable tools require explicit user authorization.

## Core Implementation Modules

The AutoResearch flow spans four critical modules:

1. **[`internal/control/input.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/control/input.go)** – Detects AutoResearch signals and builds the instruction block announcing the workspace creation
2. **[`internal/control/goal.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/control/goal.go)** – Stores the `ResearchMode` flag and task identification  
3. **[`internal/control/controller.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/control/controller.go)** – Orchestrates the planning/execution loop, writes state files, and handles pivot logic
4. **[`internal/skill/builtins.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/skill/builtins.go)** – Declares the `research` sub-agent tool and enforces read-only policies

Documentation references in `site/src/pages/docs.astro` (line 191) and [`docs/GUIDE.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/GUIDE.md) (line 335) provide user-facing semantics and directory layout specifications.

## Summary

- **AutoResearch** activates when the host detects long-horizon task signals or explicit `--research` flags, upgrading standard goals into durable research workflows.
- **Project-local state** resides in timestamped directories under `.reasonix/autoresearch/`, containing five JSON/Markdown files that track the complete research lifecycle.
- **Isolation guarantees** ensure that only the task directory mutates, leaving global project files untouched and preventing cache pollution.
- **Security controls** restrict the research sub-agent to read-only operations unless explicitly authorized, with all destructive actions requiring approval gates.
- **Lifecycle management** includes automatic pivot detection for stale iterations and completion auditing against recorded findings.

## Frequently Asked Questions

### What triggers AutoResearch mode in DeepSeek-Reasonix?

AutoResearch triggers when the system detects specific user phrases like "keep researching" or "debug until the root cause is clear", or when the user provides an explicit path to `.reasonix/autoresearch/`. The detection logic in [`internal/control/input.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/control/input.go) (lines 209–211) upgrades these signals into research goals by appending the `--research` flag.

### Where does AutoResearch store its state?

AutoResearch stores all mutable state in a dedicated directory under `.reasonix/autoresearch/YYYYMMDD-HHMMSS-slug/`. This location contains five state files—[`task_spec.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/task_spec.md), [`progress.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/progress.json), `findings.jsonl`, [`directions_tried.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/directions_tried.json), and `iteration_log.jsonl`—that capture the complete research lifecycle while isolating changes from your main repository files.

### How does AutoResearch handle multiple attempts at the same task?

When creating a task directory, AutoResearch generates a collision-resistant ID from the timestamp and goal slug. If a directory with that ID already exists, the system automatically appends "-2", "-3", and so on until finding a unique name. Alternatively, users can force a specific ID by providing the full `.reasonix/autoresearch/<task-id>/` path upfront.

### Is AutoResearch safe to run autonomously?

Yes, AutoResearch implements security gating that restricts the research sub-agent to read-only toolsets by default, as defined in [`internal/skill/builtins.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/skill/builtins.go). Any public, destructive, or credentialed actions still require passing through standard approval gates. The system only enables write-capable tools when explicitly authorized by the user.