Memory - mAIvn Docs

#Memory

These examples give an agent recall: remembering prior turns, extracting reusable skills and insights, and retrieving attached resources at execution time. Memory is configurable per agent; explicitly disable it when your workflow requires no ordinary memory processing.

#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'`	2,000-character recall context budget.
`'focus'`	6,000-character recall context budget.
`'clarity'`	12,000-character recall context budget.

Choose the lowest level that provides the recall your workflow needs. 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, then ask for recall in a second turn on the same thread:

Python

from maivn import Agent, MemoryConfig, MemoryRetrievalConfig
from 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),
    ),
)

thread_id = 'project-coastal-shield'

# Turn 1: seed
agent.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 thread
response = 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',
    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,
    ),
    skill_extraction=MemorySkillExtractionConfig(
        enabled=True,
    ),
    insight_extraction=MemoryInsightExtractionConfig(
        enabled=True,
    ),
)

Skills represent reusable procedures; insights record lessons and observations. The extraction sharing_scope compatibility fields are not forwarded by the SDK. Use Portal curation or the memory client to promote an insight for broader reuse.

#Bound skills

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,
)

from maivn import Skill

for skill in BOUND_SKILLS:
    agent.add_skill(Skill.model_validate({
        **{key: value for key, value in skill.items() if key != 'skill_id'},
        'memory_id': skill['skill_id'],
    }))

#Attaching resources

Agents can be bound to documents (PDFs, transcripts, images, video) at construction time. The SDK uploads them before the first invocation and the server makes the bound resources available for retrieval:

Python

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

Registration is cached after the first invocation on this agent instance. A new instance uploads again; the server can deduplicate matching content. For explicit replacement by resource ID, use the resource client.

#Inspecting memory lifecycle events

To inspect memory lifecycle phases, 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 payloads
for 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.