A powerful knowledge management system that allows AI models to store, retrieve, and manage information through the Model Context Protocol (MCP). Think of it as a second brain for your AI assistants! 🤖

Knowledge Vault MCP is a specialized MCP server that provides structured storage and retrieval of knowledge in a format that's easily accessible to both humans and AI models. It serves three key purposes:

1. Personal Context 👤

   • Store personal information and preferences
   • Example: "Users name is Stu Mason, he's 40 years old and lives in Folkestone, UK"
   • Example: "Stu prefers TypeScript over JavaScript for large projects"

2. Project Knowledge 📚

   • Maintain important project-specific information
   • Example: "The auth-service uses JWT tokens with a 24h expiry"
   • Example: "We chose MongoDB over PostgreSQL because of the flexible schema requirements"

3. Current Information 🔄

   • Keep AI models up-to-date with post-training-cutoff information
   • Example: "Lovable.dev is a new AI-powered platform launched in 2024"
   • Example: "Next.js 15 is the latest version and has the following breaking changes:..."

The system organizes information into categories and topics, making it simple to maintain and access a growing knowledge base.

# Clone the repository
git clone https://github.com/stumason/knowledge-vault.git
cd knowledge-vault

# Install dependencies
npm install

# Build the project
npm run build

# Initialize the database
touch knowledge.db
chmod 666 knowledge.db  # Set read/write permissions for the database file

The Knowledge Vault uses SQLite as its database engine, providing a lightweight and reliable storage solution.

If a database file doesn't exist at the specified DB_PATH, before running the server:

1. Create the database file:

   touch knowledge.db

2. Set proper permissions:

   chmod 666 knowledge.db  # Allow read/write access

⚠️ Important: If you don't set the proper permissions, you'll get a "SQLITE_READONLY" error when trying to write to the database.

1. Add the Knowledge Vault to your MCP configuration:

{
  "mcpServers": {
    "knowledge-vault": {
      "command": "node",
      "args": [
        "/path/to/knowledge-vault/build/index.js"
      ],
      "env": {
        "DB_PATH": "/path/to/knowledge-vault/knowledge.db"
      }
    }
  }
}

2. Restart your MCP-enabled application (like Claude Desktop) to load the new configuration.

• Organized Knowledge Structure 📂

  • Category-based organization
  • Topic-based content management
  • Markdown-formatted content support

• Powerful Search Capabilities 🔍

  • Full-text search across all topics
  • Category-specific searches
  • Semantic search support

• Multi-Modal Content Support 📎

  • Attach files to topics (images, PDFs, etc.)
  • Store and manage binary attachments
  • Associate descriptions with attachments
  • Retrieve attachments by filename

• Easy Content Management ✏️

  • Add new topics
  • Update existing content
  • Organize content into categories
  • List all available topics
  • Delete topics permanently (with confirmation)
  • Inactivate/reactivate topics for temporary removal
  • Hide inactive topics by default
  • Option to view both active and inactive topics

• Topic Relationships 🔗

  • Create relationships between topics
  • Define relationship types (e.g., similar, alternative, complements)
  • Specify relationship strengths
  • View related topics and their connections
  • Automatic cross-reference detection in content
  • Support for Markdown links and plain text mentions
  • Intelligent confidence scoring (100% for links, 90% for exact matches, 70% for fuzzy matches)
  • Bidirectional relationship creation with strength degradation

• Version History 📜

  • Track changes to topics over time
  • Record who made each change
  • Store change comments and timestamps
  • View complete version history

• Import/Export 💾

  • Export entire knowledge base or specific categories
  • Support for JSON and Markdown export formats
  • Import from JSON exports
  • Selective import with overwrite control
  • Import content directly from URLs
  • Sync GitHub repository information

• Automated Content Import 🤖

  • Import content from any webpage
  • Extract main content and metadata
  • Clean and format content automatically
  • Sync GitHub repositories with README
  • Track content sources and timestamps

// Search for all AI-related topics
mcp.search("AI tools and frameworks")

// Get detailed information about a specific topic
mcp.lookUp("Next.js 15")

// Create a new topic
mcp.update({
  topic: "Project Guidelines",
  content: "Our development standards and practices..."
})

// Delete a topic (requires confirmation)
mcp.deleteTopic({
  topic: "Outdated Framework",
  confirm: true  // Safety check to prevent accidental deletion
})

// Inactivate a topic (temporary removal)
mcp.toggleTopicStatus({
  topic: "Legacy API",
  setInactive: true
})

// Reactivate a topic
mcp.toggleTopicStatus({
  topic: "Legacy API",
  setInactive: false
})

// List only active topics (default)
mcp.listTopics()

// List all topics including inactive ones
mcp.listTopics({
  includeInactive: true  // Will show "(inactive)" next to inactive topics
})

// Topics with automatic reference detection
mcp.update({
  topic: "Next.js",
  content: "Next.js supports both [TypeScript](/topics/typescript) and JavaScript.\nTypeScript is recommended for large projects.",
  category: "Frameworks"
})
// This will create:
// - 100% confidence reference to TypeScript (from Markdown link)
// - 90% confidence reference to JavaScript (from exact text match)
// - 70% confidence reverse references from both topics

