Best Practices

Contents

• Core Concepts — Memory banks, taxonomy, memory types
• Bank Configuration — Missions, dispositions, entity labels
• Retaining Data — Content format, context, document_id, tags, observation scopes
• Recalling Memories — Budget, tag filtering, include options, query_timestamp
• Reflecting — Recall vs reflect, response_schema, auditing
• Mental Models — When to create, tag strategy, refresh
• Anti-patterns

Core Concepts​

Memory Banks​

A memory bank is an isolated memory store — the unit of separation between users, agents, or contexts. All operations (retain, recall, reflect) target a single bank. Banks do not share data.

• One bank per user is the most common pattern for multi-user applications
• One bank per agent is common for agent-specific long-term memory
• A shared bank with tags can work for cross-user analysis (see Tags)

Banks are auto-created on first use. Configure them before ingesting data to steer behavior.

Taxonomy​

Memory Types​

Facts extracted during retain are classified into three types:

Use types filtering in recall to target specific memory types.

Bank Configuration​

Configure a bank before first use to steer memory behavior for your domain. Misconfigured missions are the single biggest cause of low-quality memories.

Writing Effective Missions​

All three missions accept plain language. Be specific about your domain — vague missions produce vague results.

retain_mission​

Injected into the fact extraction prompt. Tells the LLM what to extract and what to ignore.

Tips:

• List the fact types you want (preferences, decisions, errors, commitments)
• List what to ignore — this is as important as what to include
• Match the mission to your actual data type (conversations vs documents vs tickets)

observations_mission​

Steers what patterns are synthesized during consolidation. Runs after retain.

Identify evolving preferences, recurring patterns, behavioral shifts, and contradictions
with prior knowledge. Focus on durable patterns — not transient states. Highlight when
user behavior contradicts previous observations.

Tips:

• Emphasize "durable patterns" to avoid ephemeral observation noise
• Mention contradiction detection explicitly if you need historical tracking
• Match scope to how often you expect patterns to change

reflect_mission​

Sets the agent persona and reasoning frame for reflect operations.

Disposition Traits​

Dispositions affect reflect only (not recall). Scale 1–5.

Common profiles:

Entity Labels​

Define a controlled vocabulary for classification. The LLM will extract and normalize values to your defined set.

{
  "entity_labels": [
    {
      "key": "tech_stack",
      "type": "multi-values",
      "values": [
        {"value": "python", "description": "Python programming language"},
        {"value": "typescript", "description": "TypeScript / Node.js"},
        {"value": "react", "description": "React frontend framework"}
      ]
    },
    {
      "key": "priority",
      "type": "value",
      "tag": true,
      "values": [
        {"value": "high", "description": "Urgent or blocking"},
        {"value": "low", "description": "Nice to have"}
      ]
    }
  ]
}

• type: "value" — single value per entity (last write wins)
• type: "multi-values" — accumulates multiple values
• tag: true — extracted label values are also added as tags (enables filtering by entity value)

Use entity labels when you need consistent classification — domain-specific terms, status values, priority levels, engagement types.

Retaining Data​

Content Format​

Pass the richest representation available. Never pre-summarize.

Conversation JSON (preferred):

[
  {"role": "user",      "content": "I'm using React for the frontend.", "timestamp": "2025-06-01T10:30:00Z"},
  {"role": "assistant", "content": "Got it. What state management are you using?"},
  {"role": "user",      "content": "Zustand. We moved away from Redux last quarter."}
]

Why not pre-summarize: The LLM extracts facts, entities, and relationships from structure. A summary like "user uses React and Zustand" loses the temporal reference ("last quarter"), the entity relationship (React↔frontend, Redux↔migration), and the causal context (moved away from).

The context Field​

High-impact on extraction quality. Always set it. Describes the nature and source of the content.

# Good — specific, descriptive
context="Customer support ticket #12345 from user Alice about a billing discrepancy"
context="Developer's architecture review session for the payments service"
context="User's onboarding form: stated goals, current tools, and team size"
context="Weekly standup notes: blockers, progress, and upcoming tasks"

# Bad — generic, adds no signal
context="some data"
context="conversation"
# Omitted entirely — extraction uses no context

The document_id Field​

Use for upsert behavior. Same document_id = delete previous version and reprocess.

Rules:

• Use stable, meaningful IDs (session ID, ticket ID, document UUID)
• Always use the same ID for a growing conversation — retain the full conversation with each new message
• Do NOT use random UUIDs per retain call — this creates duplicates

# Good — stable session ID
client.retain(bank_id="user-alice", items=[{
    "content": full_conversation,
    "document_id": f"session-{session_id}",
}])

# Bad — new random ID every call = duplicates
client.retain(bank_id="user-alice", items=[{
    "content": full_conversation,
    "document_id": str(uuid.uuid4()),  # ❌ creates a new document each time
}])

The timestamp Field​

Set whenever you have temporal context. Enables temporal retrieval strategies.

• ISO 8601 format: "2025-06-01T10:32:00Z"
• For conversations: set to when the conversation started
• Omitting it disables temporal ranking entirely

