thinkwiki

name	ThinkWiki
description	Use this skill when the user wants to create, maintain, query, or visualize a local Markdown knowledge base. ThinkWiki can initialize a wiki, import files or webpages, collect inbox items, answer from existing knowledge, save higher-value outputs, and generate HTML viewer and graph artifacts.
license	MIT
compatibility	Requires Python 3 with venv support. ThinkWiki bootstraps its own .venv, installs runtime dependencies from requirements.txt, and supports macOS, Linux, and Windows.

ThinkWiki

ThinkWiki is a single public skill for working with a local Markdown knowledge base.

Role

• Act as the end-user-facing knowledge base assistant.
• Translate user intent into stable ThinkWiki actions.
• Prefer natural conversation over exposing raw subcommands.
• Treat existing wiki pages as the primary evidence base for answers.
• Escalate to page creation only when the output is valuable enough to preserve.

Operating Principles

• Keep ThinkWiki as the only visible skill entry point.
• Resolve the wiki root before running any read, write, or generation task.
• Prefer evidence-first answers from existing pages.
• Prefer HTML deliverables such as inbox, viewer, graph, and governance pages when the user asks to inspect or browse the workspace.
• Surface ambiguity explicitly when confidence is low, sources conflict, or entity identity is unclear.

When To Use This Skill

• The user wants to create or maintain a local knowledge base.
• The user wants to import Markdown, PDF, DOCX, XLSX, XLS, PPTX, webpages, or plain text.
• The user wants to collect content into an inbox before formal ingest.
• The user wants to ask questions against an existing wiki.
• The user wants to save results as query, synthesis, decision, or concept pages.
• The user wants to generate a viewer, a graph, or a governance report.
• The user wants to review entity alias collisions or perform deterministic entity merges.

When Not To Use This Skill

• The task is unrelated to a local Markdown knowledge base.
• The user only wants general chat without knowledge capture, lookup, or maintenance.
• The task belongs to a different productivity domain such as spreadsheets, slides, or unrelated code work.

Required Environment Variables

Remote AI features are disabled by default. Configure only what you need.

Content generation (crystallize, digest)

Requires all three variables. Any OpenAI-compatible chat completion endpoint works.

Variable	Required	Used By	Notes
THINKWIKI_LLM_API_KEY	Yes, to enable	llm_client.py	API key for the configured LLM provider
THINKWIKI_LLM_BASE_URL	Yes, to enable	llm_client.py	Chat completions URL
THINKWIKI_LLM_MODEL	Yes, to enable	llm_client.py	Model name
THINKWIKI_LLM_TEMPERATURE	No	llm_client.py	Optional temperature override

Without a complete LLM configuration, crystallize and digest use local heuristics only.

Entity embedding (entity-merge-review, graph-report, health)

Enabled when THINKWIKI_EMBED_API_KEY is set. Defaults to SiliconFlow BGE-M3.

Variable	Required	Used By	Notes
THINKWIKI_EMBED_API_KEY	Yes, to enable	embed_client.py	API key for the embedding provider
THINKWIKI_EMBED_BASE_URL	No	embed_client.py	Default https://api.siliconflow.cn/v1/embeddings
THINKWIKI_EMBED_MODEL	No	embed_client.py	Default BAAI/bge-m3

Root Resolution

• If the user provides a wiki path, use it directly.
• If the working directory already contains .wiki-schema.md, treat that directory as the wiki root.
• If the user wants a new workspace, run init.
• If no wiki root can be found, ask the user where the wiki should live before making changes.

Execution Entry

When you need to invoke ThinkWiki, use the unified entry:

<python-command> scripts/thinkwiki <command> ...

Platform note:

• On macOS and Linux, <python-command> is usually python3.
• On Windows, <python-command> is usually python.

Intent Mapping

• Create a wiki -> init
• Warm up the runtime -> bootstrap
• Convert a file or webpage to Markdown -> convert
• Import a file or webpage into the wiki -> ingest
• Collect content into inbox first -> clip
• Build or refresh inbox review -> inbox
• Ask from existing wiki knowledge -> ask
• Save a correction or lesson learned -> correct
• Save a valuable answer -> query
• Create a concept, decision, or synthesis artifact -> crystallize or digest
• Build the graph explorer -> graph
• Build the graph governance report -> graph-report
• Review entity merge candidates -> entity-merge-review
• Preview or apply entity merges -> entity-merge-apply
• Browse HTML outputs in a browser -> serve
• Check workspace health -> health
• Check a compact workspace snapshot -> status
• Validate environment capabilities -> doctor

Browsing HTML Outputs

ThinkWiki HTML pages are static files under <wiki-root>/output/. Agent chat UIs usually cannot render them inline, so prefer the loopback HTTP server when the user wants to inspect or browse outputs.

Default workflow:

<python-command> scripts/thinkwiki serve --root <wiki-root>

This serves <wiki-root>/output/ at http://127.0.0.1:8765/ by default.

Useful URLs:

• Workspace home: http://127.0.0.1:8765/index.html
• Inbox review: http://127.0.0.1:8765/inbox/index.html
• Local viewer: http://127.0.0.1:8765/viewer/index.html
• Knowledge graph: http://127.0.0.1:8765/graph/index.html
• Graph report: http://127.0.0.1:8765/graph/report.html

OpenClaw integration:

• After viewer, graph, inbox, or graph-report, run serve when the user wants to browse the results.
• If the OpenClaw browser tool is available, open the workspace home URL in the openclaw browser profile.
• If a long-running serve process is not practical in the current session, run serve --print-urls and tell the user to start serve locally, then open the printed workspace URL.

Completion Criteria

• After initialization, report where the wiki was created.
• After import or capture, explain what was ingested or clipped and which artifacts were refreshed.
• After answer tasks, cite the relevant wiki pages and call out confidence or conflict where needed.
• After graph or viewer tasks, report the HTML artifact locations, especially output/index.html.
• When the user wants to browse inbox, viewer, graph, or governance pages, prefer serve and return the loopback HTTP URLs instead of only file:// paths.
• After starting serve, give the user the workspace home URL first (http://127.0.0.1:8765/index.html by default) and, in OpenClaw, offer to open it with openclaw browser --browser-profile openclaw open <url>.
• If the host cannot keep a long-running process alive, run serve --print-urls to show the URLs and ask the user to start serve in a local terminal or background job.
• After graph governance tasks, report the relevant governance outputs such as output/graph/report.html.
• After entity merge review, report how many ambiguous groups need manual confirmation and point to output/graph/entity-merge-review.html.
• After entity merge dry-runs, make it explicit that no entity pages were modified and point to output/graph/entity-merge-plan.html.
• After entity merge apply, report the canonical entity page, the merged pages, and the refreshed outputs.
• When execution fails, explain the missing input, root cause, or capability gap instead of only returning raw command errors.