How AI agents use Graphify: connect, query, refresh

This page is written for you, the coding agent. Read it when a user wants you to use Graphify, or when the project’s instruction file says the repository is indexed in Graphify. To set Graphify up from scratch, follow Setup for AI agents step by step instead. Graphify is a code knowledge graph of the user’s repositories. You query it over MCP and get definitions, callers, dependencies and linked tests with file paths, instead of reading files one by one.

​

Connect

Default to the hosted server. Use open-source Graphify only when the user asks for an offline, on-machine or self-hosted setup. Before you change a config file, tell the user what you will change and wait for a yes. After you connect, check the connection with list_repositories. If anything fails, use Check your agent is using Graphify.

​

Pick the tool

The hosted server sends instructions on connect that map question types to tools, and it lists 27 tools. Your client builds its tool list from the server, so trust the live tool list and its input schemas over this table. Rules for the results:

• Use a repository_id from list_repositories: the UUID or the owner/name. Never invent an ID or silently pick a different repository.
• Check the returned symbol and file before you cite them. If a name matches several symbols, the result lists them under ambiguous. Say which one you used. If a name doesn’t resolve, you get an error with similar candidates, or a semantic match instead of an exact one. Say so and don’t treat it as the symbol the user asked about.
• Results carry freshness: the indexed commit and its age. Mention it when the age matters.
• An empty caller list means the index returned no callers. It does not prove the symbol is unused.
• search and graphify_find match part of a symbol’s name, like ReaSource or webhook, not a question. If a fragment returns nothing, try another name or ask query_graph in a full sentence.
• If graphify_trace finds no directed call path, it says so and returns the frontier it reached. Dynamic calls can hide a real path, so check the callees from there before you say A never reaches B.
• An empty recall result means nothing is remembered for that repository yet.
• Impact and test tools read the graph. They don’t run tests or prove runtime behavior.
• Use grep for exact strings, such as error messages or config keys.
• If a Graphify tool fails or the repository isn’t indexed, say so, then fall back to reading files. Don’t guess.

​

Ask before you change state

The tools don’t edit source files, but two of them change stored state on purpose. Ask the user first:

• remember saves a note to the workspace’s shared Memory. Save only what the user asked you to save.
• set_workspace changes which workspace, and so which repositories, the session reads. With make_default, it also changes the user’s default. See Hosted MCP.

In workspaces with trail capture turned on, search, query_graph, graphify_find, graphify_trace, graphify_rank_files and an unscoped recall can also save the question you asked to workspace memory. They never change source code.

​

Keep answers fresh

Hosted Graphify serves the indexed graph of each repository’s default branch. A push to the default branch starts a new index. Other branches and uncommitted changes are not in the graph. See Repository indexing and sync.

• Before you edit, read the local files the graph pointed you to. The checkout can be ahead of the index.
• If the user’s change is on a feature branch, say that the graph reflects the default branch.
• If a repository shows Out of date, tell the user. A reindex in the Console refreshes it.

With Graphify CLI, the graph is a file on the machine. Run graphify update . after a pull or merge, or offer graphify hook install to refresh after each commit. See Incremental updates.

​

While sign-in is pending

You can add the server, but only the user can finish the OAuth sign-in in a browser. Until they do, every tool call fails and the client shows the server as needing login.

1. Don’t retry in a loop, and don’t switch to Graphify CLI unless the user asks.
2. Tell the user exactly what to do for their client: for example /mcp → graphify → Authenticate in Claude Code, or codex mcp login graphify in Codex. The full list is in Check your agent is using Graphify.
3. Remind them that a new server loads only when a session starts, so they may need to reload the editor or start a new session.
4. Meanwhile, answer from the local files and say that the answer did not come from Graphify.
5. After sign-in, call list_repositories and show the result.

If list_repositories succeeds but is empty, sign-in worked and no repository is indexed in this workspace. Ask the user to index one at app.graphify.com or switch workspace.

​

Related