KAVACHKAVACH
v2.0.3

Neo4j Operations

Operate Kavach’s durable Neo4j ontology projection without treating the graph as the source of truth.

Overview

Kavach projects authoritative governance state into Neo4j for lineage, evidence traversal, and explainable decisions. Domain repositories remain the systems of record; the graph is an idempotent, eventually consistent projection maintained by the ontology synchronization worker.

Projection events, MCP execution audit records, and worker activity are persisted durably. This gives operators one recovery path: inspect the event, correct the underlying issue, and explicitly retry it.

Run the Stack

The supported scripts start Neo4j, initialize its schema, start the API and worker, and make Studio available for inspection.

bash
./scripts/keycloak/start-keycloak.sh
./kavach.sh

For a Docker-only workflow, use ./kavach-local.sh. Thekavach-neo4j-schema service applies constraints and indexes before the application services depend on the graph. If needed, initialize the schema manually:

bash
uv run python -m kavach.ontology.cli initialize-schema

Seeded data is safe to run repeatedly because graph writes use upsert semantics:

bash
curl -X POST http://localhost:8000/api/v1/ontology/demo/seed

Observe Synchronization

In Kavach Studio, Home reports the Neo4j graph-store connection and live projection counts. Use Sync Events to review the event stream. The event list is the operational source for queued work, processing state, completed projections, and failures.

  • PENDING — accepted and awaiting worker pickup.
  • PROCESSING — currently being reconciled.
  • COMPLETED — projection converged successfully.
  • FAILED — a retryable attempt failed.
  • DEAD_LETTER — automatic attempts are exhausted and operator review is required.
  • CANCELLED — deliberately stopped and retained for history.

Dead letters are not an outage

A dead-letter event means one projection needs attention. Worker health and graph availability are reported separately so an isolated data issue does not look like the synchronizer is unavailable.

Recover Dead Letters

  1. Open the event in Studio and review its failure message, payload, retry count, and reconciliation metadata.
  2. Correct the source data or contract issue that caused the failure.
  3. Select Retry event to explicitly requeue it.
  4. Refresh the event after the worker processes it and confirm COMPLETED.

Retrying invokes reconciliation rather than blindly appending data. Repeated delivery therefore upserts the same projection and repairs only detected semantic drift.

Verify the Graph

Use Neo4j Browser to check the active projection without mutating it:

cypher
MATCH (n:OntologyEntity)
WHERE coalesce(n.isDeleted, false) = false
RETURN n.entity_type AS type, count(*) AS liveNodes
ORDER BY liveNodes DESC

MATCH ()-[r:ONTOLOGY_RELATIONSHIP]->()
WHERE coalesce(r.isDeleted, false) = false
RETURN r.relationship_type AS type, count(*) AS liveRelationships
ORDER BY liveRelationships DESC

Deletes are soft deletes. Kavach preserves the node and relationship history with an isDeleted flag while keeping it out of the live path.

Test the Integration

bash
KAVACH_RUN_NEO4J_TESTS=true \
  KAVACH_GRAPH_URI=bolt://localhost:7687 \
  uv run pytest tests/integration/ontology tests/integration/ontology_sync

uv run python smoke_tests/smoke_neo4j_evaluation_result_sync.py

Keep the in-memory graph repository for fast unit tests. Use the Neo4j integration suite and smoke test to validate schema, persistence, worker, and end-to-end projection behavior together.