Code-Graph-RAG

Attach a durable note (a Gloss) to one definition in the graph, never to the source file. `target` names the definition the way `resolve` does, optionally with `#getter`, `#setter` or `#deleter` after it to name one member of a property (a `#` opening a name, as in a JS private member, is part of the name); a name matching several definitions is refused with the candidates, so pass a qualified name to disambiguate. `kind` types the claim (invariant, mirrors, platform-conditional, safety-precondition); `mentions` lists other definitions the note refers to, each becoming a MENTIONS edge. Write the WHY that is not in the code ("safe because validate() runs first"), not a restatement of what the code does. Returns the stored gloss, or an error and nothing written.

Ask the Code Graph RAG agent a question about the codebase. Uses the full RAG pipeline to analyse the code graph and provide a detailed answer. Use this for general questions about architecture, functionality, and code relationships.

Call sites inside a qualified name, one row per site with the callee and the location of the call: `path` is the file holding the site's `line` and `col` (the caller's, named by `through`) and `callee_path` the file defining the callee; `depth` > 1 follows the callees' callees. Deterministic: fixed graph queries, no LLM, same graph gives the same JSON. Use this instead of query_code_graph whenever you know the exact name or location.

Call sites that invoke a qualified name, one row per site with the caller, file, line, column, argument count and keyword names taken from the CALLS edges; `depth` > 1 follows the callers' callers (`through` names the callee each site invokes, `callee_path` its file). Deterministic: fixed graph queries, no LLM, same graph gives the same JSON. Use this instead of query_code_graph whenever you know the exact name or location.

Change a Python or JavaScript function's or method's parameter list and rewrite every call site the graph knows, on the definition and on every override in both directions. `new_params` lists the new parameters in order (`n: int`, `limit: int = 10`, or a bare old name to carry it over unchanged). `mapping` says where each new parameter's value comes from at a call site: an old parameter's name, its 0-based index, or `=literal` to insert that text at every site; a new parameter absent from the mapping takes the old parameter of the same name. A site the mapping cannot complete (a missing required value, a splat, a surplus argument, an undeclared keyword) or that the graph resolved heuristically is left as written and listed as `unmapped`; pass `allow_heuristic` to rewrite guessed sites too. Every rewritten file must still parse, and with an indexed project the change is undone when its postcondition fails. Set `dry_run` to see the plan and diff without touching the tree. Applied edits are recorded for `cgr edits undo`.

A graph-ranked minimal context slice for a task, within a token budget. `target` is a qualified name, a bare name, `path:line`, or free text (matched by embedding similarity when the semantic extra is installed). Returns the target's source, its direct callers' call lines, its direct callees' signatures, the types it accepts and returns, the tests that reach it, and the documentation sections whose file links to it, ranked by graph distance (trace hotness and similarity break ties) and trimmed to `budget_tokens`. Every piece says why it is included. Use this before reading whole files.

File, line span, decorators, docstring and source of one definition by qualified name (`found` is false when the graph has no such node). `start_line` and `source` open at the first decorator; `name_line` is the line of its name (the `def`/`class` line). Deterministic: fixed graph queries, no LLM, same graph gives the same JSON. Use this instead of query_code_graph whenever you know the exact name or location.

Delete a specific project from the knowledge graph database. This removes all nodes associated with the project while preserving other projects. Use list_projects first to see available projects.

Call sites, in any indexed project, that reach one endpoint: `target` is the handler's qualified name or the endpoint identity (`GET /users/{id}`), whichever parameter syntax the route declares (`:id`, `<id>`); a concrete request (`GET /users/42`) matches the routes it is served by. A target that names no endpoint the project exposes is refused with the close identities and handlers, so an empty list means nothing reaches it. Each row names the caller, its file, the URL it accesses and the direction (READS_FROM or WRITES_TO); an RPC or dispatch caller reaches the endpoint directly, so its `url` is the endpoint identity. Literal URLs resolve; dynamic ones do not and are absent here. Deterministic: fixed graph queries, no LLM, same graph gives the same JSON. Use this instead of query_code_graph whenever you know the exact name or location.

