How Markdown Became the Bridge Between My Notes, My Code, and AI

For a long time, my knowledge lived like loot scattered across save files. Notes in one app, blog drafts in another, project decisions buried in commit messages, and the actually important context in a chat thread I could never find again. Each piece made sense on its own. Together, they explained nothing.

AI made that fragmentation expensive. Language models are very fast interns with amnesia: useful when I hand them explicit context, much less useful when the plan is “somewhere in my head, partially.” Every new session began with an archaeological dig through commits, notes, and old conversations.

The change that helped most was not a new model. It was a small Markdown savepoint that said what I had finished, what was blocked, and what should happen next.

That pushed me toward a rule: write structured knowledge first, publish second. Markdown is now the interchange format between my Logseq vault, code repositories, blog, and AI tools. Not one magical file powering everything—separate files still have separate jobs—but one readable format crossing the boundaries.

The bridge is the format, not one file

Markdown is plain text with a little visible structure: # marks a heading, - marks a list item, and links remain links even when the editor disappears.

That lack of magic is the useful part.

• Logseq stores durable project context, linked notes, tasks, and daily savepoints in Markdown.
• Git repositories keep plans, architecture documents, and code-adjacent decisions close to the implementation.
• Astro publishes separately edited Markdown files from src/content/posts.
• AI tools can read the relevant files directly or receive a small selected block as context.

The blog is not literally rendering my Logseq vault. A note becomes a post through editing, and the published file lives in a different repository. That duplication has a cost: changes can drift, and I still have to decide which version owns which fact.

The bridge is that I do not have to translate the idea into a proprietary document, export it, strip hidden formatting, and explain the structure again. The same syntax survives the trip.

Savepoints carry the context Git cannot

The highest-value part of this system is embarrassingly small. At the end of material work, I leave a savepoint shaped roughly like this:

### savepoint
- task: the page or issue to resume
- state: the current project state
- done: what materially changed
- blocked: what prevents progress, if anything
- next: the next concrete action

Git tells me what changed. A savepoint tells me what it meant: intent, decisions, open doubts, and the next move.

That distinction matters when I return three days later. A commit can show that twelve files changed; it usually cannot tell me why option B lost, which verification is still missing, or what past-me expected to do on Monday. Past-me, notoriously, leaves the office without answering follow-up questions.

The savepoint also gives an AI assistant a bounded handoff. Instead of asking it to infer my plan from an entire repository, I can point to the task, the current state, and the next action. Less séance, more briefing.

Why Markdown keeps winning

Markdown is not glamorous. It is the cargo pants of file formats: nobody photographs it for a design award, but it carries an unreasonable amount of useful stuff.

For this workflow, it has four practical properties:

1. It is inspectable. I can open the file in any editor and see the structure.
2. It diffs cleanly. Git shows the sentence or decision that changed instead of an opaque document blob.
3. It is easy to search and link. Filenames, headings, properties, and plain words remain available to ordinary tools.
4. It travels well. Static-site generators, note apps, code hosts, and AI tools all understand enough plain text to work with it.

It is not the best representation for every problem. Databases are better at transactions and queries. Purpose-built interfaces are better at workflows with strict validation. Markdown becomes messy when nobody owns structure or when several copies pretend to be canonical.

For knowledge that humans need to read, version, move, and hand to tools, those limits are acceptable. Boring, visible files beat a clever system I cannot inspect.

What exists now, and what does not

Today, the workflow is explicit rather than automatic:

• I capture project state and ideas in the Logseq vault.
• Agents and I read that context before material work.
• Code repositories keep their own implementation plans and documentation.
• A publishable idea becomes a separately edited Astro post.
• The site provides ordinary title, description, and tag search—not semantic search across every paragraph.

Semantic retrieval, asking an assistant questions across the public archive, and deriving several formats from one canonical source are useful next steps. They are not the current architecture, and pretending they already exist would be an excellent demonstration of why durable context needs facts instead of vibes.

The important part already works: Markdown gives each system a boundary that the next system can read.

A small version of the workflow

You do not need my vault structure to borrow the useful bit:

1. Keep a plain-text task or project note near the work.
2. At the end of a session, write state, done, blocked, and next.
3. Link the decision or source that future-you would otherwise have to rediscover.
4. Give the next human or AI session that small context before the repository dump.

The format is not the workflow. The habit of leaving a truthful handoff is.

None of these building blocks are new. Markdown is old. Git is old. Static sites are old. Linked-note systems have been around long enough to collect their own archaeology.

What changed for me is the connection. My notes, code, blog, and AI context no longer need to live in one database to share a language. They need clear ownership, a readable boundary, and enough structure to survive the handoff.

Cargo pants, remember. Not one pocket. One thing that makes all the pockets useful.