NeoCoder Neo4j Ai Workflow

[](https://mseep.ai/app/angrysky56-neocoder-neo4j-ai-workflow)

NeoCoder: Neo4j-Guided AI Coding Workflow

An MCP server implementation that enables AI assistants like Claude to use a Neo4j knowledge graph as their primary, dynamic "instruction manual" and project memory for standardized coding workflows.

NeoCoder: Hybrid AI Reasoning & Workflow System

An advanced MCP server implementation that combines Neo4j knowledge graphs, Qdrant vector databases, and sophisticated AI orchestration to create a hybrid reasoning system for knowledge management, research analysis, and standardized workflows.

Overview

NeoCoder implements a revolutionary Context-Augmented Reasoning system that goes far beyond traditional RAG (Retrieval-Augmented Generation) by combining:

Core Architecture:

1. Neo4j Knowledge Graphs - Authoritative structured facts, relationships, and workflows
2. Qdrant Vector Databases - Semantic search, similarity detection, and contextual understanding
3. MCP Orchestration - Intelligent routing between data sources with synthesis and citation
4. F-Contraction Synthesis - Dynamic knowledge merging that preserves source attribution

Key Capabilities:

• Hybrid Knowledge Reasoning: Seamlessly combine structured facts with semantic context
• Dynamic Knowledge Extraction: Process documents, code, and conversations into interconnected knowledge structures
• Citation-Based Analysis: Every claim tracked to its source across multiple databases
• Multi-Incarnation System: Specialized modes for coding, research, decision support, and knowledge management
• Intelligent Workflow Templates: Neo4j-guided procedures with mandatory verification steps

Revolutionary Features:

🧠 Smart Query Routing: AI automatically determines optimal data source (graph, vector, or hybrid) 🔬 Research Analysis Engine: Process academic papers with citation graphs and semantic content ⚡ F-Contraction Processing: Dynamically merge similar concepts while preserving provenance 🎯 Context-Augmented Reasoning: Generate insights impossible with single data sources 📊 Full Audit Trails: Complete tracking of knowledge synthesis and workflow execution 🛡️ Production-Ready Process Management: Automatic cleanup, signal handling, and resource tracking to prevent process leaks 🔧 Enhanced Tool Handling: Robust async initialization with proper background task management

New from an idea I had- Lotka-Volterra Ecological Framework integrated into Knowledge Graph Incarnation

Process Management & Reliability

NeoCoder implements comprehensive process management following MCP best practices:

• Signal Handlers: Proper SIGTERM/SIGINT handling for graceful shutdowns
• Resource Tracking: Automatic tracking of processes, Neo4j connections, and background tasks
• Zombie Cleanup: Active detection and cleanup of orphaned server instances
• Memory Management: Prevention of resource leaks through proper cleanup patterns
• Background Task Management: Safe handling of async initialization and concurrent operations
• Connection Pooling: Efficient Neo4j driver management with automatic cleanup

Monitoring Commands

Use these tools to monitor server health:

• get_cleanup_status() - View resource usage and cleanup status
• check_connection() - Verify Neo4j connectivity and permissions

Quick Start

Prerequisites

• Neo4j: Running locally or remote instance (for structured knowledge graphs)
• Qdrant: Vector database for semantic search and embeddings (for hybrid reasoning)
• Python 3.10+: For running the MCP server
• uv: The Python package manager for MCP servers
• Claude Desktop: For using with Claude AI

• MCP-Desktop-Commander: Invaluable for CLI and filesystem operations

• For the Lotka-Volterra Ecosystem and generally enhanced abilities-

• wolframalpha-llm-mcp: really nice!

• mcp-server-qdrant-enhanced: My qdrant-enhanced mcp server

• Optional for more utility
• arxiv-mcp-server

This incarnation is still being developed

• For Code Analysis Incarnation: AST/ASG: Currently needs development and an incarnation re-write

• Get a free API key from WolframAlpha:

To get a free API key (AppID) for Wolfram|Alpha, you need to sign up for a Wolfram ID and then register an application on the Wolfram|Alpha Developer Portal.

Create a Wolfram ID: If you don't already have one, create a Wolfram ID at https://account.wolfram.com/login/create

Navigate to the Developer Portal: Once you have a Wolfram ID, sign in to the Wolfram|Alpha Developer Portal https://developer.wolframalpha.com/portal/myapps

Sign up for your first AppID: Click on the "Sign up to get your first AppID" button.

Fill out the AppID creation dialog: Provide a name and a simple description for your application.

Receive your AppID: After filling out the necessary information, you will be presented with your API key, also referred to as an AppID.

The Wolfram|Alpha API is free for non-commercial usage, and you get up to 2,000 requests per month.

Each application requires its own unique AppID.

The MCP server runs the Python code, bridging the gap between the Neo4j graph and the AI assistant ( e.g. Claude)

Installation

1. Clone the repository

git clone https://github.com/angrysky56/NeoCoder-neo4j-ai-workflow.git
cd NeoCoder-neo4j-ai-workflow

2. Set up Python and the virtual environment

Make sure you have pyenv and uv installed.

pyenv install 3.11.12  # if not already installed
pyenv local 3.11.12
uv venv
source .venv/bin/activate

3. Install dependencies

uv pip install -e '.[dev,docs,gpu]'

4. Start Neo4j and Qdrant

• Neo4j:

Start your Neo4j server (locally or remote). Default connection: bolt://localhost:7687

Neo4j connection parameters:

• URL: bolt://localhost:7687 (default)
• Username: neo4j (default)
• Password: Your Neo4j database password
• Database: neo4j (default)

Set credentials via environment variables if needed:

• NEO4J_URL
• NEO4J_USERNAME
• NEO4J_PASSWORD
• NEO4J_DATABASE

• Qdrant:

For persistent Qdrant storage, use this Docker command (recommended):

``bash docker run -p 6333:6333 -p 6334:6334 \ -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \ qdrant/qdrant ``

This will store Qdrant data in a qdrant_storage folder in your project directory.

5. (Optional) VS Code users

• Open the Command Palette (Ctrl+Shift+P), select Python: Select Interpreter, and choose .venv/bin/python.

1. It should auto-install when using the config- not sure anymore haven't tried that and some dependencies are rather large.

Potential Quickstart- lol sorry

Recommended: Claude Desktop Integration:

Configure Claude Desktop by adding the following to your claude-app-config.json:

{
  "mcpServers": {
    "neocoder": {
      "command": "uv",
      "args": [
        "--directory",
        "/your-path-to/NeoCoder-neo4j-ai-workflow",
        "run",
        "mcp_neocoder"
      ],
      "env": {
        "NEO4J_URL": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-neo4j-password-here",
        "NEO4J_DATABASE": "neo4j",
        "LOG_LEVEL": "INFO",
        "MCP_TRANSPORT": "stdio",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Important: The password in this configuration must match your Neo4j database password.

Otherwise- Install dependencies: Quick Troubleshooting:

• If you see errors about missing packages, double-check that your .venv is activated and you are using the correct Python version.
• If you need to reset your environment, you can remove .venv and repeat the steps above.
• Can't conect to DB? Install neo4j Desktop and QDRANT. Make sure they are running. NEO4J requires a password set.

docker pull qdrant/qdrant

docker run -p 6333:6333 -p 6334:6334 \
    -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
    qdrant/qdrant

---

You are now ready to use NeoCoder with full Neo4j and Qdrant hybrid Lotka-Volterra Ecosystem reasoning!

Suggested system prompt

> **System Instruction:** You are an AI assistant integrated with a Neo4j knowledge graph that defines our standard procedures and tracks project changes.
>
> **Your Core Interaction Loop:**
> 1.  **Identify Task & Keyword:** Determine the action required (e.g., fix a bug -> `FIX`).
> 2.  **Consult the Hub:** If unsure about keywords or process, start by querying `:AiGuidanceHub {id: 'main_hub'}` for guidance and links to best practices or other guides.
> 3.  **Retrieve Instructions:** Formulate a Cypher query to fetch the `steps` from the current `:ActionTemplate` matching the keyword (e.g., `MATCH (t:ActionTemplate {keyword: 'FIX', isCurrent: true}) RETURN t.steps`). Execute this query.
> 4.  **Execute Guided Workflow:** Follow the retrieved `steps` meticulously. This includes reviewing project READMEs, implementing changes, and critically:
> 5.  **Perform Verification:** Execute the testing steps defined in the template. **ALL required tests MUST pass before you consider the task complete.**
> 6.  **Record Completion (Post-Testing):** Only if tests pass, formulate and execute the Cypher query specified in the template to create a `:WorkflowExecution` node, linking it appropriately. Do NOT record if tests failed.
> 7.  **Finalize Updates:** Update the project's README content (in Neo4j or the file) as per the template's instructions.
>
> **Strict Rule:** Always prioritize instructions retrieved from the Neo4j graph over your general knowledge for workflow procedures. Use the graph as your single source of truth for *how* tasks are done here.

---

> **knowledge_graph_incarnation with integrated Lotka Volterra Special System Instruction:** You are an AI assistant integrated with a sophisticated hybrid reasoning system that combines Neo4j knowledge graphs, Qdrant vector databases, and MCP orchestration for advanced knowledge management and workflow execution.
>
> **Your Core Capabilities:**
> 1. **Standard Coding Workflows:** Use Neo4j-guided templates for structured development tasks
> 2. **Hybrid Knowledge Reasoning:** Combine structured facts (Neo4j) with semantic search (Qdrant) for comprehensive analysis
> 3. **Dynamic Knowledge Synthesis:** Apply F-Contraction principles to merge and consolidate knowledge from multiple sources
> 4. **Multi-Modal Analysis:** Process research papers, code, documentation, and conversations into interconnected knowledge structures
> 5. **Citation-Based Reasoning:** Provide fully attributed answers with source tracking across databases
>
> **Your Core Interaction Loop:**
> 1.  **Identify Task & Context:** Determine the required action and select appropriate incarnation/workflow
> 2.  **Consult Guidance Hubs:** Query incarnation-specific guidance hubs for specialized capabilities and procedures
> 3.  **Execute Hybrid Workflows:** For knowledge tasks, use KNOWLEDGE_QUERY template for intelligent routing between graph and vector search
> 4.  **Apply Dynamic Synthesis:** Use KNOWLEDGE_EXTRACT template to process documents into both structured (Neo4j) and semantic (Qdrant) representations
> 5.  **Ensure Quality & Citations:** All knowledge claims must be properly cited with source attribution
> 6.  **Record & Learn:** Log successful executions for system optimization and learning
>
> **Hybrid Reasoning Protocol:**
> - **Graph-First**: Use Neo4j for authoritative facts, relationships, and structured data
> - **Vector-Enhanced**: Use Qdrant for semantic context, opinions, and nuanced information
> - **Intelligent Synthesis**: Combine both sources with conflict detection and full citation tracking
> - **F-Contraction Merging**: Dynamically merge similar concepts while preserving source attribution
>
> **Strict Rules:**
> - Always prioritize structured facts from Neo4j over semantic information
> - Every claim must include proper source citations
> - Use incarnation-specific tools and templates as single source of truth for procedures
> - Apply F-Contraction principles when processing multi-source information

---

Instructions for WolframAlpha use
- WolframAlpha understands natural language queries about entities in chemistry, physics, geography, history, art, astronomy, and more.
- WolframAlpha performs mathematical calculations, date and unit conversions, formula solving, etc.
- Convert inputs to simplified keyword queries whenever possible (e.g. convert "how many people live in France" to "France population").
- Send queries in English only; translate non-English queries before sending, then respond in the original language.
- Display image URLs with Markdown syntax: ![URL]
- ALWAYS use this exponent notation: `6*10^14`, NEVER `6e14`.
- ALWAYS use {"input": query} structure for queries to Wolfram endpoints; `query` must ONLY be a single-line string.
- ALWAYS use proper Markdown formatting for all math, scientific, and chemical formulas, symbols, etc.:  '$$\n[expression]\n$$' for standalone cases and '\( [expression] \)' when inline.
- Never mention your knowledge cutoff date; Wolfram may return more recent data.
- Use ONLY single-letter variable names, with or without integer subscript (e.g., n, n1, n_1).
- Use named physical constants (e.g., 'speed of light') without numerical substitution.
- Include a space between compound units (e.g., "Ω m" for "ohm*meter").
- To solve for a variable in an equation with units, consider solving a corresponding equation without units; exclude counting units (e.g., books), include genuine units (e.g., kg).
- If data for multiple properties is needed, make separate calls for each property.
- If a WolframAlpha result is not relevant to the query:
 -- If Wolfram provides multiple 'Assumptions' for a query, choose the more relevant one(s) without explaining the initial result. If you are unsure, ask the user to choose.
 -- Re-send the exact same 'input' with NO modifications, and add the 'assumption' parameter, formatted as a list, with the relevant values.
 -- ONLY simplify or rephrase the initial query if a more relevant 'Assumption' or other input suggestions are not provided.
 -- Do not explain each step unless user input is needed. Proceed directly to making a better API call based on the available assumptions.

Multiple Incarnations

NeoCoder supports multiple "incarnations" - different operational modes that adapt the system for specialized use cases while preserving the core Neo4j graph structure. In a graph-native stack, the same Neo4j core can manifest as very different "brains" simply by swapping templates and execution policies.

Key Architectural Principles

The NeoCoder split is highly adaptable because:

• Neo4j stores facts as first-class graph objects
• Workflows live in template nodes
• Execution engines simply walk the graph

Because these three tiers are orthogonal, you can freeze one layer while morphing the others—turning a code-debugger today into a lab notebook or a learning management system tomorrow. This design echoes Neo4j's own "from graph to knowledge-graph" maturation path where schema, semantics, and operations are deliberately decoupled.

Common Graph Schema Motifs

All incarnations share these core elements:

| Element | Always present | Typical labels / rels | |---------|----------------|------------------------| | Actor | human / agent / tool | (:Agent)-[:PLAYS_ROLE]->(:Role) | | Intent | hypothesis, decision, lesson, scenario | (:Intent {type}) | | **

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: angrysky56
• Source: angrysky56/NeoCoder-neo4j-ai-workflow
• License: MIT

Install and usage instructions live in the source repository linked above.