Qmd Knowledge

QMD Knowledge

What I do

• Record and retrieve project learnings and insights
• Capture issue-specific notes and resolutions
• Build a growing, AI-searchable knowledge base
• Provide context about project architecture and decisions

When to use me

Use this skill when you need to:

• Record learnings: Capture new insights, patterns, or best practices discovered during development
• Track issues: Add notes to ongoing or resolved issues
• Query knowledge: Search for previous decisions, learnings, or solutions
• Maintain context: Build institutional memory for the project

How it works

This skill provides a unified knowledge management system. You install the skill once, and it manages knowledge across all your projects using qmd collections:

# The qmd-knowledge skill (installed to your AI tool's skills directory)
# Location varies by tool: $HOME/.config/opencode/skills/, $HOME/.claude/skills/, or $HOME/.config/amp/skills/
├── SKILL.md              # This file - the skill definition
├── scripts/              # Executable scripts
│   └── record.sh         # Record learnings/issues/notes
└── references/           # Example structure and READMEs

# Project knowledge storage (managed by the skill)
~/.ai-knowledges/
├── <project-name>/       # Collection for your project
│   ├── learnings/
│   └── issues/
└── another-project/      # Collection for another project
    ├── learnings/
    └── issues/

The qmd MCP server provides AI-powered search across all stored knowledge, allowing your AI assistant to autonomously query and update the knowledge base.

Available scripts

Recording knowledge

Important: Before recording knowledge, ensure qmd is installed and your project collection is set up. Run a preflight check:

# Verify qmd is installed
command -v qmd || echo "Install qmd: bun install -g @tobilu/qmd"

# Verify your project collection exists (replace my-project with your actual project name)
qmd collection list | grep my-project

# Record a learning (use the skill's script)
$SKILL_PATH/scripts/record.sh learning "qmd MCP integration"

# Add a note to an issue
$SKILL_PATH/scripts/record.sh issue 123 "Fixed by updating dependencies"

# Record a general note
$SKILL_PATH/scripts/record.sh note "Consider using agent skills for extensibility"

After recording:

• The record.sh script automatically runs qmd embed to re-index the knowledge base
• This embedding step is required to make newly added content searchable for the next query
• If auto-embedding fails or you manually add/edit files, run qmd embed explicitly to update the index

Querying knowledge

Use the qmd MCP server tools directly from Claude or OpenCode:

# Fast keyword search
qmd search "MCP servers" -c <project-name>

# Semantic search with AI embeddings
qmd vsearch "how to configure MCP"

# Hybrid search with reranking (best quality)
qmd query "MCP server configuration"

# Get specific document
qmd get "references/learnings/2024-01-26-qmd-integration.md"

# Search with minimum score filter
qmd search "API" --all --files --min-score 0.3 -c <project-name>

Setup

Preflight check: Before starting, verify you have the required tools:

# Check for bun or node
command -v bun || command -v node || echo "Install bun or node.js first"

# Verify git is available (for project detection)
command -v git || echo "Install git for automatic project name detection"

1. Install qmd:

   bun install -g @tobilu/qmd

2. Install the skill:

   # The skill is installed to your AI tool's skills directory:
   # - OpenCode: $HOME/.config/opencode/skills/qmd-knowledge/
   # - Claude Code: $HOME/.claude/skills/qmd-knowledge/
   # - Amp: $HOME/.config/amp/skills/qmd-knowledge/

3. Configure MCP server (see installation docs for Claude/OpenCode/Amp)

4. Create a knowledge collection for your project:

   # The skill's record.sh script will auto-detect the project name when executed.
   # For manual setup, use your desired project name consistently in the commands below.
   # Optional: export QMD_PROJECT=<project-name> to override auto-detection
   
   # Create storage directory for your project (replace <project-name> with your project)
   mkdir -p ~/.ai-knowledges/<project-name>/learnings
   mkdir -p ~/.ai-knowledges/<project-name>/issues
   
   # Add qmd collection
   qmd collection add ~/.ai-knowledges/<project-name> --name <project-name>
   qmd context add qmd://<project-name> "Knowledge base for <project-name> project: learnings, issue notes, and conventions"
   
   # Generate embeddings for AI-powered search
   qmd embed

Knowledge structure

• references/learnings/: Time-stamped markdown files with project insights

  • Format: YYYY-MM-DD-topic-slug.md
  • Contains learnings, patterns, architectural decisions

• references/issues/: Issue-specific notes and resolutions

  • Format: <issue-id>.md
  • Append-only log of notes related to specific issues

Integration with qmd MCP server

The qmd MCP server allows Claude to:

• Search knowledge: Use natural language queries to find relevant context
• Auto-update index: Automatically reindex after adding new knowledge
• Filter by project: Use --collection flag to scope searches to specific projects

Example workflow

1. During development, you discover something useful:

   "I learned that qmd MCP server allows Claude to use tools autonomously."

2. Claude recognizes the skill and executes:

   $SKILL_PATH/scripts/record.sh learning "qmd MCP autonomous tool use"

3. Later, you ask:

   "What did I learn about MCP servers?"

4. Claude queries the knowledge base using qmd MCP tools:

   qmd query --collection <project-name> "MCP servers"