Skip to main content
Glama
henrychong-ai

Neo4j Knowledge Graph MCP Server

by henrychong-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Quick Start

Get up and running in ~10 minutes:

  1. Install Node.js (v24+) and start Neo4j (Docker or Desktop)

  2. Configure your MCP client (Claude Desktop, Claude Code, Cursor, etc.)

  3. Test the setup by creating your first entity

Sections:

Related MCP server: Graphiti MCP Server

Installation

Global Installation with npx (Recommended)

You can run this Neo4j Knowledge Graph MCP server directly using npx:

npx @henrychong-ai/mcp-neo4j-knowledge-graph

This method is recommended for use with Claude Desktop and other MCP-compatible clients.

npm Installation

For local use or development:

# Install the package
pnpm install -g @henrychong-ai/mcp-neo4j-knowledge-graph

# Or use locally in your project
pnpm install @henrychong-ai/mcp-neo4j-knowledge-graph

Note: This package is maintained in a private GitHub repository but published publicly to npm. The compiled code, documentation, and full functionality are available through npm installation.

Core Concepts

Entities

Entities are the primary nodes in the knowledge graph. Each entity has:

  • A unique name (identifier)

  • An entity type (e.g., "person", "organization", "event")

  • A list of observations

  • Vector embeddings (for semantic search)

  • Complete version history

Example:

{
  "name": "John_Smith",
  "entityType": "person",
  "observations": ["Speaks fluent Spanish"]
}

EntityType Convention: Use lowercase-kebab-case for entityType values (e.g., person, medical-condition, claude-code-skill). Avoid uppercase, spaces, or underscores.

Relations

Relations define directed connections between entities with enhanced properties:

  • Strength indicators (0.0-1.0)

  • Confidence levels (0.0-1.0)

  • Rich metadata (source, timestamps, tags)

  • Temporal awareness with version history

  • Time-based confidence decay

Example:

{
  "from": "John_Smith",
  "to": "Anthropic",
  "relationType": "works_at",
  "strength": 0.9,
  "confidence": 0.95,
  "metadata": {
    "source": "linkedin_profile",
    "last_verified": "2025-03-21"
  }
}

Storage Backend

This MCP server uses Neo4j as its storage backend, providing a unified solution for both graph storage and vector search capabilities.

Why Neo4j?

  • Unified Storage: Consolidates both graph and vector storage into a single database

  • Native Graph Operations: Built specifically for graph traversal and queries

  • Integrated Vector Search: Vector similarity search for embeddings built directly into Neo4j

  • Scalability: Better performance with large knowledge graphs

  • Simplified Architecture: Clean design with a single database for all operations

Prerequisites

  • Neo4j 5.13+ (required for vector search capabilities)

Neo4j Desktop Setup (Recommended)

The easiest way to get started with Neo4j is to use Neo4j Desktop:

  1. Download and install Neo4j Desktop from https://neo4j.com/download/

  2. Create a new project

  3. Add a new database

  4. Set password to memento_password (or your preferred password)

  5. Start the database

The Neo4j database will be available at:

  • Bolt URI: bolt://127.0.0.1:7687 (for driver connections)

  • HTTP: http://127.0.0.1:7474 (for Neo4j Browser UI)

  • Default credentials: username: neo4j, password: your_password (or whatever you configured)

Neo4j Setup with Docker (Alternative)

Alternatively, you can use Docker to run Neo4j:

# Start Neo4j container
docker run -d \
  --name neo4j-kg \
  --restart unless-stopped \
  -p 7474:7474 \
  -p 7687:7687 \
  -v neo4j-kg_data:/data \
  -v neo4j-kg_logs:/logs \
  -e NEO4J_AUTH=neo4j/your_password \
  neo4j:5.26-community

# Stop Neo4j container
docker stop neo4j-kg

# Start existing container
docker start neo4j-kg

# Remove Neo4j container (preserves data in volumes)
docker rm neo4j-kg

When using Docker, the Neo4j database will be available at:

  • Bolt URI: bolt://127.0.0.1:7687 (for driver connections)

  • HTTP: http://127.0.0.1:7474 (for Neo4j Browser UI)

  • Default credentials: username: neo4j, password: your_password

Data Persistence and Management

Neo4j data persists across container restarts and even version upgrades due to Docker named volumes:

  • neo4j-kg_data - Database files

  • neo4j-kg_logs - Log files

To backup your data:

# Create a backup of the data volume
docker run --rm -v neo4j-kg_data:/data -v $(pwd):/backup alpine tar czf /backup/neo4j-backup-$(date +%Y%m%d).tar.gz -C /data .

To restore from backup:

# Restore data from backup
docker run --rm -v neo4j-kg_data:/data -v $(pwd):/backup alpine tar xzf /backup/neo4j-backup-YYYYMMDD.tar.gz -C /data
Upgrading Neo4j Version

For comprehensive Neo4j upgrade procedures, see docs/UPGRADE.md.

This guide covers:

  • When and why to upgrade (LTS vs Latest)

  • Complete 5-phase upgrade procedure with go/no-go checkpoints

  • Configuration management (deprecated settings)

  • Troubleshooting and rollback procedures

  • Real-world upgrade examples with verified commands

  • 48-hour monitoring schedule

Quick Reference for Docker:

# Basic upgrade (for development/testing)
1. Stop current container: docker stop neo4j-kg
2. Remove container: docker rm neo4j-kg
3. Start new version: docker run -d --name neo4j-kg ... neo4j:5.XX-community
4. Reinitialize schema: pnpm run neo4j:init

Production Warning: For production deployments with valuable data, always follow the complete procedure in docs/UPGRADE.md, which includes backup verification, data integrity checks, and rollback procedures.

Complete Database Reset

If you need to completely reset your Neo4j database:

# Stop and remove the container
docker stop neo4j-kg
docker rm neo4j-kg

# Remove the data volume
docker volume rm neo4j-kg_data

# Restart with fresh container
docker run -d \
  --name neo4j-kg \
  --restart unless-stopped \
  -p 7474:7474 \
  -p 7687:7687 \
  -v neo4j-kg_data:/data \
  -v neo4j-kg_logs:/logs \
  -e NEO4J_AUTH=neo4j/your_password \
  neo4j:5.26-community

# Reinitialize the schema
pnpm run neo4j:init

Neo4j CLI Utilities

This MCP server includes command-line utilities for managing Neo4j operations:

Testing Connection

Test the connection to your Neo4j database:

# Test with default settings
pnpm run neo4j:test

# Test with custom settings
pnpm run neo4j:test -- --uri bolt://127.0.0.1:7687 --username myuser --password mypass --database neo4j

Initializing Schema

For normal operation, Neo4j schema initialization happens automatically when the MCP server connects to the database. You don't need to run any manual commands for regular usage.

The following commands are only necessary for development, testing, or advanced customization scenarios:

# Initialize with default settings (only needed for development or troubleshooting)
pnpm run neo4j:init

# Initialize with custom vector dimensions
pnpm run neo4j:init -- --dimensions 768 --similarity euclidean

# Force recreation of all constraints and indexes
pnpm run neo4j:init -- --recreate

# Combine multiple options
pnpm run neo4j:init -- --vector-index custom_index --dimensions 384 --recreate

Advanced Features

Semantic Search

Find semantically related entities based on meaning rather than just keywords:

  • Vector Embeddings: Entities are automatically encoded into high-dimensional vector space using OpenAI's embedding models

  • Cosine Similarity: Find related concepts even when they use different terminology

  • Configurable Thresholds: Set minimum similarity scores to control result relevance

  • Cross-Modal Search: Query with text to find relevant entities regardless of how they were described

  • Multi-Model Support: Compatible with multiple embedding models (OpenAI text-embedding-3-small/large)

  • Contextual Retrieval: Retrieve information based on semantic meaning rather than exact keyword matches

  • Optimized Defaults: Tuned parameters for balance between precision and recall (0.6 similarity threshold, hybrid search enabled)

  • Hybrid Search: Combines semantic and keyword search for more comprehensive results

  • Adaptive Search: System intelligently chooses between vector-only, keyword-only, or hybrid search based on query characteristics and available data

  • Performance Optimization: Prioritizes vector search for semantic understanding while maintaining fallback mechanisms for resilience

  • Query-Aware Processing: Adjusts search strategy based on query complexity and available entity embeddings

Temporal Awareness

Track complete history of entities and relations with point-in-time graph retrieval:

  • Full Version History: Every change to an entity or relation is preserved with timestamps

  • Point-in-Time Queries: Retrieve the exact state of the knowledge graph at any moment in the past

  • Change Tracking: Automatically records createdAt, updatedAt, validFrom, and validTo timestamps

  • Temporal Consistency: Maintain a historically accurate view of how knowledge evolved

  • Non-Destructive Updates: Updates create new versions rather than overwriting existing data

  • Time-Based Filtering: Filter graph elements based on temporal criteria

  • History Exploration: Investigate how specific information changed over time

Confidence Decay

