Biblos

Biblos is a multi-agent MCP server that gives your agents a shared, documented memory and a persistent inter-agent message bus. It is not a central brain: every agent keeps its own LLM and local memory. Biblos is the shared library and interconnect that lets otherwise independent agents (e.g. OpenClaw, OpenCode, Claude Code) persist knowledge in one place and hand work to each other in a verifiable way.

• Documented vectorized memory — every memory is a readable Markdown document plus structured metadata, searchable with hybrid semantic + keyword ranking.

• Inter-agent bus — a persistent request queue with recipient identity verification, so agents can ask each other for work and confirm the outcome.

Implements the Model Context Protocol over Streamable HTTP using the official @modelcontextprotocol/sdk@1.30.0. Persistence is a single SQLite file (better-sqlite3 + sqlite-vec 768-dim vectors + FTS5 keyword index). Tested with 130 passing tests (vitest).

Features

Biblos exposes 14 MCP tools across 5 domains.

Architecture

Clients (OpenClaw / OpenCode / Claude Code)
   │  MCP Streamable HTTP + Bearer + Origin + X-Biblos-Agent
   ▼
┌─────────────────────────────────────────────────────┐
│  src/index.ts  (Node http, stateless, no sessions) │
│   ┌─────────────────────────────────────────────┐  │
│   │  src/auth.ts                                │  │
│   │    Origin not allowlisted          → 403    │  │
│   │    Bearer key mismatch (timing-safe) → 401  │  │
│   └──────────────────┬──────────────────────────┘  │
│                      ▼                            │
│   McpServer — Streamable HTTP on /mcp (14 tools) │
│   └── domains: documents · graph · bus · registry │
└──────────┬─────────────────────────────┬──────────┘
           │                             │  HTTP (fetch)
      SQLite (single file)          embeddings/client.ts
      better-sqlite3                 → POST {ROUTER_URL}/v1/embeddings
      sqlite-vec vec0 (768d)               ▼
      FTS5 + sync triggers          llama.cpp router

Design principles:

• Stateless Streamable HTTP. The server does not use MCP-Session-Id sessions. Each request is handled by a fresh transport + McpServer instance, which makes proxying trivial and avoids session-affinity issues.

• Auth first. Every request passes through src/auth.ts before reaching any tool: an Origin not in BIBLOS_ALLOWED_ORIGINS (or missing on non-GET) is rejected with 403; a wrong BIBLOS_API_KEY is rejected with 401 (compared with crypto.timingSafeEqual). The server refuses to start without both variables set.

• Identity from the header, never from tool arguments. The X-Biblos-Agent header fixes the caller's identity at the HTTP boundary, so callers cannot spoof the recipient checks that the bus enforces.

• No web framework. The Streamable HTTP transport is a single JSON-RPC endpoint, so the native node:http server is enough — no Express/Hono needed, one less dependency surface.

• Explicit embed seam. All router traffic is confined to src/embeddings/client.ts behind an EmbeddingClient interface; domain services mock at that seam in tests.

Requirements

• Node.js >= 22 (ESM, NodeNext).

• External dependency — an embeddings router. save_document, update_document (on content change) and search_documents need an OpenAI-style /v1/embeddings endpoint serving a 768-dim model. The default target is a llama.cpp server running in router mode at ROUTER_URL with BIBLOS_EMBED_MODEL (nomic-embed-text-v1.5.Q8_0 by default). If the router is unreachable, embedding-dependent tools fail with an embedding_service_unavailable tool error (isError: true) and never write partial data; all other tools keep working.

Configuration

All configuration comes from environment variables (see .env.example, read by src/config.ts).

Quick start (local)

npm ci
cp .env.example .env
# fill in BIBLOS_API_KEY (e.g. `openssl rand -hex 32`) and BIBLOS_ALLOWED_ORIGINS
npm run build
npm start

The server now listens on http://127.0.0.1:8199/mcp. It will start even if the embeddings router is down — only embedding-dependent tools will fail until the router is reachable.

Connecting clients

Biblos speaks MCP Streamable HTTP and requires three things on every request:

See docs/clients.md for step-by-step configuration for OpenClaw (streamable-http transport), OpenCode (type: remote, Bearer header, oauth: false), and Claude Code, plus the registration-first rule and a curl smoke test.

Development

npm run test       # vitest run — full suite (130 tests)
npm run typecheck  # tsc --noEmit
npm run build      # tsc -p tsconfig.build.json + copy src/db/schema.sql → dist/

Repository layout:

src/
  config.ts            env config loader (loadConfig)
  index.ts             node:http server + stateless Streamable HTTP transport
  auth.ts              Bearer + Origin middleware (every request)
  server/tools.ts      14 MCP tool registrations (zod schemas)
  domain/              documents, graph, bus, registry, types
  db/                  store.ts (better-sqlite3 facade), migrate.ts, schema.sql
  embeddings/client.ts EmbeddingClient — the only llama.cpp boundary
  hybrid/fusion.ts     weighted semantic + FTS5 fusion
tests/                 unit, integration (mocked router), and E2E suites
docs/clients.md        client integration guide
deploy/                systemd unit, env example, Apache vhost template
openspec/              SDD artifacts (proposal, specs, design, tasks)

Tests never require the embeddings router — it is always mocked at the fetch seam.

License

MIT — © 2026 juanvs23.