AutoGineer
Generated banner for Create Context Graph
Generated logo for Create Context Graph

Create Context Graph

Memory frameworkOfficial neo4j-labs project

Created by neo4j-labs

Published in neo4j-labs/create-context-graph. Publisher page

747 GitHub stars

What it is

AI agents with graph based reasoning memory, scaffolded in seconds
— the description by neo4j-labs

AutoGineer overview, from the brain’s own files

Create Context Graph is an interactive scaffolding tool designed to accelerate the development of AI agents that utilize graph-based memory. By walking developers through a wizard, it generates a complete, domain-specific application stack including a FastAPI backend, a Next.js frontend with interactive graph visualization, and a configured AI agent. The tool supports multiple agent frameworks and offers a choice between a hosted memory backend (NAMS) or a self-hosted Neo4j instance. It includes built-in support for importing data from various SaaS platforms, generating domain-specific ontologies, and creating MCP servers for integration with Claude Desktop.

How it works

Memory model: Hybrid

AutoGineer overview, from the brain’s own files

The tool operates as a CLI that uses Jinja2 templates to generate project code based on a selected industry domain and agent framework. It creates a FastAPI backend for agent logic and a Next.js frontend for visualization. Memory is managed either via the hosted NAMS service or a self-hosted Neo4j database. The system supports data ingestion from various connectors and can generate domain-specific ontologies, schemas, and agent tools automatically.

Folders
FolderRoleFiles
.githubagent-config2
docsdocs105
scriptsscripts2
srcsource-code168
teststests48
.serenafolder1
npm-wrapperfolder3

The agent reads

The agent writes

Requirements

Runtimes: Python >=3.11

Databases: Neo4j

API keys (by name): ANTHROPIC_API_KEY, GOOGLE_API_KEY, LINEAR_API_KEY, MEMORY_API_KEY, OPENAI_API_KEY

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Google Antigravity, Kiro, OpenCode, Amp, Roo Code, Cline, JetBrains Junie, Devin (ex-Windsurf)

Set it up

  1. This brain runs code automatically: 1 script. Review Makefile before opening the folder in Claude Code. No step below turns a hook on for you.

    • Makefile: uv venv && uv pip install -e ".[dev]"
  2. Not scanned by AutoGineerIts dependencies are installed by pip or uv when you run it and were not scanned by AutoGineer (7 declared). https://pypi.org/project/create-context-graph/

  3. Created by neo4j-labs. Published in neo4j-labs/create-context-graph. Licence: Apache License 2.0.

Usage

AutoGineer overview, from the brain’s own files

  • Scaffold a new project using the interactive CLI wizard.
  • Generate a project with a specific domain and agent framework via CLI flags.
  • Connect SaaS data sources like GitHub, Slack, or Notion to populate the graph.
  • Configure the memory backend for either hosted NAMS or self-hosted Neo4j.
  • Generate an MCP server configuration for Claude Desktop integration.
  • Re-import data or seed the graph using generated make commands.
“uvx create-context-graph my-app --domain healthcare --framework strands --nams-api-key sk-nams-...”
Generates a healthcare-focused agent application using the Strands framework and hosted NAMS memory.
“uvx create-context-graph my-app --domain personal-knowledge --framework pydanticai --self-hosted --connector github”
Generates a personal knowledge application with self-hosted Neo4j, pre-populated with GitHub data.

Documentation by neo4j-labs

Create Context Graph

This is an experimental Neo4j Labs project and not part of Neo4j's supported product lineup. See the Neo4j Labs disclaimer.

Image: Neo4j Labs Image: Docs

Neo4j Labs Project — This project is part of Neo4j Labs. It is maintained by Neo4j staff and the community, but not officially supported. For help, use GitHub Issues or the Neo4j Community Forum.

Interactive CLI scaffolding tool that generates fully-functional, domain-specific context graph applications. Pick your industry domain, pick your agent framework, and get a complete full-stack app in under 5 minutes.

<p align="center"> <img src="docs/static/img/app-three-panel.png" alt="Generated app: chat interface, graph visualization, and document browser" width="800" /> </p>

# Python — NAMS-default (hosted memory)
uvx create-context-graph my-app --domain healthcare --framework strands --nams-api-key sk-nams-...

# Self-hosted Neo4j with full demo fixtures
uvx create-context-graph my-app --domain healthcare --framework pydanticai --self-hosted --demo

# Node.js / interactive wizard
npx create-context-graph

What It Does