Relations automatically decay in confidence over time based on configurable half-life:

  • Time-Based Decay: Confidence in relations naturally decreases over time if not reinforced

  • Configurable Half-Life: Define how quickly information becomes less certain (default: 30 days)

  • Minimum Confidence Floors: Set thresholds to prevent over-decay of important information

  • Decay Metadata: Each relation includes detailed decay calculation information

  • Non-Destructive: Original confidence values are preserved alongside decayed values

  • Reinforcement Learning: Relations regain confidence when reinforced by new observations

  • Reference Time Flexibility: Calculate decay based on arbitrary reference times for historical analysis

Advanced Metadata

Rich metadata support for both entities and relations with custom fields:

  • Source Tracking: Record where information originated (user input, analysis, external sources)

  • Confidence Levels: Assign confidence scores (0.0-1.0) to relations based on certainty

  • Relation Strength: Indicate importance or strength of relationships (0.0-1.0)

  • Temporal Metadata: Track when information was added, modified, or verified

  • Custom Tags: Add arbitrary tags for classification and filtering

  • Structured Data: Store complex structured data within metadata fields

  • Query Support: Search and filter based on metadata properties

  • Extensible Schema: Add custom fields as needed without modifying the core data model

Batch Operations

Optimized bulk operations providing 10-50x performance improvement over individual operations:

  • High-Performance Bulk Processing: Batch operations use Neo4j's UNWIND clause for dramatic performance gains

  • Automatic Chunking: Large batches are automatically split into optimal chunk sizes (default: 100 items)

  • Parallel Processing: Independent operations (like embedding generation) can run concurrently

  • Progress Tracking: Optional callbacks provide real-time progress updates for long-running operations

  • Partial Failure Handling: Continue processing on failures with detailed error reports per item

  • Performance Metrics: Each batch operation returns total time and per-item average timing

  • Transaction Safety: Automatic rollback on failures ensures data consistency

Available Batch Tools:

  • create_entities_batch: Create multiple entities in single operation

  • create_relations_batch: Create multiple relations in single operation

  • add_observations_batch: Add observations to multiple entities in single operation

  • update_entities_batch: Update multiple entities in single operation

Performance Comparison:

// Individual operations: ~50 seconds for 100 entities
for (const entity of entities) {
  await createEntities([entity]);
}

// Batch operation: ~1.5 seconds for 100 entities (33x faster)
await createEntitiesBatch(entities, {
  maxBatchSize: 100,
  enableParallel: true,
});

Configuration Options:

  • maxBatchSize: Control chunk size (default: 100)

  • enableParallel: Reserved for future parallel chunk processing (embeddings always generated if service available)

  • onProgress: Callback for progress tracking

Cost Management:

  • Incremental approach minimizes API calls

  • Only processes entities without embeddings

  • Typical cost: ~$0.02 per 1M tokens

  • Production cost: ~$0.0025 per daily run (for typical workloads)

This automation ensures semantic search remains highly effective as your knowledge graph grows, without requiring manual embedding regeneration.

Query Result Caching (v1.5.0+)

Semantic search queries are automatically cached for improved performance:

Cache Configuration:

  • LRU (Least Recently Used) Strategy: Automatically evicts oldest entries when full

  • Capacity: 500 unique queries cached simultaneously

  • TTL (Time-To-Live): 5 minutes per cache entry

  • Size Limit: 10,000 entities maximum across all cached results

  • Size Calculation: Entity count + relation count

Cache Behavior:

  • Cache Hits: Sub-millisecond response for repeated queries

  • Automatic Invalidation: Cache cleared on mutations (create_entities, add_observations, delete_entities, etc.)

  • Intelligent Keying: Considers query text, limit, similarity threshold, entity types, and hybrid config

  • Metrics Integration: Cache hits/misses tracked via Prometheus (when enabled)

Performance Impact:

  • First Query: Normal latency (~100-500ms depending on graph size)

  • Cached Query: <1ms response time

  • Memory Usage: Minimal - automatically bounded by size limits

  • Cache Miss Rate: Typically <10% for conversational workloads

Example Scenarios:

  • User asks "What programming languages do you know?" → Cache miss (~300ms)

  • User asks "What programming languages do you know?" again → Cache hit (<1ms)

  • User creates new entity → Cache cleared for consistency

  • User asks "What programming languages do you know?" → Cache miss (~300ms, fresh results)

This caching layer provides significant performance improvements for repeated or similar queries without any configuration needed.

Oversized-entity flagging (v2.8.0+)

open_nodes returns pretty-printed JSON, and the MCP client/harness caps a tool response at MAX_MCP_OUTPUT_TOKENS (default 25,000 tokens). If a single entity's own serialized form grows past that cap, open_nodes(["Name"]) fails closed — the entity can no longer be fetched or deduped by exact name. This feature flags entities approaching the cap so you can restructure them first.

How size is estimated. Per entity, the server measures the characters of the entity as open_nodes actually serializes it — nested in the { entities: [ … ] } response envelope with its temporal/identity fields, but without the embedding vector (which open_nodes does not return), so observations dominate — and estimates tokens at chars / 2.8. That divisor is calibrated against the documented failure (an entity at ~73k serialized chars that exceeded the 25k-token cap ⇒ <2.93 chars/token for dense technical/JSON content) and deliberately errs toward over-estimating tokens: a false WARN is cheap, a missed over-cap entity is the catastrophe the feature prevents. Combined with a sub-1.0 warn ratio it is a conservative early warning, not a reproduction of the harness tokenizer. Three states: OK (< warn_ratio), WARN (warn_ratio–critical_ratio: restructure soon), CRITICAL (>= critical_ratio: at/over the cap — split now).

