The Wikantik knowledge graph is a structured layer that sits on top of the wiki's content, capturing entities, relationships, and properties extracted from page frontmatter and body links. When properly maintained, it enables AI agents to traverse contextual relationships between topics, discover connections that would otherwise require reading dozens of pages, and propose new knowledge for human review. This guide walks through every aspect of administering the knowledge graph to keep it accurate, complete, and valuable.
Before diving into operations, it helps to understand how the knowledge graph is built and maintained.
Every entity in the knowledge graph is a node. Nodes have:
AssetAllocation, RetirementPlanningHub)hub, article) drawn from the page's type frontmatter fieldEdges connect two nodes with a named relationship. For example, if a page's frontmatter contains related: [IndexFundPortfolioConstruction, UnderstandingRiskTolerance], the projector creates edges of type related from the page's node to each target node.
Every node and edge carries a provenance value that records how it entered the graph:
| Provenance | Meaning |
|---|---|
human-authored | Created from page frontmatter, body links, or manual admin action in the UI |
ai-inferred | Submitted by an AI agent via the MCP propose_knowledge tool, still pending review |
ai-reviewed | Originally proposed by an AI agent, then approved by a human administrator |
Provenance tracking ensures you always know whether a fact in the graph was authored by a human or suggested by AI, and whether AI suggestions have been vetted.
The Graph Projector is a page filter that fires automatically on every page save. It:
links_to edgesRelationship detection rule: A frontmatter key is treated as a relationship (creating edges) when its value is a list of strings and the key is not in the reserved property set. The reserved property keys — always treated as node properties, never as edges — are: tags, keywords, type, summary, date, author, cluster, status, title, description, category, and language.
For example, given this frontmatter:
---
type: article
tags: [investing, diversification]
summary: How to allocate assets across classes.
related: [UnderstandingRiskTolerance, IndexFundPortfolioConstruction]
depends_on: [MarketFundamentals]
---
The projector creates:
type=article, tags=[investing, diversification], summary=...related → UnderstandingRiskTolerance, related → IndexFundPortfolioConstruction, depends_on → MarketFundamentals[PageName](PageName) links in the body text produce links_to edgesSystem pages (CSS themes, navigation fragments, etc.) are automatically excluded from projection.
Navigate to Admin > Knowledge in the Wikantik admin panel. The page presents five tabs:
A Clear All button in the toolbar permanently deletes all knowledge graph data (nodes, edges, proposals, and embeddings). Use with extreme caution — this is irreversible.
When starting with a fresh knowledge graph (or after a Clear All), the first task is to populate it from existing wiki content.
The knowledge graph is only as rich as the frontmatter in your wiki pages. Before projecting, check the Content Embeddings tab — it lists all Pages Without Frontmatter. Each entry links to the page editor so you can add frontmatter.
A well-structured page should have at minimum:
---
type: article
tags: [relevant, topic, keywords]
summary: One sentence describing the page's purpose.
related: [RelatedPageOne, RelatedPageTwo]
---
Hub pages that organize a cluster of articles should use type: hub and include a cluster identifier:
---
type: hub
tags: [topic-area]
cluster: my-topic-cluster
summary: Overview hub for the topic area.
related: [SubArticleOne, SubArticleTwo]
---
The more relationship keys you add to frontmatter (e.g. depends_on, supersedes, implements, related), the richer the graph becomes. Any key whose value is a list of page names will be detected as a relationship.
Go to the Node Explorer tab and click Project All Pages. This scans every non-system wiki page, parses its frontmatter and body links, and creates the corresponding nodes and edges. The status line will report how many pages were scanned, how many were projected, and any errors encountered.
After projection, the schema summary at the top of the Node Explorer shows the total node count, edge count, and which node types and relationship types exist in the graph.
After projection, review the graph for quality:
links_to edges from body links are present.Wikantik uses a single Ollama-backed embedding model that produces dense vectors for every page chunk. Those vectors back hybrid search and are also reused — as on-the-fly centroids over chunk_entity_mentions — for KG-node similarity, so there is no longer a separate "structural" or "content" embedding model to retrain.
The chunk embedding indexer runs continuously: it picks up newly chunked pages on each save and writes vectors into content_chunk_embeddings. The status bar at /admin/knowledge/embeddings/status reports:
There is no manual "retrain" button — operators rebuild the embedding layer with bin/kg-rebuild.sh --skip-chunks (which forwards to the embedding indexer) when they want a wholesale recompute, e.g. after switching the active embedding model.
AI agents that interact with the wiki via the MCP server can submit knowledge graph proposals using the propose_knowledge tool. These proposals appear in the Proposals tab for human review.
Each proposal includes:
| Field | Description |
|---|---|
| Type | new-node, new-edge, new-property, or modify-property |
| Source Page | The wiki page that motivated the proposal |
| Proposed Data | The full data — node definition, edge definition, or property change |
| Confidence | The agent's self-assessed confidence (0-100%) |
| Reasoning | Why the agent believes this is correct, citing specific evidence |
When reviewing proposals:
Click Approve to accept a proposal. For new-edge proposals, approval triggers two actions:
ai-reviewed provenanceThis frontmatter write-back is important: it means approved AI knowledge becomes part of the page's permanent content, visible to future page editors and graph projections.
Click Reject to decline a proposal. You'll be prompted for an optional rejection reason. Providing a clear reason is important because:
The Node Explorer's schema summary shows the count of pending proposals. Aim to keep this near zero. A backlog of unreviewed proposals means AI agents are working with an incomplete graph, and stale proposals may become irrelevant as pages change.
The Node Explorer is your primary tool for understanding and curating the graph's entities.
hub, article) to narrow the listClick any node row to view its details in the right panel:
Click any node name in the edge tables to navigate to that node's detail view.
Stub nodes appear with a "Yes" in the Stub column and an italic warning in the detail panel. These represent entities that are referenced in frontmatter or body links but don't have their own wiki page. Stubs are normal — they're placeholders that will be fleshed out when a page is created. However, a large number of stubs may indicate:
Review stubs periodically. Fix typos, create missing pages, or delete stubs that will never be resolved.
Click Delete in the node detail panel to remove a node and all its edges. Use this for:
Deletion is permanent — the node and all its edges are removed from the database.
The Edge Explorer lets you browse the relationship layer of the graph.
related, links_to, depends_on)Click any edge row to see:
Maintain consistent relationship types across your wiki. Common patterns:
| Relationship Type | Meaning | Example |
|---|---|---|
related | General topical relationship | AssetAllocation → UnderstandingRiskTolerance |
links_to | Body text contains a markdown link (auto-generated) | RetirementPlanningHub → AiDrivenRetirementPlanning |
depends_on | Topic B requires understanding of topic A | PortfolioRebalancing → AssetAllocation |
supersedes | This page replaces an older one | NewPolicy → DeprecatedPolicy |
implements | Describes an implementation of a concept | OurDeployProcess → ContinuousDeployment |
Document your conventions and share them with content authors. Consistent relationship types make the graph queryable and meaningful.
The KG Embeddings tab provides three AI-powered tools for improving graph quality. All require a trained structural embedding model.
The model scores all potential edges (entity pairs not currently connected) and surfaces the highest-scoring predictions — relationships the model believes should exist based on the graph's structure.
Each prediction shows:
Review each prediction and click Create to add the edge to the graph. The edge is created with human-authored provenance since you're making the editorial decision.
Best practice: Don't blindly accept high-scoring predictions. Verify that the relationship makes semantic sense by checking both pages. The model is finding structural patterns, not reading content — it might predict that two nodes should be connected because they have similar graph neighborhoods, even if the actual topics are unrelated.
These are existing edges that the model considers unlikely given the rest of the graph structure. A low plausibility score suggests the relationship is unusual or potentially incorrect.
Review these edges and ask:
The model identifies pairs of nodes that may be duplicates based on three similarity scores:
Click Merge to combine two duplicate nodes. Merging:
Before merging, verify that the two nodes genuinely represent the same concept. Common legitimate merge scenarios:
AssetAllocation and [Asset Allocation](AssetAllocation) (naming inconsistency)REST API and RestApi (different naming conventions)The Content Embeddings tab provides content-level intelligence.
After training the content model, this table shows the most similar page pairs ranked by TF-IDF cosine similarity. High similarity between two pages may indicate:
Review the top pairs and take action:
related frontmatter links between legitimately related pagesThis table lists all wiki pages that lack YAML frontmatter. These pages are invisible to the knowledge graph — they produce no nodes, no edges, and no properties. Each page name links to the editor so you can add frontmatter.
Prioritize adding frontmatter to:
A healthy knowledge graph requires periodic attention, not just initial setup.
When you add a new cluster of pages, reorganize existing content, or bulk-edit frontmatter:
Use the schema summary in the Node Explorer to track key metrics:
The Graph Projector runs automatically on every page save, so the graph stays current incrementally. Project All Pages is only needed when:
AI agents interact with the knowledge graph through the MCP server's propose_knowledge and list_proposals tools. To maximize the value agents get from the graph:
The more relationship types and targets you define in frontmatter, the more context agents can discover through graph traversal. A page with only tags and summary produces a node with properties but no edges to other entities. A page with related, depends_on, implements, and other relationship keys produces a richly connected node that agents can traverse.
Agents use relationship types to understand the nature of connections, not just their existence. depends_on conveys different meaning than related, which is different from supersedes. Use specific, descriptive relationship types rather than dumping everything into related.
When agents submit proposals and receive timely feedback (approvals or rejections with reasons), they learn what kinds of knowledge are valued. Rejected proposals with clear reasons are especially valuable — the rejection history prevents agents from re-submitting the same incorrect relationships.
Stub nodes are dead ends for agent traversal. When an agent follows an edge to a stub node, it finds no properties, no source page to read, and no onward edges. Prioritize creating wiki pages for stubs that appear as targets of many edges — these are clearly important concepts that the graph references but cannot describe.
Agents benefit from up-to-date similarity data when looking for related concepts. The chunk embedding indexer runs continuously on every page save, but if the active embedding model changes you'll want to issue bin/kg-rebuild.sh --skip-chunks to recompute all chunk vectors against the new model.
To introduce a new relationship type, simply start using it in page frontmatter:
---
audited_by: [ComplianceTeam, SecurityReview]
---
Because audited_by is not in the reserved property set and its value is a list of strings, the Graph Projector will automatically create edges of type audited_by to each target. No configuration changes are needed — the schema is dynamic.
If you need a list-valued frontmatter key to be treated as a property (not a relationship), it must be added to the PROPERTY_ONLY_KEYS set in the FrontmatterRelationshipDetector class. The current reserved set is: tags, keywords, type, summary, date, author, cluster, status, title, description, category, language.
Check that your pages have valid YAML frontmatter blocks delimited by --- lines. Pages without frontmatter still produce nodes but with no properties or typed edges.
Ensure you're rejecting unwanted proposals (not just ignoring them) and providing clear rejection reasons. Only rejected proposals are recorded in the rejection history that prevents re-submission.
When you merge node A into node B, the system renames all frontmatter references from A to B across all wiki pages that have edges pointing to A. This is by design — it keeps frontmatter consistent with the graph. Review the merge confirmation dialog carefully before proceeding.
The Graph Projector runs a diff on every page save that removes edges no longer present in the frontmatter. If stale edges persist, try re-saving the affected page, or use Project All Pages to refresh the entire graph.
The knowledge graph isn't built from every page. Cluster-level policy decides what contributes; per-page frontmatter overrides handle the rest. For the full model and dashboard walkthrough, see KgInclusionPolicy.
The short version:
/admin/kg-policy lets you toggle cluster inclusion with a reason. Eager reconciliation runs on commit.kg_include: true | false) wins over cluster policy. Useful for WIP, sensitive, or one-off content.bin/kg-policy.sh mirrors the dashboard for scripting and emergencies. purge --confirm is the only destructive operation.System pages (Sandbox, Main, etc.) are always excluded — both from the KG and from the search index — via the existing SystemPageRegistry.