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 1/2] 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 From a285a99e2834bb44147a44b835de4b359ff9a58a Mon Sep 17 00:00:00 2001 From: mason5052 Date: Wed, 22 Apr 2026 12:36:08 -0400 Subject: [PATCH 2/2] docs: tighten memory lifecycle guidance Signed-off-by: mason5052 --- README.md | 2 +- backend/docs/flow_execution.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 885f68fa..3a176273 100644 --- a/README.md +++ b/README.md @@ -3012,7 +3012,7 @@ If you want to inspect what happened in one engagement, search the vector store 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. +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 diff --git a/backend/docs/flow_execution.md b/backend/docs/flow_execution.md index 688acb3f..f041b394 100644 --- a/backend/docs/flow_execution.md +++ b/backend/docs/flow_execution.md @@ -710,7 +710,7 @@ The system maintains multiple types of persistent knowledge with PostgreSQL + pg - 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. +- 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