Create Context Graph

Roadmap — Create Context Graph

Last updated: March 22, 2026

Overview

Create Context Graph was built in 6 phases. The goal was to go from an empty repository to a published CLI tool that generates domain-specific context graph applications for 22 industry verticals with 8 agent framework options, powered by neo4j-agent-memory for multi-turn conversations.

Phase 1: Core CLI & Template Engine — COMPLETE

Timeline: Weeks 1–3 Status: Done

Built the foundational scaffolding tool: Python package structure, CLI, interactive wizard, template engine, and initial templates.

What was built

• Python package (src/create_context_graph/) with hatchling build, src layout, entry point via create-context-graph command

• Click CLI (cli.py) with both interactive and non-interactive (flag-based) modes

• Interactive wizard (wizard.py) — 7-step flow using Questionary + Rich: project name, data source, domain selection, agent framework, Neo4j connection, API keys, confirmation

• ProjectConfig model (config.py) — Pydantic model holding all wizard outputs, computed slug, framework display names and dependency mappings for all 8 planned frameworks

• Domain ontology system (ontology.py) — YAML loader with two-layer inheritance (_base.yaml + domain YAML), Pydantic validation models for all ontology sections, code generation helpers (Cypher schema, Pydantic models, NVL visualization config)

• Jinja2 template engine (renderer.py) — PackageLoader-based renderer with custom filters (snake_case, camel_case, pascal_case, kebab_case), renders full project directory from templates + ontology context

• 3 initial domain ontologies — Financial Services, Healthcare, Software Engineering (complete with entity types, relationships, document templates, decision traces, demo scenarios, agent tools, system prompts, visualization config)

• Backend templates — FastAPI main, config, Neo4j client, GDS client, vector search client, Pydantic models, REST routes, pyproject.toml, data generation script, agent stub fallback

• 2 agent framework templates — PydanticAI (structured tool definitions with RunContext) and Claude Agent SDK (Anthropic tool-use with agentic loop)

• Frontend templates — Next.js 15 + Chakra UI v3 + NVL: layout, page (3-panel), ChatInterface, ContextGraphView, DecisionTracePanel, Provider, domain config, theme

• Base templates — .env, Makefile, docker-compose.yml, README.md, .gitignore

• Cypher templates — Schema constraints/indexes from ontology, GDS graph projections

• Neo4j connection validator (neo4j_validator.py)

Key design decisions made

• Templates are domain-agnostic, data-driven — no per-domain template directories; the ontology YAML drives all customization

• Only agent.py varies by framework; everything else is shared

• JSX/Python dict literals in templates use {% raw %}...{% endraw %} blocks to avoid Jinja2 conflicts

• Pre-built fixtures are bundled and copied into every generated project

Phase 2: Domain Expansion & Document Generation — COMPLETE

Timeline: Weeks 4–6 Status: Done

Expanded from 3 domains to 22, built the synthetic data generation pipeline, and created the Neo4j ingestion system.

What was built

• 19 additional domain ontology YAMLs — All validated and scaffold-tested. Domains: Agent Memory, Conservation, Data Journalism, Digital Twin, Gaming, GenAI/LLM Ops, GIS & Cartography, Golf & Sports Mgmt, Hospitality, Manufacturing, Oil & Gas, Personal Knowledge, Product Management, Real Estate, Retail & E-Commerce, Scientific Research, Trip Planning, Vacation Industry, Wildlife Management

• Synthetic data generation pipeline (generator.py) — 4-stage pipeline:

  1. Entity seeding — LLM-powered or static fallback, generates 5+ entities per type with properties matching ontology schema

  2. Relationship weaving — Connects entities based on ontology relationship definitions, avoids self-relationships

  3. Document generation — Produces 25+ documents across all template types defined in the ontology (LLM-powered for realistic content, static fallback for offline use)

  4. Decision trace injection — Creates reasoning traces from ontology scenarios with thought/action/observation steps

• LLM client abstraction — Supports both Anthropic and OpenAI as generation providers, graceful fallback to static data when no API key is available

• Data ingestion system (ingest.py) — Dual-backend ingestion:

  • Primary: neo4j-agent-memory MemoryClient (long-term entities, short-term documents, reasoning traces — all three memory types)

  • Fallback: Direct neo4j driver when neo4j-agent-memory isn't installed

  • Schema application from generated Cypher

• Pre-generated fixture files — All 22 domains ship with static fixtures/{domain-id}.json files so projects work immediately without an LLM API key

• CLI integration — --demo-data flag triggers generation, --ingest flag triggers Neo4j ingestion, --anthropic-api-key enables LLM-powered generation, pre-built fixtures always copied into data/fixtures.json

• Comprehensive test suite (85 tests, all passing):

  • test_config.py — 10 unit tests for ProjectConfig

  • test_ontology.py — 20 unit tests including parametric validation of all 22 domains

  • test_renderer.py — 18 unit tests for rendering, file structure, framework selection, Python compile verification

  • test_generator.py — 14 unit tests for data generation across 6 domains

  • test_cli.py — 13 integration tests for CLI invocation, 6 domain/framework combinations

Verified

• All 22 domains load and validate without errors

• 18/18 domain+framework combinations scaffold successfully (9 domains x 2 frameworks)

• Generated Python files pass compile() syntax check

• 85/85 tests pass in 3.4 seconds

Phase 3: Framework Templates & Frontend — COMPLETE

Timeline: Weeks 7–8 Status: Done

Added all 8 agent framework templates, replaced NVL placeholder with real graph visualization, and expanded the test suite.

What was built

• 6 new agent framework templates — All in templates/backend/agents/, each generating valid Python with domain-specific tools from ontology:

  • OpenAI Agents SDK (openai_agents/) — @function_tool decorators + Runner.run()

  • LangGraph (langgraph/) — @tool + create_react_agent() with ChatAnthropic

  • CrewAI (crewai/) — Agent + Task + Crew with @tool decorator

  • Strands (strands/) — Agent with @tool, Anthropic model

  • Google ADK (google_adk/) — Agent + FunctionTool, Gemini model, async runner

  • MAF (maf/) — Modular tool registry with decorator pattern

• NVL graph visualization — Replaced placeholder in ContextGraphView.tsx with real @neo4j-nvl/react InteractiveNvlWrapper component: force-directed layout, domain-colored nodes via NODE_COLORS/NODE_SIZES, node click handler, color legend

• Makefile improvements — Added make test and make lint targets

• Expanded test suite (103 tests, all passing in 3.78s):

  • TestAllFrameworksRender — 8 parametric tests verifying each framework's agent.py compiles and contains framework-specific imports

  • TestAllFrameworksRender — 8 parametric tests verifying each framework's pyproject.toml contains correct dependencies

  • TestMultipleDomainScaffolds — Expanded from 6 to 8 domain/framework combinations covering all frameworks

Verified

• All 8 frameworks scaffold, render, and compile without errors

• All 8 frameworks produce correct pyproject.toml dependencies

• Each framework's agent.py contains the expected framework marker (import/class name)

• 103/103 tests pass in 3.78 seconds

Phase 4: SaaS Import & Custom Domains — COMPLETE

Timeline: Weeks 9–10 Status: Done

Implemented SaaS data connectors for 7 services and LLM-powered custom domain generation.

What was built

SaaS data connectors

• Connectors package (connectors/) — BaseConnector ABC, NormalizedData Pydantic model matching fixture schema, connector registry with @register_connector decorator

• 7 service connectors, each with authenticate(), fetch(), and get_credential_prompts():

• Google Workspace CLI (gws) integration — Gmail and Google Calendar connectors detect gws on PATH, offer to install via npm if missing, fall back to Python OAuth2

• OAuth2 local redirect flow (oauth.py) — Temporary HTTP server on random port, browser consent, auth code capture, token exchange

• Dual-purpose connectors — Run at scaffold time to populate initial data AND generated into the scaffolded project for ongoing make import / make import-and-seed usage

• Connector templates — 7 standalone connector .py.j2 templates + import_data.py.j2 generated into scaffolded projects (only for selected connectors)

• Makefile targets — make import and make import-and-seed added to generated projects when SaaS connectors are selected

• Wizard integration — Checkbox selection of connectors, credential prompts, gws CLI detection and install prompt

• CLI flags — --connector (multiple) for non-interactive connector selection

• Optional dependencies — New [connectors] extra in pyproject.toml

Custom domain generation

• custom_domain.py — LLM-powered domain YAML generation:

  1. Loads _base.yaml + 2 reference domain YAMLs (healthcare, wildlife-management) as few-shot examples

  2. Builds prompt with complete YAML schema specification

  3. Calls LLM (Anthropic/OpenAI) via existing generator.py abstraction

  4. Parses YAML, validates against DomainOntology Pydantic model

  5. On validation failure, retries with error feedback (up to 3 attempts)

  6. Returns (DomainOntology, raw_yaml_string)

• ontology.py extensions — load_domain_from_yaml_string(), load_domain_from_path(), list_available_domains() now scans ~/.create-context-graph/custom-domains/

• Wizard integration — Description prompt → LLM generation with spinner → Rich summary table → accept/regenerate/edit → optional save for reuse

• CLI flag — --custom-domain "description" for non-interactive custom domain generation

• Renderer support — Custom domain YAML written directly to data/ontology.yaml

• Persistence — Custom domains saved to ~/.create-context-graph/custom-domains/ and appear in future wizard runs

Bug fixes

• Fixed cli.py:73 — data_source was always "demo" regardless of flags

Tests added (40 new tests)

• test_custom_domain.py — 17 tests: YAML string loading, base merge, validation errors, prompt construction, mocked LLM generation (success, retry, max retries), display, save, custom domain listing

• test_connectors.py — 23 tests: NormalizedData model, merge, registry (7 connectors), credential prompts, mocked fetch for GitHub/Notion/Jira/Slack/Gmail/GCal/Salesforce, OAuth helpers

Verified

• All 7 connectors register and expose credential prompts

• Mocked connector fetches return valid NormalizedData

• Custom domain generation succeeds with mocked LLM

• Custom domain retry loop works on validation failure

• 182/182 tests pass in 5.2 seconds

Phase 5: Polish, Testing & Launch — COMPLETE

Timeline: Weeks 11–12 Status: Done

Prepared for public release with Docusaurus documentation, Neo4j Labs compliance, enhanced testing, and version 0.2.0.

What was built

Docusaurus documentation site

• Docusaurus 3.x site in docs/ with TypeScript config, Diataxis-organized sidebar

• 11 documentation pages following the Diataxis framework:

  • Tutorials: Your First Context Graph App, Customizing Your Domain Ontology

  • How-To Guides: Import Data from SaaS Services, Add a Custom Domain, Switch Agent Frameworks

  • Reference: CLI Options & Flags, Ontology YAML Schema, Generated Project Structure

  • Explanation: How Domain Ontologies Work, Why Context Graphs Need All Three Memory Types

• GitHub Pages deployment via .github/workflows/deploy-docs.yml (triggers on docs/ changes to main)

• Site URL: https://create-context-graph.vercel.app/

Neo4j Labs compliance

• Apache-2.0 license headers added to all 32 Python source and test files

• Labs badge added to README.md and generated project README template

