> ## Documentation Index
> Fetch the complete documentation index at: https://labs.prompthon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Memory Retrieval Starter

<div className="not-prose my-4 rounded-md border border-gray-200 bg-gray-50 p-2 text-sm dark:border-gray-800 dark:bg-gray-900/40">
  <div className="mb-2 px-1 text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400">Need help?</div>

  <div className="flex flex-wrap gap-2">
    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://discord.gg/sDE2HhGTg4" target="_blank" rel="noreferrer">
      <Icon icon="discord" iconType="brands" size={14} />

      <span>Ask in Discord</span>
    </a>

    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://github.com/Prompthon-IO/agent-systems-handbook/issues/new/choose" target="_blank" rel="noreferrer">
      <Icon icon="github" iconType="brands" size={14} />

      <span>Open a GitHub issue</span>
    </a>

    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://github.com/Prompthon-IO/agent-systems-handbook/blob/main/SUPPORT.md" target="_blank" rel="noreferrer">
      <Icon icon="life-ring" size={14} />

      <span>Support guide</span>
    </a>
  </div>
</div>

## Summary

This starter shows one clean way to separate active notes, working memory,
imported personal context, retrieval inputs, citation-bearing verifiable RAG,
and durable artifacts in a small agent loop.

## Status

`starter`

Source code: [patterns/examples/agent-memory-retrieval-starter](https://github.com/Prompthon-IO/agent-systems-handbook/tree/main/patterns/examples/agent-memory-retrieval-starter)

## Why It Exists

Memory examples often collapse everything into one vague history object. This
starter is intentionally narrower: it highlights the boundary between what the
agent is currently holding, what a user imported from another assistant, what
it can retrieve, what must remain an external file-search corpus, and what it
should preserve as an artifact.

The May 2026 multimodal file-search updates from Google made that retrieval
boundary easier to teach. A useful starter should show metadata filters,
page-level citations, and multimodal chunks without pretending that retrieval
stores are the same thing as agent memory.

## Related Lab Pages

* [Agent Memory And Retrieval](/patterns/agent-memory-and-retrieval)
* [Patterns Overview](/patterns)

## Folder Structure

```text theme={null}
agent-memory-retrieval-starter/
├── index.mdx
└── src/
    ├── artifact_policy.py
    ├── memory_flow.py
    ├── personal_context.py
    ├── retrieval_trace.py
    └── verifiable_rag.py
```

## Quick Start

From the repository root:

```bash theme={null}
python3 scripts/verify_example_projects.py
```

This is still a starter, not a full application. Read `src/memory_flow.py` for
the state boundary and `src/verifiable_rag.py` for the retrieval-side citation
surface.

## Included Sample Files

* `src/memory_flow.py`: the smallest useful state container for active notes,
  task-scoped working memory, imported personal context, retrieval inputs, and
  durable artifacts
* `src/personal_context.py`: a tiny normalization surface that keeps imported
  preference facts separate from retrieval results and artifacts
* `src/retrieval_trace.py`: a tiny ranking and trace surface for making
  retrieval decisions inspectable
* `src/verifiable_rag.py`: a tiny filter-and-citation surface for metadata
  filters, page numbers, and multimodal grounding output
* `src/artifact_policy.py`: one place to show how a starter can separate
  artifact-promotion rules from raw note capture

## Constraints

* No storage backend is wired yet.
* No embedding or vector-store integration is included.
* No provider SDK is called directly.
* Imported personal context stays deliberately small and reviewable.
* The example favors clear boundaries over completeness.
* Citations are modeled as output artifacts, not as proof that retrieval is
  always correct.

## Flow Boundaries

The starter may:

* keep working memory and personal context separate from retrieval inputs
* apply metadata filters before selecting chunks
* surface page-level and media citations as part of the returned artifact
* keep retrieval traces inspectable enough for review

The starter must not:

* treat a file-search store as durable agent memory
* silently promote retrieved snippets into long-term memory
* hide filter decisions or cited locations from the reviewer

## Next Steps

* Add a simple persistence layer for imported context and durable artifacts.
* Add a clearer review workflow for memory imports before they become active.
* Add a provider adapter for one real file-search API without collapsing the
  retrieval store into the memory layer.