Personal Knowledge Graph MCP server for maintaining a local, private knowledge graph of decisions, progress, insights, and questions during development
npm install @tomschell/personal-kg-mcpA Model Context Protocol (MCP) server for maintaining a local, private knowledge graph of decisions, progress, insights, and questions during development.
The Personal KG MCP server provides tools to capture, search, and manage knowledge during development work. It focuses on essential functionality to reduce cognitive load while maintaining a comprehensive knowledge base.
But the biggest challenge is agentic development: AI assistants like Claude and Cursor start each session with zero context about your project history, decisions, and progress. Every conversation becomes a ground-up explanation, wasting time and losing valuable context.
For agentic development, it's your AI assistant's memory: The Personal KG gives AI tools like Claude and Cursor instant access to your project context, decisions, and progress history. No more starting from scratch every session.
It's effectively a communications layer between you and your AI assistants, between different development sessions, and between team members. It bridges the gap between human context and AI capabilities.
#### 🧠 Reduced Cognitive Load
- Stop trying to remember everything
- Focus on current work, not context switching
- Quick access to relevant background information
#### 🔄 Seamless Context Switching
- Resume any project with full context
- Understand the "why" behind past decisions
- Pick up where you left off, even months later
- AI assistants start with full project context - No more explaining your codebase from scratch
#### 📈 Accelerated Learning
- Build on past insights and avoid repeating mistakes
- Track your problem-solving patterns
- Identify recurring challenges and solutions
#### 🤝 Better Collaboration
- Share context with team members
- Document decisions for future reference
- Maintain institutional knowledge
- AI-human collaboration - Your AI assistant understands your project as well as you do
- Communications bridge - Seamless information flow between human context and AI capabilities
#### 🎯 Improved Decision Making
- Reference similar past situations
- Understand the full impact of decisions
- Track the evolution of your thinking
Scenario 1: AI Assistant Session Continuity
> "I'm starting a new session with Claude to work on the authentication system. How do I avoid explaining the entire project history again?"
With Personal KG: kg_session_warmup({ project: "auth-system" }) gives your AI assistant instant context about recent decisions, blockers, and progress - no more ground-up explanations.
Scenario 2: Returning to a Project
> "I need to work on the authentication system again, but it's been 3 months. What was I thinking about the OAuth flow?"
With Personal KG: kg_session_warmup({ project: "auth-system" }) gives you recent decisions, blockers, and context in seconds.
Scenario 3: Debugging a Recurring Issue
> "This database connection error feels familiar. Have I seen this before?"
With Personal KG: kg_semantic_search("database connection timeout") finds related debugging sessions and solutions.
Scenario 4: Onboarding a New Developer
> "I need to explain our architecture decisions to the new team member."
With Personal KG: kg_query_context("architecture decisions") provides a comprehensive overview of key decisions and reasoning.
Scenario 5: Planning a Refactor
> "I want to refactor this module, but I need to understand what depends on it."
With Personal KG: kg_get_project_state("module-refactor") shows related work, dependencies, and potential impacts.
The Personal KG integrates seamlessly with your existing development tools:
#### 🔄 Daily Development Cycle
1. Start work → kg_session_warmup() gets you and your AI assistant up to speed
2. During coding → kg_capture() records decisions and progress
3. Link related work → kg_create_edge() connects related concepts
4. End session → kg_capture_session() summarizes and plans next steps
#### 🛠️ Tool Integration
- MCP Protocol - Works with Claude, Cursor, and other AI assistants
- GitHub Integration - Automatically captures issue and PR context
- Local Storage - Your data stays private and under your control
- Search & Discovery - Find relevant information when you need it
- Session Continuity - AI assistants maintain context across sessions
- Communications Layer - Bridges human context and AI capabilities seamlessly
#### 📊 Knowledge Growth
Your Personal KG becomes more valuable over time:
- Week 1: Basic decision tracking
- Month 1: Pattern recognition and context building
- Month 6: Comprehensive project history and insights
- Year 1: Institutional knowledge and learning acceleration
1. Configure MCP Server in .cursor/mcp.json:
``json`
{
"mcpServers": {
"personal-kg-cursor": {
"command": "node",
"args": ["packages/personal-kg-mcp/dist/server.cjs"],
"cwd": "packages/personal-kg-mcp",
"env": {
"PKG_STORAGE_DIR": ".kg",
"PKG_GITHUB_INTEGRATION_ENABLED": "true",
"PKG_MCP_CAPTURE_ENABLED": "true"
}
}
}
}
2. Set up GitHub Integration (optional):
- Create a GitHub Personal Access Token
- Add to .env file: PKG_GITHUB_TOKEN=github_pat_your_token_here
- Or set as environment variable
3. Build the server:
`bash`
cd packages/personal-kg-mcp
npm install
npm run build
Start with these 8 essential tools:
| Purpose | Tool |
|---------|------|
| Health check | kg_health |kg_session_warmup
| Session warmup | |kg_capture
| Capture decisions/progress | |kg_capture_session
| Session summaries | |kg_semantic_search
| Search | |kg_get_project_state
| Project overview | |kg_list_recent
| Recent activity | |kg_create_edge
| Link nodes | |
The Personal KG MCP server is configured through environment variables set in .cursor/mcp.json.
PKG_STORAGE_DIR
- Description: Directory path for Personal KG storage
- Default: .kg"PKG_STORAGE_DIR": "data/knowledge/personal"
- Example:
PKG_GITHUB_INTEGRATION_ENABLED
- Description: Enable/disable GitHub integration in session warmup
- Default: false (disabled by default for security)"true"
- Values: or "false"PKG_GITHUB_TOKEN
- Note: Requires to be set to actually enable
PKG_GITHUB_TOKEN
- Description: GitHub Personal Access Token for Personal KG integration
- Default: Not set
- Security: Store in .env file, not in version control
PKG_MCP_CAPTURE_ENABLED
- Description: Enable/disable automatic capture of MCP tool calls
- Default: true
PKG_MCP_CAPTURE_TOOLS
- Description: Comma-separated list of MCP tool names to capture
- Default: "github""PKG_MCP_CAPTURE_TOOLS": "obsidian,notion,github"
- Example:
PKG_MCP_CAPTURE_EXCLUDE
- Description: Comma-separated list of MCP tool names to exclude
- Default: "" (empty)
PKG_MCP_CAPTURE_AUTO
- Description: Enable automatic capture without explicit calls
- Default: "true"
`json`
{
"mcpServers": {
"personal-kg-cursor": {
"command": "node",
"args": ["packages/personal-kg-mcp/dist/server.cjs"],
"cwd": "packages/personal-kg-mcp",
"env": {
"PKG_STORAGE_DIR": ".kg",
"PKG_AUTO_BACKUP_MINUTES": "0",
"PKG_USE_ANN": "true",
"PKG_GITHUB_INTEGRATION_ENABLED": "true",
"PKG_MCP_CAPTURE_ENABLED": "true",
"PKG_MCP_CAPTURE_TOOLS": "github",
"PKG_MCP_CAPTURE_EXCLUDE": "",
"PKG_MCP_CAPTURE_AUTO": "true"
}
}
}
}
, ws:, ticket:
- Examples: proj:kg ws:kg-dev ticket:78$3
1. Capture key moments with kg_capture (decisions, progress, insights, questions).
2. At session boundaries use kg_capture_session (include next_actions[]).
3. When resuming a topic call kg_query_context or kg_get_project_state.
4. Link entries to the active session and mark dependencies with kg_create_edge.$3
#### Health
| Tool | Purpose |
|------|---------|
| kg_health | Confirm MCP server availability |
#### Capture
| Tool | Args (required bold) | Notes |
|------|--------------------------|-------|
| kg_capture | content, type∈idea\|decision\|progress\|insight\|question, tags?, visibility?, includeGit?, importance∈high\|medium\|low, auto_link?, sessionId?, project?, workstream?, ticket? | Primary knowledge creation |
| kg_capture_session | summary, duration?, artifacts?, next_actions[], visibility?, importance? | Session summaries |
#### Relationships
| Tool | Args | Notes |
|------|------|-------|
| kg_create_edge | fromNodeId, toNodeId, relation∈references\|relates_to\|derived_from\|blocks\|duplicates | Single relationship creation |
| kg_list_edges | nodeId? | |
| kg_link_session | sessionId, nodeId | Link a session to a node (session → node, references) |
#### Search & Retrieval
| Tool | Args | Notes |
|------|------|-------|
| kg_semantic_search | query, limit? | Vector similarity |
| kg_search | query?, tags?, type?, limit?, format?, includeContent?, includeTags?, includeMetadata?, summaryLength? | Keyword/tag search with optional formatting |
| kg_list_recent | limit, format?, summaryLength? | Recent activity |
| kg_get_node | id | |
| kg_query_context | topic | Summarise topic-relevant nodes |
| kg_get_project_state | project, includeRecent? | Overview, blockers, recent etc. |
| kg_session_warmup | project, limit? | Session context warmup |
| kg_find_similar | nodeId, limit? | Find similar nodes |
#### Maintenance & Data
| Tool | Args | Notes |
|------|------|-------|
| kg_relationships_maintenance | rebuildThreshold?, pruneThreshold?, limit? | Rebuild + prune relationships |
| kg_validate | | Structural check |
| kg_repair | | Auto-fix minor issues |
| kg_backup | retentionDays? | Zip export w/ retention policy |
| kg_export / kg_import | (payload) | Full JSON export / import |
| kg_graph_export | | Mermaid-compatible graph |
$3
| Relation | When to use | Example |
|----------|-------------|---------|
| references | Loose citation / mention | Session note references design doc |
| relates_to | General topical overlap | Two progress nodes on same feature |
| derived_from | Work or idea builds on another | Refactor derived_from original design decision |
| blocks | Hard dependency ordering | Bug fix blocks release task |
| duplicates | Identical or redundant content | Duplicate question captured twice |$3
1. Start / resume → kg_health, then kg_session_warmup({ project: "kg", limit: 20 })
2. Before starting work → kg_query_context to get relevant background
3. During dev → kg_capture with sessionId + tags
4. Link related work → kg_create_edge (relation="blocks" or "derived_from")
5. End session → kg_capture_session, then kg_relationships_maintenance$3
#### Session Warmup
`json
{
"tool": "kg_session_warmup",
"args": { "project": "kg", "limit": 20 }
}
`#### Capture Progress
`json
{
"tool": "kg_capture",
"args": {
"content": "Progress: added query tools for Issue 64",
"type": "progress",
"sessionId": "",
"tags": ["proj:kg", "ws:kg-dev", "ticket:64"],
"importance": "medium"
}
}
`#### Session Summary
`json
{
"tool": "kg_capture_session",
"args": {
"summary": "Completed KG tool analysis and documentation updates",
"next_actions": ["Implement simplified system prompt", "Update .cursorrules"],
"artifacts": ["Issue #215", "Updated documentation"]
}
}
`#### Link Related Work
`json
{
"tool": "kg_create_edge",
"args": {
"fromNodeId": "",
"toNodeId": "",
"relation": "blocks"
}
}
`#### Get Context Before Starting
`json
{
"tool": "kg_query_context",
"args": { "topic": "CI/CD pipeline improvements" }
}
`Advanced Tools (Reference Only)
These tools are available but rarely needed:
-
kg_find_connection_path - Find relationship path between nodes
- kg_detect_topic_clusters - Discover clusters/themes
- kg_find_emerging_concepts - Detect new concepts over time
- kg_query_time_range - Time-window queries
- kg_delete_node - Delete nodes with edge cleanupDeprecated Tools (Avoid)
These tools will be removed in future releases:
-
kg_mark_blocks, kg_mark_blocked_by, kg_mark_derived_from, kg_mark_affects - Use kg_create_edge instead
- kg_rebuild_relationships, kg_prune_weak_relationships - Use kg_relationships_maintenance instead
- capture_context, capture_session - Use kg_capture, kg_capture_session instead
- kg_search_minimal - Use kg_search or kg_semantic_search instead
- kg_query_context_expanded - Use kg_query_context instead
- kg_reclassify_relationships - Use kg_relationships_maintenance insteadDevelopment
$3
`bash
cd packages/personal-kg-mcp
npm install
npm run build
`$3
`bash
npm test
npm run test:unit
npm test -- config.test.ts --run
`$3
`bash
npm run dev
``MIT License - see LICENSE file for details.