tenorok/mind-vault

Mind Vault

AI-powered knowledge base with MCP server for markdown files. Automatically indexes and searches through your markdown documentation using semantic search.

Features

• 🔍 Semantic Search - Find relevant information using natural language queries
• 📁 Automatic File Watching - Automatically reindexes files when they change
• 🚀 MCP Integration - Works seamlessly with AI assistants via Model Context Protocol
• 📝 Markdown Focus - Optimized for markdown documentation
• 🔄 Real-time Updates - Changes are detected and indexed automatically
• 💾 Persistent Storage - Vector index is saved and reloaded between sessions

Prerequisites

• Node.js 22.15.0
• NPM 10.9.0

Installation

1. Clone or download this project
2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Mind Vault is configured via environment variables:

Required

• MEMORY_BANK_PATH - Path to your markdown files directory

Optional

• PROJECT_NAME - Custom project name for the MCP server (default: extracted from path)
• WATCH_PATTERNS - Comma-separated file patterns to watch (default: **/*.md)
• DEBOUNCE_DELAY - File change debounce delay in ms (default: 1000)
• BATCH_DELAY - Batch processing delay in ms (default: 2000)
• MAX_RESULTS - Maximum search results to return (default: 10)

Usage

Basic Usage

MEMORY_BANK_PATH="/path/to/your/markdown/files" npm start

Advanced Usage

MEMORY_BANK_PATH="/path/to/project/memory-bank" \
PROJECT_NAME="my-project" \
WATCH_PATTERNS="**/*.md,**/*.mdx" \
MAX_RESULTS="15" \
npm start

Development Mode

MEMORY_BANK_PATH="/path/to/your/markdown/files" npm run dev

MCP Server Integration

Mind Vault runs as an MCP server that provides the following tools:

search_knowledge

Search through your knowledge base using semantic search.

Parameters:

• query (required): The search query
• limit (optional): Maximum number of results (1-20, default: 5)

Example:

{
    "query": "How to configure React hooks?",
    "limit": 10
}

manual_reindex

Manually reindex files or the entire knowledge base.

Parameters:

• path (optional): Specific file path to reindex. If not provided, reindexes all files.

Example:

{
    "path": "/path/to/specific/file.md"
}

get_index_status

Get information about the current state of the knowledge base.

Parameters: None

Multiple Projects

You can run multiple Mind Vault servers for different projects simultaneously. Each server will have a unique name based on the project:

Project 1

MEMORY_BANK_PATH="/path/to/project1/memory-bank" \
PROJECT_NAME="project1" \
npm start

Project 2 (in another terminal)

MEMORY_BANK_PATH="/path/to/project2/memory-bank" \
PROJECT_NAME="project2" \
npm start

The AI assistant will see these as separate MCP servers:

• mind-vault-project1
• mind-vault-project2

File Structure

mind-vault/
├── src/
│   ├── config/           # Configuration management
│   ├── indexer/          # Markdown processing and vector indexing
│   ├── search/           # Search functionality
│   ├── mcp-server/       # MCP server implementation
│   ├── file-watcher/     # File watching and batch processing
│   ├── utils/            # Utility functions
│   └── main.ts           # Application entry point
├── data/                 # Vector indexes (created automatically)
├── dist/                 # Compiled JavaScript (after build)
└── package.json

How It Works

1. Initialization: Mind Vault scans your markdown directory and creates a vector index
2. File Watching: Monitors file changes and automatically reindexes modified files
3. Chunking: Large markdown files are split into semantic chunks for better search
4. Vector Search: Uses LlamaIndex with default embeddings for semantic search
5. MCP Integration: Exposes search functionality via Model Context Protocol

Troubleshooting

Common Issues

"Memory bank directory not found"

• Ensure the MEMORY_BANK_PATH points to an existing directory
• Use absolute paths to avoid confusion

"No markdown files found"

• Check that your directory contains .md files
• Verify the WATCH_PATTERNS includes the correct file extensions

Debug Mode

Run with additional logging:

DEBUG=* MEMORY_BANK_PATH="/path/to/files" npm run dev

Cleaning Up

Remove generated files:

npm run clean

Performance Tips

• Large repositories: Consider using more specific WATCH_PATTERNS to exclude unnecessary files
• Frequent changes: Increase DEBOUNCE_DELAY and BATCH_DELAY for better performance
• Memory usage: The vector index is loaded into memory - consider splitting very large document sets

Development

Building

npm run build

Type Checking

npm run type-check

Testing

npm run build && MEMORY_BANK_PATH="./test-memory-bank" npx @modelcontextprotocol/inspector node dist/main.js

Architecture

Mind Vault follows a modular architecture:

• Config: Environment-based configuration with validation
• Indexer: Markdown processing using LlamaIndex's MarkdownNodeParser
• Vector Store: Persistent vector index with automatic loading/saving
• File Watcher: Debounced file monitoring with batch processing
• MCP Server: Standard MCP implementation with tool handlers