topolox 0.1.0__tar.gz

topolox-0.1.0/.env.example

@@ -0,0 +1,10 @@
+# Topolox settings — all are optional and prefixed with TOPOLOX_.
+# Copy to .env and uncomment to override defaults.
+
+# TOPOLOX_DATA_DIR=.topolox
+# TOPOLOX_MAX_WORKERS=
+# TOPOLOX_EMBEDDING_MODEL=BAAI/bge-small-en-v1.5
+# TOPOLOX_LOG_LEVEL=INFO
+
+# Only needed for the TUI chat pane (install with the [llm] extra):
+# ANTHROPIC_API_KEY=sk-ant-...

topolox-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,39 @@
+name: Bug report
+description: Report a problem with Topolox
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug, including what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Run `topolox ...`
+        2. ...
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Topolox version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: OS / Python version
+      placeholder: "macOS 14 / Python 3.13"
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs
+      render: shell

topolox-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,22 @@
+name: Feature request
+description: Suggest an idea for Topolox
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem would this feature solve? What are you trying to do?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe what you'd like to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered

topolox-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+## Summary
+
+<!-- What does this PR change and why? -->
+
+## Related issue
+
+<!-- e.g. Closes #123 -->
+
+## Checklist
+
+- [ ] `uv run ruff check .` passes
+- [ ] `uv run ruff format --check .` passes
+- [ ] `uv run mypy src` passes
+- [ ] `uv run pytest` passes
+- [ ] Added/updated tests where relevant
+- [ ] Updated `CHANGELOG.md` (Unreleased)

topolox-0.1.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

topolox-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --python ${{ matrix.python-version }}
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Format check (ruff)
+        run: uv run ruff format --check .
+
+      - name: Type check (mypy)
+        run: uv run mypy src
+
+      - name: Test (pytest)
+        run: uv run pytest

topolox-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,24 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI trusted publishing (OIDC)
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish

topolox-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Topolox data artifacts
+.topolox/
+*.kuzu/
+*.lance/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Environments & tools
+.venv/
+.env
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# OS & editors
+.DS_Store
+*.swp
+.idea/
+.vscode/

topolox-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+# Run `uv run pre-commit install` once to enable these hooks.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [pydantic]
+        args: [src]

topolox-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

topolox-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Multi-language extraction: a config-driven (per-language `LangSpec`) generalized extractor now pulls functions/classes/methods/imports from Python, JavaScript/JSX, TypeScript/TSX, Go, Rust, Java, C, C++, C#, Ruby, PHP, Kotlin, Swift, and Scala; any other tree-sitter-language-pack grammar is parsed and indexed at the file level.
+- Multi-agent `topolox mcp install`: registers the MCP server with Claude Code, Cursor, OpenAI Codex CLI (TOML), Gemini CLI, VS Code (`servers` key), Windsurf, and Claude Desktop, merging existing config.
+- Daemon (Phase 2): incremental `Indexer.update()` (re-parse changed files in-process, content-hash skip, prune stale symbols, handle deletions) and a `watchdog` watcher → debounced async service that patches the graph + vectors in milliseconds. Wired as `topolox daemon` (initial index, then live watch).
+- MCP server (Phase 2): a FastMCP server exposing `get_file_dependencies`, `analyze_blast_radius`, `prune_context`, and `search_architecture_graph` (async, thread-offloaded) to Claude Code / Cursor. `topolox mcp serve` runs it over stdio; `topolox mcp install` writes the client config (`.mcp.json` / `.cursor/mcp.json`). Tested via an in-memory FastMCP client.
+- Query engine (Phase 2): blast-radius simulation (transitive downstream importers), LanceDB vector search, a `FastEmbedEmbedder` (local ONNX embeddings via the `[embeddings]` extra), and a hybrid `ContextPruner` (vector seeds → graph expansion → token-budget cap). Wired as `topolox blast` and `topolox prune`; `topolox index` now uses real embeddings when `fastembed` is installed.
+- Storage & indexing (Phase 1): embedded Kùzu graph store (`Symbol` nodes + `Rel` edges, idempotent MERGE upserts) and LanceDB vector store behind their ports; `Indexer.build()` wiring the parser pool into both stores. `topolox index` now persists to `.topolox/`, and `topolox deps <file>` reports module-level dependencies/dependents.
+- Core parser (Phase 1): gitignore-aware file discovery, tree-sitter symbol/edge extraction (functions, classes, methods, imports), a picklable worker, and a `ProcessPoolExecutor` pool. `topolox index --dry-run` parses a repo and prints node/edge counts.
+- Project scaffold: `src/` layout, packaging (`pyproject.toml`), and tooling (uv, ruff, mypy, pytest).
+- Core data contracts (`SymbolNode`, `Edge`, `ParseResult`, query DTOs) and store ports (`GraphStore`, `VectorStore`, `Embedder`).
+- CLI skeleton (`topolox`) and module stubs for parser, stores, indexer, query, daemon, MCP, and TUI.
+- Open-source project files: README, license, contributing guide, code of conduct, security policy, CI, and issue/PR templates.
+
+[Unreleased]: https://github.com/Karnav018/topolox/commits/main

