中文 | English

KWeaver Core is a harness-first foundation for enterprise decision agents. It turns fragmented data, knowledge, tools, and policies into governed context, safe execution, and verifiable feedback loops. With semantic modeling, real-time access, runtime control, and TraceAI, it helps AI systems reason, adapt, and act reliable in complex enterprises.

Note: KWeaver Core is a backend-only framework — it does not include a web UI. All interactions are through the CLI, SDK, or API. If you need a graphical interface, please install KWeaver DIP.

• 🌐 KWeaver DIP - Web UI for KWeaver (username: kweaver, password: 111111)
• 🤝 Contributing - Guidelines for contributing to the project
• 🚢 Deployment - One-click deploy to Kubernetes
• 📘 Documentation - Product documentation and usage guides (EN / 中文)
• 📝 Blog - KWeaver technical articles and updates
• 🚀 Release Guidelines - Version management and release process
• 🏗️ Architecture - Architecture design specification
• 🧾 Release Notes - All notable changes
• 📄 License - Apache License 2.0
• 🐛 Report Bug - Report a bug or issue
• 💡 Request Feature - Suggest a new feature

Watch the KWeaver demo on Bilibili.

1. Source deployment: see the Deployment Guide.
2. Prerequisites: follow the prerequisites described in deploy/README.md.
3. Run installation scripts:

git clone https://github.com/kweaver-ai/kweaver-core.git
cd kweaver-core/deploy
chmod +x deploy.sh

# Minimum installation — recommended for first-time experience
./deploy.sh kweaver-core install --minimum
# Equivalent to:
# ./deploy.sh kweaver-core install --set auth.enabled=false --set businessDomain.enabled=false

# Full installation (includes auth & business-domain modules)
./deploy.sh kweaver-core install

# Or specify addresses explicitly (skips interactive prompts):
#   --access_address       Address for clients to reach KWeaver services (can be IP or domain)
#   --api_server_address   IP bound to a local network interface for K8s API server (must be a real NIC IP)
./deploy.sh kweaver-core install \
  --access_address=<your-ip> \
  --api_server_address=<your-ip>

./deploy.sh --help

4. Verify the deployment:

# Check cluster status
kubectl get nodes
kubectl get pods -A

# Check service status
./deploy.sh kweaver status

5. Verify API access:

kweaver auth login https://<node-ip> -k
kweaver bkn list

6. View help:

kweaver --help                   # list all commands
kweaver <command> --help         # help for a specific command, e.g. kweaver bkn --help

For full product documentation, see the Documentation (EN / 中文).

No deployment yet? Use the KWeaver DIP web UI to try KWeaver online (username: kweaver, password: 111111), or connect your CLI/SDK directly to the demo environment (see below).

After deploying KWeaver Core, we recommend installing kweaver-sdk as your next step. The SDK provides the kweaver CLI and AI Agent Skills — the primary way to interact with the platform.

kweaver-sdk gives AI agents (Claude Code, GPT, custom agents, etc.) access to KWeaver knowledge networks and Decision Agents via the kweaver CLI. It also provides Python and TypeScript SDKs for programmatic integration.

Install the CLI with:

npm install -g @kweaver-ai/kweaver-sdk

Or run it without a global install:

npx kweaver --help

Install skills from kweaver-sdk with npx skills.

Install both skills at once (recommended):

npx skills add https://github.com/kweaver-ai/kweaver-sdk \
  --skill kweaver-core --skill create-bkn

• kweaver-core — full KWeaver APIs and CLI conventions so assistants can operate KWeaver on your behalf. See skills/kweaver-core/SKILL.md.
• create-bkn — guided workflow and tooling to create and manage Business Knowledge Networks (BKN) from your AI coding assistant. See skills/create-bkn/SKILL.md.

Install a single skill only (optional):

npx skills add https://github.com/kweaver-ai/kweaver-sdk --skill kweaver-core
# or
npx skills add https://github.com/kweaver-ai/kweaver-sdk --skill create-bkn

Before using any skill, authenticate with your KWeaver instance:

kweaver auth login https://your-kweaver-instance.com

Self-signed certificate? If your instance uses a self-signed or untrusted TLS certificate (common for fresh deployments without a CA-issued cert), add -k to skip certificate verification:

kweaver auth login https://your-kweaver-instance.com -k

No deployment needed — connect your AI agent to the demo environment and start exploring immediately (for the web UI, visit KWeaver DIP):

