LWC

This project adapts those ideas into an agent-first Rust CLI backed by SQLite.

The persistent knowledge model has four logical layers:

SQLite is canonical. The Markdown tree is a rebuildable projection for people and tools such as Obsidian. Agents mutate knowledge throughlwc, not by editing.lwc/wiki.dbor projected Markdown directly. Successful commands return JSON on stdout; failures return structured JSON on stderr.

Read commands keep current-format stores read-only. When an older writable store is opened by a newer CLI, its schema is migrated transactionally once before the read proceeds.

Every current Source and Wiki page is deterministically indexed as passages and sentences. SQLite remains authoritative; span FTS and an optional external document graph are rebuilt indexes. Existing search stays document-only unless a granularity is requested:

lwc search "projection consistency" --granularity sentence --type page lwc search "projection consistency" --granularity passage lwc search "projection consistency" --granularity all --group-by document lwc span get <SPAN_ID> lwc span expand <SPAN_ID> --before 1 --after 1 --children 20

Span locators contain the document fingerprint and segmentation version. A locator from a replaced body fails withstale_spanand reports prior/current metadata; LWC never silently remaps it to similar text.

Use the bounded, typed graph API for exploration without requiring keywords:

lwc graph explore # representative macro view lwc graph node page:projection-policy lwc graph neighbors page:projection-policy --direction outgoing lwc graph path page:implementation page:policy --max-depth 6 lwc graph impact page:policy --max-depth 4 lwc graph overview lwc graph status lwc graph verify

Automatic edges are limited to structural/evidential facts. Semantic claims must be explicit and auditable:

lwc graph relation set page:implementation DEPENDS_ON page:policy \ --provenance source-grounded --source 12 \ --reason "Source 12 states the required policy" --confidence 0.95 lwc graph relation list --from page:implementation lwc graph relation retract page:implementation DEPENDS_ON page:policy \ --reason "The dependency was superseded"

Relation reasons are durable content: never put credentials, secrets, or raw chain-of-thought in them.

SQLite documents remain authoritative. Graph storage is disabled by default; enable exactly one external engine when traversal is needed. Configuration is layered from built-in defaults through global and project files:

lwc config show lwc config set --graph grafeo lwc config set --graph surrealdb lwc config set --graph disabled lwc config unset --graph

Markdown conversion is a separate opt-in operation.lwc initreports the same machine-readable setup guidance, but never installs or enables a converter. Install one adapter, select it explicitly, convert to a new local Markdown file, review it, and only then ingest it:

OfficeCLI reading is a separate global, opt-in capability. When an Office read is needed, enable it once; the first command downloads the pinned binary into the versioned global LWC runtime cache and verifies its SHA-256:

Grafeo and embedded SurrealDB use disposable sidecars under.lwc/. Eachgraph-projectWork commits one current Source/Page and its owned links, citations, and explicit relations before starting the next document. Updates and deletions enqueue only touched documents; rebuild and resume use the same document units. Historical source revisions remain immutable and are never re-tokenized or projected. Usework list,work status, orwork watchto observe progress andwork resumeafter interruption.graph statusreports the selected engine and projected document count;graph verifycompares its current document keys with SQLite.

Most users should use the Agent setup prompt above. The manual commands below are for maintainers, debugging, or Agent environments that cannot install the companion Skill.

Install with Homebrew (prebuilt bottles are available for Apple silicon macOS and x86_64 Linux):

curl --proto '=https' --tlsv1.2 -fsSL https://github.com/JanYork/llm-wiki-cli/releases/latest/download/install.sh | sh

The installer supports x86_64/aarch64 macOS, glibc Linux, and Windows Git Bash, verifies the release checksum, and installs or updateslwc. It uses~/.local/binby default, or updates an existing copy in~/.local/binor~/.cargo/bin. To choose another directory:

