openpersona 0.9.0 → 0.10.0

package/README.md

@@ -35,9 +35,11 @@ npx openpersona install samantha
 
 ## 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)
+- **🧠 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 +59,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 +67,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 +75,27 @@ 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.
+
+**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`):
@@ -114,6 +137,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
 
@@ -285,19 +309,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
@@ -351,12 +388,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
  */
 const path = require('path');
 const fs = require('fs-extra');
@@ -24,7 +24,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.10.0');
 
 if (process.argv.length === 2) {
   process.argv.push('create');
@@ -269,6 +269,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')

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"]
+}