Skip to content

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

docs: clarify memory lifecycle across flows

Mason Kim(ZINUS US_SALES)4e2ece89450c
diff --git a/README.md b/README.md
index 7ddc15ba..885f68fa 100644
--- a/README.md
+++ b/README.md
@@ -3001,6 +3001,19 @@ Available search parameters:
- `-limit NUMBER`: Maximum number of results (default: 3)
- `-threshold NUMBER`: Similarity threshold (0.0-1.0, default: 0.7)
+### Memory Lifecycle Across Flows
+
+PentAGI stores several kinds of vector documents, and they serve different purposes:
+
+- `memory` captures flow-specific execution history such as tool results and agent observations
+- `guide`, `answer`, and `code` are intended for reusable knowledge that can help future runs
+
+If you want to inspect what happened in one engagement, search the vector store with the related `flow_id`. If you want knowledge to survive beyond a single run, store the durable result explicitly as a `guide`, `answer`, or `code` document instead of relying on execution memory alone.
+
+For example, if a target has recurring setup notes, authentication quirks, or target-specific testing methodology, instruct the agent to save that information as a `guide` and search for it at the beginning of the next engagement. This is the safest current workflow when you want a new flow to start with reusable context.
+
+Flow deletion removes the flow from normal queries through PentAGI's soft-delete mechanism, so reusable knowledge should be treated as a separate concern from per-flow execution history. If you need broader episodic context across operations, enable the optional Graphiti knowledge graph described earlier in this README.
+
### Common Troubleshooting Scenarios
1. **After changing embedding provider**: Always run `flush` or `reindex` to ensure consistency
diff --git a/backend/docs/flow_execution.md b/backend/docs/flow_execution.md
index d4303a99..688acb3f 100644
--- a/backend/docs/flow_execution.md
+++ b/backend/docs/flow_execution.md
@@ -706,6 +706,12 @@ The system maintains multiple types of persistent knowledge with PostgreSQL + pg
- **Answer Storage** (`doc_type: answer`) - Q&A pairs for common scenarios
- **Code Storage** (`doc_type: code`) - Programming language-specific code samples
+**Lifecycle Guidance**:
+- Treat `memory` as flow-scoped execution history. It is most useful for understanding what happened in a specific engagement and is commonly inspected with a `flow_id` filter.
+- Treat `guide`, `answer`, and `code` as reusable knowledge. These document types exist to preserve durable procedures, reusable target notes, Q&A material, and code snippets across future runs.
+- If you want a later flow to begin with known context, store the confirmed result intentionally through `store_guide`, `store_answer`, or `store_code` instead of assuming execution history alone will provide the right reusable context.
+- Current prompt templates already distinguish these roles: reusable guides/code live in vector documents, while Graphiti is intended for episodic memory about what actually happened during execution.
+
**Technical Parameters**:
- **Similarity Threshold**: 0.2 for all vector searches
- **Result Limits**: 3 documents maximum per search