Memory Tiers & Evolution

Snipara's memory system uses intelligent tiering to automatically prioritize and manage agent memories, ensuring the most relevant context is always available.

Memory Tier System

Memories are automatically classified into three tiers based on type, access patterns, and age:

Automatic Classification

When you store a memory with snipara_remember, it's automatically assigned to a tier based on its type:

• DECISION and FACT → CRITICAL (always available)
• TODO and CONTEXT → DAILY (recent context)
• LEARNING and PREFERENCE → ARCHIVE (query when needed)

Automatic Promotion

Memories can be promoted to CRITICAL tier based on usage:

• Access count ≥ 3: If a memory is recalled 3+ times, it's promoted to CRITICAL
• Confidence ≥ 0.8: High-confidence memories are promoted automatically

Daily Journals

Daily journals provide temporal structure to your operational notes. Unlike flat memories, journals are organized by day and automatically included in session context.

snipara_journal_append

Add an entry to today's journal:

snipara_journal_append(
    text="Completed auth refactor. Switched from JWT to session cookies.",
    tags=["auth", "refactor"]
)

snipara_journal_get

Read journal entries for a specific date:

# Today's entries
snipara_journal_get()

# Specific date with yesterday included
snipara_journal_get(date="2026-03-18", include_yesterday=True)

snipara_journal_summarize

Prepare a day's journal for summarization before archival:

snipara_journal_summarize(date="2026-03-18")

# Returns combined content with a suggested summarization prompt

Session Memory Loading

Use snipara_session_memories to get tiered memories optimized for session start:

snipara_session_memories(
    max_critical_tokens=8000,
    max_daily_tokens=4000,
    include_yesterday=True
)

This returns:

• critical: All CRITICAL tier memories within token budget
• daily: DAILY tier memories from today + yesterday
• total_tokens: Combined token count

Memory Compaction

Over time, memories accumulate. Use compaction to optimize your memory store:

snipara_memory_compact

# Preview changes first
snipara_memory_compact(dry_run=True)

# Execute compaction
snipara_memory_compact(
    deduplicate=True,           # Merge duplicate memories
    promote_threshold=3,        # Promote learnings accessed 3+ times
    archive_older_than_days=30  # Archive old non-critical memories
)

Compaction performs:

1. Promotion: Frequently-accessed learnings → CRITICAL
2. Archival: Old non-critical memories → ARCHIVE
3. Deduplication: Merge similar memories

snipara_memory_daily_brief

Generate a "Top 10 constraints" brief for the day:

snipara_memory_daily_brief(max_items=10)

# Returns formatted brief with:
# - Active decisions
# - Pending TODOs
# - Recent learnings

Tenant Profiles

For client projects, create structured tenant profiles that auto-load as CRITICAL memories:

snipara_tenant_profile_create

snipara_tenant_profile_create(
    client_name="Acme Corp",
    business_model="B2B SaaS for logistics",
    industry="Supply Chain",
    tech_stack="React, Node.js, PostgreSQL, AWS",
    legal_constraints="GDPR compliant, SOC2 Type II",
    security_requirements="MFA required, no PII in logs",
    risk_tolerance="low",
    dos=["Always validate input", "Use parameterized queries"],
    donts=["Never store passwords in plaintext"]
)

snipara_tenant_profile_get

# Get all profiles for the project
snipara_tenant_profile_get()

# Get specific profile by ID
snipara_tenant_profile_get(tenant_id="mem_xyz789")

Agent Profiles

Agent profiles define the persistent identity of a swarm participant: personality, communication style, boundaries, and memory scope. They are useful when specialist agents should behave consistently across sessions.

# Load an agent profile
snipara_agent_profile_get(
    swarm_id="swarm_abc123",
    agent_id="architect-1"
)

snipara_agent_profile_update

snipara_agent_profile_update(
    swarm_id="swarm_abc123",
    agent_id="architect-1",
    profile={
        "display_name": "Architecture Lead",
        "communication_style": "Concise, direct, evidence-first",
        "boundaries": ["Do not approve schema changes without migration review"],
        "memory_scope": "project"
    }
)

Best Practices

Architecture Overview