The endpoints a project exposes (routes, RPC methods, dispatch keys), one row per endpoint with its identity (`GET /users/{id}`), kind, handler, file and how many call sites in the whole graph reach it through RESOLVES_TO or a direct access. Zero callers on a graph holding only this project means none are indexed, not that the endpoint is dead; index the calling services with `--capture io` first. Deterministic: fixed graph queries, no LLM, same graph gives the same JSON. Use this instead of query_code_graph whenever you know the exact name or location.

Correlate a Python traceback with the code graph: each frame is resolved to its Function/Method/Module node and returned with its graph neighbourhood (callers, callees, and FLOWS_TO sources feeding it). FLOWS_TO sources require indexing with the `io` capture group. For an MCP server, set `CGR_CAPTURE=io` in the server environment before running index_repository or update_repository, then reindex after changing it. Frames outside the repository or unknown to the graph carry an unresolved reason instead. A traceback from another checkout (a CI runner, a container, a teammate's machine, Windows) is matched by the checkout root its frames share, reported as inferred_checkout_root; pass path_prefix_map when that root cannot be inferred. When nothing resolves, note says why. For an ExceptionGroup, frames is the stack that raised the group, and members holds each sub-exception (nested groups included) with its own frames; omitted_members counts those the traceback itself left out. Use this to ground a failure report in the indexed code before deciding where to look.

Finds structurally duplicated functions and methods (copy-pastes, including renamed and lightly edited copies) by comparing AST fingerprints stored in the graph. Returns clone groups with file:line locations, largest first: 'exact' groups are certain copies, 'similar' pairs carry a branch-overlap score. Use it to answer DRY questions ('where is this logic repeated?') and before writing a new helper to check whether an implementation already exists. Tune with 'threshold' (0-1 similarity, default 0.8) and 'min_size' (skeleton nodes, filters trivial getters).

Answer a source-to-sink data-flow reachability question with one of three verdicts: FOUND (a FLOWS_TO path exists, returned as qualified names), NO_FLOW (no path, and every module of the project was inside flow-analysis coverage), or UNKNOWN (no path found, but part of the project sits outside coverage; the uncovered files are named). An absent path must never be read as a verified absence when coverage gaps exist. The path may cross a service boundary: a NETWORK resource that resolves to another project's endpoint continues into that handler, `remote_hops` lists the (from, to) pairs where it does, and the coverage of every project entered counts towards the verdict. A source or sink that is not in the graph, or a source of another project, is refused with an error rather than answered. FLOWS_TO coverage requires indexing with the `io` capture group. For an MCP server, set `CGR_CAPTURE=io` in the server environment before running index_repository or update_repository, then reindex after changing it.

Retrieve source code for a function, class, or method by its qualified name. Returns the source code, file path, line numbers, and docstring.

Retrieves the source code for a specific function or method using its internal node ID, typically obtained from a semantic search result.

Notes (Glosses) about one definition: `annotating` are filed on it, `mentioning` are filed on other definitions and refer to it. `target` is resolved as `annotate` resolves it. Each note's `anchor_state` is graded after each sync of its project: EXACT when its definition's content hash still equals the one recorded at writing, STALE when it differs (EXACT again on revert), MOVED when the name is gone and exactly one definition in the project carries the recorded hash (the note follows it; `moved_from` keeps the old name), AMBIGUOUS when several do (`candidate_qns` lists them). When no definition carries the hash (a rename changes it), the note's text-quote anchor is tried: a digest of the definition's own text with its name masked, so exactly one definition in the project whose body still matches is followed as MOVED (then graded STALE, since the signature changed), several with the same body are told apart by the lines around them or listed as AMBIGUOUS, and none is LOST. The quote is recorded only when the note was written against this server's own checkout. A note on a module, or one written before hashes were recorded, is not graded while attached (there is no hash to compare) and is LOST if its name disappears (a module has no span to quote); a class, interface, enum, type or union carries a hash like a function and is graded and repaired the same way. A note's `mentions` are anchored the same way: a mentioned definition that is renamed or moved is followed by its hash or quote, one that cannot be placed is listed in `mentions_lost` with no edge (still, once another mention has taken its name), and a new definition that reuses its name does not inherit it. A target that no longer resolves returns the error plus `orphaned`: the unattached notes written against that name. Deterministic: fixed graph queries, no LLM, same graph gives the same JSON. Use this instead of query_code_graph whenever you know the exact name or location.

Types that inherit from or implement a class, interface or trait (INHERITS / IMPLEMENTS edges). Direct subtypes only by default; `depth` > 1 also follows their own subtypes (every class implementing an interface through an abstract base), each row then carrying its `depth` and the type it was reached `through`. Deterministic: fixed graph queries, no LLM, same graph gives the same JSON. Use this instead of query_code_graph whenever you know the exact name or location.

Modules that import a module, with each import statement's line, column, bound alias and imported symbol. Direct importers only, unless `through_reexports` is true: then also the modules that reach it through a re-export (a package `__init__.py`, a Rust `pub use`, an `index.ts` barrel), each row with `via`, the import statements it came through, consumer side first (empty for a direct importer). Deterministic: fixed graph queries, no LLM, same graph gives the same JSON. Use this instead of query_code_graph whenever you know the exact name or location.

WARNING: Clears all data for the current project including its embeddings. Parse and ingest the repository into the Memgraph knowledge graph. Use update_repository for incremental updates. Only use when explicitly requested.

List contents of a directory in the project.

List all indexed projects in the knowledge graph database. Returns a list of project names that have been indexed.

Methods overriding a method, and the method it overrides (OVERRIDES edges in both directions). Direct only by default; `depth` > 1 follows each direction on its own (the overriders' overriders, and what the overridden method overrides in turn), each row then carrying its `depth` and the method it was reached `through`. Deterministic: fixed graph queries, no LLM, same graph gives the same JSON. Use this instead of query_code_graph whenever you know the exact name or location.

Prefer the deterministic tools (resolve, definition, callers, callees, implementors, overrides, importers, tests_reaching) when you know the exact name or location: they run fixed queries with no LLM. Use this for open-ended questions. Query the codebase knowledge graph using natural language. Ask questions like 'What functions call UserService.create_user?' or 'Show me all classes that implement the Repository interface'. Pass `project` to restrict results to one indexed project; use list_projects for the available names. Omit it to search them all. The scope is enforced on the results before they are capped, so it holds regardless of the query generated and the result limit is spent on rows from the requested project.

Rank the sites that can explain a Python traceback's failure, best first. The anchor (failing) is the innermost frame the graph resolves; anchor_is_crash_site is false when the actual crash line sits deeper (a library frame, or a frame the graph cannot match), so the ranking reads as relative to the deepest resolvable frame. Candidates score by three additive signals: being a FLOWS_TO source into the failing frame (a possible producer of the failing value), sitting on the crashing stack itself, and reaching the failing frame through CALLS edges (closer callers score higher). Each candidate carries its file, definition line, reasons, and the call path to the failure. When the project has no FLOWS_TO edges the ranking degrades to a CALLS-only walk and flow_used is false; flow_gaps always names the files outside flow-analysis coverage. FLOWS_TO coverage requires indexing with the `io` capture group. For an MCP server, set `CGR_CAPTURE=io` in the server environment before running index_repository or update_repository, then reindex after changing it. Frames from another checkout resolve as in explain_traceback, and resolution plus note say why a ranking is empty. For an ExceptionGroup, the ranking anchors where the group was raised, and members ranks each sub-exception against its own failing frame.

Read the contents of a file from the project. Supports pagination for large files.

Re-ingest specific files into the knowledge graph after editing them. Re-parses only the given files and the files that depend on them, and re-resolves calls in that set only; an edit that leaves a file's interface unchanged (a comment, or a function body no other file's resolution reads) re-parses no dependents at all. An edit lands in the graph in the time it takes to parse the affected dependents (hundreds of milliseconds for a typical file, seconds for a hub imported by dozens) instead of a full update_repository pass. Paths are relative to the project root; files that no longer exist are removed from the graph; paths the project's ignore rules exclude are skipped and reported rather than indexed. Repository-wide passes are not re-run: code-quality findings (smells, vulnerabilities, patterns) and URL-to-endpoint links are rebuilt only by update_repository. Returns the files re-parsed, the dependents re-parsed with them, the files removed, the paths skipped, and the elapsed milliseconds.

Every network access a project makes, one row per call site and URL, with the endpoint, handler and project it resolves to when one is indexed; a row with no endpoint is a dependency the graph cannot place (a dynamic URL, or a service not indexed). Deterministic: fixed graph queries, no LLM, same graph gives the same JSON. Use this instead of query_code_graph whenever you know the exact name or location.

Rename a function, method, class or other definition everywhere the graph knows it is referenced: the definition, every call, reference and instantiation site, import statements (aliases kept), overrides in both directions, and Python `__all__` entries. Refuses when any site was resolved heuristically, by overload fan-out, or only by a trace, unless `allow_heuristic` is true. It also refuses when the source names the symbol where the graph has no site (a call the index missed), listing those occurrences as `unplanned`; `allow_heuristic` rewrites them as guessed sites. A class referenced by an inheritance or type annotation edge that carries no rewrite location refuses regardless of `allow_heuristic`. Every rewritten file must still parse; otherwise nothing is written. Set `dry_run` to see the plan and diff without touching the tree. Applied edits are recorded for `cgr edits undo`, and Markdown mentions of the old name are listed for a human to review.

Resolve a name or a location to qualified names in the graph. `target` is a qualified name, a bare name like `helper` or `Store.get`, or `path:line` (the file's path relative to the repository root or absolute inside it, a 1-based line, optionally `:col`) for the definitions spanning that line, innermost first; a file the project does not hold is refused with an error. Exact matches come first, then dotted-suffix matches, then same-name matches. Deterministic: fixed graph queries, no LLM, same graph gives the same JSON. Use this instead of query_code_graph whenever you know the exact name or location.

Surgically replace an exact code block in a file using diff-match-patch. Only modifies the exact target block, leaving the rest unchanged. After a successful write on an indexed project, the touched files are re-ingested and a structural delta is appended to the result as JSON: symbols added, removed and renamed, callers left dangling, call sites passing too many arguments, signature changes with a verdict per call site, new duplicates of existing functions, new import cycles, and the tests reaching the edited symbols. A project that is not indexed appends nothing, and a failed analysis appends an error note instead of a delta. Read it before the next edit.

Test functions and methods from which a qualified name is reachable through CALLS / REFERENCES / INSTANTIATES, with the distance and the symbol each test reaches it through: what to run after editing it. Deterministic: fixed graph queries, no LLM, same graph gives the same JSON. Use this instead of query_code_graph whenever you know the exact name or location.

Update the repository in the Memgraph knowledge graph without clearing existing data. Use this for incremental updates.

WARNING: Completely wipe the entire database, removing ALL indexed projects. This cannot be undone. Use delete_project for removing individual projects.

Write content to a file, creating it if it doesn't exist. After a successful write on an indexed project, the touched files are re-ingested and a structural delta is appended to the result as JSON: symbols added, removed and renamed, callers left dangling, call sites passing too many arguments, signature changes with a verdict per call site, new duplicates of existing functions, new import cycles, and the tests reaching the edited symbols. A project that is not indexed appends nothing, and a failed analysis appends an error note instead of a delta. Read it before the next edit.