diff --git a/README.md b/README.md index cb0cb98c..97864ba5 100644 --- a/README.md +++ b/README.md @@ -3117,6 +3117,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 enable the optional Graphiti knowledge graph described earlier in this README, treat its current search context as scoped to the active flow or engagement unless you explicitly build a separate cross-flow reuse workflow. + ### 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 39c518cc..e54b579e 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, answers, and 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