# ethanchang.io — full Markdown Concatenated published essays and project files. Prefer the per-page URL with `Accept: text/markdown` when you only need one document. --- # Placeholder 2026-01 Empty placeholder for the article index pager. Not a real essay. This is a placeholder article used to exercise the article index pager. --- # Placeholder 2026-03 Empty placeholder for the article index pager. Not a real essay. This is a placeholder article used to exercise the article index pager. --- # Placeholder 2026-04 Empty placeholder for the article index pager. Not a real essay. This is a placeholder article used to exercise the article index pager. --- # Placeholder 2026-05 Empty placeholder for the article index pager. Not a real essay. This is a placeholder article used to exercise the article index pager. --- # Placeholder 2026-02 Empty placeholder for the article index pager. Not a real essay. This is a placeholder article used to exercise the article index pager. --- # Embed preview: a post and a video A post from X and a YouTube video on one page, to check TweetEmbed and VideoEmbed together. This page does one thing: put two external citations in the same reading flow, and see how they sit with the prose. First, a post from X, using our own card so the full text stays on the page: Then a YouTube video, using the official player: --- # How I use Heptabase for deep learning How I use Heptabase for knowledge work, deep study, and research — and how it sits next to Obsidian. > "The point of visualizing notes is to build a deep understanding of what you have learned." — that is what using Heptabase taught me most clearly. If you know my [PKM practice](/articles/pkm-method), you might ask: with Obsidian, why Heptabase? They solve **different layers**. Obsidian is good at **linear, structured notes**. Heptabase is good at **seeing relations among concepts**. This is how I use both. ## Meeting Heptabase I first found Heptabase through an interview with the founder, Alan Chan. One line hit: > Real understanding does not live in “the link between two books.” It lives in “the links among all the concepts in those two books.” That was my old confusion — a dense web of backlinks in Obsidian, and still no **global view**. The Heptabase whiteboard fills that gap. ## Three kinds of card ### 1. Literature cards Raw material — excerpts from books, papers, courses, podcasts. - Keep the source and the surrounding context - Organized by chapter or theme - Ingredients, not the dish ### 2. Concept cards The core. Each concept card: - Holds one idea - Uses a one-sentence title - Is rewritten in my words, with the original as support ### 3. Index cards A table of contents for the board: related concepts, easy to revisit. ``` literature → extract → concept → integrate → index ``` ## Five steps I follow the deep-learning method from the official Heptabase wiki: ### 1. Record Capture important passages as you read; file them as literature cards by chapter. ### 2. Break down Make a whiteboard, import the literature cards. Pull out core concepts and turn them into concept cards. The key: **summarize the concept in one sentence, and make that the title**. You should know what it is at a glance. ### 3. Relate Draw arrows between concept cards. Cause? Containment? Contrast? ### 4. Group Use Sections to cluster related cards, and name each Section. ### 5. Integrate Join new concepts to old ones. Let the knowledge become a network. ## The force of atoms > Only when notes are atomic can visualizing them give you a deep hold on the subjects you care about. If a note is long and full of points, visualization does little — you are relating “two books,” not “two concepts.” A concrete case. I read *Mindstorms* and *The Early History of Smalltalk*, both relevant to dynamic media. I made a board, put the related concept cards from both books on it, and organized them as a mind map. Because I had already atomized while reading, I could reuse that knowledge later without starting over. ## Color I use color for card attributes: | Color | Meaning | |------|------| | 🟢 Green | Finished cards | | 🟡 Yellow | Source / material boards | | 🔵 Blue | Knowledge boards | Clear at a glance in Map view. ## P.A.R.A. spaces My Spaces split into: - **P.A.R.A.**: Projects, Areas, Resources, Archives - **Theme boards**: by interest and research direction Project boards and knowledge boards stay separate. ## When to open Heptabase A few rules I keep: 1. **Only make a board when I am thinking hard** - Not every stray thought gets a board - Delete it if I no longer need it 2. **A board is a map of thinking** - Add the result of each session - So I can return and reuse 3. **Research boards vs knowledge boards** - Research: project sources, literature, ideas - Knowledge: reusable knowledge ## With Obsidian The current workflow: 1. **Quick thought → Flomo** 2. **Needs deep filing → Obsidian** (atomic notes, backlinks) 3. **Needs visual understanding → Heptabase** (boards, concept relations) Three tools, three jobs. ## In short Heptabase is how I finally understood a “knowledge network”: 1. **Atomic**: one concept, one card 2. **Visual**: see the whole on a board 3. **Reusable**: old knowledge can steer new research 4. **Accumulating**: every session feeds the network The tool is not the goal. Becoming someone who is good at learning is. --- *For more Heptabase technique, see the [official wiki](https://wiki.heptabase.com).* --- # A demo of a series of content This is a demo used to show how a collection looks on this site. I'm trying this out: what does a collection article look like? I want the blog to hold a deep, nested collection — a place to explore and share the things we care about at length. --- # My PKM practice: from notes to a knowledge network The personal knowledge system I run in Obsidian: three layers, naming rules, and a bias toward links. > "Your notes are not a warehouse for information. They are a tool for thinking." — that is the deepest lesson of years of PKM. We do not lack information. We lack the ability to turn it into knowledge that is actually ours. This is the system I run in Obsidian. The core method comes from Andy Matuschak’s Evergreen Notes. ## Why a system at all Every day we take in a lot: articles, podcasts, books, papers. Most of it is gone by the next day. Very little can be recalled on demand. The usual problems with notes: - **Fragments**: notes sit alone, never a network - **Hard to reuse**: you wrote it, then you cannot find it, or cannot read it - **Hard to maintain**: more notes, uneven quality A good PKM system should mean **more notes without more mess**. ## Three layers: material → atom → index Each layer has a job: ### Layer 1: Material notes The raw intake — articles, book notes, meeting notes, stray thoughts. - Keep the source and the context - They can be long and mixed - Raw material, not the finished thing ### Layer 2: Atom notes The core. Evergreen notes should be **atomic** — one idea each, so they can be used and combined on their own. - One note, one idea - Rewritten in your own words, not a paste - Other notes can cite and link them ### Layer 3: Index notes A table of contents and a map: they gather related atoms. Common shapes: - Topic index: every note under a subject - Concept index: a hard idea and its neighbors - Project index: notes for one project ``` material ──extract──> atom ──organize──> index ↓ ↑ └────────── bidirectional links ←─────────┘ ``` ## Naming: titles as sentences Naming is a load-bearing part of the system. A good title should: ### Prefer a sentence over a phrase | ❌ Avoid | ✅ Prefer | |---------|---------| | Writing tips | Finish first, then polish | | Compound interest | Compound interest lets a small edge accumulate | | Deep work | Deep work has to be practiced on purpose | ### Point at a concept The title should name a **concept** or a **claim**, not a task or a project. ### Be findable later Three months from now, what would you type to find this note? The title should answer that. ## The art of linking: density over folders > "The links between notes matter more than the notes." That is the line I repeat most. One note is limited; a network of notes is **1+1>2**. ### Why dense links - **Trigger association**: one note reminds you of others - **Surprise insight**: links you did not plan - **Build a viewpoint**: different indexes, different structures ### Practice 1. **Link when you see a relation** — do not wait for the perfect moment 2. **Think both ways** — if you link to A, what does A link to? 3. **Prefer links over folders** — connect it instead of filing it ## Lifecycle: seed → sprout → evergreen Notes are not born equal. Mine have three states: ### 🌱 Seed notes Early, half-formed. - Fragments, claims not yet tested - Need more work - Often excerpts from material notes ### 🌿 Sprout notes Rewritten, not yet mature. - In your own words - A basic shape - Still need more links and filling-in ### 🌲 Evergreen notes Mature enough to stand alone. - Atomic: one note, one core idea - Reusable across contexts - Well linked ``` 🌱 seed → 🌿 sprout → 🌲 evergreen ↓ ↓ ↓ needs work in progress reusable ``` Notes should move through this life, not freeze in one state. ## Workflow: from reading to writing ### 1. Capture Save what is worth it, fast: - Read-later tools (Pocket, Instapaper) - WeChat / Flomo quick capture - Straight into the inbox of the vault ### 2. Process On a cadence (daily or weekly): - Pull the core idea - Rewrite it - Place it near a related theme ### 3. Link The step people skip, and the one that matters: - Which existing notes does this touch? - Make the bidirectional links - Update the relevant indexes ### 4. Output After enough accumulation, writing gets easier: - The network is the source material - Index notes are outlines - Evergreen notes are paragraphs ## In short 1. **Atomic**: one note, one idea 2. **Links first**: the connections matter more than the note 3. **Keep moving**: notes have a life; they should iterate 4. **Naming is thinking**: a good title is the start of a thought Tools are never the point. **The habit of thinking is.** Treat each note seriously, and knowledge really does grow. --- # Aletheia In-context lookup and review while reading English Aletheia means “to bring to light” — a lamp held up to the confusion of reading. The Greek root is often rendered as “unconcealment.” It is my second project: looking up words while reading English, and an early experiment in tools for research and analysis — select, highlight, and pull unfamiliar words into cards you can review. ## Lookup that does not invade The lookup interaction is quiet. It does not wreck the page with five or six highlight colors that steal attention. A traditional dictionary may offer five to ten senses; you have to match them yourself, which is a real tax on reading. We send the surrounding context to an AI agent and get back the sense that actually fits — lookup in context, not a dump from a dictionary. ## Review after lookup Lookup without review is cheap. So there is a small review module, reusing the swipe gestures (left, right, up, down) from the first project, Maker Plan. That **highlight → structure → card** pipeline did not stay a draft. It was tightened into a product of its own in [Trace](/projects/trace). Aletheia is the lab; Trace is the product. --- # Chunk A content system for notes at scale Chunk is an experiment in organizing content after notes number in the thousands — more, without messier. Its data model inherits the card paradigm from [Networks](/projects/network); its intake inherits the low-friction capture of [Robert](/projects/robert). When cards reach the thousands, does the structure still hold? It sits in the same line as the three-layer architecture in my [PKM practice](/articles/pkm-method). Chunk does not invent a new way to organize from scratch; it takes the card unit that already worked in Network and pushes it to a larger scale. --- # Craft Space Workspace management and a small productivity kit Craft Space is a set of experiments around “workspace”: how to bring everything a stretch of deep work needs — sources, tools, context — into place in one motion. --- # Deeptalk An AI conversation and learning assistant Deeptalk is a prototype of an AI conversation-and-learning assistant: what happens if dialogue itself is the medium for going deep. --- # ethanchang.io The hypermedia container you are in This site is a work of its own — not another card in a list, but the container that shows the experiments: prose, demos, rule toys, and **software-grade interaction** in one media engine. It is not a blog. An article is only one of the media levels it can carry. It is closer to a software product that keeps gaining features. ## Architecture - **Framework**: Astro 5 (islands + MDX collections) - **Interactive islands**: Svelte 5 (runes) - **Scroll narrative**: GSAP ScrollTrigger - **Style**: Tailwind CSS v4 design tokens - **Deploy**: Cloudflare Pages. D1 and KV are already running. Auth is wired; the nav no longer shows login. Want the mechanism? The live demo of every media component is on [/lab](/lab). --- # Maker Plan A small, quiet app for writing and reviewing flashcards My first software project. The motive was blunt: popular review apps are either noisy and messy, or the features are badly built. “Messy” means the UI is cluttered, and review is not a first-class citizen — it is buried behind a second-level door. You often have to pick a deck before you can start the day’s review, which is resistance and noise. The card editor is awkward too: not powerful enough, not finished enough. ## What I wanted to get right The **card editor** should support: - Cloze deletions on Q&A cards - Image-hint clozes - Masked-text clozes: merge different hint blocks into one review item, hide the others each time you recall — “hide one, test all” and “merge different clozes.” Many editors never ship this **Bulk import**: after a single card works, import a lot of flashcards at once, write them the way you write notes, and file them where they belong. I wanted a small, quiet, easy-to-use app. --- # Networks A notes app where every card is both folder and document My third project. In short, I wanted a Heptabase where every card was stronger — able to be a folder and a document. The plan had five or six card types: Excalidraw, Whiteboard, ordinary cards, and more. It was also the first desktop notes app I seriously **shipped**. The bet was simple: heavy writers will keep both hands on the keyboard if it is fast enough. The product is organized around **cards** — each card a Markdown unit, arrow keys to move, Enter to edit, Esc to save and leave. This is not decorative “card UI”; it is the data model: notes cut into blocks you can move, link, and recombine. It proved two things: the card as a content unit holds; keyboard navigation can cover the loop from browsing to editing. [Chunk](/projects/chunk) inherited the latter directly. ## Why it stopped The work spread too far and collapsed. With the time I had, I could only do a single card-plus-folder mechanism well. The full vision — many card types coordinated with folder/card — was more than I could carry then. The project paused. The structure “a note is both folder and document” continued into Robert. --- # Robert A personal context manager with a robert agent My fourth project. The name is a butler’s name — I wanted it to be a personal context manager. In parallel with desktop [Networks](/projects/network), Robert puts **voice** at the front door, inspired by flomo but with even less friction: voice in, Whisper transcribes, block-level cards out. The easier capture is, the more ideas you keep. One lives in the pocket, one on the desk, on the same line of inquiry: how knowledge flows in as **blocks**, not as documents dumped into folders. That low-friction capture later fed [Chunk](/projects/chunk). ## Structure The note structure follows Networks: a note can have several parent cards; each note is both a folder and a document. You store in it, and you navigate with it. ## The robert agent Several parents is too much flexibility. Matching them by hand is like finding one folder, except now you must find several — a lot of resistance and fatigue. So we introduced a robert agent: an async confirmation loop, so the system and the user agree on what to keep. Each evening the agent takes some of the context you gave it, explores structure against what it already knows. Say you already have a “programming notes” card, and today you wrote five notes on programming. After reading them, the agent remembers “programming notes” and asks: should these five become children of that card? --- # Trace An agent reading-chat with a learning loop My fifth project. An agent you read and chat with, but with a learning loop built in. ## Three core abilities **1. Sub-thread chat** It is an AI chat app that can open a new branch mid-conversation, keep context clean, and let you go deeper wherever curiosity pulls. **2. Highlight → flashcard** It is also an agent-assisted flashcard app. Highlight what you want to learn; the agent turns those highlights into cards. **3. In-context vocabulary cards** I want to read English in the original, so Trace inherits Aletheia’s vocabulary cards: look up a word in context, save it, and review it later. Aletheia is the lab; Trace takes that highlight → structure → card pipeline and shapes it for reading. Trace also gathers the earlier line of work: Maker Plan’s review gestures, Aletheia’s in-context lookup, and an agent-driven loop of reading and learning.