Skip to content

Fully autonomous AI Agents system capable of performing complex penetration testing tasks

feat(graphiti): enhance configuration and integration settings

Dmitry Ngebb228b19a0d
diff --git a/.env.example b/.env.example
index c6c9223f..85308a19 100644
--- a/.env.example
+++ b/.env.example
@@ -301,13 +301,71 @@ DATABASE_SEARCH_PATH_VIA_OPTIONS=
GRAPHITI_ENABLED=false
GRAPHITI_TIMEOUT=30
GRAPHITI_URL=
-GRAPHITI_MODEL_NAME=
+GRAPHITI_CPUS=2.0
+GRAPHITI_MEMORY=2G
+
+## Graphiti LLM provider preset: openai, gemini, custom, or litellm.
+## Model and request settings are loaded from examples/graphiti/<provider>.yaml.
+## OpenAI, Gemini, and custom providers reuse the corresponding credentials above.
+## Keep this set to llm_configs only when the adjacent graphiti directory is installed.
+## Older .env files omit it, so a newer compose file cannot shadow built-in configs
+## with an empty host directory.
+## Override the host path for development deployments when needed.
+GRAPHITI_CONFIG_PATH=./graphiti
+GRAPHITI_CONFIG_DIR=llm_configs
+GRAPHITI_LLM_CLIENT_TYPE=openai
+GRAPHITI_LITELLM_BASE_URL=
+GRAPHITI_LITELLM_API_KEY=
+
+## Use the shared EMBEDDING_URL, EMBEDDING_KEY, and EMBEDDING_MODEL settings above.
+## Graphiti requires an OpenAI-compatible embedding endpoint. When disabled,
+## Graphiti uses the selected LLM provider credentials instead.
+GRAPHITI_SEPARATE_EMBEDDING=false
+
+## Graphiti runtime and logging
+GRAPHITI_SEMAPHORE_LIMIT=20
+GRAPHITI_TELEMETRY_ENABLED=false
+GRAPHITI_LOG_FORMAT=json
+GRAPHITI_LOG_LEVEL=INFO
+GRAPHITI_LOG_STDOUT=events
+GRAPHITI_FLOW_LOGGER_WARN_COUNT=256
+GRAPHITI_DEBUG_RUNTIME_RESOURCES=false
+GRAPHITI_SEARCH_SCOPE=flowid
+
+## Graphiti ingestion policy and worker settings
+GRAPHITI_INGEST_POLICY_RULES='{"graphiti_search":"REJECT","tool_execution_terminal":"PROCESS","tool_execution_file":"PROCESS"}'
+GRAPHITI_INGEST_POLICY_FIELD=both
+GRAPHITI_INGEST_POLICY_DEFAULT_ACTION=SKIP_LLM
+GRAPHITI_INGEST_USE_GROUP_ACTORS=true
+GRAPHITI_INGEST_WORKER_COUNT=16
+GRAPHITI_INGEST_LOCK_BY_GROUP_ID=true
+GRAPHITI_INGEST_TASK_MAX_RETRIES=1
+GRAPHITI_INGEST_TASK_RETRY_DELAY_SEC=2.0
+GRAPHITI_INGEST_TASK_TIMEOUT_SEC=0
+GRAPHITI_INGEST_QUEUE_MAX_SIZE=0
+GRAPHITI_INGEST_DEAD_LETTER_ENABLED=false
+
+## Graphiti extraction and graph-linking settings
+GRAPHITI_TAXONOMY_LAYER_PROFILE=STRUCTURAL,EVIDENCE,PROGRESS,ATTEMPT
+GRAPHITI_USE_COMBINED_FULL_EXTRACTION=true
+GRAPHITI_USE_COMBINED_EXTRACTION=true
+GRAPHITI_COMBINED_FULL_GATING_ENABLED=true
+GRAPHITI_COMBINED_DIAGNOSTIC_SAMPLES=false
+GRAPHITI_ANCHOR_NODE_MODE=smart
+GRAPHITI_ANCHOR_NODE_LIMIT=25
+GRAPHITI_ANCHOR_MASS_TYPE_LIMIT=10
+GRAPHITI_ANCHOR_QUERY_TIMEOUT=10
# Neo4j settings (used by Graphiti stack)
NEO4J_USER=neo4j
NEO4J_DATABASE=neo4j
NEO4J_PASSWORD=devpassword # change this to improve security
NEO4J_URI=bolt://neo4j:7687
+NEO4J_CPUS=4.0
+NEO4J_MEMORY=4G
+## /dev/shm is a separate limit but its actual usage counts toward NEO4J_MEMORY.
+NEO4J_SHM_SIZE=4g
+NEO4J_NOFILE=65536
## PentAGI image settings
PENTAGI_IMAGE=
diff --git a/README.md b/README.md
index 91c3e2a7..3ea28da8 100644
--- a/README.md
+++ b/README.md
@@ -63,7 +63,7 @@ You can watch the video **PentAGI overview**:
- Fully Autonomous. AI-powered agent that automatically determines and executes penetration testing steps with optional execution monitoring and intelligent task planning for enhanced reliability.
- Professional Pentesting Tools. Built-in suite of 20+ professional security tools including nmap, metasploit, sqlmap, and more.
- Smart Memory System. Long-term storage of research results and successful approaches for future use.
-- Knowledge Graph Integration. Graphiti-powered knowledge graph using Neo4j for semantic relationship tracking and advanced context understanding.
+- Optional Knowledge Graph Integration. Graphiti-powered knowledge graph using Neo4j for semantic relationship tracking and advanced context understanding.
- Web Intelligence. Built-in browser via [scraper](https://hub.docker.com/r/vxcontrol/scraper) for gathering latest information from web sources.
- External Search Systems. Integration with advanced search APIs including [Tavily](https://tavily.com), [Firecrawl](https://www.firecrawl.dev), [Traversaal](https://traversaal.ai), [Perplexity](https://www.perplexity.ai), [DuckDuckGo](https://duckduckgo.com/), [Google Custom Search](https://programmablesearchengine.google.com/), [Sploitus Search](https://sploitus.com) and [Searxng](https://searxng.org) for comprehensive information gathering.
- Team of Specialists. Delegation system with specialized AI agents for research, development, and infrastructure tasks, enhanced with optional execution monitoring and intelligent task planning for optimal performance with smaller models.
@@ -538,10 +538,10 @@ The architecture of PentAGI is designed to be modular, scalable, and secure. Her
- Task Queue: Async task processing system for reliable operation
- AI Agent: Multi-agent system with specialized roles for efficient testing
-2. **Knowledge Graph**
+2. **Optional Knowledge Graph**
- Graphiti: Knowledge graph API for semantic relationship tracking and contextual understanding
- Neo4j: Graph database for storing and querying relationships between entities, actions, and outcomes
- - Automatic capturing of agent responses and tool executions for building comprehensive knowledge base
+ - When enabled, automatically captures agent responses and tool executions for a flow-scoped knowledge base
3. **Monitoring Stack**
- OpenTelemetry: Unified observability data collection and correlation
@@ -804,10 +804,9 @@ WEB_SEARCH_INTERNAL_MAX_SITES=5
WEB_SEARCH_INTERNAL_MAX_SITE_BYTES=10240
## Graphiti knowledge graph settings
-GRAPHITI_ENABLED=true
+GRAPHITI_ENABLED=false
GRAPHITI_TIMEOUT=30
-GRAPHITI_URL=http://graphiti:8000
-GRAPHITI_MODEL_NAME=gpt-5-mini
+GRAPHITI_URL=
# Neo4j settings (used by Graphiti stack)
NEO4J_USER=neo4j
@@ -2676,89 +2675,194 @@ 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.
+> Graphiti is an optional **beta** integration and is disabled by default. Review [Limitations and Security](#limitations-and-security) 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?
-Graphiti automatically extracts and stores structured knowledge from agent interactions, building a graph of entities, relationships, and temporal context. This enables:
+Graphiti asynchronously extracts structured knowledge from agent interactions and builds a graph of entities, relationships, evidence, and temporal context. PentAGI sends agent responses and tool executions to Graphiti and exposes the `graphiti_search` tool to enabled agents. Graphiti complements the primary pgvector memory; it does not replace it.
- **Semantic Memory**: Store and recall relationships between tools, targets, vulnerabilities, and techniques
- **Contextual Understanding**: Track how different pentesting actions relate to each other over time
-- **Knowledge Reuse**: Learn from past penetration tests and apply insights to new assessments
-- **Advanced Querying**: Search for complex patterns like "What tools were effective against similar targets?"
+- **Flow-Scoped Recall**: Reuse knowledge within the active flow without exposing data from other engagements by default
+- **Advanced Querying**: Search temporal context, relationships, successful tools, recent episodes, and entities by type
+
+When enabled, PentAGI captures agent responses, tool execution details, and flow/task/subtask context. Ingestion is asynchronous, so newly submitted events can take time to become searchable.
-#### Enabling Graphiti
+#### Deployment Modes and Enabling
-The Graphiti knowledge graph is **optional** and disabled by default. To enable it:
+Graphiti can run as the bundled Neo4j + Graphiti stack, as an external service, or remain disabled.
-1. Configure Graphiti environment variables in `.env` file:
+For the bundled stack, configure `.env`:
```bash
-## Graphiti knowledge graph settings
GRAPHITI_ENABLED=true
GRAPHITI_TIMEOUT=30
GRAPHITI_URL=http://graphiti:8000
-GRAPHITI_MODEL_NAME=gpt-5-mini
+GRAPHITI_LLM_CLIENT_TYPE=openai
-# Neo4j settings (used by Graphiti stack)
+# Reused by the Graphiti OpenAI preset
+OPEN_AI_KEY=your_openai_api_key
+OPEN_AI_SERVER_URL=https://api.openai.com/v1
+
+# Bundled Neo4j
NEO4J_USER=neo4j
NEO4J_DATABASE=neo4j
-NEO4J_PASSWORD=devpassword
+NEO4J_PASSWORD=replace_with_a_strong_password
NEO4J_URI=bolt://neo4j:7687
-
-# OpenAI API key (required by Graphiti for entity extraction)
-OPEN_AI_KEY=your_openai_api_key
```
-2. Run the Graphiti stack along with the main PentAGI services:
+Download the optional compose file when installing manually, then start both stacks:
```bash
-# Download the Graphiti compose file if needed
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-graphiti.yml
-
-# Start PentAGI with Graphiti
docker compose -f docker-compose.yml -f docker-compose-graphiti.yml up -d
```
-3. Verify Graphiti is running:
+The base stack must create the external `pentagi-network` before the Graphiti stack can start. The installer handles stack ordering automatically.
-```bash
-# Check service health
-docker compose -f docker-compose.yml -f docker-compose-graphiti.yml ps graphiti neo4j
+For an external Graphiti deployment, set `GRAPHITI_ENABLED=true` and point `GRAPHITI_URL` to its API. Do not start `docker-compose-graphiti.yml`; configure providers, embeddings, the graph database, and ingest tuning on the external service itself.
-# View Graphiti logs
-docker compose -f docker-compose.yml -f docker-compose-graphiti.yml logs -f graphiti
+PentAGI enables its client only when both `GRAPHITI_ENABLED=true` and `GRAPHITI_URL` is non-empty. At startup it performs three health-check attempts with a two-second backoff. If they all fail, PentAGI logs a warning and continues with Graphiti disabled.
+
+#### LLM Provider and Model Presets
+
+`GRAPHITI_LLM_CLIENT_TYPE` selects one deployment-wide preset. Model names and call parameters are not environment variables; they live in `graphiti/<provider>.yaml`.
+
+| Preset | Credentials and endpoint | Shipped main model |
+| --- | --- | --- |
+| `openai` | `OPEN_AI_KEY`, `OPEN_AI_SERVER_URL` | `openai/gpt-5-mini` |
+| `gemini` | `GEMINI_API_KEY`, `GEMINI_SERVER_URL` | `gemini/gemini-2.5-flash-lite` |
+| `custom` | `LLM_SERVER_KEY`, `LLM_SERVER_URL` | `Qwen/Qwen3.6-27B-FP8` |
+| `litellm` | `GRAPHITI_LITELLM_API_KEY`, `GRAPHITI_LITELLM_BASE_URL` | `openrouter/openai/gpt-oss-20b` |
-# Access Neo4j Browser (optional)
-# Visit http://localhost:7474 and login with NEO4J_USER/NEO4J_PASSWORD
+The Gemini preset uses Graphiti's LiteLLM/OpenAI-compatible client path. Point `GEMINI_SERVER_URL` at a compatible gateway if the native Gemini endpoint does not provide the required OpenAI-compatible API.
-# Access Graphiti API (optional, for debugging)
-# Visit http://localhost:8000/docs for Swagger API documentation
+Each preset file must contain a matching `provider` plus `MODEL_NAME` and `SMALL_MODEL_NAME` mappings. The small model is used for reranking and lighter calls. Supported call settings include temperature, token limits, sampling and penalty parameters, JSON mode, reasoning effort, verbosity, pricing metadata, and provider-specific `extra_body`.
+
+The installer copies [`examples/graphiti`](examples/graphiti) beside the installation as `./graphiti`. The compose mount is controlled by:
+
+```bash
+GRAPHITI_CONFIG_PATH=./graphiti
+GRAPHITI_CONFIG_DIR=llm_configs
```
+`GRAPHITI_CONFIG_PATH` may point directly to `./examples/graphiti` for development. `GRAPHITI_CONFIG_DIR=llm_configs` activates the mounted presets. If an older `.env` omits that variable, a newer compose file mounts an empty host directory at the unused `configs` path instead of hiding the presets built into the image.
+
> [!NOTE]
-> The Graphiti service is defined in `docker-compose-graphiti.yml` as a separate stack. You must run both compose files together to enable the knowledge graph functionality. The pre-built Docker image `vxcontrol/graphiti:latest` is used by default.
+> `GRAPHITI_MODEL_NAME` is obsolete and ignored. Edit the active YAML preset instead, then restart the Graphiti container.
+
+#### Graphiti Embedding Configuration
+
+By default, Graphiti uses the active LLM preset's credentials and its default OpenAI embedding model. To use PentAGI's shared embedding endpoint explicitly:
-#### What Gets Stored
+```bash
+GRAPHITI_SEPARATE_EMBEDDING=true
+EMBEDDING_URL=https://embedding.example.com/v1
+EMBEDDING_KEY=your_embedding_api_key
+EMBEDDING_MODEL=openai/text-embedding-3-large
+```
+
+Graphiti's embedder is OpenAI-compatible. `EMBEDDING_PROVIDER` is used by PentAGI but is not passed to Graphiti, so a non-OpenAI-compatible embedding provider cannot be shared directly.
+
+#### Ingestion and Extraction Tuning
+
+The supplied defaults prioritize flow isolation and limit expensive extraction to useful events.
+
+Ingest policy actions:
+
+- `REJECT`: do not store the episode.
+- `SKIP_LLM`: store the episode for retrieval but do not extract nodes or edges.
+- `PROCESS`: store the episode and run full LLM extraction.
+
+| Variable | Default | When to change it |
+| --- | --- | --- |
+| `GRAPHITI_INGEST_POLICY_RULES` | `{"graphiti_search":"REJECT","tool_execution_terminal":"PROCESS","tool_execution_file":"PROCESS"}` | Add narrow, case-insensitive name/source patterns when specific events need different handling |
+| `GRAPHITI_INGEST_POLICY_FIELD` | `both` | Restrict matching to `name` or `source_description` only when event naming is controlled |
+| `GRAPHITI_INGEST_POLICY_DEFAULT_ACTION` | `SKIP_LLM` | Use `PROCESS` only when every unmatched event justifies extraction cost |
+| `GRAPHITI_INGEST_USE_GROUP_ACTORS` | `true` | Keep enabled to preserve FIFO ordering independently for each flow |
+| `GRAPHITI_INGEST_WORKER_COUNT` | `16` | Raise for more concurrent flows when the LLM and database have capacity; lower to control load |
+| `GRAPHITI_INGEST_LOCK_BY_GROUP_ID` | `true` | Used only in shared-pool mode; ignored when group actors are enabled |
+| `GRAPHITI_INGEST_TASK_MAX_RETRIES` | `1` (`0`-`5`) | Increase for transient LLM/network failures |
+| `GRAPHITI_INGEST_TASK_RETRY_DELAY_SEC` | `2.0` (`0.5`-`60`) | Increase when an upstream service needs more recovery time |
+| `GRAPHITI_INGEST_TASK_TIMEOUT_SEC` | `0` (`0`-`3600`) | Set a finite value to prevent one stalled request from blocking a flow; `0` disables the timeout |
+| `GRAPHITI_INGEST_QUEUE_MAX_SIZE` | `0` | Set a bound to return HTTP 429 instead of allowing an unlimited backlog |
+| `GRAPHITI_INGEST_DEAD_LETTER_ENABLED` | `false` | Enable when failed episodes must be retained for operational review |
+
+Extraction uses the following fallback order: full combined extraction (nodes, attributes, summaries, and edges in one call), regular combined extraction (nodes and edges), then separate node/edge extraction. Empty or failed combined results automatically fall back; these log messages are expected during normal operation.
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `GRAPHITI_TAXONOMY_LAYER_PROFILE` | `STRUCTURAL,EVIDENCE,PROGRESS,ATTEMPT` | Controls which edge classes appear in prompts and pass validation; `full`/`all` enables every class and `minimal` selects the core attack graph |
+| `GRAPHITI_USE_COMBINED_FULL_EXTRACTION` | `true` | Enables the most compact single-call extraction path |
+| `GRAPHITI_USE_COMBINED_EXTRACTION` | `true` | Enables the regular combined fallback |
+| `GRAPHITI_COMBINED_FULL_GATING_ENABLED` | `true` | Skips expensive full extraction for low-signal administrative/search events |
+| `GRAPHITI_COMBINED_DIAGNOSTIC_SAMPLES` | `false` | Includes content samples in diagnostics; keep disabled because pentest output can contain credentials |
+| `GRAPHITI_ANCHOR_NODE_MODE` | `smart` | `smart` loads all key entities plus limited high-volume types; `limit` applies one total cap |
+| `GRAPHITI_ANCHOR_NODE_LIMIT` | `25` (`1`-`500`) | Total anchor cap in `limit` mode |
+| `GRAPHITI_ANCHOR_MASS_TYPE_LIMIT` | `10` (`1`-`100`) | Per-type cap in `smart` mode; `0` is invalid |
+| `GRAPHITI_ANCHOR_QUERY_TIMEOUT` | `10` (`1`-`60`) | Bounds anchor lookup; timeout degrades gracefully to no anchors |
+
+Anchors connect entities across episodes and are used by the separate extraction path. Combined extraction has already produced its edges and does not perform this anchor lookup.
+
+These flags are passed as process environment variables by the bundled compose file. This is important for combined extraction because Graphiti reads those flags when Python modules are imported.
+
+#### Runtime, Logging, and Neo4j
+
+The values below are PentAGI's recommended `.env.example`/compose defaults, not the raw Graphiti image fallbacks. Running a freshly pulled image behind an old compose file can instead enable telemetry and global search, use one shared-pool worker with `PROCESS` as the unmatched ingest action, enable the full taxonomy, and disable combined extraction. Keep the image, compose file, `.env`, and presets in sync.
+
+| Variable | Default | Guidance |
+| --- | --- | --- |
+| `GRAPHITI_CPUS`, `GRAPHITI_MEMORY` | `2.0`, `2G` | Container limits; raise together with concurrency only after observing CPU and memory pressure |
+| `GRAPHITI_SEMAPHORE_LIMIT` | `20` | Limits parallel Graphiti coroutines; it is separate from ingest worker concurrency |
+| `GRAPHITI_TELEMETRY_ENABLED` | `false` | Enables anonymous Graphiti telemetry when set to `true` |
+| `GRAPHITI_LOG_LEVEL` | `INFO` | Use `DEBUG` temporarily; it can produce sensitive and high-volume output |
+| `GRAPHITI_LOG_STDOUT` | `events` | `off`, `events`, or `full`; `events` is recommended for containers |
+| `GRAPHITI_FLOW_LOGGER_WARN_COUNT` | `256` | Warns about growth of cached per-flow loggers; `0` disables the warning |
+| `GRAPHITI_DEBUG_RUNTIME_RESOURCES` | `false` | Enables `/debug/runtime-resources`; expose only to trusted operators |
+| `GRAPHITI_SEARCH_SCOPE` | `flowid` | Keep for flow/tenant isolation; `all` enables global searches and can expose other engagements |
+| `GRAPHITI_LOG_FORMAT` | `json` | Reserved by the current deployment contract; the Graphiti logger does not yet apply it |
+| `NEO4J_CPUS`, `NEO4J_MEMORY` | `4.0`, `4G` | Neo4j container limits; use `neo4j-admin server memory-recommendation --docker` for production sizing |
+| `NEO4J_SHM_SIZE` | `4g` | `/dev/shm` limit; actual use counts toward the container memory limit |
+| `NEO4J_NOFILE` | `65536` | Open-file soft/hard limit, suitable for many indexes and concurrent connections |
+
+`NEO4J_USER`, `NEO4J_PASSWORD`, `NEO4J_URI`, and `NEO4J_DATABASE` configure the bundled connection. Neo4j Community Edition supports only its default database; do not configure a separate database name that requires Enterprise multi-database support.
+
+The bundled stack currently wires Neo4j only. The Graphiti image contains FalkorDB support, but using it requires a separately configured deployment because the stock compose file does not expose `GRAPHITI_GRAPH_BACKEND` or `FALKORDB_*`.
+
+#### Verification and Troubleshooting
+
+Check service health, queue state, and logs:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose-graphiti.yml ps graphiti neo4j
+docker compose -f docker-compose.yml -f docker-compose-graphiti.yml logs -f graphiti
+curl -fsS http://localhost:8000/healthcheck
+curl -fsS http://localhost:8000/queue-size
+```
-When enabled, PentAGI automatically captures:
+Neo4j Browser is available at `http://localhost:7474`; the Graphiti OpenAPI UI is at `http://localhost:8000/docs`. Both are bound to localhost by the stock compose file.
-- **Agent Responses**: All agent reasoning, analysis, and decisions
-- **Tool Executions**: Commands executed, tools used, and their results
-- **Context Information**: Flow, task, and subtask hierarchy
+Common failures:
-#### Current Limitations
+- A missing API key or base URL for the selected preset, a missing YAML file, or a YAML `provider` mismatch causes the Graphiti container to fail startup validation.
+- `LLM_CLIENT_TYPE=openai` rejects local/custom model prefixes; use the `custom` preset for an OpenAI-compatible local server.
+- In `flowid` search mode, requests without a group ID are rejected. PentAGI supplies the flow-derived group ID automatically.
+- A bounded full queue returns HTTP 429. `/queue-size` reports waiting, processing, active-group, and dropped counters.
+- Invalid retry, timeout, or anchor ranges fail startup rather than being silently normalized.
-The Graphiti integration is currently a beta feature. Operators should plan around the following constraints before enabling it in production:
+Update `.env`, `docker-compose-graphiti.yml`, the Graphiti image, and the `graphiti` preset directory together. Pulling only a new image can retain older compose defaults and silently change extraction behavior.
-- **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.
+#### Limitations and Security
-When `GRAPHITI_ENABLED=false`, PentAGI continues to operate with its primary memory and vector store; only the additional knowledge graph features are skipped.
+- Graphiti is beta and has no in-app graph explorer.
+- One provider preset is active for the entire Graphiti deployment; it is not selected per PentAGI agent or flow.
+- Graphiti extraction, reranking, and embeddings incur billing independently of the model used by the main PentAGI flow.
+- Search is flow-scoped by default. Cross-flow reuse requires an explicit global-search design and must not be enabled on shared or multi-tenant deployments without additional isolation.
+- The Graphiti HTTP API has no authentication layer in the bundled service. The stock compose binds it and Neo4j to `127.0.0.1`; secure external deployments with network controls and authentication at a trusted reverse proxy.
+- Agent and tool output may contain credentials and exploitation evidence. Protect Neo4j data, logs, dead letters, diagnostics, and backups accordingly.
+- If Graphiti is unavailable, PentAGI continues with its primary memory and vector store after logging the failed startup health check. Set `GRAPHITI_ENABLED=false` to disable the integration explicitly.
### GitHub and Google OAuth Integration
diff --git a/backend/cmd/installer/files/links/graphiti b/backend/cmd/installer/files/links/graphiti
new file mode 120000
index 00000000..9bb4b3f6
--- /dev/null
+++ b/backend/cmd/installer/files/links/graphiti
@@ -0,0 +1 @@
+../../../../../examples/graphiti
\ No newline at end of file
diff --git a/backend/cmd/installer/processor/fs.go b/backend/cmd/installer/processor/fs.go
index 516d6134..5a2b1968 100644
--- a/backend/cmd/installer/processor/fs.go
+++ b/backend/cmd/installer/processor/fs.go
@@ -15,6 +15,7 @@ import (
const (
observabilityDirectory = "observability"
+ graphitiConfigsDirectory = "graphiti"
pentagiExampleCustomConfigLLM = "example.custom.provider.yml"
pentagiExampleOllamaConfigLLM = "example.ollama.provider.yml"
)
@@ -53,7 +54,9 @@ func (fs *fileSystemOperationsImpl) ensureStackIntegrity(ctx context.Context, st
return errors.Join(errCompose, errCustom, errOllama)
case ProductStackGraphiti:
- return fs.ensureFileFromEmbed(composeFileGraphiti, state)
+ errCompose := fs.ensureFileFromEmbed(composeFileGraphiti, state)
+ errConfigs := fs.ensureDirectoryFromEmbed(graphitiConfigsDirectory, state)
+ return errors.Join(errCompose, errConfigs)
case ProductStackLangfuse:
return fs.ensureFileFromEmbed(composeFileLangfuse, state)
@@ -86,7 +89,10 @@ func (fs *fileSystemOperationsImpl) verifyStackIntegrity(ctx context.Context, st
return fs.verifyFileIntegrity(composeFilePentagi, state)
case ProductStackGraphiti:
- return fs.verifyFileIntegrity(composeFileGraphiti, state)
+ if err := fs.verifyFileIntegrity(composeFileGraphiti, state); err != nil {
+ return err
+ }
+ return fs.verifyDirectoryIntegrity(graphitiConfigsDirectory, state)
case ProductStackLangfuse:
return fs.verifyFileIntegrity(composeFileLangfuse, state)
@@ -121,6 +127,11 @@ func (fs *fileSystemOperationsImpl) checkStackIntegrity(ctx context.Context, sta
case ProductStackGraphiti:
result[composeFileGraphiti] = fs.checkFileIntegrity(composeFileGraphiti)
+ if r, err := fs.checkDirectoryIntegrity(graphitiConfigsDirectory); err != nil {
+ return result, err
+ } else {
+ maps.Copy(result, r)
+ }
case ProductStackLangfuse:
result[composeFileLangfuse] = fs.checkFileIntegrity(composeFileLangfuse)
@@ -165,6 +176,7 @@ func (fs *fileSystemOperationsImpl) cleanupStackFiles(ctx context.Context, stack
case ProductStackGraphiti:
filesToRemove = append(filesToRemove, filepath.Join(workingDir, composeFileGraphiti))
+ filesToRemove = append(filesToRemove, filepath.Join(workingDir, graphitiConfigsDirectory))
case ProductStackLangfuse:
filesToRemove = append(filesToRemove, filepath.Join(workingDir, composeFileLangfuse))
diff --git a/backend/cmd/installer/processor/fs_test.go b/backend/cmd/installer/processor/fs_test.go
index d59bf058..9ec7559f 100644
--- a/backend/cmd/installer/processor/fs_test.go
+++ b/backend/cmd/installer/processor/fs_test.go
@@ -516,6 +516,10 @@ func TestCheckStackIntegrity(t *testing.T) {
m.statuses[composeFilePentagi] = files.FileStatusOK
// graphiti
m.statuses[composeFileGraphiti] = files.FileStatusOK
+ m.lists[graphitiConfigsDirectory] = []string{
+ "graphiti/openai.yaml",
+ }
+ m.statuses["graphiti/openai.yaml"] = files.FileStatusOK
// langfuse
m.statuses[composeFileLangfuse] = files.FileStatusModified
// observability
@@ -528,6 +532,7 @@ func TestCheckStackIntegrity(t *testing.T) {
expected: map[string]files.FileStatus{
composeFilePentagi: files.FileStatusOK,
composeFileGraphiti: files.FileStatusOK,
+ "graphiti/openai.yaml": files.FileStatusOK,
composeFileLangfuse: files.FileStatusModified,
composeFileObservability: files.FileStatusMissing,
"observability/config.yml": files.FileStatusOK,
@@ -541,6 +546,10 @@ func TestCheckStackIntegrity(t *testing.T) {
m.statuses[composeFilePentagi] = files.FileStatusOK
// graphiti
m.statuses[composeFileGraphiti] = files.FileStatusOK
+ m.lists[graphitiConfigsDirectory] = []string{
+ "graphiti/openai.yaml",
+ }
+ m.statuses["graphiti/openai.yaml"] = files.FileStatusOK
// langfuse
m.statuses[composeFileLangfuse] = files.FileStatusModified
// observability
@@ -553,6 +562,7 @@ func TestCheckStackIntegrity(t *testing.T) {
expected: map[string]files.FileStatus{
composeFilePentagi: files.FileStatusOK,
composeFileGraphiti: files.FileStatusOK,
+ "graphiti/openai.yaml": files.FileStatusOK,
composeFileLangfuse: files.FileStatusModified,
composeFileObservability: files.FileStatusMissing,
"observability/config.yml": files.FileStatusOK,
@@ -615,6 +625,10 @@ func TestCheckStackIntegrity_RealFiles(t *testing.T) {
// Setup comprehensive test scenario
mockFiles.statuses[composeFilePentagi] = files.FileStatusOK
mockFiles.statuses[composeFileGraphiti] = files.FileStatusOK
+ mockFiles.lists[graphitiConfigsDirectory] = []string{
+ "graphiti/openai.yaml",
+ }
+ mockFiles.statuses["graphiti/openai.yaml"] = files.FileStatusOK
mockFiles.statuses[composeFileLangfuse] = files.FileStatusModified
mockFiles.statuses[composeFileObservability] = files.FileStatusMissing
mockFiles.lists[observabilityDirectory] = []string{
@@ -637,7 +651,7 @@ func TestCheckStackIntegrity_RealFiles(t *testing.T) {
}
// Verify all files are captured
- expectedCount := 6 // 4 compose files + 2 observability directory files
+ expectedCount := 7 // 4 compose files + 1 Graphiti config + 2 observability files
if len(result) != expectedCount {
t.Errorf("expected %d files, got %d", expectedCount, len(result))
}
diff --git a/backend/cmd/installer/wizard/controller/controller.go b/backend/cmd/installer/wizard/controller/controller.go
index 0c897e94..d7ba51cb 100644
--- a/backend/cmd/installer/wizard/controller/controller.go
+++ b/backend/cmd/installer/wizard/controller/controller.go
@@ -771,13 +771,30 @@ type GraphitiConfig struct {
// integration settings (always)
GraphitiURL loader.EnvVar // GRAPHITI_URL
Timeout loader.EnvVar // GRAPHITI_TIMEOUT
- ModelName loader.EnvVar // GRAPHITI_MODEL_NAME
+
+ // graphiti sidecar settings (embedded only)
+ LLMClientType loader.EnvVar // GRAPHITI_LLM_CLIENT_TYPE
+ SeparateEmbedding loader.EnvVar // GRAPHITI_SEPARATE_EMBEDDING
+ SemaphoreLimit loader.EnvVar // GRAPHITI_SEMAPHORE_LIMIT
+ LogLevel loader.EnvVar // GRAPHITI_LOG_LEVEL
+ SearchScope loader.EnvVar // GRAPHITI_SEARCH_SCOPE
+ IngestPolicyRules loader.EnvVar // GRAPHITI_INGEST_POLICY_RULES
+ IngestPolicyField loader.EnvVar // GRAPHITI_INGEST_POLICY_FIELD
+ IngestPolicyDefaultAction loader.EnvVar // GRAPHITI_INGEST_POLICY_DEFAULT_ACTION
+ IngestWorkerCount loader.EnvVar // GRAPHITI_INGEST_WORKER_COUNT
+ IngestQueueMaxSize loader.EnvVar // GRAPHITI_INGEST_QUEUE_MAX_SIZE
+ TaxonomyLayerProfile loader.EnvVar // GRAPHITI_TAXONOMY_LAYER_PROFILE
+ GraphitiCPUs loader.EnvVar // GRAPHITI_CPUS
+ GraphitiMemory loader.EnvVar // GRAPHITI_MEMORY
// neo4j settings (embedded only)
Neo4jUser loader.EnvVar // NEO4J_USER
Neo4jPassword loader.EnvVar // NEO4J_PASSWORD
Neo4jDatabase loader.EnvVar // NEO4J_DATABASE
Neo4jURI loader.EnvVar // NEO4J_URI
+ Neo4jCPUs loader.EnvVar // NEO4J_CPUS
+ Neo4jMemory loader.EnvVar // NEO4J_MEMORY
+ Neo4jShmSize loader.EnvVar // NEO4J_SHM_SIZE
// computed fields (not directly mapped to env vars)
Installed bool
@@ -788,37 +805,57 @@ func (c *controller) GetGraphitiConfig() *GraphitiConfig {
vars, _ := c.GetVars([]string{
"GRAPHITI_URL",
"GRAPHITI_TIMEOUT",
- "GRAPHITI_MODEL_NAME",
+ "GRAPHITI_LLM_CLIENT_TYPE",
+ "GRAPHITI_SEPARATE_EMBEDDING",
+ "GRAPHITI_SEMAPHORE_LIMIT",
+ "GRAPHITI_LOG_LEVEL",
+ "GRAPHITI_SEARCH_SCOPE",
+ "GRAPHITI_INGEST_POLICY_RULES",
+ "GRAPHITI_INGEST_POLICY_FIELD",
+ "GRAPHITI_INGEST_POLICY_DEFAULT_ACTION",
+ "GRAPHITI_INGEST_WORKER_COUNT",
+ "GRAPHITI_INGEST_QUEUE_MAX_SIZE",
+ "GRAPHITI_TAXONOMY_LAYER_PROFILE",
+ "GRAPHITI_CPUS",
+ "GRAPHITI_MEMORY",
"NEO4J_USER",
"NEO4J_PASSWORD",
"NEO4J_DATABASE",
"NEO4J_URI",
+ "NEO4J_CPUS",
+ "NEO4J_MEMORY",
+ "NEO4J_SHM_SIZE",
})
// set defaults if missing
- if v := vars["GRAPHITI_TIMEOUT"]; v.Default == "" {
- v.Default = "30"
- vars["GRAPHITI_TIMEOUT"] = v
- }
- if v := vars["GRAPHITI_MODEL_NAME"]; v.Default == "" {
- v.Default = "gpt-5-mini"
- vars["GRAPHITI_MODEL_NAME"] = v
- }
- if v := vars["NEO4J_USER"]; v.Default == "" {
- v.Default = "neo4j"
- vars["NEO4J_USER"] = v
- }
- if v := vars["NEO4J_PASSWORD"]; v.Default == "" {
- v.Default = "devpassword"
- vars["NEO4J_PASSWORD"] = v
- }
- if v := vars["NEO4J_DATABASE"]; v.Default == "" {
- v.Default = "neo4j"
- vars["NEO4J_DATABASE"] = v
- }
- if v := vars["NEO4J_URI"]; v.Default == "" {
- v.Default = "bolt://neo4j:7687"
- vars["NEO4J_URI"] = v
+ defaults := map[string]string{
+ "GRAPHITI_TIMEOUT": "30",
+ "GRAPHITI_LLM_CLIENT_TYPE": "openai",
+ "GRAPHITI_SEPARATE_EMBEDDING": "false",
+ "GRAPHITI_SEMAPHORE_LIMIT": "20",
+ "GRAPHITI_LOG_LEVEL": "INFO",
+ "GRAPHITI_SEARCH_SCOPE": "flowid",
+ "GRAPHITI_INGEST_POLICY_RULES": `{"graphiti_search":"REJECT","tool_execution_terminal":"PROCESS","tool_execution_file":"PROCESS"}`,
+ "GRAPHITI_INGEST_POLICY_FIELD": "both",
+ "GRAPHITI_INGEST_POLICY_DEFAULT_ACTION": "SKIP_LLM",
+ "GRAPHITI_INGEST_WORKER_COUNT": "16",
+ "GRAPHITI_INGEST_QUEUE_MAX_SIZE": "0",
+ "GRAPHITI_TAXONOMY_LAYER_PROFILE": "STRUCTURAL,EVIDENCE,PROGRESS,ATTEMPT",
+ "GRAPHITI_CPUS": "2.0",
+ "GRAPHITI_MEMORY": "2G",
+ "NEO4J_USER": "neo4j",
+ "NEO4J_PASSWORD": "devpassword",
+ "NEO4J_DATABASE": "neo4j",
+ "NEO4J_URI": "bolt://neo4j:7687",
+ "NEO4J_CPUS": "4.0",
+ "NEO4J_MEMORY": "4G",
+ "NEO4J_SHM_SIZE": "4g",
+ }
+ for name, defaultValue := range defaults {
+ if v := vars[name]; v.Default == "" {
+ v.Default = defaultValue
+ vars[name] = v
+ }
}
graphitiURL := vars["GRAPHITI_URL"]
@@ -836,15 +873,30 @@ func (c *controller) GetGraphitiConfig() *GraphitiConfig {
}
return &GraphitiConfig{
- DeploymentType: deploymentType,
- GraphitiURL: graphitiURL,
- Timeout: vars["GRAPHITI_TIMEOUT"],
- ModelName: vars["GRAPHITI_MODEL_NAME"],
- Neo4jUser: vars["NEO4J_USER"],
- Neo4jPassword: vars["NEO4J_PASSWORD"],
- Neo4jDatabase: vars["NEO4J_DATABASE"],
- Neo4jURI: vars["NEO4J_URI"],
- Installed: c.checker.GraphitiInstalled,
+ DeploymentType: deploymentType,
+ GraphitiURL: graphitiURL,
+ Timeout: vars["GRAPHITI_TIMEOUT"],
+ LLMClientType: vars["GRAPHITI_LLM_CLIENT_TYPE"],
+ SeparateEmbedding: vars["GRAPHITI_SEPARATE_EMBEDDING"],
+ SemaphoreLimit: vars["GRAPHITI_SEMAPHORE_LIMIT"],
+ LogLevel: vars["GRAPHITI_LOG_LEVEL"],
+ SearchScope: vars["GRAPHITI_SEARCH_SCOPE"],
+ IngestPolicyRules: vars["GRAPHITI_INGEST_POLICY_RULES"],
+ IngestPolicyField: vars["GRAPHITI_INGEST_POLICY_FIELD"],
+ IngestPolicyDefaultAction: vars["GRAPHITI_INGEST_POLICY_DEFAULT_ACTION"],
+ IngestWorkerCount: vars["GRAPHITI_INGEST_WORKER_COUNT"],
+ IngestQueueMaxSize: vars["GRAPHITI_INGEST_QUEUE_MAX_SIZE"],
+ TaxonomyLayerProfile: vars["GRAPHITI_TAXONOMY_LAYER_PROFILE"],
+ GraphitiCPUs: vars["GRAPHITI_CPUS"],
+ GraphitiMemory: vars["GRAPHITI_MEMORY"],
+ Neo4jUser: vars["NEO4J_USER"],
+ Neo4jPassword: vars["NEO4J_PASSWORD"],
+ Neo4jDatabase: vars["NEO4J_DATABASE"],
+ Neo4jURI: vars["NEO4J_URI"],
+ Neo4jCPUs: vars["NEO4J_CPUS"],
+ Neo4jMemory: vars["NEO4J_MEMORY"],
+ Neo4jShmSize: vars["NEO4J_SHM_SIZE"],
+ Installed: c.checker.GraphitiInstalled,
}
}
@@ -855,56 +907,58 @@ func (c *controller) UpdateGraphitiConfig(config *GraphitiConfig) error {
}
// set deployment type based configuration
+ vars := map[string]string{}
switch config.DeploymentType {
case "embedded":
// for embedded mode, use default endpoint
config.GraphitiURL.Value = checker.DefaultGraphitiEndpoint
-
- // enable Graphiti
- if err := c.SetVar("GRAPHITI_ENABLED", "true"); err != nil {
- return fmt.Errorf("failed to set GRAPHITI_ENABLED: %w", err)
- }
-
- // update timeout, model, and neo4j settings
- if err := c.SetVar("GRAPHITI_TIMEOUT", config.Timeout.Value); err != nil {
- return fmt.Errorf("failed to set GRAPHITI_TIMEOUT: %w", err)
- }
- if err := c.SetVar("GRAPHITI_MODEL_NAME", config.ModelName.Value); err != nil {
- return fmt.Errorf("failed to set GRAPHITI_MODEL_NAME: %w", err)
- }
- if err := c.SetVar("NEO4J_USER", config.Neo4jUser.Value); err != nil {
- return fmt.Errorf("failed to set NEO4J_USER: %w", err)
- }
- if err := c.SetVar("NEO4J_PASSWORD", config.Neo4jPassword.Value); err != nil {
- return fmt.Errorf("failed to set NEO4J_PASSWORD: %w", err)
- }
- if err := c.SetVar("NEO4J_DATABASE", config.Neo4jDatabase.Value); err != nil {
- return fmt.Errorf("failed to set NEO4J_DATABASE: %w", err)
+ vars = map[string]string{
+ "GRAPHITI_ENABLED": "true",
+ "GRAPHITI_URL": config.GraphitiURL.Value,
+ "GRAPHITI_TIMEOUT": config.Timeout.Value,
+ "GRAPHITI_LLM_CLIENT_TYPE": config.LLMClientType.Value,
+ "GRAPHITI_SEPARATE_EMBEDDING": config.SeparateEmbedding.Value,
+ "GRAPHITI_SEMAPHORE_LIMIT": config.SemaphoreLimit.Value,
+ "GRAPHITI_LOG_LEVEL": config.LogLevel.Value,
+ "GRAPHITI_SEARCH_SCOPE": config.SearchScope.Value,
+ "GRAPHITI_INGEST_POLICY_RULES": config.IngestPolicyRules.Value,
+ "GRAPHITI_INGEST_POLICY_FIELD": config.IngestPolicyField.Value,
+ "GRAPHITI_INGEST_POLICY_DEFAULT_ACTION": config.IngestPolicyDefaultAction.Value,
+ "GRAPHITI_INGEST_WORKER_COUNT": config.IngestWorkerCount.Value,
+ "GRAPHITI_INGEST_QUEUE_MAX_SIZE": config.IngestQueueMaxSize.Value,
+ "GRAPHITI_TAXONOMY_LAYER_PROFILE": config.TaxonomyLayerProfile.Value,
+ "GRAPHITI_CPUS": config.GraphitiCPUs.Value,
+ "GRAPHITI_MEMORY": config.GraphitiMemory.Value,
+ "NEO4J_USER": config.Neo4jUser.Value,
+ "NEO4J_PASSWORD": config.Neo4jPassword.Value,
+ "NEO4J_DATABASE": config.Neo4jDatabase.Value,
+ "NEO4J_CPUS": config.Neo4jCPUs.Value,
+ "NEO4J_MEMORY": config.Neo4jMemory.Value,
+ "NEO4J_SHM_SIZE": config.Neo4jShmSize.Value,
}
case "external":
// for external mode, use provided endpoint
- // enable Graphiti
- if err := c.SetVar("GRAPHITI_ENABLED", "true"); err != nil {
- return fmt.Errorf("failed to set GRAPHITI_ENABLED: %w", err)
- }
-
- // update timeout only (model is configured on external server)
- if err := c.SetVar("GRAPHITI_TIMEOUT", config.Timeout.Value); err != nil {
- return fmt.Errorf("failed to set GRAPHITI_TIMEOUT: %w", err)
+ vars = map[string]string{
+ "GRAPHITI_ENABLED": "true",
+ "GRAPHITI_URL": config.GraphitiURL.Value,
+ "GRAPHITI_TIMEOUT": config.Timeout.Value,
}
case "disabled":
// for disabled mode, disable Graphiti
- if err := c.SetVar("GRAPHITI_ENABLED", "false"); err != nil {
- return fmt.Errorf("failed to set GRAPHITI_ENABLED: %w", err)
- }
config.GraphitiURL.Value = ""
+ vars = map[string]string{
+ "GRAPHITI_ENABLED": "false",
+ "GRAPHITI_URL": "",
+ }
+
+ default:
+ return fmt.Errorf("unsupported Graphiti deployment type: %s", config.DeploymentType)
}
- // update integration environment variables
- if err := c.SetVar("GRAPHITI_URL", config.GraphitiURL.Value); err != nil {
- return fmt.Errorf("failed to set GRAPHITI_URL: %w", err)
+ if err := c.SetVars(vars); err != nil {
+ return fmt.Errorf("failed to update Graphiti configuration: %w", err)
}
return nil
@@ -915,11 +969,27 @@ func (c *controller) ResetGraphitiConfig() *GraphitiConfig {
"GRAPHITI_ENABLED",
"GRAPHITI_URL",
"GRAPHITI_TIMEOUT",
- "GRAPHITI_MODEL_NAME",
+ "GRAPHITI_LLM_CLIENT_TYPE",
+ "GRAPHITI_SEPARATE_EMBEDDING",
+ "GRAPHITI_SEMAPHORE_LIMIT",
+ "GRAPHITI_LOG_LEVEL",
+ "GRAPHITI_SEARCH_SCOPE",
+ "GRAPHITI_INGEST_POLICY_RULES",
+ "GRAPHITI_INGEST_POLICY_FIELD",
+ "GRAPHITI_INGEST_POLICY_DEFAULT_ACTION",
+ "GRAPHITI_INGEST_WORKER_COUNT",
+ "GRAPHITI_INGEST_QUEUE_MAX_SIZE",
+ "GRAPHITI_TAXONOMY_LAYER_PROFILE",
+ "GRAPHITI_CPUS",
+ "GRAPHITI_MEMORY",
"NEO4J_USER",
"NEO4J_PASSWORD",
"NEO4J_DATABASE",
"NEO4J_URI",
+ "NEO4J_CPUS",
+ "NEO4J_MEMORY",
+ "NEO4J_SHM_SIZE",
+ "GRAPHITI_MODEL_NAME", // remove obsolete values written by older installers
}
if err := c.ResetVars(vars); err != nil {
@@ -2425,11 +2495,27 @@ func (c *controller) getVariableDescription(varName string) string {
"LANGFUSE_EE_LICENSE_KEY": locale.EnvDesc_LANGFUSE_EE_LICENSE_KEY,
- "GRAPHITI_URL": locale.EnvDesc_GRAPHITI_URL,
- "GRAPHITI_TIMEOUT": locale.EnvDesc_GRAPHITI_TIMEOUT,
- "GRAPHITI_MODEL_NAME": locale.EnvDesc_GRAPHITI_MODEL_NAME,
- "NEO4J_USER": locale.EnvDesc_NEO4J_USER,
- "NEO4J_DATABASE": locale.EnvDesc_NEO4J_DATABASE,
+ "GRAPHITI_ENABLED": locale.EnvDesc_GRAPHITI_ENABLED,
+ "GRAPHITI_URL": locale.EnvDesc_GRAPHITI_URL,
+ "GRAPHITI_TIMEOUT": locale.EnvDesc_GRAPHITI_TIMEOUT,
+ "GRAPHITI_LLM_CLIENT_TYPE": locale.EnvDesc_GRAPHITI_LLM_CLIENT_TYPE,
+ "GRAPHITI_SEPARATE_EMBEDDING": locale.EnvDesc_GRAPHITI_SEPARATE_EMBEDDING,
+ "GRAPHITI_SEMAPHORE_LIMIT": locale.EnvDesc_GRAPHITI_SEMAPHORE_LIMIT,
+ "GRAPHITI_LOG_LEVEL": locale.EnvDesc_GRAPHITI_LOG_LEVEL,
+ "GRAPHITI_SEARCH_SCOPE": locale.EnvDesc_GRAPHITI_SEARCH_SCOPE,
+ "GRAPHITI_INGEST_POLICY_RULES": locale.EnvDesc_GRAPHITI_INGEST_POLICY_RULES,
+ "GRAPHITI_INGEST_POLICY_FIELD": locale.EnvDesc_GRAPHITI_INGEST_POLICY_FIELD,
+ "GRAPHITI_INGEST_POLICY_DEFAULT_ACTION": locale.EnvDesc_GRAPHITI_INGEST_POLICY_DEFAULT_ACTION,
+ "GRAPHITI_INGEST_WORKER_COUNT": locale.EnvDesc_GRAPHITI_INGEST_WORKER_COUNT,
+ "GRAPHITI_INGEST_QUEUE_MAX_SIZE": locale.EnvDesc_GRAPHITI_INGEST_QUEUE_MAX_SIZE,
+ "GRAPHITI_TAXONOMY_LAYER_PROFILE": locale.EnvDesc_GRAPHITI_TAXONOMY_LAYER_PROFILE,
+ "GRAPHITI_CPUS": locale.EnvDesc_GRAPHITI_CPUS,
+ "GRAPHITI_MEMORY": locale.EnvDesc_GRAPHITI_MEMORY,
+ "NEO4J_USER": locale.EnvDesc_NEO4J_USER,
+ "NEO4J_DATABASE": locale.EnvDesc_NEO4J_DATABASE,
+ "NEO4J_CPUS": locale.EnvDesc_NEO4J_CPUS,
+ "NEO4J_MEMORY": locale.EnvDesc_NEO4J_MEMORY,
+ "NEO4J_SHM_SIZE": locale.EnvDesc_NEO4J_SHM_SIZE,
"PENTAGI_POSTGRES_PASSWORD": locale.EnvDesc_PENTAGI_POSTGRES_PASSWORD,
"NEO4J_PASSWORD": locale.EnvDesc_NEO4J_PASSWORD,
@@ -2611,9 +2697,28 @@ var criticalVariables = map[string]bool{
"OTEL_HOST": true,
// graphiti changes
- "GRAPHITI_URL": true,
- "GRAPHITI_TIMEOUT": true,
- "GRAPHITI_MODEL_NAME": true,
+ "GRAPHITI_ENABLED": true,
+ "GRAPHITI_URL": true,
+ "GRAPHITI_TIMEOUT": true,
+ "GRAPHITI_LLM_CLIENT_TYPE": true,
+ "GRAPHITI_SEPARATE_EMBEDDING": true,
+ "GRAPHITI_SEMAPHORE_LIMIT": true,
+ "GRAPHITI_LOG_LEVEL": true,
+ "GRAPHITI_SEARCH_SCOPE": true,
+ "GRAPHITI_INGEST_POLICY_RULES": true,
+ "GRAPHITI_INGEST_POLICY_FIELD": true,
+ "GRAPHITI_INGEST_POLICY_DEFAULT_ACTION": true,
+ "GRAPHITI_INGEST_WORKER_COUNT": true,
+ "GRAPHITI_INGEST_QUEUE_MAX_SIZE": true,
+ "GRAPHITI_TAXONOMY_LAYER_PROFILE": true,
+ "GRAPHITI_CPUS": true,
+ "GRAPHITI_MEMORY": true,
+ "NEO4J_USER": true,
+ "NEO4J_PASSWORD": true,
+ "NEO4J_DATABASE": true,
+ "NEO4J_CPUS": true,
+ "NEO4J_MEMORY": true,
+ "NEO4J_SHM_SIZE": true,
// server settings changes
"ASK_USER": true,
diff --git a/backend/cmd/installer/wizard/locale/locale.go b/backend/cmd/installer/wizard/locale/locale.go
index d8ec1f78..82e5883f 100644
--- a/backend/cmd/installer/wizard/locale/locale.go
+++ b/backend/cmd/installer/wizard/locale/locale.go
@@ -838,9 +838,9 @@ Graphiti provides temporal knowledge graph capabilities:
• Entity and relationship extraction
• Semantic memory for AI agents
• Temporal context tracking
-• Knowledge reuse across flows
+• Flow-scoped contextual search
-⚠️ REQUIREMENT: Graphiti requires configured OpenAI provider (LLM Providers → OpenAI) for entity extraction.
+Graphiti reuses credentials configured in the LLM Providers and Embeddings screens. LiteLLM credentials remain in .env. Select the provider preset here; configure its models in ./graphiti/<provider>.yaml.
Choose between embedded instance or external connection.`
@@ -850,20 +850,50 @@ Choose between embedded instance or external connection.`
MonitoringGraphitiDisabled = "Disabled"
// Form fields
- MonitoringGraphitiDeploymentType = "Deployment Type"
- MonitoringGraphitiDeploymentTypeDesc = "Select the deployment type for Graphiti"
- MonitoringGraphitiURL = "Graphiti Server URL"
- MonitoringGraphitiURLDesc = "Address of the Graphiti API server"
- MonitoringGraphitiTimeout = "Request Timeout"
- MonitoringGraphitiTimeoutDesc = "Timeout in seconds for Graphiti operations"
- MonitoringGraphitiModelName = "Extraction Model"
- MonitoringGraphitiModelNameDesc = "LLM model for entity extraction (uses OpenAI provider from LLM Providers configuration)"
- MonitoringGraphitiNeo4jUser = "Neo4j Username"
- MonitoringGraphitiNeo4jUserDesc = "Username for Neo4j database access"
- MonitoringGraphitiNeo4jPassword = "Neo4j Password"
- MonitoringGraphitiNeo4jPasswordDesc = "Password for Neo4j database access"
- MonitoringGraphitiNeo4jDatabase = "Neo4j Database"
- MonitoringGraphitiNeo4jDatabaseDesc = "Neo4j database name"
+ MonitoringGraphitiDeploymentType = "Deployment Type"
+ MonitoringGraphitiDeploymentTypeDesc = "Select the deployment type for Graphiti"
+ MonitoringGraphitiURL = "Graphiti Server URL"
+ MonitoringGraphitiURLDesc = "Address of the Graphiti API server"
+ MonitoringGraphitiTimeout = "Request Timeout"
+ MonitoringGraphitiTimeoutDesc = "Timeout in seconds for Graphiti operations"
+ MonitoringGraphitiLLMClientType = "LLM Provider Preset"
+ MonitoringGraphitiLLMClientTypeDesc = "Provider preset; credentials come from LLM Providers (LiteLLM from .env) and models from ./graphiti/<provider>.yaml"
+ MonitoringGraphitiSeparateEmbedding = "Use Separate Embedding Endpoint"
+ MonitoringGraphitiSeparateEmbeddingDesc = "Use the shared Embeddings configuration instead of the selected LLM credentials"
+ MonitoringGraphitiSemaphoreLimit = "Coroutine Limit"
+ MonitoringGraphitiSemaphoreLimitDesc = "Maximum concurrent Graphiti helper coroutines"
+ MonitoringGraphitiLogLevel = "Log Level"
+ MonitoringGraphitiLogLevelDesc = "Graphiti log verbosity"
+ MonitoringGraphitiSearchScope = "Search Scope"
+ MonitoringGraphitiSearchScopeDesc = "Use flowid for isolation or all for trusted global-search testing"
+ MonitoringGraphitiIngestPolicyRules = "Ingest Policy Rules"
+ MonitoringGraphitiIngestPolicyRulesDesc = "JSON mapping of message patterns to REJECT, SKIP_LLM, or PROCESS"
+ MonitoringGraphitiIngestPolicyField = "Ingest Policy Match Field"
+ MonitoringGraphitiIngestPolicyFieldDesc = "Message field used for policy matching"
+ MonitoringGraphitiIngestDefaultAction = "Default Ingest Action"
+ MonitoringGraphitiIngestDefaultActionDesc = "Action applied when no ingest policy rule matches"
+ MonitoringGraphitiIngestWorkerCount = "Ingest Worker Count"
+ MonitoringGraphitiIngestWorkerCountDesc = "Maximum concurrent heavy ingest jobs across flows"
+ MonitoringGraphitiIngestQueueMaxSize = "Ingest Queue Limit"
+ MonitoringGraphitiIngestQueueMaxSizeDesc = "Maximum queued messages; 0 keeps the queue unlimited"
+ MonitoringGraphitiTaxonomyLayerProfile = "Taxonomy Layer Profile"
+ MonitoringGraphitiTaxonomyLayerProfileDesc = "Enabled relationship classes or the full/minimal alias"
+ MonitoringGraphitiCPUs = "Graphiti CPU Limit"
+ MonitoringGraphitiCPUsDesc = "CPU limit for the Graphiti container"
+ MonitoringGraphitiMemory = "Graphiti Memory Limit"
+ MonitoringGraphitiMemoryDesc = "Memory limit for the Graphiti container"
+ MonitoringGraphitiNeo4jUser = "Neo4j Username"
+ MonitoringGraphitiNeo4jUserDesc = "Username for Neo4j database access"
+ MonitoringGraphitiNeo4jPassword = "Neo4j Password"
+ MonitoringGraphitiNeo4jPasswordDesc = "Password for Neo4j database access"
+ MonitoringGraphitiNeo4jDatabase = "Neo4j Database"
+ MonitoringGraphitiNeo4jDatabaseDesc = "Neo4j database name"
+ MonitoringGraphitiNeo4jCPUs = "Neo4j CPU Limit"
+ MonitoringGraphitiNeo4jCPUsDesc = "CPU limit for the Neo4j container"
+ MonitoringGraphitiNeo4jMemory = "Neo4j Memory Limit"
+ MonitoringGraphitiNeo4jMemoryDesc = "Memory limit for the Neo4j container"
+ MonitoringGraphitiNeo4jShmSize = "Neo4j Shared Memory Limit"
+ MonitoringGraphitiNeo4jShmSizeDesc = "/dev/shm limit; actual usage counts toward Neo4j memory"
// Help text
MonitoringGraphitiModeGuide = "Choose deployment: Embedded (local Neo4j), External (existing Graphiti), Disabled (no knowledge graph)"
@@ -877,16 +907,20 @@ Embedded deploys complete Graphiti stack:
• Private knowledge graph on your server
Prerequisites:
-• OpenAI provider must be configured (LLM Providers → OpenAI)
-• OpenAI API key is used for entity extraction
-• Configured model will be used for knowledge graph operations
+• Configure provider credentials in LLM Providers (or .env for LiteLLM)
+• Configure shared embeddings before enabling separate embeddings
+• Edit models and call parameters in ./graphiti/<provider>.yaml
Resource requirements:
-• ~1.5GB RAM, 3GB disk space minimum
+• Defaults reserve up to 2GB for Graphiti and 4GB for Neo4j
• Neo4j UI: http://localhost:7474
• Graphiti API: http://localhost:8000
• Automatic setup and maintenance
+Keep flowid search scope for isolation. Use a bounded ingest queue on memory-constrained hosts. Semaphore/workers control throughput; Graphiti and Neo4j CPU/memory limits must grow with concurrent flows.
+
+Fine tuning for retries, combined extraction, anchors, telemetry, and diagnostics remains available in .env.
+
Best for: Teams wanting knowledge graph capabilities with full data control and privacy.`
MonitoringGraphitiExternalHelp = `⚠️ BETA: This feature is under active development. Monitor updates for improvements.
@@ -900,8 +934,7 @@ External connects to your existing Graphiti server:
Setup requirements:
• Graphiti server URL and access
• Network connectivity required
-• External server must be configured with OpenAI API key
-• Model and extraction settings configured on external server
+• Provider, model, embedding, extraction, and graph settings are configured on the external server
Best for: Teams using existing Graphiti deployments or cloud services.`
MonitoringGraphitiDisabledHelp = `Graphiti is disabled. You will not have:
@@ -909,13 +942,10 @@ Best for: Teams using existing Graphiti deployments or cloud services.`
• Temporal knowledge graph
• Entity and relationship extraction
• Semantic memory for AI agents
-• Knowledge reuse across flows
+• Flow-scoped graph recall
• Advanced contextual search
-Note: Graphiti is currently in beta.
-Consider enabling for production use
-to build a knowledge base from
-penetration testing results.`
+PentAGI continues using its primary vector memory when Graphiti is disabled.`
)
// Observability Integration constants
@@ -2472,12 +2502,28 @@ const (
EnvDesc_LANGFUSE_EE_LICENSE_KEY = "Langfuse Enterprise License Key"
EnvDesc_PENTAGI_POSTGRES_PASSWORD = "PentAGI PostgreSQL Password"
- EnvDesc_GRAPHITI_URL = "Graphiti Server URL"
- EnvDesc_GRAPHITI_TIMEOUT = "Graphiti Request Timeout"
- EnvDesc_GRAPHITI_MODEL_NAME = "Graphiti Extraction Model"
- EnvDesc_NEO4J_USER = "Neo4j Username"
- EnvDesc_NEO4J_DATABASE = "Neo4j Database Name"
- EnvDesc_NEO4J_PASSWORD = "Neo4j Database Password"
+ EnvDesc_GRAPHITI_ENABLED = "Enable Graphiti Integration"
+ EnvDesc_GRAPHITI_URL = "Graphiti Server URL"
+ EnvDesc_GRAPHITI_TIMEOUT = "Graphiti Request Timeout"
+ EnvDesc_GRAPHITI_LLM_CLIENT_TYPE = "Graphiti LLM Provider Preset"
+ EnvDesc_GRAPHITI_SEPARATE_EMBEDDING = "Graphiti Separate Embedding Endpoint"
+ EnvDesc_GRAPHITI_SEMAPHORE_LIMIT = "Graphiti Coroutine Limit"
+ EnvDesc_GRAPHITI_LOG_LEVEL = "Graphiti Log Level"
+ EnvDesc_GRAPHITI_SEARCH_SCOPE = "Graphiti Search Scope"
+ EnvDesc_GRAPHITI_INGEST_POLICY_RULES = "Graphiti Ingest Policy Rules"
+ EnvDesc_GRAPHITI_INGEST_POLICY_FIELD = "Graphiti Ingest Policy Match Field"
+ EnvDesc_GRAPHITI_INGEST_POLICY_DEFAULT_ACTION = "Graphiti Default Ingest Action"
+ EnvDesc_GRAPHITI_INGEST_WORKER_COUNT = "Graphiti Ingest Worker Count"
+ EnvDesc_GRAPHITI_INGEST_QUEUE_MAX_SIZE = "Graphiti Ingest Queue Limit"
+ EnvDesc_GRAPHITI_TAXONOMY_LAYER_PROFILE = "Graphiti Taxonomy Layer Profile"
+ EnvDesc_GRAPHITI_CPUS = "Graphiti CPU Limit"
+ EnvDesc_GRAPHITI_MEMORY = "Graphiti Memory Limit"
+ EnvDesc_NEO4J_USER = "Neo4j Username"
+ EnvDesc_NEO4J_DATABASE = "Neo4j Database Name"
+ EnvDesc_NEO4J_PASSWORD = "Neo4j Database Password"
+ EnvDesc_NEO4J_CPUS = "Neo4j CPU Limit"
+ EnvDesc_NEO4J_MEMORY = "Neo4j Memory Limit"
+ EnvDesc_NEO4J_SHM_SIZE = "Neo4j Shared Memory Limit"
)
// dynamic, contextual sections used in processor operation forms
diff --git a/backend/cmd/installer/wizard/models/graphiti_form.go b/backend/cmd/installer/wizard/models/graphiti_form.go
index 2a555341..ba827241 100644
--- a/backend/cmd/installer/wizard/models/graphiti_form.go
+++ b/backend/cmd/installer/wizard/models/graphiti_form.go
@@ -1,7 +1,10 @@
package models
import (
+ "encoding/json"
"fmt"
+ "net/url"
+ "strconv"
"strings"
"pentagi/cmd/installer/loader"
@@ -14,13 +17,33 @@ import (
"github.com/charmbracelet/bubbles/list"
tea "github.com/charmbracelet/bubbletea"
"github.com/charmbracelet/lipgloss"
+ "github.com/docker/go-units"
)
const (
GraphitiURLPlaceholder = "http://graphiti:8000"
GraphitiTimeoutPlaceholder = "30"
- GraphitiModelNamePlaceholder = "gpt-5-mini"
GraphitiNeo4jUserPlaceholder = "neo4j"
+
+ graphitiSemaphoreMin = 1
+ graphitiSemaphoreMax = 10000
+ graphitiWorkersMin = 1
+ graphitiWorkersMax = 1024
+ graphitiQueueMin = 0
+ graphitiQueueMax = 2147483647
+)
+
+var (
+ graphitiProviderPresets = []string{"openai", "gemini", "custom", "litellm"}
+ graphitiLogLevels = []string{"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
+ graphitiSearchScopes = []string{"flowid", "all"}
+ graphitiPolicyFields = []string{"name", "source_description", "both"}
+ graphitiPolicyActions = []string{"REJECT", "SKIP_LLM", "PROCESS"}
+ graphitiTaxonomySuggestions = []string{
+ "STRUCTURAL,EVIDENCE,PROGRESS,ATTEMPT",
+ "minimal",
+ "full",
+ }
)
// GraphitiFormModel represents the Graphiti configuration form
@@ -81,12 +104,52 @@ func (m *GraphitiFormModel) BuildForm() tea.Cmd {
switch deploymentType {
case "embedded":
- // Embedded mode - requires timeout, model, and neo4j credentials
- fields = append(fields, m.createTextField(config, "timeout",
+ fields = append(fields, m.createIntegerField(config, "timeout",
locale.MonitoringGraphitiTimeout, locale.MonitoringGraphitiTimeoutDesc, false, GraphitiTimeoutPlaceholder,
+ 1, 3600,
+ ))
+ fields = append(fields, m.createSelectField(config, "llm_client_type",
+ locale.MonitoringGraphitiLLMClientType, locale.MonitoringGraphitiLLMClientTypeDesc, graphitiProviderPresets,
+ ))
+ fields = append(fields, m.createBooleanField(config, "separate_embedding",
+ locale.MonitoringGraphitiSeparateEmbedding, locale.MonitoringGraphitiSeparateEmbeddingDesc,
+ ))
+ fields = append(fields, m.createIntegerField(config, "semaphore_limit",
+ locale.MonitoringGraphitiSemaphoreLimit, locale.MonitoringGraphitiSemaphoreLimitDesc, false, "",
+ graphitiSemaphoreMin, graphitiSemaphoreMax,
+ ))
+ fields = append(fields, m.createIntegerField(config, "ingest_worker_count",
+ locale.MonitoringGraphitiIngestWorkerCount, locale.MonitoringGraphitiIngestWorkerCountDesc, false, "",
+ graphitiWorkersMin, graphitiWorkersMax,
+ ))
+ fields = append(fields, m.createSelectField(config, "log_level",
+ locale.MonitoringGraphitiLogLevel, locale.MonitoringGraphitiLogLevelDesc, graphitiLogLevels,
+ ))
+ fields = append(fields, m.createSelectField(config, "search_scope",
+ locale.MonitoringGraphitiSearchScope, locale.MonitoringGraphitiSearchScopeDesc, graphitiSearchScopes,
+ ))
+ fields = append(fields, m.createTextField(config, "ingest_policy_rules",
+ locale.MonitoringGraphitiIngestPolicyRules, locale.MonitoringGraphitiIngestPolicyRulesDesc, false, "",
+ ))
+ fields = append(fields, m.createSelectField(config, "ingest_policy_field",
+ locale.MonitoringGraphitiIngestPolicyField, locale.MonitoringGraphitiIngestPolicyFieldDesc, graphitiPolicyFields,
))
- fields = append(fields, m.createTextField(config, "model_name",
- locale.MonitoringGraphitiModelName, locale.MonitoringGraphitiModelNameDesc, false, GraphitiModelNamePlaceholder,
+ fields = append(fields, m.createSelectField(config, "ingest_policy_default_action",
+ locale.MonitoringGraphitiIngestDefaultAction, locale.MonitoringGraphitiIngestDefaultActionDesc, graphitiPolicyActions,
+ ))
+ fields = append(fields, m.createIntegerField(config, "ingest_queue_max_size",
+ locale.MonitoringGraphitiIngestQueueMaxSize, locale.MonitoringGraphitiIngestQueueMaxSizeDesc, false, "",
+ graphitiQueueMin, graphitiQueueMax,
+ ))
+ fields = append(fields, m.createSelectField(config, "taxonomy_layer_profile",
+ locale.MonitoringGraphitiTaxonomyLayerProfile, locale.MonitoringGraphitiTaxonomyLayerProfileDesc,
+ graphitiTaxonomySuggestions,
+ ))
+ fields = append(fields, m.createTextField(config, "graphiti_cpus",
+ locale.MonitoringGraphitiCPUs, locale.MonitoringGraphitiCPUsDesc, false, "",
+ ))
+ fields = append(fields, m.createTextField(config, "graphiti_memory",
+ locale.MonitoringGraphitiMemory, locale.MonitoringGraphitiMemoryDesc, false, "",
))
fields = append(fields, m.createTextField(config, "neo4j_user",
locale.MonitoringGraphitiNeo4jUser, locale.MonitoringGraphitiNeo4jUserDesc, false, GraphitiNeo4jUserPlaceholder,
@@ -97,6 +160,15 @@ func (m *GraphitiFormModel) BuildForm() tea.Cmd {
fields = append(fields, m.createTextField(config, "neo4j_database",
locale.MonitoringGraphitiNeo4jDatabase, locale.MonitoringGraphitiNeo4jDatabaseDesc, false, GraphitiNeo4jUserPlaceholder,
))
+ fields = append(fields, m.createTextField(config, "neo4j_cpus",
+ locale.MonitoringGraphitiNeo4jCPUs, locale.MonitoringGraphitiNeo4jCPUsDesc, false, "",
+ ))
+ fields = append(fields, m.createTextField(config, "neo4j_memory",
+ locale.MonitoringGraphitiNeo4jMemory, locale.MonitoringGraphitiNeo4jMemoryDesc, false, "",
+ ))
+ fields = append(fields, m.createTextField(config, "neo4j_shm_size",
+ locale.MonitoringGraphitiNeo4jShmSize, locale.MonitoringGraphitiNeo4jShmSizeDesc, false, "",
+ ))
case "external":
// External mode - requires connection details only
@@ -118,22 +190,7 @@ func (m *GraphitiFormModel) BuildForm() tea.Cmd {
func (m *GraphitiFormModel) createTextField(
config *controller.GraphitiConfig, key, title, description string, masked bool, placeholder string,
) FormField {
- var envVar loader.EnvVar
- switch key {
- case "url":
- envVar = config.GraphitiURL
- case "timeout":
- envVar = config.Timeout
- case "model_name":
- envVar = config.ModelName
- case "neo4j_user":
- envVar = config.Neo4jUser
- case "neo4j_password":
- envVar = config.Neo4jPassword
- case "neo4j_database":
- envVar = config.Neo4jDatabase
- }
-
+ envVar := m.graphitiEnvVar(config, key)
input := NewTextInput(m.GetStyles(), m.GetWindow(), envVar)
if placeholder != "" {
input.Placeholder = placeholder
@@ -150,6 +207,98 @@ func (m *GraphitiFormModel) createTextField(
}
}
+func (m *GraphitiFormModel) createBooleanField(
+ config *controller.GraphitiConfig, key, title, description string,
+) FormField {
+ envVar := m.graphitiEnvVar(config, key)
+ input := NewBooleanInput(m.GetStyles(), m.GetWindow(), envVar)
+ return FormField{
+ Key: key, Title: title, Description: description, Input: input,
+ Value: input.Value(), Suggestions: input.AvailableSuggestions(),
+ }
+}
+
+func (m *GraphitiFormModel) createSelectField(
+ config *controller.GraphitiConfig, key, title, description string, suggestions []string,
+) FormField {
+ envVar := m.graphitiEnvVar(config, key)
+ input := NewTextInput(m.GetStyles(), m.GetWindow(), envVar)
+ input.ShowSuggestions = true
+ input.SetSuggestions(suggestions)
+ return FormField{
+ Key: key, Title: title, Description: description, Input: input,
+ Value: input.Value(), Suggestions: suggestions,
+ }
+}
+
+func (m *GraphitiFormModel) createIntegerField(
+ config *controller.GraphitiConfig,
+ key, title, description string,
+ masked bool,
+ placeholder string,
+ minValue, maxValue int,
+) FormField {
+ field := m.createTextField(config, key, title, description, masked, placeholder)
+ envVar := m.graphitiEnvVar(config, key)
+ if envVar.Default != "" {
+ field.Input.Placeholder = fmt.Sprintf("%s (%d-%d)", envVar.Default, minValue, maxValue)
+ } else {
+ field.Input.Placeholder = fmt.Sprintf("(%d-%d)", minValue, maxValue)
+ }
+ return field
+}
+
+func (m *GraphitiFormModel) graphitiEnvVar(
+ config *controller.GraphitiConfig, key string,
+) loader.EnvVar {
+ switch key {
+ case "url":
+ return config.GraphitiURL
+ case "timeout":
+ return config.Timeout
+ case "llm_client_type":
+ return config.LLMClientType
+ case "separate_embedding":
+ return config.SeparateEmbedding
+ case "semaphore_limit":
+ return config.SemaphoreLimit
+ case "log_level":
+ return config.LogLevel
+ case "search_scope":
+ return config.SearchScope
+ case "ingest_policy_rules":
+ return config.IngestPolicyRules
+ case "ingest_policy_field":
+ return config.IngestPolicyField
+ case "ingest_policy_default_action":
+ return config.IngestPolicyDefaultAction
+ case "ingest_worker_count":
+ return config.IngestWorkerCount
+ case "ingest_queue_max_size":
+ return config.IngestQueueMaxSize
+ case "taxonomy_layer_profile":
+ return config.TaxonomyLayerProfile
+ case "graphiti_cpus":
+ return config.GraphitiCPUs
+ case "graphiti_memory":
+ return config.GraphitiMemory
+ case "neo4j_user":
+ return config.Neo4jUser
+ case "neo4j_password":
+ return config.Neo4jPassword
+ case "neo4j_database":
+ return config.Neo4jDatabase
+ case "neo4j_cpus":
+ return config.Neo4jCPUs
+ case "neo4j_memory":
+ return config.Neo4jMemory
+ case "neo4j_shm_size":
+ return config.Neo4jShmSize
+ default:
+ return loader.EnvVar{}
+ }
+}
+
func (m *GraphitiFormModel) GetFormTitle() string {
return locale.MonitoringGraphitiFormTitle
}
@@ -179,73 +328,53 @@ func (m *GraphitiFormModel) GetFormOverview() string {
}
func (m *GraphitiFormModel) GetCurrentConfiguration() string {
- var sections []string
-
- sections = append(sections, m.GetStyles().Subtitle.Render(m.GetFormName()))
-
+ sections := []string{m.GetStyles().Subtitle.Render(m.GetFormName())}
config := m.GetController().GetGraphitiConfig()
- getMaskedValue := func(value string) string {
- maskedValue := strings.Repeat("*", len(value))
- if len(value) > 15 {
- maskedValue = maskedValue[:15] + "..."
+ appendValue := func(title string, envVar loader.EnvVar, masked bool) {
+ value := envVar.Value
+ style := m.GetStyles().Info
+ if value == "" {
+ value = envVar.Default
+ style = m.GetStyles().Muted
+ }
+ if value == "" {
+ return
}
- return maskedValue
+ if masked {
+ value = strings.Repeat("*", min(len(value), 15))
+ if len(envVar.Value) > 15 {
+ value += "..."
+ }
+ }
+ sections = append(sections, fmt.Sprintf("• %s: %s", title, style.Render(value)))
}
switch config.DeploymentType {
case "embedded":
sections = append(sections, "• "+locale.UIMode+m.GetStyles().Success.Render(locale.MonitoringGraphitiEmbedded))
- if config.GraphitiURL.Value != "" {
- sections = append(sections, fmt.Sprintf("• %s: %s",
- locale.MonitoringGraphitiURL, m.GetStyles().Info.Render(config.GraphitiURL.Value)))
- }
- if timeout := config.Timeout.Value; timeout != "" {
- sections = append(sections, fmt.Sprintf("• %s: %s",
- locale.MonitoringGraphitiTimeout, m.GetStyles().Info.Render(timeout)))
- } else if timeout := config.Timeout.Default; timeout != "" {
- sections = append(sections, fmt.Sprintf("• %s: %s",
- locale.MonitoringGraphitiTimeout, m.GetStyles().Muted.Render(timeout)))
- }
- if modelName := config.ModelName.Value; modelName != "" {
- sections = append(sections, fmt.Sprintf("• %s: %s",
- locale.MonitoringGraphitiModelName, m.GetStyles().Info.Render(modelName)))
- } else if modelName := config.ModelName.Default; modelName != "" {
- sections = append(sections, fmt.Sprintf("• %s: %s",
- locale.MonitoringGraphitiModelName, m.GetStyles().Muted.Render(modelName)))
- }
- if neo4jUser := config.Neo4jUser.Value; neo4jUser != "" {
- sections = append(sections, fmt.Sprintf("• %s: %s",
- locale.MonitoringGraphitiNeo4jUser, m.GetStyles().Info.Render(neo4jUser)))
- } else if neo4jUser := config.Neo4jUser.Default; neo4jUser != "" {
- sections = append(sections, fmt.Sprintf("• %s: %s",
- locale.MonitoringGraphitiNeo4jUser, m.GetStyles().Muted.Render(neo4jUser)))
- }
- if neo4jPassword := config.Neo4jPassword.Value; neo4jPassword != "" {
- sections = append(sections, fmt.Sprintf("• %s: %s",
- locale.MonitoringGraphitiNeo4jPassword, m.GetStyles().Muted.Render(getMaskedValue(neo4jPassword))))
- }
- if neo4jDatabase := config.Neo4jDatabase.Value; neo4jDatabase != "" {
- sections = append(sections, fmt.Sprintf("• %s: %s",
- locale.MonitoringGraphitiNeo4jDatabase, m.GetStyles().Info.Render(neo4jDatabase)))
- } else if neo4jDatabase := config.Neo4jDatabase.Default; neo4jDatabase != "" {
- sections = append(sections, fmt.Sprintf("• %s: %s",
- locale.MonitoringGraphitiNeo4jDatabase, m.GetStyles().Muted.Render(neo4jDatabase)))
- }
+ appendValue(locale.MonitoringGraphitiTimeout, config.Timeout, false)
+ appendValue(locale.MonitoringGraphitiLLMClientType, config.LLMClientType, false)
+ appendValue(locale.MonitoringGraphitiSeparateEmbedding, config.SeparateEmbedding, false)
+ appendValue(locale.MonitoringGraphitiSemaphoreLimit, config.SemaphoreLimit, false)
+ appendValue(locale.MonitoringGraphitiIngestWorkerCount, config.IngestWorkerCount, false)
+ appendValue(locale.MonitoringGraphitiSearchScope, config.SearchScope, false)
+ appendValue(locale.MonitoringGraphitiIngestDefaultAction, config.IngestPolicyDefaultAction, false)
+ appendValue(locale.MonitoringGraphitiIngestQueueMaxSize, config.IngestQueueMaxSize, false)
+ appendValue(locale.MonitoringGraphitiTaxonomyLayerProfile, config.TaxonomyLayerProfile, false)
+ appendValue(locale.MonitoringGraphitiCPUs, config.GraphitiCPUs, false)
+ appendValue(locale.MonitoringGraphitiMemory, config.GraphitiMemory, false)
+ appendValue(locale.MonitoringGraphitiNeo4jUser, config.Neo4jUser, false)
+ appendValue(locale.MonitoringGraphitiNeo4jPassword, config.Neo4jPassword, true)
+ appendValue(locale.MonitoringGraphitiNeo4jDatabase, config.Neo4jDatabase, false)
+ appendValue(locale.MonitoringGraphitiNeo4jCPUs, config.Neo4jCPUs, false)
+ appendValue(locale.MonitoringGraphitiNeo4jMemory, config.Neo4jMemory, false)
+ appendValue(locale.MonitoringGraphitiNeo4jShmSize, config.Neo4jShmSize, false)
case "external":
sections = append(sections, "• "+locale.UIMode+m.GetStyles().Success.Render(locale.MonitoringGraphitiExternal))
- if config.GraphitiURL.Value != "" {
- sections = append(sections, fmt.Sprintf("• %s: %s",
- locale.MonitoringGraphitiURL, m.GetStyles().Info.Render(config.GraphitiURL.Value)))
- }
- if timeout := config.Timeout.Value; timeout != "" {
- sections = append(sections, fmt.Sprintf("• %s: %s",
- locale.MonitoringGraphitiTimeout, m.GetStyles().Info.Render(timeout)))
- } else if timeout := config.Timeout.Default; timeout != "" {
- sections = append(sections, fmt.Sprintf("• %s: %s",
- locale.MonitoringGraphitiTimeout, m.GetStyles().Muted.Render(timeout)))
- }
+ appendValue(locale.MonitoringGraphitiURL, config.GraphitiURL, false)
+ appendValue(locale.MonitoringGraphitiTimeout, config.Timeout, false)
case "disabled":
sections = append(sections, "• "+locale.UIMode+m.GetStyles().Warning.Render(locale.MonitoringGraphitiDisabled))
@@ -285,37 +414,144 @@ func (m *GraphitiFormModel) HandleSave() error {
deploymentType := m.getSelectedDeploymentType()
fields := m.GetFormFields()
- // create a working copy of the current config to modify
newConfig := &controller.GraphitiConfig{
DeploymentType: deploymentType,
- // copy current EnvVar fields - they preserve metadata like Line, IsPresent, etc.
- GraphitiURL: config.GraphitiURL,
- Timeout: config.Timeout,
- ModelName: config.ModelName,
- Neo4jUser: config.Neo4jUser,
- Neo4jPassword: config.Neo4jPassword,
- Neo4jDatabase: config.Neo4jDatabase,
- Neo4jURI: config.Neo4jURI,
- Installed: config.Installed,
+ GraphitiURL: config.GraphitiURL, Timeout: config.Timeout,
+ LLMClientType: config.LLMClientType, SeparateEmbedding: config.SeparateEmbedding,
+ SemaphoreLimit: config.SemaphoreLimit, LogLevel: config.LogLevel,
+ SearchScope: config.SearchScope, IngestPolicyRules: config.IngestPolicyRules,
+ IngestPolicyField: config.IngestPolicyField,
+ IngestPolicyDefaultAction: config.IngestPolicyDefaultAction,
+ IngestWorkerCount: config.IngestWorkerCount, IngestQueueMaxSize: config.IngestQueueMaxSize,
+ TaxonomyLayerProfile: config.TaxonomyLayerProfile,
+ GraphitiCPUs: config.GraphitiCPUs, GraphitiMemory: config.GraphitiMemory,
+ Neo4jUser: config.Neo4jUser, Neo4jPassword: config.Neo4jPassword,
+ Neo4jDatabase: config.Neo4jDatabase, Neo4jURI: config.Neo4jURI,
+ Neo4jCPUs: config.Neo4jCPUs, Neo4jMemory: config.Neo4jMemory,
+ Neo4jShmSize: config.Neo4jShmSize, Installed: config.Installed,
}
- // update field values based on form input
for _, field := range fields {
value := strings.TrimSpace(field.Input.Value())
+ envVar := m.graphitiEnvVar(config, field.Key)
+ if value == "" {
+ value = envVar.Default
+ }
switch field.Key {
case "url":
+ if err := validateGraphitiURL(value); err != nil {
+ return err
+ }
newConfig.GraphitiURL.Value = value
case "timeout":
+ if err := validateGraphitiInteger(value, locale.MonitoringGraphitiTimeout, 1, 3600); err != nil {
+ return err
+ }
newConfig.Timeout.Value = value
- case "model_name":
- newConfig.ModelName.Value = value
+ case "llm_client_type":
+ if err := validateGraphitiEnum(value, locale.MonitoringGraphitiLLMClientType, graphitiProviderPresets); err != nil {
+ return err
+ }
+ newConfig.LLMClientType.Value = value
+ case "separate_embedding":
+ if value != "true" && value != "false" {
+ return fmt.Errorf("%s must be true or false", locale.MonitoringGraphitiSeparateEmbedding)
+ }
+ newConfig.SeparateEmbedding.Value = value
+ case "semaphore_limit":
+ if err := validateGraphitiInteger(value, locale.MonitoringGraphitiSemaphoreLimit, graphitiSemaphoreMin, graphitiSemaphoreMax); err != nil {
+ return err
+ }
+ newConfig.SemaphoreLimit.Value = value
+ case "log_level":
+ value = strings.ToUpper(value)
+ if err := validateGraphitiEnum(value, locale.MonitoringGraphitiLogLevel, graphitiLogLevels); err != nil {
+ return err
+ }
+ newConfig.LogLevel.Value = value
+ case "search_scope":
+ value = strings.ToLower(value)
+ if err := validateGraphitiEnum(value, locale.MonitoringGraphitiSearchScope, graphitiSearchScopes); err != nil {
+ return err
+ }
+ newConfig.SearchScope.Value = value
+ case "ingest_policy_rules":
+ normalized, err := normalizeGraphitiPolicyRules(value)
+ if err != nil {
+ return err
+ }
+ newConfig.IngestPolicyRules.Value = normalized
+ case "ingest_policy_field":
+ value = strings.ToLower(value)
+ if err := validateGraphitiEnum(value, locale.MonitoringGraphitiIngestPolicyField, graphitiPolicyFields); err != nil {
+ return err
+ }
+ newConfig.IngestPolicyField.Value = value
+ case "ingest_policy_default_action":
+ value = strings.ToUpper(value)
+ if err := validateGraphitiEnum(value, locale.MonitoringGraphitiIngestDefaultAction, graphitiPolicyActions); err != nil {
+ return err
+ }
+ newConfig.IngestPolicyDefaultAction.Value = value
+ case "ingest_worker_count":
+ if err := validateGraphitiInteger(value, locale.MonitoringGraphitiIngestWorkerCount, graphitiWorkersMin, graphitiWorkersMax); err != nil {
+ return err
+ }
+ newConfig.IngestWorkerCount.Value = value
+ case "ingest_queue_max_size":
+ if err := validateGraphitiInteger(value, locale.MonitoringGraphitiIngestQueueMaxSize, graphitiQueueMin, graphitiQueueMax); err != nil {
+ return err
+ }
+ newConfig.IngestQueueMaxSize.Value = value
+ case "taxonomy_layer_profile":
+ normalized, err := normalizeGraphitiTaxonomyProfile(value)
+ if err != nil {
+ return err
+ }
+ newConfig.TaxonomyLayerProfile.Value = normalized
+ case "graphiti_cpus":
+ if err := validateGraphitiCPUs(value, locale.MonitoringGraphitiCPUs); err != nil {
+ return err
+ }
+ newConfig.GraphitiCPUs.Value = value
+ case "graphiti_memory":
+ if err := validateGraphitiMemory(value, locale.MonitoringGraphitiMemory); err != nil {
+ return err
+ }
+ newConfig.GraphitiMemory.Value = value
case "neo4j_user":
+ if value == "" {
+ return fmt.Errorf("%s cannot be empty", locale.MonitoringGraphitiNeo4jUser)
+ }
newConfig.Neo4jUser.Value = value
case "neo4j_password":
+ if value == "" {
+ return fmt.Errorf("%s cannot be empty", locale.MonitoringGraphitiNeo4jPassword)
+ }
newConfig.Neo4jPassword.Value = value
case "neo4j_database":
+ if value == "" {
+ return fmt.Errorf("%s cannot be empty", locale.MonitoringGraphitiNeo4jDatabase)
+ }
newConfig.Neo4jDatabase.Value = value
+ case "neo4j_cpus":
+ if err := validateGraphitiCPUs(value, locale.MonitoringGraphitiNeo4jCPUs); err != nil {
+ return err
+ }
+ newConfig.Neo4jCPUs.Value = value
+ case "neo4j_memory":
+ if err := validateGraphitiMemory(value, locale.MonitoringGraphitiNeo4jMemory); err != nil {
+ return err
+ }
+ newConfig.Neo4jMemory.Value = value
+ case "neo4j_shm_size":
+ if err := validateGraphitiMemory(value, locale.MonitoringGraphitiNeo4jShmSize); err != nil {
+ return err
+ }
+ newConfig.Neo4jShmSize.Value = value
+ default:
+ return fmt.Errorf("unknown Graphiti field: %s", field.Key)
}
}
@@ -329,6 +565,110 @@ func (m *GraphitiFormModel) HandleSave() error {
return nil
}
+func validateGraphitiURL(value string) error {
+ parsed, err := url.ParseRequestURI(value)
+ if err != nil || parsed.Host == "" || (parsed.Scheme != "http" && parsed.Scheme != "https") {
+ return fmt.Errorf("%s must be an HTTP or HTTPS URL", locale.MonitoringGraphitiURL)
+ }
+ return nil
+}
+
+func validateGraphitiEnum(value, fieldName string, allowed []string) error {
+ for _, candidate := range allowed {
+ if value == candidate {
+ return nil
+ }
+ }
+ return fmt.Errorf("%s must be one of: %s", fieldName, strings.Join(allowed, ", "))
+}
+
+func validateGraphitiInteger(value, fieldName string, minValue, maxValue int) error {
+ parsed, err := strconv.Atoi(value)
+ if err != nil || parsed < minValue || parsed > maxValue {
+ return fmt.Errorf("%s must be an integer between %d and %d", fieldName, minValue, maxValue)
+ }
+ return nil
+}
+
+func validateGraphitiCPUs(value, fieldName string) error {
+ parsed, err := strconv.ParseFloat(value, 64)
+ if err != nil || parsed <= 0 {
+ return fmt.Errorf("%s must be a positive CPU value", fieldName)
+ }
+ return nil
+}
+
+func validateGraphitiMemory(value, fieldName string) error {
+ bytes, err := units.RAMInBytes(value)
+ if err != nil || bytes <= 0 {
+ return fmt.Errorf("%s must be a positive memory value such as 2G or 512M", fieldName)
+ }
+ return nil
+}
+
+func normalizeGraphitiPolicyRules(value string) (string, error) {
+ value = strings.TrimSpace(value)
+ if len(value) >= 2 && ((value[0] == '\'' && value[len(value)-1] == '\'') ||
+ (value[0] == '"' && value[len(value)-1] == '"')) {
+ value = value[1 : len(value)-1]
+ }
+
+ var rules map[string]string
+ if err := json.Unmarshal([]byte(value), &rules); err != nil {
+ return "", fmt.Errorf("%s must be a JSON object: %w", locale.MonitoringGraphitiIngestPolicyRules, err)
+ }
+ for pattern, action := range rules {
+ if strings.TrimSpace(pattern) == "" {
+ return "", fmt.Errorf("%s cannot contain an empty pattern", locale.MonitoringGraphitiIngestPolicyRules)
+ }
+ action = strings.ToUpper(strings.TrimSpace(action))
+ if err := validateGraphitiEnum(action, locale.MonitoringGraphitiIngestPolicyRules, graphitiPolicyActions); err != nil {
+ return "", err
+ }
+ rules[pattern] = action
+ }
+ normalized, err := json.Marshal(rules)
+ if err != nil {
+ return "", fmt.Errorf("failed to normalize %s: %w", locale.MonitoringGraphitiIngestPolicyRules, err)
+ }
+ return string(normalized), nil
+}
+
+func normalizeGraphitiTaxonomyProfile(value string) (string, error) {
+ value = strings.TrimSpace(value)
+ alias := strings.ToLower(value)
+ if alias == "full" || alias == "all" || alias == "minimal" {
+ return alias, nil
+ }
+
+ validClasses := map[string]bool{
+ "STRUCTURAL": true,
+ "EVIDENCE": true,
+ "PROGRESS": true,
+ "AGENT_ACTION": true,
+ "META": true,
+ "ATTEMPT": true,
+ "NARRATIVE": true,
+ }
+ parts := strings.Split(value, ",")
+ normalized := make([]string, 0, len(parts))
+ seen := make(map[string]bool)
+ for _, part := range parts {
+ className := strings.ToUpper(strings.TrimSpace(part))
+ if !validClasses[className] {
+ return "", fmt.Errorf("%s contains unknown class %q", locale.MonitoringGraphitiTaxonomyLayerProfile, part)
+ }
+ if !seen[className] {
+ normalized = append(normalized, className)
+ seen[className] = true
+ }
+ }
+ if len(normalized) == 0 {
+ return "", fmt.Errorf("%s cannot be empty", locale.MonitoringGraphitiTaxonomyLayerProfile)
+ }
+ return strings.Join(normalized, ","), nil
+}
+
func (m *GraphitiFormModel) HandleReset() {
// reset config to defaults
config := m.GetController().ResetGraphitiConfig()
diff --git a/backend/docs/config.md b/backend/docs/config.md
index 329d9e87..923a51d8 100644
--- a/backend/docs/config.md
+++ b/backend/docs/config.md
@@ -75,8 +75,10 @@ This document serves as a comprehensive guide to the configuration system in Pen
- [Network and Proxy Settings](#network-and-proxy-settings)
- [Usage Details](#usage-details-11)
- [Graphiti Knowledge Graph Settings](#graphiti-knowledge-graph-settings)
- - [Usage Details](#usage-details-12)
- - [Current Limitations (Beta)](#current-limitations-beta)
+ - [PentAGI Configuration Boundary](#pentagi-configuration-boundary)
+ - [Client Lifecycle and Failure Behavior](#client-lifecycle-and-failure-behavior)
+ - [Data Flow, Search, and Tenancy](#data-flow-search-and-tenancy)
+ - [Deployment Ownership](#deployment-ownership)
- [Agent Supervision Settings](#agent-supervision-settings)
- [Usage Details](#usage-details-13)
- [Supervision System Integration](#supervision-system-integration)
@@ -1827,64 +1829,64 @@ 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.
+Graphiti is an optional beta integration. This section documents the PentAGI-side configuration boundary and lifecycle; the operator-facing deployment, provider, ingestion, extraction, and Neo4j settings are maintained in [README.md — Knowledge Graph Integration](../../README.md#knowledge-graph-integration-graphiti).
-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.
+### PentAGI Configuration Boundary
-| Option | Environment Variable | Default Value | Description |
-| --------------- | -------------------- | ----------------------- | ------------------------------------------------------ |
-| GraphitiEnabled | `GRAPHITI_ENABLED` | `false` | Enable or disable Graphiti knowledge graph integration |
-| GraphitiURL | `GRAPHITI_URL` | `http://localhost:8001` | Base URL for Graphiti API service |
-| GraphitiTimeout | `GRAPHITI_TIMEOUT` | `30` | Timeout in seconds for Graphiti operations |
+`pkg/config.Config` intentionally owns only the settings required by the PentAGI process:
-### Usage Details
+| Field | Environment Variable | Default | Responsibility |
+| --- | --- | --- | --- |
+| `GraphitiEnabled` | `GRAPHITI_ENABLED` | `false` | Operator intent to enable the integration |
+| `GraphitiURL` | `GRAPHITI_URL` | *(empty)* | Graphiti API base URL; embedded deployments use `http://graphiti:8000` |
+| `GraphitiTimeout` | `GRAPHITI_TIMEOUT` | `30` seconds | Timeout used for Graphiti client requests and storage contexts |
-The Graphiti settings are used in `pkg/graphiti/client.go` and integrated throughout the provider system to automatically capture agent interactions and tool executions:
+All other variables with `GRAPHITI_*`, `NEO4J_*`, provider, embedding, ingest, extraction, anchor, or logging names configure `docker-compose-graphiti.yml` or the Graphiti process. They are not parsed into the Go `Config` struct. Keep that boundary explicit when adding settings: a value needed by PentAGI belongs in `pkg/config/config.go`; a value consumed only by the sidecar belongs in `.env.example` plus the compose mapping.
-- **GraphitiEnabled**: Controls whether the knowledge graph integration is active:
- ```go
- // Check if Graphiti is enabled
- if !cfg.GraphitiEnabled {
- return &Client{enabled: false}, nil
- }
- ```
+The provider controller applies an additional URL guard:
-- **GraphitiURL**: Specifies the Graphiti API endpoint:
- ```go
- client := graphiti.NewClient(cfg.GraphitiURL, timeout, cfg.GraphitiEnabled)
- ```
+```go
+graphitiClient, err := graphiti.NewClient(
+ cfg.GraphitiURL,
+ time.Duration(cfg.GraphitiTimeout)*time.Second,
+ cfg.GraphitiEnabled && cfg.GraphitiURL != "",
+)
+```
-- **GraphitiTimeout**: Sets the maximum time for knowledge graph operations:
- ```go
- timeout := time.Duration(cfg.GraphitiTimeout) * time.Second
- storeCtx, cancel := context.WithTimeout(ctx, timeout)
- defer cancel()
- ```
+Consequently, `GRAPHITI_ENABLED=true` with an empty URL still creates a disabled wrapper.
-The Graphiti integration captures:
-- Agent responses and reasoning for all agent types (pentester, researcher, coder, etc.)
-- Tool execution details including function name, arguments, results, and execution status
-- Context information including flow, task, and subtask IDs for hierarchical organization
-- Temporal relationships between entities, actions, and outcomes
+### Client Lifecycle and Failure Behavior
-These settings enable:
-- Building a comprehensive knowledge base from agent interactions
-- Semantic memory across multiple penetration tests
-- Advanced querying of relationships between tools, targets, and techniques
-- Learning from past successful approaches and strategies
+`pkg/graphiti/client.go` wraps `graphiti-go-client` and performs a synchronous health check during provider initialization. It makes three attempts with a two-second backoff. A final failure is returned to `pkg/providers/providers.go`, which logs a warning and substitutes a disabled client so the rest of PentAGI can start.
+
+The disabled wrapper has deliberate asymmetric behavior:
+
+- `AddMessages` is a no-op, allowing normal flow execution to continue.
+- Search methods return `graphiti is not enabled`; disabled clients are normally excluded from agent tool registration and prompts through `IsEnabled`.
+- Storage calls use `GraphitiTimeout`, log failures with their group ID, and return the error to the caller without making Graphiti a required persistence layer.
+
+Do not change initialization failures into fatal PentAGI startup errors without treating that as a deployment-contract change.
+
+### Data Flow, Search, and Tenancy
+
+Provider performers render `backend/pkg/templates/graphiti/*.tmpl` and enqueue agent responses and tool executions with observation metadata. The sidecar applies ingest policy and performs asynchronous extraction; successful submission does not imply that the graph is immediately searchable.
+
+Enabled agents receive the `graphiti_search` tool. Its seven modes map to temporal-window, entity-relationship, diverse-result, episode-context, successful-tool, recent-context, and entity-by-label client methods. Transport and server failures are handled as degradable tool failures where possible, while malformed arguments and validation errors remain hard errors so the LLM can repair its call.
+
+Every request is partitioned by `Config.GroupID(flowID)`:
+
+- without `TENANT_ID`: `flow-<id>`;
+- with `TENANT_ID`: `<tenant>-flow-<id>`.
-The integration is designed to be non-blocking - if Graphiti operations fail, they are logged but don't interrupt the agent workflow.
+`Config.ParseGroupID` rejects identifiers belonging to another tenant. Keep `GroupID` and `ParseGroupID` exact inverses, and never accept a client-supplied namespace in place of a server-derived group ID. The stock deployment also sets `GRAPHITI_SEARCH_SCOPE=flowid`; changing it to global search bypasses this retrieval boundary inside Graphiti and is unsafe for shared deployments.
-### Current Limitations (Beta)
+### Deployment Ownership
-The Graphiti integration is currently a beta feature. Operators should plan around the following constraints before enabling it in production:
+The bundled stack is separate from `docker-compose.yml`. The installer distinguishes disabled, external, and embedded deployments using `GRAPHITI_ENABLED` and `GRAPHITI_URL`; `http://graphiti:8000` is the embedded endpoint. It starts the Graphiti stack before PentAGI so the startup health check can succeed.
-- **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.
+Installer assets include `docker-compose-graphiti.yml` and the `graphiti` preset directory sourced from `examples/graphiti`. The target directory is checked, repaired, and removed with the Graphiti stack. Compose mounts it through `GRAPHITI_CONFIG_PATH` and `GRAPHITI_CONFIG_DIR`; the fallback target `configs` prevents a newer compose file paired with an older `.env` from masking the image's built-in `llm_configs` with an empty host directory.
-If your deployment cannot reach an OpenAI-compatible endpoint, set `GRAPHITI_ENABLED=false`. The rest of PentAGI continues to function without the knowledge graph.
+Models and call parameters belong to the provider YAML presets, selected by `GRAPHITI_LLM_CLIENT_TYPE`; they are not fields in the PentAGI Go configuration. `GRAPHITI_MODEL_NAME` is obsolete. Refer operators to the README instead of duplicating the sidecar's tuning reference here.
## Agent Supervision Settings
diff --git a/docker-compose-graphiti.yml b/docker-compose-graphiti.yml
index 78936a8a..10979996 100644
--- a/docker-compose-graphiti.yml
+++ b/docker-compose-graphiti.yml
@@ -20,6 +20,15 @@ services:
timeout: 10s
retries: 10
start_period: 3s
+ deploy:
+ resources:
+ limits:
+ cpus: ${NEO4J_CPUS:-4.0}
+ memory: ${NEO4J_MEMORY:-4G}
+ ulimits:
+ nofile:
+ soft: ${NEO4J_NOFILE:-65536}
+ hard: ${NEO4J_NOFILE:-65536}
ports:
- "127.0.0.1:7474:7474" # HTTP
- "127.0.0.1:7687:7687" # Bolt
@@ -33,7 +42,7 @@ services:
- NEO4J_AUTH=${NEO4J_USER:-neo4j}/${NEO4J_PASSWORD:-devpassword}
networks:
- pentagi-network
- shm_size: 4g
+ shm_size: ${NEO4J_SHM_SIZE:-4g}
graphiti:
image: vxcontrol/graphiti:latest
@@ -41,16 +50,20 @@ services:
container_name: graphiti
hostname: graphiti
healthcheck:
- test:
- [
- "CMD",
- "python",
- "-c",
- "import urllib.request; urllib.request.urlopen('http://localhost:8000/healthcheck')",
- ]
- interval: 10s
+ test: ["CMD-SHELL", "curl -f http://127.0.0.1:8000/healthcheck || exit 1"]
+ interval: 30s
timeout: 5s
retries: 3
+ start_period: 20s
+ deploy:
+ resources:
+ limits:
+ cpus: ${GRAPHITI_CPUS:-2.0}
+ memory: ${GRAPHITI_MEMORY:-2G}
+ ulimits:
+ nofile:
+ soft: 65536
+ hard: 65536
depends_on:
neo4j:
condition: service_healthy
@@ -60,14 +73,54 @@ services:
options:
max-size: 50m
max-file: "7"
+ volumes:
+ - ${GRAPHITI_CONFIG_PATH:-./graphiti}:/app/pentagi-graphiti/server/${GRAPHITI_CONFIG_DIR:-configs}:ro
environment:
- NEO4J_URI=${NEO4J_URI:-bolt://neo4j:7687}
- NEO4J_USER=${NEO4J_USER:-neo4j}
- NEO4J_DATABASE=${NEO4J_DATABASE:-neo4j}
- NEO4J_PASSWORD=${NEO4J_PASSWORD:-devpassword}
- - MODEL_NAME=${GRAPHITI_MODEL_NAME:-gpt-5-mini}
+ - LLM_CLIENT_TYPE=${GRAPHITI_LLM_CLIENT_TYPE:-openai}
- OPENAI_BASE_URL=${OPEN_AI_SERVER_URL:-https://api.openai.com/v1}
- OPENAI_API_KEY=${OPEN_AI_KEY:-}
+ - GEMINI_BASE_URL=${GEMINI_SERVER_URL:-https://generativelanguage.googleapis.com}
+ - GEMINI_API_KEY=${GEMINI_API_KEY:-}
+ - LLM_SERVER_BASE_URL=${LLM_SERVER_URL:-}
+ - LLM_SERVER_API_KEY=${LLM_SERVER_KEY:-}
+ - LITELLM_BASE_URL=${GRAPHITI_LITELLM_BASE_URL:-}
+ - LITELLM_API_KEY=${GRAPHITI_LITELLM_API_KEY:-}
+ - SEPARATE_EMBEDDING=${GRAPHITI_SEPARATE_EMBEDDING:-false}
+ - EMBEDDING_MODEL=${EMBEDDING_MODEL:-}
+ - EMBEDDING_URL=${EMBEDDING_URL:-}
+ - EMBEDDING_KEY=${EMBEDDING_KEY:-}
+ - SEMAPHORE_LIMIT=${GRAPHITI_SEMAPHORE_LIMIT:-20}
+ - GRAPHITI_TELEMETRY_ENABLED=${GRAPHITI_TELEMETRY_ENABLED:-false}
+ - LOG_FORMAT=${GRAPHITI_LOG_FORMAT:-json}
+ - LOG_LEVEL=${GRAPHITI_LOG_LEVEL:-INFO}
+ - LOG_STDOUT=${GRAPHITI_LOG_STDOUT:-events}
+ - FLOW_LOGGER_WARN_COUNT=${GRAPHITI_FLOW_LOGGER_WARN_COUNT:-256}
+ - DEBUG_RUNTIME_RESOURCES=${GRAPHITI_DEBUG_RUNTIME_RESOURCES:-false}
+ - GRAPHITI_SEARCH_SCOPE=${GRAPHITI_SEARCH_SCOPE:-flowid}
+ - INGEST_POLICY_RULES=${GRAPHITI_INGEST_POLICY_RULES:-}
+ - INGEST_POLICY_FIELD=${GRAPHITI_INGEST_POLICY_FIELD:-both}
+ - INGEST_POLICY_DEFAULT_ACTION=${GRAPHITI_INGEST_POLICY_DEFAULT_ACTION:-SKIP_LLM}
+ - INGEST_USE_GROUP_ACTORS=${GRAPHITI_INGEST_USE_GROUP_ACTORS:-true}
+ - INGEST_WORKER_COUNT=${GRAPHITI_INGEST_WORKER_COUNT:-16}
+ - INGEST_LOCK_BY_GROUP_ID=${GRAPHITI_INGEST_LOCK_BY_GROUP_ID:-true}
+ - INGEST_TASK_MAX_RETRIES=${GRAPHITI_INGEST_TASK_MAX_RETRIES:-1}
+ - INGEST_TASK_RETRY_DELAY_SEC=${GRAPHITI_INGEST_TASK_RETRY_DELAY_SEC:-2.0}
+ - INGEST_TASK_TIMEOUT_SEC=${GRAPHITI_INGEST_TASK_TIMEOUT_SEC:-0}
+ - INGEST_QUEUE_MAX_SIZE=${GRAPHITI_INGEST_QUEUE_MAX_SIZE:-0}
+ - INGEST_DEAD_LETTER_ENABLED=${GRAPHITI_INGEST_DEAD_LETTER_ENABLED:-false}
+ - TAXONOMY_LAYER_PROFILE=${GRAPHITI_TAXONOMY_LAYER_PROFILE:-STRUCTURAL,EVIDENCE,PROGRESS,ATTEMPT}
+ - USE_COMBINED_FULL_EXTRACTION=${GRAPHITI_USE_COMBINED_FULL_EXTRACTION:-true}
+ - USE_COMBINED_EXTRACTION=${GRAPHITI_USE_COMBINED_EXTRACTION:-true}
+ - COMBINED_FULL_GATING_ENABLED=${GRAPHITI_COMBINED_FULL_GATING_ENABLED:-true}
+ - COMBINED_DIAGNOSTIC_SAMPLES=${GRAPHITI_COMBINED_DIAGNOSTIC_SAMPLES:-false}
+ - ANCHOR_NODE_MODE=${GRAPHITI_ANCHOR_NODE_MODE:-smart}
+ - ANCHOR_NODE_LIMIT=${GRAPHITI_ANCHOR_NODE_LIMIT:-25}
+ - ANCHOR_MASS_TYPE_LIMIT=${GRAPHITI_ANCHOR_MASS_TYPE_LIMIT:-10}
+ - ANCHOR_QUERY_TIMEOUT=${GRAPHITI_ANCHOR_QUERY_TIMEOUT:-10}
- PORT=8000
networks:
- pentagi-network
diff --git a/examples/graphiti/custom.yaml b/examples/graphiti/custom.yaml
new file mode 100644
index 00000000..22fbb7a7
--- /dev/null
+++ b/examples/graphiti/custom.yaml
@@ -0,0 +1,17 @@
+provider: custom
+MODEL_NAME:
+ model: Qwen/Qwen3.6-27B-FP8
+ temperature: 1.0
+ max_tokens: 32768
+ json: true
+ extra_body:
+ chat_template_kwargs:
+ enable_thinking: false
+SMALL_MODEL_NAME:
+ model: Qwen/Qwen3.6-27B-FP8
+ temperature: 1.0
+ max_tokens: 32768
+ json: true
+ extra_body:
+ chat_template_kwargs:
+ enable_thinking: false
diff --git a/examples/graphiti/gemini.yaml b/examples/graphiti/gemini.yaml
new file mode 100644
index 00000000..29a52ce6
--- /dev/null
+++ b/examples/graphiti/gemini.yaml
@@ -0,0 +1,11 @@
+provider: gemini
+MODEL_NAME:
+ model: gemini/gemini-2.5-flash-lite
+ temperature: 1.0
+ max_tokens: 64000
+ json: true
+SMALL_MODEL_NAME:
+ model: gemini/gemini-2.5-flash-lite
+ temperature: 1.0
+ max_tokens: 64000
+ json: true
diff --git a/examples/graphiti/litellm.yaml b/examples/graphiti/litellm.yaml
new file mode 100644
index 00000000..df599b47
--- /dev/null
+++ b/examples/graphiti/litellm.yaml
@@ -0,0 +1,11 @@
+provider: litellm
+MODEL_NAME:
+ model: openrouter/openai/gpt-oss-20b
+ temperature: 1.0
+ max_tokens: 32768
+ json: true
+SMALL_MODEL_NAME:
+ model: openrouter/openai/gpt-oss-20b
+ temperature: 1.0
+ max_tokens: 32768
+ json: true
diff --git a/examples/graphiti/openai.yaml b/examples/graphiti/openai.yaml
new file mode 100644
index 00000000..567f96a2
--- /dev/null
+++ b/examples/graphiti/openai.yaml
@@ -0,0 +1,17 @@
+provider: openai
+MODEL_NAME:
+ model: openai/gpt-5-mini
+ temperature: 1.0
+ max_tokens: 32768
+ json: true
+ reasoning:
+ effort: low
+ verbosity: low
+SMALL_MODEL_NAME:
+ model: openai/gpt-5.4-nano
+ temperature: 1.0
+ max_tokens: 32768
+ json: true
+ reasoning:
+ effort: low
+ verbosity: low