# 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.
```bash
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:
```bash
target/debug/relay-knowledge status --format json
target/debug/relay-knowledge health --format json
target/debug/relay-knowledge help --format json
```
## Installing Releases
Version 1.1.17 introduces Repository Map v4 with the latest 16 history entries.
See the [1.1.17 release notes](pages/en/releases/1.1.17.html) for migration,
backup, and installation guidance.
[GitHub Releases](https://github.com/coolplayagent/relay-knowledge/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.28 baseline.
Rust users can install from crates.io:
```bash
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](skills/relay-knowledge-cli/README.md) and the
[installation, release, and upgrade contract](docs/en/03-architecture-specs/19-installation-release-and-upgrade.md)
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.
- Remote embedding and provider HTTP always pass through shared QoS admission;
rejection, timeout, cancellation, and permit release remain observable.
- Software-wide projections and authorized local-file indexing expose typed
systems, APIs, resources, tests, build/deployment/release evidence,
provenance statements, conflicts, and legacy-compatible slices without
query-time repository scans. The Web Software page reads that same bounded,
snapshot-pinned application service.
- 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
| Complete bookshelf | [English documentation](docs/en/README.md) |
| User workflows | [User Guide](docs/en/01-user-guide/README.md) |
| Implemented behavior | [Capabilities](docs/en/02-capabilities/README.md) |
| Architecture contracts | [Architecture Specifications](docs/en/03-architecture-specs/README.md) |
| Mandatory engineering rules | [Engineering Hard Constraints](docs/en/03-architecture-specs/02-engineering-hard-constraints.md) |
| Research and external evidence | [Research](docs/en/04-research/README.md) |
| Performance and self-iteration contracts | [Benchmarks](docs/en/05-benchmarks/README.md) |
| Auditable verification records | [Verification](docs/en/06-verification/README.md) |
Two development-loop chapters have distinct responsibilities:
- [Chapter 24: Code-Map-Backed Knowledge Development Loop](docs/en/03-architecture-specs/24-code-map-backed-knowledge-development-loop.md)
- [Chapter 27: Business Knowledge to Technical Graph Mapping](docs/en/03-architecture-specs/27-business-knowledge-technical-mapping.md)
is the executable operating contract.
- [Chapter 26: Git Commit + Knowledge Development Philosophy and Iteration Loop](docs/en/03-architecture-specs/26-git-commit-knowledge-development-loop.md)
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:
```bash
relay-knowledge help --format json
relay-knowledge help repo query --format json
```
Create and query knowledge:
```bash
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:
```bash
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 framework repository --framework vue --kind component \
--ref HEAD --path src --freshness wait-until-fresh --format json
relay-knowledge repo software repository --kind relationships \
--ref HEAD --format json
relay-knowledge repo software repository --kind statements \
--ref HEAD --format json
relay-knowledge repo software export repository --profile cyclonedx-1.7 \
--ref HEAD --format json
```
Software responses retain stable entity identity, snapshot occurrences,
statement provenance, freshness, completeness, and conflicts. Dockerfiles and
CI jobs are build surfaces rather than IaC resources, and ordinary README
headings remain documentation unless controlled metadata promotes them.
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](docs/en/01-user-guide/05-code-repository-graph-workflow.md).
Do not start unmanaged loops or competing writers.
Query a resident service without opening unrelated local state:
```bash
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](docs/en/01-user-guide/03-cli-command-reference.md).
## Resident Service and Agent Access
Start the shared Web/API service and opt into MCP Streamable HTTP:
```bash
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](docs/en/01-user-guide/06-web-workspace.md),
[MCP and Agent Access](docs/en/01-user-guide/07-mcp-agent-access.md), and
[Resident Service](docs/en/01-user-guide/09-resident-service.md) for session,
authorization, cancellation, audit, service-manager, and diagnostics guidance.
## Development
Use the repository scripts by responsibility:
```bash
./setup.sh
./build.sh
./run.sh start --port 8791 --daemon
./run.sh status
./run.sh stop --force
./check.sh
./check.sh --deep
```
The principal local quality gates are:
```bash
cargo fmt --all -- --check
cargo check --all-targets --all-features
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
```
The default `./check.sh` profile uses the stable toolchain and is suitable for
routine changes. The deep profile additionally runs the deterministic benchmark,
Miri over the FFI-free core-domain invariants, and AddressSanitizer over the
library and binaries. Install its nightly prerequisites first:
```bash
rustup toolchain install nightly --profile minimal --component miri,rust-src
./check.sh --deep
```
Miri and sanitizer checks also run as Linux pull-request jobs. They stay out of
the ordinary commit hook because they require nightly, rebuild instrumented
artifacts, and are materially slower than the stable check/Clippy/test loop.
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](docs/en/03-architecture-specs/02-engineering-hard-constraints.md).
### Self-Iteration Harness
The independent Rust harness for retrieval and indexing optimization is
documented in [tools/self_iteration](tools/self_iteration/README.md):
```bash
./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
```bash
./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](docs/en/01-user-guide/01-install-and-runtime.md).
Optional local hooks: `pre-commit install` and
`pre-commit run --all-files`. Rust changes run `cargo check`, Clippy, and tests
before the commit is accepted; the test command includes the deterministic
benchmark target through `--all-targets`.