• Community support disclaimer updated to standard Neo4j Labs language

• CONTRIBUTING.md — Getting started, adding domains/frameworks/connectors, testing, PR process

Testing improvements

• Cypher syntax validation in test_generated_project.py — validates statement keywords and semicolons

• Frontend syntax validation — TSX files checked for imports and exports, config.ts validated for required exports

• Timed performance test (test_performance.py) — all 22 domains must scaffold in < 120 seconds each (slow marker)

Publishing

• Version bumped to 0.2.0 across pyproject.toml, npm-wrapper/package.json, and __init__.py

• Publishing workflows already in place from prior phases (PyPI + npm on version tags)

Success metrics achieved

Post-Launch: Data Quality & UI Enhancements — COMPLETE

Status: Done

Fixture data quality overhaul

• name_pools.py — Realistic name pools (25 person names, 20 org names, etc.) and contextual value generators (emails from names, realistic IDs, domain-appropriate ranges)

• Improved static fallback in generator.py — produces passable data without an LLM (realistic names, structured documents, interpolated trace outcomes)

• scripts/regenerate_fixtures.py — One-time script to regenerate all 22 fixtures using Claude API with coherent cross-entity prompts, validation, and retry logic

• All 22 fixtures regenerated with LLM-quality data: 80-90 entities, 160-280 relationships, 25+ documents (200-1600 words each), 3-5 decision traces with specific observations and outcomes

• Fixture quality tests — 66 parametrized tests across all 22 domains verify no placeholder names, documents >= 200 chars, no uninterpolated template variables

Full fixture data utilization in generated apps

• generate_data.py.j2 updated — make seed now loads all 4 data types: entities, relationships, documents (as :Document nodes with :MENTIONS entity links), and decision traces (as :DecisionTrace → :HAS_STEP → :TraceStep chains)

• 4 new API endpoints in routes.py.j2:

  • GET /documents — list with template filter, previews, mentioned entities

  • GET /documents/{title} — full document content

  • GET /traces — traces with full reasoning steps

  • GET /entities/{name} — all properties, labels, and connections

• Document browser (DocumentBrowser.tsx.j2) — template type filter badges, scrollable list with previews, full document viewer with mentioned entity badges

• Entity detail panel in ContextGraphView.tsx.j2 — click any graph node to see all properties, labels, and connections with relationship types/directions

• Fixed DecisionTracePanel — uses new /traces endpoint, loads steps with observations (was previously broken: wrong node label, empty steps array)

• Tabbed right panel in page.tsx.j2 — Traces and Documents tabs using Chakra UI v3 compound Tabs components

• Schema indexes for Document and DecisionTrace nodes added to generate_cypher_schema()

Graph Visualization & Agent Fixes — COMPLETE

Status: Done

Interactive graph visualization

• Schema view on load — Graph starts by calling db.schema.visualization() (via new GET /schema/visualization endpoint), showing entity type labels as nodes and relationship types as edges. No data query on initial load.

• Agent-driven graph updates — CypherResultCollector in context_graph_client.py captures all Cypher results from agent tool calls. The /chat endpoint drains collected results and attaches them as graph_data in the response. ChatInterface passes graph_data to page.tsx via onGraphUpdate callback, which flows to ContextGraphView as externalGraphData. Works for all 8 agent frameworks without modifying any agent template.

