Use codemap find "SymbolName" to locate any symbol before reading — it gives exact file + line range and is faster than grep across the whole repo.

Managing Memory in Agents

Memory tier overview

Quick start: @remember for long-term user facts

from lauren_ai import (
    agent, remember, use_guardrails, use_tools,
    InMemoryUserMemoryStore, PromptInjectionFilter,
)

_memory = InMemoryUserMemoryStore()

@agent(model="claude-opus-4-6", system="You are a personal assistant.")
@remember(store=_memory, extract=True, inject=True, top_k=5)
@use_guardrails(input=[PromptInjectionFilter()])
@use_tools(my_tool)
class PersonalAssistant: ...

How it works:

1. Inject (inject=True): Before each LLM call, top_k relevant facts are retrieved from the store and prepended to the system prompt as:

   ## What I remember about you:
   - User prefers dark mode (confidence: high)
   - User works on Python projects (confidence: medium)

2. Extract (extract=True): After each conversation turn, the LLM extracts new facts from the exchange and stores them.

Decorator order (mandatory)

@remember() must sit between @agent() and @use_guardrails():

@agent(model="claude-opus-4-6")   # outermost — applied last
@remember(store=_memory, ...)      # reads/sets REMEMBER_META
@use_guardrails(input=[...])       # optional
@use_tools(my_tool)                # innermost — applied first
class MyAgent: ...

Python applies decorators bottom-up. Wrong ordering causes the decorator that reads metadata to run before the decorator that writes it, silently dropping tools, guardrails, or memory configuration.

Tier 2: Conversation history across runs

Use ConversationStore to persist full message history across multiple agent runs within a session. Declare it on the agent (or override it per call):

from lauren_ai import agent, InMemoryConversationStore

store = InMemoryConversationStore()

@agent(model="claude-opus-4-6", conversation_store=store)
class MyAgent: ...

Then pass a conversation_id on each run() call — the runner loads prior history before the new message and saves afterward:

# Turn 1
result1 = await runner.run(agent, "My name is Alice.", conversation_id="sess-1")
# Turn 2 — agent sees the full prior exchange
result2 = await runner.run(agent, "What is my name?", conversation_id="sess-1")
# result2.content → "Your name is Alice."

Without conversation_store, conversation_id is accepted but ignored.

Tier 4: Vector store for RAG

from lauren_ai import InMemoryVectorStore

store = InMemoryVectorStore()

# Index documents (requires EmbedService)
await store.add(
    texts=["Python is a programming language.", "FastAPI is an async web framework."],
    embed_service=embed_service,
)

# Query
results = await store.search(
    query="web development with Python",
    embed_service=embed_service,
    top_k=3,
)
for doc, score in results:
    print(f"{score:.3f} — {doc}")

Reference

See memory.md for:

• Full ShortTermMemory API (including ctx.memory access from lifecycle hooks)
• ConversationStore protocol and implementing a custom persistent backend
• @remember parameters (store, extract, inject, top_k, store_token)
• Manual store.add() / store.search() usage with MemoryFact
• Implementing a custom UserMemoryStore (e.g. Postgres-backed)
• InMemoryVectorStore full API
• TeamMemory shared state for multi-agent teams