Memory Tiers & Evolution

Snipara combines explicit project and owner profiles with reviewed, tiered memory. Session bootstrap reserves bounded space for those anchors before active decisions, durable memory, and recent daily carryover.

Memory Tier System

The three tiers are the session-loading policy model. They should not be read as a guarantee that every write is automatically reclassified from its memory type or access count.

Tier assignment and session loading

snipara_remember stores reviewed memory with explicit type and scope metadata. The current write path does not guarantee the type-only mapping shown in older examples; inspect the returned record and the active session-loading policy before treating a memory as CRITICAL, DAILY, or ARCHIVE.

• DECISION and FACT are commonly prioritized as CRITICAL
• TODO and CONTEXT are commonly considered for DAILY loading
• LEARNING and PREFERENCE are commonly queried from ARCHIVE

Promotion and compaction caveat

Promotion thresholds are policy examples, not a universal automatic behavior of every storage path. Frequent recall or confidence can inform a review decision, but neither makes a memory more true or bypasses evidence review.

• Access count ≥ 3: A project policy may nominate frequently recalled memories for review
• Confidence ≥ 0.8: A project policy may use confidence as a review signal; it does not itself promote the record

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:

• profiles: Metadata for the selected project and owner profile records
• critical: Bounded profile entries, active decisions, and other CRITICAL memories for backward-compatible clients
• daily: DAILY tier memories from today + yesterday
• total_tokens: Combined token count

Selection is deterministic when the budget is tight: project profile → owner profile → active decisions → other durable memory → daily carryover. The project slot reserves the newest active project/client profile. Additional active tenant profiles remain ordinary critical entries when the remaining budget allows. Each reserved profile has a bounded allocation, so one large profile cannot consume the entire session budget. Older clients still receive the selected profile rows in critical; newer clients can also inspect the additive profiles metadata.

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
    archive_older_than_days=30  # Policy-controlled archival candidate
)

Compaction performs:

1. Promotion: Reviewable candidates may be promoted by an active policy
2. Archival: Old non-critical memories may be nominated for ARCHIVE
3. Deduplication: Merge similar memories

The project-profile category and canonical owner-profile category are protected from generic compaction. A normal compaction run does not promote, archive, conflict-normalize, or deduplicate them as if they were ordinary notes; the dedicated profile APIs manage them explicitly.

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

Project / Tenant Profiles

For client projects and repository workspaces, create structured project profiles that auto-load as CRITICAL memories. These records are project-scoped: they describe the product and repository, not the personal owner.

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

Owner Operating Profiles

The owner operating profile is the explicit, canonical USER-scoped profile for the authenticated owner. It follows that owner across projects and tells agents how to communicate, handle decisions, exercise autonomy, verify work, and preserve durable product principles. It is not conversation history or an inferred psychological profile.

snipara_owner_profile_get

# Get the authenticated user's canonical owner profile
snipara_owner_profile_get()

# Integrator client keys identify their isolated end user
snipara_owner_profile_get(external_user_id="customer-42")

snipara_owner_profile_update

snipara_owner_profile_update(
    profile={
        "preferred_language": "French",
        "communication_style": "Direct and evidence-first",
        "decision_style": "Recommend one path after showing tradeoffs",
        "autonomy_preference": "Finish agreed work end to end",
        "risk_tolerance": "Conservative for production changes",
        "evidence_preferences": "Tests and live production proof",
        "product_principles": ["Keep shipped claims verifiable"],
        "non_negotiables": ["Never store secrets in memory"],
        "working_preferences": ["Commit each substantial phase"]
    },
    evidence_refs=["decision-receipt-123"]
)

# Replace instead of patching supplied fields
snipara_owner_profile_update(profile={...}, replace=True)

Automatically extracted or inferred traits remain pending review candidates and never silently become the canonical profile. Review can accept a candidate as ordinary durable memory; only an explicit owner-profile update changes the canonical profile. Never put secrets, credentials, or private keys in profile fields.

Agent Profiles

Agent profiles are separate from owner profiles. They 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