# The shared backbone: one Neo4j Enterprise instance, one Cognee, one LLM
# router, reused by every problem. Brought up once and left running (`restart:
# unless-stopped`) — not torn down between runs, not owned by any one problem.
#
#   scripts/shared-up            # start or reconcile; waits for health
#   scripts/shared-up --down     # stop it (the volumes survive)
#
# # This stack does not have to be on the run box
#
# It is every problem's memory and none of its compute, which makes it the half
# worth moving off a box that is doing the runs. Set `MATH_AGENT_SHARED_HOST`
# to an ssh host and `scripts/shared-up` drives it there; the runs then reach
# it by address — `MATH_AGENT_MEMORY_URL`, `MATH_AGENT_API_BASE_URL` — rather
# than by joining Docker networks, and the ports below are published for
# exactly that. `docs/runtime.md` has the split, including what publishing
# grants and what still carries the security when the network no longer does.
#
# Everything sized in this file is overridable for the same reason: the box
# that holds this stack decides its ceilings, and a heap larger than the host's
# Docker VM is a startup failure rather than a slow server.
#
# `scripts/memory-up` calls `scripts/shared-up` itself, and `./agent` calls
# `scripts/memory-up`, so an ordinary `./conjecture <slug>` brings the whole
# thing up in order without anyone naming this file.
#
# # One Cognee, one tenant per problem
#
# This used to run one Cognee container per problem, each pointed at its own
# pre-created Neo4j database. A dozen problems meant a dozen Python servers,
# a dozen embedding models resident in RAM, and a `mem_limit` per problem that
# decided whether the tenth stack fit on the box. The isolation that shape
# bought is now Cognee's own, and one process serves every problem:
#
# - **`ENABLE_BACKEND_ACCESS_CONTROL=true`** makes each problem a Cognee
#   *user* — its tenant — reached with an `X-Api-Key` header
#   (`scripts/memory-up` provisions one per workspace). Every dataset belongs
#   to the user that created it, and the server refuses a request for anybody
#   else's: probed live, one tenant asking for another's dataset by name got
#   `404 DatasetNotFoundError`, and an unauthenticated request got `401`.
# - **The graph is still one database per problem**, and Cognee now creates it
#   rather than `scripts/memory-up`: with the `neo4j` dataset-database handler
#   (selected automatically for the `neo4j` provider) each dataset gets its own
#   Neo4j database, named `cognee<dataset-uuid-hex>`, created and brought
#   online on first ingest. The Bolt-level isolation the previous shape relied
#   on is unchanged — a driver session is bound to one named database — but
#   nothing outside Cognee has to know the name.
# - **The vector store is per dataset too** (`lancedb`, the default handler),
#   so one problem's embeddings live in their own table directory.
#
# The runtime therefore writes and reads exactly one dataset per problem, with
# the four stores — brain, sessions, library, scratch — separated by
# `node_set`, which is the scoping this repository has measured as actually
# enforced (`docs/memory.md`). One dataset per problem is also what keeps the
# knowledge graph *connected*: a dataset is a graph database, so splitting the
# four stores across four datasets would put a source and the session that read
# it in different graphs, and the entity linking between them — the reason a
# graph store is worth its cost — would have nothing to link across.
#
# # What this costs, and the failure to watch for
#
# The failure this shape reintroduces is **contention**, and it is the one that
# broke the last shared Cognee: four concurrent runs against a single server
# produced a `409 Conflict` on a `recall_memory` that had already hung the full
# ten-minute tool ceiling. Two things are different now and neither is a proof:
# Cognee serialises per *dataset* rather than globally (`dataset_queue`), and
# the server is three minor versions on. Treat a hung or conflicting recall
# under load as this failure returning — `config/trace.jsonl` counts it — and
# `docs/memory.md` records what to measure before concluding otherwise.
#
# Multiple databases need Neo4j **Enterprise**: Community cannot create one at
# all (`Local Neo4j multi-user mode requires a Neo4j deployment that supports
# CREATE/DROP DATABASE`, measured directly against the Community image).
# `NEO4J_ACCEPT_LICENSE_AGREEMENT=yes` accepts the licence for this deployment;
# the commercial agreement behind it is handled outside this repository.