npx skills add https://github.com/kweaver-ai/kweaver-sdk \
  --skill kweaver-core --skill create-bkn

npm install -g @kweaver-ai/kweaver-sdk
kweaver auth login https://dip-poc.aishu.cn -k

Then ask your AI agent (Cursor, Claude Code, etc.) using natural language:

List all knowledge networks
What object types are in the supply chain knowledge network?
Search the supply chain knowledge network for "supply chain risks"
Show 2 sample customer records
List all Decision Agents
Chat with Agent xxx, ask "What is the current inventory status?"

Or use /kweaver-core slash commands (the skill takes over automatically):

/kweaver-core List all knowledge networks
/kweaver-core What's in the supply chain knowledge network?
/kweaver-core Search knowledge network for "supply chain risks"
/kweaver-core Show 2 sample customer records from the knowledge network
/kweaver-core List all Decision Agents
/kweaver-core Chat with Agent <agent-id>, ask "What is the current inventory status?"

Demo credentials: username kweaver, password 111111

The npm kweaver CLI supports authenticating without a local browser or without pasting callback URLs. Three methods are available:

Method 1 — --no-browser (recommended for interactive headless sessions)

kweaver auth login https://your-instance --no-browser

The CLI prints an OAuth URL instead of opening a browser. Copy that URL and open it on any device with a browser (phone, laptop, etc.). After login the browser redirects to a localhost callback URL — it will show an error page (this is expected). Copy the full URL from the address bar and paste it back into the CLI prompt:

Open this URL on any device (use a private/incognito window if you need the full sign-in form):

  https://your-instance/oauth2/auth?redirect_uri=...&client_id=...

After login, the browser may show an error page (this is expected if nothing listens on localhost).
Copy the FULL URL from the address bar and paste it here, or paste only the authorization code.

Paste URL or code>

Method 2 — Export & replay credentials (for CI / fully non-interactive)

1. On a machine with a browser, run kweaver auth login https://your-instance. After success, export credentials:

kweaver auth export              # prints a one-line command you can paste on the headless host
kweaver auth export --json       # JSON format (useful for CI secrets)

2. On the headless host, paste the exported command. It uses --client-id, --client-secret, and --refresh-token to exchange tokens and save credentials under ~/.kweaver/:

kweaver auth login https://your-instance \
  --client-id <ID> --client-secret <SECRET> --refresh-token <TOKEN>

Method 3 — Playwright + username/password (fully non-interactive on the host, no callback paste)

When the machine can run Node and download a Chromium build (typical CI agents and Linux containers), you can complete the same OAuth2 authorization-code flow as the GUI login, but with Playwright driving a headless browser and filling the platform sign-in form:

npm install playwright && npx playwright install chromium   # once per environment
kweaver auth login https://your-instance -u <username> -p <password> -k

-u / -p together select this path automatically (no need for --playwright). The CLI registers the OAuth client, opens the auth URL, submits credentials, and saves tokens under ~/.kweaver/ including a refresh_token when the IdP returns one — same auto-refresh behavior as a normal browser login.

Use --playwright without -u/-p if you want Playwright to open a visible browser window and you sign in manually (useful when debugging or when the login UI is not the default account/password form).

With saved ~/.kweaver/ sessions, the CLI automatically exchanges refresh_token for a new access token when it expires — no extra flags needed. You can also set environment variables (KWEAVER_BASE_URL, KWEAVER_TOKEN) instead of persisting credentials to disk.

Full details: kweaver-sdk — Authentication and Headless / Server Authentication. The Python kweaver CLI still uses interactive browser login; reuse the ~/.kweaver/ directory from a machine where the Node CLI finished login, or set the environment variables above.

kweaver auth login https://your-kweaver.com     # authenticate (-k for self-signed certs)
kweaver bkn list                                 # browse knowledge networks
kweaver bkn search <kn-id> "query"              # semantic search over a BKN
kweaver bkn build <kn-id> --wait                # rebuild index and wait for completion
kweaver bkn object-type list <kn-id>            # inspect object types
kweaver bkn action-type execute <kn-id> <at-id> # execute an action
kweaver agent list                               # list Decision Agents
kweaver agent chat <agent-id> -m "Hello"        # chat with an agent
kweaver ds import-csv <ds-id> --files "*.csv"   # import CSV files into a datasource
kweaver context-loader kn-search "query"        # semantic search via Context Loader
kweaver call /api/...                            # raw API call

