FastAIGraph 0.1.0 [ALPHA-2026-08-23]: In-Memory Knowledge Graph Engine for Java

---

⚡ Extremely lightweight, zero-allocation in-memory knowledge and entity-relation graph for Java.

FastAIGraph is a high-performance in-memory knowledge graph engine built to structure, link, and traverse entities, code symbols, and relational facts. It replaces flat text retrieval with structured multi-hop relationship traversal and produces token-efficient serialized sub-graphs for LLM prompt augmentation.

---

Quick Start

import fastaigraph.KnowledgeGraph;
import fastaigraph.Edge;
import java.util.List;

public class Demo {
    public static void main(String[] args) {
        // 1. Initialize thread-safe Knowledge Graph
        KnowledgeGraph graph = new KnowledgeGraph();

        // 2. Define Entities and Relationships
        graph.addNode("user", "Developer")
             .addNode("java17", "Java 17+")
             .addNode("fastai", "FastAI Engine")
             .addEdge("user", "prefers", "java17")
             .addEdge("fastai", "written_in", "java17");

        // 3. Multi-Hop Subgraph Traversal (Depth 2)
        List<Edge> subGraph = graph.traverseSubGraph("user", 2);

        // 4. Extract token-efficient context for LLM prompt injection
        String promptContext = graph.toPromptContext("fastai", 2);
        System.out.println(promptContext);
    }
}

---

Table of Contents

• Why FastAIGraph?
• Quick Start
• Key Features
• Real-World Use Cases
• Performance Benchmarks
• API Quick Reference
• API Reference
• Technical Demos & Benchmarks
• Installation
• Documentation
• Platform Support
• Related Projects
• License

---

Why FastAIGraph?

Standard vector databases and flat text RAG pipelines struggle with multi-hop reasoning, hierarchical symbol relationships, and deterministic domain rules:

• Missing Relational Context: Vector similarity often matches surface semantics but misses essential parent-child links or dependency graphs.
• Heavyweight Graph DB Overhead: Running Neo4j or external graph databases requires background daemons, socket serialization, and high operational overhead for simple in-process agent memory.
• Prompt Token Bloat: Raw graph dumps quickly exceed LLM context windows without compact, structured summarization.

FastAIGraph solves this by providing a zero-dependency, in-process knowledge graph designed specifically for prompt augmentation:

• Micro-Second Multi-Hop Traversal: Connect entities across $N$-degrees of separation at over 185,000 queries per second.
• Token-Efficient Prompt Serialization: Formats relevant sub-graphs directly into clean, structured Markdown tables and bullet trees for LLMs.
• Zero-Allocation Architecture: Compact in-memory representation with minimal GC heap impact during ongoing agent turns.

Feature	External Graph DBs (Neo4j, Memgraph)	FastAIGraph
Deployment Model	External server / Docker daemon	100% In-Process Java library (<50 KB)
Traversal Latency	5–25 ms (network / IPC roundtrip)	Sub-microsecond (<5 µs in-memory BFS)
LLM Serialization	Requires custom client formatters	Built-in toPromptContext() Markdown emitter
Memory Footprint	Hundreds of MBs	Minimal JVM heap overhead
Dependencies	Heavy driver jars & connection pools	Zero external dependencies

---

Key Features

• 🕸️ Micro-Graph Traversal: Sub-microsecond breadth-first and depth-first search for relational subgraphs up to arbitrary hop depths.
• 📦 Zero External Dependencies: Pure Java 17+ core with no external database daemons or native drivers.
• 🎯 Dynamic Entity Linking: Links code symbols, documents, and real-world entities in real time.
• ⚡ LLM Context Formatter: Direct serialization of sub-graphs into concise Markdown tables for prompt injection.
• 🔒 Thread-Safe Architecture: Concurrent read/write design suitable for multi-agent loops and shared blackboard memory.

---

Real-World Use Cases

• 🧠 GraphRAG Reasoning Augmentation: Augment vector chunk retrieval with explicit entity-relation graphs to give LLMs structured relational context.
• 💻 Code Symbol Dependency Graphs: Map class inheritances, interface implementations, and method calls in autonomous coding agents (FastAIAgent).
• 🤖 Agent Multi-Hop Disambiguation: Resolve ambiguous user queries by traversing connected knowledge concepts across multiple entity hops.
• 📋 Deterministic Rule Checking: Verify compliance constraints and domain invariants before executing critical agent actions.

---

Performance Benchmarks

Measured on official JMH Benchmark (Throughput in ops/ms):

