Memex Best Practices

Zettelkasten Best Practices

A reference guide for writing high-quality memex cards that compound in value over time. Covers card format, naming conventions, tagging, linking strategy, and graph health maintenance.

This is NOT a workflow skill (see memex-recall, memex-retro, memex-organize for those). This is a quality standard — consult it when writing or reviewing cards.

Card Quality Checklist

Before writing a card, verify:

• Atomic — one insight per card. If you can split it, do.
• Own words — distill and rephrase, don't copy-paste. This is the Feynman method: if you can't explain it simply, you don't understand it well enough.
• Non-obvious — would this change how you approach a similar task in the future? If not, skip it.
• Linked in context — [[wikilinks]] are embedded in sentences explaining why the relationship exists.

Card Format

---
title: "Short Noun Phrase ≤60 chars"
created: "YYYY-MM-DD"
source: "<auto-filled by client>"
tags: [domain-tag, type-tag]
category: "<domain>"
---

One atomic insight, written in your own words.

This relates to [[other-card]] because <explanation of the relationship>.

Required Frontmatter

Optional Frontmatter

Body Rules

• Write in plain Markdown
• Use [[slug]] wikilinks inline, within natural sentences
• Keep cards concise — aim for a few paragraphs, not an essay
• Code examples are fine, but the insight should stand without them

Slug Naming

Slugs are permanent identifiers. Choose them carefully.

Format

• kebab-case, all lowercase English
• 3–60 characters
• Descriptive but concise

Examples

Special Slug Prefixes

Use these prefixes to signal card type at a glance:

These are conventions, not enforced constraints. Use them when they fit naturally.

Categories

Assign one category per card to indicate its domain:

architecture · backend · frontend · devops · tooling · security · workflow · testing · data

Categories are broad. Use tags for fine-grained classification.

Tag System

Tags serve two purposes: domain (what technology) and type (what kind of knowledge).

Domain Tags

Use the specific technology or concept name:

docker · nodejs · typescript · react · nextjs · postgres · redis · git · api · css · linux · aws · azure

Type Tags

Classify the kind of insight:

Tagging Guidelines

• Use 1–3 tags per card (one domain + one type is ideal)
• Prefer existing tags over creating new ones
• Tags are lowercase, single-word or hyphenated (rate-limiting, not Rate Limiting)

Linking Strategy

Links are the most valuable part of a Zettelkasten. They create a network that surfaces unexpected connections.

Link in Context

Every [[wikilink]] should appear in a sentence that explains the relationship:

<!-- ✅ Good: link explains WHY -->
This contradicts what we found in [[jwt-migration]] — stateless tokens
can't be revoked without a server-side blacklist.

<!-- ❌ Bad: link without context -->
Related: [[jwt-migration]]

When to Link

• Contradiction — "This conflicts with [[X]] because..."
• Extension — "This builds on [[X]] by adding..."
• Example — "[[X]] is a concrete instance of this pattern"
• Alternative — "We chose this over the approach in [[X]] because..."
• Prerequisite — "Understanding [[X]] is necessary context for this"

Avoid Over-Linking

Not every card needs to link to every related card. Link when the connection would surprise someone or change how they read either card.

The Keyword Index

The index card is a curated entry point to the entire knowledge graph — inspired by Luhmann's Schlagwortregister (keyword register).

Purpose

• Provides structured entry points for the memex-recall skill
• Groups cards by concept, not by chronology
• Each card appears under 1–2 categories

Format

---
title: Keyword Index
created: <date>
source: organize
---

## Authentication
- [[jwt-revocation-blacklist]] — Server-side revocation for stateless tokens
- [[oauth2-pkce-flow]] — PKCE flow for public clients (SPAs, mobile)

## Docker
- [[docker-compose-port-binding]] — 0.0.0.0 vs 127.0.0.1 gotcha
- [[docker-multi-stage-builds]] — Reducing image size with build stages

The index is maintained by the memex-organize skill. You can also update it manually after writing cards.

The Recall → Work → Retro Loop

The core memex workflow is a learning cycle:

┌─────────────────────────────────────────────────┐
│                                                 │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐ │
│   │  RECALL  │───▶│   WORK   │───▶│  RETRO   │ │
│   │          │    │          │    │          │ │
│   │ Search   │    │ Do the   │    │ Distill  │ │
│   │ existing │    │ actual   │    │ insights │ │
│   │ cards    │    │ task     │    │ to cards │ │
│   └──────────┘    └──────────┘    └──────────┘ │
│        ▲                               │       │
│        └───────────────────────────────┘       │
│              Cards feed future recalls          │
└─────────────────────────────────────────────────┘

• Recall (task start) — search for relevant prior knowledge before starting work. Avoid repeating past mistakes.
• Work — do the actual task, informed by what you recalled.
• Retro (task end) — reflect on what you learned. Write cards for non-obvious insights only.

This loop is implemented by the memex-recall and memex-retro skills. The key insight: retro is not just documentation — it's how you learn. Writing in your own words forces deeper understanding than simply bookmarking a Stack Overflow link.