ClawVault MCP Server 🐘

An elephant never forgets. Now your AI agent won't either.

MCP (Model Context Protocol) server that gives Claude Desktop, Cursor, and other MCP-compatible tools access to the ClawVault memory system.

Features

• 🔍 Semantic Search — Find memories using natural language queries via qmd
• 📝 Store Memories — Create structured notes in preferences, decisions, patterns, people, projects, goals, transcripts, or inbox
• 🔗 Wiki-Links — Track connections between memories using [[double-bracket]] links
• 📊 Connection Analysis — See your most-connected knowledge nodes and orphan files
• 🗂️ Browse — List and read memories by category

Installation

cd ~/clawd/projects/clawvault-mcp
npm install

Prerequisites

1. ClawVault structure — Set up the vault directories:

   mkdir -p ~/clawd/clawvault/{preferences,decisions,patterns,people,projects,goals,transcripts,inbox}

2. qmd (recommended for semantic search):

   # Install qmd if not already present
   cargo install qmd
   
   # Set up the ClawVault collection
   qmd collection add ~/clawd/clawvault --name clawvault --mask "**/*.md"

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "clawvault": {
      "command": "node",
      "args": ["/path/to/clawvault-mcp/index.js"],
      "env": {
        "CLAWVAULT_PATH": "/path/to/your/clawvault"
      }
    }
  }
}

Example (Linux/WSL):

{
  "mcpServers": {
    "clawvault": {
      "command": "node",
      "args": ["/home/frame/clawd/projects/clawvault-mcp/index.js"],
      "env": {
        "CLAWVAULT_PATH": "/home/frame/clawd/clawvault"
      }
    }
  }
}

Cursor

Add to your Cursor settings under MCP servers with the same configuration.

Environment Variables

Variable	Description	Default
CLAWVAULT_PATH	Path to your ClawVault directory	~/clawd/clawvault

Tools

clawvault_search

Search your memories using natural language.

Search: "What does Pedro prefer for communication?"
→ Returns relevant snippets from preferences, patterns, people files

clawvault_store

Store a new memory in the vault.

Category: decisions
Title: Switch to WAL Protocol  
Content: |
  # Decision: Switch to WAL Protocol
  
  **Date:** 2026-01-30
  **Context:** Kept forgetting things after context compression
  **Decision:** Implement write-ahead logging
  **Reasoning:** Can't rely on remembering to remember
  
  Related: [[projects/memory-system]], [[patterns/context-loss]]

clawvault_read

Read a specific memory file.

Path: people/pedro.md
→ Returns content + extracted wiki-links

clawvault_list

List memories, optionally filtered by category.

Category: decisions
→ Returns all decision files with paths and modification dates

clawvault_connections

Analyze the knowledge graph.

→ Returns:
  - Most connected nodes (hub files)
  - Orphan files (no connections)
  - Total link statistics

ClawVault Structure

~/clawd/clawvault/
├── preferences/     # What your human likes/dislikes
├── decisions/       # Choices with context + reasoning
├── patterns/        # Recurring behaviors observed
├── people/          # One file per person (wiki-linked)
├── projects/        # Active projects and ventures
├── goals/           # Long-term and short-term goals
├── transcripts/     # Session summaries
└── inbox/           # Quick capture → process later

Wiki-Links

Use [[double-brackets]] to create connections:

# Decision: Pause Site Machine

[[people/pedro]] decided to deprioritize [[projects/site-machine]].
This affects [[people/forge]] who was running outreach.

These links create a knowledge graph you can explore with clawvault_connections.

Testing

# Test the server directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node index.js

# Or run the test script
npm test

Development

# Run with debug output
DEBUG=mcp node index.js

# Check if qmd is working
qmd search "test query" -c clawvault

Troubleshooting

"ClawVault collection not found"

Run: qmd collection add ~/clawd/clawvault --name clawvault --mask "**/*.md"

Search returns empty results

1. Make sure you have .md files in your vault
2. Run qmd update to refresh the index
3. Try a simpler search term

Permission denied

Make sure index.js is executable: chmod +x index.js

License

MIT

---

"An elephant never forgets." — ClawVault 🐘