For full text search please use the '?' prefix. e.g. ? Onboarding

Visit History

Summary

Visit history records your note visitation history per user, tracking where you have been and when. In V1, this enables navigation to recently visited notes. Future iterations of Thorg will use this for more elaborate features.

By default, history is stored under your user directory (only you have access to your visitation history).

Does not track your brain

Visit history gives you a good idea of the notes you've opened recently to help filter your search. However, Thorg doesn't track your eyes or your brain -- just keep in mind that we can't guarantee a note visit included an actual read.

What is a visit event

From Visit Event
Go to text →

What are visit events

Events that power Visit History to answer the question: When did you visit a Note and for how long?

Two types of Visit Events:

From FOCUS - Visit Event
Go to text →

What is a FOCUS event?

FOCUS: A visit event that represents you focusing on the editor view of a particular note.

When is FOCUS eligible to be persisted?

From FOCUS eligible for persistence WHEN
Go to text →

For pre-existing notes

You need to spend more than the Min Visitation Time Threshold with the note in focus for the FOCUS - Visit Event to be eligible for persistence.

For brand new notes

FOCUS will be eligible for persistence right away for a newly created note.

What is NOT a visit event

Rapidly jumping in and out of pre-existing note: Not a visit event

If you jump into a note for less than the minimum amount of time (default is a few seconds) and jump out before the minimum time passes, we will NOT record that as a visit event. From the visitation history, it will appear as if you haven't opened that note at all (unless you just created the note).

Seeing the preview of an embedded note: Not a visit event

If note-A has note-B embedded in it and you preview note-A, you will see note-B's contents. However, this is NOT considered a visit to note-B (only a visit to note-A).

You need to navigate to note-B explicitly for it to be considered a visit to note-B.

FOCUS is written to file with UNFOCUS

FOCUS is persisted to file with UNFOCUS

A FOCUS visit event is persisted into the Visit history File when its corresponding UNFOCUS - Visit Event is processed and persisted.

Therefore, if you want your FOCUS event to be persisted (after it has met FOCUS eligibility for persistence), you need to trigger an UNFOCUS event, which is triggered by:

From UNFOCUS triggered-by
Go to text →

UNFOCUS - Visit Event is triggered when you unfocus the editor view of the note that you had in focus. There are two main categories that trigger unfocus:

  • User action:

    • Navigating to a different note
    • Navigating to settings
    • Focusing on non-editor view of the note (e.g., Dendron preview)
    • Focusing on a different application (e.g., IntelliJ)
    • Closing VSCode

  • Prolonged user inaction:

From UNFOCUS - Visit Event
Go to text →

What is an UNFOCUS event?

UNFOCUS: A visit-event that symbolizes loss of focus from a Note.

It can only occur after a FOCUS - Visit Event for the note in question.

Triggered by:

From UNFOCUS triggered-by
Go to text →

UNFOCUS - Visit Event is triggered when you unfocus the editor view of the note that you had in focus. There are two main categories that trigger unfocus:

  • User action:

    • Navigating to a different note
    • Navigating to settings
    • Focusing on non-editor view of the note (e.g., Dendron preview)
    • Focusing on a different application (e.g., IntelliJ)
    • Closing VSCode

  • Prolonged user inaction:

Where are visit events stored?

Visit events are stored in visit history files

Available configuration of Visit History:

From thorg.visitHistory - VSCode Config Section
Go to text →

Visit history file storage

From Visit history File
Go to text →

Storage file for visit events

From Visit history file Content Format
Go to text →

Visit history File: contains the data to power Visit history Feature (in short this file contains the timestamps of when you visited particular note).

Visit history file path contains the note id in the file name. Therefore, we do NOT need to duplicate the note id in the events that we store.

The contents of the visit history file are in compact text format with the following structure per line:

Line Structure (VisitPair format)

<FOCUS_TIMESTAMP_MILLIS>:<DURATION_MILLIS>
  • FOCUS_TIMESTAMP_MILLIS: When the FOCUS - Visit Event event occurred (milliseconds since epoch).
  • DURATION_MILLIS: How long the visit lasted (milliseconds).

Each line represents a complete visit (a FOCUS followed by UNFOCUS).

Example content

1753911954503:4597
1753912000000:60000

This translates to:

  • 1753911954503:4597: Visit started at timestamp [1753911954503], lasted [4597] ms (~4.6 seconds)
  • 1753912000000:60000: Visit started at timestamp [1753912000000], lasted [60000] ms (1 minute)

Stored transparently

Per Transparent Data Model, we use a human-readable format to store data in a transparent (non-proprietary) way. We opted away from JSONL to keep files compact while retaining human readability and ease of parsing, so you can see what is being recorded and parse it if you desire.

Future-proof parsing guidance

Future-proof parsing guidance

If you're parsing this data, you can future-proof your implementation by expecting additional fields to be added after the current ones, separated by the : delimiter.

In future versions, we may extend the data recorded per visit:

1753911954503:4597:<some-new-data>:<additional-field>

Simple future-proofing strategy:

  1. Take one line
  2. Split on : delimiter to get tokens
  3. Read tokens[0] (focus timestamp) and tokens[1] (duration)
  4. Ignore any additional tokens beyond index 1

This ensures your parser continues working even as new fields are added.

From Visit History file Location - (Where visit history data is written to)
Go to text →

Location

$HOME/
  .thorg/
    usr/
      {user_name}/
        qc/
         h/
            vh2/
              vaultid_{vault_id}/
                {machine_name}/
                  {note-id}.note_visit_log
  • $HOME/ - Your user directory.
  • .thorg/ - Thorg directory under your home folder ($HOME/.thorg (Directory)).
  • usr/ - Stands for split by thorg username.
  • {user_name}/ - Thorg Username (Concept)
  • qc/ - Stands for quick changing.
  • h/ - Folder stands for history.
  • vh2/ - Folder stands for visit history v2.
  • vaultid_{vault_id}/ - vault Id
  • {machine_name}/ - Machine Name
    • Machine name exists to prevent merge conflicts when you share your visit history for the same user across multiple machines.
  • {note-id}.note_visit_log - Visit log for the Note, indexed by note_id.

Recommendation

From As descendent of $HOME/.thorg: Recommended to be backed up.
Go to text →

Per Back up $HOME/.thorg, this directory is a descendant of $HOME/.thorg and is recommended to be under source control.

If you're already backing up (e.g., source controlling) $HOME/.thorg, then this directory is already backed up as well as a descendant of $HOME/.thorg. If not, it's highly recommended to backup/source control $HOME/.thorg per Back up $HOME/.thorg.

Caveats

  • A visit does not necessarily mean the note was read by the user. The note could have been opened without being read.
Children
  1. Visit Event
  2. Visit history File
Backlinks