EPOCHGRAM DOCS

The Epochgram Handbook

Pain. Your vault fills up with quick capture notes. A week later, you've lost the thread. A month later, you can't reconstruct the story — and you don't see the themes, the slow stretches, or the bursts of activity.

Solution. Epochgram turns your notes into an AI-powered interactive timeline. Browse day by day to scan changes in order, spot bigger patterns across unsorted notes, and edit directly on the timeline — so you can focus on what really matters.

Epochgram Pro adds even more overview:

• On-device AI summaries via Google Chrome.
• Epochs: a zoomable timemap, from daily detail to a year overview.
• Find related notes through links, tags, titles, and semantic similarity.
• Topic clustering and marked related groups.
• Tracked content edits.
• Recurring events.

Table of Contents

• Get Started
• Timeline
• Examples
• Filters
• Search
• Actions
• Review State
• Recurring (Pro)
• Similarity (Pro)
• AI Bridge (Pro)
• Epochs (Pro)
• Custom YAML
• Settings & Data
• FAQ
• Disclosures

Get Started

Download

Install from Obsidian Community plugins

BRAT

• Install BRAT community plugin in Obsidian.
• Use Obsidian protocol to add Epochgram.
• Or Obsidian Settings → BRAT → Add beta plugin https://github.com/2brn/Epochgram.

Manual install

• Download the latest release files from GitHub releases.
• Copy files into your vault plugin folder: .obsidian/plugins/epochgram.
• Enable Epochgram in Obsidian Settings → Community plugins.

Cheatsheet

Activating Pro

• Follow the instructions on epochgram.com/pro to get your activation key by email.
• Open the link in the email or paste the key into ⛭ License key to activate.
• Epochgram may periodically connect to the cloud service to verify your license.

Timeline

The timeline is a scrollable, zoomable surface that collects records from all files in the vault, excluding paths ignored in Obsidian settings. It detects dates and date ranges in different formats and renders one record per file per day, in the following priority order:

Source	Description
Tracked changes	Per-block edit history excluding YAML. Requires ⛭ Track changes (Pro).
Content date	Parsed content date (ranges), including Recurring dates (Pro).
-- Anchors --
Filename date	Parsed filename date.
Frontmatter date	YAML ⛭ Anchor property.
File cdate or mdate	Configurable via ⛭ Anchor by mdate.

Each file has one anchor record that represents its canonical date. All other record types are optional. Drag and drop works only for anchor records, it updates the YAML ⛭ Anchor property, and the filename for daily notes.

Each record appears as file ⸱ summary. You can control the length of each part using ⛭ Filename length and ⛭ Summary length. The summary is either the first N words extracted from Markdown or an AI-generated summary when ⛭ Auto summarize is enabled (Pro). You can also set a manual summary using YAML ⛭ Summary property or via context menu Edit summary…; manual summaries are always preferred over AI-generated ones.

Use this CSS snippet to make the timeline full width on mobile:

 body.is-mobile {
   --mobile-sidebar-width: 100vw;
 }

Timeline draws today as , weekdays as and weekends as . Entries are shown stacked or side by side when space allows, long entries are truncated with …. When records no longer fit within the ⛭ Record width limit, the rest collapse into (+n). When zoomed out, records collapse into placeholder bars , with height based on record count.

Examples

Let's assume you have the following notes in your vault:

backup.md

---
repeat: every week on wednesday
---

Local RAG workshop.md

---
date: 2026-05-18
---
 
Workshop focused on building local RAG pipelines with Ollama, vector embeddings, and semantic search across Markdown knowledge bases.
 
Event was originally planned for May 16, 2026, but was later postponed due to severe weather conditions.

daily-17-05-2026.md

---
published: 2026-05-15T15:04:17
description: PKM
---
 
