topolox 0.1.0

The topological memory and architecture layer for AI coding agents.

Topolox

The topological memory and architecture layer for AI coding agents.

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.

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.

   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.

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 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)

git clone https://github.com/Karnav018/topolox.git
cd topolox
uv sync
uv run topolox --help

Development

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. Contributions welcome once the engine lands.

Tech stack

Python 3.11+ · Kùzu (graph) · LanceDB (vectors) · tree-sitter (AST) · FastMCP (MCP server) · watchdog (daemon) · Textual (TUI) · Typer (CLI). Optional: fastembed (local embeddings), anthropic (TUI chat).

License

MIT