# How to Set Up Real-Time Updates for Code-Graph-RAG

> Set up real-time updates for Code-Graph-RAG with `make watch`. Enable automatic knowledge graph synchronization and incremental updates for debounced file changes, reflecting only affected nodes.

- Repository: [Vitali Avagyan/code-graph-rag](https://github.com/vitali87/code-graph-rag)
- Tags: how-to-guide
- Published: 2026-09-04

---

**Run `make watch REPO_PATH=/path/to/repo` after installing dependencies and starting Memgraph on `localhost:7687` to enable automatic, incremental knowledge graph synchronization that debounces file changes and updates only affected nodes.**

Code-Graph-RAG is an open-source project that bridges source code and graph databases for AI retrieval. When you set up real-time updates for Code-Graph-RAG, a file-system watcher monitors your repository and incrementally refreshes the Memgraph knowledge graph without requiring full re-indexes.

## Prerequisites

Before starting the watcher, ensure your environment meets the following requirements.

**Install the development environment**, including the optional `treesitter-full` extra required for language parsers:

```bash
make install

```

**Start a Memgraph instance** listening on the default address `localhost:7687`. If your database requires authentication, export the credentials in your environment:

```bash
export MEMGRAPH_USERNAME=your_user
export MEMGRAPH_PASSWORD=your_pass

```

The watcher reads these values from [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py) via the `settings` object.

## Launching the Real-Time Updater

You can invoke the watcher directly via CLI or use the Makefile convenience target.

**Direct execution** via [`realtime_updater.py`](https://github.com/vitali87/code-graph-rag/blob/main/realtime_updater.py):

```bash
python realtime_updater.py /path/to/your/repo \
    --host localhost --port 7687 --batch-size 1000 \
    --debounce 5 --max-wait 30

```

**Makefile shortcut** (recommended):

```bash
make watch REPO_PATH=/path/to/your/repo

```

The `--debounce` parameter (seconds) defines the quiet period the watcher waits after the last change before processing. The `--max-wait` parameter caps the maximum delay so updates are not postponed indefinitely during rapid editing sessions.

## How the Real-Time Pipeline Works

The real-time system consists of several coordinated components that optimize for speed and accuracy.

### File System Watching and Debouncing

The entry point [`realtime_updater.py`](https://github.com/vitali87/code-graph-rag/blob/main/realtime_updater.py) initializes a **watchdog** that detects file creates, modifies, and deletes. The `CodeChangeEventHandler` class debounces rapid saves, filters ignored paths, and invokes the incremental update logic.

When a change is detected, the handler waits for the debounce interval specified by `DEFAULT_DEBOUNCE_SECONDS` (defined in [`codebase_rag/constants.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/constants.py)) to ensure the file system has stabilized. You can override this via the `--debounce` CLI argument.

### Incremental Re-ingest Logic

The `GraphUpdater` class in [`codebase_rag/graph_updater.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_updater.py) executes the core `reingest` method. Rather than rebuilding the entire graph, this method:

1. Deletes previous contributions of the changed file from Memgraph
2. Re-parses only the affected file and its **one-level dependents**
3. Resolves call relationships for that subset
4. Writes the delta to the database via the `MemgraphIngestor`

This scoped re-ingest logic mirrors the behavior of the MCP `reingest` tool, ensuring the graph stays current without the latency of a full repository scan.

### Batched Database Writes

The `MemgraphIngestor` in [`codebase_rag/services/graph_service.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/services/graph_service.py) handles bulk inserts and updates. You can tune throughput for large repositories by increasing the `--batch-size` parameter, which controls how many nodes and edges are written in a single transaction.

## Configuration Options

Fine-tune the watcher behavior through environment variables, CLI arguments, or source constants.

**Environment Variables:**
- `MEMGRAPH_USERNAME` and `MEMGRAPH_PASSWORD` for database authentication
- `REALTIME_LOGGER_FORMAT` to customize log output formatting (uses **loguru**)

**CLI Arguments:**
- `--debounce`: Override `DEFAULT_DEBOUNCE_SECONDS` (default defined in [`codebase_rag/constants.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/constants.py))
- `--max-wait`: Override `DEFAULT_MAX_WAIT_SECONDS` for the maximum delay cap
- `--batch-size`: Control bulk write granularity for `MemgraphIngestor`

**Programmatic Defaults:**
Modify [`codebase_rag/constants.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/constants.py) to change repository-wide defaults for debounce timing and batch sizing if you prefer not to pass CLI flags.

## Programmatic Integration

You can embed the watcher in other Python scripts by importing the `start_watcher` function from [`realtime_updater.py`](https://github.com/vitali87/code-graph-rag/blob/main/realtime_updater.py):

```python
from realtime_updater import start_watcher

repo = "/home/user/my-project"
start_watcher(
    repo_path=repo,
    host="localhost",
    port=7687,
    batch_size=2000,
    debounce_seconds=2.0,
    max_wait_seconds=15.0,
)

```

This pattern is useful for building custom development tools or CI pipelines that require real-time graph synchronization.

## Summary

- **Installation** requires `make install` to obtain the `treesitter-full` parser dependencies
- **Entry point** is [`realtime_updater.py`](https://github.com/vitali87/code-graph-rag/blob/main/realtime_updater.py), which delegates to `CodeChangeEventHandler` for debounced file watching
- **Incremental updates** are handled by `GraphUpdater.reingest` in [`codebase_rag/graph_updater.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_updater.py), limiting re-parsing to changed files plus one-level dependents
- **Database writes** are batched via `MemgraphIngestor` in [`codebase_rag/services/graph_service.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/services/graph_service.py)
- **Tuning** is available via CLI flags (`--debounce`, `--max-wait`, `--batch-size`) or constants in [`codebase_rag/constants.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/constants.py)

## Frequently Asked Questions

### What triggers a real-time graph update?

Any file system event—create, modify, or delete—within the watched repository path triggers the `CodeChangeEventHandler`. After the debounce period elapses, the handler calls `GraphUpdater.reingest` to synchronize only the changed file and its immediate dependents with Memgraph.

### How do I configure authentication for Memgraph?

Set the `MEMGRAPH_USERNAME` and `MEMGRAPH_PASSWORD` environment variables before launching the watcher. The `settings` object in [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py) automatically picks up these values and passes them to the database connection pool used by `MemgraphIngestor`.

### What is the scope of files re-parsed during an update?

The pipeline performs a **scoped re-ingest**: it deletes the previous graph contributions of the changed file, re-parses only that file, and resolves calls for its one-level dependents. This avoids the overhead of re-indexing the entire codebase while maintaining referential integrity in the knowledge graph.

### How can I tune performance for large repositories?

Increase the `--batch-size` parameter (default is typically 1000) to allow `MemgraphIngestor` to write larger transactions in [`codebase_rag/services/graph_service.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/services/graph_service.py). For extremely active development, reduce the `--debounce` interval in [`realtime_updater.py`](https://github.com/vitali87/code-graph-rag/blob/main/realtime_updater.py) or adjust `DEFAULT_DEBOUNCE_SECONDS` in [`codebase_rag/constants.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/constants.py) to trade stability for lower latency.