Graphify — Obsidian-first Codebase & Knowledge Graph Builder

Build an Obsidian-readable knowledge graph and codebase index from any repository. Scans source code, extracts structural and semantic relationships, and generates an interlinked Obsidian vault with full-text search support.

Features

• Repository Scanning — Recursively scans codebases, skipping .git and binaries
• AST Extraction — Extracts functions, classes, and exports from Python, TypeScript, JavaScript
• Structure Analysis — Builds file/folder relationship graphs
• Obsidian Vault Generation — Wiki-linked markdown notes with YAML frontmatter
• Semantic Search — Embeddings via sentence-transformers or TF-IDF fallback
• Vector Store — On-disk embedding persistence with Qdrant support
• Raw Ingestion — HTML-to-Markdown pipeline for documentation ingestion
• LLM Q&A — Ask questions over your codebase (HuggingFace, OpenRouter, local LLM)
• Watch Mode — Auto re-index on git changes
• Git Integration — Post-commit hooks and GitHub Actions workflow

Quick Start

Install

pip install -r requirements.txt

Run Pipeline

python -m graphify.cli /path/to/repo /path/to/output

This produces:

• output/graph.json — Full graph in JSON
• output/vault/ — Obsidian vault with wiki-linked notes
• output/embeddings/ — Semantic search index

Query the Index

python -m graphify.cli query /path/to/output "your question" --k=5

Ask with LLM

python -m graphify.cli ask /path/to/output "your question" --k=3

Requires an LLM backend (see LLM Configuration).

Watch Mode

python -m graphify.cli watch /path/to/repo /path/to/output --once

Without --once, polls git HEAD every 5 seconds and re-runs on changes.

Install Git Hook

python -m graphify.cli install-hook /path/to/repo /path/to/output

Install GitHub Workflow

python -m graphify.cli install-workflow /path/to/repo /path/to/output --branch=main --schedule='0 6 * * 1'

LLM Configuration

Set environment variables to enable LLM features:

Backend	Env Variables
HuggingFace	HUGGINGFACE_API_KEY, optional GRAPHIFY_HF_MODEL
OpenRouter	OPENROUTER_API_KEY, optional OPENROUTER_MODEL
Local HTTP	GRAPHIFY_LOCAL_LLM_URL
Generic API	GRAPHIFY_API_URL, GRAPHIFY_API_KEY
Opencode Zen	OPENCODE_ZEN_API_KEY, OPENCODE_ZEN_URL

Raw Ingestion Pipeline

python -m graphify.cli ingest-raw /path/to/raw/files /path/to/output
python -m graphify.cli compile-wiki /path/to/output /path/to/vault

Useful for ingesting HTML documentation, markdown files, and images.

Development

pip install -r requirements.txt
pytest tests/

See CONTRIBUTING.md for detailed setup.

Project Structure

graphify/
  __init__.py          # Package init, version
  cli.py               # CLI entry point (subcommands: query, watch, ask, etc.)
  graph.py             # Graph data structure (nodes + edges)
  ingestion.py         # Repository file scanning
  obsidian_writer.py   # Obsidian vault markdown generation
  detectors.py         # Language detection by file extension
  llm.py               # LLM client abstraction (HuggingFace, OpenRouter, local)
  ask.py               # Q&A over codebase with RAG
  query.py             # Semantic search query
  watch.py             # Git-based watch mode
  hooks.py             # Git hook & GitHub workflow installer
  ingest_raw.py        # Raw HTML/markdown ingestion
  compile_wiki.py      # Wiki compilation from ingested data
  agents/
    ast_agent.py       # AST-based code extraction
    structure_agent.py # File/folder structure analysis
  integrations/
    external_runner.py # External graphify extract runner
  semantic/
    __init__.py
    embeddings.py      # Text embedding (sentence-transformers / TF-IDF / hash fallback)
    store.py           # On-disk vector store
    qdrant_adapter.py  # Qdrant vector DB adapter

License

MIT — see LICENSE