Simple API (recommended):

import kweaver from "@kweaver-ai/kweaver-sdk/kweaver";
kweaver.configure({ config: true, bknId: "your-bkn-id", agentId: "your-agent-id" });

const results = await kweaver.search("What risks exist in the supply chain?");
const reply   = await kweaver.chat("Summarise the top 3 risks");
await kweaver.weaver({ wait: true });   // rebuild BKN index

import kweaver
kweaver.configure(config=True, bkn_id="your-bkn-id", agent_id="your-agent-id")

results = kweaver.search("What risks exist in the supply chain?")
reply   = kweaver.chat("Summarise the top 3 risks")

Full client API (advanced):

import { KWeaverClient } from "@kweaver-ai/kweaver-sdk";
const client = new KWeaverClient();   // reads ~/.kweaver/ credentials

const kns   = await client.knowledgeNetworks.list();
const reply = await client.agents.chat("agent-id", "Hello");
await client.agents.stream("agent-id", "Hello", {
  onTextDelta: (chunk) => process.stdout.write(chunk),
});

from kweaver import KWeaverClient, ConfigAuth
client = KWeaverClient(auth=ConfigAuth())
kns  = client.knowledge_networks.list()
msg  = client.conversations.send_message("", "Hello", agent_id="agent-id")

KWeaver Core is the AI-native platform foundation for autonomous decision-making. It sits between AI Agents (above) and AI/Data infrastructure (below), with the Business Knowledge Network (BKN) at its center, providing unified data access, execution, and security governance for Agents.

            ┌─────────────────────────────────┐
            │     AI Agents (Decision Agent,   │
            │     Data Agent, HiAgent, ...)    │
            └───────────────┬─────────────────┘
                            │
            ┌───────────────▼─────────────────┐
            │     Business Knowledge Network   │
            │         KWeaver Core             │
            └───────────────┬─────────────────┘
                            │
            ┌───────────────▼─────────────────┐
            │   AI Infrastructure & Data       │
            │   Infrastructure                 │
            └─────────────────────────────────┘

KWeaver Core solves two critical pain points when connecting proprietary data with autonomous AI Agents:

In long-running agent scenarios, context inevitably faces explosion, decay, pollution, and high token costs. KWeaver Core addresses these through the Business Knowledge Network:

• Context explosion containment — Multi-source candidates are first organized and aggregated via the BKN semantic network, then unified by Context Loader (recall → coarse ranking → fine ranking) to retain only key evidence and constraints, avoiding massive prompt fragments that cause decision drift. Overall accuracy reaches 93%+.
• Context decay mitigation — Replaces long-text stacking with "real-time facts + evidence citations", keeping reasoning grounded around specific objects and reducing forgetting and hallucination risks in long inputs. Accuracy improves 15%+ over baselines across scenario types.
• Context pollution isolation — Builds precise enterprise digital twins through the BKN network, blocking unreliable content and potential injection risks outside the knowledge and execution boundary, ensuring a clean and controllable reasoning chain.
• Token cost compression — Converts multi-source materials into structured object information fetched on demand (not full-text concatenation), improving information density within the same budget. Token consumption reduced 30%+ while improving accuracy.

Beyond "seeing more", Agents must "do it right". KWeaver Core provides constraint engineering capabilities for enterprise-grade safe execution:

• Explainable decisions — Uses "Object → Action → Rule → Constraint" knowledge structures to express business intent graphs, grounding tool invocation and parameter selection to explicit semantic boundaries and rule dependencies, making it clear "why this action was taken".
• Traceable evidence chain — From action intent → knowledge node → data source → mapping/operator → final invocation, full-chain tracing is supported. Entities and relationships can be traced back to source data and active rules, enabling audit and review.
• Controllable execution loop — Unifies identity and access control down to knowledge network object/action permissions, with pre-execution validation, mid-execution policy interception, and post-execution audit logging, achieving "authorizable, approvable, revocable" security loops.
• Risk prevention mechanism — Models risks as "Risk Types" linked to Action Types; performs risk assessment and simulation before execution, with automatic downgrade/blocking/secondary confirmation when thresholds are hit, blocking high-risk actions before they execute.

