Menu
Conceptual and operational master guide for interacting with Neo4j using MCP tools.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Protocol for high-fidelity document consolidation and conceptual shifting, preventing lossy 'banal summarization'.
Use this skill when the user wants to analyze a YouTube video forensically using a .info.json (metadata + comments) and/or .en.srt (transcript) produced by yt-dlp. Covers any narrative video genre: scams, true crime, interviews, controversies, documentaries. Triggers include: any mention of .info.json or .en.srt files, requests to analyze YouTube comments, mine crowd reactions, run sentiment analysis, cluster topics, find narrative pivots in a transcript, or extract the video URL from a yt-dlp JSON. The skill covers two tiers: (1) quick forensics via jq/Python, and (2) full statistical analysis via pandas/sklearn/matplotlib. Do NOT use for general YouTube searches, video downloading, or tasks where no .info.json/.en.srt files are present.
A methodology for researching, drafting, and posting high-quality technical reports to GitHub repositories.
Sequential JSON-based workflow for accessing non-Termux files on Android using termux-saf-*.
Generalized template for diagnosing complex logical patterns and bugs in unstructured codebases or texts.
Procedural instructions on tunneling and exposing GH Codespaces over SSH/SFTP directly to Termux.
| name | neo4j-expert |
| description | Conceptual and operational master guide for interacting with Neo4j using MCP tools. |
This document outlines the conceptual benefits, best practices, and learned methods for interacting with the Neo4j database using the available tools.
Neo4j is a graph database built to understand relationships and connections in data, excelling where traditional SQL databases struggle.
JOIN operations, making deep connection queries incredibly fast.(Customer)-[:BOUGHT]->(Product).Person, Product).:Person).KNOWS). Always directed.name: 'Alice').MATCH (me:Person)-[:KNOWS]->(friend)-[:BOUGHT]->(recc:Product) WHERE NOT (me)-[:BOUGHT]->(recc) RETURN reccMATCH (p1:Person)-[:USED]->(c:CreditCard)<-[:USED]-(p2:Person) WHERE p1 <> p2 RETURN p1, p2Note on Configuration: All Neo4j credentials (URI, username, password, database) are sourced from the .env file at the root of the Gemini directory. Do not hardcode these values in settings.json or other configuration files.
This section outlines the complete real-world workflow for transforming unstructured text into a queryable and visually intuitive knowledge graph, emphasizing the immediate online visualization aspect.
User Supplies Text Files: The user provides unstructured text content (e.g., news articles, reports, notes).
AI Converts to Cypher Queries: The AI (myself) processes the text, extracts entities and relationships based on best practices, and generates precise Cypher queries.
AI Populates Neo4j Database: The generated Cypher queries are executed against the Neo4j database using the available tools.
User Visualizes Online Instantly: The user can immediately visualize the newly created or updated graph in a GUI using the following services:
This seamless process allows for rapid prototyping and exploration of knowledge extracted from text.
neo4j-cypher vs. neo4j-memory ToolsetsThere is a fundamental difference in how the two toolsets interact with the Neo4j database:
neo4j-cypher (get_neo4j_schema): This tool provides a raw, low-level view of the entire database. It inspects and returns all nodes, relationships, and properties that exist, without any assumptions about the data's structure or meaning.
neo4j-memory (read_graph, create_entities, etc.): This toolset operates on a specific, high-level data model. It is designed to work with a structured concept of "entities" and "relations". As a result, read_graph will only return data that conforms to this specific model. An initially empty result from read_graph indicates that no data matching this model exists, even if the database itself is not empty.
Beyond the immediate online visualization, it's helpful to understand the current state of the graph programmatically. You can get a schema overview directly using the get_neo4j_schema() tool.
The Neo4j Console's "Explore" view can be overwhelming with technical metadata (embeddings, Chunk, Document nodes, and technical relationships like HAS_ENTITY, FIRST_CHUNK, NEXT_CHUNK, PART_OF, SIMILAR). While the GUI offers filtering options ("In Scene", "Off Scene", Node Labels, Relationship Types, Property Filters), these can be counter-intuitive or apply predefined queries that include unwanted nodes.
Key Learnings:
Chunk and Document nodes, making it difficult to get a clean view of the semantic graph.Solution for a Cleaner View: To get a cleaner, more relevant visualization, it's best to use a custom Cypher query that explicitly excludes the technical metadata. Here's a query that can be pasted directly into the Neo4j Console's query editor:
MATCH (n)-[r]->(m)
WHERE NOT (n:Chunk OR n:Document OR n:__Entity__)
AND NOT (m:Chunk OR m:Document OR m:__Entity__)
AND NOT type(r) IN ['HAS_ENTITY', 'FIRST_CHUNK', 'NEXT_CHUNK', 'PART_OF', 'SIMILAR']
RETURN n, r, m
LIMIT 100 // Limit the number of results to avoid overwhelming the visualization
This query will:
MATCH (n)-[r]->(m): Find all nodes n and m and their relationships r.WHERE NOT (n:Chunk OR n:Document OR n:__Entity__): Exclude Chunk, Document, and __Entity__ nodes from the starting point of the relationship.AND NOT (m:Chunk OR m:Document OR m:__Entity__): Exclude Chunk, Document, and __Entity__ nodes from the ending point of the relationship.AND NOT type(r) IN [...]: Exclude the specified technical relationship types.RETURN n, r, m: Return the filtered nodes and relationships.LIMIT 100: Limits the number of results to prevent overwhelming the visualization.neo4j_memory__ prefixed tools to ensure they provide a robust and intuitive way to manipulate the graph without needing direct Cypher queries for common tasks. This includes verifying their behavior for creating, updating, and deleting entities and relationships, and ensuring they handle edge cases (e.g., non-existent nodes) gracefully.Transforming unstructured text into a structured knowledge graph requires significant intellectual effort beyond just knowing how to use the Neo4j tools. This process involves:
Person, Organization, Location, Concept, Event) and relationship types (e.g., INVESTIGATES, REPORTED, LOCATED_IN, ACCUSED_OF_TIES_WITH). The schema should accurately represent the domain and facilitate meaningful queries.MERGE statements. This involves ensuring correct property assignments, handling potential duplicates, and structuring queries for efficiency.While the write_neo4j_cypher tool simplifies database interaction, the intellectual task of transforming natural language into a structured knowledge graph remains a key challenge and a critical step for effective graph population.
There are two primary methods for interacting with the database:
This method provides the most power and flexibility. It is ideal for complex queries, specific data retrieval, and fine-grained control.
Tools:
read_neo4j_cypher(query: str): For all read-only operations (MATCH, RETURN).write_neo4j_cypher(query: str): For all write operations (CREATE, MERGE, SET, DELETE).This method is more abstract and intuitive, allowing you to work with "entities" and "relations" without writing raw Cypher. This is preferable for structured data entry and simpler graph manipulations.
Primary Tools:
neo4j_memory__create_entities
name (string): A unique identifier for the entity.type (string): The category or classification of the entity (e.g., "Person", "Location").observations (list): A list of observations related to the entity. This field is mandatory, even if it is an empty list ([]).properties (dict, optional): A dictionary for any additional, unstructured attributes.Example:
[
{
"name": "Arthur",
"type": "Person",
"properties": { "title": "Sir" },
"observations": []
}
]
neo4j_memory__create_relations
source (string): The name of the entity where the relationship originates.target (string): The name of the entity where the relationship terminates.relationType (string): The name or type of the relationship (e.g., "SERVES", "LOVES").Example:
[
{
"source": "Arthur",
"target": "Uther",
"relationType": "SERVES"
}
]
neo4j_memory__add_observations
observations list, making it more descriptive and discoverable via search_memories.entityName and an observations field which is a list of strings.
{"entityName": "Uther", "observation": "He is King."}{"entityName": "Uther", "observations": ["He is the King."]} neo4j_memory__delete_entities: To remove nodes and their relationships.
read_graph
find_memories_by_name
name. This is the most efficient way to retrieve an entity if you know its unique identifier.search_memories
observations field. An entity may not appear in search results if the keyword is only in its properties or name.observations list.Important Distinction: Be aware that there is another set of generic memory tools. For direct Neo4j manipulation, ensure you are using the neo4j_memory__ prefixed tools.
This section provides examples of common Cypher query patterns for interacting with the Neo4j database. These examples focus purely on the Cypher syntax, as the MCP server handles the connection and execution.
Create a single node with a label and properties:
CREATE (p:Person {name: 'Alice', age: 30})
Create multiple nodes:
CREATE (p1:Person {name: 'Bob'})
CREATE (p2:Person {name: 'Charlie'})
Merge a node (create if not exists, match if exists):
MERGE (c:City {name: 'London'})
Create a relationship between existing nodes:
MATCH (p1:Person {name: 'Alice'}), (p2:Person {name: 'Bob'})
CREATE (p1)-[:KNOWS]->(p2)
Create a node and a relationship simultaneously:
MATCH (p:Person {name: 'Alice'})
CREATE (p)-[:LIVES_IN]->(c:City {name: 'Paris'})
Merge a relationship:
MATCH (p:Person {name: 'Alice'}), (c:City {name: 'London'})
MERGE (p)-[:LIVES_IN]->(c)
Match all nodes with a specific label:
MATCH (p:Person)
RETURN p.name, p.age
Match nodes with specific properties:
MATCH (p:Person {name: 'Alice'})
RETURN p
Match nodes connected by a relationship:
MATCH (p1:Person)-[:KNOWS]->(p2:Person)
RETURN p1.name, p2.name
Match relationships with properties:
MATCH (p1:Person)-[r:WORKS_AT {since: 2020}]->(c:Company)
RETURN p1.name, c.name, r.since
Set a new property or update an existing one:
MATCH (p:Person {name: 'Alice'})
SET p.age = 31
RETURN p
Set multiple properties:
MATCH (p:Person {name: 'Bob'})
SET p.age = 25, p.city = 'New York'
RETURN p
Delete a node and all its relationships:
MATCH (p:Person {name: 'Charlie'})
DETACH DELETE p
Delete only relationships:
MATCH (p1:Person {name: 'Alice'})-[r:KNOWS]->(p2:Person)
DELETE r
These examples cover the most frequent operations you'll perform when working with Neo4j using Cypher. Remember to adapt the labels, relationship types, and properties to your specific graph model.