groundly 0.3.0

Local-first course knowledge bases for AI agents: index your materials, study grounded, share the index.

Groundly

Local-first course knowledge bases for AI agents. Index your course materials once; then any MCP-capable agent — Claude Code, Claude Desktop, Codex — can answer questions grounded in the actual course content with page-level citations, generate execution-verified tests and flashcards, quiz your weak areas, and track your mastery. Share the finished knowledge base with your coursemates as a single file.

Bachelor thesis project, Universitatea Politehnica Timișoara.

$ groundly index <SUBJECT> ./slides/
  ✓ 12 PDFs → 384 chunks → embedded (bge-m3, local) → indexed
$ # wire into Claude Code:  { "command": "groundly", "args": ["mcp"] }

Then, inside your agent: "What did lecture 4 say about deadlock prevention?" → answer cited to lecture-04.pdf, page 12, "Deadlocks › Prevention" — or "not covered by the course materials", never a hallucination.

Why not NotebookLM / a Claude Project?

1. Verified generation — every test question and flashcard passes a verifier: answerable from the cited sources, answer key checked, and code questions' reference solutions actually executed before acceptance.
2. Enforced citations — structural, page-level, with honest refusal when the corpus doesn't cover it.
3. A portable index — groundly export <SUBJECT> → one file; a coursemate imports it and their agent uses it directly. The expensive artifacts (knowledge graph, verified decks) are built once and shared.
4. Cross-host progress — mastery per topic and study memory persist in local files, whatever agent you talk to. Your queries and results never leave your machine and are never part of an export.

Features

• Grounded Q&A — hybrid retrieval (bge-m3 dense + learned sparse + BM25, reranked; optional GraphRAG for synthesis questions), via MCP tools or groundly ask
• Verified quizzes & coding challenges — generated by Groundly (your API key) or by your agent (no key needed) — either way, nothing unverified is stored
• Flashcards → Anki — verified decks exported as .apkg
• Mastery map & study memory — per-topic mastery from quiz results; "continue studying" warm starts in any host
• Import/export — the whole knowledge base as one shareable file, with pinned-model compatibility

Install

uv tool install groundly

Local-first honestly stated: first run downloads the embedding models (~2.7GB total). Indexing and search need no API key; grounded answer generation and graph builds use your own OpenAI-compatible provider (cloud key, LM Studio, or Ollama).

Thesis core: four-arm RAG vs GraphRAG evaluation on real RO/EN course corpora, plus a measured comparison of enforced vs agent-mediated grounding.