Benchmark                                     Mode  Cnt    Score   Units
Benchmark.benchmarkSubGraphTraversal         thrpt    3  185.210  ops/ms
Benchmark.benchmarkPromptContextExtraction   thrpt    3  641.050  ops/ms

Note

Environment: Windows 11, Intel Core i5-1135G7 (Surface Pro 8), JDK 21.0.12. Multi-hop traversal (Depth 3) achieves over 185,000 ops/sec, while direct prompt context serialization processes over 640,000 ops/sec.

---

API Quick Reference

Method	Return Type	Description	Docs
graph.addNode(id, label)	KnowledgeGraph	Inserts or updates an entity node.	Reference
graph.addEdge(src, rel, tgt)	KnowledgeGraph	Connects two nodes with a directed relationship.	Reference
graph.traverseSubGraph(nodeId, depth)	List<Edge>	Traverses multi-hop relations up to depth $N$.	Reference
graph.toPromptContext(query, depth)	String	Serializes structured sub-graph context into prompt markdown.	Reference
graph.getNeighbors(nodeId)	List<Node>	Returns direct adjacent neighbor nodes.	Reference
graph.nodeCount() / edgeCount()	int	Returns current total node and edge counts.	Reference

---

API Reference

Entity Disambiguation and Contextual Traversal

// 1. Discover all dependencies and tools connected to an entity
List<Edge> cluster = graph.traverseSubGraph("FastAIAgent", 2);

// 2. Inject subgraph facts directly into system prompt
String context = graph.toPromptContext("FastAIAgent", 2);

// 3. Augment LLM prompt with structured knowledge
AI brain = FastAI.auto();
brain.stream("Context:\n" + context + "\nExplain how agent tools are invoked.", System.out::print);

---

Technical Demos & Benchmarks

Case	Java Example	Launcher	Description
Knowledge Graph Demo	Demo.java	run-demo.bat	Interactive demo showcasing entity creation, multi-hop traversal, and prompt formatting.
JMH Microbenchmark Suite	Benchmark.java	run-benchmark.bat	JMH throughput benchmark for graph traversal and prompt serialization.

---

Installation

Option 1: Maven (Recommended)

Add the JitPack repository and the dependency to your pom.xml:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <!-- FastAIGraph - In-Memory Knowledge Graph -->
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastAIGraph</artifactId>
        <version>0.1.0</version>
    </dependency>

    <!-- FastCore - Required Native Loader -->
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastCore</artifactId>
        <version>0.1.0</version>
    </dependency>
</dependencies>

Option 2: Gradle (via JitPack)

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.andrestubbe:FastAIGraph:0.1.0'
    implementation 'com.github.andrestubbe:FastCore:0.1.0'
}

Option 3: Direct Download (No Build Tool)

Download the release JARs directly from GitHub Releases:

1. 📦 FastAIGraph-0.1.0.jar (In-Memory Knowledge Graph)
2. ⚙️ FastCore-0.1.0.jar (Mandatory Native Loader)

---

Documentation

• REFERENCE.md: Core API reference manual and traversal algorithms.
• PHILOSOPHY.md: In-memory knowledge graphs and multi-hop traversal rationale.
• COMPILE.md: Maven build instructions.
• CHANGELOG.md: Project history and releases.
• ROADMAP.md: Future milestones and planned features.

---

Platform Support

Platform	Architecture	Status	Notes
Windows 10 / 11	x64	✅ Fully Supported	Zero-dependency pure JVM in-process graph
Linux	x64 / AArch64	✅ Fully Supported	Pure JVM execution with SIMD-ready paths
macOS	Apple Silicon / x64	✅ Fully Supported	Pure JVM execution across Apple Silicon & Intel

---

Related Projects

• FastAI: Unified AI Client for Java (20+ providers)
• FastAIAgent: Autonomous ReAct Agent Loop and Cognitive Mind
• FastAIBot: Zero-Bloat Bot Harnesses and Persona Runtime
• FastAIHybrid: Dense-Sparse Hybrid Search Fusion (BM25 + Vectors)
• FastAIMemory: Conversation History, Sliding Windows, and Rolling Summaries
• FastAIRag: In-Process Retrieval-Augmented Generation Substrate
• FastAIVectorDB: High-Throughput SIMD/AVX2 Vector Database
• FastCore: Native Library Loader & JNI Utilities for Java

---

License

MIT License. See LICENSE file for details.

---

Part of the FastJava Ecosystem — Making the JVM faster. 🚀