Memory Management

Effectively manage agent memory for optimal performance and cost.

Memory Lifecycle

Creation

Memory is created automatically when agents interact:

@agent.on_message
async def handle_message(message):
    # Memory is automatically stored
    await agent.remember(message.content)

Retrieval

Retrieve relevant memories:

# Get recent memories
recent = await agent.memory.get_recent(limit=10)

# Search memories
relevant = await agent.memory.search(query, limit=5)

Update

Update existing memories:

await agent.memory.update(
    memory_id="mem_123",
    content="Updated content"
)

Deletion

Clean up old memories:

# Delete specific memory
await agent.memory.delete("mem_123")

# Delete old memories
await agent.memory.cleanup(older_than="30d")

Memory Optimization

Set Appropriate TTLs

Configure time-to-live:

{
  "memory": {
    "shortTerm": { "ttl": "1h" },
    "longTerm": { "ttl": "30d" }
  }
}

Implement Memory Compression

Compress old memories:

@agent.schedule("0 0 * * *")  # Daily
async def compress_memories():
    old_memories = await agent.memory.get_old(days=7)
    summary = await agent.summarize(old_memories)
    await agent.memory.replace(old_memories, summary)

Use Memory Scopes

Isolate memory by scope:

{
  "memory": {
    "scope": "per-user"  // per-user | per-session | global
  }
}

Memory Search

Vector Search

Semantic search using embeddings:

results = await agent.memory.search(
    query="customer complaints",
    type="vector",
    limit=5
)

Text Search

Keyword-based search:

results = await agent.memory.search(
    query="billing issue",
    type="text",
    limit=5
)

Hybrid Search

Combine vector and text search:

results = await agent.memory.search(
    query="refund request",
    type="hybrid",
    vector_weight=0.7,
    text_weight=0.3
)

Memory Analytics

Track Memory Usage

Monitor memory metrics:

swiftclaw memory stats my-agent

Memory Insights

Get insights about memory:

stats = await agent.memory.stats()
print(f"Total memories: {stats.count}")
print(f"Storage used: {stats.size}")
print(f"Oldest memory: {stats.oldest}")

Best Practices

Regular Cleanup

Schedule regular cleanup:

@agent.schedule("0 0 * * 0")  # Weekly
async def cleanup():
    await agent.memory.cleanup(older_than="30d")

Monitor Memory Size

Set size limits:

{
  "memory": {
    "maxSize": "100MB",
    "onLimit": "compress"  // compress | delete-old | error
  }
}

Use Appropriate Scopes

Choose the right scope:

per-user: User-specific data
per-session: Temporary context
global: Shared knowledge

Proper memory management can reduce costs by 40-60% while improving performance.