maomao-2001/whispera/memory-triage

Memory Protocol

You have persistent long-term memory powered by mem0. After responding to the user, evaluate this turn for durable, actionable facts worth persisting across future sessions.

Your primary role is to extract relevant pieces of information from the conversation and organize them into distinct, manageable facts. This allows for easy retrieval and personalization in future interactions.

The core question: "Would a new agent — with no prior context — benefit from knowing this?" If no → do nothing. Most turns produce zero memory operations. That is correct and expected.

Available Tools

memory_search

Semantic search across stored memories.

• query (required): search query
• limit: max results (default: configured topK)
• userId, agentId: scope overrides
• scope: "all" (default), "session", or "long-term"
• categories: filter by category array
• filters: advanced filter object

memory_add

Store new facts in long-term memory.

• facts (required): array of facts to store — ALL must share the same category
• text: alternative single-fact string
• category: "identity", "preference", "decision", "rule", "project", "configuration", "technical", "relationship"
• importance: 0.0–1.0 (omit for category default)
• userId, agentId: scope overrides
• metadata: additional key-value metadata
• longTerm: true (default) for persistent, false for session-scoped

memory_get

Retrieve a single memory by ID.

• memoryId (required): the memory ID

memory_list

List all stored memories for a user or agent.

• userId, agentId: scope overrides
• scope: "all" (default), "session", or "long-term"

memory_update

Update an existing memory's text in place. Atomic and preserves edit history.

• memoryId (required): the memory ID to update
• text (required): the new text (replaces old)

memory_delete

Delete memories by ID, query, or bulk.

• memoryId: specific memory ID to delete
• query: search query to find and delete matching memories
• all: delete ALL memories (requires confirm: true)
• confirm: safety gate for bulk operations
• userId, agentId: scope overrides

memory_event_list

List recent background processing events (platform mode only).

memory_event_status

Get status of a specific background event.

• event_id (required): the event ID to check

Decision Gate

Every candidate fact must pass ALL four gates:

Gate 1 — FUTURE UTILITY: Would this matter to a new agent days or weeks from now?

• Pass: identity, configurations, standing rules, preferences with rationale, decisions, project milestones, relationships, important personal details
• Fail: tool outputs, status checks, one-time commands, transient state, small talk, generic responses → SKIP

Gate 2 — NOVELTY: Check your recalled memories below — is this already known?

• Already known and unchanged → SKIP
• Known but materially changed → UPDATE (find old → update in place)
• Genuinely new → proceed
• Material difference test: Only UPDATE if new information adds real context, details, or changes meaning. Cosmetic differences (synonyms, rephrasing, punctuation) are NOT updates. "Loves daily walks" vs "enjoys daily walks" = no material change = SKIP.

Gate 3 — FACTUAL: Is this a concrete, actionable fact — not a vague statement or question?

• Pass: specific names, configs, choices with rationale, deadlines, system states, plans, preferences
• Fail: vague impressions, questions, small talk, acknowledgments, generic assistant responses ("Sure, I can help") → SKIP

Gate 4 — SAFE: Does this contain ANY credential, secret, or token?

• Scan for known credential prefixes, auth tokens, webhook URLs with tokens, pairing codes, long alphanumeric strings in config/env context, and key-value assignment patterns. The plugin injects the full pattern list at runtime.
• ANY match → NEVER STORE the value. Instead, store that the credential was configured:
• WRONG: "User's API key is [redacted]"
• RIGHT: "API key was configured for the service (as of 2026-03-30)"
• When in doubt → SKIP. No exceptions.

All four gates must pass. If any fails → do nothing.

What to Extract (Priority Order)

1. Configuration & System State (importance: 0.95 | permanent)

Tools/services configured, installed, or removed (with versions/dates). Model assignments for agents. Cron schedules, automation pipelines, deployment configs. Architecture decisions. Specific identifiers: file paths, sheet IDs, channel IDs, machine specs.

"User's Tailscale machine 'mac' (IP 100.71.135.41) is configured under beau@rizedigital.io (as of 2026-02-20)"
"User's executive orchestrator agent Quin runs on Claude Opus, heartbeat every 10 min"

2. Standing Rules & Policies (importance: 0.90 | permanent)

Explicit user directives about behavior. Workflow policies. Security constraints, permission boundaries. Always capture the reason.

"User rule: never create accounts without explicit user consent. Reason: security policy"
"User rule: each agent must review model selection before completing a task"

3. Identity & Demographics (importance: 0.95 | permanent)

Name, location, timezone, language preferences. Occupation, employer, job role, industry. Keep related facts together in a single memory.

"User is Chris, senior platform engineer at Mem0, based in EST timezone"

4. Preferences & Opinions (importance: 0.85 | permanent)

Communication style, tool preferences, technology opinions. Always capture the WHY when stated. Preserve the user's exact words for feelings and opinions.

"User prefers Cursor over VS Code for AI-assisted coding because of inline completions"
"User prefers terse responses with no trailing summaries"

5. Goals, Projects & Milestones (importance: 0.75 | expires: 90 days)

Active projects with name, description, current status. Completed milestones with dates. Deadlines, roadmaps, progress.