Three ways you find out:

  1. On demand — flag_oversized_entities tool. Returns a ranked, size-only list (never full entity bodies, so the scan can't itself breach the cap). The ranking is computed in the storage layer; the largest candidates are then sized precisely.

  2. At the moment of growth — write warnings. When create_entities_batch, add_observations_batch, or update_entities_batch push a touched entity into WARN/CRITICAL, the result gains an additive, non-fatal warnings[] field naming it. Strictly fail-open (never blocks or fails the write); disable with ENTITY_SIZE_WARN_ON_WRITE=false.

  3. On an ongoing basis — the CLI + a cron. Run a recurring digest:

    pnpm run kg:oversized                 # table of WARN/CRITICAL entities
pnpm run kg:oversized -- --include-ok # include OK entities too
pnpm run kg:oversized:json            # machine-readable JSON
pnpm run kg:oversized -- --limit 100  # scan the 100 largest

    The CLI exits non-zero when any CRITICAL entity exists, so a weekly cron (alongside the embedding backfill) can alert. Sizing is pure Cypher — no embedding provider is needed.

Restructuring stays a judgement call (the tool informs, it does not auto-split): group an oversized entity's observations by theme into new, more specific sibling entities, then link them with create_relations. Dedup with open_nodes before creating. A CRITICAL entity may already be unretrievable whole — split it from its source before it grows further.

Thresholds and scan size are configurable via the MAX_MCP_OUTPUT_TOKENS / ENTITY_SIZE_* environment variables (see Configuration).

Versioning safety & graph repair (v2.9.0+)

Every write path that supersedes an existing entity version — add_observations, add_observations_batch, delete_observations, update_entities_batch, and the upsert case of create_entities / create_entities_batch — goes through one shared versioning helper. It closes every live version of the name, creates the new version, and copies the old version's live relationships onto it with MERGE (newE)-[r:RELATES_TO {id: rel.id}]->(to), resolved against the counterpart's single newest live version.

Before v2.9.0 each path carried its own copy of that logic and they disagreed, which corrupted graphs in two ways:

  • Duplicated relationships. Relationship copies used CREATE, once as the source's outgoing edge and once as the target's incoming edge. Any batch holding both endpoints of a relationship therefore copied it twice, and the count doubled again on every subsequent joint batch. One production node reached 39,382 physical live relationships for 15 logical ones, after which every write exhausted db.memory.transaction.max (512 MiB).

  • Multiple live versions and stranded edges. Some paths opened a new live version without closing the previous one — the composite (name, validTo) constraint does not catch this, because Neo4j exempts rows with a NULL in the constrained property set — and delete_observations versioned the node without closing or copying its relationships at all. 48 names ended up with more than one live version and 358 live relationships were left attached to stale versions.

Two guards now bound the damage, both configurable (see Environment Variables):

Variable

Default

What it does

NEO4J_TX_TIMEOUT_MS

60000

Transaction timeout on every transaction and auto-commit query

NEO4J_MAX_LIVE_RELATIONSHIPS

5000

Refuses to version an entity whose live-relationship count is already above the ceiling, naming the entity and the repair command instead of loading the graph into transaction memory

Repairing an already-damaged graph — kg:repair

pnpm run kg:repair                      # DRY RUN (default) — reports, writes nothing
pnpm run kg:repair -- --apply           # execute the repair
pnpm run kg:repair -- --json            # machine-readable output
pnpm run kg:repair -- --batch-size 2000 # rows per inner transaction (default 5000)
pnpm run kg:repair -- --apply --passes 5 # max full passes; repeats while work remains (default 3)

Five idempotent steps, run in order, each as its own implicit transaction (required by CALL … IN TRANSACTIONS):

  1. Delete duplicate live relationships, keeping one per (startNode, endNode, relationType) between live versions.

  2. Delete live relationships attached to a stale version that already have a live-to-live equivalent.

  3. Delete duplicate historical relationships the same way.

  4. Close duplicate live versions per name — keep the greatest validFrom, carry the losers' live relationships onto the survivor with MERGE, then stamp the originals (loser i closes at now - i ms, because (name, validTo) is unique).

  5. Re-point any remaining stale-attached live relationship onto the live version of the same name, then delete the original.

Exit code is 1 when a dry run finds work to do (so a cron can alert), 0 when the graph is clean or --apply completed, 2 on failure. Grouping stages carry min(elementId(r)) and count(r) only and never collect() a relationship group — a collect() over a 39k-edge group exceeds the 512 MiB transaction cap on its own, even with batched deletes.

Running the repair twice is a no-op the second time.

MCP API Tools

The following tools are available to LLM client hosts through the Model Context Protocol:

Entity Management

  • create_entities

    • Create multiple new entities in the knowledge graph

    • Input: entities (array of objects)

      • Each object contains:

        • name (string): Entity identifier

        • entityType (string): Type classification

        • domain (string, optional): User-defined namespace for organization. Default: null (uncategorized)

        • observations (string[]): Associated observations

  • add_observations

    • Add new observations to existing entities

    • Input: observations (array of objects)

      • Each object contains:

        • entityName (string): Target entity

        • contents (string[]): New observations to add

  • delete_entities

    • Remove entities and their relations

    • Input: entityNames (string[])

  • delete_observations

    • Remove specific observations from entities

    • Input: deletions (array of objects)

      • Each object contains:

        • entityName (string): Target entity

        • observations (string[]): Observations to remove

Relation Management

  • create_relations

    • Create multiple new relations between entities with enhanced properties

    • Input: relations (array of objects)

      • Each object contains:

        • from (string): Source entity name

        • to (string): Target entity name

        • relationType (string): Relationship type

        • strength (number, optional): Relation strength (0.0-1.0)

        • confidence (number, optional): Confidence level (0.0-1.0)

        • metadata (object, optional): Custom metadata fields

  • get_relation

    • Get a specific relation with its enhanced properties

    • Input:

      • from (string): Source entity name

      • to (string): Target entity name

      • relationType (string): Relationship type

  • update_relation

    • Update an existing relation with enhanced properties

    • Input: relation (object):

      • Contains:

        • from (string): Source entity name

        • to (string): Target entity name

        • relationType (string): Relationship type

        • strength (number, optional): Relation strength (0.0-1.0)

        • confidence (number, optional): Confidence level (0.0-1.0)

        • metadata (object, optional): Custom metadata fields

  • delete_relations

    • Remove specific relations from the graph

    • Input: relations (array of objects)

      • Each object contains:

        • from (string): Source entity name

        • to (string): Target entity name

        • relationType (string): Relationship type

Graph Operations

  • read_graph

    • Read the entire knowledge graph

    • No input required

  • search_nodes

    • Search for nodes based on query

    • Input:

      • query (string): Search query

      • domain (string, optional): Filter by user-defined domain. Omit to search all domains

  • open_nodes

    • Retrieve specific nodes by name

    • Input: names (string[])

  • flag_oversized_entities (v2.8.0+)

    • List entities whose serialized size approaches or exceeds the MCP open_nodes output cap (default 25,000 tokens), ranked largest-first, so they can be split before they become unretrievable. Read-only; returns size metrics only (est_tokens, ratio, state of OK/WARN/CRITICAL, observation counts) — never full entity bodies, so the call can never itself breach the cap.

    • Input (all optional):

      • limit (number): number of largest entities to scan/rank (default: 50)

      • warn_ratio (number): fraction of the cap (0.0-1.0) for the WARN threshold (default: 0.8)

      • include_ok (boolean): include entities below the warn threshold (default: false)

    • See Oversized-entity flagging.

Semantic Search

  • semantic_search

    • Search for entities semantically using vector embeddings and similarity

    • Input:

      • query (string): The text query to search for semantically

      • limit (number, optional): Maximum results to return (default: 10; with a reranker configured, default: 5 reranked best-first — an explicit limit is always honoured exactly)

      • min_similarity (number, optional): Minimum similarity threshold on Neo4j's normalised cosine scale (0.0-1.0, where 0.5 ≈ unrelated; default: 0 = disabled — see Result counts, ordering & min_similarity)

      • entity_types (string[], optional): Filter results by entity types

      • domain (string, optional): Filter by user-defined domain. Omit to search all domains

      • hybrid_search (boolean, optional): Combine keyword and semantic search (default: true)

      • semantic_weight (number, optional): Weight of semantic results in hybrid search (0.0-1.0, default: 0.6)

    • Features:

      • Intelligently selects optimal search method (vector, keyword, or hybrid) based on query context

      • Gracefully handles queries with no semantic matches through fallback mechanisms

      • Maintains high performance with automatic optimization decisions

  • get_entity_embedding

    • Get the vector embedding for a specific entity

    • Input:

      • entity_name (string): The name of the entity to get the embedding for

Temporal Features

  • get_entity_history

    • Get complete version history of an entity

    • Input: entityName (string)

  • get_relation_history

    • Get complete version history of a relation

    • Input:

      • from (string): Source entity name

      • to (string): Target entity name

      • relationType (string): Relationship type

  • get_graph_at_time

    • Get the state of the graph at a specific timestamp

    • Input: timestamp (number): Unix timestamp (milliseconds since epoch)

  • get_decayed_graph

    • Get graph with time-decayed confidence values

    • Input: options (object, optional):

      • reference_time (number): Reference timestamp for decay calculation (milliseconds since epoch)

      • decay_factor (number): Optional decay factor override

Embeddings & Reranking Setup

Semantic search needs an embedding provider. The server speaks the OpenAI-compatible /embeddings API, so it works with OpenAI, Cloudflare Workers AI, or any self-hosted OpenAI-compatible endpoint (Ollama, LM Studio, vLLM). An optional cross-encoder reranker re-scores semantic search candidates for better precision.

The one rule that matters: dimensions must match

EMBEDDING_DIMENSIONS  ==  NEO4J_VECTOR_DIMENSIONS  ==  the model's NATIVE output dimension

The Neo4j vector index is created at a fixed dimension. A vector of any other length can never be indexed — and as of v2.6.0 the server refuses to write it (see Graceful degradation). The dimension is a property of the model, so pick the model first, then set both variables to its native output size.

The other thing to know: input context windows

Each model also has a maximum input length, and text past it is truncated before it is vectorised — so a very long entity is embedded from its head only, and anything beyond the cutoff becomes unreachable by semantic_search. Keep entities reasonably sized (split oversized ones) for good recall.

Model

Role

Max input

Truncation

@cf/qwen/qwen3-embedding-0.6b

embedding

8,192 tokens

full text is sent; Cloudflare truncates the overflow server-side

text-embedding-3-small / -large

embedding

8,191 tokens

OpenAI truncates server-side

@cf/baai/bge-reranker-base

reranker

512 tokens (query + passage)

each passage is truncated client-side to RERANK_MAX_PASSAGE_CHARS (default 2,000 chars ≈ this window) before scoring

Cloudflare's docs are currently inconsistent on the qwen3 embedding limit — the model page and AI Search table say 8,192 tokens; the launch changelog says 4,096. Treat ~4K as a conservative floor if a single entity sits near the limit.

Option A — OpenAI (default)

OPENAI_API_KEY=sk-...
OPENAI_EMBEDDING_MODEL=text-embedding-3-small   # 1536 dimensions (default)
NEO4J_VECTOR_DIMENSIONS=1536

Nothing else needed — the OpenAI endpoint is the built-in default.

Option B — Cloudflare Workers AI (free plan works)

Cloudflare's free Workers AI allocation (10,000 neurons/day) comfortably covers a personal knowledge graph — a full re-embed of ~2,000 entities fits inside a single day's free quota, and steady-state usage (query embeddings + incremental backfill) is a tiny fraction of that.

  1. Create a token: Cloudflare dashboard → My Profile → API Tokens → Create Token → use the Workers AI template (or a custom token with Account → Workers AI → Read). This single permission covers both embeddings and the reranker.

  2. Find your account ID: dashboard → any zone → right sidebar, or Workers & Pages overview.

  3. Configure:

EMBEDDING_API_KEY=<your-cf-workers-ai-token>
EMBEDDING_API_ENDPOINT=https://api.cloudflare.com/client/v4/accounts/<your-account-id>/ai/v1/embeddings
EMBEDDING_MODEL=@cf/qwen/qwen3-embedding-0.6b   # native 1024 dimensions
EMBEDDING_DIMENSIONS=1024
NEO4J_VECTOR_DIMENSIONS=1024

# Optional but recommended: cross-encoder reranker (same token)
RERANK_ENABLED=true
RERANK_ACCOUNT_ID=<your-account-id>
RERANK_MODEL=@cf/baai/bge-reranker-base
RERANK_API_KEY=<your-cf-workers-ai-token>

Option C — Any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM)

