memgraph-ingester

Requirements

For normal use:

• Memgraph, either local, Docker, or an existing Bolt endpoint.
• One ingester download from the release page.

Runtime requirements by artifact:

Optional tools:

• mgconsole, if you want to query Memgraph directly without MCP (produces much fewer tokens)
• Maven, only if you want a richer Java classpath or you want to build from source.
• Java 25 SDK, only if you build from source.

Use as a Maven dependency

<dependency>
  <groupId>io.github.ousatov-ua</groupId>
  <artifactId>memgraph-ingester</artifactId>
  <version>9.0.3</version>
</dependency>

Agent Setup

The graph is useful directly, but it becomes much more powerful when your agent is told to use it. The executable can write project-scoped Memgraph instructions to the agent's local instruction file. It replaces its own previously managed block when one already exists, so rerunning the command keeps AGENTS.md, CLAUDE.md, or another instruction file tidy.

Run the command from the repo you just ingested, using the same --project value.

Code graph guidance is installed by default:

memgraph-ingester --init-instructions -P my-project
memgraph-ingester -P my-project --instructions-agent codex

Add optional Memory workflow instructions when you want agents to create and maintain durable Memgraph Memories:

memgraph-ingester --init-instructions -P my-project --with-memories
memgraph-ingester -P my-project --instructions-agent codex --with-memories

Agent presets choose the default target file:

memgraph-ingester --init-instructions -P my-project --instructions-agent codex
memgraph-ingester --init-instructions -P my-project --instructions-agent claude
memgraph-ingester --init-instructions -P my-project --instructions-agent gemini
memgraph-ingester --init-instructions -P my-project --instructions-agent github

When --instructions-agent is present, --init-instructions is optional.

Use --instructions-file to target a specific file:

memgraph-ingester -P my-project --instructions-file .github/copilot-instructions.md

The legacy helper scripts now delegate to the executable and accept the same optional flags:

MEMGRAPH_INGESTER_BIN=./memgraph-ingester-macos-arm64 script/init-memgraph-codex.sh my-project --with-memories

Commit the updated instruction file so future agent sessions get the same graph guidance.

For Enthusiasts: Build It Yourself

You do not need this section to use the tool. Use the release downloads unless you want to hack on the project.

Build the shaded JAR

Requirements:

• Java 25 SDK.
• Maven 3.9+.

git clone https://github.com/ousatov-ua/memgraph-ingester.git
cd memgraph-ingester
mvn clean package -Pshade -DskipTests

Output:

target/memgraph-ingester.jar

Run it:

java -jar target/memgraph-ingester.jar --help

Build a native executable

Native builds use GraalVM Native Image and build for the OS where Maven runs.

mvn clean package -Pnative-macos -DskipTests
mvn clean package -Pnative-linux -DskipTests
mvn clean package -Pnative-windows -DskipTests

Use the profile that matches your operating system.

Quick Start

Java Guide

The Java adapter reads .java files using JavaParser with Java 25 syntax support. It should handle most earlier Java versions as well.

Captured Java structure:

• Packages and files.
• Classes, interfaces, annotations, enums, records, and nested classes.
• Methods, constructors, fields, visibility, return types, static flags, line ranges, and synthetic flags.
• EXTENDS, IMPLEMENTS, DECLARES, DEFINES, CONTAINS, ANNOTATED_WITH, and best-effort CALLS.

Use --classpath whenever you can. Without dependency JARs, the ingester still works, but external types may fall back to simple names and some call edges may be missing.

For Maven projects:

CP=$(mvn -q dependency:build-classpath -DincludeScope=test -Dmdep.outputFile=/dev/stdout 2>/dev/null)

Use -DincludeScope=test when you ingest tests or test fixtures. It includes JUnit, Testcontainers, mocking libraries, and other test-scoped dependencies.

Generated code is indexed only if you ingest it:

<ingester> \
  --source target/generated-sources/annotations \
  --bolt bolt://localhost:7687 \
  --project my-java-project

Do not pass --wipe-project-code on the generated-source pass unless you want to replace the previous graph with generated sources only.

JavaScript and TypeScript Guide

Use --language js, --language javascript, --language ts, or --language typescript.

Accepted source extensions:

• .js
• .jsx
• .ts
• .tsx
• .mts
• .cts
• .d.ts
• .d.mts
• .d.cts
• .mjs
• .cjs

Only source files under --source are considered. Use the repository root as --source when you want root JavaScript config files or support scripts indexed alongside application source. tsconfig.json and configs from its extends chain are read for TypeScript path aliases when present, but they are not indexed as code nodes.

Skipped paths:

• Anything under node_modules.

Captured JS/TS structure:

- Files and synthetic module owners. - Classes and class expressions assigned to variables. - Interfaces and type aliases as graph interfaces. - Class/interface EXTENDS and class IMPLEMENTS relationships, including relative imports and tsconfig.json path aliases, including those inherited from extended configs, that resolve under --source. - Interface and object-literal type members as :Field/:Method declarations. - TypeScript enums as graph classes with isEnum = true and kind = "enum", with enum members as :Field declarations using kind = "enum-member". - Top-level functions and variables under the module owner. - Exported callable aliases and class re-export aliases as graph-visible declarations for their public export names. - Methods, constructors, function-valued class fields, fields, abstract class metadata, bodyless abstract/optional method signatures, static flags, line ranges, and kinds. - Decorators as annotations, preserving namespace-qualified decorator FQNs when possible. - Angular decorators with framework metadata when detected. - Syntax-based best-effort call edges, including top-level IIFEs/callbacks, local function constructors, and deferred resolution for resolvable relative imports. - Relative import and tsconfig.json path-alias resolution, including extended configs, prefers TypeScript source files over emitted JavaScript when both exist for the same local module path.

Runtime modes:

Custom cache:

<ingester> \
  --source . \
  --bolt bolt://localhost:7687 \
  --project my-js-project \
  --language js \
  --js-runtime-cache /path/to/cache \
  --wipe-project-code

Custom pinned versions:

<ingester> \
  --source . \
  --bolt bolt://localhost:7687 \
  --project my-js-project \
  --language js \
  --js-node-version 22.11.0 \
  --js-typescript-version 5.6.3 \
  --wipe-project-code

JS/TS caveat: JavaScript is dynamic. Dynamic dispatch, dependency injection, monkey-patching, framework templates, and generated code can produce missing call edges. A missing JS/TS CALLS edge does not prove a call never happens.

CLI Reference

Exit codes:

Options:

Parallel ingestion:

Use 4 to 8 threads for large projects on most machines. Values higher than your CPU core count rarely help.