@adarsh6938/mcp-knowledge-graph-semantic v1.1.0

Personal Knowledge Graph with Semantic Search

A powerful MCP (Model Context Protocol) server that provides persistent memory using a local knowledge graph with semantic search capabilities. Built for personal use with Claude/Cursor to maintain context across conversations.

Features

🧠 Persistent Memory: Store and retrieve information across chat sessions
🔍 Semantic Search: Find relevant information based on meaning, not just keywords
🔗 Knowledge Graph: Entities and relationships for structured knowledge storage
📄 Pagination: Handle large datasets without response size limits
🚀 Local & Private: All data stays on your machine
💰 Cost-Free: Uses open-source Transformers.js models (no API costs)

Quick Start

Installation

npm install -g @adarsh6938/mcp-knowledge-graph-semantic

Configuration

Add to your .cursor/mcp.json or claude_desktop_config.json:

{
  "mcpServers": {
    "knowledge-graph-semantic": {
      "command": "npx",
      "args": [
        "-y",
        "@adarsh6938/mcp-knowledge-graph-semantic",
        "--memory-path",
        "/path/to/your/memory.jsonl"
      ]
    }
  }
}

Core Concepts

Entities

Primary nodes in your knowledge graph:

{
  "name": "John_Doe",
  "entityType": "person",
  "observations": [
    "Software engineer specializing in contract testing",
    "Uses TypeScript and Java for development",
    "Prefers systematic debugging over trial-and-error"
  ]
}

Relations

Connections between entities:

{
  "from": "John_Doe",
  "to": "Alpha_workspace",
  "relationType": "works_in"
}

Semantic Search

Find information by meaning:

• Query: "debugging contract tests"
• Finds: Entities related to troubleshooting, testing, and development

Available Tools

Core Operations

• create_entities - Add new entities to the graph
• create_relations - Connect entities with relationships
• add_observations - Add facts to existing entities
• delete_entities - Remove entities and their connections
• delete_observations - Remove specific facts
• delete_relations - Remove connections

Reading & Search

• read_graph - Get limited view (first 5 entities)
• read_graph_paginated - Browse large datasets with pagination
• search_nodes - Keyword-based search
• semantic_search - AI-powered semantic search
• hybrid_search - Combined keyword + semantic search
• open_nodes - Get specific entities by name

Maintenance

• rebuild_semantic_index - Refresh semantic search index
• update_entities - Modify existing entities
• update_relations - Modify existing relationships

Semantic Search Examples

// Find contract testing information
semantic_search("debugging test failures")

// Find people and relationships
semantic_search("software engineers working on APIs")

// Hybrid search for best results
hybrid_search("JSON parsing OpenAPI validation")

Pagination Example

// Browse large knowledge graphs
read_graph_paginated({ page: 0, pageSize: 10 })
// Returns: entities, relations, and pagination metadata

Technical Details

• Storage: JSONL format for entities/relations
• Embeddings: Transformers.js with all-MiniLM-L6-v2 model
• Search: Cosine similarity with configurable thresholds
• Memory: Automatic indexing when entities are created/modified

Use Cases

• Personal Assistant: Remember preferences, goals, and context
• Project Memory: Track technical decisions and implementations
• Learning: Store and connect knowledge across domains
• Development: Maintain context about codebases and architectures

Configuration Options

Memory Path

"args": ["--memory-path", "/Users/you/projects/memory.jsonl"]

Multiple Projects

Use different memory files for different contexts:

// Work project
"--memory-path", "/Users/you/work/work-memory.jsonl"

// Personal project  
"--memory-path", "/Users/you/personal/personal-memory.jsonl"

System Prompt Recommendation

Add this to your Claude/Cursor configuration:

Follow these steps for each interaction:

1. User Identification:
   - Assume you are interacting with the default_user
   - Proactively identify the user if not already known

2. Memory Retrieval:
   - Begin by saying "Remembering..." and retrieve relevant information
   - Use semantic_search for context-aware information retrieval

3. Memory Updates:
   - Store new information about:
     * Identity (role, expertise, preferences)
     * Behaviors (habits, patterns, approaches)
     * Goals (objectives, targets, aspirations)
     * Relationships (professional and personal connections)
     * Technical knowledge (implementations, decisions, learnings)

4. Knowledge Management:
   - Create entities for people, projects, and concepts
   - Connect related information with meaningful relationships
   - Use observations to store specific facts and insights

Privacy & Security

• ✅ All data stored locally on your machine
• ✅ No external API calls for embeddings
• ✅ No data sent to third-party services
• ✅ Full control over your knowledge graph

License

MIT License - Feel free to use, modify, and distribute.

This knowledge graph helps maintain context and memory across AI conversations, making interactions more personalized and effective.