Librarian

Librarian is a local-first Java CLI for cross-repository code intelligence. It indexes multiple repositories into an embedded Apache Lucene index and answers questions about dependencies, imports, symbols, and shared implementation patterns.

It is the retrieval layer for Syntropy source-grounded reviews: deterministic evidence packets that feed multi-agent architecture decision workflows without dumping whole repositories into a prompt.

Capabilities

• Project and workspace discovery across mixed-language monorepos
• Lucene-backed indexing with incremental re-indexing and foreground watch mode
• Full-text query, dependency/import/symbol search, pattern drift, similarity, and impact analysis
• Bundled local dependency vulnerability audit (deps --vulnerable)
• Deterministic retrieval evidence packets for source-grounded codebase review
• JVM install distribution and optional GraalVM native-image builds
• LIBRARIAN_HOME for isolated local state (required when Syntropy shells out per run)

Syntropy integration contracts

Librarian exposes two stable JSON contracts consumed by Syntropy:

Initial run packet — librarian retrieve:

librarian retrieve \
  --repo ~/projects/my-app \
  --goal "Find the highest-leverage next engineering move." \
  --focus architecture,security,operations \
  --budget 60000 \
  --json

Emits schema_version: librarian.retrieve.v1 with inventory, selected files, bounded snippets, omissions, and agent briefs.

Agent inquiry expansion — librarian evidence:

librarian evidence \
  --repo ~/projects/my-app \
  --request-file inquiry.json \
  --budget 18000 \
  --json

Emits schema_version: librarian.evidence.v1 for follow-up search, open-file, related-files, and dependency-context actions during a run.

Set SYNTROPY_LIBRARIAN_BIN to the librarian binary path when integrating with Syntropy Platform or the Elixir runtime.

Requirements

• Java 21+
• Gradle wrapper in this repository
• Optional for native builds: GraalVM with native-image

Install

Download the latest release from GitHub Releases (librarian-{version}.zip or native binary). Extract and place librarian on your PATH, or set SYNTROPY_LIBRARIAN_BIN.

Build from source:

./gradlew installDist
# binary: build/install/librarian/bin/librarian

Build and quality gate

./gradlew test
./gradlew quality
./gradlew installDist

./gradlew quality runs the JUnit suite, Spotless, Checkstyle, and SpotBugs.

Distribution smoke checks:

scripts/smoke-jvm-dist.sh
scripts/smoke-native.sh   # when GraalVM is available

Release packaging:

scripts/package-release.sh --skip-native
LIBRARIAN_RELEASE_VERSION=0.1.0 scripts/package-release.sh --skip-native

Push a v* tag or run the Release workflow to publish JVM archives and native binaries to GitHub Releases.

Usage

Index project roots or workspace directories:

librarian index ~/code/workspace ~/projects/my-app
librarian status --json
librarian query "which projects use chromadb?" --json
librarian deps --vulnerable --json
librarian retrieve --repo ~/projects/my-app --goal "Review deployment safety." --focus architecture,security --json

Watch mode re-indexes after debounced local changes:

librarian watch ~/code/workspace

Runtime diagnostics:

librarian doctor --json

Override local state directory:

LIBRARIAN_HOME=/tmp/librarian-home librarian status

Command surface

index, watch, status, doctor, query, deps, drift, similar, impact, retrieve, evidence

Structured output is available with --json for one-shot commands. watch is human-output only (long-running foreground process).

What Librarian does not do

• No hosted service, web UI, or API server
• No LLM calls, embeddings, or model orchestration (that is Syntropy's job)
• No repository mutation, dependency installation, or build-tool execution
• No replacement for full build-graph resolution (manifest intelligence only)

CI

• CI workflow: ./gradlew quality, JVM distribution smoke, release packaging
• Release workflow: JVM archives + native binaries on v* tags

Local state

• Lucene index: ~/.librarian/index/
• Registry metadata: ~/.librarian/registry.yml

Indexed source projects are read-only inputs.

License

Fair Source — Business Source License 1.1. Free for development, evaluation, research, and personal use; free in production for organizations under US $1M revenue/funding; each version converts to Apache 2.0 four years after release. See LICENSE.

"Librarian" and the Syntropy logo are trademarks of Syntropy OS. See CONTRIBUTING.md for the contributor license agreement.