Build a Local Code Graph and Memory for Coding Agents with Graphicle

What is Graphicle?

Graphicle is a local Rust program that combines a repository code graph with project memory for coding agents. It indexes files, functions, classes, calls, and imports, while also remembering documentation, decisions, procedures, and past agent sessions.

When an agent or developer asks a question, Graphicle returns cited excerpts that identify the source file and line range. The code graph and core context tools work without an API key or account, and Graphicle does not send data anywhere unless you explicitly configure a model or connector that requires it.

Graphicle works with Claude Code, Cursor, Codex, VS Code, Claude Desktop, and other MCP clients. It provides a command-line interface, an MCP server, a browser app, and a single SQLite-based data store.

Key features

• Code graph: Explore files, symbols, calls, imports, paths, and affected code using a tree-sitter-based parser.
• Project memory: Search Markdown, PDF, Office, and HTML documents, reviewed decisions, procedures, and captured agent sessions.
• Cited context: Retrieve relevant excerpts from code and project knowledge within a token budget, without calling a model.
• Agent integration: Connect supported coding agents through MCP with one setup command.
• Memory tied to code: Reviewed memories can be anchored to the functions they describe and become stale when that code changes.
• Local-first operation: Data is stored locally, endpoints listen on loopback by default, and Graphicle uses no telemetry or account.
• Automatic synchronization: Changed files sync before answers, while Git hooks can synchronize after commits, merges, and checkouts.

Install Graphicle

Graphicle currently supports macOS and Linux. The simplest installation method on macOS or a Linux system with Homebrew is:

brew install graphicle-ai/tap/graphicle

If Homebrew is unavailable, use the release installer:

curl -fsSL https://github.com/graphicle-ai/graphicle/releases/latest/download/install.sh | sh

You can also download a platform-specific archive from the GitHub releases page. Native Windows support is not currently available, although the README notes that the Linux installation may work under WSL2 and has not yet been tested.

Set up a repository

Change into the repository that you want your agents to understand, then run setup:

cd your-repo
graphicle setup

The setup process indexes the repository, builds its code graph, and connects the coding agents it finds. Depending on the clients installed on your machine, it can update MCP configuration for Claude Code, Codex, Cursor, VS Code, Claude Desktop, and other MCP clients.

Setup also enables session capture, points Claude Code searches toward the code graph, adds a short section to AGENTS.md, and installs Git hooks that help keep the project current. Graphicle lists every file it changes and creates a backup before modifying it. To let setup run without interactive prompts, use:

graphicle setup --yes

To undo the integration changes, run:

graphicle disconnect

The disconnect command removes what setup added. It does not delete the repository's existing Graphify output directory.

Ask questions from the terminal

After setup, use graphicle ask to search the repository:

graphicle ask "where is tax added to prices?"

Graphicle returns evidence with file names, line ranges, symbols, and excerpts. A result can look like this:

Evidence for "where is tax added to prices?"
4 excerpts · 598 of 3,000 tokens

[1] shop/pricing.py:1-7  price_with_tax()
    """Prices and tax."""
    TAX_RATE = 0.2

    def price_with_tax(price):
        """A price with the sales tax added."""
        return round(price * (1 + TAX_RATE), 2)

With no model configured, ask displays the evidence. To have Graphicle add a written answer, configure a supported model provider such as Anthropic, OpenAI, or Ollama:

graphicle config set model anthropic

Local models through Ollama and OpenAI-compatible servers are also supported. See the configuration documentation for model settings.

Use Graphicle with an agent

Once graphicle setup has connected an MCP client, ask your coding agent to use Graphicle for repository questions. For example:

Use Graphicle to find where failed requests are retried.

The agent can use Graphicle's code-graph and memory tools, receive cited excerpts, and combine those results with its own reasoning. Graphicle exposes one MCP server containing code-graph tools and memory tools. Its graph tools include names such as query_graph, get_neighbors, and shortest_path.

Browse the graph and project memory

To open Graphicle's browser app, run:

graphicle open

The app lets you browse the code graph, source material, and project memory. It is also where proposed memories can be reviewed and approved.

For a health check covering the installation and integrations, run:

graphicle doctor

Use doctor when an agent cannot connect, synchronization appears incomplete, or you want to verify the configured environment.

Explore dependencies and affected code

Graphicle can build and query a code-only graph. First extract the graph:

graphicle graph extract . --code-only

Then ask which code depends on a symbol:

graphicle graph affected "retry()"

The graph command can search the repository, explain symbols, trace paths, and export an interactive HTML graph. The --code-only mode does not require a model.

Graphicle can also connect mentions of code in project documents to the definitions they reference. Use the document-linking graph command to list those relationships:

graphicle call graph.doc_links

Retrieve context without an answer model

The context command retrieves relevant excerpts from code, documents, sessions, and reviewed memory. It does not call a model:

graphicle context

For a workspace containing multiple repositories, request context across the workspace:

graphicle context --workspace

This makes Graphicle useful when an implementation in one repository depends on documentation or source code in another repository. Workspace MCP configuration is described in the MCP documentation.

Understand synchronization and privacy

During synchronization, Graphicle respects .gitignore and skips environment files, keys, and credentials. Session capture removes content inside <private>...</private> spans and redacts credentials.

On macOS, the main local data folder is ~/Library/Application Support/Graphicle. On Linux, it is ~/.local/share/graphicle. A graph created by graphicle graph extract is written to .graphicle/ inside the project.

The app, HTTP endpoints, and MCP endpoints listen on 127.0.0.1 by default. Network access occurs only when you request a feature that needs it, such as a configured model or connector, a full graph extraction that sends documents or images to an LLM, selected GitHub CLI operations, or an update feed.

Advanced tips

Keep answers grounded in evidence

Use Graphicle's cited excerpts to verify an agent's claims against exact files and lines. This is especially useful for debugging, understanding unfamiliar repositories, and reviewing changes.

Review proposed memories

Agent-proposed memories do not become trusted project knowledge automatically. Review them in the app before approval. Memories anchored to code symbols can become stale when the related code changes, while edits elsewhere in the same file usually leave them current.

Use Git hooks for current context

Keep the repository synchronized by retaining the hooks installed during setup. They sync after commits, merges, and checkouts, while Graphicle also synchronizes files changed before an answer.

Adjust repository limits

By default, a project can contain up to 100,000 text files and 1 GiB of text. The limits can be raised in the configuration if you are working with a larger repository. Very large files may be analyzed partially or retained as searchable text instead of stopping synchronization.

Connect another MCP client

For clients that Graphicle does not detect automatically, add the short JSON MCP configuration described in the MCP guide. The same MCP server provides both graph and memory capabilities.

Conclusion

Graphicle gives coding agents a local, searchable view of repository structure and project knowledge. Install it, run graphicle setup, and use ask, context, open, and graph to investigate code with citations. Configure a model only when you want generated answers; the graph, synchronization, MCP server, session capture, and app can operate without one.

For more detail, continue with the project's quick start, agent guide, configuration reference, and FAQ.