From 4e2ece89450cd177d30631c4d14ad2d86d23ccce Mon Sep 17 00:00:00 2001 From: "Mason Kim(ZINUS US_SALES)" Date: Wed, 15 Apr 2026 19:35:08 -0400 Subject: [PATCH] docs: clarify memory lifecycle across flows Signed-off-by: Mason Kim(ZINUS US_SALES) --- README.md | 13 +++++++++++++ backend/docs/flow_execution.md | 6 ++++++ 2 files changed, 19 insertions(+) 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