topolox 0.1.4

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 but usable. The engine — multiprocessing parser, Kùzu + LanceDB index, query layer, MCP server, daemon, and 14-language support — is built and on PyPI. The TUI and benchmarks are next; 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, ...
   

   Then connect your agent — its MCP server reads the index read-only, so several agents (Claude Code, Cursor, …) can connect at once. Re-run topolox index to refresh.

   ⚠️ One writer at a time. Kùzu lets only one process write the database, so don't run topolox daemon while an agent is connected — they'd fight over the lock (MCP error -32000: Connection closed). A combined always-live server (one process that watches and serves over HTTP) is on the roadmap.

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

The four tools your agent gets

Tool	Use it for
get_file_dependencies(path, depth)	what a file imports, and what imports it
analyze_blast_radius(changed_files, max_depth)	which files/tests a change would impact
prune_context(prompt, token_budget)	the most relevant symbols/files for a prompt
search_architecture_graph(query, limit)	semantic + structural search over the codebase

Nudge the agent with "Using topolox, …" so it reaches for these instead of grepping. deps and blast are graph-based and most reliable; search/prune ranking improves with the [embeddings] extra.

CLI

topolox index .                 # build / refresh the index in .topolox/
topolox index --dry-run .       # preview what gets parsed (no writes)
topolox deps   <file>           # dependencies + dependents of a file
topolox blast  <file...>        # blast radius of changing file(s)
topolox prune  "<question>"     # pruned, token-budgeted context
topolox mcp install [--client claude-code|cursor|codex|gemini|vscode|windsurf|claude-desktop|all]
topolox mcp serve               # run the MCP server over stdio (agents usually spawn this)

Install

pip install topolox                 # from PyPI  (or: uv tool install topolox)
pip install 'topolox[embeddings]'   # optional — local embeddings for semantic search / prune

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