budget-aware-mcp
Model-agnostic code memory MCP server. Budget-aware graph retrieval for AI agents. Sub-millisecond queries, token budgeting, deterministic results. Built on CodeGraphContext.
MCP server that gives AI coding assistants budget-aware code context by walking call and import graphs from an anchor symbol until a token limit is hit, backed by SQLite and tree-sitter.
budget-aware-mcp is an MCP server, which is a small program that an AI coding assistant talks to in order to fetch information about a codebase. This one is meant to be a model-agnostic code memory tool: the assistant can ask it questions about your source code and get back a small, structured answer instead of being flooded with raw files. The author builds it on top of an existing project called CodeGraphContext, which already knows how to parse 155 languages using tree-sitter, and replaces the retrieval layer with what they call budget-aware graph walks.
The argument for the project is that most code-memory tools just dump everything they find, which fills up the assistant's context window and leads to hallucinations or wasted spend. Here, the agent asks for context around a symbol with a token budget, for example 8000 tokens around AuthService, and the server walks outward from that symbol along real call and import edges, stopping the moment the budget is reached. No embeddings or vector database is used, and there are no API keys to set up. The data is kept in SQLite.
The server exposes 22 tools grouped into indexing, retrieval, discovery, context, and management. Examples include index_repo to parse and index a project, graph_walk for hop-limited walks from an anchor symbol, check_scope to ask if a task is feasible without making any LLM call, trace_call_path between two symbols, analyze_impact to estimate the blast radius of a change, fuzzy_find_symbol, find_dead_code, and get_session_stats for cumulative token accounting.
Installation is npm install -g budget-aware-mcp followed by budget-aware-mcp install, which auto-configures Kiro, Claude Code, Cursor, VS Code, Windsurf, Zed, Codex CLI, Gemini CLI, Aider, and OpenCode.
Where it fits
- Give Claude Code or Cursor scoped context around a symbol instead of dumping whole files
- Trace the call path between two functions across a 155-language codebase
- Estimate the blast radius of a refactor before making any LLM call
- Find dead code and fuzzy-match symbols across a large repo