// Disable automatic reference detection
mcp.update({
  topic: "Programming Guide",
  content: "Guide about TypeScript and JavaScript",
  detectReferences: false  // No automatic references will be created
})

// Import content from a webpage
mcp.importFromURL({
  url: "https://developer.mozilla.org/en-US/docs/Web/JavaScript",
  topic: "JavaScript",
  category: "Programming Languages"
})

// Sync GitHub repository information
mcp.syncFromGitHub({
  repo: "vercel/next.js",
  category: "GitHub Projects",
  token: "your-github-token" // Optional, for private repos
})

// Export entire knowledge base to JSON file
mcp.exportVault({
  format: "json",
  exportPath: "/path/to/exports/knowledge.json"
})

// Export specific category to Markdown file
mcp.exportVault({
  format: "markdown",
  category: "Development",
  exportPath: "/path/to/exports/development.md"
})

// Export without saving to file (returns content directly)
mcp.exportVault({
  format: "json"
})

// Import from JSON file
mcp.importVault({
  importPath: "/path/to/exports/knowledge.json",
  format: "json",
  overwrite: false
})

// Import directly from data string
mcp.importVault({
  data: jsonString,
  format: "json",
  overwrite: false
})

// Update a topic with history tracking
mcp.update({
  topic: "Project Conventions",
  category: "Development",
  content: "# Git Commit Standards\n\nWe use conventional commits...",
  user: "stuart",
  comment: "Updated commit standards"
})

// View topic history
mcp.viewHistory({
  topic: "Project Conventions",
  limit: 10  // Show last 10 versions
})

// Add or update a topic
mcp.update({
  topic: "Project Conventions",
  category: "Development",
  content: "# Git Commit Standards\n\nWe use conventional commits..."
})

This Knowledge Vault is built on the Model Context Protocol (MCP), allowing seamless integration with AI models and applications that support the MCP standard. For more information about MCP, see the MCP Specification.

• MCP Client Compatibility 🚫
  • The MCP Client currently only supports text-based content
  • File attachments (getAttachment and getAttachments) will not work through the MCP Client
  • Consider using direct API calls or alternative methods to retrieve attachments
  • Text-based operations (topics, relationships, etc.) work normally

To add a new tool to the Knowledge Vault, follow these steps:

1. Add Database Schema (if needed):

   // In the initializeDb() function:
   await db.exec(`
     CREATE TABLE IF NOT EXISTS your_table (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       // ... other fields
       FOREIGN KEY (...) REFERENCES ... (...)
     );
     
     // Add any necessary indexes
     CREATE INDEX IF NOT EXISTS idx_your_table_field ON your_table (field);
   `);

2. Register the Tool:

   server.tool(
     "toolName",                    // Tool name
     "Tool description...",         // Human-readable description
     {
       // Zod schema for parameters
       param1: z.string().describe("Parameter description"),
       param2: z.number().optional().describe("Optional parameter description")
     },
     async ({ param1, param2 }) => {
       // Tool implementation
       const result = await db.all(`
         SELECT ... FROM ...
         WHERE ... = ?
       `, [param1]);
       
       return {
         content: [{
           type: "text",
           text: `Formatted result...`
         }]
       };
     }
   );

3. Update README:

   • Add tool to Features section
   • Add usage example
   • Update any relevant documentation

1. Database Operations:

   • Use parameterized queries to prevent SQL injection
   • Add appropriate indexes for query performance
   • Handle foreign key relationships properly
   • Consider adding constraints where appropriate

2. Error Handling:

   if (!result) {
     return {
       content: [{ 
         type: "text", 
         text: "Error message" 
       }],
       isError: true
     };
   }

3. Response Formatting:

   • Use markdown for text responses
   • Structure complex data clearly
   • Include relevant metadata
   • Consider adding timestamps for time-sensitive data

4. Parameter Validation:

   • Use Zod schemas for type safety
   • Add descriptive parameter descriptions
   • Make parameters optional when appropriate
   • Set sensible default values

1. Basic functionality:

   // Create/update content
   await toolName({
     param1: "test value",
     param2: 123
   });
   
   // Verify results
   const result = await verificationTool({
     param: "test value"
   });

2. Edge cases to consider:

   • Empty/null values
   • Invalid parameters
   • Missing optional parameters
   • Maximum value sizes
   • Foreign key constraints

When developing or testing new features:

1. Database Creation:

   touch knowledge.db
   chmod 666 knowledge.db

2. Database Reset:

   rm knowledge.db
   touch knowledge.db
   chmod 666 knowledge.db

3. Common Issues:

   • If you get "SQLITE_READONLY" errors, check file permissions
   • Use ls -l knowledge.db to verify permissions
   • The database is automatically initialized with tables on first run

To contribute to the Knowledge Vault:

1. Create new topics with clear, well-structured content
2. Use markdown formatting for consistency
3. Organize content into appropriate categories
4. Include relevant metadata and tags

• Keep topics focused and concise
• Use descriptive titles
• Include examples where relevant
• Update outdated information promptly
• Cross-reference related topics

MIT

If you encounter any issues or have questions, please check the Issues page

Made with ❤️ by Stu Mason and AI.