sciogen 0.1.0

Codebase intelligence layer — a queryable knowledge graph over your code.

Codebase intelligence layer — a queryable knowledge graph over your code.

sciogen parses a codebase once, resolves every reference to the exact definition it points to, and materializes the result into an embedded triple store. After that, questions like "who calls AuthService.login?", "what breaks if I change UserModel.find_by_email?", or "where is the password hashing logic?" are sub-second index lookups that return typed objects with file/line locations — not grep results, not raw source dumps.

sciogen is a static analysis and indexing tool. It never calls an LLM, never counts tokens, and has no concept of a context window. It is to codebases what Elasticsearch is to documents: precomputed, queryable structure.

pip install sciogen
sciogen index .

  ███████╗ ██████╗██╗ ██████╗  ██████╗ ███████╗███╗   ██╗
  ██╔════╝██╔════╝██║██╔═══██╗██╔════╝ ██╔════╝████╗  ██║
  ███████╗██║     ██║██║   ██║██║  ███╗█████╗  ██╔██╗ ██║
  ╚════██║██║     ██║██║   ██║██║   ██║██╔══╝  ██║╚██╗██║
  ███████║╚██████╗██║╚██████╔╝╚██████╔╝███████╗██║ ╚████║
  ╚══════╝ ╚═════╝╚═╝ ╚═════╝  ╚═════╝ ╚══════╝╚═╝  ╚═══╝
  Codebase Intelligence Layer  v0.1.0

✓ Scanning project structure...
✓ Reading 143 files...
✓ Parsing Python, TypeScript...
✓ Building knowledge graph...
✓ Embedding 1,204 symbols...
✓ Linking dependencies...
✓ Done! 1,204 nodes · 3,456 edges · indexed in 4.2s
  Ready. Your codebase is now queryable.

Why

A coding agent understands a codebase by reading files — and files are the wrong granularity. To learn one function's callers it reads thousands of lines of source into its context window, burning tokens on noise. sciogen precomputes the structure once, so the same answer is a handful of typed records with exact file:line locations.

You run sciogen index . once. The knowledge graph is written to a .sciogen/ directory inside the codebase. From then on, an agent working in that repo reads the graph instead of the raw files — the callers of a symbol, the blast radius of a change, where a concept lives — for a fraction of the tokens a file-by-file crawl would cost. sciogen itself never calls an LLM and is unaware of tokens; the savings are a consequence of returning structure instead of source.

  index once  ─────────────►  .sciogen/  (graph stored in the repo)
  (sciogen index .)                │
                                   ▼
  agent asks: "who calls login?"  →  typed records + file:line
  agent asks: "what breaks if …?"  →  impact subgraph, not 40 files

The two ways it's used

You — from the terminal. sciogen index . builds the graph; sciogen explore opens it as an interactive browser GUI to inspect the codebase visually.

Your coding agent — over MCP. sciogen mcp . exposes the graph to any agent (Claude Code, etc.) through the Model Context Protocol, so it can query callers, dependencies, impact, and semantic search directly instead of reading files. See docs/mcp.md.

What the graph gives an agent

• Exact call graphs — a call to login() resolves to src/auth/service.py:AuthService.login, not the string "login". References static analysis cannot prove (dynamic dispatch, injected dependencies) are kept with a low confidence score rather than silently dropped, so the caller chooses how much to trust each edge.
• Impact analysis — everything that may break if a symbol changes: transitive callers with hop counts, subclasses, implementors, tests, mutators — and the same for a whole PR at once from a unified diff.
• Semantic + hybrid search — local embeddings at four granularities (file, class, function, chunk); hybrid mode expands vector hits through the graph.
• Incremental by design — SHA256 differ with a stat fast path; a single-file change re-indexes in under a second, and dependent files are re-linked without being re-parsed.
• Interactive visualization — sciogen explore renders the graph in your browser from one self-contained HTML file. No server.

Getting started

pip install sciogen
# optional, for real code-optimized semantic search (larger, one model download):
pip install "sciogen[embeddings]"

cd your-project
sciogen index .          # build the graph (stored in ./.sciogen; incremental after)
sciogen explore          # inspect it visually in the browser
sciogen mcp .            # serve it to your coding agent over MCP

Add .sciogen/ to your .gitignore — it's machine-local and regenerable.

You can also query directly from the terminal for a quick look:

sciogen search "password hashing"      # semantic search
sciogen callers AuthService.login      # who calls this?
sciogen impact UserModel.find_by_email # what breaks if this changes?
sciogen deps src/auth/service.py       # imports, transitive deps

See docs/cli.md for every command.

Architecture in one paragraph

sciogen index runs a five-stage pipeline per file: tree-sitter parses (100+ languages, one API), a normalizer converts the language-specific AST into a universal IR (only this layer knows languages), the symbol resolver traces every reference to its exact definition with a confidence score, the graph builder materializes typed nodes/edges into KuzuDB (Cypher), and a SHA256 differ backed by SQLite makes re-runs incremental. Embeddings of normalized symbol summaries (never raw code) go to ChromaDB at four granularities. Queries are deterministic: structural queries hit KuzuDB, semantic queries hit ChromaDB, hybrid uses vector hits as seeds for graph expansion. The full design — including the performance architecture (parallel parsing, batched transactional writes, embed deduplication, incremental re-resolution) — is in docs/architecture.md.

Storage

Everything is embedded — no servers, no ports, one .sciogen/ directory:

Store	Role
KuzuDB	Graph topology — nodes, typed edges, confidence scores
ChromaDB	Vector embeddings at file/class/function/chunk granularity
SQLite	File hashes, symbol table, reference records, schema version

Add .sciogen/ to your .gitignore.

Documentation

Doc	Contents
docs/quickstart.md	Install, first index, first queries
docs/cli.md	Every command and flag
docs/mcp.md	MCP tools and agent setup — how an agent consumes the graph
docs/schema.md	Node types, edge types, confidence model
docs/architecture.md	The two phases, every design decision, performance architecture
docs/api.md	Embedded Python API — only if you're building tooling on top of sciogen

Supported languages

Full symbol extraction: Python, JavaScript, TypeScript/TSX. File-level indexing (parse check + file search): Go, Rust, Java, Ruby, PHP, C, C++, C#, Kotlin, Swift, Scala, Lua. Adding full support for a language means writing one normalizer — see docs/architecture.md.

Development

git clone <repo> && cd sciogen
python -m venv .venv && .venv/Scripts/activate   # or bin/activate
pip install -e ".[dev]"
pytest

MIT license.