[Personal knowledge management](https://en.wikipedia.org/wiki/Personal_knowledge_management)

And these Epochgram settings:

After indexing, you will see the following records on the timeline:

⛭ Track changes lets you review file history on the timeline. For example, you have a long document you edit every day:

campaign-notes.md

Added the first draft of the Black Hollow region, including the mining town, nearby ruins, and the main faction leaders.
 
Updated Seraphine’s backstory and connected her father’s disappearance to House Vaelor. Also added notes for the underground smuggler tunnels.
 
Reworked the final dungeon encounter after the last session. Added shadow creatures, new traps, and alternative paths for stealth-focused players.

Then you will see your edit history on the timeline, day by day:

Each day you edit the document, the latest changed block is shown as added, changed, or removed.

Filters

You can show or hide specific types of records using collapsible filters under the button:

Filter	Description
	Show drafts only.
	Show tracked changes (Pro).
	Show content dates, ranges, and recurring.
	Show non-text files.
	Toggle Epochs view (Pro).

Search

A search bar at the bottom lets you search timeline records and shows the number of matches. Click it or run ⌘ Epochgram: Search timeline. Search supports fuzzy matching across filenames, content, summaries, Epochs, and all indexed attributes.

Actions

Files in the vault are never modified unless you run an explicit file action. All attributes except the date and manual summary are stored in Epochgram data files, not in vault files.

Record menu	Description
Edit summary…	Update the file manual summary.
Set topic…	Open the topics assignment popup; to remove topics, clear the input (Pro).
Pin	Pin the file at the Today position; or ⌘ Epochgram: Toggle pin for current file.
Mark	Mark similar records with a color; or ⌘ Epochgram: Toggle mark for current file.
Draft Review Hide	Change the file review state.
Rename…	Rename the file in the vault.
Move to…	Move the file to another folder.
Delete	Permanently delete the file, or move it to trash, depending on Obsidian settings.

Date menu	Description
Create daily note	Uses ⛭ Daily notes core plugin settings for that date: date format, location, and template. You can also create daily records by Double-click a date.

Review State

Epochgram is designed around the C.O.D.E. process (Capture → Organize → Distill → Express). New or indexed files appear as Draft. After organizing the file and extracting the key points, the record can be set as Reviewed. If the file changes later, the record returns to Draft, indicating it may need review again.

Not every record deserves space on the timeline. Some, such as minor tracked changes, can be set Hidden. Hidden records disappear from the timeline by default. Use !hidden in search to show only hidden records — they are rendered muted.

Recurring (Pro)

You can create recurring records, which will appear on the timeline. To add one, set the repeat or recur property in YAML. Supported formats (see RRULE):

---
repeat: every day
repeat: every N days
repeat: every week on monday,tuesday
repeat: every N weeks on mon,tue
repeat: every month on D
repeat: every month on -D # D days from end of month; -1 = last day
repeat: every year on MM-DD
repeat: FREQ=DAILY;COUNT=5 # RRULE
---

Similarity (Pro)

Similarity helps find related records. When you open a note, similar records on the timeline are marked using the current theme color. Epochgram includes multiple similarity settings that work across all platforms, including iOS and Android:

Building semantic vectors and running topic classification can take a long time on slower machines. Long-running jobs show their progress in the status bar — hover over the progress item to see all jobs, or click it to cancel.

Similarity also groups related records automatically: when you mark one record, related records inherit the same color. These records behave as one group, so changing or removing the color updates the whole group, and inherited marks are recalculated automatically if the relation later disappears.

In addition to the standard red-to-violet palette, an extended palette is available in the submenu. This makes it easy to choose colors by activity. For example, I use glacier for ski trip reports.

AI Bridge (Pro, desktop-only)

Epochgram Pro includes an AI Bridge that uses Google Chrome's on-device AI APIs for local summarization. When started, it runs a small local server on an available port at http://127.0.0.1. The bridge page can be opened from ⌘ Epochgram: Open AI bridge, from the ⌀ AI status bar button (button absent → server not started; button red → client disconnected), or automatically on startup if ⛭ Open AI bridge on startup is enabled. This page processes summary jobs in Chrome and returns the results to the plugin. All summarization data stays only on your device and is not sent to external services.

On first use, Chrome may need a user gesture to download the built-in Gemini Nano model, and the drive with your Chrome profile should have at least 22 GB of free space. The bridge page also serves as a control panel, showing connection and model status, queue progress, the current text preview, the latest result, and a chart with progress in gray and processing speed in blue. Keep it open while summaries are running. For larger notes, Epochgram can split input into chunks, summarize them separately, then merge the results. You can also adjust API settings and prompt/context texts in the YAML settings editor:

sharedContext: | # Shared instructions across all summarization jobs
  Ignore dates and empty content.
  Group by topics, compress, remove duplicates and metaphrases.
  Order by frequency.
 
format: plain-text # Output format: markdown | plain-text
preference: capability # Model preference: auto | speed | capability
expectedInputLanguages: [en] # Accepted input languages: en | es | ja
outputLanguage: en # Output language: en | ja | es
expectedContextLanguages: [en] # Accepted context languages: en | ja | es
maxRelatedChars: 300 # Related-context size limit
 
reduce:
  context: | # Recursive reduction instructions
    Recursive summary reduction.
    Preserve dominant topics and recurring entities.
 
  type: tldr # Reduction summary type: key-points | tldr | teaser | headline
  length: long # Summary length: short | medium | long
  maxChunkChars: 3000 # Split threshold before recursive reduction
  maxDepth: 3 # Maximum recursive reduction depth
 
records:
  context: | # Per-record summarization instructions
    File:
    {{filePath}}
    
    Preserve facts, entities, terminology, and concrete topics.
    Remove repetition, filler, boilerplate, and metaphrases.
 
  type: tldr # Summary type: key-points | tldr | teaser | headline
  length: short # Summary length: short | medium | long
 
  maxInputChars: 3000 # Max source chars per record
  maxOutputWords: 30 # Max generated words (optional)
 
epochs:
  - period: day-2weeks # Supported  periods/ranges: day | 2days | 4days | week | 2weeks | month | 3months | 6months | year | day-year
    context: | # Epoch summarization instructions
      Short-term activity summary.
      Recent events, actions, tasks, places, people, projects.
      Output max 12 words, nouns only.
 
    type: tldr # Summary type: key-points | tldr | teaser | headline
    length: short # Summary length: short | medium | long
    maxFileChars: 300 # Max chars taken per file
    maxOutputWords: 30 # Max generated words (optional)
 
  - period: month-year
    context: |
      Broad period summary.
      Long-term themes, domains, projects, interests, recurring topics.
      Output max 12 words, nouns only.
 
    type: tldr
    length: medium 
    maxFileChars: 300 
    maxOutputWords: 30

AI Summaries & Epochs (Pro, desktop-only)

⛭ Auto summarize → when enabled, Epochgram automatically summarizes timeline records through the AI Bridge whenever the file changes. It does not modify the file content.

⛭ Generate Epochs → when enabled, Epochgram creates a zoomable timemap that groups many days into larger period summaries, helping you see the bigger picture without reading the timeline day by day. Epochs are generated hierarchically from day up to year, in essence, summaries of summaries. If marked records are present, Epochs are colored by the most common mark color in that range. You can regenerate a specific Epoch from the context menu.

Custom YAML

Epochgram supports the following custom YAML properties:

---
date: 2026-01-01 # override the anchor date
description: my summary # override the summary
noindex: # exclude this file from all indexing
notracked: # don't track changes for this file
noparsed: # don't parse dates from this file's content
nosimilar: # don't match this file by similarity
similar: [links, tags, title, semantics, topics] # match similarity only by these relations
repeat: every day # create recurring records
recur: every day # same as repeat
---

Settings & Data

Plugin data is mostly stored in the vault config directory, usually .obsidian/.

If Obsidian Sync is enabled, this data should synchronize between devices as long as ⛭ Sync → Vault configuration sync → Other file types is turned on. License data is stored separately in localStorage and is not synced through the vault config.

Epochgram also provides Rebuild and Reset popups for rebuilding or clearing stored data:

• ⛭ Rebuild
  • ⛭ All → rebuild all data.
  • ⛭ Index → rebuild the index; useful if something is broken or after an update.
  • ⛭ Search → rebuild the MiniSearch cache.
  • ⛭ Semantics → rebuild embedding vectors.
  • ⛭ Topics → reclassify topics.
  • ⛭ AI summaries → queue all files for AI summary generation.
  • ⛭ Epochs → queue all Epochs for regeneration.
• ⛭ Reset
  • ⛭ All → reset all data and settings to defaults, keep license data, then rerun indexing.
  • ⛭ Settings → reset all settings to defaults.
  • ⛭ Data files → clear data files and schedule regeneration.
  • ⛭ Search → clear the search cache.
  • ⛭ Pinned → unpin all items.
  • ⛭ Marks → remove all marks.
  • ⛭ Reviews → set all records to draft.
  • ⛭ Semantics → remove all embedding vectors.
  • ⛭ Topics → remove all topics and classification data.
  • ⛭ Tracked changes → remove all tracked changes.
  • ⛭ AI summaries → remove all AI summaries and use default "first N words".
  • ⛭ Epochs → remove all Epochs.

FAQ

How do I get support?
Check the docs first. If you still cannot find what you need, feel free to open an issue on GitHub. You can also join the Reddit community for discussions, feedback, and updates. If you have any other questions, just contact me at hi@epochgram.com.

What should I do if Epochgram feels slow?
On huge vaults or slower machines, performance may degrade. Try setting ⛭ Semantic threshold and ⛭ Topic threshold to 0, disable ⛭ Auto summarize and ⛭ Generate Epochs. You can also uncheck ⛭ Enable animation or reset plugin data.

What should I do if some records are missing?
Try rebuilding the index or reload Obsidian.

Disclosures

• Epochgram Pro:
  • Requires a payment and internet access for license validation; your email address, license key, and basic server-side telemetry may be processed (see TERMS).
  • Is not affiliated with Obsidian Sync, Publish, or other Obsidian paid services.
  • AI Bridge: Epochgram starts a local server on http://127.0.0.1 and opens a local bridge page in Google Chrome to use Chrome's on-device Summarizer API. The bridge communication stays on your device. Chrome may download its built-in model(s) (Gemini Nano) the first time you use these APIs.
  • Similarity: embeddings/topic models and runtime files may be downloaded on first use via @huggingface/transformers (for example from Hugging Face) and ONNX Runtime Web WASM from jsDelivr.
• All vault data is processed locally on your device and is NEVER sent over the internet.
• License: MIT (see LICENSE).