/memex-best-practices

name: memex-best-practices
description: Zettelkasten best practices for building a high-quality knowledge graph.
whenToUse: When the user asks about how to write good memory cards, naming conventions, linking strategies, or general Zettelkasten methodology. Also useful as a reference when writing or reviewing cards.

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

| Field | Required | Format | |-----------|----------|---------------------------------| | `title` | ✅ | Noun phrase, ≤60 chars | | `created` | ✅ | ISO date `YYYY-MM-DD` | | `source` | ✅ | Auto-filled by MCP/CLI client |

Optional Frontmatter

| Field | Format | Notes | |------------|-------------------------|------------------------------------------| | `tags` | YAML list | See [Tag System](#tag-system) below | | `category` | Single string | See [Categories](#categories) below | | `links` | YAML list of slugs | Explicit links (in addition to wikilinks) | | `status` | `conflict` / `draft` | Set by organize skill when needed |

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

| ✅ Good | ❌ Bad | Why | |---------|--------|-----| | `docker-compose-port-binding` | `note-1` | Descriptive vs. meaningless | | `jwt-revocation-blacklist` | `docker` | Specific vs. too broad | | `nextjs-app-router-caching` | `how-to-fix-the-bug-we-found` | Noun phrase vs. sentence | | `vitest-mock-timer-gotcha` | `vitest_mock_timer` | kebab-case vs. snake_case |

Special Slug Prefixes

Use these prefixes to signal card type at a glance:

| Prefix | Use | Example | |-------------|------------------------------------|--------------------------------| | `adr-*` | Architecture decision records | `adr-monorepo-vs-polyrepo` | | `gotcha-*` | Pitfalls, traps, surprising behavior | `gotcha-yaml-date-auto-parse` | | `pattern-*` | Reusable patterns, best practices | `pattern-retry-with-backoff` | | `tool-*` | Tool-specific tips and configs | `tool-gh-cli-pagination` |

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:

| Tag | When to use | |-------------|----------------------------------------------| | `decision` | A choice was made between alternatives | | `gotcha` | Surprising behavior, easy-to-miss pitfall | | `pattern` | Reusable solution or approach | | `howto` | Step-by-step procedure | | `reference` | Factual lookup (config format, API shape) | | `debug` | Root cause analysis of a specific bug |

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"

A