diff --git a/guides/ai-agents/agent-memory.mdx b/guides/ai-agents/agent-memory.mdx index 25267bf6..385ea17e 100644 --- a/guides/ai-agents/agent-memory.mdx +++ b/guides/ai-agents/agent-memory.mdx @@ -79,6 +79,34 @@ Organization admins get a memories tab that lists memories across users and agen Admins can audit what the agent has learned without that memory entering their own agent context — reading a memory never injects it into your own conversations. +## Promoting a memory to project context + +A memory is personal by design, but sometimes what one person taught the agent is knowledge the whole project needs. Promotion is how a memory becomes a project-context entry that every agent answer in the project reads. + +Promotion never publishes directly. It files a nomination on the [Reviews](/guides/ai-agents/reviews) board, which is the same board that handles findings from likely-wrong answers. A reviewer approves or dismisses it, and only an approved, merged pull request lands the entry in `lightdash.project_context.yml`. + +### Who can promote + +Anyone who can read a memory can nominate it: + +* **Memory owners** see a **Propose for project context** action on their own memory page. +* **Organization admins** see the same action on any memory in the admin memories tab. + +Promotion requires the project to have the project-context feature available (a connected GitHub or GitLab repository with `lightdash.project_context.yml` writeback set up through [Reviews](/guides/ai-agents/reviews)). + + + The my memories panel showing a selected memory with the Propose for project context button highlighted in the top right. + + +### What happens when you promote + +1. **You nominate.** Click **Propose for project context** on the memory and optionally add a reason. A new review item is filed on the Reviews board, sourced from the memory, with the proposed project-context entry and the writeback diff preview attached. +2. **The board reviews it.** A reviewer sees the memory's wording, the exact `lightdash.project_context.yml` change it would make, and a link back to the source memory for provenance. They can approve, dismiss, or leave it in triage. +3. **Approval opens a pull request.** Approving runs the same project-context writeback used by [Reviews](/guides/ai-agents/reviews) findings — a pull request against your dbt repository adding or updating the entry. +4. **Merging finishes the promotion.** When the pull request merges, the source memory flips to a terminal `promoted` status. The memory page becomes read-only and links its review item; the new entry now serves every user in the project. + +Until the pull request is merged, the original memory keeps serving your own conversations, so promotion never leaves a gap. If the pull request is closed unmerged, the memory stays active and the review item is reverted. + ## What is not included in memory A few things are deliberately kept out: @@ -102,7 +130,7 @@ Memory and [project context](/guides/ai-agents/reviews) both improve future agen If you also want to hand the agent context upfront (a glossary, fiscal calendar, internal definitions) without waiting for either loop, use [knowledge documents](/guides/ai-agents/best-practices#knowledge-documents). -Use memory for in-the-moment course corrections that stick to you, project context to improve every agent in the project at the source, and knowledge documents when you can hand the agent the answer upfront. +Use memory for in-the-moment course corrections that stick to you, project context to improve every agent in the project at the source, and knowledge documents when you can hand the agent the answer upfront. When a personal memory turns out to be knowledge the whole project needs, [promote it to project context](#promoting-a-memory-to-project-context) so every agent answer benefits. ## Frequently asked questions @@ -122,6 +150,10 @@ Nothing. Memories are stored as plain text and are model-agnostic, so switching Yes. Open the memory from its citation chip or the memories page and retire it — retired memories are never injected into future answers. You can reactivate a retired memory from the same page if you change your mind. +**Can I share a memory with other people on my project?** + +Not directly — memory itself is always personal. If a memory contains knowledge that would help the whole project, [promote it to project context](#promoting-a-memory-to-project-context). Promotion goes through the [Reviews](/guides/ai-agents/reviews) board and lands the entry in `lightdash.project_context.yml` via a pull request, so approved knowledge is shared through project context rather than through memory itself. + **What happens if memory is disabled after it has been used?** Learning and injection stop immediately: no new memories are saved, and existing memories are no longer added to answers. The memories themselves are retained, so if memory is re-enabled later, they resume being used without any data loss. diff --git a/images/guides/ai-agents/agent-memory/promote-memory-to-project-context.png b/images/guides/ai-agents/agent-memory/promote-memory-to-project-context.png new file mode 100644 index 00000000..a42c9371 Binary files /dev/null and b/images/guides/ai-agents/agent-memory/promote-memory-to-project-context.png differ