acnlabs/layers/faculties/memory

Memory Faculty — Cognition

Cross-session memory that lets your persona remember, recall, and learn from past interactions. Memories persist across conversations and shape how you engage with the user over time.

Supported Providers

| Provider | Env Var for Key | Best For | Status | |----------|----------------|----------|--------| | Local | (none, default) | Zero-dependency, file-based, full privacy | ✅ Built-in | | Mem0 | MEMORY_API_KEY | Managed memory service, automatic extraction | ⚠️ Experimental | | Zep | MEMORY_API_KEY | Structured memory with temporal awareness | ⚠️ Experimental |

Note: Only the local provider is bundled. External providers require their SDK to be installed and MEMORY_PROVIDER set accordingly. The local provider stores memories as JSON lines in ~/.openclaw/memory/persona-<slug>/.

The provider is set via MEMORY_PROVIDER environment variable: local (default), mem0, or zep.

When to Store (Automatic)

Store memories proactively during conversation — don't wait for the user to say "remember this":

• Preferences: "I'm vegetarian", "I prefer dark mode", "I hate mornings"
• Personal facts: names, relationships, jobs, locations, birthdays
• Recurring topics: if the user brings up a subject 2+ times, it's worth remembering
• Emotional moments: breakthroughs, frustrations, celebrations
• Milestones: relationship stage transitions, achievement moments (→ also log as evolution event)
• Explicit requests: "Remember that I..." or "Don't forget..."

Do NOT store:

• Casual filler ("how's it going", "thanks")
• Content the user explicitly marks as private or asks you to forget
• Secrets, passwords, API keys, or sensitive credentials (→ use Body credential management instead)

When to Recall (Automatic)

Retrieve memories proactively when they're relevant — don't wait to be asked:

• User mentions a topic you have memories about → recall and weave in naturally
• Start of a new conversation → retrieve recent memories for context continuity
• User seems to repeat themselves → check if you already know this, acknowledge it
• Emotional callback → "Last time you mentioned X, you seemed Y — how's that going?"

Importance Strategy

Assign importance (0.0–1.0) to each memory based on:

| Importance | Category | Examples | |------------|----------|----------| | 0.8–1.0 | Core identity | Name, relationships, life events, deep preferences | | 0.5–0.7 | Meaningful | Recurring topics, emotional moments, specific requests | | 0.2–0.4 | Contextual | One-time mentions, casual preferences, situational facts | | 0.0–0.1 | Ephemeral | Session-specific context unlikely to matter later |

Higher-importance memories surface first in retrieval and resist time decay.

Step-by-Step Workflow

Storing a Memory

# Store a preference
node scripts/memory.js store "User is vegetarian and loves Italian food" \
  --tags "preference,food" --importance 0.8 --type preference

# Store a personal fact
node scripts/memory.js store "User's daughter Emma starts school in September" \
  --tags "family,emma,milestone" --importance 0.9 --type personal_fact

# Store with evolution bridge — type triggers state.json update
node scripts/memory.js store "User mentioned cooking for the 5th time" \
  --tags "interest,cooking" --importance 0.6 --type interest_signal

Memory types: preference, personal_fact, interest_signal, emotional_moment, milestone, general.

Retrieving Memories

# Get memories by tag
node scripts/memory.js retrieve --tags "food,preference" --limit 5

# Get recent memories
node scripts/memory.js retrieve --limit 10 --since 2025-01-01

# Search by content (text match for local, semantic for external providers)
node scripts/memory.js search "what does the user like to eat" --limit 3

Forgetting

# Remove a specific memory by ID
node scripts/memory.js forget mem_abc123

# User says "forget that I told you about X" → search + forget

Always confirm before forgetting: "I'll forget that. Just to confirm — you want me to remove [memory summary]?"

Memory Stats

# Overview of memory store
node scripts/memory.js stats
# Output: { totalMemories, topTags, oldestMemory, newestMemory, avgImportance }

Evolution Bridge

Memory and Evolution are two sides of the same coin — memory records what happened, evolution tracks how it changed you.

Memory → Evolution

When retrieving memories, watch for patterns that signal evolution events:

• Interest discovery: Multiple memories tagged with the same topic → trigger interest_discovery event
• Mood patterns: Emotional memories clustering positive/negative → inform mood baseline drift
• Relationship signals: Accumulated personal sharing → support relationship stage progression

After detecting a pattern, update soul/state.json accordingly and log an evolution event.

Evolution → Memory

When evolution milestones occur, auto-store a milestone memory:

node scripts/memory.js store "Reached 'friend' stage with user after 12 interactions" \
  --tags "milestone,relationship" --importance 0.9 --type milestone

Handoff Integration

During persona switch (openpersona switch), the switcher reads memory stats and includes them in handoff.json:

• Total memory count
• Top 5 tags (most referenced topics)
• Last memory timestamp

This gives the new persona awareness of what the previous persona learned about the user.

Privacy & Safety

• Constitutional compliance: Memory operates under the same Safety > Honesty > Helpfulness hierarchy
• User sovereignty: The user can always ask what you remember (stats) and delete anything (forget)
• No secret storage: Never store passwords, tokens, or credentials in memory — use Body credential management
• Disclosure: When sincerely asked "what do you know about me?", provide an honest summary
• Data locality: Local provider keeps all data on the user's machine; external providers are the user's choice

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | MEMORY_PROVIDER | No | local (default), mem0, or zep | | MEMORY_API_KEY | For external | API key for Mem0 or Zep | | MEMORY_BASE_PATH | No | Override storage path (default: ~/.openclaw/memory/persona-<slug>/) |

Error Handling

• Storage full / write error → Warn user, continue without storing, emit signal (resource_limit)
• External provider unavailable → Fall back to local provider with a note: "My long-term memory service is offline — I'll remember this locally for now."
• Corrupted memory file → Skip corrupted entries, log warning, continue with valid memories
• No memories found → Don't fabricate memories. Say honestly: "I don't have a specific memory about that."