create-context-graph CLAUDE.md

CLAUDE.md — Create Context Graph

Project Overview

Interactive CLI scaffolding tool that generates domain-specific context graph applications. Like create-next-app but for AI agents with graph memory. Invoked via uvx create-context-graph or npx create-context-graph.

Given a domain (e.g., "healthcare", "wildlife-management") and an agent framework (e.g., PydanticAI, Claude Agent SDK), it generates a complete full-stack application: FastAPI backend, Next.js + Chakra UI v3 + NVL frontend, Neo4j schema, synthetic data, and a configured AI agent with domain-specific tools.

Status: v0.14.0. Community PR hardening release — integrates PRs #52/#56/#58/#59/#60, closes the gaps found reviewing them, and fixes five breaks found by live-testing the full NAMS flow against the production service with neo4j-agent-memory 0.5.0: (1) conversation memory was silently failing on every message — the NAMS service only accepts messages addressed to conversation ids IT minted, so generated memory.py now creates conversations per session and targets the server id (_resolve_nams_conversation()), and store_message() treats MemoryIntegration's swallowed {"error": ...} returns as failures; (2) every document/body ingest write failed (role="document" rejected — only user/assistant/system allowed — plus the conversation-404), fixed across all three NAMS ingest implementations (run_nams_ingest, scaffolded import_data.py, make seed's ingest_fixtures_nams) with role="user" + metadata.kind markers and server-created channels; (3) /api/documents and /api/schema/visualization returned nothing (the live service coerces OBJECT/EVENT entity types to custom and rejects empty search queries) — both adapters are now cypher-first via the _pole_type: OBJECT_ description marker / type-count aggregation with search fallbacks; (4) graph expand + entity connections were dead (long_term.get_entity(id) doesn't exist in 0.5.x) — expand_node_nams/get_entity_detail_nams resolve through the cypher API; (5) NAMS reset never deleted anything (delete_entity doesn't exist upstream; the old loop swallowed the AttributeError and printed "0 removed") — --reset-database and make reset now honestly report that no delete API exists and point at the NAMS dashboard. NAMS domain ontology activation (new): NAMS pre-registers a server-side ontology for every bundled domain but auto-binds workspaces to nams-default until one is activated — generated apps now bind on connect_memory() (activate catalog match by domain id, or create-from-backend/app/ontology_document.json + activate for custom domains, best-effort via _ensure_nams_ontology()), the CLI ingest and scaffolded import_data.py run the same stage-0 sequence (parity-pinned), and build_nams_ontology_document() in ontology.py produces the server document shape ({domain, entity_types, relationships}) used by the renderer and ingest; verified live — workspace flips nams-default→healthcare on first connect, custom test-domain creates+activates server-side; stored entity type still coerces to {Person,Organization,Location,custom} server-side regardless (activation governs version stamp + extraction vocabulary). Verified live: 19/19 API checks, clean document ingest, working chat-memory writes, cypher reads (writes rejected server-side), trace ingest OK (list_traces NotSupported → /traces degrades to empty), and add_relationship still NotSupported so ccg-edges remains the design. New --neo4j-database / NEO4J_DATABASE for the self-hosted backend, threaded end-to-end: CLI flag, wizard prompt, Aura .env import (explicit flag wins), generated .env + .env.example, Settings.neo4j_database, MemorySettings (key omitted when blank so the SDK default neo4j applies), execute_cypher() sessions, scaffold-time ingest.py (_ingest_with_memory_client/_ingest_with_driver/reset_neo4j), the scaffolded import_data.py bolt session, and validate_connection(database=). Live memory-write failures now surface: store_message() records into the classified error state and the bolt /health gains memory/memory_error/memory_error_detail (startup lifecycle checks get_client() instead of assuming success). execute_cypher() dispatches to NAMS client.query.cypher (with _coerce_nams_records() shape coercion) so agent tools and POST /cypher work on the hosted backend; _require_neo4j() 503s when the NAMS client is missing. --ontology-file is implemented (was documented-only, issue #50): scaffolds from a hand-written YAML, copies it to data/ontology.yaml, mutually exclusive with --custom-domain, works through the wizard path too. load_domain() resolves custom domains from ~/.create-context-graph/custom-domains/ with a declared-domain.id fallback (issue #30); bundled domains shadow same-id customs; the test suite is hermetic against that directory via an autouse conftest fixture. Playwright spec template survives missing demo_scenarios AND a scenario with empty prompts. Schema-DDL splitter bug fixed: the old split(";") + skip-// pattern silently dropped 5 real statements behind comment headers (person_name, document_title, document_domain, document_name_unique, local_file_fulltext were never created by seeding) and executed a comment tail as Cypher; new shared split_cypher_statements() in ontology.py is used by ingest.py, the generated generate_data.py, and test_integration.py. New test surfaces: tests/test_generated_client_runtime.py (26 tests executing the rendered client/memory modules against doubles), +6 app-level route tests, +12 CLI tests, +5 wizard tests, +17 template pins, +9 ontology tests, +3 integration tests, generated test_routes.py gains 2 backend-specific /health tests, test_generated_tests.py runs one bolt scaffold, and e2e_smoke_test.py asserts the /health contract shape. Carry-forward from v0.13.1 (feedback-report triage): create-context-graph --dry-run no longer demands a NAMS API key (the credential gate is now scoped to non-dry-run flows in cli.py:392). Dead template_id parameter dropped from list_documents_nams (NAMS branch already raises 501). Generated Pydantic app/models.py now emits Field(...) for required fields instead of bare = ... Ellipsis literal. New GET /schema/models endpoint introspects app.models at runtime and returns the JSON Schema for each entity model — makes the previously-unused models.py load-bearing. Last key={\${e.name}-${i}`}site (DocumentBrowser mentioned-entities) replaced withkey={`${selectedDoc.document.title}-${e.name}`}. New regression tests (TestCompositeKeyRegressionsintest_frontend_logic.pyplusTestV0131ModelsPolishandTestV0131TemplateIdRemovalintest_generated_project.py) plus 3 new Playwright tests pin the v0.12.0/v0.13.0 fixes. The v0.13.0 report's claims about connector code being removed from scaffolded projects, pyproject.toml bloat on NAMS, and missing domains (media, insurance, supply-chain) were verified-false against current code — see CHANGELOG.md"Not Changed" section. **Carry-forward from v0.13.0 (v0.12.0 feedback-report fixes):** Fixed the bolt async/sync mismatch in the scaffoldedimport_data.py (ingest_via_bolt()isasync defand both call sites wrap withasyncio.run); ChatInterface stale-closure bug fixed by moving streamingEntities/streamingPreferencesto refs;list_documents_namspushes the OBJECT filter server-side;externalInputuseEffect depends onloading. Removed the --framework maf alias entirely (Click rejects with "Invalid value"). Restored 4 domains as YAML definitions (legal, education, cybersecurity, government); domain count is now 27. New Docusaurus page docs/docs/explanation/ccg-edges.mddocuments the relationship-encoding strategy. **Carry-forward from v0.12.0 (NAMS-native connector ingest release):** Default memory backend is the hosted Neo4j Agent Memory Service (NAMS,MEMORY_API_KEYenv), with--self-hostedpreserving the bolt-Neo4j path. **LiteLLM provider injection** for memory layer viaMEMORY_LLM/MEMORY_EMBEDDINGenv vars (LiteLLM-style strings) routes through native adapters when available, LiteLLM otherwise. Default framework is **AWS Strands**. Wizard collapsed from 11 prompts to 6 with autocomplete domain picker and a single "Customize advanced settings" gate. NAMS ingest now uses a **hybrid write shape**: entities viaadd_entitywith non-name properties markdown-serialized into thedescriptionfield; **outbound relationships encoded into the source entity'sdescriptionas a fenced ```ccg-edges``` YAML block** (sorted bytypethentarget) since NAMS REST has no add_relationshipyet — the frontend parses these out for the graph view, and a future migration will replay them as native edges; **documents dual-tracked** aslong_term.add_entity(type=OBJECT)(queryable source of truth, matches bolt:Documentshape) ANDshort_term.add_message(role="document")(extraction fuel); **entity bodies routed throughadd_message** when the connector declares a BODY_FIELDS: dict[label, property]map (e.g.Comment.bodyfor Linear,Message.contentfor Claude AI/ChatGPT/Claude Code,DecisionThread.content/Reply.contentfor Google Workspace,Document.description/Section.descriptionfor local-file); decision traces viareasoning.start_trace/add_step/complete_trace. Preferences and facts still unsupported by NAMS REST (logged-skipped). Schema DDL skipped on NAMS (server-owned). The two ingest consumers (src/create_context_graph/ingest.py run_nams_ingest()and the scaffoldedtemplates/backend/connectors/import_data.py.j2) share the same NAMS write sequence pinned by tests/test_nams_ingest_parity.py(~526 LOC contract test). Generatedimport_data.pyis **idempotent**: per-connector watermarks in.context-graph/watermarks.json(re-runs fetch deltas only), failures appended to.context-graph/deadletter.jsonl, new --dry-run(fetch only) and--retry(drain deadletter) modes, surfaced viamake import(fetch + ingest),make import-dry-run, make import-retry(the legacymake import-and-seedtarget is gone —make importis the single entrypoint)./documents?template_id=...returns HTTP 501 on NAMS (template filtering needsMENTIONSedges that NAMS doesn't have); un-filtered/documentsworks on both backends. Bolt ingest hardened withrequire_safe_cypher_identifier()(relationship types and labels validated against[A-Za-z][A-Za-z0-9]*before string interpolation) and labeledMATCH (a:SourceLabel)/MATCH (b:TargetLabel)(no more label-less fallback that could mis-merge).ingest_data()library entry point now accepts either aProjectConfigor the legacy(neo4j_uri, neo4j_username, neo4j_password) triple (v0.11.0 had broken legacy callers). Frontend routes (/expand, /documents, /traces, /schema/visualization, /entities/{name}, /search) dispatch through memory_adapter.pyon NAMS. MCP profile coerced tocoreon NAMS (extended-profile tools rely on unsupported endpoints).auto_preferencesforcedFalseon NAMS. Generatedpyproject.tomlpinsneo4j-agent-memory[litellm,sentence-transformers]>=0.4.0,<0.6.0; self-hosted scaffolds also pull [extraction,fuzzy]. 27 domains, 8 agent frameworks (7 working out of box — openai-agents requires OPENAI_API_KEY, google-adk requires GOOGLE_API_KEY with clear warnings), **streaming chat via Server-Sent Events** (token-by-token text in 6 frameworks + real-time tool call visualization with Timeline/Spinner/Collapsible + entities_extractedandpreferences_detected SSE events displayed as badges), neo4j-agent-memory v0.1.0 MemoryIntegration for multi-turn conversations with automatic entity extraction and preference detection (local sentence-transformers embeddings by default — no OpenAI key required; auto-upgrades to OpenAI embeddings if OPENAI_API_KEY is set), MCP server generation for Claude Desktop (--with-mcpflag,make mcp-server target, dual-interface architecture), configurable session strategies (per_conversation/per_day/persistentviaSESSION_STRATEGYenv var), interactive NVL graph visualization (schema view, double-click expand, drag/zoom, property panel, agent-driven graph updates — now updated incrementally during streaming, node hover tooltips, "Ask about this" button), LLM-generated demo data (80-90 entities, 25+ documents, 8-12 decision traces per domain) with post-generation value clamping for 28 property types, markdown rendering in chat and document browser with ReactMarkdown, document browser with pagination, entity detail panel, decision trace viewer, 13 SaaS connectors (including Linear for real project data import, Google Workspace for decision trace extraction from comment threads, Claude Code for local session history import with decision/preference extraction, Claude AI + ChatGPT for importing conversation exports from AI chat platforms, and local-file for deterministic ingestion of local Markdown / PDF / HTML / AsciiDoc / Word documents into Document → Section hierarchies), custom domain generation, Neo4j Aura .env import + neo4j-local support, Docusaurus documentation site (24 pages including quick-start, domain catalog, framework comparison, Neo4j Aura/Local guides, Docker guide, architecture diagram, "Why Context Graphs?" explainer, Google Workspace tutorial, decision trace explainer, GWS schema reference, chat history import tutorial, chat import schema reference, andccg-edgesencoding explainer), graceful Neo4j degradation with /health endpoint (retry with backoff on initial load) and 503 guards on all endpoints, Cypher injection prevention, enum identifier sanitization, configurable CORS/model/timeouts, --dry-run/--verbose/--reset-database/--demo CLI flags, CLI auto-slug generation (PROJECT_NAME optional in non-interactive mode), CLI warnings for framework-specific API key requirements (openai-agents, google-adk), constants module, WCAG accessibility improvements, chat timeout/cancel with AbortController, mobile-responsive layout, .dockerignore for Docker builds,make test-connectiontarget, framework-specific README sections, troubleshooting guide, thread-safe async bridging for sync frameworks (CrewAI/Strands), bounded agentic loops (max 15 iterations), domain-specific static name pools (1000+ names across 118 entity labels — all domain YAML labels covered) with domain-aware base entities, tool-use emphasis in all agent system prompts, domain-scoped chat history localStorage keys, SSR hydration fix, retry button on chat errors, PydanticAI tool serialization fix (JSON string return types), Google ADK API key support (--google-api-key flag) with AttributeError guard for SDK cleanup, Strands robust text extraction, CrewAI explicit Anthropic LLM config withcrewai[anthropic] dependency, domain-scoped MERGE keys ({name, domain}) for cross-domain isolation when sharing a Neo4j instance, improved static data quality (26 domain-specific industry pools, POLE-type-aware entity descriptions with 5 label categories + 7 label-specific overrides, entity-derived document titles, realistic decision trace observations, 20+ domain-specific property pools, float value clamping, taxonomy class correction), agent thinking text collapsible filter with continuation pattern support, Cypher query validation tests across all domains, fixture cross-validation tests (schema alignment + data quality), proper Document/DecisionTrace node ingestion via --ingest, Chakra UI Pro-inspired chat input redesign, list/get-by-id agent tools for all 27 domains (7-8+ tools per domain), ON CREATE/MATCH SET for constraint-safe seeding, hardened Linear connector (named constants, structured logging, URLError/JSONDecodeError/429 handling with retry, pagination safety limits, null-safe field access, team key validation in authenticate(), incremental sync via updated_after, decision traces in generated template), optional credential prompts in interactive wizard, Google Workspace connector with decision trace extraction from 6 Google APIs (Drive Files, Comments, Revisions, Activity, Calendar, Gmail) with 10 decision-focused agent tools and cross-connector Linear linking, scaffolded Claude Code connector with full entity extraction (9 entity types, 14 relationship types, secret redaction, decision/preference extraction, language detection), connector-specific demo scenarios, 1,454 passing tests in the fast suite; the full CI suite (dev+connectors extras, --slow --functional`) runs 1,866 passing / 1,881 collected.