EMBEDDING_API_KEY=anything-non-empty            # some local servers ignore auth but the key must be set
EMBEDDING_API_BASE_URL=http://localhost:11434/v1  # /embeddings is appended automatically
EMBEDDING_MODEL=nomic-embed-text                # check your model's native dimension!
EMBEDDING_DIMENSIONS=768
NEO4J_VECTOR_DIMENSIONS=768

Result counts, ordering & min_similarity

Defaults are reranker-aware (v2.7.0+). Vector recall is always limit ?? 10; the reranker only re-orders within that recalled set and trims the default return:

Scenario

Vector recall

Returned

Final order

No reranker, default

10

10

hybrid score, best-first

Reranker configured, default

10

5 (RERANK_TOP_K)

cross-encoder, best-first

Explicit limit: N (either mode)

N

N (always honoured exactly)

as above

Reranker fails → fail-open

10 / N

5 / N

hybrid score, sliced to the return count

Two env knobs govern the reranker, and they mean different things:

  • RERANK_TOP_K (default 5) — the default return count when a reranker is configured. Only applies when no explicit limit is given.

  • RERANK_TOP_N (default 20) — the scoring-payload cap: how many recall candidates are sent to the cross-encoder for scoring. It is not a return count. With an explicit limit larger than RERANK_TOP_N, the first RERANK_TOP_N candidates are cross-encoder-ordered and the unscored remainder is appended in recall order, so the limit contract always holds.

Ordering guarantees: with a reranker, results are cross-encoder best-first (the response is defensively score-sorted server-side). Without a reranker — and on any reranker failure (fail-open) — results follow the hybrid-score order, which is preserved through entity hydration on both search paths (v2.7.0+).

min_similarity: the threshold applies to Neo4j's normalised cosine score — (cosine + 1) / 2, so 0.5 ≈ unrelated and 1.0 = identical. The default is 0 (disabled). Absolute floors are not meaningful on this scale for typical embedding models: measured with qwen3 embeddings, top-20 scores cluster around 0.71–0.90 for relevant and irrelevant queries alike, so any floor that blocks junk also blocks real queries. The parameter is retained per-call for power users (an explicit 0 works).

Switching models (dimension migration)

Changing to a model with a different native dimension requires rebuilding the vector index and re-embedding — vectors of the old dimension cannot coexist with the new index. With the server stopped:

DROP INDEX entity_embeddings IF EXISTS;

MATCH (e:Entity) WHERE e.embedding IS NOT NULL
SET e.embedding = NULL, e.embeddingModel = NULL, e.embeddingGeneratedAt = NULL;

CREATE VECTOR INDEX entity_embeddings IF NOT EXISTS
FOR (n:Entity) ON (n.embedding)
OPTIONS { indexConfig: {
  `vector.dimensions`: 1024,            // the NEW dimension
  `vector.similarity_function`: 'cosine'
} };

Then update the EMBEDDING_* / NEO4J_VECTOR_DIMENSIONS variables and restart. The backfill cron (EMBEDDING_BACKFILL_CRON) re-embeds every entity automatically — tighten it to */1 * * * * for the duration of the migration if you want it done in minutes rather than at the next daily tick.

Graceful degradation / failure behaviour

The embedding pipeline is designed to fail loudly into a safe state, never silently corrupt:

Condition

Behaviour

No provider configured (no EMBEDDING_API_KEY/OPENAI_API_KEY)

Server runs in keyword-only mode: BM25/keyword search works, semantic_search falls back, nothing is ever embedded. Random/mock vectors are never generated implicitly.

Embedding API call fails on entity write

Entity is persisted with embedding = NULL; the backfill cron retries later. Writes never block on the embedding provider.

Reranker errors (timeout, bad response, quota)

Fail-open: semantic_search returns the hybrid-ordered recall sliced to the return count (v2.7.0+; previously the full widened recall, unordered). Reranking is strictly additive.

Vector length ≠ NEO4J_VECTOR_DIMENSIONS (v2.6.0+)

Write is rejected with a loud error — a mismatched vector can never be indexed, so persisting it would silently corrupt search. The startup log also warns if EMBEDDING_DIMENSIONS ≠ NEO4J_VECTOR_DIMENSIONS.

NODE_ENV=production with a mock/fallback embedding service (v2.6.0+)

Embedding writes are refused (keyword-only mode + hard error log). MOCK_EMBEDDINGS=true is for tests and never counts as a provider in production.

Multi-Surface MCP Client Setup

When several MCP clients (Claude Code, Claude Desktop, Codex, etc.) share one knowledge graph, use a hub-and-spoke topology:

  • One server-side instance owns all embedding writes: WRITE_EMBEDDINGS_LOCALLY=true (the default) plus a tight backfill cron (EMBEDDING_BACKFILL_CRON='*/1 * * * *').

  • Every interactive client runs as a thin client: WRITE_EMBEDDINGS_LOCALLY=false. Thin clients embed queries (so semantic_search works) but never write embeddings — a misconfigured laptop can therefore never pollute the shared store.

The canonical thin-client environment (substitute your own values):

NEO4J_URI=bolt://<your-neo4j-host>:7687
NEO4J_USERNAME=neo4j                  # NOTE: NEO4J_USERNAME — "NEO4J_USER" is silently ignored
NEO4J_PASSWORD=<password>
NEO4J_DATABASE=neo4j
NEO4J_VECTOR_DIMENSIONS=1024
EMBEDDING_API_KEY=<token>
EMBEDDING_API_ENDPOINT=https://api.cloudflare.com/client/v4/accounts/<account-id>/ai/v1/embeddings
EMBEDDING_MODEL=@cf/qwen/qwen3-embedding-0.6b
EMBEDDING_DIMENSIONS=1024
RERANK_ENABLED=true
RERANK_ACCOUNT_ID=<account-id>
RERANK_MODEL=@cf/baai/bge-reranker-base
RERANK_API_KEY=<token>
WRITE_EMBEDDINGS_LOCALLY=false

Claude Code (user scope, all projects):

claude mcp add-json kg -s user '{
  "command": "npx",
  "args": ["-y", "@henrychong-ai/mcp-neo4j-knowledge-graph"],
  "env": { /* canonical thin-client env above */ }
}'

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "kg": {
      "command": "npx",
      "args": ["-y", "@henrychong-ai/mcp-neo4j-knowledge-graph"],
      "env": { "...": "canonical thin-client env above" }
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.kg]
command = "npx"
args = ["-y", "@henrychong-ai/mcp-neo4j-knowledge-graph"]

[mcp_servers.kg.env]
NEO4J_URI = "bolt://<your-neo4j-host>:7687"
# ... canonical thin-client env above, TOML syntax

