Merge pull request #305 from mason5052/codex/issue-187-graphiti-limitations-docs

docs(graphiti): note beta status and OpenAI-only provider limitation

README.md

@@ -2374,6 +2374,9 @@ Visit [localhost:3000](http://localhost:3000) to access Grafana Web UI.
 
 ### Knowledge Graph Integration (Graphiti)
 
+> [!IMPORTANT]
+> The Graphiti integration is currently a **beta** feature and has notable provider limitations. See [Current Limitations](#current-limitations) below before enabling it in production.
+
 PentAGI integrates with [Graphiti](https://github.com/vxcontrol/pentagi-graphiti), a temporal knowledge graph system powered by Neo4j, to provide advanced semantic understanding and relationship tracking for AI agent operations. The vxcontrol fork provides custom entity and edge types that are specific to pentesting purposes.
 
 #### What is Graphiti?
@@ -2445,6 +2448,17 @@ When enabled, PentAGI automatically captures:
 - **Tool Executions**: Commands executed, tools used, and their results
 - **Context Information**: Flow, task, and subtask hierarchy
 
+#### Current Limitations
+
+The Graphiti integration is currently a beta feature. Operators should plan around the following constraints before enabling it in production:
+
+- **OpenAI-compatible LLM only.** The bundled `vxcontrol/graphiti` image authenticates against a single OpenAI-compatible endpoint configured through PentAGI's `.env` variables `OPEN_AI_KEY` and `OPEN_AI_SERVER_URL` (default `https://api.openai.com/v1`). `docker-compose-graphiti.yml` maps these into the container as `OPENAI_API_KEY` and `OPENAI_BASE_URL`, so operators do not set the container variables directly. Provider credentials configured elsewhere in PentAGI for Anthropic, Google AI (Gemini), AWS Bedrock, DeepSeek, GLM, Kimi, or Qwen are **not** used by Graphiti for entity extraction. If your deployment cannot reach an OpenAI-compatible endpoint, leave `GRAPHITI_ENABLED=false`.
+- **Single fixed model per deployment.** Graphiti uses one model name (`GRAPHITI_MODEL_NAME`, default `gpt-5-mini`) for all extractions. The model cannot be selected per agent or per flow.
+- **Independent billing.** Even when a flow runs against a non-OpenAI provider, Graphiti still incurs cost on the configured OpenAI-compatible endpoint.
+- **No in-app graph explorer yet.** Browsing the captured graph relies on the Neo4j Browser at `http://localhost:7474` and the Graphiti Swagger UI at `http://localhost:8000/docs`. There is no PentAGI UI surface for the graph today.
+
+When `GRAPHITI_ENABLED=false`, PentAGI continues to operate with its primary memory and vector store; only the additional knowledge graph features are skipped.
+
 ### GitHub and Google OAuth Integration
 
 OAuth integration with GitHub and Google allows users to authenticate using their existing accounts on these platforms. This provides several benefits:

backend/docs/config.md

@@ -1620,6 +1620,8 @@ The SSL settings provide additional security configuration:
 
 ## Graphiti Knowledge Graph Settings
 
+> The Graphiti integration is currently a **beta** feature with notable provider limitations. See [Current Limitations (Beta)](#current-limitations-beta) at the end of this section before enabling it in production.
+
 These settings control the integration with Graphiti, a temporal knowledge graph system powered by Neo4j, for advanced semantic understanding and relationship tracking of AI agent operations.
 
 | Option          | Environment Variable | Default Value           | Description                                            |
@@ -1666,6 +1668,17 @@ These settings enable:
 
 The integration is designed to be non-blocking - if Graphiti operations fail, they are logged but don't interrupt the agent workflow.
 
+### Current Limitations (Beta)
+
+The Graphiti integration is currently a beta feature. Operators should plan around the following constraints before enabling it in production:
+
+- **OpenAI-compatible LLM only.** Operators configure the endpoint through PentAGI's `.env` variables `OPEN_AI_KEY` and `OPEN_AI_SERVER_URL` (default `https://api.openai.com/v1`); `docker-compose-graphiti.yml` maps these into the bundled `vxcontrol/graphiti` container as `OPENAI_API_KEY` and `OPENAI_BASE_URL`, which it uses to drive entity extraction. Provider credentials configured elsewhere in PentAGI for Anthropic, Google AI (Gemini), AWS Bedrock, DeepSeek, GLM, Kimi, or Qwen are not consumed by Graphiti.
+- **Single fixed model per deployment.** Graphiti uses one model name (`GRAPHITI_MODEL_NAME`, default `gpt-5-mini`) for all extractions; per-agent or per-flow selection is not supported.
+- **Independent billing.** Graphiti billing is tied to the configured OpenAI-compatible endpoint, even when the main flow runs against a non-OpenAI provider.
+- **No in-app graph explorer yet.** The captured graph is inspected through the Neo4j Browser at `http://localhost:7474` and the Graphiti Swagger UI at `http://localhost:8000/docs`; there is no PentAGI UI surface for it today.
+
+If your deployment cannot reach an OpenAI-compatible endpoint, set `GRAPHITI_ENABLED=false`. The rest of PentAGI continues to function without the knowledge graph.
+
 ## Agent Supervision Settings
 
 These settings control the agent supervision system, including execution monitoring and tool call limits for different agent types.