Tags: Naming Conventions​

Tags scope visibility. A memory tagged user:alice is only returned for recall/reflect calls that include user:alice in their tags filter (with strict matching).

Standard naming conventions:

Multi-tenant minimum: Every retain for user data must include at least user:<id>. Omitting it makes the memory globally visible.

# Multi-tenant retain — always tag with user ID
items=[{
    "content": conversation,
    "tags": ["user:alice", "session:s_abc", "topic:billing"],
    "document_id": f"session-{session_id}",
}]

Metadata Schema​

Use for source tracking and downstream linking. Not filterable — use tags for filtering.

# Source tracking
metadata={"source": "slack", "channel": "#engineering", "thread_id": "T123456"}

# Ticket linking
metadata={"ticket_id": "JIRA-123", "priority": "high", "reporter": "alice"}

# Document provenance
metadata={"url": "https://...", "section": "pricing-faq", "version": "2025-Q1"}

Metadata is returned with every recalled memory — use it to link memories back to source systems for UI display, deep-linking, or audit trails.

Observation Scopes​

Controls which tag combinations get their own observation pass.

Custom scope example (recommended for multi-tenant):

# Observations scoped to: user-level, team-level, and combined
observation_scopes=[
    ["user:alice"],
    ["team:engineering"],
    ["user:alice", "team:engineering"],
]

Sync vs Async​

Do not retain and recall in the same turn — retain is a write operation and the extracted memories will not be available immediately.

Recalling Memories​

Budget Selection​

Default to mid. Use low for high-frequency agent loops. Reserve high for explicit "deep recall" user-triggered flows.

Tag Filtering Modes​

Decision guide:

• Shared global knowledge + per-user: tags=["user:alice"], tags_match="any" — returns Alice's memories and untagged global memories
• Fully partitioned (no leakage): tags=["user:alice"], tags_match="any_strict" — Alice's memories only
• Multi-condition AND: tags=["user:alice", "topic:billing"], tags_match="all_strict" — only where both tags present

tag_groups for complex filters:

Tag groups use a tree structure with and/or/not compound nodes and {"tags": [...], "match": "..."} leaf nodes.

# Alice's billing memories OR shared billing memories (no user tag)
recall(
    query="...",
    tag_groups=[
        {"or": [
            {"tags": ["user:alice", "topic:billing"], "match": "all_strict"},
            {"and": [
                {"tags": ["topic:billing"], "match": "any_strict"},
                {"not": {"tags": ["user:alice"], "match": "any_strict"}},
            ]},
        ]}
    ]
)

include Options​

types Filtering​

query_timestamp​

Set for time-sensitive queries. Anchors temporal ranking to a specific point in time.

# "What was the team working on in January?"
recall(query="team priorities", query_timestamp="2025-01-31T23:59:59Z")

# Current context (most common)
recall(query="user preferences", query_timestamp=datetime.utcnow().isoformat() + "Z")

Reflecting​

Recall vs Reflect​

response_schema​

Use when you need structured output for programmatic consumption.

reflect(
    query="What are the user's top 3 technical preferences?",
    response_schema={
        "type": "object",
        "properties": {
            "preferences": {
                "type": "array",
                "items": {"type": "string"},
                "maxItems": 3
            },
            "confidence": {"type": "number", "minimum": 0, "maximum": 1}
        },
        "required": ["preferences", "confidence"]
    }
)
# Returns: result.structured_output["preferences"], result.structured_output["confidence"]

Auditing and Debugging​

Enable include.facts in production for audit trails. Enable include.tool_calls only during development.

Mental Models​

Mental models are pre-computed reflect responses stored for common queries. They return instantly and consistently.

When to Create​

• Common repeated queries that should return consistent answers
• High-traffic agents that need sub-100ms responses
• User profiles or personas read on every request
• Knowledge summaries reviewed or approved by humans
• Cross-session state that changes slowly (preferences, skills, background)

Tag Strategy​

Tags on a mental model filter BOTH which memories are used to build it AND which recall/reflect calls can see it.

# Per-user mental model — uses Alice's memories (all_strict applied automatically during refresh)
create_mental_model(
    bank_id="shared-bank",
    name="Alice's Technical Profile",
    source_query="Summarize Alice's technical background, preferred stack, and current projects",
    tags=["user:alice"],
)

# Global mental model — uses all memories, visible to everyone
create_mental_model(
    bank_id="shared-bank",
    name="Team Engineering Standards",
    source_query="What are the team's agreed engineering standards and conventions?",
    # No tags — reads all memories, visible to all
)

Refresh Strategy​

Create narrow, scoped models — one per knowledge dimension. A mental model titled "Everything about the user" is as useful as none.

Model granularity examples for a personal assistant:

• "User Profile" — demographics, preferences, stated goals
• "Current Projects" — active work, deadlines, blockers
• "Technical Stack" — languages, tools, frameworks used
• "Communication Style" — formality preferences, response length preferences

Anti-patterns​