networks:
  # Cognee reaches `neo4j:7687` here. Internal: the graph store has no reason
  # to be routable, and nothing on this network needs egress.
  graph:
    name: ${GRAPH_NETWORK:-math-agent-shared_graph}
    internal: true
  # The agent and every problem's Cognee reach `ladder:6969` here. Internal and
  # gatewayless on purpose: joining it must not hand a calibration run a route
  # out. `compose.yaml` joins it by name.
  router:
    name: ${LADDER_NETWORK:-math-agent-shared_router}
    internal: true
  # The ladder alone needs provider egress. Keeping this attachment off every
  # other service is what preserves the calibration network boundary.
  ladder-egress:
    driver: bridge
  # Every run reaches `cognee:8000` here, and this is the only network the
  # agent has that carries a service it talks to. Internal and gatewayless, as
  # `router` is and for the same reason: joining it must never be how a run
  # gets a route out. That is what makes a calibration run's isolation a
  # property of the shared stack rather than of an overlay somebody has to
  # remember to pass — `compose.yaml` gives an ordinary run its egress as a
  # separate attachment, and `compose.eval.yaml` takes that one away.
  memory:
    name: ${MEMORY_NETWORK:-math-agent-shared_memory}
    internal: true
  # Cognee's own way out, and nothing else is on it. Its model calls go through
  # the ladder on the internal `router` network and need nothing from this, but
  # the embedding provider fetches its model from Hugging Face on a cold
  # volume, so removing this turns a fresh stack into a startup failure rather
  # than a tighter boundary.
  cognee-egress:
    driver: bridge
  # Neo4j's published ports, for reading the graph from a browser or Neo4j
  # Desktop on this box. A container attached only to an `internal` network
  # has no route a published port can be forwarded over, so the publication
  # needs an ordinary bridge to land on — this is that bridge and nothing
  # else is on it. It does not widen what any *run* can reach: the agent is
  # never on this network, and in a calibration run it is not on `graph`
  # either.
  graph-admin:
    driver: bridge

