LLMWiki Agent Bridge

llmwiki-agent-bridge is the optional source fan-out and runtime-synthesis layer for the LLMWiki toolchain. It runs as a local HTTP service, gathers evidence from one or more llmwiki-serve Knowledge Sources, and returns one normalized answer artifact with citations, optional graph context, and trace steps. It can run evidence-only for a first smoke test, or call an OpenAI-compatible chat completions runtime for synthesized answers.

Use it when:

• A client wants one endpoint instead of managing source fan-out, prompting, runtime calls, citations, and trace shaping itself.

• You are connecting Hermes, DeepAgents, or a generic OpenAI-compatible local runtime to LLMWiki evidence.

• llmwiki-chat or another UI needs Agent Bridge A2A or MCP endpoints backed by local Knowledge Sources.

Skip it when your agent or script can call llmwiki-serve directly and manage its own answer synthesis.

Quick Start | Choose a Path | Demo | Runtime Profiles | Message Contract | OpenAPI | Integrations | Examples | Docs portal | Contributing | Security | Support | Changelog

Public-preview note: source-checkout usage is the supported first-run path. Package-install commands apply after the first npm release is published.

For a visual first-run walkthrough, see the docs demo. It shows the toolchain boundary: upstream workflows create compatible Markdown/wiki files, llmwiki-serve projects them read-only as Knowledge Sources, and the optional bridge can query selected served sources together.

It is not a Hermes-only bridge. Hermes is one supported runtime profile beside generic and deepagents; all profiles use the same message contract and return the same llmwiki_agent_result artifact shape.

It is independent community tooling for LLM Wiki-style Markdown knowledge folders and agent-readable context. It is not an official project from Andrej Karpathy or any upstream producer named in compatibility examples.

Choose a Path

Start with the direct path whenever your client can call llmwiki-serve itself. Add the bridge when you need fan-out, runtime synthesis, or a single normalized result behind one local service.

Direct-client templates live in integrations. The bridge request and artifact contract is documented in docs/message-send-contract.md and generated as docs/openapi.json.

Related MCP server: personal-llm-wiki-kit

Quick Start

Requirements:

• Node.js >=22.12

• npm >=10

• One or more running llmwiki-serve Knowledge Source endpoints

• Optional: an OpenAI-compatible /v1/chat/completions runtime for synthesis

• uv and Python 3.11 or newer when starting the sample source from a checkout

This quickstart uses two checkouts. Keep Terminal 1 in the source-server checkout and Terminal 2 in the bridge checkout so relative paths resolve in the right repository.

Terminal 1: source server

Clone and start the sample llmwiki-serve Knowledge Source. Leave this process running:

git clone https://github.com/knowledge-bridge-labs/llmwiki-serve.git
cd llmwiki-serve
uv sync --extra dev
uv run llmwiki-serve serve ./examples/sample-wiki --host 127.0.0.1 --port 8765

Terminal 2: bridge

Open Terminal 2 in the same parent workspace that contains the llmwiki-serve checkout. Clone the bridge, install dependencies, and run the local checks:

git clone https://github.com/knowledge-bridge-labs/llmwiki-agent-bridge.git
cd llmwiki-agent-bridge
npm ci
npm run check

From the bridge checkout, verify that Terminal 1 is serving the sample source:

curl -s http://127.0.0.1:8765/manifest

Start the bridge. The bundled sample request uses evidence-only mode, so the first smoke test does not need provider credentials or a running model runtime:

node ./bin/llmwiki-agent-bridge.mjs

The CLI writes a JSON ready event when the bridge is listening:

{
  "event": "ready",
  "url": "http://127.0.0.1:8788",
  "sourcePolicy": "private-http"
}

For runtime-backed answer synthesis, restart the bridge with the runtime profile that matches your local runtime. This generic example works for any runtime that implements OpenAI-compatible chat completions.

macOS/Linux:

LLMWIKI_AGENT_BRIDGE_BASE_URL=http://127.0.0.1:8642/v1 \
LLMWIKI_AGENT_BRIDGE_MODEL=local-model \
LLMWIKI_AGENT_BRIDGE_RUNTIME_PROFILE=generic \
node ./bin/llmwiki-agent-bridge.mjs

Windows PowerShell:

$env:LLMWIKI_AGENT_BRIDGE_BASE_URL = 'http://127.0.0.1:8642/v1'
$env:LLMWIKI_AGENT_BRIDGE_MODEL = 'local-model'
$env:LLMWIKI_AGENT_BRIDGE_RUNTIME_PROFILE = 'generic'
node .\bin\llmwiki-agent-bridge.mjs

