Knowledge Connector

Knowledge Connector should feel like a product line, not another graph utility.

Its job is not just to extract concepts. Its job is to help the user:

• import notes and documents with low friction
• verify the connector is installed and writable before a long import
• search across multiple documents from one query
• visualize concept relationships in a way that is easy to inspect
• get actionable graph results such as what to connect, review, or expand next

What This Skill Optimizes For

Default toward five high-value outcomes:

• reliable first-run setup
• fast document import
• guided import onboarding
• cross-document knowledge retrieval
• relationship-aware graph views
• actionable next steps

Avoid drifting into “yet another adjacent knowledge skill”.

Primary Workflows

1. First-Run Check

Use kc doctor when:

• the user just installed the skill
• kc is not found or a command fails before doing useful work
• the user is about to import a large notes folder

Good doctor behavior means:

• confirm the data directory is writable
• confirm JSON stores are readable
• confirm the CLI entrypoint exists
• warn clearly if kc is not on PATH

If kc is not available, tell the user to reinstall or repair the Clawhub install before continuing with import/search commands.

If dependencies are missing but the files are present, node bin/cli.js doctor still works as a fallback diagnostic.

If the default data directory is not writable, set KC_DATA_DIR to a writable folder before running import/search commands.

2. Import Experience

Use kc import-docs when the user wants to build a graph from multiple files or a notes directory.

Use kc import-wizard when the user wants a preview-first onboarding flow.

Good import behavior means:

• accept files or a directory
• avoid duplicate source records when the same file is imported again
• preserve source titles and paths
• show how many documents, concepts, and relations were created
• keep the user oriented after import

3. Cross-Document Search

Use kc search or kc query when the user asks:

• where an idea appears across notes
• which documents mention a concept
• what concepts connect several documents

Results should show:

• matching concepts
• matching source documents
• matched keywords when helpful
• useful next actions

4. Relationship Visualization

Use kc visualize for full graph export and kc map for a concept-centered actionable subgraph.

Visualization should help the user answer:

• what is central
• what is weakly connected
• what deserves review

5. Actionable Results

Do not stop at “here is the graph”.

The output should usually recommend one or more actions such as:

• import more source material
• auto-connect newly imported concepts
• inspect a concept-centered subgraph
• verify weak relationships from source documents
• export a graph view for sharing or review

Core Commands

Import

kc doctor
kc import-wizard --dir notes/
kc import-docs --dir notes/
kc import-docs --files a.md b.md c.txt

Search

kc search "machine learning"
kc answer "哪些文档把强化学习和规划连在一起？"
kc query "transformer" --sources
kc query --ask "哪些文档同时提到了强化学习和规划？"

Map And Visualize

kc map --concept "人工智能" --depth 2
kc visualize --format html --output graph.html
kc visualize --concept "机器学习" --depth 2 --output ml-graph.html

Manage

kc stats
kc export --output backup.json
kc import --file backup.json

Output Standard

When the skill returns results, prefer this structure:

What Matched

Show concepts and source coverage.

Why It Matters

Explain the meaningful relationship or pattern.

Next Step

Tell the user what to do next with the graph.

Product Positioning

Knowledge Connector is strongest when the user has:

• a growing notes corpus
• repeated concepts spread across files
• a need to move from storage to understanding

It is weaker if it only acts like a raw extractor with no import flow, no source-aware search, and no next-step guidance.