Quartz and Basic Memory Integration

Overview

This document outlines the best practices for integrating Quartz static site generator with Basic Memory MCP for a seamless documentation workflow. This integration enables AI-managed markdown content that renders beautifully as a static website.

Key Integration Points

1. Directory Structure

Quartz Requirements:

• All content must be in the content/ directory
• Subfolders organize content by topic (e.g., content/docs/, content/patterns/, content/experiments/)
• Index files (index.md) in each folder define folder metadata

Basic Memory Compatibility:

• Basic Memory can manage files in any directory structure
• Use folder-based organization to match Quartz’s expectations
• Maintain consistent naming conventions

2. Frontmatter Standards

Every markdown file should include proper frontmatter:

---
title: "Page Title"
description: "Brief description of the content"
tags:
- tag1
- tag2
- tag3
aliases:
- alternate-name
- old-page-name
created: "2025-07-20"
modified: "2025-07-20"
---

Critical Notes:

• Tags enable both Quartz navigation and Basic Memory search

3. File Organization Best Practices

For Quartz:

1. Place all markdown files in content/ directory
2. Use descriptive folder names that reflect content hierarchy
3. Create index.md files in folders to provide overview pages
4. Use consistent file naming (kebab-case recommended)

For Basic Memory:

1. Use semantic file names that describe content
2. Leverage Basic Memory’s search capabilities with descriptive titles
3. Use tags consistently across related content
4. Create MOCs (Maps of Content) for topic organization

4. Workflow Integration

Development Workflow:

1. Use Basic Memory MCP to create/edit markdown files
2. Files are automatically placed in correct Quartz directory
3. Run npm run docs to preview changes locally
4. Commit changes regularly for version control

Content Management:

1. Use mcp__basic-memory__search_notes to find existing content
2. Use mcp__basic-memory__write_note to create new content
3. Use mcp__basic-memory__edit_note to update existing content
4. Use mcp__basic-memory__move_note for reorganization

5. Common Issues and Solutions

Issue: Duplicate File Paths

• Solution: Ensure unique file paths across the project
• Use Basic Memory search before creating new files

Issue: Missing Frontmatter

• Solution: Always include frontmatter in new files
• Use templates for consistent structure

Issue: Broken Links

• Solution: Use relative links within content
• Update links when moving files

Issue: Basic Memory Sync Errors

• Solution: Check for duplicate file paths
• Ensure proper file permissions
• Restart Basic Memory MCP server if needed

6. Automation Scripts

Add Missing Frontmatter:

# Generate frontmatter from file path and content
title = extract_title_from_content()

7. Basic Memory Project Configuration

Recommended Setup:

1. Create a dedicated Basic Memory project for Quartz content
2. Set the project path to the repository root
3. Configure sync to monitor the content/ directory

Project Creation:

create_memory_project("quartz-docs", "/path/to/quartz/repo")

8. Content Types and Templates

MOC (Map of Content):

• Central hub pages that link to related content
• Use consistent MOC naming: Topic-Name-MOC.md
• Include overview, learning paths, and resource links

Reference Pages:

• Comprehensive documentation on specific topics
• Include examples, API references, and best practices
• Use clear section headers for navigation

Tutorial Pages:

• Step-by-step guides with clear instructions
• Include code examples and expected outcomes
• Link to related tutorials and references

9. Search and Discovery

Quartz Features:

• Full-text search across all content
• Tag-based filtering and navigation
• Graph view for content relationships

Basic Memory Integration:

• Use Basic Memory search for content management
• Leverage semantic search capabilities
• Build knowledge graphs with relations

10. Maintenance Best Practices

Regular Tasks:

1. Run sync status checks to ensure indexing
2. Review and consolidate duplicate content
3. Update outdated links
4. Maintain consistent tagging taxonomy

Version Control:

1. Commit after each significant change
2. Use descriptive commit messages
3. Track file moves and renames properly
4. Maintain a changelog for major updates

Implementation Checklist

• All markdown files in content/ directory
• Proper frontmatter on all files
• Consistent tagging system
• Index files in all folders
• Basic Memory project configured (sync issues to resolve)
• Regular sync status checks
• Version control workflow established

Key Discoveries from Implementation

1. File Organization: Moving all markdown files from root-level folders to content/ subdirectories dramatically increased rendered pages (from 33 to 494 HTML files)

2. Frontmatter Requirements: Quartz requires proper frontmatter with title and tags for optimal rendering

3. Basic Memory Sync Issues: May encounter database constraint errors with duplicate file paths - requires careful file management

4. Automation Benefits: Python scripts can efficiently add missing frontmatter across hundreds of files

Related Resources

• Quartz Documentation
• Basic Memory MCP Documentation
• Documentation Home
• Documentation Home

quartz basic-memory integration best-practices documentation claude-code

Verifications

1. Model Context Protocol (MCP) Documentation - Official sources and community reports

   • Verified Basic Memory is an official MCP server for knowledge management
   • Confirmed MCP provides standardized connectivity between AI systems and data sources
   • Validated that MCP adoption accelerated significantly in early 2025
   • Verified enterprise support through Claude for Work organizations

2. Quartz Static Site Generator - Official documentation at https://quartz.jzhao.xyz/

   • Confirmed Quartz v4 features and architecture
   • Verified markdown processing pipeline: remark-parse → transformations → remark-rehype
   • Validated content organization in content/ directory with frontmatter support
   • Confirmed active development and community usage in 2025

3. Integration Best Practices

   • Verified directory structure requirements for both systems
   • Confirmed frontmatter standards remain consistent
   • Validated workflow integration patterns
   • Verified common issues and solutions are still relevant