# Kalika Knowledge Graph Deployment

Kalika uses Neo4j as the primary persistence backend for the theorem and concept
knowledge graph. Start it locally with the dedicated Docker `graph` profile:

```bash
docker compose -f docker/docker-compose.dev.yml --profile graph up -d neo4j
```

The profile runs Neo4j 5.26 Community with APOC enabled, default database
`kalika_knowledge`, and memory defaults sized for an approximately 10M node /
100M relationship graph:

- `KALIKA_NEO4J_MEM_LIMIT=24g`
- `KALIKA_NEO4J_HEAP_INITIAL=6G`
- `KALIKA_NEO4J_HEAP_MAX=8G`
- `KALIKA_NEO4J_PAGECACHE=12G`
- `KALIKA_NEO4J_TX_MEMORY_MAX=4G`

Use smaller values for laptop-only development. Keep the Neo4j version at 5.11+
because Kalika installs a theorem embedding vector index with
`CREATE VECTOR INDEX`.

The library backend resolver selects Neo4j when `COMPOSE_PROFILES` or
`DOCKER_PROFILES` includes `graph`, or when
`KALIKA_KNOWLEDGE_GRAPH_BACKEND=neo4j` is set. The persistence schema installs:

- unique constraints for concept, property, theorem, and open-problem IDs
- full-text indexes for concept labels/descriptions and theorem
  titles/statements
- a cosine vector index on `KalikaTheorem.embedding` with 1536 dimensions

## PostgreSQL AGE Fallback

Deployments that cannot run Neo4j can use Apache AGE in PostgreSQL:

```bash
export KALIKA_KNOWLEDGE_GRAPH_BACKEND=postgres-age
```

The AGE fallback expects a PostgreSQL image with the `age` extension installed.
At startup, Kalika applies:

- `CREATE EXTENSION IF NOT EXISTS age`
- `LOAD 'age'`
- `create_graph('kalika_knowledge_graph')`

The fallback writes the same snapshot to PostgreSQL JSONB sidecar tables for
full-text search and recovery, then mirrors graph topology into AGE through the
`cypher()` interface. AGE is selected automatically when
`KALIKA_ENABLE_POSTGRES_AGE=true` or `POSTGRES_EXTENSIONS` includes `age`.
