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

> Learn to enable Wiki and Knowledge Graph features in WeKnora with our complete setup guide. Configure Neo4j and knowledge base settings for seamless integration.

- Repository: [Tencent/WeKnora](https://github.com/tencent/WeKnora)
- Tags: how-to-guide
- Published: 2026-09-13

---

**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.

```text
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.

```bash
docker-compose --profile neo4j up -d

```

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

```bash
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`](https://github.com/Tencent/WeKnora/blob/main/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:

```http
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`](https://github.com/Tencent/WeKnora/blob/main/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:

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

```

The ingestion pipeline, implemented in [`internal/application/service/wiki_ingest.go`](https://github.com/Tencent/WeKnora/blob/main/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:

```cypher
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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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.