services:
  neo4j:
    image: neo4j:5.26-enterprise
    # Cognee's graph store, and nothing else on this box uses it. Both carry the
    # `cognee` profile so an ordinary `scripts/shared-up` starts neither: the
    # default engine is CortexDB, which brings its own graph and its own vector
    # index, and a Neo4j Enterprise instance nobody queries is several gigabytes
    # of reservation held against a box doing runs.
    #
    #     MATH_AGENT_MEMORY=cognee scripts/shared-up
    profiles: ["cognee"]
    restart: unless-stopped
    environment:
      NEO4J_AUTH: neo4j/cognee-local
      NEO4J_ACCEPT_LICENSE_AGREEMENT: "yes"
      NEO4J_PLUGINS: '["apoc"]'
      # Sized for many problems' graphs landing in one instance, rather than
      # the defaults a single problem's private instance ran on. Revisit
      # against real usage once a dozen databases are live here.
      # Sized for many problems' graphs in one instance. Overridable because
      # this stack is meant to be movable: the box it runs on decides these,
      # and a heap larger than the host's Docker VM is a startup failure rather
      # than a slow server.
      NEO4J_server_memory_heap_max__size: ${NEO4J_HEAP:-4g}
      NEO4J_server_memory_pagecache_size: ${NEO4J_PAGECACHE:-2g}
      # The Browser is served over HTTP from this container but speaks Bolt
      # from the *browser*, to whatever address the server advertises. Left at
      # the container's own hostname it would advertise a name that resolves
      # to nothing on the host, and the Browser hangs on "connecting"; the
      # published Bolt port below is what `localhost` here refers to.
      NEO4J_server_default__advertised__address: ${NEO4J_ADVERTISED_ADDRESS:-localhost}
    healthcheck:
      test: ["CMD-SHELL", "cypher-shell -u neo4j -p cognee-local 'RETURN 1' >/dev/null"]
      interval: 10s
      timeout: 5s
      retries: 30
      start_period: 20s
    # One instance holding every problem's graph, so the ceiling is the box's
    # rather than one problem's. 1g is reserved — the floor the scheduler keeps
    # for it while it is idle, which is what stops a busy run from starving the
    # store every other run reads through — and 16g is the ceiling, above the
    # 4g heap and 2g page cache configured above with room for the query load
    # a dozen live databases put on it.
    mem_reservation: ${NEO4J_MEM_RESERVATION:-1g}
    mem_limit: ${NEO4J_MEM_LIMIT:-16g}
    # See the note on `cognee` below: the two shared services are sized
    # together, and the weight is the half that does the work.
    cpus: ${NEO4J_CPUS:-4}
    cpu_shares: 2048
    # 7474 is the Neo4j Browser, 7687 is Bolt for Neo4j Desktop or
    # `cypher-shell`. Log in as `neo4j` / `cognee-local` and pick a problem's
    # database from the selector — one database per problem, named
    # `cognee<dataset-uuid-hex>` and created by Cognee itself. The mapping from
    # a workspace to its database is Cognee's dataset table, not a name you can
    # read off the slug: `scripts/memory-inventory <label>` prints it.
    #
    # `NEO4J_BIND_ADDRESS` defaults to the loopback interface, so out of the
    # box this is reachable from a browser on this box and from nowhere else.
    # Set it to a Tailscale address to read the graph from another of your own
    # machines, and set `NEO4J_ADVERTISED_ADDRESS` to the same thing — the
    # Browser is served over HTTP from here but speaks Bolt from the
    # *browser*, to whatever address the server advertises, so a mismatch
    # leaves it hanging on "connecting". Both belong in `.env`.
    #
    # Note what widening the bind grants: `NEO4J_AUTH` above is a fixed local
    # password, so anything that can reach the port can read every problem's
    # graph. A tailnet of your own machines is the intended ceiling for that;
    # `0.0.0.0` is not.
    ports:
      - "${NEO4J_BIND_ADDRESS:-127.0.0.1}:${NEO4J_HTTP_PORT:-7474}:7474"
      - "${NEO4J_BIND_ADDRESS:-127.0.0.1}:${NEO4J_BOLT_PORT:-7687}:7687"
    networks:
      - graph
      - graph-admin
    volumes:
      - neo4j-data:/data

  ladder:
    # `latest`, not a sha. The router is a sibling repository whose CI rebuilds
    # and republishes this tag on every push to its main, so a fix there
    # reaches every problem here by restarting one container rather than by
    # editing this line. It moves under us by design; `pull_policy: always`
    # below is what makes that actually happen, since Compose would otherwise
    # keep serving whatever `latest` meant the first time it pulled.
    image: ghcr.io/senamakel/llm-ladder-router:latest
    # The image is published for amd64 only. Declaring it is a no-op on an
    # amd64 host and is what lets this stack run on an Apple Silicon box, where
    # Docker emulates it — acceptable for a proxy, which is I/O bound rather
    # than compute bound, and verified running there before anything depended
    # on it.
    platform: linux/amd64
    pull_policy: always
    restart: unless-stopped
    # This used to live in `compose.yaml`, whose project name is the checkout
    # directory's, so a second checkout brought up a second ladder and the two
    # fought over port 6969 — the loser simply failed to bind. One ladder,
    # named once, is what every checkout and every problem now reaches.
    #
    # The run's `.env` contributes the independent memory key. The router's
    # file comes second so its own OpenRouter and Surplus credentials win when
    # both files name the same upstream variable. Compose parses quoted dotenv
    # values; `docker run --env-file` does not, and sends the quote as part of
    # the bearer token.
    env_file:
      - .env
      - ${LADDER_ENV_FILE:-../llm-ladder-router/.env}
    volumes:
      - type: bind
        source: ${LADDER_CONFIG_PATH:-../llm-ladder-router/config.toml}
        target: /etc/ladder/config.toml
        read_only: true
    # Loopback by default, so an ordinary single-box deployment publishes this
    # to itself and nowhere else. Set `LADDER_BIND_ADDRESS` to a Tailscale
    # address when the runs are on a different machine from this stack; see the
    # note on Cognee's publication for what that grants and what it does not.
    ports:
      - "${LADDER_BIND_ADDRESS:-127.0.0.1}:${LADDER_PORT:-6969}:6969"
    # No `healthcheck:` here on purpose — the image carries its own, which is
    # what `scripts/shared-up --wait` and the old `depends_on` both read.
    # Capped like everything else in this stack. Measured at 55 MiB serving a
    # live run, so 512m is headroom rather than a budget — but an uncapped
    # container on a box whose whole Docker VM is a few gigabytes is one bad
    # response away from taking the memory server down with it, and the memory
    # server is every problem's.
    mem_limit: ${LADDER_MEM_LIMIT:-512m}
    read_only: true
    tmpfs:
      - /tmp:rw,nosuid,nodev,noexec,size=16m
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    pids_limit: 64
    networks:
      # `priority` decides which attachment supplies the default route. The
      # egress network must win, or the ladder inherits a gatewayless route
      # from `router` and every provider call fails as a connection error.
      ladder-egress:
        priority: 100
      router:
        priority: 10

  cortexdb:
    # Pinned, not `latest`. The vendor's own agent manifest says it outright —
    # `latest` is a moving pointer, so a digest resolved through it is not a
    # reproducible release identity — and this is the process holding every
    # problem's memory. Bump it deliberately, and re-read
    # https://cortexdb.ai/agent/manifest.json when you do: that file is
    # generated from the release and is where the current server version, the
    # write barriers and the error contract are stated.
    image: cortexdb/cortexdb:v0.9.8
    restart: unless-stopped
    environment:
      # The one operator credential. Unset, the server generates a key, prints
      # it to its log once, and serves nothing without it — which is a fine
      # default for a laptop and useless for a stack a dozen runs authenticate
      # against, since nothing could read it back. `CORTEX_INSECURE_NO_AUTH`
      # exists and is not used: this publishes a host port.
      #
      # It is one key for the deployment rather than one per problem, and that
      # is a real difference from the Cognee shape above. The self-hosted image
      # cannot mint scoped tokens — `POST /v1/auth/tokens` answers
      # `NOT_CONFIGURED` — so the cross-problem boundary is the runtime's scope
      # construction rather than the server's authorization.
      # `src/orchestrator/cortex.rs` states exactly what that is worth, and
      # `compose.eval.yaml` is where a calibration run declines to rely on it.
      # The default is a fixed local credential, on the same footing as
      # `NEO4J_AUTH` above and for the same reason: out of the box this is
      # published to loopback and nowhere else. Set `CORTEX_API_KEY` in `.env`
      # before widening `CORTEX_BIND_ADDRESS` to a tailnet address —
      # `scripts/memory-up --key` reads the same variable with the same
      # default, so the two sides cannot disagree about what the key is.
      CORTEX_API_KEY: ${CORTEX_API_KEY:-cortex-local-shared}
      # Everything that thinks goes through the ladder, which is the same
      # arrangement Cognee has above and for the same reason: the router holds
      # the upstream credentials and the memory's own budget
      # (`OPENROUTER_MEMORY_API_KEY`, reaching the ladder through its
      # `env_file`), so no provider key is named here.
      #
      # The server gates on `OPENAI_API_KEY` / `LLM_API_KEY` rather than on the
      # per-lane keys when it decides whether it has a real provider at all —
      # measured: with only `CORTEX_EMBEDDING_API_KEY` set it fell back to MOCK
      # embeddings and reported `degraded: true` while looking otherwise
      # healthy. So the ladder's key is given under the name the gate reads.
      OPENAI_API_KEY: ${MATH_AGENT_API_KEY}
      # Entity extraction, on the ordinary-role ladder. This is the model that
      # runs on the write path, which is what makes a durable write cost about
      # five seconds; `flash` is the cheapest rung that does it well.
      CORTEX_LLM_URL: ${LLM_ENDPOINT:-http://ladder:6969/v1}
      CORTEX_LLM_MODEL: flash
      # Fact augmentation. Without it the `facts` and `beliefs` layers stay
      # empty — measured — and `relate_memory` then has only `understanding` to
      # answer from, which is the layer that costs the most to build.
      CORTEX_ENRICHMENT_MODEL: flash
      # `/v1/answer` and the answer verifier. Neither is on any path this
      # runtime takes — it reads packs and renders them itself rather than
      # asking the memory to write prose — but a server pointed at
      # `api.openai.com` by its own image defaults would try to reach it from a
      # gatewayless network and fail slowly. Pointing them at the ladder costs
      # nothing and removes a class of timeout.
      CORTEX_ANSWER_PROVIDER: openai
      CORTEX_ANSWER_URL: ${LLM_ENDPOINT:-http://ladder:6969/v1}
      CORTEX_ANSWER_MODEL: flash
      CORTEX_VERIFIER_URL: ${LLM_ENDPOINT:-http://ladder:6969/v1}
      CORTEX_VERIFIER_MODEL: flash
      # The embeddings surface, which is a different ladder rather than a
      # different price band: an embedding model cannot answer a chat request,
      # and the router refuses the wrong pairing at the door. `vectors` resolves
      # to a 3072-dimension model, which is one of the seven dimensions the
      # server accepts — a value outside that set is a startup failure, not a
      # slow server.
      CORTEX_EMBEDDING_URL: ${LLM_ENDPOINT:-http://ladder:6969/v1}
      CORTEX_EMBEDDING_MODEL: ${CORTEX_EMBEDDING_MODEL:-vectors}
      CORTEX_EMBEDDING_DIMS: ${CORTEX_EMBEDDING_DIMS:-3072}
      # Build the derived layers in the background. Off by default — the
      # image's vector-only default rebuilds episodes, beliefs and concepts only
      # when a build endpoint is called, and nothing here calls one. Left off,
      # `relate_memory` would answer from layers that never fill.
      CORTEX_V1_LAYERS_AUTO: "1"
      # The hot vector tier is uncapped by default and the server says so in a
      # startup warning: at roughly 1.1 KB a vector, an unbounded tier is an OOM
      # with the box's whole memory behind it. This is the watermark above which
      # vectors are demoted rather than held, and it is sized against
      # `mem_limit` below rather than against the host.
      CORTEX_VECTOR_RESIDENT_MAX: ${CORTEX_VECTOR_RESIDENT_MAX:-4000000}
      CORTEX_EVICT_VECTORS_ON_ENRICH: "1"
    healthcheck:
      # `/v1/admin/ready`, never `/v1/admin/health`. The manifest is explicit
      # that health returns 200 with unreadable storage or mock providers and
      # must not gate traffic; readiness answers 503 with the same body shape
      # when a required check fails. The runtime reads the same endpoint before
      # every write, for the same reason.
      test: ["CMD-SHELL", "curl -sf http://127.0.0.1:3141/v1/admin/ready || exit 1"]
      interval: 10s
      timeout: 20s
      retries: 30
      start_period: 30s
    # Sized like Cognee was, because it holds the same thing: every problem's
    # memory rather than one problem's. The reservation matters more than the
    # ceiling — ingest is bursty and the server is idle between a run's turns,
    # so without a floor it is exactly the process a busy neighbour squeezes,
    # and the symptom is every problem's recall slowing at once.
    mem_reservation: ${CORTEX_MEM_RESERVATION:-1g}
    mem_limit: ${CORTEX_MEM_LIMIT:-16g}
    cpus: ${CORTEX_CPUS:-4}
    cpu_shares: 2048
    # Published so a run on another machine can reach it, bound to loopback by
    # default. On a single-box deployment the agent joins the `memory` network
    # and reaches `cortexdb:3141` by name, and this publication is unused.
    # Widening it to a Tailscale address is what a split deployment needs; what
    # carries the security then is `CORTEX_API_KEY`, and a tailnet of your own
    # machines is the intended ceiling rather than `0.0.0.0`.
    ports:
      - "${CORTEX_BIND_ADDRESS:-127.0.0.1}:${CORTEX_PORT:-3141}:3141"
    # No egress attachment, and that is the difference from Cognee. Its
    # embedding provider fetched a model from Hugging Face on a cold volume, so
    # it needed a way out; this one embeds through the ladder like everything
    # else, so `memory` and `router` are the whole of its network.
    networks:
      - memory
      - router
    volumes:
      - cortexdb-data:/data

  cognee:
    image: cognee/cognee:1.4.2
    # See `neo4j` above: the alternative engine, started only under
    # `MATH_AGENT_MEMORY=cognee`.
    profiles: ["cognee"]
    restart: unless-stopped
    environment:
      LLM_PROVIDER: custom
      # litellm (Cognee's LLM client) requires a provider prefix on the model
      # string even against a custom OpenAI-compatible endpoint — bare `flash`
      # raises `BadRequestError: LLM Provider NOT provided` on every call,
      # which the health check then reports as a flat 30s timeout since each
      # attempt fails instantly and litellm's own retry/backoff eats the
      # budget. `openai/` is litellm's convention for "treat this as an
      # OpenAI-compatible endpoint"; the ladder is the actual routing, and
      # `flash` is the router's ordinary-role ladder — the same tier
      # `MATH_AGENT_MODEL` defaults to for every non-reasoning role.
      LLM_MODEL: openai/flash
      # The ladder's key, not a provider's: `LLM_ENDPOINT` below is the router,
      # and the router holds the upstream credentials. Handing Cognee an
      # OpenRouter key here reaches the ladder as a bearer token it does not
      # recognise, and every ingest fails `409 AuthenticationError` — measured,
      # while `/health/detailed` reported the model endpoint healthy.
      # `OPENROUTER_MEMORY_API_KEY` is the memory's own upstream budget and it
      # reaches the ladder through the ladder's `env_file`, which is where a
      # provider credential belongs.
      LLM_API_KEY: ${MATH_AGENT_API_KEY}
      LLM_ENDPOINT: http://ladder:6969/v1
      LLM_ARGS: '{"max_tokens":8192}'
      EMBEDDING_PROVIDER: fastembed
      EMBEDDING_MODEL: BAAI/bge-small-en-v1.5
      EMBEDDING_DIMENSIONS: 384
      HUGGINGFACE_TOKENIZER: BAAI/bge-small-en-v1.5
      GRAPH_DATABASE_PROVIDER: neo4j
      GRAPH_DATABASE_URL: bolt://neo4j:7687
      GRAPH_DATABASE_USERNAME: neo4j
      GRAPH_DATABASE_PASSWORD: cognee-local
      # No `GRAPH_DATABASE_NAME`. Under access control the graph database is
      # per dataset and Cognee creates it — `CREATE DATABASE cognee<hex> IF NOT
      # EXISTS` against the shared instance, then waits for it to come online
      # before the first ingest touches it. A name set here would be the
      # single-tenant default database and would mean every problem sharing one
      # graph, which is the mistake this deployment must not make.
      VECTOR_DB_PROVIDER: lancedb
      # The two switches that make this one server multi-tenant. Access control
      # is what scopes a dataset to the user that created it — and what makes
      # Cognee honour the `datasets` field at all, which in single-user mode it
      # documents as unenforced and this repository measured leaking
      # (`docs/memory.md`). Authentication is not independent of it: multi-user
      # mode requires a user, and Cognee forces authentication on and logs a
      # warning if these two disagree. Set explicitly rather than left to the
      # image's default, because the default is a property of the image tag and
      # this is a property of the deployment.
      ENABLE_BACKEND_ACCESS_CONTROL: "true"
      REQUIRE_AUTHENTICATION: "true"
      # Keep a tenant's key readable back off the server. `scripts/memory-up`
      # is idempotent because it can list an existing key and hand the same one
      # to the next run; hashed, it could only ever mint another, and a
      # workspace continued ten times would own ten keys. The key is a local
      # credential for a server with no published port, on the same footing as
      # `NEO4J_AUTH` above.
      HASH_API_KEY: "false"
      # Lets `/api/v1/add` take a URL as well as an uploaded file, so a source
      # can be handed over by reference. Note what it grants: the *server* then
      # performs the fetch, from inside this network, where the runtime
      # container's own egress rules do not apply. Nothing here publishes a
      # host port, which is what kept that fetch off-box before and still does.
      ALLOW_HTTP_REQUESTS: "true"
    healthcheck:
      test: ["CMD", "curl", "--fail", "--silent", "http://localhost:8000/health"]
      interval: 10s
      # 20s, not 5s. A healthy server under load fails a five-second probe —
      # the health log read `Health check exceeded timeout (5s)` three times
      # over while the server's own log showed it coming up normally. A probe
      # that times out under load reports the wrong thing about the service.
      timeout: 20s
      retries: 30
      start_period: 30s
    # One process for every problem on the box, so this is the whole memory
    # budget rather than one problem's share of it. The per-problem shape it
    # replaces was capped at 2g each and measured between 0.6g and a problem
    # pinned at 3.96g of its 4g during cognify — a dozen of those reserved 24g
    # of ceiling for what is now one server.
    #
    # 1g reserved and 16g capped, matching Neo4j: the pair are the shared half
    # of the box and are sized together. The reservation matters more here than
    # the ceiling does — ingest is bursty and the server is idle between a
    # run's turns, so without a floor it is exactly the process a busy
    # neighbour squeezes, and the symptom is every problem's recall slowing at
    # once. A repeated OOM kill here is a finding about the ingest — it now
    # stops *every* problem's memory rather than one, so read
    # `docker events --filter event=oom` before raising it.
    # Published so a run on another machine can reach it. Bound to loopback by
    # default, which is where this used to publish nothing at all: on a
    # single-box deployment the agent joins the `memory` network and reaches
    # `cognee:8000` by name, and this publication is unused.
    #
    # Widening it to a Tailscale address is what a split deployment needs, and
    # it is worth being clear about what carries the security then. The API is
    # authenticated — each problem is a tenant with its own key, an unkeyed
    # request is `401` and another tenant's dataset is `404` — so the boundary
    # travels with the request rather than with the network. `0.0.0.0` is not
    # the intended ceiling: a tailnet of your own machines is.
    ports:
      - "${COGNEE_BIND_ADDRESS:-127.0.0.1}:${COGNEE_PORT:-8000}:8000"
    mem_reservation: ${COGNEE_MEM_RESERVATION:-1g}
    mem_limit: ${COGNEE_MEM_LIMIT:-16g}
    # Four of the box's cores, and twice the default scheduling weight.
    #
    # The weight is the half that matters, because nothing else here is CPU
    # bounded: a dozen run containers are unlimited, so on a busy box the
    # shared services compete against them at equal priority and lose by
    # sheer number. `cpu_shares` is a *relative* weight applied only under
    # contention — 2048 against the default 1024 means that when every core is
    # wanted, Cognee and Neo4j get twice the slice one run container does, and
    # when the box is idle it changes nothing.
    #
    # `cpus` is the ceiling on top of that. Ingest is the CPU-hungry part —
    # fastembed embeds on the CPU here, and chunking and entity extraction run
    # per document — and one problem cognifying a large source should not be
    # able to take the box from every other problem's recall. Four leaves ten
    # for the runs.
    cpus: ${COGNEE_CPUS:-4}
    cpu_shares: 2048
    networks:
      - memory
      - graph
      - router
      - cognee-egress
    volumes:
      - cognee-system:/app/cognee/.cognee_system
      - cognee-data:/app/cognee/.data_storage
      # A bind-mount over a vendored prompt, ranked below the env keys because
      # there is no environment variable for a prompt template. Cognee's own
      # `summarize_content` prompt tells the model to "Output two sections
      # only" as free text, while `instructor` wraps the same call in a
      # JSON-schema tool call for `{summary, description}`. The model's visible
      # reasoning on a failed chunk showed it noticing the contradiction and
      # guessing at how to reconcile the two — sometimes emitting `{}`, once a
      # JSON key with a stray leading quote. The corrected copy says once,
      # explicitly, that `summary` is the one string to fill.
      - ./cognee-overrides/summarize_content.txt:/app/cognee/infrastructure/llm/prompts/summarize_content.txt:ro

volumes:
  cortexdb-data:
  neo4j-data:
  cognee-system:
  cognee-data: