Memory Prefetch

Auto-inject relevant long-term memories into the system prompt at turn start

Prefetch pulls relevant long-term memories into the system prompt at the start of every turn — the agent answers with context it never had to ask for.

Prefetch is “auto” by default. On query-based backends (sqlite, chroma, mem0, {"provider": ...}) it runs automatically — facts saved with agent.store_memory(..., memory_type="long_term") reach the model with no prefetch=True and no recall() call. On the file backend it stays off because file memory already injects recent items into the system prompt itself. Pass prefetch=True or prefetch=False to override.

Quick Start

1. Simple Usage

   Pick a query-based backend and stored facts reach the model automatically.

   from praisonaiagents import Agent
   
   agent = Agent(
       name="assistant",
       instructions="Answer using recalled memories when relevant.",
       memory="sqlite",   # query-based backend → prefetch is automatic
   )
   agent.store_memory(
       "The project codename is BLUEHERON.",
       memory_type="long_term",
   )
   print(agent.start("What is the project codename?"))   # answers "BLUEHERON"

2. Scope per user (optional but recommended)

   Set user_id so recalled memories persist across runs and stay private to one user.

   from praisonaiagents import Agent, MemoryConfig
   
   agent = Agent(
       name="assistant",
       instructions="Answer using recalled memories when relevant.",
       memory=MemoryConfig(backend="sqlite", user_id="alice"),
   )
   agent.store_memory("Alice prefers metric units.", memory_type="long_term")
   print(agent.start("How should I format my dashboard?"))

3. Tune the budget

   Cap how many memories are injected and how large the block can grow.

   from praisonaiagents import Agent, MemoryConfig
   
   agent = Agent(
       name="assistant",
       instructions="Answer using recalled memories when relevant.",
       memory=MemoryConfig(
           backend="sqlite",
           user_id="alice",
           prefetch_limit=3,           # inject at most 3 memories
           prefetch_token_budget=200,  # estimated-token cap; truncates with "…"
       ),
   )
   
   agent.start("What are my UI preferences?")

4. Force prefetch on or off

   Override the auto default when you need to.

   from praisonaiagents import MemoryConfig
   
   # Force on even for the file backend
   MemoryConfig(user_id="alice", prefetch=True)
   
   # Force off even for sqlite / chroma / mem0
   MemoryConfig(backend="sqlite", user_id="alice", prefetch=False)

5. Automatic cross-instance recall with auto_memory

   Set auto_memory=True on a shared user_id and the first agent persists each turn durably — a second agent on the same backend recalls it with no explicit store call.

   from praisonaiagents import Agent, MemoryConfig
   
   shared = dict(backend="sqlite", user_id="alice", auto_memory=True)
   
   Agent(
       name="writer",
       instructions="You help the user.",
       memory=MemoryConfig(**shared),
   ).start("Remember launch date is Nov 15.")
   
   reader = Agent(
       name="reader",
       instructions="Answer using recalled context.",
       memory=MemoryConfig(**shared),
   )
   print(reader.start("When do we launch?"))   # answers from recalled context

6. Cross-agent recall with an explicit store

   Use store_memory(..., memory_type="long_term") when you want to control exactly what is stored, instead of persisting the whole turn.

   from praisonaiagents import Agent, MemoryConfig
   
   shared_kwargs = dict(backend="sqlite", user_id="alice")
   
   writer = Agent(
       name="writer",
       instructions="Store facts.",
       memory=MemoryConfig(**shared_kwargs),
   )
   writer.store_memory("Launch date is Nov 15.", memory_type="long_term")
   
   reader = Agent(
       name="reader",
       instructions="Answer using recalled context.",
       memory=MemoryConfig(**shared_kwargs),
   )
   print(reader.start("When do we launch?"))

How It Works

Prefetch searches long-term memory with the user prompt, dedupes and budgets the matches, then appends them to the system prompt before the first LLM call.

Multimodal prompts (a list of {type: "text", text: ...} blocks) also drive the search — non-text parts are ignored for the query.

Configuration Options

Identity scoping (user_id, session_id) is inherited from the same MemoryConfig.

Backends: file (default), sqlite, chroma, mongodb, mem0, dakera, in_memory — see Memory.

Common Patterns

Pattern 1 — Personal assistant with recalled preferences

from praisonaiagents import Agent, MemoryConfig

agent = Agent(
    name="assistant",
    instructions="Answer using recalled preferences.",
    memory=MemoryConfig(backend="sqlite", user_id="alice"),
)
agent.store_memory(
    "Alice prefers metric units and dark mode.",
    memory_type="long_term",
)
print(agent.start("How should I format my dashboard?"))

Pattern 2 — Tight budget for cost control

from praisonaiagents import Agent, MemoryConfig

agent = Agent(
    name="assistant",
    instructions="Answer concisely using recalled context.",
    memory=MemoryConfig(
        backend="sqlite",
        user_id="alice",
        prefetch_limit=2,
        prefetch_token_budget=128,
    ),
)
print(agent.start("Remind me what I asked for last time."))

Best Practices

Related