GraphRaptor

A reference implementation of a graph-backed memory and reasoning service: documents are ingested into a hierarchical Neo4j graph, and reasoning tasks retrieve over that graph instead of a flat vector index. Built to explore how agent memory behaves when it's structured, multi-tenant, and self-correcting.

Status: proof of concept / reference architecture. The focus here is the system design — the distributed pipeline, multi-tenancy, and graph memory model — not a production-ready product. By default the worker runs a deterministic Mock LLM so the full pipeline runs with no API key; set ENVIRONMENT=production with an OPENAI_API_KEY to use real models. Several connectors (e.g. SharePoint) are mocked, and parts of the reasoning loop are intentionally simplified.

What this demonstrates

Area	Approach
Hybrid architecture	Node.js/Fastify for high-concurrency orchestration + Python/DSPy worker for reasoning, decoupled via RabbitMQ with dead-letter exchanges
Multi-tenancy as a security boundary	Every graph query is filtered by namespace (and allowedGroups); tenant scoping is threaded through every layer, not bolted on
Structured error handling	A 3-bucket taxonomy (retryable → requeue, fatal → dead-letter, agent-give-up → mark failed) maps failure modes to queue behavior
Hierarchical memory	RAPTOR-style recursive summarization builds an abstract-to-raw tree; retrieval walks it instead of scanning flat chunks
Self-correction	Negative user feedback traces back through the graph to blame and regenerate the summaries that produced a bad answer

Concept glossary (names used throughout the code and docs):

• Fractal Memory — the recursive Document → summary → chunk graph structure (RAPTOR summarization).
• G-Memory — a store of past reasoning trajectories and extracted insights, reused on similar future queries.
• MemWalker — tree navigation over the memory graph using beam search with LLM-guided step decisions.

System Architecture

The system uses a Connected Brain architecture where a lightweight Node.js API acts as the nervous system (routing) and a Python Neural Worker handles the heavy cognitive lifting (Reasoning, Ingestion, Knowledge Retrieval).

graph LR
    Client[Client] -->|POST /ingest| Spine[Spine API]
    Spine -->|Metadata| Postgres[(PostgreSQL)]
    Spine -->|Task| RabbitMQ[RabbitMQ]

    subgraph Worker Service
        Worker[Python Worker]
        Worker -->|Consume| RabbitMQ
    end

    Worker -->|Store Graph| Neo4j[(Neo4j)]
    Worker -->|Update Status| Postgres

Loading

Getting Started

Prerequisites

• Docker & Docker Compose
• Node.js 20+ (for local dev)
• Python 3.11+ (for local dev)

Setup & Run

1. Clone the repository

   git clone <repo-url>
   cd graphraptor

2. Start Services

   docker-compose up -d --build

   This will start Neo4j, PostgreSQL, RabbitMQ, Spine, and the Worker.

3. Verify Services

   • Spine API: http://localhost:3000
   • Neo4j Browser: http://localhost:7474 ⚠️ First-time setup required
   • RabbitMQ UI: http://localhost:15672 (User/Pass: guest/guest)

Authentication

All API endpoints are protected by API key authentication in production.

Setup

1. Generate a secret key:

   openssl rand -hex 32

2. Add to spine/.env:

   API_KEY=your_generated_key_here
   

3. Include in all requests:

   x-api-key: your_generated_key_here
   

Dev Mode: If API_KEY is not set, authentication is disabled — but only when NODE_ENV is not production. In production the server refuses to start without an API_KEY (fails closed).

Configuration

Embedding Dimensions

Both services must use matching embedding dimensions (default: 1536 for text-embedding-3-small):

Service	Variable	Default
Spine	EMBEDDING_DIMENSIONS	1536
Worker	EMBEDDING_DIMENSIONS	1536

Warning: Changing dimensions requires recreating Neo4j vector indexes.

Usage

1. Ingest a Document

Upload a text file to be processed into the Graph.

curl -X POST http://localhost:3000/ingest \
  -H "x-api-key: $API_KEY" \
  -F "file=@your-document.txt" \
  -F "namespace=test-app" \
  -F "userGroups=admin"

2. Verify Processing

Check the Worker logs:

docker logs graphraptor-worker-1 --tail 50

Query Neo4j to see the results:

MATCH (d:Document)-[:HAS_CHUNK]->(c:Chunk) RETURN d, c LIMIT 25

Project Structure

• spine/: Node.js API Service (Fastify)
• worker/: Python Worker Service (FastStream + DSPy)
• docs/: Architecture documentation
• docker-compose.yml: Service orchestration

Documentation

Document	Description
Architecture	Executive specification of the Graph Cognitive Architecture
Fractal Memory	Deep dive into RAPTOR, MemWalker, and G-Memory internals
Neo4j Setup	Neo4j authentication and troubleshooting guide
Ingestion Flow	Claim Check pattern for document processing
Retrieval Architecture	Parallel Scatter-Gather pattern and MemWalker logic
Dreamer Initiative	Proactive Generative Simulation (Synthetic Memory)