┌──────────────────────── KWeaver Core ────────────────────────┐
│         │                                          │         │
│         │  Decision Agent                          │         │
│  Info   │  (Dolphin Runtime / Agent Executor)       │  Trace │
│  Secu-  │──────────────────────────────────────────│         │
│  rity   │                                          │   AI    │
│         │  AI Data Platform                        │         │
│ Fabric  │  ┌────────────────────────────────────┐  │  Obse-  │
│         │  │ Context Loader                     │  │  rvab-  │
│ (ISF)   │  │  ┌───────────┐   ┌─────────────┐  │  │  ility  │
│         │  │  │ Retrieval │ → │   Ranker    │  │  │    /    │
│ Access  │  │  └───────────┘   └─────────────┘  │  │  Evid-  │
│ Control │  ├────────────────────────────────────┤  │  ence   │
│    /    │  │ Business Knowledge Network         │  │         │
│ Secu-   │  │  ┌────────────────────────────┐    │  │         │
│  rity   │  │  │ BKN Engine                 │    │  │         │
│         │  │  │ (Data/Logic/Risk/Action)    │    │  │         │
│         │  │  └──────┬─────────────┬───────┘    │  │         │
│         │  │         ↓ mapping     ↓ mapping    │  │         │
│         │  │  ┌────────┐ ┌───────────┐ ┌──────┐ │  │         │
│         │  │  │  VEGA  │ │ Execution │ │ Data │ │  │         │
│         │  │  │ Engine │ │  Factory  │ │ flow │ │  │         │
│         │  │  └────────┘ └───────────┘ └──────┘ │  │         │
│         │  └────────────────────────────────────┘  │         │
│         │                                          │         │
└─────────┴──────────────────────────────────────────┴─────────┘
               ↕                ↕                ↕
       Multi-source & Multi-modal Data (30+ data sources)

BKN Lang is a Markdown-based business knowledge modeling language, designed for human-machine bidirectional friendliness:

• Easy to develop — Based on standard Markdown syntax, eliminating code barriers entirely. Business experts write, read, and modify definitions via WYSIWYG editors, with rapid version diff and collaborative review — modifying system rules is like editing a document.
• Easy to understand — "Object-Relationship-Risk-Action" four-in-one model perfectly maps enterprise business models. Humans read business semantics; Agents parse precise context constraints in real-time. Logic is made explicit, rejecting black boxes, fundamentally reducing LLM reasoning hallucination and logical deviation.
• Easy to integrate — Definitions stored as full-text in specific database fields with no complex underlying table coupling. Context Loader dynamically loads on demand, discarding static hardcoding. Plug-and-play across systems and Agents, flowing as lightweight assets through AI Data Platform.

See more details: KWeaver Blog

Based on 145 HR scenario samples (resume corpus with 118 multi-format PDFs), covering simple information lookup, cross-section experience analysis, and multi-hop comprehensive reasoning. All platforms used DeepSeek V3.2 + BGE M3-Embedding with identical data sources, tested in Agentic mode.

KWeaver Core is the only platform that breaks the traditional RAG "performance impossible triangle" — achieving >99% accuracy while keeping inference cost and latency at production-ready levels. Dify trades high token consumption (1.7x) for decent accuracy; BiSheng sacrifices reasoning depth for speed; RAGFlow falls behind on both accuracy and latency.

The following ablation experiments identify the contribution of each KWeaver Core component:

Retrieval Depth — Increasing retrieval limit from 10 to 20 raised accuracy from 96.67% to 100%, with only +6.48s latency. Context Loader's semantic reranking and compression enable KWeaver Core to effectively handle the increased context without "Lost in the Middle" effects.

Schema Preloading — With Context Loader preloading the BKN schema:

Schema provides Agents with a clear "map" of entity relationships, reducing reasoning steps by 44.8% and token consumption by 47.9%.

Tool Curation — Precise tool selection outperforms providing all available tools:

With excessive tools, Agents favor "seemingly powerful" broad-search tools whose noise triggers reflection loops and path divergence. Curated tools constrain Agents onto the correct path, achieving one-shot resolution.

Path Guidance — Encoding domain expert experience into executable reasoning templates:

Path guidance tells Agents "how to walk" for efficiency; tool curation "reduces wrong turns" for stability. Combined, they deliver optimal production performance.

F1 Bench is based on the BIRD test set with the Formula-1 database mixed with 30 unstructured documents, testing Agent capabilities in structured + unstructured heterogeneous data reasoning.

Scan to join the KWeaver community group

• Contributing: Contributing Guide
• Issues: GitHub Issues
• License: Apache License 2.0

More components will be open-sourced in the future. Stay tuned!