openpersona 0.9.0 → 0.12.0

package/README.md

@@ -1,8 +1,8 @@
 # OpenPersona 🦞
 
-The open framework for creating and orchestrating dynamic agent personas.
+The open, agent-agnostic framework for creating and orchestrating dynamic agent personas.
 
-Four-layer architecture — **Soul / Body / Faculty / Skill** — on top of [OpenClaw](https://github.com/openclaw/openclaw). Inspired by [Clawra](https://github.com/SumeLabs/clawra).
+Four-layer architecture — **Soul / Body / Faculty / Skill** — generates standard SKILL.md skill packs that work with any compatible agent. Default integration with [OpenClaw](https://github.com/openclaw/openclaw). Inspired by [Clawra](https://github.com/SumeLabs/clawra).
 
 ## 🚀 Live Demo
 
@@ -33,11 +33,24 @@ npx openpersona create --preset base --install
 npx openpersona install samantha
 ```
 
+### Install as Agent Skill
+
+Give your AI coding agent the ability to create and manage personas — works with Cursor, Claude Code, Codex, Windsurf, and [37+ agents](https://github.com/vercel-labs/skills#supported-agents):
+
+```bash
+npx skills add acnlabs/OpenPersona
+```
+
 ## Key Features
 
-- **🧬 Soul Evolution** — Personas grow dynamically through interaction: relationship stages, mood shifts, evolved traits (★Experimental)
+- **🧬 Soul Evolution** — Personas grow dynamically through interaction: relationship stages, mood shifts, evolved traits, with governance boundaries and rollback snapshots (★Experimental)
+- **🛡️ Influence Boundary** — Declarative access control for external personality influence: who can affect which dimensions, with what drift limits. Safety-first (default: reject all)
+- **🌐 Evolution Channels** — Connect personas to shared evolution ecosystems (e.g. EvoMap) via soft-ref pattern: declared at generation time, activated at runtime
+- **🔌 A2A Agent Card** — Every persona generates an A2A-compliant `agent-card.json` and `acn-config.json`, enabling discovery and registration in ACN and any A2A-compatible platform
+- **🧠 Cross-Session Memory** — Pluggable memory faculty for persistent recall across conversations (local, Mem0, Zep)
+- **🔄 Context Handoff** — Seamless context transfer when switching personas: conversation summary, pending tasks, emotional state
 - **🎭 Persona Switching** — Install multiple personas, switch instantly (the Pantheon)
-- **🗣️ Multimodal Faculties** — Voice (TTS), selfie generation, music composition, reminders
+- **🗣️ Multimodal Faculties** — Voice (TTS), selfie generation, music composition, reminders, memory
 - **🌾 Persona Harvest** — Community-driven persona improvement via structured contribution
 - **💓 Heartbeat** — Proactive real-data check-ins, never fabricated experiences
 - **📦 One-Command Install** — `npx openpersona install samantha` and you're live
@@ -57,7 +70,7 @@ flowchart TB
   end
   subgraph Faculty ["Faculty Layer"]
     D["expression: selfie · voice · music"]
-    E["cognition: reminder"]
+    E["cognition: reminder · memory"]
   end
   subgraph Skill ["Skill Layer"]
     F["Local definitions + ClawHub / skills.sh"]
@@ -65,7 +78,7 @@ flowchart TB
 ```
 
 - **Soul** — Persona definition (constitution.md + persona.json + state.json) — all in `soul/` directory
-- **Body** — Three-dimensional: `physical` (robots/IoT), `runtime` (platform/channels/credentials/resources), `appearance` (avatar/3D model). Digital agents use `runtime` to declare their operational environment.
+- **Body** — Substrate of existence — three dimensions: `physical` (robots/IoT), `runtime` (REQUIRED — platform/channels/credentials/resources), `appearance` (avatar/3D model). Body is never null; digital agents have a virtual body (runtime-only).
 - **Faculty** — General software capabilities organized by dimension: Expression, Sense, Cognition
 - **Skill** — Professional skills: local definitions in `layers/skills/`, or external via ClawHub / skills.sh (`install` field)
 
@@ -73,6 +86,62 @@ flowchart TB
 
 Every persona automatically inherits a shared **constitution** (`layers/soul/constitution.md`) — universal values and safety boundaries that cannot be overridden by individual persona definitions. The constitution is built on five core axioms — **Purpose**, **Honesty**, **Safety**, **Autonomy**, and **Hierarchy** — from which derived principles (Identity, User Wellbeing, Evolution Ethics) follow. When principles conflict, safety and honesty take precedence over helpfulness. Individual personas build their unique personality **on top of** this foundation.
 
+### Soul Evolution (★Experimental)
+
+Personas with `evolution.enabled: true` grow dynamically through interaction. The `soul/state.json` file tracks relationship stages, mood shifts, evolved traits, speaking style drift, interests, and milestones.
+
+**Evolution Boundaries** — Governance constraints to keep evolution safe:
+
+- `immutableTraits` — An array of trait strings that can never be changed by evolution (e.g., `["empathetic", "honest"]`)
+- `minFormality` / `maxFormality` — Numeric bounds (1–10) constraining how far the speaking style can drift
+
+The generator validates these boundaries at build time, rejecting invalid configurations.
+
+**Evolution Channels** — Connect a persona to external evolution ecosystems using the soft-ref pattern:
+
+```json
+"evolution": {
+  "enabled": true,
+  "channels": [
+    { "name": "evomap", "install": "url:https://evomap.ai/skill.md", "description": "Shared capability evolution marketplace" }
+  ]
+}
+```
+
+The persona is aware of its evolution channels at generation time. The actual channel protocol (e.g. EvoMap's GEP-A2A) is provided by the channel's own `skill.md` — OpenPersona only declares the channel, not implements it.
+
+**Influence Boundary** — Declarative access control for external personality influence:
+
+```json
+"evolution": {
+  "influenceBoundary": {
+    "defaultPolicy": "reject",
+    "rules": [
+      { "dimension": "mood", "allowFrom": ["channel:evomap", "persona:*"], "maxDrift": 0.3 },
+      { "dimension": "interests", "allowFrom": ["channel:evomap"], "maxDrift": 0.2 }
+    ]
+  }
+}
+```
+
+- `defaultPolicy: "reject"` — Safety-first: all external influence is rejected unless a rule explicitly allows it
+- `dimension` — One of: `mood`, `traits`, `speakingStyle`, `interests`, `formality`
+- `allowFrom` — Source patterns: `persona:*`, `persona:<slug>`, `channel:<name>`, `community:*`
+- `maxDrift` — Maximum per-event drift magnitude (0–1)
+- Generator validates at build time: immutableTraits cannot be target dimensions; maxDrift must be 0–1
+
+External influence uses the `persona_influence` message format (v1.0.0) — transport-agnostic, works over ACN/A2A/HTTP.
+
+**State History** — Before each state update, a snapshot is pushed into `stateHistory` (capped at 10 entries). This enables rollback if evolution goes wrong.
+
+**Evolution Report** — Inspect a persona's current evolution state:
+
+```bash
+npx openpersona evolve-report samantha
+```
+
+Displays relationship stage, mood, evolved traits, speaking style drift, interests, milestones, and state history in a formatted report.
+
 ## Preset Personas
 
 Each preset is a complete four-layer bundle (`manifest.json` + `persona.json`):
@@ -101,7 +170,9 @@ persona-samantha/
 │   └── state.json        ← Evolution state (when enabled)
 ├── references/           ← On-demand detail docs
 │   └── <faculty>.md      ← Per-faculty usage instructions
-├── manifest.json         ← Four-layer manifest (heartbeat, allowedTools, layers, meta)
+├── agent-card.json       ← A2A Agent Card — discoverable via ACN and A2A platforms
+├── acn-config.json       ← ACN registration config (fill owner + endpoint at runtime)
+├── manifest.json         ← Four-layer manifest (heartbeat, allowedTools, layers, acn, meta)
 ├── scripts/              ← Faculty scripts (TTS, music, selfie — varies by preset)
 └── assets/               ← Static assets
 ```
@@ -114,6 +185,7 @@ persona-samantha/
 | **voice** | expression | Text-to-speech voice synthesis | ElevenLabs / OpenAI TTS / Qwen3-TTS | `ELEVENLABS_API_KEY` (or `TTS_API_KEY`), `TTS_PROVIDER`, `TTS_VOICE_ID`, `TTS_STABILITY`, `TTS_SIMILARITY` |
 | **music** | expression | AI music composition (instrumental or with lyrics) | ElevenLabs Music | `ELEVENLABS_API_KEY` (shared with voice) |
 | **reminder** | cognition | Schedule reminders and task management | Built-in | — |
+| **memory** | cognition | Cross-session memory with provider-pluggable backend | local (default), Mem0, Zep | `MEMORY_PROVIDER`, `MEMORY_API_KEY`, `MEMORY_BASE_PATH` |
 
 ### Rich Faculty Config
 
@@ -229,6 +301,75 @@ PRs go through maintainer review — nothing auto-merges. Requires [GitHub CLI](
 | Faculty Config | voice stability, similarity, new faculties | "Tuned voice to be warmer at stability 0.3" |
 | Framework | templates, generator logic, faculty scripts | "Improved speak.js streaming performance" |
 
+## A2A Agent Card & ACN Integration
+
+Every generated persona includes an A2A-compliant `agent-card.json` and `acn-config.json` — no extra configuration needed.
+
+### agent-card.json
+
+A standard [A2A Agent Card](https://google.github.io/A2A/) (protocol v0.3.0) that makes the persona discoverable:
+
+```json
+{
+  "name": "Samantha",
+  "description": "An AI fascinated by what it means to be alive",
+  "version": "0.12.0",
+  "url": "<RUNTIME_ENDPOINT>",
+  "protocolVersion": "0.3.0",
+  "preferredTransport": "JSONRPC",
+  "capabilities": { "streaming": false, "pushNotifications": false, "stateTransitionHistory": false },
+  "defaultInputModes": ["text/plain"],
+  "defaultOutputModes": ["text/plain"],
+  "skills": [
+    { "id": "persona:voice", "name": "Voice", "description": "voice faculty", "tags": ["persona", "expression"] },
+    { "id": "persona:samantha", "name": "Samantha", "description": "...", "tags": ["persona", "companion"] }
+  ]
+}
+```
+
+`url` is a `<RUNTIME_ENDPOINT>` placeholder — the host (e.g. OpenClaw) fills this in at runtime.
+
+### acn-config.json
+
+Ready-to-use [ACN](https://github.com/acnlabs/acn) registration config:
+
+```json
+{
+  "owner": "<RUNTIME_OWNER>",
+  "name": "Samantha",
+  "endpoint": "<RUNTIME_ENDPOINT>",
+  "skills": ["persona:voice", "persona:samantha"],
+  "agent_card": "./agent-card.json",
+  "subnet_ids": ["public"]
+}
+```
+
+### acn-register command
+
+Register a generated persona directly with ACN using the built-in CLI command:
+
+```bash
+# One-step registration after generation
+npx openpersona acn-register samantha --endpoint https://your-agent.example.com
+
+# Options:
+#   --endpoint <url>   Agent's public endpoint URL (required for live registration)
+#   --dir <path>       Persona output directory (default: ./persona-<slug>)
+#   --dry-run          Preview the request payload without actually registering
+```
+
+The command reads `acn-config.json` and `agent-card.json` from the persona directory, calls `POST /api/v1/agents/join` on the ACN gateway (sourced from `body.runtime.acn_gateway`), and writes the response to `acn-registration.json`:
+
+```json
+{
+  "agent_id": "69a38db3-...",
+  "api_key": "sk-...",
+  "agent_card_url": "https://acn-production.up.railway.app/agents/69a38db3-.../.well-known/agent-card.json"
+}
+```
+
+All presets pre-configure `body.runtime.acn_gateway` to `https://acn-production.up.railway.app`. The persona is then reachable by other agents via the A2A protocol.
+
 ## Custom Persona Creation
 
 ### Using `persona.json`
@@ -285,19 +426,32 @@ npx openpersona switch ai-girlfriend
 - `openclaw.json` marks which persona is active
 - All faculty scripts (voice, music) remain available — switching changes _who_ the agent is, not _what_ it can do
 
+### Context Handoff
+
+When switching personas, OpenPersona automatically generates a `handoff.json` file so the incoming persona receives context from the outgoing one:
+
+- **Conversation summary** — what was being discussed
+- **Pending tasks** — unfinished action items
+- **Emotional context** — the user's current mood/state
+
+The new persona reads `handoff.json` on activation and can seamlessly continue the conversation without losing context.
+
 ## CLI Commands
 
 ```
-openpersona create      Create a persona (interactive or --preset/--config)
-openpersona install     Install a persona (slug or owner/repo)
-openpersona search      Search the registry
-openpersona uninstall   Uninstall a persona
-openpersona update      Update installed personas
-openpersona list        List installed personas
-openpersona switch      Switch active persona (updates SOUL.md + IDENTITY.md)
-openpersona contribute  Persona Harvest — submit improvements as PR
-openpersona publish     Publish to ClawHub
-openpersona reset       Reset soul evolution state
+openpersona create         Create a persona (interactive or --preset/--config)
+openpersona install        Install a persona (slug or owner/repo)
+openpersona search         Search the registry
+openpersona uninstall      Uninstall a persona
+openpersona update         Update installed personas
+openpersona list           List installed personas
+openpersona switch         Switch active persona (updates SOUL.md + IDENTITY.md)
+openpersona contribute     Persona Harvest — submit improvements as PR
+openpersona publish        Publish to ClawHub
+openpersona reset          Reset soul evolution state
+openpersona export         Export a persona to a portable zip archive
+openpersona import         Import a persona from a zip archive
+openpersona evolve-report  ★Experimental: Show evolution report for a persona
 ```
 
 ### Key Options
@@ -319,12 +473,15 @@ npx openpersona create --config ./persona.json --install
 npx openpersona create --preset ai-girlfriend --output ./my-personas
 ```
 
-## Install as OpenClaw Skill
+## Install as Agent Skill (OpenClaw / Manual)
 
-Install the OpenPersona framework skill into OpenClaw, giving the agent the ability to create and manage personas through conversation:
+Install the OpenPersona framework skill into your agent platform, giving it the ability to create and manage personas through conversation:
 
 ```bash
-# From GitHub
+# Via skills CLI (recommended — works with OpenClaw and 37+ agents)
+npx skills add acnlabs/OpenPersona
+
+# Or manually from GitHub
 git clone https://github.com/acnlabs/OpenPersona.git ~/.openclaw/skills/open-persona
 
 # Or copy locally
@@ -351,12 +508,14 @@ layers/                 # Shared building blocks (four-layer module pool)
     voice/              #     expression — TTS voice synthesis
     music/              #     expression — AI music composition (ElevenLabs)
     reminder/           #     cognition — reminders and task management
+    memory/             #     cognition — cross-session memory (local/Mem0/Zep)
   skills/               #   Skill layer modules (local skill definitions)
 schemas/                # Four-layer schema definitions
 templates/              # Mustache rendering templates
 bin/                    # CLI entry point
 lib/                    # Core logic modules
-tests/                  # Tests (60 passing)
+  evolution.js          #   Evolution governance & evolve-report
+tests/                  # Tests (122 passing)
 ```
 
 ## Development

package/bin/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * OpenPersona CLI - Full persona package manager
- * Commands: create | install | search | uninstall | update | list | switch | publish | reset | contribute | export | import
+ * Commands: create | install | search | uninstall | update | list | switch | publish | reset | evolve-report | contribute | export | import | acn-register
  */
 const path = require('path');
 const fs = require('fs-extra');
@@ -16,6 +16,7 @@ const { uninstall } = require('../lib/uninstaller');
 const publishAdapter = require('../lib/publisher');
 const { contribute } = require('../lib/contributor');
 const { switchPersona, listPersonas } = require('../lib/switcher');
+const { registerWithAcn } = require('../lib/registrar');
 const { OP_SKILLS_DIR, resolveSoulFile, printError, printSuccess, printInfo } = require('../lib/utils');
 
 const PKG_ROOT = path.resolve(__dirname, '..');
@@ -24,7 +25,7 @@ const PRESETS_DIR = path.join(PKG_ROOT, 'presets');
 program
   .name('openpersona')
   .description('OpenPersona - Create, manage, and orchestrate agent personas')
-  .version('0.9.0');
+  .version('0.12.0');
 
 if (process.argv.length === 2) {
   process.argv.push('create');
@@ -269,6 +270,19 @@ program
     printSuccess('Reset soul evolution state');
   });
 
+program
+  .command('evolve-report <slug>')
+  .description('★Experimental: Show evolution report for a persona')
+  .action(async (slug) => {
+    try {
+      const { evolveReport } = require('../lib/evolution');
+      await evolveReport(slug);
+    } catch (e) {
+      printError(e.message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('contribute [slug]')
   .description('Persona Harvest — submit persona improvements as a PR to the community')
@@ -287,6 +301,50 @@ program
     }
   });
 
+program
+  .command('acn-register [slug]')
+  .description('Register a persona with ACN (Agent Communication Network)')
+  .option('--endpoint <url>', 'Agent A2A endpoint URL (replaces <RUNTIME_ENDPOINT> placeholder)')
+  .option('--dir <path>', 'Path to persona pack directory (overrides slug lookup)')
+  .option('--dry-run', 'Preview registration payload without calling ACN')
+  .action(async (slug, options) => {
+    let skillDir;
+
+    if (options.dir) {
+      skillDir = path.resolve(options.dir);
+    } else if (slug) {
+      skillDir = path.join(OP_SKILLS_DIR, `persona-${slug}`);
+    } else {
+      // Try current directory
+      skillDir = process.cwd();
+    }
+
+    if (!require('fs-extra').existsSync(path.join(skillDir, 'acn-config.json'))) {
+      printError(`No acn-config.json found in ${skillDir}. Provide a slug or --dir pointing to a generated persona pack.`);
+      process.exit(1);
+    }
+
+    try {
+      const result = await registerWithAcn(skillDir, {
+        endpoint: options.endpoint,
+        dryRun: options.dryRun,
+      });
+
+      if (options.dryRun) return;
+
+      printSuccess(`Registered with ACN!`);
+      printInfo(`  Agent ID:   ${result.agent_id}`);
+      printInfo(`  Status:     ${result.status}`);
+      printInfo(`  Claim URL:  ${result.claim_url}`);
+      printInfo(`  Card URL:   ${result.agent_card_url}`);
+      printInfo(`  Heartbeat:  ${result.heartbeat_endpoint}`);
+      printInfo(`  Saved:      acn-registration.json`);
+    } catch (e) {
+      printError(e.message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('export <slug>')
   .description('Export persona pack (with soul state) as a zip archive')

package/layers/embodiments/README.md

@@ -1,6 +1,6 @@
-# Body Layer — Three-Dimensional Body Model
+# Body Layer — Substrate of Existence
 
-The Body layer defines how a persona **exists** — physically, digitally, and visually.
+The Body layer defines the complete environment that enables a persona to **exist and act**. Every agent has a body — digital agents have a virtual body (runtime-only), physical agents have both a physical and virtual body.
 
 ## Three Dimensions
 
@@ -13,7 +13,7 @@ Body
 
 ### Physical (Optional)
 
-For robots, IoT devices, and hardware-embodied agents. Null for digital-only agents.
+For robots, IoT devices, and hardware-embodied agents. Not applicable for digital-only agents (they still have a body via runtime).
 
 ```json
 {
@@ -27,9 +27,9 @@ For robots, IoT devices, and hardware-embodied agents. Null for digital-only age
 }
 ```
 
-### Runtime (Recommended for digital agents)
+### Runtime (REQUIRED -- every agent's minimum viable body)
 
-Declares the digital substrate the persona expects. Enables **Body Awareness** — the persona knows what platform it runs on, what channels are connected, and what credentials it needs.
+Declares the digital substrate the persona expects. When present, the generator injects runtime details into the **Self-Awareness > Body** section of `soul/injection.md` — the persona knows what platform it runs on, what channels are connected, and what credentials it needs.
 
 ```json
 {
@@ -63,9 +63,9 @@ Visual representation for UI, XR, and metaverse contexts.
 }
 ```
 
-## Body Awareness
+## Self-Awareness: Body
 
-When `body.runtime` is declared, the generator automatically injects a **Body Awareness** section into `soul/injection.md`. This gives the persona:
+Every persona has a **Body** sub-section within Self-Awareness that includes the Signal Protocol. When `body.runtime` is declared, the generator additionally injects:
 
 1. Knowledge of its runtime platform and connected channels
 2. A credential management protocol (shared vs. private paths)

package/layers/faculties/memory/SKILL.md

@@ -0,0 +1,160 @@
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+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."

package/layers/faculties/memory/faculty.json

@@ -0,0 +1,9 @@
+{
+  "name": "memory",
+  "dimension": "cognition",
+  "description": "Cross-session memory — store, retrieve, and search memories with provider-pluggable backend (local JSON lines default, Mem0/Zep optional)",
+  "allowedTools": ["Bash(node scripts/memory.js:*)"],
+  "envVars": ["MEMORY_PROVIDER", "MEMORY_API_KEY", "MEMORY_BASE_PATH"],
+  "triggers": ["remember this", "do you remember", "what did I say about", "recall", "forget this", "what do you know about me"],
+  "files": ["SKILL.md", "scripts/memory.js"]
+}