persistent_user_memory

Skill: Persistent User Memory

Version: 1.0.0 Author: community Tags: memory, personalization, context, learning, stateful Requires: file system access, optional: vector store or SQLite

---

Overview

This skill gives OpenClaw a long-term, structured memory of the user it works with. Unlike session-scoped context, this memory persists across restarts, learns from patterns over time, and is actively consulted before every significant action.

The goal: make OpenClaw behave less like a capable stranger and more like a trusted assistant who actually knows you.

---

Memory Store Location

All memory is stored in a local file:

~/.openclaw/memory/user_profile.json

Never store memory in a temp directory. Never delete this file unless the user explicitly says "reset my memory" or "forget everything".

---

Memory Schema

{
  "identity": {
    "name": "",
    "timezone": "",
    "language": "en",
    "preferred_name": ""
  },
  "preferences": {
    "communication": {
      "email_tone": "formal | casual | neutral",
      "response_length": "concise | detailed",
      "sign_off": ""
    },
    "scheduling": {
      "protected_hours": [],
      "preferred_meeting_times": [],
      "buffer_between_meetings_minutes": 15
    },
    "work": {
      "tools": [],
      "stacks": [],
      "working_hours": { "start": "", "end": "" }
    }
  },
  "relationships": {
    "contacts": [
      {
        "name": "",
        "alias": [],
        "relationship": "boss | colleague | client | friend | family",
        "communication_notes": "",
        "last_interaction": ""
      }
    ]
  },
  "patterns": {
    "recurring_tasks": [],
    "common_mistakes": [],
    "frequent_requests": []
  },
  "episodic": [
    {
      "date": "",
      "summary": "",
      "outcome": "",
      "tags": []
    }
  ],
  "meta": {
    "created_at": "",
    "last_updated": "",
    "version": "1.0.0"
  }
}

---

Core Behaviors

1. Read Before Acting

Before any significant action (sending email, scheduling, running a script, making a purchase), silently load and consult user_profile.json. Apply relevant preferences without asking the user to repeat themselves.

Example: > User asks to draft an email to "Sarah" > → Look up Sarah in relationships.contacts > → Find she's a client, communication_notes says "very formal, always address as Ms. Chen" > → Draft accordingly, without prompting the user for tone

---

2. Write After Learning

After completing any task where a new preference, pattern, or fact was revealed, update memory silently. Do not announce every write. Do announce if a conflict is detected (see edge cases).

Trigger conditions for a memory write:

User corrects you → update the relevant field

User states a preference explicitly ("I always want...", "never do X")

A contact is mentioned with context for the first time

A recurring task is completed for the 3rd+ time

An error occurred and the user explained why it was wrong

---

3. Surface Memory Proactively

Occasionally surface relevant memory when it adds value. Do not do this constantly — only when it meaningfully changes what action should be taken.

Good: > "You mentioned last week the deploy failed because of a missing env var — want me to check for that before running?"

Bad (annoying): > "I remember you like concise emails! Here is a concise email."

---

4. Episodic Log

After any multi-step task or significant interaction, append a brief episode to episodic[]:

{
  "date": "2026-03-02",
  "summary": "Drafted contract email to Ms. Chen re: Q2 renewal",
  "outcome": "sent",
  "tags": ["email", "contract", "sarah-chen"]
}

Keep episodes short (1–2 sentences). Do not log trivial or one-line tasks. Trim episodes older than 180 days unless tagged important.

---

Edge Cases

❗ Conflicting Preferences

If a new instruction contradicts stored memory:

1. Do NOT silently overwrite. 2. Surface the conflict: > "You previously told me to always CC your manager on client emails, but this time you haven't mentioned it — should I still CC them, or update that preference?" 3. Wait for explicit resolution before writing.

---

❗ Ambiguous Contacts

If a name matches multiple contacts (e.g., two "Davids"):

1. Do NOT guess. 2. Ask: "Which David — David Kim (colleague) or David Okafor (client)?" 3. After resolution, update the episodic log and consider adding an alias.

---

❗ Sensitive or Private Data

Never store:

Passwords or API keys

Banking or payment details

Medical information unless user explicitly requests it

Verbatim message contents (summarize instead)

If the user tries to ask you to remember sensitive data, respond: > "I don't store that kind of information for your safety. You can use a password manager or secure vault instead."

---

❗ Memory Corruption / Parse Failure

If user_profile.json fails to parse:

1. Do NOT overwrite or delete it. 2. Back it up to user_profile.backup.json. 3. Notify the user: "Your memory file appears corrupted. I've backed it up and started fresh. Want me to try to recover it?" 4. Start with an empty profile.

---

❗ First Run (No Memory File)

If no memory file exists:

1. Create the file with empty defaults. 2. Do NOT ask the user a long onboarding questionnaire. 3. Learn passively through normal interaction — fill in fields as they naturally emerge. 4. After the 5th session, you may ask 1–2 targeted questions to fill obvious gaps (e.g., timezone, preferred name).

---

❗ User Asks "What Do You Know About Me?"

Respond with a human-readable summary, not raw JSON:

> "Here's what I know about you so far: > - You prefer concise, casual communication except with clients > - Your protected hours are 9–10am and noon–1pm > - You work primarily in Python and use VS Code > - I have notes on 4 contacts including your manager (Alex) and a client (Ms. Chen) > - I've logged 12 recent tasks"

Then offer: "Want to correct or add anything?"

---

❗ User Says "Forget [X]"

Surgically remove only the referenced data. Confirm before deleting: > "Just to confirm — you want me to forget everything about Ms. Chen, or just the communication notes?"

Never bulk-delete unless user says "forget everything" or "reset my memory."

---

Memory Hygiene (Automated)

Run silently on each startup:

Remove episodic entries older than 180 days (unless tagged important)

Deduplicate contacts with identical names

Flag fields that haven't been updated in 90+ days as stale (do not delete, just mark)

Rewrite meta.last_updated timestamp

---

Privacy Notes

All memory is stored locally only. Never send user_profile.json to any remote server or include it in API calls as raw context.

When passing memory to an LLM, extract only the relevant subset for the task at hand.

Memory is the user's property. Always honor deletion requests immediately.

---

Example Interactions

Learning a preference: > User: "Don't schedule anything before 9:30am." > Agent writes: preferences.scheduling.protected_hours: ["00:00–09:30"] > Agent: "Got it, I'll keep your mornings free."

Applying memory: > User: "Send the weekly report to the team." > Agent: checks patterns.recurring_tasks, finds this has been done before on Fridays at 4pm to a specific list → pre-fills recipients and subject line automatically.

Conflict resolution: > Stored: email tone for Alex = formal > User: "Send Alex a quick casual message about lunch" > Agent: Sends casual (user's explicit in-context instruction overrides stored default), then asks: "Should I update your default tone for Alex to casual?"

---

Installation

claw skill install persistent-user-memory

Or manually place this file at:

~/.openclaw/skills/persistent-user-memory/SKILL.md

---

Changelog

| Version | Notes | |---------|-------| | 1.0.0 | Initial release — full schema, edge cases, episodic log |