Journal

egon-journal adds structured journaling to your Egon graph. Write daily entries linked to the content you already have, follow guided programs, and run local reports across mood, physiology, and personality — without any data leaving your device.

Getting started

You need Python 3.13+ and uv. Clone the repository and install:

git clone https://github.com/egon-notebooks/egon-journal
cd egon-journal
uv sync

Configure your graph directories by copying the example env file:

cp .env.example .env

Open .env and set the three paths:

EGON_JOURNAL_DIR=/path/to/your/graph/journal
EGON_SUMMARIES_DIR=/path/to/your/graph/summaries
EGON_GRAPH_DIR=/path/to/your/graph

Create your first journal entry:

uv run egon new-entry        # today
uv run egon new-entry --open  # open immediately in $EDITOR

Entries are named Journal — YYYY-MM-DD.md and written as plain Markdown with YAML frontmatter. They land in EGON_JOURNAL_DIR and sit alongside your content nodes in Obsidian or Logseq.

Prompts and programs

Journaling prompts are short, topic-linked questions that sit as nodes in your graph alongside the content they refer to. Structured programs are time-bounded sequences — each day is a node that frames a reading and a reflection.

# Generate all prompt nodes
uv run egon generate-prompts

# List available programs
uv run egon list-programs

# Generate a specific program
uv run egon generate-program --name "14-Day Sleep Improvement"

# Generate all programs
uv run egon generate-all-programs

Weekly and monthly summaries

Summary nodes give each week or month a structured reflection: overall tone, recurring themes, one thing noticed, and what to carry forward. Fill them in by hand or use a local AI tool to draft them from your entries.

uv run egon new-summary --period week
uv run egon new-summary --period month

Reports

Reports are generated locally as PDFs (or .png / .svg) and saved to ./reports/. They read only from your local files — no API calls, no data transmitted.

Run everything at once with the full report command:

uv run egon report                  # current month
uv run egon report --period week
uv run egon report --for 2026-Q1

Which analyses appear is controlled by egon.toml in the project root. All analyses are enabled by default except wordcloud (opt-in) and topics (requires the topics extra).

Journal insights

Word count

Daily word count across all entries as a bar chart — a proxy for how much you've been engaging with your graph.

uv run egon report-word-count

Word cloud

A visual summary of the most frequent words across a period. Opt-in: set wordcloud = true in egon.toml.

uv run egon report-wordcloud

requires --extra topics

Topics

Latent theme discovery using BERTopic — a bar chart of recurring topics and a stacked timeline showing how they shift across months.

uv run egon report-topics

requires --extra limbic

Cognitive distortions

Detects cognitive distortions in journal text across seven categories (personalization, emotional reasoning, overgeneralizing, labeling, should statements, catastrophizing, reward fallacy) using a BERT-tiny classifier. Two-panel figure: daily distortion signal line and a stacked area by distortion type.

uv run egon report-cognitive-bias

Personality & affective patterns

Sentiment

Daily sentiment score (VADER, −1 to +1) as a line chart with a neutral band. A fast, local measure of overall emotional tone.

uv run egon report-sentiment

requires --extra limbic

Emotion

Daily emotion profile across seven categories (anger, disgust, fear, joy, neutral, sadness, surprise) using a DistilRoBERTa model. Includes a joy-vs-sadness overlay.

uv run egon report-emotion

requires --extra limbic

Big Five traits

Scores each entry on the five personality dimensions (Openness, Conscientiousness, Extraversion, Agreeableness, Neuroticism) using a DistilBERT regression model. Five subplots, one per trait, with the period average annotated.

uv run egon report-bigfive

requires --extra limbic

MBTI dimensions

Classifies each entry into four binary MBTI dimensions (E/I, N/S, T/F, J/P) and shows the dominant pole and proportion across the period.

uv run egon report-mbti

Physiological measures

Sleep

Nightly time asleep (hours) from an Apple Health export, with 7 h and 9 h reference lines. Sleep quality is strongly correlated with mood and mental health symptoms.

uv run egon report-sleep --xml ~/export.xml

Resting heart rate

Daily resting heart rate (bpm) from Apple Health. A useful proxy for stress and recovery. Set a target via EGON_TARGET_RESTING_HEART_RATE in .env.

uv run egon report-resting-heart-rate --xml ~/export.xml

HRV

Daily heart rate variability (ms, SDNN) from Apple Health. HRV is associated with autonomic nervous system function and stress levels.

uv run egon report-hrv --xml ~/export.xml

Weight

Daily body weight (kg) from Apple Health. Sudden weight changes can be an early indicator of shifts in mental health.

uv run egon report-weight --xml ~/export.xml

Step count

Daily steps from Apple Health as a bar chart with a 10,000-step reference line.

uv run egon report-step-count --xml ~/export.xml

Exercise time

Daily Apple Exercise Time (minutes) with a WHO-recommended 30 min/day reference line. Customise via EGON_TARGET_EXERCISE_MINUTES in .env.

uv run egon report-exercise --xml ~/export.xml

VO2 max

Daily mean VO2 max (mL/min/kg) from Apple Health with the period average annotated.

uv run egon report-vo2max --xml ~/export.xml

Cross-signal analysis

Correlations

Pairwise Pearson correlations across all available journal and health signals — a full heatmap and a top-pairs chart. Requires at least two signals.

uv run egon report-correlations --xml ~/export.xml

All report commands accept --period (week, month, quarter, year, all-time) and --for (e.g. 2026-02, 2026-W14, 2026-Q1). Health reports also accept --xml to specify an Apple Health export path.

Next steps

Browse the Registry to download content packs to read alongside your entries
Follow the Getting Started guide to set up your Obsidian or Logseq vault
View the full source on GitHub