Smart Memory Guide

Smart Memory is Aegis’s intelligent extraction layer that automatically determines what’s worth remembering from conversations. Instead of storing everything (noise) or requiring manual decisions (burden), Smart Memory uses a two-stage process to extract and store only valuable information.

Quick Start

from aegis_memory import SmartMemory

# Initialize with your API keys
memory = SmartMemory(
    aegis_api_key="your-aegis-key",
    llm_api_key="your-openai-key"
)

# After each conversation turn, process it
memory.process_turn(
    user_input="I'm John, a Python developer from Chennai. I prefer dark mode.",
    ai_response="Nice to meet you, John! I'll remember your preferences.",
    user_id="user_123"
)

# Later, get relevant context for a new query
context = memory.get_context(
    query="What color theme should I use?",
    user_id="user_123"
)

print(context.context_string)
# Output:
# - User's name is John
# - User is a Python developer
# - User is based in Chennai
# - User prefers dark mode for applications

How It Works

Smart Memory uses a two-stage process to avoid expensive LLM calls while maintaining quality:

┌─────────────────────────────────────────────────────────────────┐
│  STAGE 1: FAST FILTER (Rule-based, ~0.1ms)                      │
│                                                                  │
│  Checks for memory signals:                                      │
│  ✓ "I'm" → Personal fact signal                                 │
│  ✓ "developer" → Professional fact signal                       │
│  ✓ "from Chennai" → Location signal                             │
│                                                                  │
│  Decision: WORTH EXTRACTING                                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  STAGE 2: LLM EXTRACTION (~200ms, only if Stage 1 passes)       │
│                                                                  │
│  Extracts atomic facts:                                          │
│  1. "User's name is John" (confidence: 0.95)                    │
│  2. "User is a developer" (confidence: 0.90)                    │
│  3. "User is based in Chennai" (confidence: 0.92)               │
└─────────────────────────────────────────────────────────────────┘

Cost Comparison

Approach	LLM Calls	Cost	Quality
Store everything	0	Low	Poor (noisy)
LLM for everything	100%	High	Good
Two-stage (Smart)	~30%	Low	Good

The filter catches obvious non-memories (greetings, confirmations) without LLM calls, saving ~70% of extraction costs.

Use Cases

Conversational
Coding
Task
Support

memory = SmartMemory(use_case="conversational", ...)

Extracts: Preferences, personal facts, relationshipsIgnores: Greetings, one-time questions, temporary states

memory = SmartMemory(use_case="coding", ...)

Extracts: Tech stack decisions, architecture choices, bugs and solutionsIgnores: Syntax questions, one-off debugging

memory = SmartMemory(use_case="task", ...)

Extracts: Decisions, constraints, problems solved, strategiesIgnores: Implementation details, debugging steps

memory = SmartMemory(use_case="support", ...)

Extracts: User setup, past issues, skill level, account detailsIgnores: Troubleshooting steps, generic support talk

Configuration

Sensitivity Levels

# High sensitivity - extract more, risk some noise
memory = SmartMemory(sensitivity="high", ...)

# Balanced (default) - good balance
memory = SmartMemory(sensitivity="balanced", ...)

# Low sensitivity - extract less, only high-confidence
memory = SmartMemory(sensitivity="low", ...)

LLM Providers

# OpenAI (default)
memory = SmartMemory(
    llm_provider="openai",
    llm_api_key="sk-...",
    llm_model="gpt-4o-mini"
)

# Anthropic
memory = SmartMemory(
    llm_provider="anthropic",
    llm_api_key="sk-ant-...",
    llm_model="claude-3-haiku-20240307"
)

SmartAgent (Full Auto)

For the simplest experience, use SmartAgent which handles everything:

from aegis_memory import SmartAgent

agent = SmartAgent(
    aegis_api_key="your-aegis-key",
    llm_api_key="your-openai-key",
    system_prompt="You are a helpful coding assistant."
)

# Memory is completely automatic
response = agent.chat("I'm John, I prefer Python over JavaScript", user_id="user_123")
response = agent.chat("What language should I use?", user_id="user_123")
# Agent automatically knows user prefers Python!

What Gets Stored

Category	Description	Example
`preference`	Likes, dislikes, style	”User prefers dark mode”
`fact`	Personal information	”User is a developer in Chennai”
`decision`	Choices made	”User decided to use React”
`constraint`	Limits and requirements	”Budget is $5000”
`goal`	What user wants	”User wants to build a chatbot”
`strategy`	What worked	”Using async improved performance”
`mistake`	What didn’t work	”Don’t use range() for large pagination”

Best Practices

Choose the Right Use Case

Match use case to your domain. Don’t use “conversational” for coding tasks.

Use Appropriate Sensitivity

High sensitivity for personal assistants. Low sensitivity for task agents.

Monitor Extraction Stats

stats = memory.get_stats()
print(f"Filter rate: {stats['filter_rate']:.1%}")
# If filter_rate is too high, increase sensitivity

Combine with Explicit Storage

Use Smart Memory for conversations, explicit storage for known-important info.

Troubleshooting

Nothing is being extracted

Check sensitivity: memory = SmartMemory(sensitivity="high", ...)
Use force_extract=True to bypass filter
Check stats: print(memory.get_stats())

Too much noise being stored

Lower sensitivity: sensitivity="low"
Use a more specific use case
Create custom filter patterns

LLM costs too high

Use cheaper models: gpt-4o-mini or claude-3-haiku
Lower sensitivity to reduce LLM calls
Use auto_store=False for custom storage logic

Guides

Smart Memory

Smart Memory Guide

Quick Start

How It Works

Cost Comparison

Use Cases

Configuration

Sensitivity Levels

LLM Providers

SmartAgent (Full Auto)

What Gets Stored

Categories

Best Practices

Troubleshooting

​Smart Memory Guide

​Quick Start

​How It Works

​Cost Comparison

​Use Cases

​Configuration

​Sensitivity Levels

​LLM Providers

​SmartAgent (Full Auto)

​What Gets Stored

​Categories

​Best Practices

​Troubleshooting

Smart Memory Guide

Quick Start

How It Works

Cost Comparison

Use Cases

Configuration

Sensitivity Levels

LLM Providers

SmartAgent (Full Auto)

What Gets Stored

Categories

Best Practices

Troubleshooting