For Hermes or DeepAgents, keep the same command shape and change LLMWIKI_AGENT_BRIDGE_RUNTIME_PROFILE plus the model name:

Leave the bridge running. The following commands are also bridge-checkout commands; if Terminal 2 is occupied by the bridge process, open another prompt and run cd llmwiki-agent-bridge first.

Check the local surface:

curl -s http://127.0.0.1:8788/health
curl -s http://127.0.0.1:8788/.well-known/agent-card.json
curl -s http://127.0.0.1:8788/settings.json

For the first run, open http://127.0.0.1:8788/settings and follow the guided setup:

1. Connect runtime when you want synthesis. Set the runtime profile, base URL, and model. The page saves these fields through PUT /settings/config.json.

2. Register Knowledge Sources. Add the sample source at http://127.0.0.1:8765, mark it ready and selected, then save it through GET/PUT /settings/sources.json.

3. Verify Bridge. Run the settings-page verification, which sends POST /message:send using the registered source and shows the returned answer artifact, citations, graph, and trace steps.

Runtime credentials, network, auth, CORS, timeout, and source-policy controls live under diagnostics/advanced. Most local OSS users only need the three setup steps above.

Send the sample request from the llmwiki-agent-bridge checkout so the --data @examples/message-send.local.json path resolves to this repository:

curl -s http://127.0.0.1:8788/message:send \
  -H 'content-type: application/json' \
  --data @examples/message-send.local.json

The bundled examples/message-send.local.json points at http://127.0.0.1:8765. If your llmwiki-serve or bridge process uses a different port, copy that file to a temporary path, update the source URL, and post it to the bridge URL you started.

MCP-style clients can list and call the bridge tool at /mcp:

curl -s http://127.0.0.1:8788/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -s http://127.0.0.1:8788/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"llmwiki_agent_run","arguments":{"query":"release readiness"}}}'

Omit knowledgeSources to use sources registered through /settings. Passing knowledgeSources: [] means "run with no sources" and is useful only for negative tests.

The sample request asks release readiness. Exact answer wording may vary by runtime; the stable integration target is the completed task plus the llmwiki_agent_result data artifact fields:

{
  "answer": "Grounded answer text from the configured runtime.",
  "citations": [
    {
      "sourceId": "sample-wiki",
      "pageId": "release-readiness",
      "title": "Release Readiness",
      "score": 0.92
    }
  ],
  "graph": {
    "nodes": [],
    "edges": []
  },
  "steps": [
    {
      "id": "bridge-evidence",
      "label": "Prepare evidence",
      "status": "done"
    },
    {
      "id": "runtime-chat-completions",
      "label": "Call chat completions",
      "status": "done"
    }
  ]
}

For complete payloads and local setup notes, use examples, runtime profiles, the message contract, and client paths.

What It Does

The bridge exposes one small local HTTP surface:

For each POST /message:send request, the bridge:

1. Selects ready Knowledge Source descriptors from the request.

2. Fetches context over llmwiki-http, MCP-style JSON-RPC, or A2A-style HTTP.

3. Packages citations, graph context, source bundle metadata, and trace steps.

4. In delegated-runtime or hybrid, compacts the evidence bundle and calls the configured OpenAI-compatible /v1/chat/completions endpoint.

5. In evidence-only, skips the runtime call and returns a bridge-generated evidence summary.

6. Returns answer text plus the llmwiki_agent_result artifact.

POST /mcp calls the same internal run path as /message:send. Its llmwiki_agent_run tool returns text content plus structuredContent.llmwiki_agent_result for tool-oriented clients.

Requests may supply knowledgeSources directly, or omit them and use the bridge's registered Knowledge Sources. Register sources in Step 2 of /settings or by calling PUT /settings/sources.json with a sources array. Multiple ready, selected sources can be registered and queried in one run.

flowchart LR
  client["client or chat workbench"]
  bridge["llmwiki-agent-bridge"]
  sources["selected Knowledge Sources"]
  runtime["OpenAI-compatible runtime"]
  artifact["answer artifact<br/>citations, graph, trace"]

  client --> bridge
  bridge --> sources
  sources --> bridge
  bridge --> runtime
  runtime --> bridge
  bridge --> artifact

Supported Knowledge Source protocols:

The generated OpenAPI contract is committed at docs/openapi.json. It covers the bridge's local HTTP surface and the llmwiki_agent_result artifact shape as a public-preview compatibility contract, not as certified A2A conformance.

The package includes @a2a-js/sdk@0.3.13 for A2A discovery compatibility checks while keeping the existing /message:send route stable.

Runtime Profiles

Profiles are conservative configuration presets over the same bridge contract. They change runtime identity metadata, default model naming, and operator-facing configuration; they do not change the LLMWiki evidence format.

Legacy HERMES_* and HERMES_A2A_BRIDGE_* environment aliases remain available for migration. New deployments should prefer the LLMWIKI_AGENT_BRIDGE_* variables.

More detail: docs/runtime-profiles.md.

Package Surface

llmwiki-agent-bridge ships one Node package with these public entry points:

After npm publication, the intended package entrypoint is:

npx llmwiki-agent-bridge

Until then, source-checkout usage is the supported path.

Integration Paths

Direct-client integrations are the best first choice when the agent can safely retrieve context from llmwiki-serve itself. Bridge integrations are a better fit when a client wants one local service to gather evidence, call a runtime, and return a normalized result.

• Client path guide

• Integrations overview

• Codex skill example

• Claude Code command example

• Copilot instructions example

For direct agent use, run llmwiki-serve, set LLMWIKI_SERVE_URL, and adapt the templates in integrations/. The examples call /query first, then /search, /read/{page_id}, /graph, or /mcp for narrower inspection.

export LLMWIKI_SERVE_URL=http://127.0.0.1:8765

Use llmwiki-agent-bridge when the workflow also needs source fan-out, OpenAI-compatible runtime synthesis, and one normalized answer artifact.

Configuration

Most local runs only need the runtime base URL, model, profile, and optional bridge bearer token:

Source policy, CORS, bind-host, and migration alias details are documented in runtime profiles and client paths.

The implementation keeps Hermes defaults for backward compatibility. For a new OSS install, set LLMWIKI_AGENT_BRIDGE_RUNTIME_PROFILE=generic explicitly unless you are connecting Hermes or DeepAgents, and set the model name expected by that runtime.

Do not expose the bridge on a public or shared interface without LLMWIKI_AGENT_BRIDGE_BEARER_TOKEN. Non-loopback binds require an explicit opt-in, and public unauthenticated binds are a development-only escape hatch.

The /settings page is the guided first-run UI over the same configuration. Step 1 connects the runtime and saves profile, base URL, and model through PUT /settings/config.json. Step 2 saves reusable Knowledge Source descriptors through GET/PUT /settings/sources.json. Step 3 verifies the bridge by sending POST /message:send from the page and showing the returned artifact. Runtime credentials, advanced network, auth, CORS, timeout, and source-policy fields are still available under diagnostics/advanced; changes to live runtime fields apply to the running process. Bind host and port are saved for the next start and the save response lists them under restartRequired.

Programmatic API

import { startAgentBridge } from 'llmwiki-agent-bridge'

const { server, url } = await startAgentBridge({
  port: 0,
  baseUrl: 'http://127.0.0.1:8642/v1',
  model: 'local-model',
  runtimeProfile: 'generic',
})

console.log(url)
server.close()

Legacy createHermesA2aBridge and startHermesA2aBridge exports are available during migration.

Repository Structure

Release Status

llmwiki-agent-bridge is in public source-checkout preview. Source-checkout usage is the supported path today. npm package-install links should be treated as release gates until the first package is published.

Repository, issue, CI badge, package, and hosted docs URLs intentionally target the Knowledge Bridge Labs organization. The hosted Release Status & Compatibility matrix records which package and runtime paths are currently available.

See docs/release.md before publishing or tagging a public preview.

Development

npm run lint
npm run contracts:check
npm test
npm run pack:dry-run
npm run audit

npm run check runs lint, generated-contract drift checks, tests, and dry packaging.

Toolchain

Community

Before opening a pull request, read CONTRIBUTING.md, keep changes focused on the bridge contract, and include validation results.

Use GitHub issues for reproducible bugs, focused feature requests, runtime or protocol compatibility notes, and documentation gaps. Keep examples public and sanitized; do not include credentials, bearer tokens, private endpoint URLs, raw sensitive wiki content, or private runtime logs.

• Bug reports

• Runtime or protocol compatibility

• Feature requests

• Documentation issues

• Security policy

• Support guide

• Code of conduct

For vulnerabilities, follow SECURITY.md instead of opening a detailed public issue.

License

Apache-2.0. See LICENSE.