Wikantik delivers grounding context to AI agents through an architectural model known as RAG-as-a-Service. Rather than forcing caller frameworks to implement custom chunkers, vector searchers, graph traversers, and deduplicators, Wikantik performs server-side assembly, ranking, de-duplication, and version-pinned citation generation.
Crucially, Wikantik never synthesizes answers—it returns raw, citation-bearing context bundles and structured briefings, leaving reasoning and code generation to the agent model.
Context injection is partitioned into two distinct operational moments:
+-------------------------------------------------------------------------------+
| WIKANTIK DUAL-MOMENT CONTEXT ARCHITECTURE |
+-------------------------------------------------------------------------------+
| MOMENT A: Session Start (Proactive Standing Context) |
| - Fires ONCE when a session or fresh context window starts |
| - Ingests repo-level pinned pages, domain clusters, and initial user prompt |
| - Transports: `GET /api/briefing?format=md` (Hooks) or `get_briefing` (MCP) |
| |
| MOMENT C: Mid-Session Directed Pulls (Reactive Grounding) |
| - Fires whenever the agent encounters follow-up questions during work |
| - Primary tool: `assemble_bundle(query, mode="hybrid")` |
| - Evaluates `coverage.confidence` signal ('strong', 'partial', 'weak') |
| - Triggers autonomous traversal up the 4-tier MCP Escalation Ladder |
+-------------------------------------------------------------------------------+
A Context Briefing front-loads the architectural rules, runbooks, and design decisions of the repository before the agent writes a single line of code.
When GET /api/briefing or get_briefing is called, Wikantik fills the token budget (200 \le \text{budget} \le 24,000, default 6,000) in strict priority order:
BundleAssemblyService, extracting hybrid BM25 + dense sections. With the default scope_mode=prefer, sections from the requested clusters come first and the rest follow; with strict, only in-cluster sections are kept.pins): Ingests full bodies of load-bearing pages (e.g., ArchitectureRules, CodingStandards) in the exact order specified.clusters, Tier 1): Ingests each cluster's hub page first, then its member pages ordered by intra-cluster in-degree descending (then recency), while budget permits (ProjectContextSeparationDesign, SA-13).At least one of pins, clusters or prompt is required. Input is capped at 25 pins and 10 clusters (200 members per cluster); the excess is dropped with a warning in the response. Like every other read path, a briefing only contains pages the caller is allowed to view.
The hook executes outside the agent before the initial model call, fetches the briefing via REST, and injects it into additionalContext.
Copy clients/antigravity/antigravity-briefing-hook.sh into your repository:
mkdir -p clients/antigravity
cp /path/to/jspwiki/clients/antigravity/antigravity-briefing-hook.sh clients/antigravity/
chmod +x clients/antigravity/antigravity-briefing-hook.sh
PreInvocation Hook in .agents/hooks.jsonCreate or update <project_root>/.agents/hooks.json:
{
"wikantik-briefing": {
"PreInvocation": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "./clients/antigravity/antigravity-briefing-hook.sh",
"timeout": 15
}
]
}
]
}
}
Set the following environment variables in your workspace or shell profile:
export WIKANTIK_BASE_URL="https://wiki.yourdomain.com"
export WIKANTIK_BRIEFING_PINS="ArchitectureRules,CodingConventions"
export WIKANTIK_BRIEFING_CLUSTERS="backend-services,auth-subsystem"
export WIKANTIK_BRIEFING_BUDGET=6000
# Optional: export WIKANTIK_BASIC_AUTH="user:password"
State-Gating Mechanism: Because
PreInvocationfires on every turn, the hook self-gates using a state file in${XDG_CACHE_HOME:-$HOME/.cache}/wikantik-briefing/keyed bytranscriptPath. It injects context exactly once per session and exits0with{}on subsequent turns.
For Claude Code the equivalent is clients/claude-code/briefing-hook.sh, registered as a UserPromptSubmit hook in .claude/settings.json and driven by the same environment variables (see clients/claude-code/README.md). Both hooks call the REST endpoint, so they need no MCP key; they never fail the model call, and any error leaves the prompt unchanged.
If client hooks are disabled, configure standing instructions in AGENTS.md (for Antigravity) or CLAUDE.md (for Claude Code). This path goes through the MCP server, so the wikantik-knowledge entry needs an mcp_read API key:
## Wikantik Context Grounding
At the START of every new session or task, BEFORE executing any work, call the `get_briefing` tool on the `wikantik-knowledge` MCP server with:
- `pins`: ["ArchitectureRules", "DatabaseConventions"]
- `clusters`: ["core-services"]
- `prompt`: the user's first prompt, verbatim
Treat the returned markdown as authoritative standing context for the session.
The repository also ships a ready-made agent skill, clients/skills/wiki-context, which packages the whole protocol in this guide (briefing, assemble_bundle, escalation, citations).
When an agent needs context mid-session, it must follow the Autonomous Escalation Protocol:
Autonomous Escalation Ladder:
[ Step 1: assemble_bundle(query, mode="hybrid") ]
|
+--------------+--------------+
| |
[ confidence == "strong" ] [ confidence == "partial" | "weak" | "unknown" ]
| |
v v
[ Cite sections & proceed ] [ Step 2: retrieve_context(query) ]
(Discovers relevant page slugs)
|
v
[ Step 3: read_pages(slugs=[...]) ]
(Fetches full page bodies, max 20)
|
v (If entities / relationships)
[ Step 4: traverse / query_nodes ]
(Knowledge Graph entity exploration)
|
v (If count / aggregation query)
[ Step 5: sparql_query ]
(Ontology-level RDF queries)
|
v (All steps exhausted?)
[ Fallback: Ask User for Clarification ]
Every assemble_bundle call returns a coverage telemetry block (sectionCount, distinctPageCount, topSimilarity, confidence):
topSimilarity: The true dense cosine similarity of the best-matching chunk (0.0 \dots 1.0).confidence:
strong (topSimilarity of at least 0.55 and at least 3 sections): High-relevance matches found across the global chunk pool. Directly cite the returned sections.partial (topSimilarity from 0.40 up to 0.55, or a high similarity with fewer than 3 sections): Tangential or incomplete coverage. The agent must not guess; it must escalate.weak (topSimilarity below 0.40, or no sections): Low similarity. The agent must initiate broader discovery.unknown: No dense similarity was available (topSimilarity is -1.0), typically because the dense index is stale or down and retrieval fell back to BM25 only. Treat it like partial.The two thresholds are configurable (wikantik.bundle.coverage.strong_similarity, wikantik.bundle.coverage.partial_similarity). Coverage is recounted after the page-view ACL gate, so a bundle thinned below 3 viewable sections is downgraded from strong to partial.
/knowledge-mcp)The read-only Knowledge MCP server (/knowledge-mcp) provides up to 21 specialized tools organized into five functional categories. 21 is the fully wired count: several tools register only when their backing service is present, so a leaner deployment advertises fewer (see MCP Integration). The server authenticates with an mcp_read (or stronger) API key and shows only pages an anonymous visitor may view.
+-------------------------------------------------------------------------------+
| KNOWLEDGE MCP TOOL SURFACE TAXONOMY |
+-------------------------------------------------------------------------------+
| 1. Answer Grounding & Briefings |
| - `assemble_bundle`: Primary hybrid search returning citation-bearing text |
| - `get_briefing`: Budgeted session-start briefing markdown payload |
| |
| 2. Context & Content Retrieval |
| - `retrieve_context`: Page and section discovery candidates |
| - `read_pages`: Batched markdown read for up to 20 pages |
| - `get_page`: One page's frontmatter metadata and URL, by name |
| - `list_pages`: Browse corpus with pagination |
| - `list_metadata_values`: Inspect distinct frontmatter values |
| |
| 3. Structural Spine Navigation |
| - `list_clusters`: List high-level topic domains and their hub pages |
| - `list_tags`: Inspect categorized taxonomy tags |
| - `list_pages_by_filter`: Filter by type, cluster, tags, or freshness |
| - `get_page_by_id`: Resolve permanent canonical ULID identifiers |
| |
| 4. Knowledge Graph (LLM-Extracted Entities & Mentions) |
| - `discover_schema`: List available entity types and relationship predicates|
| - `query_nodes`: Filter nodes by type and properties |
| - `get_node`: Fetch full entity profile and incident edges |
| - `traverse`: Multi-hop graph traversal across relationship edges |
| - `search_knowledge`: Full-text search across entity names/properties |
| - `find_similar`: Node-level vector similarity search |
| |
| 5. Projections, Ontology & Citations |
| - `get_page_for_agent`: Tailored page projection with tool/page hints |
| - `get_ontology`: Inspect RDF ontology class and property hierarchy |
| - `sparql_query`: Execute read-only SPARQL queries (ideal for counts) |
| - `list_stale_citations`: Detect broken/drifted `cite://` groundings |
+-------------------------------------------------------------------------------+
When grounding agent reasoning in Wikantik, agents must adhere to strict citation rules:
slug @ version: Use the page and the version from the citation handle returned by the tool (e.g., AuthenticationArchitecture @ 4). The handle also carries the page's canonicalId, the headingPath and a span hash; see Citing a Wiki Page.assemble_bundle with the new topic query.Cluster Hub: Wikantik Platform Development Hub: Architecture, MCP Protocols, and Agent Briefings (wikantik-development)