Offline, file-first document toolkit for LLM agents — a grep/cat that reads PDF & Office, plus a reasoning-graph MCP server.
One Rust binary (kb); no external services required for core operation.

Install · Connect to agents · CLI for agents · MCP tools · Architecture · MIT

glossa indexes documents on disk, serves ranked search and ripgrep-style tools, and maintains a provenance-stamped knowledge graph that agents can query and extend.

Why glossa

• CLI or MCP — shell out to kb cat / kb grep / kb read as a Unix-composable tool that reads Office & PDF (the grep/cat your agent is missing), or run it as an MCP server for a persistent, graph-backed corpus. Same binary, same extractors.
• Native corpora — PDF and Office (Word, Excel, PowerPoint) indexed in place; no markdown conversion step.
• File-first graph — files stay authoritative; .glossa/ is a rebuildable overlay with provenance-stamped reasoning nodes.
• Agent retrieval loop — BM25 search, exact grep, chunk read, then glossary → neighbors over solved-case chains.
• Production MCP — one offline binary; stdio for local IDEs, streamable HTTP with health/metrics for deploy.

Features

Feature	What it does
Native document ingest	Drop PDF/Office files into the corpus folder — glossa extracts text and chunks them (p.N for PDF, sections for Office). Embedded images in read for vision-capable agents; --noimage for text-only mode. No LibreOffice, pandoc, or separate ETL.
Auto-indexing	ensure_fresh before MCP/CLI reads — new or changed files are indexed automatically. Cheap stat-scan when nothing changed; safe across concurrent reader/editor instances.
Auto-generalize	Editor MCP runs a debounced graph_generalize after index changes — SIMILAR links, communities, centrality without agent action. Cross-process lock on .glossa/generalize.lock.
Graph without embeddings	Reasoning types and relations from ontology.toml; derived layer (closure, SIMILAR, communities) is deterministic — no vector DB, no model calls.
Gitignore-aware indexing	Skips paths matched by .gitignore / .ignore (ripgrep-style). Use -u / --no-ignore when you need everything.
Profiles, not RBAC	reader / editor / full hide write tools from the model; every profile still serves fresh data.
Production HTTP MCP	--transport streamable-http at <bind>/mcp; /health, /ready, /metrics (Prometheus). Multi-instance reader pools; TLS/auth at the gateway. See deploy guide.

Details: architecture.md, mcp.md.

Quickstart

As your agent's CLI — no server, no setup; point it at files and read or search them:

kb cat report.docx              # full text of a Word / Excel / PowerPoint / PDF file
kb grep "revenue" reports/      # ripgrep, but inside every .docx / .xlsx / .pdf
kb search "connection timeout"  # BM25-ranked search over a folder of documents

Operators — install from GitHub Releases (no Rust required):

# See docs/install.md for your OS — then index any folder of documents:
kb index ~/Documents/my-kb
kb mcp ~/Documents/my-kb --profile reader --transport stdio

Connect Claude, Cursor, or ZeroClaw: connect-to-agents.md.
Run as a system service: deploy/service.md.

Developers — build from source:

cargo build --release
./target/release/kb index ./my-corpus
cd ./my-corpus
./target/release/kb search "connection timeout"
./target/release/kb mcp --profile reader

On Windows, the binary is target\release\kb.exe. Optional: install just and run just build.

Architecture

flowchart LR
  files[Corpus files]
  index[Tantivy BM25 index]
  kg[SQLite reasoning graph]
  mcp[MCP server kb mcp]
  agent[LLM agent]

  files --> index
  files --> kg
  agent --> mcp
  mcp --> index
  mcp --> kg

Loading

• Structural layer (auto during index): Document → Section → CONTAINS, MENTIONS, chunk navigation.
• Reasoning layer (agent via graph_upsert): Symptom → Cause → Resolution and domain-specific types from ontology.toml.
• Derived layer (graph generalize): transitive closure, SIMILAR links, communities, centrality.

See docs/architecture.md for details.

MCP profiles

Profile	Purpose	Write tools
reader	Query-only agents	Hidden: index, graph_upsert, graph_generalize, purge, …
editor	Index + graph editing	All except purge
full	Admin	All tools including purge

Tool reference: docs/mcp.md. Service install: docs/deploy/service.md. Advanced HTTP: docs/deploy/mcp-server.md.

Documentation

Doc	Description
docs/install.md	Install from release; first index
docs/connect-to-agents.md	Claude, Cursor, ZeroClaw
docs/getting-started.md	Build from source, CLI
docs/architecture.md	Index, extraction, graph layers
docs/mcp.md	MCP tools and IDE setup
docs/deploy/service.md	System service install
docs/graph-and-ontology.md	Ontology, enrich, generalize
docs/eval-and-training.md	kb-eval, kb-train, dataset format
docs/ROADMAP.md	Backlog and direction
docs/benchmarks.md	Eval run history

Full index: docs/README.md.

Development

just build
cargo test -p glossa --release

CI runs on every push/PR (Linux + Windows tests, cargo check). Tagged releases (v*) build kb binaries for Linux, Windows, and macOS — see GitHub Releases.

See CONTRIBUTING.md.

Acknowledgments

glossa is built with excellent Rust libraries:

Project	Role
Tantivy	BM25 full-text index
pdf_oxide	PDF text extraction, page render, embeds
office_oxide	Word, Excel, PowerPoint extraction

Also: ripgrep ecosystem (regex, globset, ignore), rusqlite (graph storage), rmcp (MCP server).

License

MIT — see LICENSE.