• Double-click to expand — Schema nodes load instances of that label (MATCH (n:\Label`)-[r]-(m) RETURN n,r,m LIMIT 50). Data nodes call new POST /expand` endpoint to fetch neighbors. Expanded data is merged with deduplication.

• NVL d3Force layout — Replaced InteractiveNvlWrapper configuration: d3Force layout, zoom 0.1–5x, relationship thickness 2, dynamic import for SSR avoidance. Uses mouseEventCallbacks for node click, double-click, relationship click, canvas click.

• Property details panel — Click any node to see labels (color badges), all properties (key-value list), and metadata. Click relationships to see type and properties. Canvas click deselects.

• UI overlays — Color legend (top 6 node types), instructions overlay, loading spinner during expansion, back-to-schema button, schema/data mode indicator.

• State management — page.tsx lifts graphData state with useState/useCallback. Props flow down, callbacks flow up. No external state library.

Neo4j driver serialization fix

• _serialize() function in context_graph_client.py.j2 — Replaced result.data() (which strips metadata) with per-record iteration and custom serialization preserving Node (elementId, labels), Relationship (elementId, type, startNodeElementId, endNodeElementId), and Path objects.

MAF agent template fix

• Bug: MAF agent used keyword-based tool dispatch (lines 75-114) that never called an LLM. Fallback echoed system prompt: "I'm your {SYSTEM_PROMPT}... Available tools: ...".

• Fix: Rewrote handle_message() with Anthropic API tool-use loop (matching claude_agent_sdk pattern). Kept TOOL_REGISTRY + @register_tool decorator. Added _build_tool_definitions() that introspects registry via inspect.signature to generate Anthropic tool schemas. Added anthropic>=0.30 to MAF framework dependencies.

New backend endpoints

• GET /schema/visualization — Returns schema graph via db.schema.visualization() (with fallback to basic labels/types)

• POST /expand (body: {element_id}) — Returns immediate neighbors with nodes and relationships for graph expansion

Files modified

• config.py — Added anthropic>=0.30 to MAF deps

• templates/backend/agents/maf/agent.py.j2 — Full rewrite

• templates/backend/shared/context_graph_client.py.j2 — _serialize(), CypherResultCollector, get_schema_visualization(), expand_node()

• templates/backend/shared/routes.py.j2 — New endpoints, collector integration in /chat

• templates/frontend/components/ContextGraphView.tsx.j2 — Complete rewrite (~480 lines)

• templates/frontend/components/ChatInterface.tsx.j2 — onGraphUpdate prop

• templates/frontend/app/page.tsx.j2 — State lifting

• templates/frontend/lib/config.ts.j2 — GraphData type, schema constants

Phase 6: Memory Integration, Multi-Turn & DX — COMPLETE

Status: Done (v0.3.0)

Addressed all critical and high-priority feedback from the v0.2.0 product review. Core theme: make the generated apps actually use neo4j-agent-memory and deliver a compelling multi-turn conversation experience.

Critical fixes

• neo4j-agent-memory integration — Generated context_graph_client.py now initializes MemoryClient alongside the Neo4j driver (with ImportError fallback). Exposes get_conversation_history() and store_message() functions used by all 8 agent frameworks for multi-turn conversation persistence.

• Multi-turn conversations — All 8 agent templates retrieve conversation history before each LLM call and store messages after. Frontend ChatInterface captures session_id from the first response and sends it in all subsequent requests. "New Conversation" button resets session state.

• CrewAI/Strands/Google ADK async fix — Added nest_asyncio to prevent asyncio.run() deadlocks inside FastAPI's async event loop. Added to FRAMEWORK_DEPENDENCIES for all three frameworks.

• MAF → Anthropic Tools rebrand — Renamed framework from maf to anthropic-tools. Template directory moved to anthropic_tools/. Old maf key supported as deprecated alias via FRAMEWORK_ALIASES. Updated all tests.

High-priority fixes

• GDS client — Changed default label from hardcoded "Entity" to "*" (wildcard). Exposed ENTITY_LABELS list generated from domain ontology.

• Markdown rendering — Added react-markdown + remark-gfm to frontend. Assistant messages render through ReactMarkdown with CSS styles for headings, lists, code blocks, tables, blockquotes.

• .env.example — Generated alongside .env with placeholder values (your-password-here). Added to renderer and gitignore correctly.

Neo4j setup options (new)

• Neo4j Aura import — New wizard option "Neo4j Aura (cloud — free tier available)" with signup instructions panel and .env file parser. CLI flag: --neo4j-aura-env PATH.

• neo4j-local — New wizard option "Local Neo4j via neo4j-local (no Docker required)". Generates make neo4j-start/stop/status targets using npx @johnymontana/neo4j-local. CLI flag: --neo4j-local.

• neo4j_type expanded — Config Literal from "docker" | "existing" to "docker" | "existing" | "aura" | "local". Makefile, README, docker-compose all render conditionally based on type.

Medium-priority fixes

• Port configurability — CORS reads from settings.frontend_port. Makefile uses include .env / export with $${BACKEND_PORT:-8000} and $${FRONTEND_PORT:-3000} defaults.

• Process management — make start uses trap 'kill 0' EXIT to clean up child processes on Ctrl+C.

• Docker version pin — neo4j:5 → neo4j:5.26.0 in docker-compose template.

• README entity types — Split into "Base POLE+O Entities" and "Domain-Specific Entities" subsections.

• Vector index creation — create_vector_index() called in app lifespan startup (try/except for Neo4j < 5.13).

Enhancements

• Tool call visualization — CypherResultCollector extended with tool_calls tracking. ChatResponse includes tool_calls field. Frontend renders inline tool call cards (badge + abbreviated inputs) above assistant messages.

• Test scaffold — Generated projects include backend/tests/test_routes.py with test_health() and test_scenarios() tests using mocked Neo4j.

Tests added (52 new tests → 314 total)

• test_renderer.py (+18): .env.example, session_id, ReactMarkdown, memory functions, GDS labels, tool calls, README sections, CORS, vector index, docker pin, trap cleanup, neo4j-local/aura Makefile targets, markdown CSS

• test_generated_project.py (+22): .env.example, ChatInterface features, memory integration, docker pin, neo4j type variations, test scaffold

• test_config.py (+9): aura/local neo4j types, framework alias resolution (maf→anthropic-tools)

• test_cli.py (+3): --neo4j-aura-env, --neo4j-local, maf alias backward compatibility

Files modified

• config.py — SUPPORTED_FRAMEWORKS, FRAMEWORK_ALIASES, FRAMEWORK_DEPENDENCIES, neo4j_type Literal, resolved_framework property

• cli.py — --neo4j-aura-env, --neo4j-local flags, alias resolution

• wizard.py — 4 Neo4j options (Aura, local, Docker, existing), _parse_aura_env helper

• renderer.py — .env.example rendering, base/domain entity type partition, test scaffold rendering, resolved_framework in context

• templates/backend/shared/context_graph_client.py.j2 — MemoryClient init, get_conversation_history(), store_message(), tool call collector

• templates/backend/shared/routes.py.j2 — tool_calls in ChatResponse

• templates/backend/shared/main.py.j2 — CORS from settings, vector index startup

• templates/backend/shared/gds_client.py.j2 — wildcard label, ENTITY_LABELS

• templates/backend/agents/*/agent.py.j2 — all 8 frameworks: multi-turn history, tool_name tracking

• templates/backend/agents/maf/ → templates/backend/agents/anthropic_tools/ — renamed

• templates/frontend/components/ChatInterface.tsx.j2 — session_id, ReactMarkdown, tool call cards, new conversation button

• templates/frontend/package.json.j2 — react-markdown, remark-gfm

• templates/frontend/app/globals.css.j2 — .markdown-content styles

• templates/base/Makefile.j2 — env vars, trap cleanup, neo4j-local targets

• templates/base/docker-compose.yml.j2 — neo4j:5.26.0

• templates/base/dot_env_example.j2 — new file

• templates/base/README.md.j2 — entity sections, neo4j-type-aware instructions, .env.example docs

• templates/backend/tests/test_routes.py.j2 — new test scaffold template

Phase 7 — Hardening, Security & DX (v0.4.0)

Based on comprehensive QA testing of all 176 domain-framework combinations.

Bug Fixes

• B-01 (Critical): Enum identifier sanitization — A+, A-, 3d_model now generate valid Python identifiers (A_PLUS, A_MINUS, _3D_MODEL) with value aliases

• B-02 (Critical): Graceful degradation when Neo4j is unavailable — backend starts in degraded mode with /health endpoint reporting status

• B-03 (High): Cypher injection prevention in gds_client.py — label parameters validated against generated ENTITY_LABELS whitelist

• B-04 (High): CrewAI async/sync fix — replaced bare asyncio.run() with _run_sync() helper using nest_asyncio, crew runs in thread via asyncio.to_thread()

• B-05 (High): Claude Agent SDK model now configurable via ANTHROPIC_MODEL environment variable

• B-06 (Medium): Silent exception swallowing replaced with structured warnings in ingest.py and vector_client.py

• B-07 (Medium): JSON parsing error handling added to all 8 agent framework templates

• B-08 (Medium): Input validation (max_length) on chat and search request models

• B-09/B-10 (Low): CLI validates empty project names, adds --dry-run and --verbose flags

Security

• CORS origins configurable via CORS_ORIGINS environment variable

• Credential warnings in .env.example

• Query timeouts (30s default) on all Neo4j operations

Code Quality

• Magic strings extracted to constants.py module (index names, graph projections, embedding dimensions)

• Frontend error messages: parse HTTP error responses, show actionable guidance

• Document browser pagination (page size 20)

• Semantic HTML landmarks (<main>, <section>, <aside>) and ARIA labels

• 365 passing tests (51 new)

Phase 8 — Streaming Chat & Real-Time Tool Visualization (v0.5.0)

Streaming Architecture (SSE)

• Event-driven CypherResultCollector — added asyncio.Queue-based event system to the global collector. When a streaming session is active, tool_start, tool_end, text_delta, and done events are pushed to the queue automatically as tools execute and text streams in

• POST /chat/stream endpoint — new SSE endpoint alongside existing /chat (backward compatible). Uses StreamingResponse with text/event-stream content type. Emits session_id first, then tool and text events, terminated by done or error

• execute_cypher() emits tool_start before query execution when tool_name is set — all 8 frameworks get real-time tool events with zero agent template changes

Text Streaming (5 of 8 frameworks)

• Full streaming (handle_message_stream() added): PydanticAI (agent.run_stream()), Claude Agent SDK (client.messages.stream()), OpenAI Agents SDK (Runner.run_streamed()), LangGraph (graph.astream_events()), Anthropic Tools (client.messages.stream())

• Tool-only streaming (no agent changes): CrewAI, Strands, Google ADK — tool call events fire in real-time via the collector; text arrives at the end. The /chat/stream route auto-detects and falls back gracefully

Frontend Streaming UI

• SSE client — fetch + ReadableStream + TextDecoder for POST-based SSE (not EventSource which only supports GET)

• Chakra UI Timeline — tool calls displayed as a vertical timeline with Spinner for running tools, checkmark Check icon for complete tools

• Collapsible tool details — expandable view of tool inputs and output preview

• Skeleton loading — Skeleton placeholders while waiting for first content

• Throttled ReactMarkdown — text deltas batched at ~50ms to avoid excessive re-renders

• Incremental graph updates — onGraphUpdate called on each tool_end event, so the NVL visualization updates after each tool completes rather than all at once

Tests added (23 new → 388 total)

• TestStreamingEndpoint — /chat/stream endpoint, StreamingResponse, backward compat

• TestCollectorEventQueue — event queue methods on CypherResultCollector

• TestStreamingAgentTemplates — handle_message_stream presence in 5 frameworks, absence in 3

• TestStreamingFrontend — Timeline, Skeleton, Collapsible, SSE parsing in ChatInterface

• End-to-end validation: 8 frameworks × 3 domains + all 22 domains = 46 scaffold validations

Files modified

• templates/backend/shared/context_graph_client.py.j2 — event queue on CypherResultCollector

• templates/backend/shared/routes.py.j2 — /chat/stream SSE endpoint

• templates/frontend/components/ChatInterface.tsx.j2 — SSE client + Timeline/Collapsible/Skeleton UI

• templates/backend/agents/anthropic_tools/agent.py.j2 — handle_message_stream()

• templates/backend/agents/claude_agent_sdk/agent.py.j2 — handle_message_stream()

• templates/backend/agents/pydanticai/agent.py.j2 — handle_message_stream()

• templates/backend/agents/openai_agents/agent.py.j2 — handle_message_stream()

• templates/backend/agents/langgraph/agent.py.j2 — handle_message_stream()

• tests/test_generated_project.py — 23 new streaming tests

Phase 9 — QA Hardening & DX Polish (v0.5.0)

Comprehensive QA pass across all 176 domain/framework combinations. 15 bugs fixed, 3 false alarms identified, 21 new tests added (409 total).

Critical Fixes

• Settings extra: "ignore" — Neo4j Aura .env files with extra variables (NEO4J_DATABASE, AURA_INSTANCEID) no longer cause ValidationError

• is_connected() state flag — replaced broken sync verify_connectivity() on AsyncDriver with tracked _connected flag set during connect_neo4j()/close_neo4j()

• 503 guards on all endpoints — added _require_neo4j() guard to all 15 Neo4j-dependent routes (was only on /chat and /chat/stream); /cypher now returns 503 for connection errors, 400 for syntax errors

Async Safety

• Removed nest_asyncio from Strands and CrewAI templates — replaced with asyncio.to_thread() + clean asyncio.run() in worker threads. Google ADK keeps nest_asyncio (needed for sync tools within async run_async())

Conversation History

• Structured format — replaced flat "Previous conversation:\n" string concatenation with <conversation_history>[ROLE]\ncontent</conversation_history> format in OpenAI Agents, Strands, CrewAI, and Google ADK

• ADK session leverage — Google ADK skips history injection for existing sessions (ADK manages multi-turn internally), only injects persisted history for new sessions after server restart

Streaming

• Google ADK full streaming — added handle_message_stream() that emits text_delta events from runner.run_async() events. Google ADK promoted from "tools only" to "full streaming" (6 of 8 frameworks now stream)

Frontend Fixes

• Unique message IDs — crypto.randomUUID() for React keys instead of array indices

• Loading fallback — Spinner component in dynamic ContextGraphView import

• Storage warning — console.warn() on sessionStorage failures

Domain & Build Fixes

• Color collision resolution — fixed 12 entity color collisions across 7 domains (entities sharing hex colors with base POLE+O types)

• LIMIT clause — added LIMIT 100 to software-engineering default Cypher query

• ESLint dependencies — added eslint and eslint-config-next to frontend devDependencies

• .dockerignore — new template excluding node_modules, .venv, .git, pycache from Docker builds

• CrewAI Python 3.11+ — conditional requires-python = ">=3.11" in generated pyproject.toml

Developer Experience

• make test-connection — Makefile target to validate Neo4j credentials

• README troubleshooting — common issues with Neo4j connection, port conflicts, API keys (conditional on neo4j_type)

• Framework-specific README — each generated README documents the chosen framework's architecture, streaming support, and required API keys

Tests added (21 new → 409 total)

• TestQABugFixes — config extra ignore, connected flag, endpoint guards, cypher 503, message IDs, storage warning, loading fallback, ESLint deps, dockerignore

• TestDeferredBugFixes — structured history format, ADK session reuse, ADK streaming, CrewAI Python version, strands deps

• test_no_color_collisions_with_base — validates all 22 domains have unique entity colors

• test_all_domains_default_cypher_has_limit — validates LIMIT clause in all domains

Files modified

• templates/backend/shared/config.py.j2 — extra: "ignore"

• templates/backend/shared/context_graph_client.py.j2 — _connected flag

• templates/backend/shared/routes.py.j2 — _require_neo4j() guard

• templates/backend/shared/pyproject.toml.j2 — conditional Python version

• templates/backend/agents/{strands,crewai,google_adk,openai_agents}/agent.py.j2 — async safety, history format, streaming

• templates/frontend/components/ChatInterface.tsx.j2 — message IDs, storage warning

• templates/frontend/app/page.tsx.j2 — loading fallback

• templates/frontend/package.json.j2 — ESLint deps

• templates/base/Makefile.j2 — test-connection target

• templates/base/README.md.j2 — troubleshooting, framework sections

• templates/base/dockerignore.j2 — new file

• src/create_context_graph/config.py — remove nest-asyncio from deps

• src/create_context_graph/renderer.py — register dockerignore template

• src/create_context_graph/domains/*.yaml — color fixes (7 domains), LIMIT clause (1 domain)

• tests/test_generated_project.py — 19 new tests

• tests/test_ontology.py — 2 new tests

Phase 10 — Framework Reliability, Data Quality & UX (v0.5.1)

Comprehensive testing of v0.4.6 revealed that 6 of 9 agent frameworks were non-functional (hanging or not executing tools), plus frontend UX bugs and static data quality issues. This phase addresses all feedback.

Critical: Fix Hanging Frameworks

• Thread-safe CypherResultCollector: _push_event() now detects worker threads and uses loop.call_soon_threadsafe() instead of direct put_nowait() on the asyncio.Queue. Captures self._loop in set_event_queue().

• CrewAI/Strands async bridging: Replaced asyncio.run() in _run_sync() with asyncio.run_coroutine_threadsafe(coro, _main_loop). Added _capture_loop() called before asyncio.to_thread() to capture the main event loop. 30s timeout per tool call.

• Google ADK async bridging: Improved _run_sync() with cross-thread run_coroutine_threadsafe fallback alongside existing nest_asyncio for same-thread reentrant calls.

• Bounded agentic loops: Anthropic Tools and Claude Agent SDK while True: loops replaced with for _iteration in range(15):. Added timeout=60.0 to API calls. Fallback message when max iterations exceeded.

Critical: Fix Tool Execution

• Tool-use emphasis: All 8 agent templates now append "IMPORTANT: You MUST use the available tools to query the knowledge graph..." to the domain system prompt.

• PydanticAI: Added retries=2 to Agent constructor for transient failure recovery.

• OpenAI Agents JSON leak: Streaming now filters response.output_text.delta events only, skipping response.function_call_arguments.delta that leaked raw JSON into the text stream.

Frontend Fixes

• Chat history scoping: STORAGE_KEY and SESSION_KEY now include DOMAIN.id to prevent cross-app pollution when running multiple domain apps.

• SSR hydration fix: Deferred sessionStorage reads to useEffect instead of useState initializer. Added hydrated state.

• Send button: Increased from size="sm" to size="md" with colorPalette="blue".

• Timeout feedback: Added elapsed time counter (shown after 3s), reduced visible timeout from 120s to 60s.

• Retry button: Error messages now include a "Retry" button that resends the original message.

Dependencies & CLI

• neo4j-agent-memory[openai]: Added [openai] extra to fix "OpenAI package not installed" error on store_message().

• --reset-database flag: New CLI flag that runs MATCH (n) DETACH DELETE n before ingestion. Added reset_neo4j() to ingest.py.

Static Demo Data Quality

• Domain-specific name pools: Added 200+ names across 50+ entity labels (medical diagnoses, financial instruments, software repos, gaming items, etc.) in LABEL_NAMES dict in name_pools.py.

• Label-aware ID prefixes: LABEL_ID_PREFIXES maps labels to domain-appropriate prefixes (PAT-, DX-, ACT-, REPO-, etc.).

• get_names_for_label(): New function that checks LABEL_NAMES first, falls back to POLE+O pools.

• Generator updated: _generate_static_entities() now uses get_names_for_label() instead of get_names_for_pole_type().

Decision Traces Expansion

• All 22 domains: Expanded from 3-5 to 8-12 decision traces each. Added ~130 new traces total with domain-specific multi-step reasoning scenarios.

Streaming Endpoint

• Overall timeout: SSE endpoint now has a 300s overall timeout alongside the 120s per-event idle timeout.

Tests added (26 new → 435 total)

• TestAsyncBridgingFixes — CrewAI/Strands use run_coroutine_threadsafe, no bare asyncio.run()

• TestMaxIterationGuards — Anthropic Tools/Claude Agent SDK have bounded iterations

• TestOpenAIStreamFiltering — OpenAI agents filter tool argument deltas

• TestCollectorThreadSafety — Collector uses call_soon_threadsafe and threading

• TestToolPromptSuffix — All 8 frameworks include tool-use emphasis

• TestChatHistoryScoping — Storage keys include DOMAIN.id

• TestHydrationFix — No direct sessionStorage in useState, has hydrated state

• TestNeo4jAgentMemoryDeps — pyproject includes [openai] extra

• TestStreamingEndpointTimeout — Routes have overall_timeout

• TestDomainSpecificNamePools — Label names exist and are used correctly

Files modified

• src/create_context_graph/templates/backend/shared/context_graph_client.py.j2 — thread-safe collector

• src/create_context_graph/templates/backend/agents/crewai/agent.py.j2 — async bridging + tool prompt

• src/create_context_graph/templates/backend/agents/strands/agent.py.j2 — async bridging + tool prompt

• src/create_context_graph/templates/backend/agents/google_adk/agent.py.j2 — async bridging + tool prompt

• src/create_context_graph/templates/backend/agents/anthropic_tools/agent.py.j2 — max iterations + tool prompt

• src/create_context_graph/templates/backend/agents/claude_agent_sdk/agent.py.j2 — max iterations + tool prompt

• src/create_context_graph/templates/backend/agents/pydanticai/agent.py.j2 — tool prompt + retries

• src/create_context_graph/templates/backend/agents/openai_agents/agent.py.j2 — JSON leak fix + tool prompt

• src/create_context_graph/templates/backend/agents/langgraph/agent.py.j2 — tool prompt

• src/create_context_graph/templates/frontend/components/ChatInterface.tsx.j2 — history scoping, hydration, retry, timeout, send button

• src/create_context_graph/templates/backend/shared/pyproject.toml.j2 — openai extra

• src/create_context_graph/templates/backend/shared/routes.py.j2 — overall timeout

• src/create_context_graph/name_pools.py — domain-specific name pools

• src/create_context_graph/generator.py — label-aware naming

• src/create_context_graph/cli.py — --reset-database flag

• src/create_context_graph/ingest.py — reset_neo4j() function

• src/create_context_graph/domains/*.yaml — ~130 new decision traces across all 22 domains

• tests/test_generated_project.py — 26 new tests

Phase 11 — v0.5.1 Testing Feedback Fixes

Comprehensive end-to-end testing of v0.5.0 across all 9 framework/domain combinations revealed 3 critical framework bugs, data quality issues, and UX improvements. This phase addresses all actionable findings from the testing feedback.

Critical: Framework Bug Fixes

• PydanticAI tool serialization: Changed all @agent.tool return types from list[dict] to str with json.dumps(result, default=str). PydanticAI was the only framework returning raw Neo4j objects, causing silent serialization failures that prevented the LLM from seeing tool results.

• Google ADK agent name sanitization: Added | replace('-', '_') to the agent name template. Hyphenated domain IDs (e.g., real-estate, financial-services) produced invalid Python identifiers like real-estate_agent, crashing ADK's LlmAgent validator.

• Strands max_tokens configuration: Added max_tokens=4096 to AnthropicModel() initialization. The Anthropic API requires this parameter; without it, Strands returned a 'max_tokens' KeyError.

Cross-Domain Data Isolation

• Domain property on entities: Both ingestion paths (MemoryClient and direct driver) now add domain=ontology.domain.id to all entity nodes. Enables future domain-scoped queries when sharing a Neo4j instance.

• CLI ingestion tip: After --ingest, prints "Tip: Use --reset-database if you previously ingested a different domain into this Neo4j instance."

• Conditional make seed messaging: Post-scaffold instructions now distinguish between "Seed sample data" (no --ingest) and "Re-seed sample data (already ingested)" (with --ingest).

Static Data Quality Improvements

• 12 new property-specific value pools in name_pools.py: _CURRENCY_POOL (USD, EUR, GBP...), _TICKER_POOL (AAPL, MSFT...), _DRUG_CLASS_POOL (Biguanide, ACE Inhibitor...), _STATUS_POOL, _SEVERITY_POOL, _LANGUAGE_POOL, _COUNTRY_POOL, _COMPLAINT_POOL, _DISPOSITION_POOL, _SPECIALTY_POOL, plus blood_type and gender handling.

• Float value clamping: confidence/score/rating fields clamped to 0.0-1.0 range. efficiency/accuracy/utilization clamped to 60-99%. Prevents absurd values like confidence=552.92.

• Improved description templates: Replaced generic "X record for Y. Created as part of the Z management workflow." with varied, natural-sounding descriptions.

Frontend UX

• Agent thinking text filter: New splitThinkingAndResponse() function in ChatInterface.tsx.j2 detects "thinking" patterns (lines starting with "Let me", "I'll", "First, I need to", etc.) and renders them in a collapsible "Show reasoning" <Collapsible> section, keeping responses focused.

Developer Experience

• HuggingFace warning suppression: Added HF_HUB_DISABLE_TELEMETRY=1 to .env and .env.example templates to suppress unauthenticated Hub warnings on backend startup.

Tests added (75 new → 510 total)

• TestCypherQueryValidation — 66 tests: validates node labels, relationship types, and deprecated syntax across all 22 domain YAMLs' agent_tools Cypher queries

• TestV051Regressions — 9 tests: PydanticAI returns str not list[dict], Google ADK agent names have no hyphens, Strands has max_tokens, .env has HF telemetry setting, confidence/currency/ticker values are realistic, descriptions have no boilerplate, ChatInterface has thinking filter

Files modified

• src/create_context_graph/templates/backend/agents/pydanticai/agent.py.j2 — tool return type str + json.dumps()

• src/create_context_graph/templates/backend/agents/google_adk/agent.py.j2 — agent name hyphen sanitization

• src/create_context_graph/templates/backend/agents/strands/agent.py.j2 — max_tokens=4096

• src/create_context_graph/name_pools.py — 12 new property pools, float clamping, description improvements

• src/create_context_graph/ingest.py — domain property on all entities (both ingestion paths)

• src/create_context_graph/cli.py — post-ingest tip, conditional make seed messaging

• src/create_context_graph/templates/frontend/components/ChatInterface.tsx.j2 — thinking text filter with collapsible reasoning

• src/create_context_graph/templates/base/dot_env.j2 — HF_HUB_DISABLE_TELEMETRY=1

• src/create_context_graph/templates/base/dot_env_example.j2 — HF telemetry + token guidance

• tests/test_ontology.py — TestCypherQueryValidation class (66 tests)

• tests/test_generated_project.py — TestV051Regressions class (9 tests)

Phase 12 — v0.6.0 Comprehensive Testing Feedback Fixes

End-to-end testing of v0.5.3 across 9 framework/domain combinations (6 working, 3 broken) revealed framework bugs, data ingestion issues, data quality gaps, and UI/UX improvements. This phase addresses all P0-P2 findings.

Critical: Framework Fixes

• CrewAI hanging fix: Added explicit llm="anthropic/claude-sonnet-4-20250514" to Agent() constructor — CrewAI was defaulting to OpenAI and hanging when no OPENAI_API_KEY was set. Added ANTHROPIC_API_KEY environment setup, request-level logging, and reduced timeout from 90s to 60s.

• Strands serialization fix: Added _extract_text() helper that tries .text, .message.content, and str() fallbacks — handles ParsedTextBlock serialization issues from newer Anthropic SDK versions.

• Google ADK API key support: Added google_api_key field to ProjectConfig, --google-api-key CLI flag with GOOGLE_API_KEY env, wizard prompt when google-adk is selected, and warning when google-adk used without key.

Critical: Document & Trace Ingestion Fix

The Documents panel and Decision Traces panel appeared empty when using --ingest because the two ingestion paths created incompatible node structures:

• Root cause: _ingest_with_memory_client() stored documents as conversation messages (short-term memory) and traces via the reasoning API, creating different node structures than the :Document and :DecisionTrace/:TraceStep nodes the frontend queries for.

• Fix: Both ingestion paths (_ingest_with_memory_client and _ingest_with_driver) now create :Document and :DecisionTrace/:TraceStep nodes using direct Cypher, matching the generate_data.py.j2 pattern.

• Entity MERGE fix: Direct driver path changed from MERGE (n:Label {all_props}) to MERGE (n:Label {name: $name}) SET ... to prevent duplicate nodes from property mismatches.

Data Quality

• Domain-aware base entity pools: Added DOMAIN_PERSON_NAMES, DOMAIN_ORGANIZATION_NAMES, DOMAIN_LOCATION_NAMES, DOMAIN_EVENT_NAMES, DOMAIN_OBJECT_NAMES, and DOMAIN_ROLE_POOL for 6 domains (healthcare, financial-services, gaming, software-engineering, conservation, data-journalism).

• Fixed templated property values: Added property pools for contraindications, dosage_form, allergies, sector, lead_reporter, manufacturer, mechanism_of_action, population_trend, habitat — replacing "{entity_name} - {PropertyName}" template pattern.

• Domain-aware role generation: generate_property_value() for role/title now checks DOMAIN_ROLE_POOL before falling back to generic roles.

Frontend UI Improvements

• Chat input redesign: Bordered container with focus highlight, keyboard shortcut hint ("Enter to send, Shift+Enter for new line"), compact send button (Chakra UI Pro AI template pattern).

• Suggested questions: Flat wrapped HStack of pill-shaped buttons with full text (no 60-char truncation), "Try these" label with Sparkles icon.

• Message avatars: User/assistant Circle avatars with User/Bot lucide-react icons.

• Tool progress counter: Shows "Running tool N of M..." instead of generic "Generating response..."

CLI

• --demo convenience flag: Shortcut for --reset-database --demo-data --ingest

• --google-api-key flag: New CLI flag with GOOGLE_API_KEY env variable support

Tests added (35 new → 545 total)

• TestV060GoogleApiKey — 2 tests: .env and .env.example include GOOGLE_API_KEY

• TestV060CrewAIFix — 2 tests: explicit LLM config, logging

• TestV060StrandsFix — 1 test: _extract_text helper

• TestV060DomainAwareNamePools — 8 tests: healthcare person names, contraindications, dosage_form, allergies, sector, domain roles, population_trend

• TestV060ChatInterfaceUI — 5 tests: avatars, keyboard hints, no truncation, sparkles icon, tool progress

• TestGoogleApiKey in test_config.py — 2 tests

Files modified

• src/create_context_graph/config.py — google_api_key field

• src/create_context_graph/cli.py — --google-api-key, --demo flags, google-adk warning

• src/create_context_graph/wizard.py — Google API key prompt, summary display

• src/create_context_graph/renderer.py — pass google_api_key to template context

• src/create_context_graph/ingest.py — direct Cypher for documents/traces in both paths, entity MERGE fix

• src/create_context_graph/name_pools.py — domain-aware base pools, 9 new property pools, domain-aware roles

• src/create_context_graph/generator.py — pass domain_id to name pool functions

• src/create_context_graph/templates/backend/agents/strands/agent.py.j2 — _extract_text() helper

• src/create_context_graph/templates/backend/agents/crewai/agent.py.j2 — explicit LLM, env setup, logging

• src/create_context_graph/templates/base/dot_env.j2 — GOOGLE_API_KEY

• src/create_context_graph/templates/base/dot_env_example.j2 — GOOGLE_API_KEY with comment

• src/create_context_graph/templates/frontend/components/ChatInterface.tsx.j2 — avatars, input redesign, suggested questions, progress counter

• tests/test_config.py — TestGoogleApiKey

• tests/test_generated_project.py — 5 new test classes

Phase 13 — v0.6.1 Stability, Data Quality & Tool Coverage

Comprehensive v0.6.0 testing revealed dependency issues, data quality gaps, missing tool archetypes, and frontend UX improvements. This phase addresses all findings across v0.6.1 (bug fixes), v0.6.2 (data quality), and v0.7.0 (features + docs) in a single release.

Critical Bug Fixes

• CrewAI [anthropic] dependency: Changed crewai>=0.1 to crewai[anthropic]>=0.1 in config.py FRAMEWORK_DEPENDENCIES. The crewai agent template uses Anthropic's Claude model, which requires the extra.

• CLI auto-slug without PROJECT_NAME: When --domain and --framework flags are provided without a positional project name, the CLI now auto-generates a slug (e.g., healthcare-pydanticai-app). Added TTY detection with helpful error messages for CI/CD.

Data Quality

• Document Markdown format: Static document content now uses ## Heading instead of RST ===/---. DocumentBrowser renders with ReactMarkdown.

• Entity-derived document titles: Titles reference primary entities ("Discharge Summary: Maria Elena Gonzalez") instead of sequential numbers.

• POLE-type-aware entity descriptions: Replaced "Comprehensive patient profile for..." with role/industry-specific descriptions using domain pools.

• Domain-aware Organization.industry: Added DOMAIN_INDUSTRY_POOL for all 22 domains (healthcare → "Hospital Systems", not "Technology").

• Realistic decision trace observations: Now reference actual entity names and vary by action type.

• Improved thinking text filter: Added CONTINUATION_PATTERNS to catch multi-sentence thinking blocks.

Agent Tool Coverage

• list_* and get_*_by_id tools for all 22 domains: Every domain now has aggregate listing and direct ID lookup tools alongside existing search/analysis tools. Each domain has 7-8+ tools (up from 5-6).

• Gaming get_top_players: Domain-specific aggregate tool sorting by level.

Frontend Features

• "Ask about this" button: Clicking a graph node shows a button that sends "Tell me about {entity}" to the chat. Wired via externalInput prop from ContextGraphView → page.tsx → ChatInterface.

• Node hover tooltips: Full name, labels, and top 5 properties shown on hover.

• Health polling 30s → 60s: Reduced unnecessary traffic.

• Mobile-responsive hint text: Keyboard shortcut hint hidden on small screens.

• Suggested question maxW: Pill buttons capped at 320px.

• Scrollable label badges: Label filter badges scroll when they overflow (maxH 180px).

• Seed constraint fix: generate_data.py.j2 uses ON CREATE SET / ON MATCH SET to avoid constraint violations.

Documentation

• 4 new docs pages: use-neo4j-aura.md, use-docker.md, why-context-graphs.md, framework-comparison.md

• Updated sidebars.ts: All new pages added to Docusaurus navigation.

Tests added (57 new → 602 total)

• test_crewai_includes_anthropic_extra — verifies crewai dependency has anthropic extra

• test_no_project_name_auto_generates_slug — verifies CLI auto-slug generation

Files modified

• src/create_context_graph/config.py — crewai[anthropic] dependency

• src/create_context_graph/cli.py — auto-slug generation, TTY detection

• src/create_context_graph/generator.py — Markdown documents, entity-derived titles, realistic observations

• src/create_context_graph/name_pools.py — DOMAIN_INDUSTRY_POOL, _generate_description, _PERSON_LABELS, _ORGANIZATION_LABELS

• src/create_context_graph/templates/backend/shared/generate_data.py.j2 — ON CREATE/MATCH SET

• src/create_context_graph/templates/frontend/components/ChatInterface.tsx.j2 — thinking filter, externalInput, responsive hint

• src/create_context_graph/templates/frontend/components/ContextGraphView.tsx.j2 — tooltips, ask-about button, scrollable badges

• src/create_context_graph/templates/frontend/components/DocumentBrowser.tsx.j2 — ReactMarkdown rendering

• src/create_context_graph/templates/frontend/app/page.tsx.j2 — askAbout wiring, 60s health polling

• All 22 domain YAML files — list_* and get_*_by_id tools added

• docs/sidebars.ts — 4 new pages

• docs/docs/how-to/use-neo4j-aura.md — new

• docs/docs/how-to/use-docker.md — new

• docs/docs/explanation/why-context-graphs.md — new

• docs/docs/reference/framework-comparison.md — new

Phase 14 — v0.7.1 Testing Feedback: Embedding Regression, Data Quality & Docs

Comprehensive v0.7.0 testing revealed 2 critical regressions, data quality gaps, missing documentation, and UX improvements. This phase addresses all findings.

Critical Fixes (P0)

• neo4j-agent-memory embedding regression: Removed [openai] extra from generated pyproject.toml, added sentence-transformers>=2.0 dependency. MemorySettings now auto-detects: uses local sentence_transformers/all-MiniLM-L6-v2 (384 dims) by default, upgrades to OpenAI text-embedding-3-small (1536 dims) if OPENAI_API_KEY is set. Conversation memory works out of the box with no API key.

• openai-agents API key warning: CLI now warns when --framework openai-agents is used without --openai-api-key. Wizard prompt text updated to indicate "required" for this framework.

Data Quality (P1)

• 67 missing LABEL_NAMES: Added name pools for all 67 entity labels that were falling back to generic "Label 1" names. LABEL_NAMES now has 118 entries (up from 51) covering every entity type across all 22 domain YAMLs.

• Post-generation value clamping: Added _validate_and_clamp() in generator.py with 28 property range rules (price_per_night: $30-$2000, duration_hours: 0.25-24, etc.) and taxonomy class correction (species → correct class mapping).

• POLE-type entity descriptions: Added _LOCATION_LABELS, _EVENT_LABELS, _OBJECT_LABELS sets (parallel to existing Person/Organization) plus 7 label-specific description overrides (Medication, Permit, Sensor, Equipment, Paper, Model, Species).

• digital-twin fixture fix: Fixed label casing (UPPERCASE → PascalCase) to match YAML schema.

• Domain-scoped MERGE keys: Changed entity MERGE from {name: $name} to {name: $name, domain: $domain} in both generate_data.py.j2 and ingest.py to prevent constraint violations when sharing a Neo4j instance across domains.

google-adk Error Guard (P2)

• Added try/except AttributeError around runner.run_async() in both handle_message and handle_message_stream to handle SDK cleanup errors when _async_httpx_client was never initialized.

Documentation

• Quick-Start page (docs/docs/quick-start.md): 5-step guide with sidebar link.

• use-neo4j-local guide (docs/docs/how-to/use-neo4j-local.md): 3 setup options (npx, Desktop, Docker).

• switch-frameworks slug fix: Added slug: switch-frameworks to fix 404.

• Domain catalog (docs/docs/reference/domain-catalog.md): Auto-generated table of all 22 domains with entity types, tool counts, sample questions.

• Architecture diagram: Mermaid flowchart added to docs/docs/intro.md.

• Updated sidebars.ts: Added quick-start, use-neo4j-local, domain-catalog to navigation.

Frontend UX

• Status indicator: Enlarged from 8px to 12px, added text label ("Connected"/"Degraded"/"Offline").

• Health check retry: Initial load retries 3 times with exponential backoff (1s/2s/4s) to prevent "Internal Server Error" on first page load.

• Empty graph state: Larger icon, descriptive heading ("Your knowledge graph will appear here"), actionable guidance text.

Tests added (89 new → 691 total)

• tests/test_fixtures.py (88 tests): Fixture schema alignment (required properties, agent tool property references, label coverage), data quality validation (numeric ranges)

• test_pyproject_has_sentence_transformers — verifies no [openai] extra

• test_context_graph_client_has_embedding_config — verifies embedding provider selection logic

Files modified

• src/create_context_graph/templates/backend/shared/pyproject.toml.j2 — removed [openai] extra, added sentence-transformers

• src/create_context_graph/templates/backend/shared/context_graph_client.py.j2 — embedding provider auto-detection

• src/create_context_graph/templates/base/dot_env_example.j2 — clarified OPENAI_API_KEY is optional

• src/create_context_graph/cli.py — openai-agents warning

• src/create_context_graph/wizard.py — framework-specific OpenAI key prompt

• src/create_context_graph/name_pools.py — 67 new LABEL_NAMES, 3 new label sets, 7 description overrides

• src/create_context_graph/generator.py — _validate_and_clamp(), _PROPERTY_CLAMP_RANGES, _TAXONOMY_CLASS_MAP

• src/create_context_graph/ingest.py — domain-scoped MERGE keys

• src/create_context_graph/templates/backend/shared/generate_data.py.j2 — domain-scoped MERGE keys

• src/create_context_graph/templates/backend/agents/google_adk/agent.py.j2 — AttributeError guard

• src/create_context_graph/templates/frontend/app/page.tsx.j2 — health retry, larger status dot

• src/create_context_graph/templates/frontend/components/ContextGraphView.tsx.j2 — improved empty state

• src/create_context_graph/fixtures/digital-twin.json — fixed label casing

• tests/test_generated_project.py — updated embedding tests

• tests/test_fixtures.py — new cross-validation test suite

• docs/docs/quick-start.md — new

• docs/docs/how-to/use-neo4j-local.md — new

• docs/docs/reference/domain-catalog.md — new

• docs/docs/how-to/switch-agent-frameworks.md — slug fix

• docs/docs/intro.md — architecture diagram, updated links

• docs/sidebars.ts — 3 new pages

Phase 15 — Linear Data Import Connector (v0.8.2)

Real-world project data import from Linear. First connector to import graph-native project management data (issues, projects, cycles, teams, users, labels, workflow states) with full relationship fidelity.

What was built

Linear connector

• linear_connector.py implementing BaseConnector ABC with GraphQL client

• Cursor-based pagination against Linear's GraphQL API (https://api.linear.app/graphql)

• Rate limiting via X-RateLimit-Requests-Remaining header with adaptive sleep

• 8 entity types mapped to POLE+O model (Issue, Project, Cycle, Team, Person, Label, WorkflowState, Comment)

• 16 relationship types (ASSIGNED_TO, CREATED_BY, BELONGS_TO_PROJECT, BELONGS_TO_TEAM, IN_CYCLE, HAS_STATE, HAS_LABEL, CHILD_OF, HAS_COMMENT, AUTHORED_BY, MEMBER_OF, LEADS, CONTRIBUTED_BY, CYCLE_FOR, STATE_OF)

• Issue descriptions exported as documents for RAG/vector search

• Deduplication of users, labels, and workflow states across paginated issue responses

• Optional comment import (gated behind include_comments kwarg)

• Team key filtering (--linear-team ENG imports only that team's data)

• No external dependency — uses urllib.request from stdlib

CLI integration

• --connector linear flag (works with existing --connector multiple=True pattern)

• --linear-api-key flag (envvar LINEAR_API_KEY)

• --linear-team flag (envvar LINEAR_TEAM) for team filtering

• Warning when --connector linear is used without an API key

Generated project integration

• linear_connector.py.j2 Jinja2 template for standalone connector in generated projects

• import_data.py.j2 updated with Linear credential wiring

• .env and .env.example templates include LINEAR_API_KEY and LINEAR_TEAM (conditional)

• config.py.j2 includes linear_api_key and linear_team settings fields (conditional)

Tests added (14 new → 705 total)

• test_credential_prompts — verify api_key and team_key prompts

• test_authenticate_success/missing_key/invalid_key — auth validation

• test_fetch_entity_mapping — verify all 7 entity labels present

• test_fetch_entity_counts — correct counts for mocked workspace

• test_fetch_relationships — verify all relationship types

• test_fetch_child_of_relationship — sub-issue hierarchy

• test_fetch_documents — issue descriptions as documents

• test_fetch_deduplication — users/labels not duplicated

• test_fetch_team_filter/team_filter_not_found — team key filtering

• test_issue_name_format — "ENG-101 Fix login bug" format

• test_priority_labels — priority mapping (0-4 → human-readable)

Files created

• src/create_context_graph/connectors/linear_connector.py

• src/create_context_graph/templates/backend/connectors/linear_connector.py.j2

Files modified

• src/create_context_graph/connectors/__init__.py — register LinearConnector

• src/create_context_graph/cli.py — --linear-api-key, --linear-team flags + credential wiring

• src/create_context_graph/renderer.py — add linear to connector_templates

• src/create_context_graph/templates/backend/connectors/import_data.py.j2 — Linear block

• src/create_context_graph/templates/base/dot_env.j2 — conditional Linear env vars

• src/create_context_graph/templates/base/dot_env_example.j2 — Linear env vars with docs

• src/create_context_graph/templates/backend/shared/config.py.j2 — Linear settings fields

• tests/test_connectors.py — 14 new tests, registry counts 7→8

Phase 15b — Linear Deep Graph: Relations, History, Decisions & Full Schema (v0.8.3)

Schema introspection of Linear's GraphQL API (494 types) revealed significant additional data available beyond the initial v1 import. This phase adds issue relations (blocking/dependency graph), issue history transformed into decision traces, threaded comments with resolution tracking, project updates with health, milestones, initiatives, attachments, and Linear Docs.

Issue Relations — blocking/dependency graph (P0)

• Import issue.relations connection with type field (blocks, is-blocked-by, related, duplicate)

• New relationship types: :BLOCKS, :BLOCKED_BY, :RELATED_TO, :DUPLICATE_OF between Issue nodes

• Also import inverseRelations for bidirectional coverage

• Enables "what's blocking X?" and dependency chain queries

Issue History → Decision Traces (P0)

• Import issue.history connection: state transitions, assignee changes, priority changes, label changes, cycle/project moves

• Transform history entries into :DecisionTrace → :HAS_STEP → :TraceStep chains

• Each issue with 2+ history entries generates a decision trace with:

  • task: "Lifecycle of {identifier} {title}"

  • outcome: derived from final state (completed/canceled/current state)

  • Steps: each history entry becomes a TraceStep with thought/action/observation derived from the transition fields

• :TraceStep nodes linked to :Person via :PERFORMED_BY for actor attribution

Comment Threading & Resolution (P1)

• Import comment parent field for thread hierarchy: (:Comment)-[:REPLY_TO]->(:Comment)

• Import resolvedAt and resolvingUser: (:Comment)-[:RESOLVED_BY]->(:Person)

• Import comments on ProjectUpdates, not just Issues: (:ProjectUpdate)-[:HAS_COMMENT]->(:Comment)

• Import quotedText for context on replies

• Comments always imported (remove include_comments gate — comments are core to decision traces)

Project Updates & Health (P1)

• New entity: ProjectUpdate with body, health (onTrack/atRisk/offTrack), createdAt

• Relationships: (:Project)-[:HAS_UPDATE]->(:ProjectUpdate), (:ProjectUpdate)-[:POSTED_BY]->(:Person)

• Project updates with health changes generate decision trace steps

• Update bodies imported as documents for RAG

Project Milestones (P1)

• New entity: ProjectMilestone with name, description, targetDate, status, progress

• Relationships: (:Project)-[:HAS_MILESTONE]->(:ProjectMilestone), (:Issue)-[:IN_MILESTONE]->(:ProjectMilestone)

• Query issue.projectMilestone field for issue→milestone linking

Initiative Hierarchy (P2)

• New entity: Initiative with name, description, status (Planned/Active/Completed), health, targetDate, owner

• Relationships: (:Initiative)-[:CONTAINS_PROJECT]->(:Project), (:Initiative)-[:OWNED_BY]->(:Person)

• Query projects.initiatives connection for initiative→project linking

Attachments — External Links (P2)

• New entity: Attachment with title, url, sourceType, metadata

• Relationship: (:Issue)-[:HAS_ATTACHMENT]->(:Attachment)

• Enables cross-tool graph (GitHub PRs, Figma files, Slack messages linked to issues)

Linear Docs (P2)

• Query documents connection on Issue, Project, Cycle

• Import as :Document nodes (same as our existing document model)

• Links: (:Issue)-[:HAS_DOCUMENT]->(:Document), (:Project)-[:HAS_DOCUMENT]->(:Document)

Additional Issue Fields

• Add completedAt, canceledAt, startedAt timestamps for lifecycle tracking

• Add branchName for Git branch linking

• Add number (team-scoped numeric ID)

• Add trashed boolean for soft-delete awareness

Tests added (36 new → 741 total)

Unit tests in test_connectors.py (+22 Linear tests, 59 total)

• History transform edge cases: priority changes, label changes, reassignment, system actor, combined changes

• Pagination: multi-page cursor-based pagination verification

• Error handling: HTTP 401 → ValueError, HTTP 500 → RuntimeError, empty workspace

• Data integrity: all relationships have required keys, entity labels match relationship labels

• Constants: RELATION_TYPE_MAP completeness, PRIORITY_LABELS completeness

• Entity/relationship tests for all new types: relations, comments, threading, resolution, milestones, updates, initiatives, attachments, Linear Docs

CLI integration tests in test_cli.py (+12 tests, TestLinearConnectorCLI)

• Dry-run, warning without key, file generation, .env vars, .env.example, config settings

• import_data.py script content, API key flag, team flag, template compilation

• Multi-connector combination (linear + github)

Files modified

• src/create_context_graph/connectors/linear_connector.py — all new entities, relations, history→trace transform

• src/create_context_graph/templates/backend/connectors/linear_connector.py.j2 — matching template

• tests/test_connectors.py — 22 new Linear tests (59 total)

• tests/test_cli.py — 12 new Linear CLI integration tests

Phase 16 — Linear Connector Hardening & Test Suite Expansion (v0.8.3)

Linear connector improvements (10 improvements)

• Named constants: 18 constants replacing hardcoded page sizes, rate limits, retry counts (ISSUES_PAGE_SIZE, MAX_PAGES, RATE_LIMIT_THRESHOLD, MAX_RETRIES, etc.)

• Structured logging: logging.getLogger(__name__) with info/debug/warning/error throughout (auth, fetch summary, rate limits, pagination, truncation)

• Error handling: URLError (network), JSONDecodeError (malformed response), GraphQL-level errors field (logged as warning, data still returned)

• Pagination safety: max_pages parameter prevents infinite loops; null-safe data traversal with (x or {}) pattern

• Rate limit 429: _retry_on_rate_limit() method with exponential backoff up to MAX_RETRIES attempts

• Null safety: _safe_nodes() helper extracts connection nodes from fields that might be None; applied throughout fetch()

• History/comment limits: Comments increased from 20 → 100, history from 15 → 50; pageInfo { hasNextPage } with truncation warnings

• Team key validation: authenticate() validates team_key against available teams, lists available keys on mismatch

• Incremental sync: fetch(updated_after="ISO8601") adds updatedAt: { gt: ... } filter to issue queries

• Template parity: _describe_history_step() and decision trace generation ported to linear_connector.py.j2

CLI fix

• Optional credential prompts no longer abort the wizard when left blank (Linear team key)

Test suite expansion (5 new test files, 133 new tests → 874 passing, 1,084 collected)

tests/test_security.py (84 tests) — Cypher injection prevention

• Agent tool Cypher parameterization across all 22 domains ($param placeholders, no string literals in WHERE)

• Domain scoping verification ($domain reference in queries)

• Generated code static analysis: execute_cypher uses driver parameterization, no f-string user input, max_length on request models, GDS label validation

• run_cypher tool safety across 4 frameworks: JSON parameter parsing, param passthrough, domain default

tests/test_doc_snippets.py (8 tests) — Documentation validation

• YAML ontology examples from docs parse correctly (bookstore example, customizing tutorial)

• CLI flags documented in cli-options.md exist in Click command

• Cypher snippets from Linear tutorial have valid structure (MATCH/RETURN)

• Make targets referenced in docs exist in Makefile template

• Environment variable names in docs match .env.example template

tests/test_frontend_logic.py (23 tests) — SSE parsing & contract

• Python SSE event parser: all 6 event types, multi-event streams, malformed JSON

• Thinking/response splitting: THINKING_PATTERNS, CONTINUATION_PATTERNS, markdown breaks, error bypass

• Backend/frontend event type contract: routes.py.j2 emits same events ChatInterface.tsx.j2 handles

• Generated frontend structure: all event handlers, schema view mode, AbortController

tests/test_integration.py (7 tests, @pytest.mark.integration) — Neo4j database

• Schema DDL execution: constraints and indexes apply without error

• Fixture ingestion: entity counts, document nodes, relationships created

• Agent tool queries execute against seeded data without errors

• Domain scoping: two domains in same database, filter isolates correctly

tests/test_generated_tests.py (5 tests, @pytest.mark.slow) — Generated project tests

• Scaffolded project test discovery: pytest --collect-only finds test_health and test_scenarios

• Generated tests pass with mocked Neo4j for 4 frameworks (pydanticai, claude-agent-sdk, langgraph, anthropic-tools)

Linear connector tests (test_connectors.py +18, test_cli.py +1)

• Error handling: URLError, JSONDecodeError, GraphQL errors logged

• Team validation: valid key succeeds, invalid key lists available keys

• Pagination safety: max_pages limit stops infinite loops

• Null safety: all sub-objects None doesn't crash

• Truncation warnings: comments/history hasNextPage logged

• Logging: auth success, fetch summary

• Rate limit: 429 retry succeeds, 429 exhausts retries

• Incremental sync: updated_after filter in query, absent when not provided

• _safe_nodes helper

• Template has decision traces

CI changes

• Integration tests (--integration) run in smoke-test job before E2E tests, using same Neo4j credentials

• pyproject.toml: added integration marker

• conftest.py: added --integration flag with auto-skip

Files created

• tests/test_security.py

• tests/test_doc_snippets.py

• tests/test_frontend_logic.py

• tests/test_integration.py

• tests/test_generated_tests.py

Files modified

• src/create_context_graph/connectors/linear_connector.py — all 10 improvements

• src/create_context_graph/templates/backend/connectors/linear_connector.py.j2 — template parity

• src/create_context_graph/wizard.py — optional credential prompt fix

• tests/test_connectors.py — 18 new Linear tests (79 total)

• tests/test_cli.py — 1 new template test (34 total)

• tests/conftest.py — integration marker support

• pyproject.toml — integration marker registration

• .github/workflows/ci.yml — integration tests in smoke-test job

Phase 16b — Google Workspace Connector: Decision Trace Extraction (v0.8.4)

What was built

Google Workspace connector (google-workspace)

• New connector importing from 6 Google APIs: Drive Files, Drive Comments, Drive Revisions, Drive Activity, Calendar (optional), Gmail (optional)

• Decision trace extraction: Resolved comment threads in Google Docs become DecisionThread graph nodes with content, quotedContent, resolution, resolved status, and participant count — the core innovation

• Each resolved thread generates a decision trace (thought/action/observation steps) in the same format used by neo4j-agent-memory

• Unresolved threads become queryable DecisionThread nodes with resolved: false for the open_questions tool

• Reply entities for each response in a thread, linked via HAS_REPLY with AUTHORED_BY

• Revision entities tracking document evolution via HAS_REVISION and REVISED_BY

• Activity entities from Drive Activity API v2 with action type mapping (create, edit, move, rename, delete, etc.)

• Meeting entities from Calendar API (when --gws-include-calendar) with ATTENDEE_OF, ORGANIZED_BY, and DISCUSSED_IN (document-meeting linking via Drive URL detection)

• EmailThread entities from Gmail API (when --gws-include-gmail) with metadata only (no body text for privacy) and THREAD_ABOUT linking

• Cross-connector linking: Scans comment bodies, doc names, email subjects, meeting descriptions for Linear issue references (ENG-123 pattern) creating RELATES_TO_ISSUE relationships

• OAuth2 authentication with dynamic scope building based on enabled features, gws CLI preferred with Python OAuth2 fallback

• Rate limiting: 950 queries/100s sliding window with exponential backoff (5 retries, max 60s)

• Person deduplication by email across all sub-fetchers

CLI integration

• 9 new --gws-* CLI flags: --gws-folder-id, --gws-include-comments/--gws-no-comments, --gws-include-revisions/--gws-no-revisions, --gws-include-activity/--gws-no-activity, --gws-include-calendar, --gws-include-gmail, --gws-since, --gws-mime-types, --gws-max-files

• Credential passing via config.saas_credentials["google-workspace"] dict

• Updated --connector help text to include google-workspace

Agent tools

• 10 decision-focused tools injected via renderer when connector is active: find_decisions, decision_context, who_decided, document_timeline, open_questions, meeting_decisions, knowledge_contributors, trace_decision_to_source, stale_documents, cross_reference

• System prompt augmented with Google Workspace decision context description

• Tools use Cypher queries traversing DecisionThread, Reply, Revision, Activity, Meeting, EmailThread nodes

Generated project integration

• Scaffold template: google_workspace_connector.py.j2 with full parity — all 7 stages (Files, Comments/Decision Traces, Revisions, Activity, Calendar, Gmail, Cross-references) using OAuth2 only (no gws CLI fallback)

• import_data.py.j2 updated with google-workspace dispatch case

• .env and .env.example templates add GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GWS_FOLDER_ID

• Renderer connector_templates mapping updated

Documentation (3 new pages, 3 updated)

• Tutorial: "Decision Traces from Google Workspace" — step-by-step OAuth setup, scaffold, seed, explore, 10 example agent questions, 7 Cypher queries, combining with Linear

• Explanation: "How Decision Traces Are Extracted" — conceptual guide to comment thread classification, resolution detection, cross-connector linking, graph vs RAG comparison

• Reference: "Google Workspace Graph Schema" — complete node labels, relationships, properties, agent tools, cross-connector patterns

• Updated: import-saas-data.md (how-to), cli-options.md (reference), sidebars.ts (navigation)

Tests added (36 new)

Unit tests in test_connectors.py (+28 Google Workspace tests)

• Registration & metadata (3): connector registered, credential prompts with/without gws CLI

• Authentication (3): missing creds, gws path, flag parsing

• File fetching (3): basic files, relationships, documents

• Comment threads (4): decision threads, replies, resolved→trace, unresolved→no trace

• Comment relationships (1): HAS_COMMENT_THREAD, HAS_REPLY, AUTHORED_BY, RESOLVED_BY

• Revisions (1): entities and relationships

• Activity (1): entities, action types, relationships

• Calendar (2): disabled by default, enabled with attendees/document linking

• Gmail (2): disabled by default, enabled with participants/document linking

• Cross-connector (2): Linear refs detected, no false positives

• Integrity (2): person deduplication, relationship required keys

• Integration (1): full pipeline with all features

• Edge cases (2): empty workspace, comments disabled

CLI integration tests in test_cli.py (+8 tests, TestGoogleWorkspaceConnectorCLI)

• Dry run output, generated files, .env vars, .env.example, import script, template compilation, all flags accepted, combined with Linear

Files created

• src/create_context_graph/connectors/google_workspace_connector.py — core connector (~1,400 lines)

• src/create_context_graph/templates/backend/connectors/google_workspace_connector.py.j2 — scaffold template

• docs/docs/tutorials/google-workspace-decisions.md — tutorial

• docs/docs/explanation/how-decision-traces-work.md — conceptual explainer

• docs/docs/reference/google-workspace-schema.md — schema reference

Files modified

• src/create_context_graph/connectors/__init__.py — register GoogleWorkspaceConnector

• src/create_context_graph/cli.py — 9 new --gws-* flags, credential passing block

• src/create_context_graph/renderer.py — connector template mapping, 10 GWS agent tools, system prompt augmentation

• src/create_context_graph/templates/backend/connectors/import_data.py.j2 — google-workspace dispatch

• src/create_context_graph/templates/base/dot_env.j2 — GWS env vars

• src/create_context_graph/templates/base/dot_env_example.j2 — GWS env var docs

• tests/test_connectors.py — 28 new tests, registry count updated to 9

• tests/test_cli.py — 8 new GWS CLI tests

• docs/sidebars.ts — 3 new pages in navigation

• docs/docs/how-to/import-saas-data.md — Google Workspace section

• docs/docs/reference/cli-options.md — 9 new --gws-* flags

Phase 17 — Claude Code Session History Connector (v0.9.0)

What was built

Claude Code connector (claude-code)

• New connector importing local Claude Code session JSONL files from ~/.claude/projects/ — no authentication or API keys required

• Parses user/assistant messages, tool_use/tool_result blocks, and progress entries from session JSONL files

• Extracts 7 entity types: Project, Session, Message, ToolCall, File, GitBranch, Error

• 10 relationship types: HAS_SESSION, HAS_MESSAGE, NEXT, USED_TOOL, MODIFIED_FILE, READ_FILE, PRECEDED_BY, ON_BRANCH, ENCOUNTERED_ERROR, RESOLVED_BY

• Heuristic decision extraction (4 signal types):

  • User corrections ("no, instead use X") → Decision with rejected/chosen alternatives

  • Deliberation markers ("should we", "alternatively", "trade-off") → Decision with discussion context

  • Error-resolution cycles (tool error → corrective tool calls) → Decision with error context

  • Dependency changes (pip install, npm install, etc.) → Dependency decisions

• Preference extraction from explicit statements ("always use X", "prefer Y over Z") and package install frequency across sessions

• Secret redaction by default: API keys (sk-ant-*, ghp_*, xoxb-*, AKIA*), tokens, passwords, connection strings replaced with [REDACTED]

• Content truncation modes: truncated (2000 chars, default), full, none (metadata only)

• Token usage tracking from assistant message usage fields

• File deduplication across sessions with modification/read counts

• Implementation split into main connector + _claude_code/ subpackage (parser.py, redactor.py, decision_extractor.py, preference_extractor.py)

CLI integration

• 5 new --claude-code-* CLI flags: --claude-code-scope (current/all), --claude-code-project, --claude-code-since, --claude-code-max-sessions, --claude-code-content

• Credential passing via config.saas_credentials["claude-code"] dict

• Updated --connector help text to include claude-code

Agent tools

• 8 session intelligence tools injected via renderer when connector is active: search_sessions, decision_history, file_timeline, error_patterns, tool_usage_stats, my_preferences, project_overview, reasoning_trace

• System prompt augmented with Claude Code session context description

• Tools use Cypher queries traversing Session, Message, ToolCall, Decision, Preference, File, Error nodes

Generated project integration

• Scaffold template: claude_code_connector.py.j2 — simplified standalone parser for re-importing sessions from generated projects

• import_data.py.j2 updated with claude-code dispatch case

• Renderer connector_templates mapping updated

Documentation (2 new pages, 4 updated)

• Tutorial: "Build a Developer Knowledge Graph from Claude Code Sessions" — step-by-step guide: prerequisites, scaffold, seed, explore, decision extraction, preferences, Cypher queries, combining with other connectors, privacy/security

• Reference: "Claude Code Session Schema" — complete entity types, relationships, decision categories, preference categories, agent tools, redaction patterns, example Cypher

• Updated: import-saas-data.md (how-to), cli-options.md (reference), intro.md, sidebars.ts (navigation)

Tests added (45 new → 955 passing, 1,165 collected)

Unit tests in test_connectors.py (+38 Claude Code tests)

• Registration & metadata (4): connector registered, get_connector, empty credential prompts, listed in connectors

• Parser / discovery (8): discover projects, empty projects, discover sessions, max sessions, parse basic, parse tool calls, files tracked, skips meta, progress counted, malformed lines

• Connector fetch (8): returns NormalizedData, entity types, relationships, file relationships, file deduplication, git branch, documents, token usage

• Content modes (3): truncation, mode none, mode full

• Scope/filtering (3): scope all, project filter, empty directory

• Secret redaction (6): redact API keys, GitHub tokens, passwords, connection strings, empty strings, fetch redacts content

• Error extraction (1): errors from is_error tool_results

• Decision extraction (2): user correction detected, error-resolution cycle detected

• Preference extraction (1): explicit statement detected

CLI integration tests in test_cli.py (+7 tests, TestClaudeCodeConnectorCLI)

• Dry run output, generated files, import data includes connector, scope flag, all flags accepted, combined with other connector, agent tools injected

Files created

• src/create_context_graph/connectors/_claude_code/__init__.py — package init

• src/create_context_graph/connectors/_claude_code/parser.py — JSONL parsing, project/session discovery (~350 lines)

• src/create_context_graph/connectors/_claude_code/redactor.py — secret detection and redaction (~70 lines)

• src/create_context_graph/connectors/_claude_code/decision_extractor.py — heuristic decision extraction (~350 lines)

• src/create_context_graph/connectors/_claude_code/preference_extractor.py — preference pattern detection (~170 lines)

• src/create_context_graph/connectors/claude_code_connector.py — main connector (~380 lines)

• src/create_context_graph/templates/backend/connectors/claude_code_connector.py.j2 — scaffold template

• docs/docs/tutorials/claude-code-sessions.md — tutorial

• docs/docs/reference/claude-code-schema.md — schema reference

Files modified

• src/create_context_graph/connectors/__init__.py — register ClaudeCodeConnector (10th connector)

• src/create_context_graph/cli.py — 5 new --claude-code-* flags, credential passing block

• src/create_context_graph/renderer.py — connector template mapping, 8 Claude Code agent tools (_CLAUDE_CODE_AGENT_TOOLS), system prompt augmentation

• src/create_context_graph/templates/backend/connectors/import_data.py.j2 — claude-code dispatch

• tests/test_connectors.py — 38 new tests, registry count updated to 10

• tests/test_cli.py — 7 new Claude Code CLI tests

• docs/sidebars.ts — 2 new pages in navigation

• docs/docs/intro.md — updated connector list

• docs/docs/how-to/import-saas-data.md — Claude Code connector section

• docs/docs/reference/cli-options.md — 5 new --claude-code-* flags

• README.md — connector table, CLI reference, Claude Code description

• CLAUDE.md — connector count, test counts, connector table, description

Phase 18 — Chat History Import: Claude AI & ChatGPT (v0.10.0)

What was built

Claude AI connector (claude-ai)

• New connector importing conversations from Claude AI data exports (Settings > Account > Export Data)

• Parses conversations.jsonl from .zip or raw .jsonl file — streaming line-by-line for memory efficiency on large exports (1GB+)

• Extracts content from structured content blocks: text, tool_use, tool_result, thinking

• Normalizes sender values (human → user, assistant → assistant)

• Creates Conversation entities with title, UUID, timestamps, message count

• Creates Message entities with role, content (truncated to 2000 chars), timestamps, tool call metadata

• Generates Document per conversation with full concatenated text for search/RAG

• Deep mode extracts DecisionTrace nodes from tool call sequences

• All processing is local — no API keys required, no data sent externally

ChatGPT connector (chatgpt)

• New connector importing conversations from ChatGPT data exports (Settings > Data Controls > Export Data)

• Parses conversations.json from .zip or raw .json file — handles the tree-structured mapping field

• Tree walking algorithm: finds root nodes, traverses depth-first following last child at branch points to reconstruct linear conversation path

• Filters out system role messages and messages with is_visually_hidden_from_conversation: true

• Converts Unix float timestamps to ISO 8601

• Handles content_type variants: text, code, execution_output, multimodal_text

• Tool-role messages (author.role = "tool") captured with execution_output content as tool results

• Same entity schema as Claude AI: Conversation, Message, Document, DecisionTrace (deep mode)

Shared infrastructure (_chat_import/)

• models.py — ParsedConversation and ParsedMessage dataclasses shared by both parsers

• zip_reader.py — Zip extraction, format auto-detection (looks for conversations.jsonl vs conversations.json), streaming JSONL reader, JSON array reader, malformed line handling

• All stdlib — no new dependencies (json, zipfile, io, re)

CLI integration

• 7 new --import-* CLI flags: --import-type (claude-ai/chatgpt), --import-file, --import-depth (fast/deep), --import-filter-after, --import-filter-before, --import-filter-title, --import-max-conversations

• Validation: --import-type and --import-file must be provided together

• Auto-adds import type to config.saas_connectors — flows through existing connector pipeline

• Credential wiring: file path + filter options passed via config.saas_credentials[import_type]

Documentation (2 new pages, 4 updated)

• Tutorial: "Import Your AI Chat History into a Context Graph" — step-by-step: how to export from Claude AI and ChatGPT, scaffold with import flags, customize with filters, explore in frontend and Neo4j Browser, example Cypher queries, privacy notes, combining with other connectors

• Reference: "Chat Import Schema" — complete entity types, relationships, platform differences, example Cypher queries

• Updated: import-saas-data.md (how-to), cli-options.md (reference), sidebars.ts (navigation)

Tests added (78 new → 1033 passing, 1243 collected)

tests/test_chat_import.py (78 tests)

• Zip reader (13): format auto-detection for zip/jsonl/json, unknown extensions, missing known files, JSONL streaming from zip and raw files, malformed line skipping, empty line handling, JSON reading from zip and raw files, non-array JSON rejection

• Claude AI parser (15): single/multi conversation, zip support, message parsing, sender normalization, content block extraction (text/tool_use/tool_result/thinking), timestamp parsing, date filtering (after/before), title filtering (regex), max conversations limit, malformed conversation skip, empty conversations, text fallback, metadata

• ChatGPT parser (14): single conversation, zip support, system message filtering, message content, Unix timestamp conversion, branching (follows last child), hidden message filtering, tool-role messages, date filtering, title filtering, max conversations, null message nodes, empty mapping, model slug metadata, malformed skip

• Claude AI connector (15): registration, service name, credential prompts, authenticate with file path, file not found, wrong extension, fetch returns NormalizedData, entity properties, relationships (HAS_MESSAGE/NEXT), documents, empty file, multiple conversations, filters, deep mode traces, fast mode no traces

• ChatGPT connector (15): registration, service name, credential prompts, authenticate with file path, file not found, wrong extension, fetch returns NormalizedData, entity properties, relationships, documents, empty file, branching conversation, hidden messages excluded, tool messages, filters, deep mode traces, fast mode no traces

• CLI (3): import-type without file fails, import-file without type fails, dry-run with import flags

Files created

• src/create_context_graph/connectors/_chat_import/__init__.py — shared package init

• src/create_context_graph/connectors/_chat_import/models.py — ParsedConversation, ParsedMessage dataclasses

• src/create_context_graph/connectors/_chat_import/zip_reader.py — zip extraction, format detection, streaming JSONL (~130 lines)

• src/create_context_graph/connectors/_claude_ai/__init__.py — parser package init

• src/create_context_graph/connectors/_claude_ai/parser.py — JSONL streaming parser with content block extraction (~180 lines)

• src/create_context_graph/connectors/_chatgpt/__init__.py — parser package init

• src/create_context_graph/connectors/_chatgpt/parser.py — JSON tree-walker parser (~200 lines)

• src/create_context_graph/connectors/claude_ai_connector.py — Claude AI connector (~220 lines)

• src/create_context_graph/connectors/chatgpt_connector.py — ChatGPT connector (~220 lines)

• tests/test_chat_import.py — 78 tests (~650 lines)

• docs/docs/tutorials/import-chat-history.md — tutorial

• docs/docs/reference/chat-import-schema.md — schema reference

Files modified

• src/create_context_graph/connectors/__init__.py — register ClaudeAIConnector, ChatGPTConnector (12 connectors total)

• src/create_context_graph/cli.py — 7 new --import-* flags, validation, credential wiring

• tests/test_connectors.py — registry count updated to 12, expected connectors set expanded

• docs/sidebars.ts — 2 new pages in navigation

• docs/docs/how-to/import-saas-data.md — Claude AI and ChatGPT connector sections, credential setup

• docs/docs/reference/cli-options.md — 8 new --import-* flags documented, chat import example

Suggested improvements (future phases)

Phase 18b — Standard-depth entity extraction

• LLM-powered entity extraction from conversation text (people, organizations, technologies, topics)

• Batched extraction with configurable concurrency and rate limiting

• Cross-conversation entity resolution (same entity mentioned in multiple conversations merged)

• --import-depth standard level between fast and deep

• ImportBatch provenance nodes tracking import source, timestamp, conversation count

• Progress bar with Rich showing conversations parsed, entities extracted, ETA

Phase 18c — Standalone import subcommand

• Convert CLI from @click.command() to @click.group() with backward-compatible default

• create-context-graph import claude-ai ~/Downloads/export.zip --neo4j-uri bolt://localhost:7687 — import directly into existing Neo4j without scaffolding a project

• --dry-run on the import subcommand to preview what would be imported

• Incremental re-import: skip unchanged conversations, update modified, add new (via originalPlatformId matching)

Phase 18d — Generated project templates & agent tools

• claude_ai_connector.py.j2 and chatgpt_connector.py.j2 scaffold templates

• import_data.py.j2 updated with claude-ai and chatgpt dispatch cases

• 6-8 agent tools for querying imported chat history: search_conversations, conversation_timeline, entity_mentions, topic_trends, tool_usage_history, conversation_summary

• System prompt augmented with chat history context

Phase 18e — Cross-platform entity resolution

• When importing from both Claude AI and ChatGPT, entities mentioned across platforms are merged

• Fuzzy name matching with configurable threshold (default 0.85 similarity)

• Property overlap detection (same email, URL, employer → merge)

• MERGED_FROM relationship tracking provenance

Additional future improvements

• Conversation branch import (ChatGPT): option to import all branches as separate conversation variants instead of just the main path

• Thinking block storage: Claude AI thinking blocks stored as reasoning memory nodes (configurable: raw vs. summarized)

• Privacy-preserving import: local entity extraction via spaCy/GLiNER instead of LLM, matching existing neo4j-agent-memory[spacy,gliner] extras

• MCP server surface: expose import capability through neo4j-agent-memory MCP server as an import tool

• Additional platforms: Google Gemini, Perplexity AI, GitHub Copilot Chat export import

• Import visualization: real-time graph building during import, before/after comparison, entity timeline view

Phase 19 — neo4j-agent-memory v0.1.0 Alignment: MemoryIntegration, MCP Server & Entity Extraction (v0.9.0)

MemoryIntegration migration

• Replaced MemoryClient with MemoryIntegration from neo4j-agent-memory v0.1.0

• New shared memory.py.j2 template generates backend/app/memory.py with connect_memory(), close_memory(), store_message(), get_context(), resolve_session_id()

• context_graph_client.py.j2 stripped of inline MemoryClient init (~60 lines removed), delegates to app.memory

• All 8 agent templates migrated from get_conversation_history()/store_message() to get_context()/store_message()/resolve_session_id() from app.memory

• get_context() returns rich context: messages + entities + preferences + traces (vs old simple message list)

• store_message() returns extraction results (entities, preferences) used for SSE events

• Graceful degradation preserved: ImportError catch if neo4j-agent-memory not installed

• pyproject.toml.j2 bumped to neo4j-agent-memory[spacy,gliner]>=0.1.0