#Memory

These examples give an agent recall: remembering prior turns, extracting
reusable skills and insights, and retrieving attached resources at execution
time. Memory is opt-in and configurable per agent.

#Enabling memory

The simplest configuration: turn it on, pick a level, let defaults handle
the rest.

python

from maivn import Agent, MemoryConfig agent = Agent(    name='Memory Demo Agent',    system_prompt='You are an analyst. Use prior context when available.',    api_key='...',    memory_config=MemoryConfig(enabled=True, level='clarity'),)

Memory level controls how much the agent retains and recalls, ranging from
off to the richest experience:

Level	Behavior
`'none'`	Memory disabled.
`'glimpse'`	Lightweight thread context only.
`'focus'`	Thread context plus moderate recall.
`'clarity'`	Full thread context plus extracted skills and insights.

For day-to-day work, clarity is the sweet spot. Pair level with
persistence_mode ('persist_none', 'vector_only', or
'vector_plus_graph') to control how that memory is stored and retrieved.

#A seed-and-recall pattern

Drop fact-dense context into the first turn; ask for recall in a second
turn on the same thread:

python

from maivn import Agent, MemoryConfig, MemoryRetrievalConfigfrom maivn.messages import HumanMessage agent = Agent(    name='Memory Demo Agent',    system_prompt='You are an operations analyst. Use prior context when available.',    api_key='...',    memory_config=MemoryConfig(        enabled=True,        level='clarity',        persistence_mode='vector_plus_graph',        retrieval=MemoryRetrievalConfig(top_k=2, candidate_limit=2),    ),) thread_id = 'project-coastal-shield' # Turn 1: seedagent.invoke(    [HumanMessage(content=(        'Project Coastal Shield priorities:\n'        '1) Salt marsh restoration — owner: Lena Brooks, deadline 2027-03-15\n'        '2) Stormwater pump upgrade — owner: Marcus Lee, deadline 2028-08-30\n'        '3) Community cooling centers — owner: Priya Raman, deadline 2029-05-01\n'        'Budget cap: $185M. Escalate if sea-level trend exceeds 8mm/year.'    ))],    thread_id=thread_id,) # Turn 2: recall on the same threadresponse = agent.invoke(    [HumanMessage(content='List the priorities, owners, deadlines, and escalation trigger.')],    thread_id=thread_id,)

The same thread_id puts both invocations on the same conversation; memory
retrieval surfaces the seed turn's facts when the recall turn asks for them.

#Full retrieval configuration

For finer control over how much context is pulled in:

python

from maivn import (    MemoryConfig,    MemoryRetrievalConfig,    MemorySkillExtractionConfig,    MemoryInsightExtractionConfig,) memory_config = MemoryConfig(    enabled=True,    level='clarity',    summarization_enabled=True,    persistence_mode='vector_plus_graph',    retrieval=MemoryRetrievalConfig(        skills_enabled=True,        insights_enabled=True,        resources_enabled=True,        skill_injection_max_count=5,        insight_injection_max_count=5,        resource_injection_max_count=5,        top_k=6,        candidate_limit=12,        insight_relevance_floor=0.0,    ),    skill_extraction=MemorySkillExtractionConfig(        enabled=True,        sharing_scope='project',    ),    insight_extraction=MemoryInsightExtractionConfig(        enabled=True,        sharing_scope='agent',    ),)

Skills — reusable procedural patterns the agent learns over time.
sharing_scope='project' means every agent in the project can use them.
Insights — declarative facts ("this customer prefers async over
email"). sharing_scope='agent' keeps them private to one agent.

#Bound skills

Pre-supply skills the agent should always know about, instead of waiting
for them to be extracted from conversation:

python

BOUND_SKILLS = [    {        'skill_id': 'general_research_workflow_v1',        'name': 'general_research_workflow',        'description': (            'For any user question, gather context, synthesize findings, then '            'answer with concise bullets plus optional next steps.'        ),        'steps': [            {'index': 1, 'action': 'identify core question and constraints'},            {'index': 2, 'action': 'extract relevant evidence from memory'},            {'index': 3, 'action': 'compose a clear answer with confidence caveats'},        ],    },] agent = Agent(    name='General Memory Agent',    system_prompt='...',    api_key='...',    memory_config=memory_config,    skills=BOUND_SKILLS,)

#Attaching resources

Agents can be bound to documents (PDFs, transcripts, images, video) at
construction time. The runtime registers them, hashes them so re-attaching
is a no-op, and makes them retrievable when relevant:

python

agent = Agent(    name='Product Analyst',    system_prompt='You know the product deeply. Answer from the attached docs.',    api_key='...',    resources=[        {'path': 'docs/product_overview.pdf', 'name': 'Product Overview'},        {'path': 'docs/user_research_2025.pdf', 'name': 'User Research 2025'},    ],    memory_config=memory_config,)

Content-hashed: re-running with the same files doesn't re-upload, and
changing a file's content automatically supersedes the prior version.

#Inspecting memory lifecycle events

If you want to see what memory is doing under the hood, attach an event
callback that filters for the memory phases. agent.events(...) builds an
invocation wrapper; chain a terminal .invoke() (or .stream()) to run it.
Each callback dict carries category, event, and payload:

python

memory_events = [] def on_event(event: dict) -> None:    if event.get('event') == 'enrichment':        phase = event.get('payload', {}).get('phase', '')        if phase.startswith('memory_'):            memory_events.append(event['payload']) agent.events(include='enrichment', on_event=on_event).invoke(    messages,    thread_id=thread_id,) # Now `memory_events` holds the memory-phase enrichment payloadsfor e in memory_events:    print(e.get('phase'), '-', e.get('message'))

#Memory + structured final tool

Final tools work the same way they would without memory — but you can
combine @depends_on_private_data and memory retrieval, and the runtime
keeps them straight:

python

@agent.toolify(name='operations_brief', final_tool=True)class OperationsBrief(BaseModel):    summary: str    priorities: list[str]    deadlines: list[str]    risk_flags: list[str]

The agent's memory layer surfaces the seeded context; the final tool
captures the recalled answer in a structured shape.

#What's next

Memory & Recall guide — the deeper
treatment of skills, insights, retrieval policies, and the asset
lifecycle.
Swarms — each agent in a swarm can have its own bound
resources for specialist roles.
Private Data — combining memory with
redaction-safe execution.