@adarsh6938/mcp-knowledge-graph-semantic/README.md

Private MCP Server for semantic knowledge graph with persistent memory

# 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

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

### Configuration

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

```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:
```json
{
  "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:
```json
{
  "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

```javascript
// 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

```javascript
// 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
```json
"args": ["--memory-path", "/Users/you/projects/memory.jsonl"]
```

### Multiple Projects
Use different memory files for different contexts:
```json
// 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.*