topolox-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,61 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards and
+will take appropriate and fair corrective action in response to any behavior
+that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+`INSERT-CONTACT-EMAIL`. All complaints will be reviewed and investigated
+promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

topolox-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing to Topolox
+
+Thanks for your interest! Topolox is in early development — see [ROADMAP.md](ROADMAP.md) for the phase plan.
+
+## Development setup
+
+Topolox uses [uv](https://docs.astral.sh/uv/) for environment and dependency management.
+
+```bash
+git clone https://github.com/Karnav018/topolox.git
+cd topolox
+uv sync                       # creates .venv, installs deps + dev tools
+uv run pre-commit install     # optional: enable git hooks
+```
+
+The project targets Python 3.11–3.13. `uv` will fetch the pinned interpreter automatically (see `.python-version`).
+
+## Before you push
+
+All of these run in CI and must pass:
+
+```bash
+uv run ruff check .           # lint
+uv run ruff format --check .  # formatting
+uv run mypy src               # static types (strict)
+uv run pytest                 # tests
+```
+
+`uv run ruff check --fix .` and `uv run ruff format .` fix most issues automatically.
+
+## Guidelines
+
+- **Match the surrounding code** — typing is strict; annotate everything in `src/`.
+- **Keep the engine deterministic.** Graph construction must not call an LLM; the LLM is only used at query time by the consuming agent.
+- **New ports go behind a Protocol.** Storage backends implement `GraphStore` / `VectorStore` (see `src/topolox/graph/store.py`, `src/topolox/vectors/store.py`).
+- **Conventional commits** are appreciated (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`).
+
+## Pull requests
+
+1. Fork and branch from `main`.
+2. Make your change with tests.
+3. Ensure the checks above pass.
+4. Open a PR describing the change and linking any related issue.
+
+By contributing you agree your work is licensed under the project's [MIT License](LICENSE) and that you follow the [Code of Conduct](CODE_OF_CONDUCT.md).

topolox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karnav and the Topolox contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

topolox-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: topolox
+Version: 0.1.0
+Summary: The topological memory and architecture layer for AI coding agents.
+Project-URL: Homepage, https://github.com/Karnav018/topolox
+Project-URL: Repository, https://github.com/Karnav018/topolox
+Project-URL: Issues, https://github.com/Karnav018/topolox/issues
+Project-URL: Changelog, https://github.com/Karnav018/topolox/blob/main/CHANGELOG.md
+Author: Karnav
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude,code-intelligence,coding-agents,cursor,knowledge-graph,kuzu,lancedb,mcp,tree-sitter
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fastmcp<4,>=3.4
+Requires-Dist: kuzu==0.11.3
+Requires-Dist: lancedb<0.34,>=0.33
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: textual>=8.2
+Requires-Dist: tree-sitter-language-pack>=1.8
+Requires-Dist: tree-sitter<0.26,>=0.25
+Requires-Dist: typer>=0.12
+Requires-Dist: watchdog>=6
+Provides-Extra: embeddings
+Requires-Dist: fastembed>=0.8; extra == 'embeddings'
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.105; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# Topolox
+
+> **The topological memory and architecture layer for AI coding agents.**
+
+[![CI](https://github.com/Karnav018/topolox/actions/workflows/ci.yml/badge.svg)](https://github.com/Karnav018/topolox/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Status](https://img.shields.io/badge/status-pre--alpha-orange)](ROADMAP.md)
+
+Topolox gives AI coding agents (Claude Code, Cursor) **instant, deep understanding of large codebases**. Instead of burning tokens reading thousands of files, it feeds an agent exactly the context it needs using an embedded **hybrid graph + vector engine** — kept live by a background daemon and exposed over **MCP** and an optional terminal cockpit.
+
+> ⚠️ **Pre-alpha.** The scaffold and contracts are in place; the engine is being built phase by phase. See [ROADMAP.md](ROADMAP.md).
+
+## Why
+
+On a big repo, an AI agent is *smart but blind*: it either reads dozens of files (slow, expensive) or misses a downstream caller and breaks something. Topolox is the **memory + map** the agent reads from — deterministic, instantly rebuildable, and zero-token to build.
+
+## How it works
+
+```
+discover → parse (multiprocessing tree-sitter) → ParseResult
+        → index → Kùzu (graph) + LanceDB (vectors)
+        → query (dependencies · context pruner · blast radius)
+        → MCP tools  +  CLI  +  Textual TUI
+   ┌ watchdog daemon patches the graph live on every file save ┐
+```
+
+## Topolox vs. Graphify
+
+Graphify pioneered "drop in a folder, get a knowledge graph." Topolox takes that idea in a different direction: an **always-on, agent-native engine for code**. They're built for different jobs.
+
+| | **Graphify** | **Topolox** |
+| :--- | :--- | :--- |
+| **Form factor** | A Claude Code *skill* (`/graphify`) | A standalone *service*: CLI + MCP server + daemon |
+| **Graph build** | AST **+ LLM extraction** (Claude subagents / Gemini) | **Pure deterministic** AST (multiprocessing tree-sitter) |
+| **When the LLM runs** | At **build** time — spends tokens on every build | Only at **query** time (the consuming agent); build is **zero-token** |
+| **Storage** | Static `graph.json` + in-memory NetworkX | Embedded **Kùzu** (graph) + **LanceDB** (vectors), on disk |
+| **Retrieval** | Lexical substring + IDF + BFS/DFS traversal | **Vector** semantic search + graph traversal (hybrid) |
+| **Live updates** | Opt-in `--watch` / git hook / manual `--update` | **watchdog daemon**, ms-level incremental patches |
+| **Agent access** | Optional MCP (7 read-only tools) + Markdown reports | **MCP-native** (4 tools), `mcp install` for every agent |
+| **Inputs** | Code **+ docs + papers + images + video** | Code — 14 languages richly, 300+ at the file level |
+| **Signature features** | Community detection, "god nodes", multi-modal RAG | Blast radius, dependency maps, context pruner |
+| **Concurrency** | Single graph, in-memory | Multiprocessing + asyncio, embedded DBs |
+
+**In short:** Graphify is a broad, **multi-modal, LLM-enriched** knowledge-graph builder you invoke as a skill — its graph is *richer* on inferred relationships. Topolox is a narrow, **deterministic, zero-token, always-live code engine** that any MCP agent reads from — *faster, cheaper, and instantly rebuildable*. That's the trade Topolox makes to be an always-on backend.
+
+## Two ways to use it
+
+1. **Invisible backend (MCP).** Index once, register with your agent, and any MCP client silently pulls grounded, cheap context.
+   ```bash
+   topolox index .
+   topolox mcp install      # registers with Claude Code, Cursor, Codex, Gemini CLI, VS Code, ...
+   topolox daemon           # keep the graph live in the background
+   ```
+2. **The TUI cockpit** *(planned — Phase 3).* A 3-pane terminal dashboard (agent chat · live knowledge graph · daemon log), `topolox ui`. See [ROADMAP.md](ROADMAP.md).
+
+## Supported languages & agents
+
+**Languages** — symbol + import extraction for Python, JavaScript/JSX, TypeScript/TSX, Go, Rust, Java, C, C++, C#, Ruby, PHP, Kotlin, Swift, and Scala; any other [tree-sitter-language-pack](https://github.com/Goldziher/tree-sitter-language-pack) grammar (300+) is still parsed and indexed at the file level.
+
+**Agents** — `topolox mcp install` registers the MCP server with **Claude Code, Cursor, OpenAI Codex CLI, Gemini CLI, VS Code, Windsurf, and Claude Desktop** (and any other MCP client — it's a standard stdio MCP server).
+
+## Install (from source)
+
+```bash
+git clone https://github.com/Karnav018/topolox.git
+cd topolox
+uv sync
+uv run topolox --help
+```
+
+## Development
+
+```bash
+uv sync                       # create the env + install dev tools
+uv run ruff check .           # lint
+uv run ruff format .          # format
+uv run mypy src               # type-check (strict)
+uv run pytest                 # tests
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Contributions welcome once the engine lands.
+
+## Tech stack
+
+Python 3.11+ · [Kùzu](https://kuzudb.com) (graph) · [LanceDB](https://lancedb.com) (vectors) · [tree-sitter](https://tree-sitter.github.io) (AST) · [FastMCP](https://gofastmcp.com) (MCP server) · [watchdog](https://github.com/gorakhargosh/watchdog) (daemon) · [Textual](https://textual.textualize.io) (TUI) · [Typer](https://typer.tiangolo.com) (CLI). Optional: `fastembed` (local embeddings), `anthropic` (TUI chat).
+
+## License
+
+[MIT](LICENSE)

topolox-0.1.0/README.md

@@ -0,0 +1,90 @@
+# Topolox
+
+> **The topological memory and architecture layer for AI coding agents.**
+
+[![CI](https://github.com/Karnav018/topolox/actions/workflows/ci.yml/badge.svg)](https://github.com/Karnav018/topolox/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Status](https://img.shields.io/badge/status-pre--alpha-orange)](ROADMAP.md)
+
+Topolox gives AI coding agents (Claude Code, Cursor) **instant, deep understanding of large codebases**. Instead of burning tokens reading thousands of files, it feeds an agent exactly the context it needs using an embedded **hybrid graph + vector engine** — kept live by a background daemon and exposed over **MCP** and an optional terminal cockpit.
+
+> ⚠️ **Pre-alpha.** The scaffold and contracts are in place; the engine is being built phase by phase. See [ROADMAP.md](ROADMAP.md).
+
+## Why
+
+On a big repo, an AI agent is *smart but blind*: it either reads dozens of files (slow, expensive) or misses a downstream caller and breaks something. Topolox is the **memory + map** the agent reads from — deterministic, instantly rebuildable, and zero-token to build.
+
+## How it works
+
+```
+discover → parse (multiprocessing tree-sitter) → ParseResult
+        → index → Kùzu (graph) + LanceDB (vectors)
+        → query (dependencies · context pruner · blast radius)
+        → MCP tools  +  CLI  +  Textual TUI
+   ┌ watchdog daemon patches the graph live on every file save ┐
+```
+
+## Topolox vs. Graphify
+
+Graphify pioneered "drop in a folder, get a knowledge graph." Topolox takes that idea in a different direction: an **always-on, agent-native engine for code**. They're built for different jobs.
+
+| | **Graphify** | **Topolox** |
+| :--- | :--- | :--- |
+| **Form factor** | A Claude Code *skill* (`/graphify`) | A standalone *service*: CLI + MCP server + daemon |
+| **Graph build** | AST **+ LLM extraction** (Claude subagents / Gemini) | **Pure deterministic** AST (multiprocessing tree-sitter) |
+| **When the LLM runs** | At **build** time — spends tokens on every build | Only at **query** time (the consuming agent); build is **zero-token** |
+| **Storage** | Static `graph.json` + in-memory NetworkX | Embedded **Kùzu** (graph) + **LanceDB** (vectors), on disk |
+| **Retrieval** | Lexical substring + IDF + BFS/DFS traversal | **Vector** semantic search + graph traversal (hybrid) |
+| **Live updates** | Opt-in `--watch` / git hook / manual `--update` | **watchdog daemon**, ms-level incremental patches |
+| **Agent access** | Optional MCP (7 read-only tools) + Markdown reports | **MCP-native** (4 tools), `mcp install` for every agent |
+| **Inputs** | Code **+ docs + papers + images + video** | Code — 14 languages richly, 300+ at the file level |
+| **Signature features** | Community detection, "god nodes", multi-modal RAG | Blast radius, dependency maps, context pruner |
+| **Concurrency** | Single graph, in-memory | Multiprocessing + asyncio, embedded DBs |
+
+**In short:** Graphify is a broad, **multi-modal, LLM-enriched** knowledge-graph builder you invoke as a skill — its graph is *richer* on inferred relationships. Topolox is a narrow, **deterministic, zero-token, always-live code engine** that any MCP agent reads from — *faster, cheaper, and instantly rebuildable*. That's the trade Topolox makes to be an always-on backend.
+
+## Two ways to use it
+
+1. **Invisible backend (MCP).** Index once, register with your agent, and any MCP client silently pulls grounded, cheap context.
+   ```bash
+   topolox index .
+   topolox mcp install      # registers with Claude Code, Cursor, Codex, Gemini CLI, VS Code, ...
+   topolox daemon           # keep the graph live in the background
+   ```
+2. **The TUI cockpit** *(planned — Phase 3).* A 3-pane terminal dashboard (agent chat · live knowledge graph · daemon log), `topolox ui`. See [ROADMAP.md](ROADMAP.md).
+
+## Supported languages & agents
+
+**Languages** — symbol + import extraction for Python, JavaScript/JSX, TypeScript/TSX, Go, Rust, Java, C, C++, C#, Ruby, PHP, Kotlin, Swift, and Scala; any other [tree-sitter-language-pack](https://github.com/Goldziher/tree-sitter-language-pack) grammar (300+) is still parsed and indexed at the file level.
+
+**Agents** — `topolox mcp install` registers the MCP server with **Claude Code, Cursor, OpenAI Codex CLI, Gemini CLI, VS Code, Windsurf, and Claude Desktop** (and any other MCP client — it's a standard stdio MCP server).
+
+## Install (from source)
+
+```bash
+git clone https://github.com/Karnav018/topolox.git
+cd topolox
+uv sync
+uv run topolox --help
+```
+
+## Development
+
+```bash
+uv sync                       # create the env + install dev tools
+uv run ruff check .           # lint
+uv run ruff format .          # format
+uv run mypy src               # type-check (strict)
+uv run pytest                 # tests
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Contributions welcome once the engine lands.
+
+## Tech stack
+
+Python 3.11+ · [Kùzu](https://kuzudb.com) (graph) · [LanceDB](https://lancedb.com) (vectors) · [tree-sitter](https://tree-sitter.github.io) (AST) · [FastMCP](https://gofastmcp.com) (MCP server) · [watchdog](https://github.com/gorakhargosh/watchdog) (daemon) · [Textual](https://textual.textualize.io) (TUI) · [Typer](https://typer.tiangolo.com) (CLI). Optional: `fastembed` (local embeddings), `anthropic` (TUI chat).
+
+## License
+
+[MIT](LICENSE)