Basic Concepts

Basic concepts

Language: English · 简体中文

This page defines the terms used throughout the LWC documentation. Understanding the separation between canonical knowledge, derived indexes, and Agent workflow prevents most operational mistakes.

Wiki

An LWC Wiki is one SQLite database plus its rebuildable local projections. It stores immutable Sources, Agent-maintained Pages, citations, provenance, links, ingest state, retrieval state, and operation history.

The database is canonical. Do not edit wiki.db, its WAL files, generated Markdown, Work records, changeset databases, or graph sidecars by hand.

Scope

Scope answers where knowledge belongs.

Scope	Meaning	Typical content
project	The nearest initialized project Wiki discovered from the current directory	Repository architecture, local decisions, runbooks, project sources
global	The current user's cross-project Wiki	Stable preferences and reusable practices
all	A merged read view of project and global memory	Bounded search, context, tag listing, and strong-tag loading

all is not a canonical write target. Select project or global before enabling an optional recording mode on a read command. In normal project work, run lwc from the project directory. Set LWC_PROJECT_ROOT only when one command must target an explicitly selected project boundary; do not export it for routine use.

Purpose and schema

Every Wiki has two durable governance documents:

• Purpose states the Wiki's goal, important questions, and scope.
• Schema defines page types, provenance rules, linking conventions, and maintenance expectations.

Agents receive both documents during bounded context recall and source ingestion. They guide maintenance, but they never override system, user, repository, or host security instructions.

Source

A Source is an immutable UTF-8 snapshot of curated evidence. LWC identifies identical content by SHA-256 and separately records each observed path revision.

Adding a Source does not mean its knowledge has been integrated. It creates a pending ingest job. The Agent must read the complete source, analyze it, update the Wiki, and complete the job.

Page

A Page is maintained knowledge written by an Agent. It has:

• a stable slug;
• a title and one-line summary;
• a kind such as source, concept, entity, query, comparison, or synthesis;
• a Markdown body;
• citations to Sources;
• explicit provenance for knowledge that does not come from an immutable Source;
• outgoing Wiki links.

A kind=source page summarizes one Source for navigation. Shared knowledge belongs in non-source pages so that later evidence can revise the same concept instead of creating another detached summary.

Provenance and citations

Provenance explains why a page may make a claim.

Value	Meaning
source-grounded	Derived automatically when the Page cites one or more Source IDs
user-provided	The user stated the durable fact or decision
agent-observed	The Agent verified the fact from current authorized evidence
hypothesis	A useful but unverified possibility, clearly labelled as such

Never invent a Source citation. Do not store secrets, raw hidden reasoning, or unsupported guesses as facts.

Ingest job

An ingest job is the durable state machine that turns one Source into maintained knowledge:

pending -> analyzing -> generating -> completed
                      \-> failed -> pending (retry)

Completion normally requires both a cited source-summary Page and a cited non-source Page. If a Source genuinely adds no shared knowledge, the Agent records a specific audited reason instead of creating filler.

Search, context, and spans

• context returns the Purpose, Schema, Page index, and recent operations within a fixed limit.
• search uses deterministic lexical retrieval and returns maintained Pages before raw Sources by default.
• span resolves exact sentence or passage locators and expands nearby context.

Span locators include a document fingerprint. When a Page changes, an old locator fails with stale_span; LWC does not silently map it to similar text.

Links and the document graph

Wiki links express maintained page-to-page relationships. Citations connect Pages to Sources. LWC can project these facts, plus explicit semantic relations, into an optional document graph.

The graph is a derived index. Enable it only when traversal, path, neighborhood, impact, or visual exploration is useful. graph verify compares the projection with canonical SQLite state.

CodeGraph

CodeGraph is a separate project-local index for checked-out code. It answers questions about files, symbols, definitions, callers, callees, dependencies, and impact. It is not the document graph and it is never registered as a second Agent MCP.

The runtime is downloaded once per user and version; each project keeps its own index under .lwc/codegraph.

Word Graph

Word Graph connects documents through shared tokenized terms. Token relationships are extremely dense, so LWC never loads the complete word network in one request. Queries require bounded terms, document limits, pagination, and server-side clamping. Treat the result as an exploratory sample, not a complete semantic graph.

Strong tags

A strong tag is an explicit membership list for a small set of core Pages. lwc load tag selects the highest-priority memberships up to a limit and returns each selected Page in full.

Strong tags are appropriate for rules and runbooks that must load deterministically. They are not search keywords and are not inferred from token frequency.

Changeset

A changeset is an isolated sparse draft for a logical update that spans several mutations. The Agent can inspect, search, and lint the draft before publishing it atomically.

Commit records a guarded inverse patch and returns a changeset ID. Immediate rollback is allowed only while touched live entities remain unchanged. There is no force option.

Work

Work is a durable background task record used for graph projection and maintenance. A command that returns a Work ID has queued activity; process exit does not prove the operation is complete.

Use work status or work watch and require state=succeeded. Failed or cancelled Work remains inspectable and may support an explicit resume.

Checkpoint

A checkpoint is a validated full SQLite backup. Restore first preserves the current Wiki as a safety checkpoint, then restores and rebuilds derived material. Use checkpoints for large direct maintenance operations that cannot fit in a changeset.

Agent integration

LWC Agent integration has four main surfaces:

• MCP: one read-only lwc_explore tool for bounded memory, code, or combined exploration;
• Skill: detailed guidance about when and how an Agent should use LWC;
• Hooks: bounded readiness and strong-tag context at supported lifecycle events;
• Instructions: a marked guidance block in the host's official global or project instruction file.

AgentTarget adapters install only surfaces officially supported by each host and report UI-owned, preview, or unavailable capabilities explicitly.

Next: Use cases