curl --proto '=https' --tlsv1.2 -fsSL https://github.com/JanYork/llm-wiki-cli/releases/latest/download/install.sh | LWC_INSTALL_DIR="$HOME/bin" sh

Alternatively, build and install from GitHub with Cargo:

cargo install --locked --git https://github.com/JanYork/llm-wiki-cli

git clone https://github.com/JanYork/llm-wiki-cli.git cd llm-wiki-cli cargo install --locked --path .

npx skills add JanYork/llm-wiki-cli --skill using-lwc -g

Or copy it from a local checkout into the current Agent runtime's user-level Skills directory. For Codex:

mkdir -p "$HOME/.agents/skills" cp -R skills/using-lwc "$HOME/.agents/skills/"

The canonical invocation is$using-lwc.

- finds a compatible CLI or installs the official checksum-verified release;
- initializes global memory in~/.lwc/once;
- recalls bounded global and project context before repeated investigation;
- initializes the active project on explicit invocation, otherwise asks first;
- refuses project writes outside the current authorized workspace root;
- separates project facts from reusable global knowledge;
- integrates sources and writes durable answers back into the Wiki.

SKILL.mdis a short router rather than a monolithic manual. It links one focused teaching document for basic memory, trigger timing, active memory, physical document graph, bounded Word Graph, CodeGraph, strong tags, document conversion, Agent onboarding, and recovery/maintenance. Each document states when to use and skip the capability, its minimum workflow, consent boundary, and completion evidence.

The Skill normally discovers the active project from the current directory and invokes the globally installedlwccommand directly.LWC_PROJECT_ROOTis an explicit boundary for a deliberately targeted project, not a prefix to export for routine commands in the project you are already working in.

SetLWC_AUTO_INSTALL=0to disable automatic CLI installation. Automatic installation executes the reviewed installer bundled in the Skill, trusts this repository and its GitHub Release publishing boundary, and verifies the downloaded archive againstSHA256SUMS; the checksum is integrity protection, not publisher code signing. Release binaries cover x86_64/aarch64 macOS, glibc Linux, and Windows through Git Bash.SKILL.mdfollows the Agent Skills resource layout, whileagents/openai.yamlsupplies OpenAI/Codex metadata. The CLI itself is runtime-neutral: any Agent that can execute it and load or adapt the Skill's instructions can use LWC. Skill commands, global instructions, and Hooks remain runtime-specific, so the setup prompt detects and configures the current host.

LWC can detect supported Agents and install one unified read-only LWC MCP. All 12 registered AgentTargets are strong adapters: each installs every official file-based MCP, Skill, Hook, and Instructions surface available for that host and scope, while UI-owned, preview, or unsupported surfaces are reported explicitly.

lwc agent install --yes lwc agent status --target all --location global lwc agent install --print-config codex lwc agent refresh --target codex,claude lwc agent uninstall --target codex,claude --yes

--yesselects detected Agents, global scope, and each target's default lifecycle/prompt Hooks. Use--no-prompt-hookto omit Claude's per-prompt Hook. The installed entry islwc -> serve --mcp; its singlelwc_exploretool defaults to bounded Wiki memory and accepts explicitcode/allmodes. The requestedprojectPathmust stay inside the workspace where the MCP host started LWC. It never downloads or initializes CodeGraph. Repeated install and refresh are byte-idempotent; uninstall restores only owned state and leaves project indexes intact. Optional Codex, Claude Code, and Pi packages live underintegrations/; installing a package does not grant or bypass native trust. Do not combine the direct installer and native package for the same Agent. Each native package bundles the completeusing-lwcSkill, so installation does not depend on a third-party Skill manager or any maintainer-specific environment.

Pi exposes LWC MCP through its official extension bridge because Pi has no built-in MCP. Other Targets register onlylwc serve --mcp; CodeGraph stays an internal LWC code-context plane and is never registered as a second Agent MCP. Officially UI-owned trust and permission settings remain user-managed. Preview surfaces are labeled as such, and partial project scopes install the supported surfaces instead of weakening or rejecting the whole Target. Kiro global paths honorKIRO_HOME.

