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

LICENSE

Shown as plain text.

                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to the Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by the Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding any notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   Copyright 2026 Neo4j Labs

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
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