# How to Manage Note Status (Evergreen, Stale, Deprecated) in Hyperresearch

> Master note status management in Hyperresearch. Learn to use evergreen, stale, and deprecated states programmatically or via API for efficient research documentation.

- Repository: [Jordan Gibbs/hyperresearch](https://github.com/jordan-gibbs/hyperresearch)
- Tags: how-to-guide
- Published: 2026-09-13

---

**Hyperresearch tracks the lifecycle of every note through a `status` field in YAML front-matter, supporting six defined states ranging from `draft` to `deprecated`, which you can set programmatically, via CLI, or through the MCP server API.**

Hyperresearch uses a structured status system to prevent knowledge rot in long-term research vaults. Every markdown file carries metadata that classifies its content as evergreen, stale, or obsolete, allowing you to filter, review, or archive notes systematically. Whether you are creating new research entries or maintaining existing ones, understanding how to manage note status in Hyperresearch ensures your knowledge base remains accurate and trustworthy.

## Understanding Hyperresearch Note Status Architecture

The status taxonomy is defined by the `NoteStatus` enum in **[`src/hyperresearch/models/note.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/models/note.py)** (lines 13‑19). This strict schema validates all status values, preventing inconsistent metadata across your vault.

The six possible statuses are:

- **`draft`** – Freshly created content that has not been reviewed.
- **`review`** – Content currently under human review or verification.
- **`evergreen`** – Accurate, current information expected to remain useful long-term.
- **`stale`** – Potentially outdated content that needs verification or refresh.
- **`deprecated`** – Obsolete content that has been superseded or invalidated.
- **`archive`** – Retired from active use but preserved for historical reference.

When Hyperresearch parses a note, it loads this value into the `NoteMeta` model. The `render_note` function in **[`src/hyperresearch/core/frontmatter.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/core/frontmatter.py)** then serializes the status back into YAML front-matter, ensuring round-trip consistency between the file system and the application's internal state.

## Setting Note Status at Creation

To assign a status_when creating a note, use the `write_note` helper function located in **[`src/hyperresearch/core/note.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/core/note.py)**. This function accepts a `status` argument that defaults to `"draft"` if not specified.

```python
from pathlib import Path
from hyperresearch.core.note import write_note

vault_path = Path("/path/to/vault")
notes_dir = vault_path / "notes"

# Create an evergreen note at inception

write_note(
    notes_dir=notes_dir,
    title="Quantum Computing Fundamentals",
    body="Superposition and entanglement basics...",
    status="evergreen",  # Explicitly set status

    tags=["physics", "quantum"]
)

```

If you omit the `status` parameter, Hyperresearch automatically assigns `"draft"`, signaling that the note requires initial review before promotion to `evergreen` or another state.

## Managing Status via the CLI

The command-line interface in **[`src/hyperresearch/cli/note.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/cli/note.py)** provides dedicated subcommands for filtering and mutating note statuses without writing code.

**Creating a note with a specific status:**

```bash
hyperresearch note create "API Design Patterns" \
  --status evergreen \
  --tags "engineering,architecture"

```

**Filtering notes by status:**

```bash

# List only stale notes requiring review

hyperresearch note list --status stale

# List evergreen notes for confidence checks

hyperresearch note list -s evergreen

```

**Updating existing note status:**

```bash

# Mark a note as deprecated when superseded

hyperresearch note update api-design-patterns --status deprecated

# Flag content as stale for later refresh

hyperresearch note update quantum-fundamentals --status stale

```

These CLI commands forward requests to the MCP server, ensuring that file-system changes trigger any registered hooks or index updates.

## Updating Status via the MCP Server API

For programmatic workflows, the MCP server exposes HTTP endpoints defined in **[`src/hyperresearch/mcp/server.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/mcp/server.py)**. You can query notes by status or update individual records using standard HTTP requests.

**Listing notes filtered by status** (lines 120‑124):

```python
import requests

response = requests.get(
    "http://localhost:8000/api/list_notes",
    params={"status": "evergreen"}
)
evergreen_notes = response.json()

```

**Updating a note's status** (lines 358‑363):

```python
import requests

payload = {
    "note_id": "quantum-fundamentals",
    "status": "stale",  # Transition to stale

    "summary": "Needs update for 2024 breakthroughs",
    "add_tags": "",
    "remove_tags": ""
}

response = requests.post(
    "http://localhost:8000/api/update_note",
    json=payload
)
print(response.json()["status"])  # Confirms: stale

```

Because the API relies on the `NoteStatus` enum, passing an invalid status value returns a validation error before any file writes occur, protecting your vault from corrupted metadata.

## Summary

- Hyperresearch defines six lifecycle states in **[`src/hyperresearch/models/note.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/models/note.py)**: `draft`, `review`, `evergreen`, `stale`, `deprecated`, and `archive`.
- Use `write_note()` in **[`src/hyperresearch/core/note.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/core/note.py)** to set status during creation; it defaults to `"draft"`.
- Filter and update statuses interactively via CLI commands defined in **[`src/hyperresearch/cli/note.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/cli/note.py)**.
- Automate status workflows using the MCP server endpoints `list_notes` and `update_note` in **[`src/hyperresearch/mcp/server.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/mcp/server.py)**.
- All status values are validated against the `NoteStatus` enum, preventing metadata drift across your research vault.

## Frequently Asked Questions

### What are the valid note statuses in Hyperresearch?

The valid statuses are defined by the `NoteStatus` enum in **[`src/hyperresearch/models/note.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/models/note.py)**: `draft`, `review`, `evergreen`, `stale`, `deprecated`, and `archive`. Each state represents a specific phase in the content lifecycle, from initial creation through archival.

### How do I set a default status for all new notes?

The `write_note` function in **[`src/hyperresearch/core/note.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/core/note.py)** automatically defaults to `"draft"` when the `status` parameter is omitted. To enforce a different default, wrap `write_note` in a custom utility function that passes your preferred status explicitly, or use the CLI with the `--status` flag for every creation command.

### Can I batch update multiple notes to deprecated status?

While the CLI and MCP API process one note per call, you can script batch operations by first calling `list_notes` with a filter (e.g., a specific tag), then iterating over the returned IDs to call `update_note` with `status="deprecated"` for each. This pattern ensures atomic updates while respecting the validation rules defined in the `NoteStatus` enum.

### Where is the note status stored in the file system?

The status is stored as a `status` key within the YAML front-matter of each markdown note. The **[`src/hyperresearch/core/frontmatter.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/core/frontmatter.py)** module handles parsing and rendering this field, ensuring the value in your file matches the `NoteMeta` model used by the application internally.