Create Context Graph walks you through an interactive wizard and generates a complete project:

  • FastAPI backend with an AI agent configured for your domain, powered by neo4j-agent-memory v0.4 for multi-turn conversations with automatic entity extraction. Memory backend is configurable: hosted NAMS (default) or self-hosted bolt Neo4j (--self-hosted).

  • LiteLLM provider injection for the memory layer — pick any LLM + embedding provider via MEMORY_LLM / MEMORY_EMBEDDING env vars (Anthropic, OpenAI, Bedrock, Vertex AI, Ollama, Groq, Together, …). Native adapters resolve first; everything else routes through LiteLLM.

  • Next.js + Chakra UI v3 frontend with streaming chat (Server-Sent Events), real-time tool call visualization (Timeline with live spinners), interactive graph visualization (schema view, double-click expand, drag/zoom, property panel), entity detail panel, document browser, and decision trace viewer

  • Neo4j schema with domain-specific constraints, indexes, and GDS projections (self-hosted mode)

  • Rich demo data — LLM-generated entities, relationships, professional documents (discharge summaries, trade confirmations, lab reports), and multi-step decision traces

  • SaaS data import — connect GitHub, Slack, Gmail, Jira, Notion, Google Calendar, Salesforce, Linear, Google Workspace, Claude Code, Claude AI, ChatGPT, or local files

  • Custom domains — describe your domain in plain English and the LLM generates a complete ontology

  • Domain-specific agent tools with Cypher queries tailored to your industry

  • MCP server for Claude Desktop — optionally generates an MCP server config so Claude Desktop can query the same knowledge graph (--with-mcp)

  Creating context graph application...

  Domain:     Wildlife Management
  Framework:  PydanticAI
  Data:       Demo (synthetic)
  Neo4j:      Docker (neo4j://localhost:7687)

  [1/6] Generating domain ontology...          ✓
  [2/6] Creating project scaffold...           ✓
  [3/6] Configuring agent tools & system prompt...  ✓
  [4/6] Generating synthetic documents (25 docs)... ✓
  [5/6] Writing fixture data...                ✓
  [6/6] Bundling project...                    ✓

  Done! Your context graph app is ready.

  cd my-app
  make install && make start

Quick Start

There are two flows depending on what you want:

  • NAMS (default) — hosted memory backend. No Neo4j to install or operate. Graph starts empty; the agent populates it as you chat.

  • Self-hosted (--self-hosted) — bolt Neo4j you run yourself (Aura, Docker, neo4j-local). Full demo fixtures available via make seed.

Prerequisites

  • Python 3.11+ (with uv recommended)

  • Node.js 18+ (for the frontend)

  • NAMS path: a NAMS API key from memory.neo4jlabs.com

  • Self-hosted path: Neo4j 5+ (Docker, Aura, or local install)

  • Either path: ANTHROPIC_API_KEY for the agent (or OPENAI_API_KEY/GOOGLE_API_KEY depending on framework)

NAMS path (default, hosted memory)
uvx create-context-graph my-app \
  --domain healthcare \
  --framework strands \
  --nams-api-key sk-nams-...

cd my-app
echo 'ANTHROPIC_API_KEY=sk-ant-...' >> .env   # Strands needs Anthropic
make install
make start

Open http://localhost:3000. Graph starts empty — chat with the agent and entities populate via auto-extraction.

Self-hosted path (bolt Neo4j + full demo data)
uvx create-context-graph my-app \
  --domain healthcare \
  --framework pydanticai \
  --self-hosted \
  --demo

cd my-app
echo 'ANTHROPIC_API_KEY=sk-ant-...' >> .env
make install
make docker-up   # or: make neo4j-start  (for neo4j-local)
make seed
make start

Open http://localhost:3000. Pre-populated graph with ~85 entities, 180 relationships, 25 documents, and decision traces.

Other scaffold patterns
# Interactive wizard (asks 6 prompts, autocomplete domain picker)
uvx create-context-graph

# Custom domain from description
uvx create-context-graph my-app \
  --custom-domain "veterinary clinic management" \
  --framework pydanticai \
  --self-hosted --demo \
  --anthropic-api-key $ANTHROPIC_API_KEY

# Import real data from SaaS services
uvx create-context-graph my-app \
  --domain personal-knowledge --framework pydanticai --self-hosted \
  --connector github --connector slack

# With MCP server for Claude Desktop (works on either backend)
uvx create-context-graph my-app \
  --domain healthcare --framework strands \
  --nams-api-key sk-nams-... --with-mcp

# Pick a specific LiteLLM provider for memory entity extraction
uvx create-context-graph my-app \
  --domain healthcare --framework strands --nams-api-key sk-nams-... \
  --memory-llm bedrock/anthropic.claude-3-haiku-20240307-v1:0 \
  --memory-embedding sentence-transformers/all-MiniLM-L6-v2
Explore the running app
NAMS write-path caveats (v0.4)

The NAMS REST API has a narrower write surface than bolt Cypher. The CLI and the generated import_data.py work around it with a hybrid write shape:

  • Relationships encoded as ccg-edges YAML blocks inside each source entity's description. The frontend graph view parses them out and renders edges; a future migration replays them as native edges when NAMS adds add_relationship.

  • Entity properties collapse into description as a markdown block (NAMS REST accepts only name/type/description).

  • Documents are dual-tracked — long_term.add_entity(type=OBJECT) (queryable, matches bolt :Document) AND short_term.add_message(role="document") (extraction fuel).

  • No preferences or facts via REST. auto_preferences forced off on NAMS.

  • GDS endpoints and arbitrary Cypher writes return 501 on NAMS.

For native graph edges + GDS + arbitrary Cypher, use --self-hosted --demo.

Supported Domains

27 industry domains, each with a purpose-built ontology, sample data, agent tools, and demo scenarios:

DomainKey EntitiesDomainKey Entities
Financial ServicesAccount, Transaction, Decision, PolicyReal EstateProperty, Listing, Agent, Inspection
HealthcarePatient, Provider, Diagnosis, TreatmentVacation & HospitalityResort, Booking, Guest, Activity
Retail & E-CommerceCustomer, Product, Order, ReviewOil & GasWell, Reservoir, Equipment, Permit
ManufacturingMachine, Part, WorkOrder, SupplierData JournalismSource, Story, Claim, Investigation
Scientific ResearchResearcher, Paper, Dataset, GrantTrip PlanningDestination, Hotel, Activity, Itinerary
GenAI / LLM OpsModel, Experiment, Prompt, EvaluationGIS & CartographyFeature, Layer, Survey, Boundary
Agent MemoryAgent, Conversation, Memory, ToolCallWildlife ManagementSpecies, Sighting, Habitat, Camera
GamingPlayer, Character, Quest, GuildConservationSite, Species, Program, Funding
Personal KnowledgeNote, Contact, Project, TopicGolf & Sports MgmtCourse, Player, Round, Tournament
Digital TwinAsset, Sensor, Reading, AlertSoftware EngineeringRepository, Issue, PR, Deployment
Product ManagementFeature, Epic, UserPersona, MetricHospitalityHotel, Room, Reservation, Service
Options IntelligenceUnderlying, OptionsContract, Regime, KeyLevelLegalCase, Matter, Contract, Filing
EducationStudent, Instructor, Course, AssessmentCybersecurityAsset, Vulnerability, Alert, Incident
GovernmentAgency, Program, Policy, Regulation
# List all available domains
create-context-graph --list-domains

Custom domains: Don't see your industry? Select "Custom (describe your domain)" in the wizard or use --custom-domain "your description". The LLM generates a complete ontology with entity types, relationships, agent tools, and more.

SaaS Data Connectors

<p align="center"> <img src="docs/static/img/connector-data-flow.png" alt="SaaS connector data flow into Neo4j knowledge graph" width="700" /> </p>

Import real data from your existing tools instead of (or in addition to) synthetic demo data:

ServiceWhat's ImportedAuth
GitHubIssues, PRs, commits, contributorsPersonal access token
NotionPages, databases, usersIntegration token
JiraIssues, sprints, usersAPI token
SlackChannel messages, threads, usersBot OAuth token
GmailEmails (last 30 days)Google Workspace CLI or OAuth2
Google CalendarEvents, attendees (last 90 days)Google Workspace CLI or OAuth2
SalesforceAccounts, contacts, opportunitiesUsername/password
LinearIssues, projects, cycles, teams, users, labels, comments, milestones, initiatives, attachments + decision traces from historyPersonal API key
Google WorkspaceDrive files, comment threads (as decision traces), revisions, Drive Activity, Calendar events, Gmail metadataGoogle OAuth 2.0
Claude CodeSession history, messages, tool calls, files, decisions, preferences, errorsNone (local files)
Claude AIConversations, messages, tool calls, thinking traces from Claude AI web/app exportNone (local file)
ChatGPTConversations, messages, tool results from ChatGPT data exportNone (local file)

The Google Workspace connector extracts resolved comment threads from Google Docs as first-class decision traces — capturing the question, deliberation, resolution, and participants. Combined with Linear, it provides the full decision lifecycle: from meeting discussion to code execution.

The Claude Code connector reads your local session history from ~/.claude/projects/ — no API keys needed. It extracts decision traces from user corrections and error-resolution cycles, identifies developer preferences from explicit statements and behavioral patterns, and automatically redacts secrets before storage.

The Claude AI and ChatGPT connectors import your conversation exports directly from the official data export features. Export your data from Settings, pass the .zip file to the CLI with --import-type claude-ai or --import-type chatgpt, and get a fully populated context graph from your real conversations — no API keys needed.

Connectors run at scaffold time to populate initial data. They're also generated into your project so you can re-import with make import:

cd my-app
make import            # Re-import from connected services
make import-and-seed   # Import and seed into Neo4j

Agent Frameworks

Select your preferred agent framework at project creation time:

FrameworkDescription
PydanticAIStructured tool definitions with Pydantic models and RunContext
Claude Agent SDKAnthropic tool-use with agentic loop
OpenAI Agents SDK@function_tool decorators with Runner.run()
LangGraphStateful graph-based agent workflow with create_react_agent()
CrewAIMulti-agent crew with role-based tools
StrandsTool-use agents with Anthropic model
Google ADKGemini agents with FunctionTool calling
Anthropic ToolsModular tool registry with Anthropic API agentic loop

All frameworks share the same FastAPI HTTP layer, Neo4j client, and frontend. Only the agent implementation differs. "Full streaming" means token-by-token text + real-time tool calls. "Tool streaming" means real-time tool calls with text delivered at the end.

Note on memory providers: Conversation memory uses local sentence-transformers/all-MiniLM-L6-v2 embeddings by default — no API key required. Override with MEMORY_EMBEDDING (LiteLLM provider string) for OpenAI, Vertex AI, Bedrock, or others. The entity-extraction LLM defaults to anthropic/claude-haiku-4-5 when ANTHROPIC_API_KEY is set, or openai/gpt-4o-mini if only OPENAI_API_KEY is set. Override with MEMORY_LLM for full control. See Configure Memory Providers.

Generated Project Structure

<p align="center"> <img src="docs/static/img/ontology-pipeline.png" alt="From domain YAML through Jinja2 templates to generated code" width="750" /> </p>

A single domain YAML drives the entire generated application — schema, models, agent tools, and visualization — through the Jinja2 template engine.

my-app/
├── backend/
│   ├── app/
│   │   ├── main.py                # FastAPI application
│   │   ├── agent.py               # AI agent (framework-specific)
│   │   ├── config.py              # Settings from .env
│   │   ├── routes.py              # REST API endpoints
│   │   ├── models.py              # Pydantic models (from ontology)
│   │   ├── context_graph_client.py # Neo4j CRUD operations
│   │   ├── memory.py              # Memory integration (MemoryIntegration)
│   │   ├── gds_client.py          # Graph Data Science algorithms
│   │   ├── vector_client.py       # Vector search
│   │   └── connectors/            # SaaS connectors (if selected)
│   ├── scripts/
│   │   ├── generate_data.py       # Data seeding script
│   │   └── import_data.py         # SaaS import script (if connectors selected)
│   └── pyproject.toml
├── frontend/
│   ├── app/                       # Next.js pages
│   ├── components/
│   │   ├── ChatInterface.tsx      # Streaming AI chat (SSE) with real-time tool calls + graph data flow
│   │   ├── ContextGraphView.tsx   # Interactive NVL graph (schema view, expand, drag/zoom, properties)
│   │   ├── DecisionTracePanel.tsx  # Reasoning trace viewer with step details
│   │   ├── DocumentBrowser.tsx    # Document browser with template filtering
│   │   └── Provider.tsx           # Chakra UI v3 provider
│   ├── lib/config.ts              # Domain configuration
│   ├── theme/index.ts             # Chakra theme with domain colors
│   └── package.json
├── cypher/
│   ├── schema.cypher              # Constraints & indexes
│   └── gds_projections.cypher     # GDS algorithm config
├── data/
│   ├── ontology.yaml              # Domain ontology definition
│   └── fixtures.json              # Pre-generated sample data
├── .env                           # Neo4j + API key configuration
├── .env.example                   # Configuration template (tracked in git)
├── .dockerignore                  # Docker build context exclusions
├── docker-compose.yml             # Local Neo4j instance (Docker mode only)
├── Makefile                       # start, seed, reset, install, test, test-connection, lint
├── mcp/                           # MCP server config (only if --with-mcp)
└── README.md                      # Domain-specific documentation (with framework docs + troubleshooting)

CLI Reference

create-context-graph [PROJECT_NAME] [OPTIONS]

Arguments:
  PROJECT_NAME              Project name (optional — auto-generated from domain+framework if omitted)

Options:
  --domain TEXT             Domain ID (e.g., healthcare, gaming)
  --framework TEXT          Agent framework (strands [default], pydanticai, claude-agent-sdk, openai-agents, langgraph, crewai, google-adk, anthropic-tools)
  --self-hosted             Use self-hosted Neo4j (bolt) instead of NAMS hosted memory
  --nams-api-key TEXT       NAMS API key [env: MEMORY_API_KEY] — obtain at https://memory.neo4jlabs.com
  --nams-endpoint TEXT      Override NAMS endpoint URL (default: https://memory.neo4jlabs.com/v1)
  --memory-llm TEXT         LiteLLM provider string for memory entity extraction (e.g. anthropic/claude-haiku-4-5)
  --memory-embedding TEXT   LiteLLM provider string for memory embeddings (e.g. sentence-transformers/all-MiniLM-L6-v2)
  --demo-data               Generate synthetic demo data
  --custom-domain TEXT      Generate custom domain from description (requires --anthropic-api-key)
  --connector TEXT          SaaS connector to enable; repeatable (github, slack, jira, notion, gmail, gcal, salesforce, linear, google-workspace, claude-code, claude-ai, chatgpt)
  --import-type TEXT        Chat history import: claude-ai or chatgpt (requires --import-file)
  --import-file PATH        Path to chat export file (.zip, .json, .jsonl)
  --import-depth TEXT       Import extraction depth: fast (default) or deep
  --import-filter-after TEXT Only import conversations after this date (ISO 8601)
  --import-filter-before TEXT Only import conversations before this date (ISO 8601)
  --import-filter-title TEXT Only import conversations matching title pattern (regex)
  --import-max-conversations INT Max conversations to import, 0=all (default: 0)
  --linear-api-key TEXT    Linear API key (required for --connector linear) [env: LINEAR_API_KEY]
  --linear-team TEXT       Linear team key to filter import (e.g., ENG) [env: LINEAR_TEAM]
  --gws-folder-id TEXT     Google Drive folder ID to scope import [env: GWS_FOLDER_ID]
  --gws-include-comments / --gws-no-comments  Import comment threads (default: on)
  --gws-include-revisions / --gws-no-revisions  Import revision history (default: on)
  --gws-include-activity / --gws-no-activity  Import Drive Activity (default: on)
  --gws-include-calendar   Import Calendar events (default: off)
  --gws-include-gmail      Import Gmail thread metadata (default: off)
  --gws-since TEXT         Import data since date (ISO format, default: 90 days ago)
  --gws-mime-types TEXT    MIME types to include (default: docs,sheets,slides)
  --gws-max-files INT      Maximum files to import (default: 500)
  --claude-code-scope TEXT Import current project or all (default: current)
  --claude-code-project TEXT Explicit project path to import sessions for
  --claude-code-since TEXT Import sessions since date (ISO format)
  --claude-code-max-sessions INT Max sessions to import, 0=all (default: 0)
  --claude-code-content TEXT Content mode: truncated, full, none (default: truncated)
  --with-mcp                Generate MCP server configuration for Claude Desktop
  --mcp-profile TEXT        MCP tool profile: core (6 tools) or extended (16 tools, default)
  --session-strategy TEXT   Memory session strategy: per_conversation (default), per_day, persistent
  --auto-extract/--no-auto-extract  Auto-extract entities from messages (default: on)
  --auto-preferences/--no-auto-preferences  Auto-detect user preferences (default: on)
  --ingest                  Ingest data into Neo4j after generation
  --neo4j-uri TEXT          Neo4j connection URI [env: NEO4J_URI] (--self-hosted only)
  --neo4j-username TEXT     Neo4j username [env: NEO4J_USERNAME] (--self-hosted only)
  --neo4j-password TEXT     Neo4j password [env: NEO4J_PASSWORD] (--self-hosted only)
  --neo4j-aura-env PATH    Path to Neo4j Aura .env file with credentials (--self-hosted only)
  --neo4j-local             Use @johnymontana/neo4j-local for local Neo4j (--self-hosted only)
  --anthropic-api-key TEXT  Anthropic API key for LLM generation [env: ANTHROPIC_API_KEY]
  --openai-api-key TEXT    OpenAI API key for LLM generation [env: OPENAI_API_KEY]
  --google-api-key TEXT    Google/Gemini API key (required for google-adk) [env: GOOGLE_API_KEY]
  --output-dir PATH         Output directory (default: ./<project-name>)
  --demo                    Shortcut for --reset-database --demo-data --ingest
  --reset-database          Clear all Neo4j data before ingesting
  --dry-run                 Preview what would be generated without creating files
  --verbose                 Enable verbose debug output
  --list-domains            List available domains and exit
  --version                 Show version and exit
  --help                    Show help and exit

Context Graph Architecture

<p align="center"> <img src="docs/static/img/architecture-overview.png" alt="Architecture: generation pipeline and runtime components" width="800" /> </p>

Every generated app demonstrates the three-memory-type architecture from neo4j-agent-memory:

<p align="center"> <img src="docs/static/img/memory-architecture.png" alt="Three memory types: short-term, long-term, and reasoning memory in Neo4j" width="700" /> </p>

  • Short-term memory — Conversation history and document content stored as messages

  • Long-term memory — Entity knowledge graph built on the POLE+O model (Person, Organization, Location, Event, Object)

  • Reasoning memory — Decision traces with full provenance: thought chains, tool calls, causal relationships

This is what makes context graphs different from simple RAG — the agent doesn't just retrieve text, it reasons over a structured knowledge graph with full decision traceability.

With --with-mcp, the generated project also includes an MCP server configuration that connects Claude Desktop to the same knowledge graph. This dual-interface architecture means the web app and Claude Desktop share one context graph — entities, conversations, and reasoning traces are available everywhere.

Development

# Clone and install
git clone https://github.com/neo4j-labs/create-context-graph.git
cd create-context-graph
uv venv && uv pip install -e ".[dev]"

# Run tests (no Neo4j or API keys required)
source .venv/bin/activate
pytest tests/ -v               # Fast: 1,177 tests
pytest tests/ -v --slow        # Full: 1,398 tests (includes domain x framework matrix + perf + generated project tests)
pytest tests/ --integration    # Integration tests (requires running Neo4j)

# Test a specific scaffold
create-context-graph /tmp/test-app --domain software-engineering --framework pydanticai --demo-data
Makefile Targets
TargetDescriptionRequirements
make testRun fast unit tests (1,177 tests)None
make test-slowFull suite including matrix + perf + generated project tests (1,398 tests)None
make test-matrixDomain × framework matrix only (176 combos)None
make test-coverageTests with HTML coverage reportNone
make smoke-testE2E smoke tests for 3 key frameworksNeo4j + LLM API keys
make lintRun ruff linterruff
make scaffoldScaffold a test project to /tmp/test-scaffoldNone
make buildBuild Python package (sdist + wheel)None
make docsStart Docusaurus dev serverNode.js
E2E Smoke Tests

The smoke tests scaffold a real project, install dependencies, start the backend, and send chat prompts to verify the full pipeline works end-to-end. Pass --backend nams to test the hosted-memory path (requires MEMORY_API_KEY env); the default bolt exercises self-hosted Neo4j with full demo fixtures:

# Run all 3 smoke tests (requires Neo4j + at least one LLM API key)
make smoke-test

# Or run individual framework tests directly (default: --backend bolt)
python scripts/e2e_smoke_test.py --domain financial-services --framework pydanticai --quick
python scripts/e2e_smoke_test.py --domain real-estate --framework google-adk --quick
python scripts/e2e_smoke_test.py --domain trip-planning --framework strands --quick

# Test against NAMS hosted backend (requires MEMORY_API_KEY env)
python scripts/e2e_smoke_test.py --domain healthcare --framework strands --backend nams --quick

# Test all 27 domains with one framework
python scripts/e2e_smoke_test.py --all-domains --framework pydanticai --quick

# Full mode (all prompts per scenario, not just first)
python scripts/e2e_smoke_test.py --domain healthcare --framework claude-agent-sdk

Required environment variables:

  • NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD — Neo4j connection (Aura, Docker, or local) for --backend bolt

  • MEMORY_API_KEY — NAMS API key for --backend nams

  • ANTHROPIC_API_KEY — for Claude-based frameworks (PydanticAI, Claude Agent SDK, Anthropic Tools, Strands, CrewAI)

  • OPENAI_API_KEY — for OpenAI-based frameworks (OpenAI Agents, LangGraph)

  • GOOGLE_API_KEY — for Google ADK (Gemini)

CI Pipeline

GitHub Actions (.github/workflows/ci.yml) runs automatically:

JobTriggerDescription
testAll pushes + PRsUnit tests on Python 3.11 and 3.12 (1,177 tests including security, doc snippets, frontend logic, NAMS adapter, wizard, route integration)
lintAll pushes + PRsRuff linter on src/ and tests/
matrixPush to main onlyFull suite + 176 domain × framework matrix + perf + generated project tests (1,398 tests)
smoke-testPush to main onlyNeo4j integration tests + E2E for all 8 frameworks (scaffold → install → start → chat)

The smoke-test CI job is gated behind a SMOKE_TESTS_ENABLED repository variable. To enable it:

  1. Go to Settings → Variables → Repository variables and add SMOKE_TESTS_ENABLED = true

  2. Go to Settings → Secrets → Repository secrets and add:

    • NEO4J_URI — e.g., neo4j+s://xxxxx.databases.neo4j.io

    • NEO4J_USERNAME

    • NEO4J_PASSWORD

    • ANTHROPIC_API_KEY

    • OPENAI_API_KEY

    • GOOGLE_API_KEY

The smoke-test job uses fail-fast: false so one framework failure doesn't block the others, and it only runs after the unit test job passes.

The npm package is a thin wrapper that delegates to the Python CLI via uvx, pipx, or python3 -m. It requires Python 3.11+ to be installed.

Automated Publishing (GitHub Actions)

Both packages are published automatically when you push a version tag:

# 1. Update version in pyproject.toml and npm-wrapper/package.json
# 2. Commit the version bump (and any CHANGELOG.md update)
# 3. Tag and push
git tag v0.13.0
git push origin v0.13.0

This triggers a GitHub Actions workflow, release.yml with jobs:

  • publish-pypi — Builds and publishes to PyPI

  • publish-npm — Publishes the npm wrapper to npmjs.com Both use trusted publishing/OIDC.

Version Bumping

Both packages must use the same version. Update in two places:

  1. pyproject.toml → version = "X.Y.Z"

  2. npm-wrapper/package.json → "version": "X.Y.Z"

Note: a job called validate-version-consistency in release.yml ensures that the correct versions exist in both places.

License

Apache-2.0

document-parsing-libraries.md

Document parsing libraries and

This document breaks down some candidate Python libraries and APIs for doing unstructured document parsing, which is the first step of the KG builder pipe line (after fetching the docs of course).

For context, the MVP scope we decided on for this is pdf only, and not worry about images and tables in the pdfs.

Python libraries for local parsing

docling

Covers all kinds of document types including pdf, docx, pptx, images, etc, including determining what the format of the doc is. It uses OCR to detect text. It also has the capability to output the parsed doc in a different format, such as markdown. Uses ML models, so would probably run faster with decent HW acceleration. Seems to be the best in terms of quality out of all “intelligent” doc parsing libs/APIs. The API also has functionality for deriving metadata and high level document structure. Well maintained (IBM).

License: MIT

unstructured.io (OSS Python lib)

It basically has the same functionality as docling. However people online claim that docling is significantly better these days in terms of accuracy. Seems well maintained.

License: Apache 2.0

pypdf

What we use now. Works only on PDF. It’s pretty fast. It does extract text from tables and adds some special characters to it. When I give this extracted table as text to an LLM, it is able to understand it completely. It can extract images from pdfs, but not interpret them as text. It also has great functionality for extracting metadata, without parsing the entire document. And can also extract a document’s structure (nested tree of titles and page numbers). Well maintained.

License: BSD

pymupdf

Supports several doc types, including docx, xlsx, epub, and more. It’s very fast (containing non-Python code). Like docling, it can also output parsed text as markdown, and even help with chunking. Like pypdf, it handles metadata, doc structure well in that it can derive them without parsing the entire doc. It also extracts tables as text with special characters in a way that can be parsed by an LLM. Images are also handled the same way as in pypdf, i.e. it can extract them from a pdf, but there’s no OCR or anything to interpret it. Well maintained.

License: AGPL

pdfminer.six

Similar to the aforementioned pypdf. The main difference is that it’s able to derive additional, more precise information like font types, and precise character positions and size. This could be useful if we want to capture the exact layout and geometry of the pdf. It cannot be used for editing pdfs. Seems well maintained.

License: MIT

pdfplumber

Built on top of pdfminer.six, and has some additional convenience functionality that makes it a bit easier to use. Seems to be good at extracting tables (not sure that we need more than py(mu)pdf for that though…). Does not have a major release yet, but seems fairly well maintained.

License: MIT

python-docx

Works only on docx. Seems pretty fast, and can parse tables. Has fantastic support for navigating the structure of the document, once it’s parsed. Seems to be well maintained.

License: MIT

Cloud solutions

These are all basically docling, but as hosted cloud services with HTTP APIs.

LlamaParse

This seems to be fairly popular. Folks online say it’s both faster and has better accuracy than unstructured.io (but worse than docling). It has some functionality for deriving metadata and doc layout as well.
Cost is $0.003 per page.

unstructured.io (Cloud solution)

Used to be popular, but has fallen out of favor recently due to being slower and having worse accuracy than LlamaParse, and for this reason I did not benchmark it as a cloud solution.
Start package price is $500/month for 15k pages, and $0.03/page after that.

Performance benchmark

The benchmark is performed on three different documents, with the relevant libs/APIs. The time is measured in seconds, and approximate over several runs. The benchmark was run on a basic MacBook Pro (by default using the mps device as an accelerator for docling).

The documents

Simple 2 page pdf: The ‘Harry Potter and the Chamber of Secrets Summary’ document, only containing text.

Complex 72 page pdf: The paper ‘Challenges and Applications of Large Language Models’. Contains formulas, tables, images.

Small docx file: 1-2 pages of straightforward docx, but containing things like tables and dotted lists.

Results
Simple 2 page pdfComplex 72 page pdfSmall docx file
docling w/o OCR1.5 - 213 - 140.39 - 0.45
docling w/ OCR4.5 - 549 - 520.39 - 0.45
unstructured.io (lib) w/o OCR0.074.18 - 4.220.07
unstructured.io (lib) w/ OCR5.2 - 5.42350.07
pypdf0.0091.8 - 1.9n/a
pymupdf0.0050.330.002
pdfminer.six0.0333.2 - 3.3n/a
pdfplumber0.1656.6 - 6.7n/a
python-docxn/an/a0.003
LlamaParse w/o OCR30 (first run), 5 - 7 (subsequent runs)100 (first run), 25 - 26 (subsequent runs)5 - 7
LlamaParse w/ OCR30 (first run), 5 - 7 (subsequent runs)138 (first run), 28 - 30 (subsequent runs)18 - 19 (first run), 5 - 7 (subsequent runs)
Some observations

  • pymupdf is the fastest in all categories

  • Using an “intelligent” parser with OCR (optical character recognition of tables, images, etc) is several magnitudes slower than standard doc parsing, as expected

  • docling and unstructured.io is always slower on PDF when using OCR, even if the document only contains text

  • unstructured.io is significantly faster than docling when not using OCR, but significantly slower when using OCR

  • LlamaParse seems to be using caching (sometimes?), so the second time a document is dispatched it is parsed much faster. But that wouldn’t be of great help to us

Conclusion

Considering our limited MVP scope, just using pymupdf for now seems like the way to go. It’s the most performant, can handle most document formats, and handles metadata, doc structure and tables well. The main thing we would miss out on is using OCR to parse very visual data, like powerpoint docs and images, as well as very precise PDF information like font types. For the former we might consider docling (better accuracy and perf than unstructured.io when using OCR) running on proper HW, or a remote API like LlamaParse in the future.

344 files · 334 not served here

Advantages

  • Rapidly scaffolds full-stack applications with domain-specific ontologies and agent tools in under 5 minutes. evidence: README.md
  • Provides flexible memory backend options, supporting both hosted NAMS and self-hosted Neo4j. evidence: README.md

Limitations

  • The NAMS hosted memory backend has a narrower write surface compared to self-hosted Neo4j, limiting some Cypher-based operations. evidence: README.md
  • Requires specific API keys and environment variables depending on the chosen agent framework and memory provider. evidence: README.md

Security

Risk level: Low risk

This brain runs

Agent instructions that run or fetch something (28)

  • CLAUDE.md: Invoked via `uvx create-context-graph` or `npx create-context-graph`.
  • CLAUDE.md: (2) every document/body ingest write failed (`role="document"` rejected — only user/assistant/system allowed — plus the conversation-404), fixed across all three NAMS ingest implementations (`run_nams_ingest`, scaffolded `import_data.py`, `make seed`'s `ingest_fixtures_nams`) with `role …[+63 chars]
  • CLAUDE.md: the old loop swallowed the AttributeError and printed "0 removed") — `--reset-database` and `make reset` now honestly report that no delete API exists and point at the NAMS dashboard.
  • CLAUDE.md: **NAMS domain ontology activation (new)**: NAMS pre-registers a server-side ontology for every bundled domain but auto-binds workspaces to `nams-default` until one is activated — generated apps now bind on `connect_memory()` (activate catalog match by domain id, or create-from-`backend …[+359 chars]
  • CLAUDE.md: **Carry-forward from v0.13.1 (feedback-report triage):** `create-context-graph --dry-run` no longer demands a NAMS API key (the credential gate is now scoped to non-dry-run flows in `cli.py:392`).
  • CLAUDE.md: **Carry-forward from v0.13.0 (v0.12.0 feedback-report fixes):** Fixed the bolt async/sync mismatch in the scaffolded `import_data.py` (`_ingest_via_bolt()` is `async def` and both call sites wrap with `asyncio.run`);
  • CLAUDE.md: uv venv && uv pip install -e ".[dev]"
  • CLAUDE.md: # Run tests
  • CLAUDE.md: **Data seeding** (`make seed`): Loads all four data types into Neo4j — entities, relationships, documents (as `:Document` nodes with `:MENTIONS` links to entities), and decision traces (as `:DecisionTrace` → `:HAS_STEP` → `:TraceStep` chains).
  • CLAUDE.md: As tools execute, the collector emits `tool_start` and `tool_end` events (with graph data).
  • CLAUDE.md: CrewAI and Strands are synchronous frameworks that run in worker threads via `asyncio.to_thread()`.
  • CLAUDE.md: When `--with-mcp` is passed (or selected in the wizard), the scaffold generates `mcp/claude_desktop_config.json` (pre-configured for the project's Neo4j instance), `mcp/README.md` (setup instructions), and a `make mcp-server` Makefile target.
  • CLAUDE.md: python-docx (Word).
  • CLAUDE.md: Connectors run at scaffold time AND are generated into the project with `make import` / `make import-and-seed` targets.
  • CLAUDE.md: pytest tests/test_generated_tests.py # Scaffold + install + run generated project test suite for 4 frameworks (slow, 5)
  • CLAUDE.md: Full-stack integration tests that scaffold a project, install dependencies, start the backend, and send chat prompts.
  • CLAUDE.md: make smoke-test # Run 3 key framework tests (pydanticai, google-adk, strands)
  • CLAUDE.md: # Or run directly with more control:
  • CLAUDE.md: python scripts/e2e_smoke_test.py --domain healthcare --framework pydanticai --quick
  • CLAUDE.md: python scripts/e2e_smoke_test.py --all-domains --framework claude-agent-sdk --quick
  • CLAUDE.md: python scripts/e2e_smoke_test.py --domain gaming --framework openai-agents # full mode (all prompts)
  • CLAUDE.md: | Target | Description | |--------|-------------| | `make test` | Fast unit tests (1,454 passing, no external deps) | | `make test-slow` | Full suite including matrix + perf + generated project + connector/functional tests (1,866 passing with connectors extra) | | `make test-matrix` | …[+533 chars]
  • CLAUDE.md: Generate fixture data: run the CLI with `--demo-data` or use `generator.py` directly
  • CLAUDE.md: | Framework | Directory | Pattern | Streaming | |-----------|-----------|---------|-----------| | PydanticAI | `pydanticai/` | `@agent.tool` decorator + `RunContext[AgentDeps]` | Full (`agent.run_stream()`) | | Claude Agent SDK | `claude_agent_sdk/` | Dict-based TOOLS list + bounded ag …[+787 chars]
  • CLAUDE.md: | Job | Trigger | Description | |-----|---------|-------------| | **test** | All pushes + PRs | Fast unit tests on Python 3.11 and 3.12 (`fail-fast: false` so one version's failure doesn't cancel the other) | | **lint** | All pushes + PRs | Ruff on `src/` and `tests/` (rule set pinned …[+444 chars]
  • CLAUDE.md: **Every job installs from `uv.lock` via `uv sync --locked --extra ...` and runs commands with `uv run --no-sync`.** Never mix `uv pip install` with a bare `uv run` in CI: `uv run` does an implicit lockfile sync that downgrades locked base deps underneath freshly-installed latest extras …[+94 chars]
  • CLAUDE.md: If `--locked` fails, run `uv lock` locally and commit the refreshed lockfile — dependency changes in `pyproject.toml` must ship with a matching `uv.lock`.
  • CLAUDE.md: The Makefile test/lint targets use `uv run --extra dev ...` so local runs resolve from the lock the same way.

Install scripts (1)

  • Makefile (make install): uv venv && uv pip install -e ".[dev]"
  • Low risk: network-instructions (CLAUDE.md:15)
  • Low risk: network-instructions (Makefile:10)
  • Low risk: scripts-present (scripts/e2e_smoke_test.py)
  • Low risk: scripts-present (scripts/regenerate_fixtures.py)

Attribution and licence

Created by
neo4j-labs
Declared authors
  • William Lyon (declared in pyproject.toml)
Publisher
neo4j-labs (Official neo4j-labs project)
Source
neo4j-labs/create-context-graph · commit 926e3b3
Licence
Apache License 2.0 (files served here)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by neo4j-labs.

Install from source

334 of its files are not served here, so there is no ZIP. neo4j-labs/create-context-graph at 926e3b3