English | 中文

relay-knowledge

relay-knowledge is a local-first knowledge substrate for graph-backed retrieval. It stores evidence, graph facts, code-repository structure, derived indexes, freshness state, diagnostics, audit records, and agent-facing context packs. It is not a general agent runtime or a final-answer generator.

Quick Start

The default local profile needs no external service: platform defaults select the runtime directories, SQLite stores local state, and deterministic local semantic/vector read models are enabled.

cargo build
target/debug/relay-knowledge status
target/debug/relay-knowledge ingest --source docs \
  --content "Rust async services isolate blocking SQLite work" \
  --entity Rust
target/debug/relay-knowledge query SQLite --source docs \
  --freshness wait-until-fresh

Use JSON for scripts and agent integrations:

target/debug/relay-knowledge status --format json
target/debug/relay-knowledge health --format json
target/debug/relay-knowledge help --format json

Installing Releases

GitHub Releases provide prebuilt archives for Linux x64/ARM64, macOS Intel/Apple Silicon, and Windows x64/ARM64. Verify the selected archive with checksums.txt before putting the binary on PATH; GitHub artifact attestations cover the same archive digests. Linux GNU archives target a glibc 2.31 baseline.

Rust users can install from crates.io:

cargo install relay-knowledge
relay-knowledge --version
relay-knowledge service doctor

Each release also publishes relay-knowledge-cli-skill-<tag>.tar.gz for agents that use the CLI instead of MCP/ACP. See the CLI skill package and the installation, release, and upgrade contract for platform details, verification, service installation, upgrade, rollback, and uninstall behavior.

Capability Snapshot

• Hybrid GraphRAG context packs combine BM25, local or external semantic/vector retrieval, graph evidence, freshness, bounded context, and ranking explanations.
• Structured evidence, entities, relations, claims, events, source spans, confidence, graph versions, and accepted/proposed grounding remain traceable.
• Repository workflows cover registration, tree-sitter indexing, full and incremental refresh, worktree overlays, symbols, references, calls, imports, context, impact, feature flags, SBOM evidence, and multi-repository sets.
• Durable bounded queues, leases, checkpoints, backpressure, recovery, and observable maintenance protect long-running indexing and background work.
• Software-wide projections and authorized local-file indexing expose dependencies, SDKs, files, topics, build/IaC/design evidence, and relationships without query-time repository scans.
• CLI, Web, MCP Streamable HTTP, and local ACP modes share the same application behavior, scope policy, QoS, cancellation, audit, and diagnostics.

Detailed behavior, limits, and implementation ownership belong in the linked responsibility-specific documentation, not in this navigation page.

Documentation

Two development-loop chapters have distinct responsibilities:

• Chapter 24: Code-Map-Backed Knowledge Development Loop
• Chapter 27: Business Knowledge to Technical Graph Mapping is the executable operating contract.
• Chapter 26: Git Commit + Knowledge Development Philosophy and Iteration Loop explains the commit fact boundary, derived knowledge, decision context, recovery model, and human-agent handoff philosophy.

Essential CLI Workflows

The machine-readable help surface is the command contract:

relay-knowledge help --format json
relay-knowledge help repo query --format json

Create and query knowledge:

relay-knowledge ingest --source docs \
  --content "Rust async services isolate blocking SQLite work" \
  --entity Rust
relay-knowledge query SQLite --freshness wait-until-fresh --format json
relay-knowledge graph inspect --format json

Register, index, and query a code repository:

relay-knowledge repo register /path/to/repository --path src --format json
relay-knowledge repo index repository --ref HEAD --format json
relay-knowledge repo status repository --format json
relay-knowledge repo query repository --query retry_policy \
  --kind definition --ref HEAD --path src --freshness wait-until-fresh \
  --limit 10 --format json
relay-knowledge repo software repository --kind relationships \
  --ref HEAD --format json

Indexing returns a durable task and makes progress observable through repo status. If a one-shot CLI cannot finish a large cold index before the caller times out, inspect status and use the bounded task worker or managed service recovery path documented in Code Repository Graph Workflow. Do not start unmanaged loops or competing writers.

Query a resident service without opening unrelated local state:

relay-knowledge --remote http://127.0.0.1:8791 \
  repo query repository --query retry_policy --kind definition \
  --freshness wait-until-fresh --format json

The full grammar, command-local --kind values, JSON schemas, read/write effects, and environment precedence are in the CLI Command Reference.

Resident Service and Agent Access

Start the shared Web/API service and opt into MCP Streamable HTTP:

RELAY_KNOWLEDGE_MCP_ALLOWED_SCOPES=docs \
  relay-knowledge service run --web --mcp streamable-http

The default Web endpoint is http://127.0.0.1:8791/; the MCP endpoint is http://127.0.0.1:8791/mcp. MCP is disabled unless requested, and graph tools require an allowed scope or an explicitly registered repository alias.

See Web Workspace, MCP and Agent Access, and Resident Service for session, authorization, cancellation, audit, service-manager, and diagnostics guidance.

Development

Use the repository scripts by responsibility:

./setup.sh
./build.sh
./run.sh start --port 8791 --daemon
./run.sh status
./run.sh stop --force
./check.sh

The principal local quality gates are:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --lib --bins --all-features
cargo test --test relay_knowledge --all-features
cargo test --test benchmarks --all-features
cargo test --test relay_knowledge architecture_boundaries --all-features
cargo llvm-cov --all-targets --all-features --fail-under-lines 90
python3 tools/docs/check_docs.py --self-test-and-check

Architecture boundaries, async and resource-budget requirements, unit-test coverage, documentation completeness, and the requirement that hand-written files stay below 1,000 lines are mandatory in Engineering Hard Constraints.

Self-Iteration Harness

The independent Rust harness for retrieval and indexing optimization is documented in tools/self_iteration:

./self-iterate.sh
./self-iterate.sh once
./self-iterate.sh loop --strategy unattended-layered
./self-iterate.sh chart

The default fast profile builds and evaluates the release product binary with focused gates and workload guardrails. Use ./self-iterate.sh once --profile full for the complete rails and workloads. Run history, reports, patches, and resume state stay under .git/relay-knowledge-self-iteration/. The harness documentation also records the exact pinned commits and reproducible detached-checkout preparation for external repositories.

Browser Checks

./build.sh
./run.sh start --port 8791 --daemon
curl http://127.0.0.1:8791/api/health
uv sync --extra dev --no-default-groups
uv run --extra dev python -m playwright install --with-deps chromium
uv run --extra dev pytest tests/browser

Runtime data, configuration, indexes, logs, and caches belong in the documented platform directories, not in the repository. Do not commit secrets, local databases, private datasets, or generated build output. See Installation and Runtime Directories.

Optional local hooks: pre-commit install and pre-commit run --all-files.