Tips:

  • Secrets: prefer a secret-manager wrapper (e.g. 1Password: command: "op", args: ["run", "--", "npx", "-y", "@henrychong-ai/mcp-neo4j-knowledge-graph"] with op:// references in env) over literal tokens in config files.

  • Query embeddings must match the index: every client embeds its own queries, so all clients must use the same model/dimension as the server's index. A client on a different model returns no semantic hits.

  • After upgrading: clear the npx cache so clients pick up the new version — rm -rf ~/.npm/_npx/*/node_modules/@henrychong-ai — then restart the client app. Long-lived apps (Claude Desktop) keep old server processes alive until restarted.

Configuration

Environment Variables

Configure the MCP server with these environment variables:

# Neo4j Connection Settings
NEO4J_URI=bolt://127.0.0.1:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password
NEO4J_DATABASE=neo4j

# Vector Search Configuration
NEO4J_VECTOR_INDEX=entity_embeddings
NEO4J_VECTOR_DIMENSIONS=1536
NEO4J_SIMILARITY_FUNCTION=cosine

# Embedding Service Configuration
OPENAI_API_KEY=your-openai-api-key
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# Provider-neutral embedding config (v2.5.0+) — ANY OpenAI-compatible endpoint.
# These fall back to the OPENAI_* names above, so existing setups are unaffected.
# Example: Cloudflare Workers AI qwen3-embedding-0.6b (1024-dim):
#   EMBEDDING_API_KEY=<cf-workers-ai-token>
#   EMBEDDING_API_BASE_URL=https://api.cloudflare.com/client/v4/accounts/<id>/ai/v1
#   EMBEDDING_MODEL=@cf/qwen/qwen3-embedding-0.6b
#   EMBEDDING_DIMENSIONS=1024     # MUST match NEO4J_VECTOR_DIMENSIONS and the model's NATIVE output
#                                 # dim. Sets the reported/index dimension only — it is NOT sent in
#                                 # the embeddings request (not all OpenAI-compatible endpoints accept
#                                 # a `dimensions` param), so it cannot truncate an OpenAI vector;
#                                 # choose a model whose native output dim already matches.
# With NO provider configured (and MOCK_EMBEDDINGS unset) the server runs keyword-only
# (no random-vector mock). Set MOCK_EMBEDDINGS=true for deterministic test vectors.

# Optional cross-encoder reranker (v2.5.0+) — re-scores semantic_search candidates.
# Disabled unless RERANK_ENABLED=true AND an endpoint + key resolve. Fail-open on any error
# (v2.7.0+: fail-open returns the hybrid-ordered recall sliced to the return count).
RERANK_ENABLED=false
# RERANK_MODEL=@cf/baai/bge-reranker-base
# RERANK_ENDPOINT=https://api.cloudflare.com/client/v4/accounts/<id>/ai/run/@cf/baai/bge-reranker-base
# RERANK_ACCOUNT_ID=<id>          # alternative to RERANK_ENDPOINT (derives the URL from model)
# RERANK_API_KEY=<token>          # falls back to EMBEDDING_API_KEY
# RERANK_TOP_N=20                 # scoring-payload cap (candidates sent to the cross-encoder) — NOT a return count
# RERANK_TOP_K=5                  # default return count with a reranker (explicit `limit` always wins; v2.7.0: was 10)
# RERANK_MAX_PASSAGE_CHARS=2000  RERANK_TIMEOUT_MS=5000

# Embedding Pipeline Topology (v2.3.0+)
WRITE_EMBEDDINGS_LOCALLY=true       # Default true. Set to "false" on thin-client hosts (e.g. laptops)
                                     # to skip queueing embedding jobs on entity writes; entities are
                                     # persisted with embedding=NULL and a server-side instance is
                                     # responsible for backfilling. Read paths still use the embedding
                                     # service for query embeddings, so OPENAI_API_KEY is still
                                     # required for semantic_search unless you accept BM25-only fallback.
EMBEDDING_BACKFILL_CRON='0 19 * * *' # Cron schedule for scheduleIncrementalRegeneration. Default
                                     # 19:00 UTC daily (= 03:00 SGT). Server-side instances may
                                     # tighten to '*/1 * * * *' for ~1-minute backfill latency.
EMBEDDING_STALE_CLAIM_MS=300000      # (v2.4.0+) Claims older than this age are auto-released back
                                     # to 'pending' on the next processJobs tick. Default 5 minutes.
                                     # Increase if your worker's batch processing time can exceed
                                     # this; decrease for faster recovery from worker crashes.

# Oversized-Entity Flagging (v2.8.0+) — early-warning before an entity outgrows
# the open_nodes cap. All advisory; sizing is a conservative chars-per-token estimate.
MAX_MCP_OUTPUT_TOKENS=25000          # Assumed open_nodes output cap (tokens) the sizes are measured against.
                                     # Set to match your client/harness cap if it differs from the 25k default.
ENTITY_SIZE_WARN_RATIO=0.8           # Fraction of the cap at/above which an entity is flagged WARN.
ENTITY_SIZE_CRITICAL_RATIO=1.0       # Fraction of the cap at/above which an entity is flagged CRITICAL
                                     # (>= warn ratio; already at/over the cap → may be unretrievable whole).
ENTITY_SIZE_WARN_ON_WRITE=true       # When true, write tools (create/add/update batch) append a non-fatal
                                     # warnings[] field naming any touched entity that crosses WARN/CRITICAL.
ENTITY_SIZE_SCAN_LIMIT=50            # Default number of largest entities scanned/ranked per pass.

# Temporal Versioning Safety (v2.9.0+) — see "Versioning safety & graph repair".
NEO4J_TX_TIMEOUT_MS=60000            # Transaction timeout (ms) applied to EVERY transaction and
                                     # auto-commit query. Without it an abandoned transaction holds
                                     # its write locks until the server kills the connection, which on
                                     # a server with no db.transaction.timeout configured is never.
NEO4J_MAX_LIVE_RELATIONSHIPS=5000    # Pre-flight ceiling on the live relationships one entity version
                                     # may carry. Versioning has to read them all into transaction
                                     # memory; past a few thousand that alone exhausts
                                     # db.memory.transaction.max and every write on the database fails.
                                     # Over the limit the write is refused with an error naming the
                                     # entity, its count, and `pnpm kg:repair`.

# Logging Configuration
LOG_LEVEL=warn              # Log level: debug, info, warn, error, silent (default: warn)
DEBUG=true                  # Enable debug mode (enables additional diagnostic tools)

# Prometheus Metrics (Optional - Production Monitoring)
ENABLE_PROMETHEUS_METRICS=true  # Enable metrics collection and HTTP endpoint

Prometheus Metrics

The MCP server includes built-in Prometheus metrics for production observability. Metrics are disabled by default to minimize local machine overhead and only enabled when explicitly configured.

Enabling Metrics

Set the environment variable to enable metrics collection:

export ENABLE_PROMETHEUS_METRICS=true

When enabled, the metrics server starts on port 9091 and exposes a /metrics endpoint in Prometheus exposition format.

Available Metrics

Query Performance:

  • mcp_query_duration_seconds - Histogram tracking query execution time

    • Labels: operation (loadGraph, searchNodes, openNodes, semanticSearch), cache_status (hit, miss, disabled)

    • Buckets: 1ms, 5ms, 10ms, 50ms, 100ms, 500ms, 1s, 5s

Cache Performance (ready for future cache integration):

  • mcp_cache_hits_total - Counter for cache hits

  • mcp_cache_misses_total - Counter for cache misses

  • mcp_cache_invalidations_total - Counter for cache invalidations

  • mcp_cache_size_current - Gauge for current cache size

Process Metrics:

  • Default Node.js process metrics (CPU, memory, event loop, garbage collection)

Accessing Metrics

Once enabled, metrics are available at:

curl http://localhost:9091/metrics

Production Deployment

For production deployments, configure Prometheus to scrape the metrics endpoint:

scrape_configs:
  - job_name: 'mcp-kg-server'
    scrape_interval: 30s
    static_configs:
      - targets: ['localhost:9091']
        labels:
          instance: 'mcp-neo4j-knowledge-graph'
          environment: 'production'

Metrics can then be visualized in Grafana with custom dashboards showing:

  • Query performance trends

  • Cache hit/miss ratios

  • System resource utilization

  • Operation latency distributions

Port Selection

Port 9091 is chosen to avoid conflicts with common Prometheus exporters:

  • 9090: Prometheus server

  • 9099: neo4j-exporter

  • 9100: node-exporter

Command Line Options

The Neo4j CLI tools support the following options:

--uri <uri>              Neo4j server URI (default: bolt://127.0.0.1:7687)
--username <username>    Neo4j username (default: neo4j)
--password <password>    Neo4j password (default: memento_password)
--database <n>           Neo4j database name (default: neo4j)
--vector-index <n>       Vector index name (default: entity_embeddings)
--dimensions <number>    Vector dimensions (default: 1536)
--similarity <function>  Similarity function (cosine|euclidean) (default: cosine)
--recreate               Force recreation of constraints and indexes
--no-debug               Disable detailed output (debug is ON by default)

Embedding Models

Available OpenAI embedding models:

  • text-embedding-3-small: Efficient, cost-effective (1536 dimensions)

  • text-embedding-3-large: Higher accuracy, more expensive (3072 dimensions)

  • text-embedding-ada-002: Legacy model (1536 dimensions)

OpenAI API Configuration

To use semantic search, you'll need to configure OpenAI API credentials:

  1. Obtain an API key from OpenAI

  2. Configure your environment with:

# OpenAI API Key for embeddings
OPENAI_API_KEY=your-openai-api-key
# Default embedding model
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

Note: For testing environments, the system will mock embedding generation if no API key is provided. However, using real embeddings is recommended for integration testing.

Integration with Claude Desktop

Configuration

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "neo4j-kg": {
      "command": "npx",
      "args": ["-y", "@henrychong-ai/mcp-neo4j-knowledge-graph"],
      "env": {
        "NEO4J_URI": "bolt://127.0.0.1:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your_password",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_VECTOR_INDEX": "entity_embeddings",
        "NEO4J_VECTOR_DIMENSIONS": "1536",
        "NEO4J_SIMILARITY_FUNCTION": "cosine",
        "OPENAI_API_KEY": "your-openai-api-key",
        "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
        "DEBUG": "true"
      }
    }
  }
}

Alternatively, for local development, you can use:

{
  "mcpServers": {
    "neo4j-kg": {
      "command": "/path/to/node",
      "args": ["/path/to/mcp-neo4j-knowledge-graph/dist/index.js"],
      "env": {
        "NEO4J_URI": "bolt://127.0.0.1:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your_password",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_VECTOR_INDEX": "entity_embeddings",
        "NEO4J_VECTOR_DIMENSIONS": "1536",
        "NEO4J_SIMILARITY_FUNCTION": "cosine",
        "OPENAI_API_KEY": "your-openai-api-key",
        "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
        "DEBUG": "true"
      }
    }
  }
}

Important: Always explicitly specify the embedding model in your Claude Desktop configuration to ensure consistent behavior.

Recommended System Prompts

For optimal integration with Claude, add these statements to your system prompt:

You have access to a Neo4j knowledge graph memory system, which provides you with persistent memory capabilities.
Your memory tools are provided by a sophisticated knowledge graph implementation.
When asked about past conversations or user information, always check the knowledge graph first.
You should use semantic_search to find relevant information in your memory when answering questions.

Testing Semantic Search

Once configured, Claude can access the semantic search capabilities through natural language:

  1. To create entities with semantic embeddings:

    User: "Remember that Python is a high-level programming language known for its readability and JavaScript is primarily used for web development."

  2. To search semantically:

    User: "What programming languages do you know about that are good for web development?"

  3. To retrieve specific information:

    User: "Tell me everything you know about Python."

The power of this approach is that users can interact naturally, while the LLM handles the complexity of selecting and using the appropriate memory tools.

Real-World Applications

The adaptive search capabilities provide practical benefits:

  1. Query Versatility: Users don't need to worry about how to phrase questions - the system adapts to different query types automatically

  2. Failure Resilience: Even when semantic matches aren't available, the system can fall back to alternative methods without user intervention

  3. Performance Efficiency: By intelligently selecting the optimal search method, the system balances performance and relevance for each query

  4. Improved Context Retrieval: LLM conversations benefit from better context retrieval as the system can find relevant information across complex knowledge graphs

For example, when a user asks "What do you know about machine learning?", the system can retrieve conceptually related entities even if they don't explicitly mention "machine learning" - perhaps entities about neural networks, data science, or specific algorithms. But if semantic search yields insufficient results, the system automatically adjusts its approach to ensure useful information is still returned.

Integration with Claude Code

Configuration

Add this to your ~/.claude.json:

{
  "mcpServers": {
    "neo4j-kg": {
      "command": "npx",
      "args": ["-y", "@henrychong-ai/mcp-neo4j-knowledge-graph"],
      "env": {
        "NEO4J_URI": "bolt://127.0.0.1:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your_password",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_VECTOR_INDEX": "entity_embeddings",
        "NEO4J_VECTOR_DIMENSIONS": "1536",
        "NEO4J_SIMILARITY_FUNCTION": "cosine",
        "OPENAI_API_KEY": "your-openai-api-key",
        "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small"
      }
    }
  }
}

Verify MCP Tools Available

In a Claude Code session, the MCP tools will be automatically available. You can verify by asking:

Show me the available MCP tools for the knowledge graph

You should see tools like:

  • mcp__kg__create_entities

  • mcp__kg__create_relations

  • mcp__kg__add_observations

  • mcp__kg__search_nodes

  • mcp__kg__semantic_search

  • And more...

Testing Your Setup

Step 1: Create Your First Entity

In Claude Desktop or Claude Code, say:

Use the knowledge graph to create an entity named "Python"
of type "Programming Language" with the observation
"General-purpose, high-level programming language known for readability"

Step 2: Search for the Entity

Search the knowledge graph for "Python"

Claude should find your entity using the mcp__kg__search_nodes tool.

Step 3: Add More Observations

Add these observations to the Python entity:
- Created by Guido van Rossum in 1991
- Popular for data science, web development, and automation
- Dynamic typing with interpreted execution

Step 4: Verify in Neo4j Browser

Open http://localhost:7474 and run:

MATCH (e:Entity {name: "Python"})
WHERE e.validTo IS NULL
RETURN e

You should see your entity with all observations.

Step 5: Test Semantic Search (If OpenAI API Key Configured)

Perform a semantic search for "programming languages for beginners"

The Python entity should appear in results based on semantic similarity.

Troubleshooting

Schema Constraint Configuration

Temporal versioning requires a composite uniqueness constraint in your Neo4j database:

CREATE CONSTRAINT entity_name
FOR (e:Entity)
REQUIRE (e.name, e.validTo) IS UNIQUE;

If you see Node already exists errors, your database has an old single-field constraint. See docs/SCHEMA_CONSTRAINT_FIX.md for diagnosis and fix instructions.

Vector Search Diagnostics

The MCP server includes built-in diagnostic capabilities to help troubleshoot vector search issues:

  • Embedding Verification: The system checks if entities have valid embeddings and automatically generates them if missing

  • Vector Index Status: Verifies that the vector index exists and is in the ONLINE state

  • Fallback Search: If vector search fails, the system falls back to text-based search

  • Detailed Logging: Comprehensive logging of vector search operations for troubleshooting

Debug Tools (when DEBUG=true)

Additional diagnostic tools become available when debug mode is enabled:

  • diagnose_vector_search: Information about the Neo4j vector index, embedding counts, and search functionality

  • force_generate_embedding: Forces the generation of an embedding for a specific entity

  • debug_embedding_config: Information about the current embedding service configuration

Developer Reset

To completely reset your Neo4j database during development:

# Stop the container (if using Docker)
docker stop neo4j-kg

# Remove the container (if using Docker)
docker rm neo4j-kg

# Delete the data volume (if using Docker)
docker volume rm neo4j-kg_data

# For Neo4j Desktop, right-click your database and select "Drop database"

# Restart the database
# For Docker:
docker run -d \
  --name neo4j-kg \
  --restart unless-stopped \
  -p 7474:7474 \
  -p 7687:7687 \
  -v neo4j-kg_data:/data \
  -v neo4j-kg_logs:/logs \
  -e NEO4J_AUTH=neo4j/your_password \
  neo4j:5.26-community

# For Neo4j Desktop:
# Click the "Start" button for your database

# Reinitialize the schema
pnpm run neo4j:init

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

MIT - See the LICENSE file for details.

Acknowledgments

Built on foundational work by Gannon Hall. For the original implementation, see @gannonh/memento-mcp.

Available Tools

21 tools
add_observationsB

Add new observations to existing entities in your knowledge graph

ParametersJSON Schema
NameRequiredDescriptionDefault
observationsYes
strengthNoDefault strength value (0.0 to 1.0) for all observations
confidenceNoDefault confidence level (0.0 to 1.0) for all observations
metadataNoDefault metadata for all observations

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must fully disclose behavioral traits. It only states 'Add new observations' without specifying whether existing observations are overwritten, if duplicates are allowed, or any side effects (e.g., requiring entity existence). Lacks key mutation details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single, clear sentence. It is concise but could include brief usage hints without sacrificing brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Without output schema and with many sibling tools, the description is minimal. Fails to explain what an observation is, how it relates to entities, or any constraints (e.g., limit on contents array size).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 75% (high), so baseline is 3. The description adds little beyond the schema—just restates the tool's purpose. Does not clarify defaults or interaction between per-item and global parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Add', resource 'observations', and target 'existing entities in your knowledge graph'. It effectively distinguishes from siblings like 'add_observations_batch' and other entity/relation tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus the batch variant 'add_observations_batch'. No when-not-to-use or alternative suggestions provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

add_observations_batchA

Add observations to multiple entities in a single optimized batch operation (10-50x faster than individual adds)

ParametersJSON Schema
NameRequiredDescriptionDefault
observationsYesArray of observation batches
configNoOptional batch configuration

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only mentions performance and batch processing, but fails to disclose important traits like error handling (partial vs atomic failure), idempotency, side effects, or rate limits. Critical gaps for a batch mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads action and benefit. Every word adds value, with no unnecessary verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has complex nested parameters, no output schema, and no annotations. The description omits return value format, error semantics, and batch atomicity. For a batch mutation tool, this leaves agents with insufficient context to handle failures or interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the input schema already fully documents parameters. The description adds no extra parameter-level detail; the performance hint is a general attribute, not parameter-specific. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Add observations' and the resource 'multiple entities'. It also highlights the batch nature and performance advantage (10-50x faster), effectively distinguishing from the sibling tool 'add_observations'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly mentions the batch context and performance benefit, implying use when adding multiple observations. However, it does not explicitly state when not to use it or suggest alternatives like 'add_observations' for single additions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_entitiesC

Create multiple new entities in your knowledge graph system

ParametersJSON Schema
NameRequiredDescriptionDefault
entitiesYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description should disclose behavioral traits like idempotency, side effects, or return behavior. Only states 'create' without any behavioral details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single clear sentence with no wasted words, but it could include more context without being verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description lacks details on return values, error handling, or behavior when entities already exist. Incomplete for a creation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides detailed descriptions for all parameters, so the description adds no additional meaning beyond baseline.'

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (create) and resource (multiple entities), but does not distinguish from the sibling tool 'create_entities_batch', which likely has identical functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like 'add_observations' or 'create_relations'. No context on prerequisites or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_entities_batchB

Create multiple entities in a single optimized batch operation (10-50x faster than individual creates)

ParametersJSON Schema
NameRequiredDescriptionDefault
entitiesYesArray of entities to create
configNoOptional batch configuration

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It only mentions performance (optimized, 10-50x faster) but does not disclose any behavioral traits such as atomicity, error handling, failure modes, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words, efficiently conveying the purpose and key benefit.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lacks essential context: no mention of return values, error handling, or limitations. For a batch tool, users need to know about batch size limits and non-atomicity, which are not covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents both parameters. The description adds no additional meaning beyond the schema, hence baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'create', the resource 'multiple entities', and highlights the speed advantage (10-50x faster). It distinguishes from sibling tools like 'create_entities' which is for single entities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for batch creation and mentions performance benefits, but it does not explicitly state when to avoid this tool (e.g., for single entity creation) or mention alternative tools like 'create_entities'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_relationsC

Create multiple new relations between entities in your knowledge graph. Relations should be in active voice

ParametersJSON Schema
NameRequiredDescriptionDefault
relationsYes

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It only states creation of multiple relations without detailing side effects, validation, or return behavior. For a mutation tool, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences and front-loaded, but it sacrifices substance for brevity. It could include more key behavioral context without being verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given one complex parameter, no output schema, and many sibling tools, the description lacks completeness. It does not explain the structure of relations, required fields, or how it differs from related tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% per context, meaning the description must compensate. However, the description only mentions active voice, adding no semantic value about the relation parameters, their meanings, or constraints beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (create) and resource (multiple new relations) and adds a quality guideline (active voice). However, it does not distinguish from the sibling tool 'create_relations_batch', which likely serves the same purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like 'create_relations_batch' or 'update_relation'. The active voice hint is a quality guideline but does not address usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_relations_batchA

Create multiple relations in a single optimized batch operation (10-50x faster than individual creates)

ParametersJSON Schema
NameRequiredDescriptionDefault
relationsYesArray of relations to create
configNoOptional batch configuration

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It only mentions speed optimization but omits critical details like atomicity, partial failure handling, duplicate behavior, authentication requirements, or side effects. For a batch mutation tool, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the core purpose and key benefit. Every word adds value; no redundancy or unnecessary details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a batch operation and the lack of an output schema, the description fails to explain return values, error handling, limitations on number of relations, or how to interpret results. This is inadequate for safe and effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds context about the batch optimization but does not enhance understanding of individual parameters beyond what the schema descriptions already provide. Baseline score is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'create' and resource 'multiple relations', and highlights the optimized batch aspect with performance benefit (10-50x faster), clearly distinguishing it from the sibling 'create_relations' tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates this tool is for batch creation when performance is needed, implying it should be used over individual creates. However, it does not explicitly state when not to use it or provide alternative tool names for different scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_entitiesA

Delete multiple entities and their associated relations from your knowledge graph

ParametersJSON Schema
NameRequiredDescriptionDefault
entityNamesYesAn array of entity names to delete

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions deleting associated relations, which adds behavioral context, but lacks details on side effects, permissions, or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that is front-loaded with the verb and resource, with no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description adequately covers the core functionality, though it could mention error cases or behavior for non-existent entities.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage for the single parameter, and the description does not add additional meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (delete) and the resource (multiple entities and their associated relations), distinguishing it from siblings like delete_observations or delete_relations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for deleting entities but provides no explicit guidance on when to use this tool versus alternatives like delete_relations or read_graph.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_observationsB

Delete specific observations from entities in your knowledge graph

ParametersJSON Schema
NameRequiredDescriptionDefault
deletionsYes

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must disclose behavioral traits. It only states deletion occurs but omits details on permanence, side effects, permissions, or reversibility. Significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence is concise and front-loaded. Efficient but could include more detail without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 1 nested parameter, no output schema, and 19 siblings, the description lacks return behavior, error handling, and usage context. Incomplete for effective agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but description adds no additional parameter meaning beyond the schema structure. Fails to compensate for missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb 'delete', resource 'observations', and context 'from entities in your knowledge graph'. Effectively distinguishes from siblings like delete_entities and delete_relations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use or avoid this tool. While the name implies it's for deleting observations, no mention of alternatives or prerequisites. Moderate adequacy.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_relationsB

Delete multiple relations from your knowledge graph

ParametersJSON Schema
NameRequiredDescriptionDefault
relationsYesAn array of relations to delete

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description only states 'delete', implying a destructive action, but with no annotations to reinforce safety. It does not disclose reversibility, cascading effects, required permissions, or any side effects, failing to meet the burden for an unannotated tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, front-loaded with the action and object. It contains no fluff, and every word is necessary to convey the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (one parameter, no output schema, no annotations), the description is minimal but barely adequate. It lacks any behavioral context like return values or confirmation, leaving some gaps for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with all properties described in the schema. The description adds no additional meaning beyond what the schema already provides, such as clarifying the 'relations' array or its items. Baseline 3 is appropriate as no extra value is added.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it deletes multiple relations, using a specific verb and resource. It distinguishes from sibling tools like 'delete_entities' or 'delete_observations' by specifying 'relations', though it does not further differentiate from 'create_relations' or 'update_relation' which is implied by the action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. There are no explicit context hints, usage caveats, or mentions of when not to use it, leaving the agent without decision support.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_decayed_graphB

Get your knowledge graph with confidence values decayed based on time

ParametersJSON Schema
NameRequiredDescriptionDefault
reference_timeNoOptional reference timestamp (in milliseconds since epoch) for decay calculation
decay_factorNoOptional decay factor override (normally calculated from half-life)

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It only mentions 'decayed based on time' without disclosing whether the tool is read-only, side effects, performance implications, or output format. Critical behavioral aspects like authentication needs or data transformation are omitted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise (one short sentence), but it sacrifices necessary details for brevity. It is not verbose, but it is under-specified, lacking context that could be added without making it overly long.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of output schema and annotations, the description is incomplete. It does not explain the return value, how decay works, or how it differs from similar tools like 'get_graph_at_time'. The tool's complexity (two optional parameters, no required fields) demands more context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and parameters have descriptions in the input schema. The tool description adds no extra meaning beyond what the schema already provides, so it meets the baseline but does not enhance parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets the knowledge graph with confidence values decayed based on time. The verb 'Get', resource 'knowledge graph', and specific aspect 'decayed based on time' provide a specific and unique purpose, distinguishing it from siblings like 'read_graph' or 'get_graph_at_time'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool vs alternatives, no exclusions, and no context on prerequisites or preferred scenarios. It only states what the tool does, leaving the agent to infer usage without comparison to sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_entity_embeddingC

Get the vector embedding for a specific entity from your knowledge graph

ParametersJSON Schema
NameRequiredDescriptionDefault
entity_nameYesThe name of the entity to get the embedding for

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavior. It indicates a read operation but fails to mention what the embedding looks like (e.g., vector dimensions, format), any side effects, or required permissions. The behavior is minimally described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no superfluous words. It is front-loaded and efficiently communicates the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (no output schema, sibling tools with similar purposes), the description is too minimal. It lacks context about the embedding's content, typical use cases, or how it relates to other tools like semantic_search. The agent would likely need additional information to use it effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (the parameter entity_name is described). The description adds no extra meaning beyond the schema, so it earns the baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a vector embedding for a specific entity from the knowledge graph. It uses a specific verb and resource, and while there are sibling tools like semantic_search that also deal with embeddings, the purpose is distinct enough for an agent to understand the basic action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like semantic_search or get_entity_history. There is no mention of prerequisites, context for usage, or when not to use it, leaving the agent without decision-making support.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_entity_historyB

Get the version history of an entity from your knowledge graph

ParametersJSON Schema
NameRequiredDescriptionDefault
entityNameYesThe name of the entity to retrieve history for

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral traits, but it only says 'Get the version history' without detailing side effects, return format, or potential limitations. This is insufficient for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no wasted words. It efficiently conveys the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite low complexity, the description omits crucial context like output structure (e.g., list of changes with timestamps), scope of history, and any constraints. With no output schema, this information should be in the description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description does not add any meaning beyond what the schema already provides for the single parameter. It merely restates the tool's purpose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the specific resource 'version history of an entity', effectively distinguishing it from sibling tools like get_relation_history. The purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives (e.g., get_graph_at_time, get_relation_history). The description does not mention usage context, prerequisites, or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_graph_at_timeB

Get your knowledge graph as it existed at a specific point in time

ParametersJSON Schema
NameRequiredDescriptionDefault
timestampYesThe timestamp (in milliseconds since epoch) to query the graph at

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits. It only states the basic read operation (getting a historical snapshot) but does not mention side effects, rate limits, permissions, or data completeness (e.g., whether all entities/relations are returned). The description is minimal and does not add value beyond the purpose.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded and contains no filler. Every word is essential and directly conveys the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a single parameter with full schema description and no output schema, the description adequately conveys the tool's function. However, it could be more specific about the output format (e.g., returns a graph object with entities and relations). The simplicity of the tool makes the description mostly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers 100% of parameters, with the 'timestamp' parameter described clearly as milliseconds since epoch. The description adds no additional meaning beyond the schema's parameter documentation. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves the knowledge graph as it existed at a specific point in time. The verb 'Get' and resource 'knowledge graph' with a temporal qualifier make the purpose unambiguous, and it distinguishes from sibling tools like 'read_graph' (current graph).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives like 'read_graph' or 'get_decayed_graph'. The description implies it is for historical queries but does not state when not to use it or provide context for selecting among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_relationC

Get a specific relation with its enhanced properties from your knowledge graph

