Using Engram

How notes get in, and how you edit them once they're indexed.

Add — ingest notes

The Add ▾ toolbar menu has two granularities:

Section group (course PDF) — the bulk path. One PDF (e.g. one course) is split into many notes, recovering Domain → Section group → Section → Note from the text layer. This split is tuned for OneNote exports. Re-adding the same course is incremental — only changed/new notes are re-processed.
Single page (one note) — drop in any PDF (not just OneNote) as one note. The whole file becomes a single note, filed under a domain · section group · section you choose.

📄 Why two granularities

Bulk auto-split is fast for whole courses but layout-dependent; single-page add is source-agnostic and precise. In the app the single-page option is enabled once a domain has a section group to file the page into.

uv run python -m engram add "Data Science" "CSE 234.pdf"
uv run python -m engram add-page "Data Science" page.pdf --section "Lectures"

Provenance — why edits are durable

Every note carries a source: export notes come from a section-group PDF (and are diffed against it on every re-import), while page notes were added standalone and are independent. A course re-import only diffs its own export notes and never removes your added pages. This is what lets the two ingest paths — and your manual edits — coexist without destroying each other.

Edit a note

Right-click any note in the sidebar for file-like operations:

Action	What it does
Open / Reveal in Finder	Open the note, or show its files in Finder.
Re-transcribe	Re-run the model on the note's preserved page and rewrite its summary.
Move / Rename	Relocate or retitle; an export note detaches into an independent page note at the target.
Duplicate	Copy to a new independent page note.
Delete	Remove it; an export note is tombstoned so a re-import won't resurrect it.

Edits make the graph stale

Any add/edit bumps the domain's revision, so cross-links and the concept map fall behind — the app shows a stale dot on Link / Concepts. Re-run them to refresh. (engram domain status "Data Science" reports staleness.)

Transcription models

Choose the reader in Settings → Transcription model. All produce the same index-style summary.

Option	What it is	Best for
`claude-code`	Claude vision via your Claude Code login (default)	Best quality & math; no API key.
`local-7b`	Qwen2.5-VL 7B on-device (mlx-vlm)	Fast, free, fully offline.
`local-32b`	Qwen2.5-VL 32B on-device	Better local quality; ~3–4× slower, needs ~64 GB.

Filters — what gets indexed

Engram indexes knowledge, not everything. By default it skips (and reports — never silently drops) noise. Toggle these in Settings.

Filter	Skips	Config
Papers	attached papers & printouts/scans	`skip_papers`
Homeworks	homework / assignment / lab / project	`skip_homework`
Long code	code notebooks over N pages	`skip_code_over_pages`
Custom	any section/title substring you add	`skip_section_patterns`

Next: Connecting knowledge →