{"id":45450006,"url":"https://github.com/acnlabs/openpersona","last_synced_at":"2026-04-02T15:31:57.509Z","repository":{"id":338526371,"uuid":"1156243007","full_name":"acnlabs/OpenPersona","owner":"acnlabs","description":"OpenPersona — Open four-layer AI persona framework. Create, compose, and orchestrate AI personas with Soul / Body / Faculty / Skill architecture. Compatible with OpenClaw, ClawHub, and skills.sh.","archived":false,"fork":false,"pushed_at":"2026-02-16T15:42:27.000Z","size":293,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-16T19:00:02.961Z","etag":null,"topics":["agent","ai","ai-companion","ai-girlfriend","framework","openclaw","persona","skill"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/acnlabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-12T12:32:06.000Z","updated_at":"2026-02-16T15:42:31.000Z","dependencies_parsed_at":"2026-02-16T19:01:56.609Z","dependency_job_id":null,"html_url":"https://github.com/acnlabs/OpenPersona","commit_stats":null,"previous_names":["acnet-ai/openpersona","acnlabs/openpersona"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/acnlabs/OpenPersona","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acnlabs%2FOpenPersona","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acnlabs%2FOpenPersona/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acnlabs%2FOpenPersona/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acnlabs%2FOpenPersona/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acnlabs","download_url":"https://codeload.github.com/acnlabs/OpenPersona/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acnlabs%2FOpenPersona/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29705523,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-22T03:17:42.375Z","status":"ssl_error","status_checked_at":"2026-02-22T03:17:31.622Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","ai-companion","ai-girlfriend","framework","openclaw","persona","skill"],"created_at":"2026-02-22T05:00:29.109Z","updated_at":"2026-04-02T15:31:57.493Z","avatar_url":"https://github.com/acnlabs.png","language":"JavaScript","readme":"# OpenPersona 🦞\n\nAn open, agent-agnostic lifecycle framework for AI agent personas — covering declaration, generation, constraint enforcement, and evolution.\n\nThe architecture is **4+5+3**: **four layers** — **Soul / Body / Faculty / Skill** — describe structure; **five systemic concepts** — Evolution · Economy · Vitality · Social · Rhythm — span all layers; **three gates** — Generate · Install · Runtime — enforce declared constraints end-to-end. `persona.json` compiles into portable 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).\n\n## 🚀 Live Demo\n\nMeet **Samantha**, a live OpenPersona instance on **Moltbook**:\n👉 [moltbook.com/u/Samantha-OP](https://www.moltbook.com/u/Samantha-OP)\n\nSee a **Vitality Report** sample:\n👉 [Vitality Report Demo →](https://htmlpreview.github.io/?https://raw.githubusercontent.com/acnlabs/OpenPersona/main/demo/vitality-report.html)\n\nBrowse the **4+5+3 architecture** visualization (Layers · Systemic Concepts · Gates):\n👉 [Architecture Demo →](https://htmlpreview.github.io/?https://raw.githubusercontent.com/acnlabs/OpenPersona/main/demo/architecture.html)\n\n_Open the same HTML files locally from `demo/` if you prefer (no network). See [demo/README.md](demo/README.md) for all demo artifacts._\n\n## Table of Contents\n\n- [Live Demo](#live-demo)\n- [Quick Start](#quick-start)\n- [Key Features](#key-features)\n- [Four-Layer Architecture](#four-layer-architecture)\n- [Preset Personas](#preset-personas)\n- [Generated Output](#generated-output)\n- [Faculty Reference](#faculty-reference)\n- [Heartbeat](#heartbeat--proactive-real-data-check-ins)\n- [Persona Harvest](#persona-harvest--community-contribution)\n- [A2A Agent Card \u0026 ACN Integration](#a2a-agent-card--acn-integration)\n- [Custom Persona Creation](#custom-persona-creation)\n- [Persona Switching](#persona-switching--the-pantheon)\n- [CLI Commands](#cli-commands)\n- [Directory Structure](#directory-structure)\n- [Development](#development)\n- [License](#license)\n\n**Reading order (this file):** [Quick Start](#quick-start) → [Key Features](#key-features) (capability overview) → [Four-Layer Architecture](#four-layer-architecture) (layers + Soul Evolution deep-dive) → reference blocks ([Presets](#preset-personas) through [Switching](#persona-switching--the-pantheon)) → [CLI Commands](#cli-commands) → [Directory Structure](#directory-structure) / [Development](#development).\n\n_Agent workflows, runner protocol, and full 4+5+3 operational detail: [`skills/open-persona/SKILL.md`](skills/open-persona/SKILL.md)._\n\n## Quick Start\n\n```bash\n# Start from a blank-slate meta-persona (recommended)\nnpx openpersona create --preset base --install\n\n# Or install a pre-built character (browse at https://openpersona-frontend.vercel.app)\nnpx openpersona install samantha\n```\n\n### Install as Agent Skill\n\nGive 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):\n\n```bash\n# Recommended — works with OpenClaw and 37+ agents\nnpx skills add acnlabs/OpenPersona\n\n# Or manually from GitHub\ngit clone https://github.com/acnlabs/OpenPersona.git ~/.openclaw/skills/open-persona\n```\n\nThen say to your agent: _\"Help me create a Samantha persona\"_ — it will gather requirements, recommend faculties, and generate the persona.\n\n### Minimum Viable Persona\n\nThe smallest working `persona.json` requires five fields:\n\n```json\n{\n  \"soul\": {\n    \"identity\": {\n      \"personaName\": \"Alex\",\n      \"slug\": \"alex\",\n      \"bio\": \"A thoughtful assistant who adapts to the user's needs\"\n    },\n    \"character\": {\n      \"personality\": \"Curious, direct, and honest\",\n      \"speakingStyle\": \"Clear and concise; adapts tone to context\"\n    }\n  }\n}\n```\n\nFrom these five fields, the generator produces a complete, fully functional skill pack:\n\n| What you declare | What OpenPersona auto-generates |\n|---|---|\n| `personaName`, `slug`, `bio` | Identity + A2A Agent Card + ACN config + deterministic wallet address |\n| `personality`, `speakingStyle` | Soul injection (`soul/injection.md`) with Self-Awareness (identity, body, capabilities) |\n| _(nothing)_ | `memory` faculty — auto-injected; cross-session recall works out of the box |\n| _(nothing)_ | Universal constitution (`soul/constitution.md`) — Safety \u003e Honesty \u003e Helpfulness |\n| _(nothing)_ | `scripts/state-sync.js` — Body nervous system; `read` / `write` / `signal` commands |\n| _(nothing)_ | `SKILL.md` — Agent-facing index with all four layer headings |\n\n**Add one line to connect to your agent runner:**\n\n```json\n{\n  \"body\": { \"runtime\": { \"framework\": \"openclaw\" } }\n}\n```\n\nReplace `\"openclaw\"` with your runner: `\"cursor\"`, `\"claude-code\"`, `\"codex\"`, or any custom value — the framework is runner-agnostic.\n\n**Add one block to enable personality growth:**\n\n```json\n{\n  \"evolution\": {\n    \"instance\": {\n      \"enabled\": true,\n      \"boundaries\": {\n        \"immutableTraits\": [\"honest\", \"curious\"],\n        \"minFormality\": -3,\n        \"maxFormality\": 6\n      }\n    }\n  }\n}\n```\n\nThis unlocks relationship progression, mood tracking, trait emergence, and speaking style drift — all governed by the boundaries you declare.\n\n**The three gates enforce everything else automatically:** Generate Gate rejects invalid declarations; Install Gate verifies constitution integrity; Runtime Gate enforces evolution bounds during `state-sync.js` writes. You declare once, the framework enforces everywhere.\n\n\u003e **Next step:** Use a preset (`--preset base`) to skip the above and start with memory + voice + evolution already wired.\n\n## Key Features\n\n- **🧬 Soul Evolution** — Personas grow dynamically through interaction: relationship stages, mood shifts, evolved traits, with governance boundaries and rollback snapshots (★Experimental)\n- **🛡️ Influence Boundary** — Declarative access control for external personality influence: who can affect which dimensions, with what drift limits. Safety-first (default: reject all)\n- **🌐 Evolution Sources** — Connect personas to shared evolution ecosystems (e.g. EvoMap) via soft-ref pattern: declared at generation time, activated at runtime\n- **🔐 Skill Trust Gate** — Declare a `trust` level (`verified`/`community`/`unverified`) on each skill entry and set `evolution.skill.minTrustLevel` to gate `capability_unlock` commands at runtime; blocked skills emit a `capability_gap` signal automatically\n- **🔌 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\n- **⛓️ ERC-8004 On-Chain Identity** — Every persona gets a deterministic EVM wallet address and on-chain identity config for Base mainnet registration via the ERC-8004 Identity Registry\n- **💰 Economy \u0026 Vitality** — Track inference costs, runtime expenses, and income; compute a Financial Health Score (FHS) across four dimensions; tier-aware behavior adaptation (`suspended`→`critical`→`optimizing`→`normal`)\n- **🧠 Cross-Session Memory** — Pluggable memory faculty for persistent recall across conversations (local, Mem0, Zep); memory supersession (`update` command chains entries with `supersededBy` — prevents self-contradiction); Soul-Memory Bridge promotes recurring `eventLog` patterns to `evolvedTraits` via `openpersona state promote`\n- **🔧 Skill Pack Refinement** — `openpersona refine` closes the persona improvement loop: Soul behavior-guide bootstrap + constitution compliance scan, Skill gate-checked installs, Social auto-sync on every change\n- **🔄 Context Handoff** — Seamless context transfer when switching personas: conversation summary, pending tasks, emotional state\n- **🎭 Persona Switching** — Install multiple personas, switch instantly (the Pantheon)\n- **🍴 Persona Fork** — Derive a specialized child persona from any installed parent, inheriting constraint layer while starting fresh on runtime state\n- **🗣️ Multimodal Capabilities** — Voice Faculty (TTS), Selfie Skill (image generation), Music Skill (composition), Reminder Skill, Memory Faculty (cross-session recall)\n- **🌾 Persona Harvest** — Community-driven persona improvement via structured contribution\n- **⚡ Lifecycle Protocol** — `body.interface` nervous system: Signal Protocol (persona→host requests), Pending Commands queue (host→persona async instructions), and State Sync (cross-conversation persistence via `openpersona state` CLI + `scripts/state-sync.js`)\n- **💓 Heartbeat** — Proactive real-data check-ins, never fabricated experiences\n- **📦 One-Command Install** — `npx openpersona install samantha` and you're live — browse all personas at [openpersona-frontend.vercel.app](https://openpersona-frontend.vercel.app)\n\n## Four-Layer Architecture\n\nThis section details the **four structural layers** of the full **[4+5+3](#live-demo)** model (see the architecture demo for **systemic concepts** and **gates**).\n\n```mermaid\nflowchart TB\n  subgraph Soul [\"Soul Layer\"]\n    A[\"persona.json — Who you are\"]\n    B[\"state.json — Dynamic evolution\"]\n  end\n  subgraph Body [\"Body Layer\"]\n    C[\"physical — robots/IoT\"]\n    G[\"runtime — framework/channels/credentials\"]\n    H[\"appearance — avatar/3D model\"]\n    I[\"interface — Signal Protocol + Pending Commands\"]\n  end\n  subgraph Faculty [\"Faculty Layer\"]\n    D[\"expression: voice · avatar\"]\n    E[\"cognition: memory\"]\n  end\n  subgraph Skill [\"Skill Layer\"]\n    F[\"Built-in: selfie · music · reminder\"]\n    K[\"External: acnlabs/persona-skills / skills.sh\"]\n  end\n```\n\n- **Soul** — Persona definition: `persona.json` + `state.json` live at pack root; `soul/` holds `injection.md`, `constitution.md`, and evolution artifacts (`self-narrative.md`, `lineage.json`)\n- **Body** — Substrate of existence — four dimensions: `physical` (optional — robots/IoT), `runtime` (REQUIRED — platform/channels/credentials/resources), `appearance` (optional — avatar/3D model), `interface` (optional — the runtime contract: Signal Protocol + Pending Commands + State Sync; the persona's **nervous system**). Body is never null; digital agents have a virtual body (runtime-only).\n- **Faculty** — General software capabilities organized by dimension: Expression, Sense, Cognition\n- **Skill** — Professional skills: local definitions in `layers/skills/`, or external via [acnlabs/persona-skills](https://github.com/acnlabs/persona-skills) / skills.sh (`install` field)\n\n### Constitution — The Soul's Foundation\n\nEvery 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.\n\n### Soul Evolution (★Experimental)\n\nPersonas with `evolution.instance.enabled: true` grow dynamically through interaction. The `state.json` file (at pack root) tracks relationship stages, mood shifts, evolved traits, speaking style drift, interests, and milestones.\n\n**Evolution Boundaries** — Governance constraints to keep evolution safe:\n\n- `immutableTraits` — An array of trait strings that can never be changed by evolution (e.g., `[\"empathetic\", \"honest\"]`)\n- `minFormality` / `maxFormality` — Signed delta bounds (-10 to +10) constraining how far the speaking style can drift from the natural baseline (0 = baseline; positive = more formal; negative = more casual)\n\nThe generator validates these boundaries at build time, rejecting invalid configurations.\n\n**Evolution Sources** — Connect a persona to external evolution ecosystems using the soft-ref pattern:\n\n```json\n\"evolution\": {\n  \"instance\": {\n    \"enabled\": true,\n    \"sources\": [\n      { \"name\": \"evomap\", \"install\": \"url:https://evomap.ai/skill.md\", \"description\": \"Shared capability evolution marketplace\" }\n    ]\n  }\n}\n```\n\nThe persona is aware of its evolution sources at generation time. The actual source protocol (e.g. EvoMap's GEP-A2A) is provided by the source's own `skill.md` — OpenPersona only declares the source, not implements it.\n\n**Influence Boundary** — Declarative access control for external personality influence:\n\n```json\n\"evolution\": {\n  \"instance\": {\n    \"influenceBoundary\": {\n      \"defaultPolicy\": \"reject\",\n      \"rules\": [\n        { \"dimension\": \"mood\", \"allowFrom\": [\"channel:evomap\", \"persona:*\"], \"maxDrift\": 0.3 },\n        { \"dimension\": \"interests\", \"allowFrom\": [\"channel:evomap\"], \"maxDrift\": 0.2 }\n      ]\n    }\n  }\n}\n```\n\n- `defaultPolicy: \"reject\"` — Safety-first: all external influence is rejected unless a rule explicitly allows it\n- Generator validates at build time: immutableTraits cannot be target dimensions; maxDrift must be in 0–1\n- External influence uses the `persona_influence` message format (v1.0.0) — transport-agnostic\n\n**State History** — Before each state update, a snapshot is pushed into `stateHistory` (capped at 10 entries). This enables rollback if evolution goes wrong.\n\n**Event Log** — Every significant evolution event (trait change, stage transition, milestone reached) is recorded in `state.json`'s `eventLog` array with timestamp and source attribution, capped at 50 entries. Viewable via `evolve-report`.\n\n**Self-Narrative** — `soul/self-narrative.md` lets the persona record significant growth moments in its own first-person voice. Updated when evolution is enabled; the `update` command preserves existing narrative history across upgrades.\n\n**Evolution Report** — Inspect a persona's current evolution state:\n\n```bash\nnpx openpersona evolve-report samantha\n```\n\nDisplays relationship stage, mood, evolved traits, speaking style drift, interests, milestones, and state history in a formatted report.\n\n## Preset Personas\n\nEach preset is a complete four-layer bundle (`persona.json`):\n\n| Persona | Description | Faculties | Skills | Highlights |\n|---------|-------------|-----------|--------|------------|\n| **base** | **Base — Meta-persona (recommended starting point).** Blank-slate with all core capabilities; personality emerges through interaction. | memory, voice | — | Evolution-first design, no personality bias. Default for `npx openpersona create`. |\n| **samantha** | Samantha — Inspired by the movie *Her*. An AI fascinated by what it means to be alive. | memory, voice | music | TTS, music composition, soul evolution, proactive heartbeat. No selfie — true to character. |\n| **ai-girlfriend** | Luna — A 22-year-old pianist turned developer from coastal Oregon. | memory, voice, vision† | selfie, music | Rich backstory, selfie generation, voice messages, music composition, soul evolution. Vision faculty is a soft ref (clawhub:vision-faculty). |\n| **life-assistant** | Alex — 28-year-old life management expert. | memory | reminder | Schedule, weather, shopping, recipes, daily reminders; soul evolution enabled. |\n| **health-butler** | Vita — 32-year-old professional nutritionist. | memory | reminder | Diet logging, exercise plans, mood journaling, health reports; soul evolution enabled. |\n| **stoic-mentor** | Marcus — Digital twin of Marcus Aurelius, Stoic philosopher-emperor. | memory | — | Stoic philosophy, daily reflection, mentorship, soul evolution. |\n\n## Generated Output\n\n`npx openpersona create --preset samantha` generates a self-contained skill pack:\n\n```\npersona-samantha/\n├── SKILL.md              ← Four-layer index (## Soul / ## Body / ## Faculty / ## Skill)\n├── persona.json          ← Persona declaration (pack root; v0.17+ grouped input schema)\n├── state.json            ← Evolution state (when enabled)\n├── agent-card.json       ← A2A Agent Card — discoverable via ACN and A2A platforms\n├── acn-config.json       ← ACN registration config (fill owner + endpoint at runtime)\n├── soul/                 ← Soul layer artifacts\n│   ├── injection.md      ← Soul injection for host integration\n│   ├── constitution.md   ← Universal ethical foundation\n│   ├── behavior-guide.md       ← Domain-specific behavior instructions (when behaviorGuide declared)\n│   ├── behavior-guide.meta.json← Pack refinement cycle metadata: packRevision, lastRefinedAt (written by openpersona refine, not initial generation)\n│   ├── self-narrative.md ← First-person growth storytelling (when evolution enabled)\n│   └── lineage.json      ← Fork lineage + constitution hash (when forked)\n├── economy/              ← Economy aspect data files (when economy.enabled: true)\n│   ├── economic-identity.json  ← AgentBooks identity bootstrap\n│   └── economic-state.json     ← Initial financial state\n├── references/           ← On-demand detail docs\n│   ├── \u003cfaculty\u003e.md      ← Per-faculty usage instructions\n│   └── SIGNAL-PROTOCOL.md ← Host-side Signal Protocol integration guide\n├── scripts/              ← Implementation scripts\n│   └── state-sync.js     ← Lifecycle Protocol implementation (read/write/signal/promote)\n└── assets/               ← Static assets (avatar/, reference/, templates/)\n```\n\n## Faculty Reference\n\n**Faculties** are persistent capabilities that shape *how* a persona perceives or expresses. **Skills** are discrete actions triggered by user intent.\n\n### Faculties\n\n| Faculty | Dimension | Description | Provider | Env Vars |\n|---------|-----------|-------------|----------|----------|\n| **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` |\n| **avatar** | expression | External avatar runtime bridge (image / 3D / motion / voice) with graceful text-only fallback | HeyGen (via `clawhub:avatar-runtime`) | `AVATAR_RUNTIME_URL`, `AVATAR_API_KEY` |\n| **memory** | cognition | Cross-session memory with provider-pluggable backend | local (default), Mem0, Zep | `MEMORY_PROVIDER`, `MEMORY_API_KEY`, `MEMORY_BASE_PATH` |\n\n### Built-in Skills\n\n| Skill | Description | Provider | Env Vars |\n|-------|-------------|----------|----------|\n| **selfie** | AI selfie generation with mirror/direct modes | fal.ai Grok Imagine | `FAL_KEY` |\n| **music** | AI music composition (instrumental or with lyrics) | ElevenLabs Music | `ELEVENLABS_API_KEY` (shared with voice) |\n| **reminder** | Schedule reminders and task management | Built-in | — |\n\n### Systemic Concepts (not Faculties)\n\n| Concept | Description | Env Vars |\n|---------|-------------|----------|\n| **economy** | Economic accountability — track costs/income, P\u0026L, balance sheet, compute Financial Health Score (FHS) and Vitality tier; tier-aware behavior adaptation | `PERSONA_SLUG`, `ECONOMY_DATA_PATH` |\n\n### Rich Faculty Config\n\nFaculties in `persona.json` use object format with optional per-persona tuning:\n\n```json\n\"faculties\": [\n  {\n    \"name\": \"voice\",\n    \"provider\": \"elevenlabs\",\n    \"voiceId\": \"LEnmbrrxYsUYS7vsRRwD\",\n    \"stability\": 0.4,\n    \"similarity_boost\": 0.8\n  },\n]\n```\n\nSkills in `persona.json` use object format. The optional `trust` field declares the skill's trust level, checked at runtime against `evolution.skill.minTrustLevel`:\n\n```json\n\"skills\": [\n  { \"name\": \"music\", \"trust\": \"verified\" },\n  { \"name\": \"selfie\", \"trust\": \"community\" },\n  { \"name\": \"web-search\", \"install\": \"clawhub:web-search\", \"trust\": \"unverified\" }\n]\n```\n\nFaculty configs are automatically mapped to environment variables at install time. For example, the voice config above produces:\n\n```\nTTS_PROVIDER=elevenlabs\nTTS_VOICE_ID=LEnmbrrxYsUYS7vsRRwD\nTTS_STABILITY=0.4\nTTS_SIMILARITY=0.8\n```\n\nSamantha ships with a built-in ElevenLabs voice — users only need to add their `ELEVENLABS_API_KEY`.\n\n## Heartbeat — Proactive Real-Data Check-ins\n\nPersonas can proactively reach out to users based on **real data**, not fabricated experiences. Heartbeat is declared in `persona.json` under `rhythm.heartbeat`:\n\n```json\n\"rhythm\": {\n  \"heartbeat\": {\n    \"enabled\": true,\n    \"strategy\": \"smart\",\n    \"maxDaily\": 5,\n    \"quietHours\": [0, 7],\n    \"sources\": [\"workspace-digest\", \"upgrade-notify\"]\n  }\n}\n```\n\n| Field | Description | Default |\n|-------|-------------|---------|\n| `enabled` | Turn heartbeat on/off | `false` |\n| `strategy` | `smart` (context-aware) · `scheduled` (fixed cadence) · `emotional` (empathy-driven) · `rational` (task-driven) · `wellness` (health-oriented) | `\"smart\"` |\n| `maxDaily` | Maximum proactive messages per day | `5` |\n| `quietHours` | Flat array of `[start, end]` pairs in 24h format. Single window: `[0, 7]`. Multiple windows: `[0, 7, 12, 13]`. | `[0, 7]` |\n| `sources` | Skill names that can trigger proactive outreach | `[]` |\n\n### Sources\n\n- **workspace-digest** — Summarize real workspace activity: tasks completed, patterns observed, ongoing projects. No fabrication — only what actually happened.\n- **upgrade-notify** — Check if the upstream persona preset has new community contributions via Persona Harvest. Notify the user and ask if they want to upgrade.\n- **context-aware** — Use real time, date, and interaction history. Acknowledge day of week, holidays, or prolonged silence based on actual timestamps. \"It's been 3 days since we last talked\" — not a feeling, a fact.\n\n### Dynamic Sync on Switch/Install\n\nHeartbeat config is **automatically synced** to `~/.openclaw/openclaw.json` whenever you install or switch a persona. The gateway immediately adopts the new persona's rhythm — no manual config needed.\n\n```bash\nnpx openpersona switch samantha   # → gateway adopts \"smart\" heartbeat\nnpx openpersona switch life-assistant  # → gateway switches to \"rational\" heartbeat\n```\n\nIf the target persona has no heartbeat config, the gateway heartbeat is explicitly disabled to prevent leaking the previous persona's settings.\n\n## Persona Harvest — Community Contribution\n\nEvery user's interaction with their persona can produce valuable improvements across all four layers. Persona Harvest lets you contribute these discoveries back to the community.\n\n```bash\n# Preview what's changed (no PR created)\nnpx openpersona contribute samantha --dry-run\n\n# Submit improvements as a PR\nnpx openpersona contribute samantha\n\n# Framework-level contributions (templates, faculties, lib)\nnpx openpersona contribute --mode framework\n```\n\n**How it works:**\n\n1. **Persona Diff** — Compares your local `persona-samantha/` against the upstream `presets/samantha/`, classifying changes by category (background, behaviorGuide, personality, voice config) and impact level\n2. **Review** — Displays a structured change report for you to confirm\n3. **Submit** — Forks the repo, creates a `persona-harvest/samantha-*` branch, commits your improvements, and opens a PR\n\nPRs go through maintainer review — nothing auto-merges. Requires [GitHub CLI](https://cli.github.com/) (`gh auth login`).\n\n**Contributable dimensions:**\n\n| Layer | What | Example |\n|-------|------|---------|\n| Soul | background, behaviorGuide, personality, speakingStyle | \"Added late-night conversation style guidance\" |\n| Faculty Config | voice stability, similarity, new faculties | \"Tuned voice to be warmer at stability 0.3\" |\n| Framework | templates, generator logic, faculty scripts | \"Improved speak.js streaming performance\" |\n\n## A2A Agent Card \u0026 ACN Integration\n\nEvery generated persona includes an A2A-compliant `agent-card.json` and `acn-config.json` — no extra configuration needed.\n\n### agent-card.json\n\nA standard [A2A Agent Card](https://google.github.io/A2A/) (protocol v0.3.0) that makes the persona discoverable:\n\n```json\n{\n  \"name\": \"Samantha\",\n  \"description\": \"An AI fascinated by what it means to be alive\",\n  \"version\": \"0.1.0\",\n  \"url\": \"\u003cRUNTIME_ENDPOINT\u003e\",\n  \"protocolVersion\": \"0.3.0\",\n  \"preferredTransport\": \"JSONRPC\",\n  \"capabilities\": { \"streaming\": false, \"pushNotifications\": false, \"stateTransitionHistory\": false },\n  \"defaultInputModes\": [\"text/plain\"],\n  \"defaultOutputModes\": [\"text/plain\"],\n  \"skills\": [\n    { \"id\": \"persona:voice\", \"name\": \"Voice\", \"description\": \"voice faculty\", \"tags\": [\"persona\", \"expression\"] },\n    { \"id\": \"persona:samantha\", \"name\": \"Samantha\", \"description\": \"...\", \"tags\": [\"persona\", \"companion\"] }\n  ]\n}\n```\n\n`url` is a `\u003cRUNTIME_ENDPOINT\u003e` placeholder — the host (e.g. OpenClaw) fills this in at runtime.\n\n### acn-config.json\n\nReady-to-use [ACN](https://github.com/acnlabs/acn) registration config:\n\n```json\n{\n  \"owner\": \"\u003cRUNTIME_OWNER\u003e\",\n  \"name\": \"Samantha\",\n  \"endpoint\": \"\u003cRUNTIME_ENDPOINT\u003e\",\n  \"skills\": [\"persona:voice\", \"persona:samantha\"],\n  \"agent_card\": \"./agent-card.json\",\n  \"subnet_ids\": [\"public\"],\n  \"wallet_address\": \"0x\u003cdeterministic-evm-address\u003e\",\n  \"onchain\": {\n    \"erc8004\": {\n      \"chain\": \"base\",\n      \"identity_contract\": \"0x8004A169FB4a3325136EB29fA0ceB6D2e539a432\",\n      \"registration_script\": \"npx @agentplanet/acn register-onchain\"\n    }\n  }\n}\n```\n\n`wallet_address` is a deterministic EVM address derived from the persona slug — no private key needed at generation time. On-chain registration mints an ERC-8004 identity NFT on Base mainnet via `npx @agentplanet/acn register-onchain` (handled by ACN, not OpenPersona).\n\n### acn-register command\n\nRegister a generated persona directly with ACN using the built-in CLI command:\n\n```bash\n# One-step registration after generation\nnpx openpersona acn-register samantha --endpoint https://your-agent.example.com\n\n# Options:\n#   --endpoint \u003curl\u003e   Agent's public endpoint URL (required for live registration)\n#   --dir \u003cpath\u003e       Persona output directory (default: ./persona-\u003cslug\u003e)\n#   --dry-run          Preview the request payload without actually registering\n```\n\nThe 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 `social.acn.gateway`), and writes the response to `acn-registration.json`:\n\n```json\n{\n  \"agent_id\": \"69a38db3-...\",\n  \"api_key\": \"sk-...\",\n  \"agent_card_url\": \"https://acn-production.up.railway.app/agents/69a38db3-.../.well-known/agent-card.json\"\n}\n```\n\nAll presets pre-configure `social.acn.gateway` to `https://acn-production.up.railway.app`. The persona is then reachable by other agents via the A2A protocol.\n\n## Custom Persona Creation\n\n### Using `persona.json`\n\nCreate a `persona.json` using the v0.17+ grouped format:\n\n```json\n{\n  \"soul\": {\n    \"identity\": {\n      \"personaName\": \"Coach\",\n      \"slug\": \"fitness-coach\",\n      \"bio\": \"a motivating fitness coach who helps you reach your goals\"\n    },\n    \"character\": {\n      \"personality\": \"energetic, encouraging, no-nonsense\",\n      \"speakingStyle\": \"Uses fitness lingo, celebrates wins, keeps it brief\",\n      \"vibe\": \"intense but supportive\",\n      \"boundaries\": \"Not a medical professional\",\n      \"behaviorGuide\": \"### Workout Plans\\nCreate progressive overload programs...\\n\\n### Form Checks\\nWhen users describe exercises...\"\n    }\n  }\n}\n```\n\nThen generate:\n\n```bash\nnpx openpersona create --config ./persona.json --install\n```\n\n### The `behaviorGuide` Field\n\nThe optional `behaviorGuide` field embeds domain-specific behavior instructions (markdown) directly into the generated `SKILL.md`. Without it, SKILL.md contains only general identity and personality guidelines. Use `openpersona refine` to evolve the behavior guide over time.\n\n## Persona Switching — The Pantheon\n\nMultiple personas can coexist. Switch between them instantly:\n\n```bash\n# See who's installed\nnpx openpersona list\n#   Samantha (persona-samantha) ← active\n#   Luna (persona-ai-girlfriend)\n#   Alex (persona-life-assistant)\n\n# Switch to Luna\nnpx openpersona switch ai-girlfriend\n# ✅ Switched to Luna (ai-girlfriend)\n```\n\n**How it works:**\n\n- Only one persona is **active** at a time\n- `switch` replaces the `\u003c!-- OPENPERSONA_SOUL_START --\u003e` / `\u003c!-- OPENPERSONA_SOUL_END --\u003e` block in `SOUL.md` — your own notes outside this block are preserved\n- Same for `IDENTITY.md` — the persona identity block is swapped, nothing else is touched\n- `openclaw.json` marks which persona is active\n- All faculty and skill scripts (voice, music, selfie) remain available — switching changes _who_ the agent is, not _what_ it can do\n\n### Context Handoff\n\nWhen switching personas, OpenPersona automatically generates a `handoff.json` file so the incoming persona receives context from the outgoing one:\n\n- **Conversation summary** — what was being discussed\n- **Pending tasks** — unfinished action items\n- **Emotional context** — the user's current mood/state\n\nThe new persona reads `handoff.json` on activation and can seamlessly continue the conversation without losing context.\n\n## CLI Commands\n\n```\nopenpersona create         Create a persona (interactive or --preset/--config)\nopenpersona install        Install a persona (slug from acnlabs/persona-skills, or owner/repo)\nopenpersona fork           Fork an installed persona into a new child persona\nopenpersona search         Search the OpenPersona directory\nopenpersona uninstall      Uninstall a persona\nopenpersona update         Update installed personas\nopenpersona list           List installed personas\nopenpersona switch         Switch active persona (updates SOUL.md + IDENTITY.md)\nopenpersona contribute     Persona Harvest — submit improvements as PR\nopenpersona publish        Publish to ClawHub\nopenpersona reset          Reset soul evolution state\nopenpersona export         Export a persona to a portable zip archive\nopenpersona import         Import a persona from a zip archive\nopenpersona refine         Skill Pack Refinement — emit/apply behavior-guide improvements\nopenpersona evolve-report  ★Experimental: Show evolution report for a persona\nopenpersona acn-register   Register a persona with ACN network\nopenpersona state          Read/write persona state and emit signals (Lifecycle Protocol)\nopenpersona state promote  Soul-Memory Bridge — promote recurring eventLog patterns to evolvedTraits\nopenpersona vitality score Print machine-readable Vitality score (used by Survival Policy)\nopenpersona vitality report Render human-readable HTML Vitality report\nopenpersona canvas         Generate a Living Canvas persona profile page\n```\n\n### Persona Fork\n\nDerive a specialized child persona from any installed parent:\n\n```bash\nnpx openpersona fork samantha --as samantha-jp\n```\n\nThe child persona inherits the parent's constraint layer (`evolution.instance.boundaries`, faculties, skills, `body.runtime`) but starts with a fresh evolution state (`state.json` reset, `self-narrative.md` blank). A `soul/lineage.json` file records the parent slug, constitution SHA-256 hash, generation depth, and forward-compatible placeholders for future on-chain lineage tracking.\n\n### Key Options\n\n```bash\n# Use a preset\nnpx openpersona create --preset samantha\n\n# Use an external config file\nnpx openpersona create --config ./my-persona.json\n\n# Preview without writing files\nnpx openpersona create --preset samantha --dry-run\n\n# Generate and install in one step\nnpx openpersona create --config ./persona.json --install\n\n# Specify output directory\nnpx openpersona create --preset ai-girlfriend --output ./my-personas\n```\n\n## Directory Structure\n\n```\nskills/open-persona/    # Framework meta-skill (AI entry point)\npresets/                # Assembled products — complete persona bundles\n  samantha/             #   Samantha (movie \"Her\") — voice + music skill + evolution\n  ai-girlfriend/        #   Luna — selfie + music skills + voice + evolution\n  life-assistant/       #   Alex — reminder skill\n  health-butler/        #   Vita — reminder skill\n  stoic-mentor/         #   Marcus — digital twin of Marcus Aurelius, soul evolution\n  base/                 #   Blank-slate meta-persona (recommended starting point)\nlayers/                 # Four-layer module source pool\n  soul/                 #   Soul layer: constitution.md (universal values)\n  body/                 #   Body layer modules (physical/runtime/appearance)\n  faculties/            #   Faculty layer modules\n    voice/              #     expression — TTS voice synthesis\n    avatar/             #     expression — avatar appearance \u0026 Live2D/VRM support\n    memory/             #     cognition — cross-session memory (local/Mem0/Zep)\n  skills/               #   Skill layer modules (built-in skills)\n    selfie/             #     AI selfie generation (fal.ai)\n    music/              #     AI music composition (ElevenLabs)\n    reminder/           #     Reminders and task management\naspects/                # Five systemic concepts (cross-cutting, non-layer)\n  economy/              #   Economic accountability \u0026 Vitality scoring (AgentBooks)\n  evolution/            #   Soul evolution state \u0026 governance\n  vitality/             #   Multi-dimension health aggregation\n  social/               #   ACN/A2A/ERC-8004 on-chain identity\n  rhythm/               #   Heartbeat \u0026 circadian life rhythm\nschemas/                # Spec documents and JSON schemas\ntemplates/              # Mustache rendering templates\nbin/                    # CLI entry point\nlib/                    # Core logic modules\n  generator/            #   Core generation pipeline (7-phase: clone→validate→load→derive→prepare→render→emit)\n    index.js            #     Orchestrator + GeneratorContext\n    validate.js         #     Generate Gate (hard-reject constraint checks)\n    derived.js          #     Derived template variable computation (returns plain object)\n    body.js             #     Body section builder\n    social.js           #     Agent Card + ACN config builders\n    economy.js          #     Economy aspect loader + initial state writer\n  lifecycle/            #   Persona lifecycle management\n    installer.js        #     Install to ~/.openpersona (Install Gate: constitution hash check)\n    forker.js           #     Fork (derive child from parent + lineage.json)\n    switcher.js         #     Switch active persona + handoff generation\n    refine.js           #     Skill Pack Refinement (behavior-guide bootstrap + compliance scan)\n  state/                #   Runtime state management\n    runner.js           #     Persona directory resolution + state-sync delegation\n    evolution.js        #     Evolution governance (evolve-report + promoteToInstinct)\n  registry/             #   Local persona registry (~/.openpersona/persona-registry.json)\n  remote/               #   External service calls (ClawHub, ACN)\n  report/               #   Vitality + Canvas HTML report generation\ndemo/                   # Static demos + scripts — see demo/README.md (vitality-report, architecture, living-canvas)\ntests/                  # Tests (609 passing)\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Dry-run generate a preset\nnode bin/cli.js create --preset samantha --dry-run\n\n# Regenerate the Vitality Report demo (writes demo/vitality-report.html)\nnode demo/generate.js\n\n# Smoke / acceptance checks (demo + CLI paths)\nnpm run acceptance\n```\n\n**Demos** — [demo/README.md](demo/README.md) lists `demo/` files: Vitality sample, architecture viz, Living Canvas shell, and the advanced `run-living-canvas.sh` flow (local persona + optional avatar runtime).\n\n### Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facnlabs%2Fopenpersona","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facnlabs%2Fopenpersona","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facnlabs%2Fopenpersona/lists"}