SymDex — Summary

SymDex is a repo-local symbolic indexing engine for AI coding agents. It maps a project into exact symbols, file outlines, HTTP routes, caller/callee graphs, and token-budgeted context packs, stored in a local SQLite database (~/.symdex/ or ./.symdex/). It ships 21 MCP tools and a CLI with matching subcommands, covering 21 language surfaces. The core value proposition is "exact retrieval instead of file scanning": get_symbol returns one function's source instead of a whole file; build_context_pack assembles a token-budgeted evidence bundle for a feature question.

SymDex includes a dedicated symdex-code-search agent skill (installable via npx skills add) that instructs supported AI agents to search with SymDex before broad Read/Grep/Glob exploration. Every CLI search command and MCP tool output includes ROI metadata (roi, roi_summary, roi_agent_hint) so agents can report token savings in their responses. Semantic search backends include local sentence-transformers, Voyage, OpenAI-compatible, and Gemini Embedding — all optional; the base install is lean with no embedding dependency.

Compared to seeds, SymDex is closest to the ccmemory concept of providing a structured query layer over code, but it is a code structure index (not a conversation memory system): it indexes symbols, routes, and call graphs rather than storing decisions or conversation history. Unlike CogniLayer (which also does tree-sitter code intelligence), SymDex is a pure indexing/retrieval tool with no memory of facts, no hooks, and no session management.

SymDex — Overview

Origin

Husnain Khalid (husnainpk). MIT license. Version 0.1.26. Python 3.x, PyPI package symdex. Active (last commit 2026-04-22).

Philosophy

From README:

"SymDex turns a checked-out repository into a local symbolic index of code structure, routes, relations, docs, tests, and context so AI coding agents can reason, retrieve, and act without reading whole files first."

"AI coding agents are useful until they have to rediscover your repo from scratch. They open whole files, grep broad patterns, miss the route handler, read the same utility twice, and spend thousands of tokens just getting oriented."

Core tenets:

• Exact symbols, not file contents — get_symbol returns the exact function with byte offset, not the whole file
• Token-budgeted context packs — build_context_pack assembles just enough evidence for a query within a token budget
• ROI-first design — every search returns roi, roi_summary, roi_agent_hint so agents can quantify and communicate token savings
• Local-first, lean by default — base install has zero embedding dependency; semantic search is opt-in
• Multi-repo awareness — a registry supports multiple repos and worktrees; workspace-local .symdex for Docker/teams

Design Choices

• Lean core vs full: pip install symdex installs the lean core (no embeddings); pip install "symdex[local]" adds sentence-transformers.
• Lazy indexing: symdex index --lazy does foreground structural indexing with background embedding fill, so agents can start immediately.
• Quality metadata: every result includes quality fields (confidence, freshness, parser mode, generated-file hints, embedding availability) so agents can judge reliability.
• Agent skill: the symdex-code-search SKILL.md is the behavioral layer that trains agents to use SymDex first.

SymDex — Architecture

Distribution

PyPI package: pip install symdex or uv tool install symdex

Install Methods

pip install symdex                     # lean core
pip install "symdex[local]"            # + local semantic search
uv tool install symdex                 # isolated CLI tool
uvx symdex --help                      # run without installing
npx skills add https://github.com/husnainpk/SymDex --skill symdex-code-search --yes --global

CLI Binary

symdex — Python CLI entrypoint (via pyproject.toml)

Directory Structure

symdex/
├── symdex/         # Python package
│   ├── cli/        # CLI commands
│   ├── indexer/    # Symbol + route extractor (tree-sitter per language)
│   ├── search/     # FTS + semantic search
│   ├── mcp/        # MCP server (21 tools)
│   └── registry/   # Multi-repo registry management
skills/
└── symdex-code-search/
    └── SKILL.md    # Agent skill file

State Files

• ~/.symdex/registry.db + registry.json — global multi-repo registry (default)
• ~/.symdex/<repo-id>/ — per-repo index database with symbols, embeddings, route index
• ./.symdex/ — workspace-local state when SYMDEX_STATE_DIR=.symdex (optional)

Required Runtime

• Python 3.x
• Optional: sentence-transformers (local embeddings), VOYAGE_API_KEY / OpenAI-compat / Gemini API key (hosted embeddings)
• Optional: SYMDEX_EMBED_RPM env var for request pacing

Target AI Tools

Any MCP client: Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, Windsurf, Roo, Kilo Code, VS Code. Also usable via CLI in shell-based agents.

Transport

stdio (default MCP) or HTTP (symdex serve --http, port 8080).

SymDex — Components

MCP Tools (21)

CLI Subcommands

index, search, text, semantic, routes, pack, serve, repos, watch, stats

Plus shell aliases: index-folder, index-repo, list-repos (MCP-shaped names).

Skills (1)

• symdex-code-search — SKILL.md that instructs agents to use SymDex before broad file browsing; includes tool selection table, core rules, and current version snapshot.

Hooks

None — SymDex has no lifecycle hooks.

Scripts

None — all operations via CLI or MCP.

Semantic Backends (4)

• local — sentence-transformers (no API key)
• voyage — Voyage AI embedding API
• openai-compat — Any OpenAI-compatible /embeddings endpoint
• gemini — Google Gemini Embedding API

SymDex — Uniqueness

Differs From Seeds

SymDex occupies a unique niche in this batch: it is a code structure index, not a conversation memory system. The closest seed is none directly — it is most similar to the code intelligence layer inside CogniLayer (code_index, code_context, code_impact), but SymDex is standalone with 21 tools dedicated to this function, while CogniLayer's code intelligence is one component of a larger memory system. Against basic-memory (knowledge graph) and ccmemory (decision graph): those store AI conversation history and semantic facts; SymDex stores current codebase structure (symbols, routes, call graphs) that doesn't require AI conversations at all. Against taskmaster-ai: taskmaster decomposes tasks from conversation; SymDex maps code structure from AST parsing.

Unique Features in This Batch

1. ROI metadata in every response — per-call token savings (roi, roi_summary, roi_agent_hint) so agents can quantify and communicate savings. No other framework in this batch does this.
2. 21 language surfaces — broadest language coverage in this batch (Python, Go, Kotlin, Dart, Swift, HTML, CSS, Shell, Vue/Svelte, Markdown, etc.).
3. HTTP route extraction — extracts API routes from 9 framework patterns (Flask, Express, Spring, Laravel, Gin, ASP.NET, Rails, Phoenix, Actix). Unique to SymDex in this batch.
4. Quality metadata — every result includes confidence, freshness, parser mode, generated-file hints so agents can judge reliability before reasoning.
5. Multi-repo registry — one SymDex install indexes many repos with a global registry, enabling cross-repo symbol search.

Observable Failure Modes

1. No hooks — code changes outside a watched session don't auto-update the index; agent must call invalidate_cache or index_folder manually.
2. Semantic search is opt-in — without fastembed, all semantic search calls fail gracefully but return only FTS results.
3. Worker registration — SYMDEX_EMBED_RPM rate limiting can slow indexing for large repos with hosted embedding providers.
4. Index staleness — get_index_status must be called to detect stale indexes; agents that skip this step may reason from outdated symbols.
5. No conversation awareness — SymDex knows nothing about what the agent has discussed; if an agent needs "what did we decide about this function", SymDex cannot help.