How to View Individual Notes or Batch Reads in Hyperresearch: A Complete Guide

Use the hyperresearch note show command to display individual notes or multiple notes at once, with options for formatted terminal output, raw Markdown, or JSON.

Hyperresearch stores every research artifact as a Markdown file with YAML front‑matter and indexes the data in a SQLite database for fast, reliable retrieval. The CLI command hyperresearch note show pulls requested notes from the vault, applies security filters for untrusted sources, and renders results through multiple output modes. This functionality is implemented in src/hyperresearch/cli/note.py and integrates directly with the core vault and database layers.

How the Note Show Command Works

When you execute hyperresearch note show, the system performs three core operations before displaying results.

First, it discovers the vault using Vault.discover() and synchronizes any pending file changes via vault.auto_sync() to ensure the SQLite database reflects the current filesystem state.

Next, it executes a SQL join between the notes and note_content tables to retrieve both metadata and the note body:

SELECT n.*, nc.body FROM notes n
JOIN note_content nc ON n.id = nc.note_id WHERE n.id = ?

This query appears at lines 74‑76 of src/hyperresearch/cli/note.py.

Finally, if the note's source is flagged as untrusted, the body is wrapped in <untrusted-source> tags using the wrap_body utility to prevent malicious instructions from influencing agents.

Viewing Individual Notes

Rich Terminal Output (Default)

The default mode renders the note's title, status, tags, and body using Rich's Markdown renderer for easy reading in the terminal.

hyperresearch note show 2024-08-17-quantum-research

Raw Markdown View

Use the --raw flag to display the note exactly as stored on disk, without any processing or formatting.

hyperresearch note show 2024-08-17-quantum-research --raw

JSON Output

For integration with other tools, the --json flag returns a structured payload containing front‑matter fields, optional OA metadata, and the (optionally wrapped) body.

hyperresearch note show 2024-08-17-quantum-research --json

Performing Batch Reads

The CLI accepts multiple note IDs to read several notes in a single command. In plain mode, notes print sequentially. In JSON mode, the command emits a single object containing "notes" and "not_found" arrays (see lines 66‑78).

View multiple notes with formatted output:

hyperresearch note show 2024-08-17-quantum-research 2024-08-18-ml-survey 2024-08-19-data-ethics

Batch read with JSON output:

hyperresearch note show 2024-08-17-quantum-research 2024-08-18-ml-survey 2024-08-19-data-ethics --json

If any IDs are missing, the JSON response includes a not_found array (lines 75‑78).

Core Implementation Files

The note viewing functionality relies on several key components defined in the jordan-gibbs/hyperresearch repository:

• src/hyperresearch/cli/note.py – Contains the note_show command implementation, handling single versus batch processing, raw/meta options, and JSON formatting (lines 59‑84).

• src/hyperresearch/core/vault.py – Provides Vault.discover() and vault.auto_sync() to locate the research directory and synchronize the database with the filesystem.

• src/hyperresearch/core/db.py – Defines the SQLite schema including the notes, note_content, and tags tables queried by the CLI.

• src/hyperresearch/core/untrusted.py – Implements is_untrusted checking and wrap_body sanitization to protect against malicious fetched content.

• src/hyperresearch/models/note.py – Defines Pydantic models (NoteMeta, Note) that structure the front‑matter and define status, type, and tier enumerations.

Summary

• Use hyperresearch note show <id> to view individual notes with rich formatting, raw Markdown, or JSON output.
• Append --raw to see the unprocessed Markdown file or --json for machine‑readable structured data.
• Pass multiple IDs to perform batch reads; JSON mode aggregates results and lists missing IDs in not_found.
• The command automatically syncs the vault before querying and sanitizes untrusted content by wrapping it in protective tags.
• Implementation resides in src/hyperresearch/cli/note.py with dependencies on the vault, database, and security modules.

Frequently Asked Questions

How do I view multiple notes at once in Hyperresearch?

Pass multiple note IDs as arguments to the hyperresearch note show command. The CLI processes each ID sequentially in plain mode or returns a single JSON object containing all found notes and any missing IDs when using the --json flag.

What is the difference between raw and formatted output?

The formatted view (default) uses Rich's Markdown renderer to display titles, status, tags, and bodies with terminal styling. The --raw flag outputs the exact Markdown file content without processing, preserving YAML front‑matter and original formatting.

How does Hyperresearch handle security for fetched web content?

If a note's source is flagged as untrusted, the system wraps the body content in <untrusted-source> tags using the wrap_body utility from src/hyperresearch/core/untrusted.py. This prevents any embedded instructions in fetched web pages from affecting agent behavior.

Where is the note data stored and how is it accessed?

Notes exist as Markdown files with YAML front‑matter in your vault directory, while an SQLite database indexes metadata and content. The note show command queries the notes and note_content tables defined in src/hyperresearch/core/db.py after syncing via Vault.discover() and vault.auto_sync().

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