How to Enable Wiki and Knowledge Graph Features in WeKnora: A Complete Setup Guide

Enable Wiki and Knowledge Graph features in WeKnora by configuring Neo4j environment variables, starting the Neo4j container, and toggling the Wiki and extraction settings in your knowledge base configuration.

Tencent/WeKnora provides two integrated knowledge-management capabilities: Wiki generation, which automatically creates linked Markdown pages from uploaded documents, and Knowledge Graph storage, which persists extracted entities and relationships in Neo4j for semantic search during chat. Enabling both features requires specific backend configuration, container orchestration, and knowledge base-level settings that activate the asynchronous processing pipelines defined in the source code.

Prerequisites for Enabling Knowledge Graph Support

Before activating the Wiki interface, you must establish the Neo4j backend that stores the graph data. The Knowledge Graph pipeline is disabled by default and requires explicit environment configuration.

Configure Neo4j Environment Variables

Add the Neo4j connection settings to your project’s .env file to enable the graph storage backend. The NEO4J_ENABLE flag acts as the master switch for the entire Knowledge Graph pipeline.

NEO4J_ENABLE=true
NEO4J_URI=bolt://neo4j:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_strong_password

# Optional: NEO4J_DATABASE=neo4j

These variables are read by the backend services during startup to initialize the Neo4j driver. Without NEO4J_ENABLE=true, the entity extraction workers will skip graph persistence even if extractions are requested.

Deploy the Neo4j Container

Use the bundled Docker Compose profile to instantiate the Neo4j database. The default Docker Compose network uses the service name neo4j for internal DNS resolution, which must match the NEO4J_URI hostname.

docker-compose --profile neo4j up -d

After starting Neo4j, restart the WeKnora services to load the new environment variables:

make stop && make start

# Or using Docker Compose directly:

docker compose up -d --build

Activating Wiki and Extraction Features

Once the backend infrastructure is running, you must enable the user-facing features at the knowledge base level through the web interface or API.

Enable Wiki Generation in Knowledge Base Settings

Navigate to Knowledge Base → Settings → Index Strategy in the WeKnora UI and toggle Wiki on. This activates the asynchronous Wiki pipeline defined in internal/application/service/wiki_ingest.go, which processes documents and generates interconnected Markdown pages.

You can also enable Wiki functionality programmatically via the REST API:

PATCH /api/v1/knowledgebase/{kb_id}
Content-Type: application/json

{
  "wiki_config": {
    "enable": true,
    "extraction_granularity": "standard"
  }
}

Configure Entity and Relationship Extraction

In the same knowledge base settings panel, check Enable Entity Extraction and Enable Relationship Extraction. These toggles control whether the ingestion pipeline populates Neo4j with nodes and edges. According to the source code in internal/agent/tools/definitions.go, these settings determine whether extracted concepts are persisted as graph entities and linked to Wiki pages.

The extraction granularity setting (focused, standard, or exhaustive) controls how many entities/concepts are extracted from each document, directly impacting Neo4j storage size and LLM token usage.

Ingesting Documents and Verifying the Pipeline

After configuration, you must process documents to populate both the Wiki pages and the Knowledge Graph.

Upload Documents via API or UI

Trigger the ingestion pipeline by uploading source files through the web interface or by calling the documents endpoint:

POST /api/v1/knowledgebase/{kb_id}/documents

The ingestion pipeline, implemented in internal/application/service/wiki_ingest.go and related files, automatically queues wiki:ingest and wiki:finalize tasks. These tasks are processed asynchronously, so large document sets may display an "Indexing..." indicator in the UI for several minutes.

Verify Neo4j Data and Graph Visualization

Confirm that entities and relationships have been stored correctly by querying Neo4j directly or using the WeKnora UI.

Open Neo4j Browser at http://localhost:7474 and execute:

MATCH (e:Entity)-[r:RELATIONSHIP]->(c:Concept)
RETURN e.name, type(r), c.name LIMIT 20;

Alternatively, navigate to the Graph tab within your knowledge base in the WeKnora interface to visualize the linked entities. The graph visualization component, referenced in frontend/src/views/knowledge/wiki/WikiBrowser.vue, renders the relationships stored in Neo4j.

Understanding the Wiki and Knowledge Graph Architecture

Understanding the underlying implementation helps troubleshoot issues and optimize performance.

Core Source Files and Data Models

The Wiki and Knowledge Graph functionality spans multiple layers of the WeKnora architecture:

• Data model: internal/types/wiki_page.go defines the WikiPage struct and related types that represent generated Markdown pages and their metadata.
• HTTP handlers: internal/handler/wiki_page.go implements the REST endpoints for Wiki CRUD operations, protected by RBAC middleware (OwnedWikiKBOrAdmin for writes, KBAccessRead for reads).
• Ingestion logic: internal/application/service/wiki_ingest.go (and associated wiki_ingest_*.go files) contains the core pipeline logic for transforming documents into Wiki pages and extracting graph entities.
• Agent integration: internal/agent/tools/wiki_*.go registers Wiki search and retrieval tools that allow the chat agent to query generated pages during conversations.

Database migrations in migrations/versioned/000037_wiki_and_indexing.up.sql and subsequent files establish the PostgreSQL schema that tracks Wiki page hierarchies and indexing states.

Asynchronous Processing and Failure Recovery

The Wiki pipeline operates asynchronously to handle large document volumes without blocking user requests. If the backend restarts during processing, internal/container/recover_pending_wiki_tasks.go automatically re-queues any stalled wiki:ingest or wiki:finalize tasks on service startup, ensuring no documents are lost in processing limbo.

All Wiki routes enforce strict access control. Users must possess appropriate RBAC permissions to read or modify Wiki content, ensuring that generated knowledge bases maintain security boundaries even when graph data is shared across chat sessions.

Summary

• Configure Neo4j by setting NEO4J_ENABLE=true and connection details in your .env file, then start the container with docker-compose --profile neo4j up -d.
• Restart WeKnora services to load environment variables before enabling frontend features.
• Activate Wiki in Knowledge Base → Settings → Index Strategy, and enable Entity/Relationship extraction to populate the Neo4j graph.
• Upload documents via the UI or POST /api/v1/knowledgebase/{kb_id}/documents to trigger the asynchronous pipeline defined in internal/application/service/wiki_ingest.go.
• Verify graph population using Neo4j Browser or the knowledge base Graph tab, and rely on recover_pending_wiki_tasks.go for automatic failure recovery.

Frequently Asked Questions

What environment variables are required to enable the Knowledge Graph in WeKnora?

You must set NEO4J_ENABLE=true, NEO4J_URI (typically bolt://neo4j:7687 for Docker deployments), NEO4J_USERNAME, and NEO4J_PASSWORD in your .env file. Optionally, specify NEO4J_DATABASE if using a non-default database. These variables are read at startup by the backend to initialize the Neo4j connection pool; without NEO4J_ENABLE=true, all graph persistence is skipped even if extractions are enabled in the UI.

How do I verify that the Wiki pipeline is working correctly?

After uploading documents, check the Neo4j Browser at http://localhost:7474 by running MATCH (n) RETURN n LIMIT 50; to confirm entities exist. In the WeKnora UI, visit the Graph tab of your knowledge base to visualize relationships, or check the Wiki section for generated Markdown pages. If documents appear stuck "Indexing," verify that the recover_pending_wiki_tasks.go routine has run on service startup to re-queue stalled tasks.

Can I adjust the granularity of entity extraction in WeKnora?

Yes. Set the extraction_granularity field in your knowledge base's Wiki configuration to focused, standard, or exhaustive. This parameter, stored alongside the Wiki config, controls how many entities and concepts are extracted from each document, directly affecting the density of nodes in Neo4j and the computational cost of LLM calls during ingestion.

How does WeKnora handle failures in the Wiki ingestion pipeline?

WeKnora implements automatic failure recovery through internal/container/recover_pending_wiki_tasks.go. When the backend service starts, this component scans for incomplete wiki:ingest or wiki:finalize tasks and re-queues them for processing. This ensures that interrupted uploads—whether from container restarts or transient errors—resume automatically without manual intervention or data loss.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}