Entry Format Reference

Memex entries are Markdown files with YAML frontmatter.

Basic Structure

---
title: Entry Title
tags: [tag1, tag2, tag3]
created: 2025-01-15
description: One-line summary for search results
---

# Entry Title

Your content here with [[bidirectional links]] to other entries.

Frontmatter Fields

Required

Optional

Semantic Links (optional)

Semantic links are usually computed by Memex when semantic linking is enabled. They can also be set explicitly via CLI (mx add --semantic-links or mx replace --semantic-links).

semantic_links:
  - path: reference/cli.md
    score: 0.82
    reason: embedding_similarity
  - path: guides/quick-start.md
    score: 0.74
    reason: shared_tags

Typed Relations (optional)

Typed relations are manual, directed links that carry a relation type. Add them by editing frontmatter directly (or via mx patch / mx replace).

relations:
  - path: reference/cli.md
    type: documents
  - path: guides/installation.md
    type: depends_on

Canonical relation types

Use snake_case and prefer these canonical types. If none fit, use related as the fallback.

Use mx relations-lint to audit unknown or inconsistent relation types.

Bidirectional Links

Link to other entries using wiki-style syntax:

See [[guides/installation]] for setup instructions.

Or use display text: [[guides/installation|the installation guide]].

Link Resolution

Links resolve in this order:

1. Exact path match (with or without .md)
2. Title match (case-insensitive)
3. Filename match (for short links)

Examples

[[guides/installation]]           # Path link
[[Installation Guide]]            # Title link
[[installation]]                  # Filename link
[[guides/installation|Setup]]     # With display text

Tags

Tags enable filtering and discovery:

tags: [infrastructure, deployment, docker]

Best Practices

• Use lowercase, hyphenated tags
• Check existing tags with mx tags
• Be consistent across entries
• Use 2-5 tags per entry

Common Tag Patterns

Content Guidelines

Headings

Use heading hierarchy for structure:

# Main Title (matches frontmatter title)

## Section

### Subsection

Code Blocks

Use fenced code blocks with language hints:

\`\`\`bash
mx search "query"
\`\`\`

\`\`\`python
def example():
    pass
\`\`\`

Lists

Use consistent list formatting:

- Item one
- Item two
  - Nested item

1. First step
2. Second step

File Organization

Categories

Organize entries into directories:

kb/
├── guides/           # How-to guides
├── reference/        # Reference documentation
├── patterns/         # Reusable patterns
├── troubleshooting/  # Problem-solution pairs
├── projects/         # Project-specific docs
└── infrastructure/   # Infrastructure docs

Naming

• Use lowercase with hyphens: my-entry-title.md
• Keep names descriptive but concise
• Avoid special characters

Templates

Use templates for consistent structure:

# List available templates
mx templates

# Show a template and copy it into a new entry
mx templates show troubleshooting

Built-in Templates

See Also

• CLI Reference
• Quick Start Guide