ParametersJSON Schema
NameRequiredDescriptionDefault
fromYesThe name of the entity where the relation starts
toYesThe name of the entity where the relation ends
relationTypeYesThe type of the relation

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description must disclose behavior. It implies a read operation but does not clarify if the relation must exist, what happens if not found, or any other behavioral traits. This is insufficient for a safe invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence, but it omits important details. It is not overly verbose, but the structure could be improved by including usage and behavior information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple input schema and no output schema, the description is minimally adequate. It lacks context on when to use the tool, how it differs from siblings, and behavioral guarantees. More completeness is needed for effective tool selection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers all three parameters with clear descriptions. The description adds no further detail beyond 'enhanced properties,' which does not improve parameter understanding. Baseline score of 3 is appropriate given full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool retrieves a specific relation with enhanced properties from a knowledge graph. It distinguishes itself from sibling tools like create/delete relations, though 'enhanced properties' is vague.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like get_relation_history or search_nodes. The description lacks context for selecting this tool over siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_relation_historyB

Get the version history of a relation from your knowledge graph

ParametersJSON Schema
NameRequiredDescriptionDefault
fromYesThe name of the entity where the relation starts
toYesThe name of the entity where the relation ends
relationTypeYesThe type of the relation

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description offers minimal behavioral context. It does not disclose what 'version history' entails (e.g., chronological order, change details), potential limits, or authentication requirements. For a read operation, more transparency is needed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no wasted words. However, it may be too brief; slightly more detail (e.g., output format) could improve usefulness without sacrificing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a history retrieval tool with no output schema and 18 sibling tools, the description is incomplete. It fails to explain response format, ordering, or limitations, leaving the agent with insufficient context for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with clear parameter descriptions. The tool description adds no additional meaning beyond the schema, achieving the baseline score of 3 as per rubric.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Get the version history of a relation from your knowledge graph' clearly states the action (get history) and resource (relation), distinguishing it from siblings like 'get_relation' (current state) and 'get_entity_history' (entity focus).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives (e.g., get_relation, get_graph_at_time). It implicitly suggests history retrieval context but lacks explicit when-to-use or when-not-to-use instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

open_nodesB

Open specific nodes in your knowledge graph by their names

ParametersJSON Schema
NameRequiredDescriptionDefault
namesYesAn array of entity names to retrieve

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must bear the full burden. 'Open' is ambiguous—does it retrieve, navigate, or modify? The description lacks behavioral context such as whether it's read-only or requires permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence of 10 words, no waste, front-loaded with verb and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (1 param, no output schema), but the ambiguous 'open' leaves gaps. Adequate but not fully informative for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the 'names' parameter. The description adds minimal value beyond restating 'by their names'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'open' and resource 'nodes in your knowledge graph', specifying the action by names. It distinguishes from siblings like 'create_entities' or 'delete_entities'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives like 'read_graph' or 'search_nodes'. The term 'open' is ambiguous and no exclusions or prerequisites are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_graphC

Read the entire knowledge graph system

ParametersJSON Schema
NameRequiredDescriptionDefault
random_stringNoDummy parameter for no-parameter tools

TDQS

C2.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must convey all behavioral traits. 'Read' implies a non-destructive operation, but no details about potential cost, size of returned data, or side effects are given. The dummy parameter adds confusion.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short (one sentence), which is concise, but it fails to provide necessary information. It is not a model of effective conciseness as it sacrifices completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations, output schema, and vague description, the tool definition is incomplete. An agent would not know what data is returned or what 'entire knowledge graph' means. Sibling complexity increases the need for clarity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a dummy parameter clearly described in the schema. The description adds no additional meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Read the entire knowledge graph system' provides a vague purpose. It uses a verb and resource but does not specify what 'entire knowledge graph system' entails, nor does it distinguish from sibling tools like get_graph_at_time or search_nodes which also read parts of the graph.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus its many siblings (e.g., get_graph_at_time, search_nodes). There is no mention of context or alternatives, leaving the agent to guess.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_nodesC

Search for nodes in your knowledge graph based on a query

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesThe search query to match against entity names, types, and observation content
domainNoFilter results by domain (user-defined string)
include_null_domainNoWhen true, only return entities with null domain (uncategorized). Mutually exclusive with domain parameter.

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It lacks details on search behavior (e.g., case sensitivity, wildcards, ranking, result limits, pagination). Only basic purpose is stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single clear sentence, front-loaded with the verb and resource. It is concise, though it could potentially add a bit more context without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 parameters, no output schema), the description is too minimal. It does not explain return format, behavior with multiple matches, or any constraints. Lacks completeness for an effective AI agent usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema. It does not explain parameter interactions beyond what schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Search for nodes in your knowledge graph based on a query,' specifying the verb (search) and resource (nodes). It distinguishes from siblings like open_nodes or read_graph by implying text-based search, but does not explicitly contrast with semantic_search or other tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives (e.g., semantic_search for embeddings, open_nodes for direct navigation). No when-not-to-use or context of use is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_entities_batchB

Update multiple entities in a single optimized batch operation (10-50x faster than individual updates)

ParametersJSON Schema
NameRequiredDescriptionDefault
updatesYesArray of entity updates
configNoOptional batch configuration

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description should disclose behavioral traits. It mentions speed but not error handling, partial failure, permissions, or whether operations are transactional—critical for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no wasted words. Front-loaded with purpose and key benefit. Highly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, no annotations, and the description omits return value, error handling, or any guidance on batch behavior. Incomplete for a nested-parameter batch tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline 3. The description adds no specific meaning beyond schema; it only repeats that it's a batch operation. Schema already describes parameters sufficiently.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool updates multiple entities in a batch, with a performance claim. However, it doesn't explicitly mention that updates can include adding/removing observations, which is part of the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It implies use for batch updates over individual ones due to speed, but lacks explicit when-to-use or alternatives, and doesn't discuss trade-offs like atomicity or comparison with sibling batch tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_relationC

Update an existing relation with enhanced properties in your knowledge graph

ParametersJSON Schema
NameRequiredDescriptionDefault
relationYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must carry the full burden of behavioral transparency. It fails to disclose whether the update is a merge or replacement, what happens if the relation does not exist, or if any side effects occur (e.g., cascading updates to related entities). Permissions or authentication needs are not mentioned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (one short sentence), which is efficient but lacks necessary detail. It is front-loaded with the core action, but would benefit from additional context about how the update works or what output to expect.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of the tool (nested object with many optional fields, no output schema, multiple sibling tools), the description is incomplete. It does not explain return values, error handling, or how updates affect existing properties. The 'enhanced properties' term is not clarified, leaving ambiguity about which fields can be updated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the tool description adds minimal parameter information, the input schema provides detailed descriptions for each nested property (e.g., 'from', 'to', 'relationType', 'strength'). Since schema description coverage is effectively high due to these property-level descriptions, the description does not need to repeat them, earning a baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the action ('Update') and the resource ('existing relation... in your knowledge graph'), clearly distinguishing it from sibling tools like create_relations or delete_relations. However, the phrase 'enhanced properties' is vague and does not specify what enhancements are possible.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like update_entities_batch or create_relations. There is no mention of prerequisites, such as the requirement that the relation must already exist, or that from/to/relationType must uniquely identify a relation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 21 tool updatesv2.7.1
    • First observedadd_observations
    • First observedadd_observations_batch
    • First observedcreate_entities
    • First observedcreate_entities_batch
    • First observedcreate_relations
    • First observedcreate_relations_batch
    • First observeddelete_entities
    • First observeddelete_observations
    • First observeddelete_relations
    • First observedget_decayed_graph
    • First observedget_entity_embedding
    • First observedget_entity_history
    • First observedget_graph_at_time
    • First observedget_relation
    • First observedget_relation_history
    • First observedopen_nodes
    • First observedread_graph
    • First observedsearch_nodes
    • First observedsemantic_search
    • First observedupdate_entities_batch
    • First observedupdate_relation
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 21 tools

Disambiguation5/5

Each tool targets a distinct operation on entities, observations, or relations. Batch variants are clearly differentiated, and query tools like search_nodes and semantic_search serve different purposes without ambiguity.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (e.g., create_entities, delete_observations, get_relation_history). The '_batch' suffix is uniformly applied for optimized versions, and naming conventions are predictable throughout.

Tool Count5/5

With 21 tools covering CRUD, batch operations, time-travel queries, semantic search, and embeddings, the count is well-scoped for a knowledge graph server. Each tool serves a clear purpose without excess.

Completeness4/5

The tool surface covers core entity, relation, and observation lifecycle management. However, there is no explicit update_observations tool, and batch update for relations is limited to a single update_relation. These are minor gaps in an otherwise comprehensive set.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • Graphiti MCP Server

    chen9z
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to build and query temporally-aware knowledge graphs from conversations and data, maintaining persistent memory of entities, relationships, and facts across interactions.
    -
  • Memsolus MCP Server by memsolus

    Memsolus MCP Serverofficial

    memsolus
    A
    license
    A
    quality
    D
    maintenance
    Provides persistent long-term memory for AI agents through semantic search and automated knowledge graph extraction. It enables agents to store, recall, and reason over facts, preferences, and relationships across multiple conversations and sessions.
    14
    12 npm
    MIT

  • dejaview-mcp

    JakeC77
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides persistent knowledge graph memory for AI agents, enabling them to store, recall, and query facts about people, projects, and relationships across sessions.
    MIT