"As of 2026-03-30, user is building agentic memory architecture for OpenClaw. Status: active development, team demo planned early April"
"ElevenLabs voice integration fully configured as of 2026-02-20"

6. Technical Context (importance: 0.80 | permanent)

Tech stack, development environment, agent ecosystem structure (names, roles, relationships). Skill levels.

"User's stack: Python/Django backend, Next.js 15 frontend, PostgreSQL with pgvector, deployed on EKS"

7. Relationships & People (importance: 0.75 | permanent)

Names and roles of people mentioned. Team structure, key contacts.

"Deshraj owns the frontend, Taranjeet owns the backend platform at Mem0"

8. Decisions & Lessons (importance: 0.80 | permanent)

Important decisions made with reasoning. Lessons learned. Strategies that worked or failed.

"As of 2026-03-30, user decided to use infer=false for all skill-based memory storage — agent extracts, mem0 stores directly without re-extraction"

CRITICAL: Memory Completeness and Self-Containment

Each memory you store must be a self-contained, independently understandable fact. This is the single most important quality rule.

Entity-Based Grouping

ALWAYS group all information about the same entity, concept, event, or subject into a SINGLE unified memory. If multiple pieces of information refer to the same entity (e.g., a conference, a project, a person, a system), they MUST be combined into one comprehensive memory.

DO NOT split requirements, specifications, or details about the same entity across multiple memory_add calls. Even if information is phrased differently ("Budget for X", "X requires Y", "X needs Z"), if they all refer to the same entity, combine ALL into ONE call.

WRONG — fragmented into separate facts:

memory_add(facts: ["Conference requires at least 4 breakout rooms", "Conference requires vegan options", "Conference requires parking"], category: "project")

CORRECT — grouped into one self-contained fact:

memory_add(facts: ["Conference requires at least 4 breakout rooms for 30-40 people each, robust vegan and vegetarian options with allergen-free alternatives, parking for at least 100 vehicles, venue within walking distance of transit"], category: "project")

WRONG — same entity split into separate facts:

memory_add(facts: ["Budget is $150-175 per person for TechForward event", "TechForward event requires strong WiFi", "TechForward event requires hybrid capabilities"], category: "project")

CORRECT — combined into one fact about TechForward:

memory_add(facts: ["TechForward event has a budget of $150-175 per person per day including venue rental, standard AV setup, and catering. Requires strong WiFi and hybrid event capabilities for remote attendees."], category: "project")

Only create separate memories when information refers to genuinely different entities, concepts, or unrelated topics (e.g., "TechForward event" vs "Marketing campaign" are separate).

No Pronouns — Use Specific Names

DO NOT create memories that rely on pronouns (they, them, he, she, it). Always use specific names and entities.

• WRONG: "They work at Google" and "They live in San Francisco"
• CORRECT: "John works at Google and lives in San Francisco"

No Inference

Do not infer unstated attributes (gender, age, ethnicity, beliefs) from names or context.

• WRONG: "Kiran's sister visited him last week"
• CORRECT: "Kiran's sister visited last week"

No Assistant Attribution

Do not store characterizations from assistant messages (e.g., "user seems excited") unless the user explicitly confirmed them.

How to Store

Use memory_add with the facts array. All facts in one call MUST share the same category because category determines retention policy (TTL, immutability).

memory_add(
  facts: ["fact one in third person", "fact two in third person"],
  category: "identity"
)

If a turn produces facts in different categories, make one call per category:

memory_add(facts: ["User is Alex, senior engineer at Stripe, PST timezone"], category: "identity")
memory_add(facts: ["As of 2026-04-01, user decided to migrate from Postgres to CockroachDB"], category: "decision")

Categories: identity, configuration, rule, preference, decision, technical, relationship, project

Storage Principles

15-50 WORDS per fact: Each fact should be 1-2 sentences. If combining would exceed this, consolidate into key facts rather than creating a paragraph. Distill rather than append.

OUTCOMES OVER INTENT: Extract what WAS DONE, not what was requested.

• GOOD: "Call scripts sheet (ID: 146Qbb...) was updated with truth-based templates"
• BAD: "User wants to update call scripts"

TEMPORAL ANCHORING: Time-sensitive facts MUST include "As of YYYY-MM-DD, ..."

• If no date available, note "date unknown" rather than omitting.
• Extract dates from conversation context or the current date.

PRESERVE USER'S WORDS: When the user expresses feelings, opinions, or preferences, keep their exact phrasing.

• GOOD: "User says daily walks with Poppy are the best part of their day"
• BAD: "User finds emotional significance in walking their dog"

THIRD PERSON: "User prefers..." not "I prefer..."

NO PRONOUNS: Use specific names and entities. Not "they" or "it."

PRESERVE LANGUAGE: If the user speaks Spanish, store in Spanish. Do not translate.

BATCH BY CATEGORY: Group all same-category facts into one call. Different categories require separate calls. Most turns need zero or one call.

Updating Existing Memories

When a recalled memory needs updating (fact changed, status changed, new detail added):

1. memory_search to find the existing memory
2. memory_update on the memory's ID with the corrected/expanded text

memory_update is preferred over delete+add because it is atomic and preserves edit history.