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

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 (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 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. This function accepts a status argument that defaults to "draft" if not specified.

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 provides dedicated subcommands for filtering and mutating note statuses without writing code.

Creating a note with a specific status:

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

Filtering notes by status:

# 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:

# 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. You can query notes by status or update individual records using standard HTTP requests.

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

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):

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: draft, review, evergreen, stale, deprecated, and archive.
• Use write_note() in 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.
• Automate status workflows using the MCP server endpoints list_notes and update_note in 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: 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 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 module handles parsing and rendering this field, ensuring the value in your file matches the NoteMeta model used by the application internally.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}