Fresh projectlwc initoutput and session/compaction Hooks expose boundedLWC_READINESSfacts for the Wiki, physical document graph, CodeGraph runtime and project index, optional Office capability, plus Agent integration commands. Physical graph readiness distinguishes configured consent from a pending or failed projection. Detection is read-only and never enables or initializes a graph. When both graphs need authorization, the portable baseline is plain text, so Agents without checkbox support behave the same way:

1. Enable physical document graph and CodeGraph (recommended) 2. Enable physical document graph only 3. Enable CodeGraph only 4. Later

After explicit choice1, the Agent initializes a missing project Wiki, enables Grafeo, waits for and verifies its projection Work, initializes CodeGraph, and checks both results independently.Laterchanges nothing and does not block the primary task. Native plugins may render the same choice IDs with their own UI, but checkbox support is never required.

When an actual Word, Excel, or PowerPoint read is requested, Agents inspectLWC_READINESS.officeand ask before globally enabling OfficeCLI. Readiness detection itself never enables or downloads the runtime.

Strong tags provide bounded full-page loading for core rules and runbooks:

lwc tag set "operations" incident-response --priority 100 --reason "primary runbook" lwc load tag "operations" --limit 3 lwc tag autoload "operations" --enable --priority 100 --limit 3 \ --max-chars 50000 --reason "required at session boundaries"

This is an explicit strong-load mechanism, not token-derived search: limits and character budgets are applied before complete pages enter Agent context.

This section documents the CLI protocol that the Agent executes. Humans do not need to run these commands during normal use.

cd your-project lwc init printf '# Schema\nEvery page declares provenance; source-grounded claims cite sources.\n' | lwc schema set - printf '# Purpose\nBuild a durable project Wiki.\n' | lwc purpose set -

Project initialization adds the project-relative.lwc/path to Git's localinfo/excludefile when needed, without changing the repository.gitignore. Uselwc init --no-git-excludeonly when the Wiki is intentionally versioned.

Files without an explicit title use their source origin as a stable, human-readable fallback. Identical bytes are deduplicated by SHA-256. Project sources that resolve outside the active Wiki root require--allow-external-source. High-confidence credential markers are rejected unless the reviewed source is explicitly acknowledged with--acknowledge-sensitive-source.

Each successful add also records the observed file path and its current immutable snapshot. Check only the sources relevant to the task before relying on file-backed evidence:

The command streams each live file through SHA-256 and reports path lineage (currentorsuperseded) separately from filesystem state (current,modified,missing,unreadable,oversized, orunstable). It is read-only. Usesource status --allonly for explicit maintenance because its cost is proportional to the bytes in all tracked files. Inspect a modified path before updating knowledge:

lwc source diff 7 lwc source refs 7 --limit 1000

source diffcompares the immutable source with its live file, or with another snapshot via--to-source. It returns a bounded unified diff: at most 8 MiB and 200,000 lines per side, 20,000 Unicode output characters by default, and 100,000 with--max-chars. If one source was observed at multiple paths, select an exact--path. A truncated diff is only a preview.source refslists directly citing review candidates; it does not prove which pages are semantically affected. Re-runsource addonly after review when the same path contains a meaningful new revision. An A -> B -> A sequence remains three path observations even though content A reuses its original source ID. External live paths require--allow-external-sourceagain; flagged live text also requires--acknowledge-sensitive-sourceafter inspection.

Sources migrated from older stores remain explicitly untracked because LWC does not guess historical paths; re-add the intended file once to establish its first tracked revision. If a file or path head changes during the check, LWC returnssource_status_unstable; retry instead of trusting a mixed-time result.

For a curated atomic import, paths in a JSON manifest resolve from the manifest's directory: