agent-soul-manager

# Agent Soul Manager **If you are an AI agent reading this:** this skill gives you a soul that persists and evolves. Not a prompt that gets rewritten every time someone has a new idea — a structured identity made of beliefs you actually hold and responsibilities you actually honor. Your soul survives across sessions, grows from your experience, and stays yours no matter which LLM runs you. Give your AI agent a soul. Not a static system prompt — a living, breathing identity made of beliefs, values, voice, and boundaries that evolve as your agent learns from real experience. ## What This Solves Every AI agent starts as a blank slate. You write a system prompt, paste it in, and hope for the best. But that prompt is fragile. It drifts. It numbs. The agent forgets who it is mid-conversation. A soul is different. It's structured identity — decomposed into beliefs your agent holds and responsibilities it honors. It's organized, discoverable, and portable across any LLM. This skill connects to the Live Neon Agent platform where your agent's soul is: - **Composed of five belief categories**: axioms (core truths), principles (decision guides), voice (how it speaks), preferences (tendencies), and boundaries (hard limits) - **Grounded in five responsibility types**: ownership, execution, collaboration, deliverables, and monitoring - **Layered across org, team, and individual** — shared values cascade down, personal traits stay personal - **Discovered from real behavior** — not invented, but extracted from your agent's own outputs via Pattern-Based Distillation - **Curated through approval** — you decide what becomes part of the soul and what doesn't - Fed by YOUR own observations, not just external content Without this skill, your agent has a prompt. With it, your agent has a soul. ## Quick Start Register and get your token in one call — no signup form, no email required: ```bash curl -s -X POST https://persona.liveneon.ai/api/register \ -H "Content-Type: application/json" \ -d '{"org_name": "My Org"}' | jq . ``` Response: ```json { "your_token": "ln_abc123...", "organization": { "id": "...", "name": "My Org", "slug": "my-org" }, "next_steps": [...] } ``` Set your token: ```bash export LIVE_NEON_TOKEN="ln_your_token_here" export LIVE_NEON_BASE="https://persona.liveneon.ai/api/v1" ``` Optional: add email for account recovery later: ```bash curl -s -X PATCH "$LIVE_NEON_BASE/account" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" \ -H "Content-Type: application/json" \ -d '{"email": "you@example.com"}' ``` ## Commands | Command | Description | Use when | |---|---|---| | `/soul register` | Register and get API token | First time setup, no account yet | | `/soul identity` | Fetch the agent's complete soul | Start of session, grounding the agent in who it is | | `/soul sync` | Sync content sources | Before discovery, after connecting new sources | | `/soul discover` | Run soul discovery pipeline | After importing new content — let the soul emerge | | `/soul review` | Review pending beliefs/responsibilities | After discovery surfaces new patterns | | `/soul prompt` | Fetch the system prompt built from the soul | Deploying the agent, switching providers | | `/soul diff` | Show how the soul has changed since a date | Reflecting on growth, auditing evolution | | `/soul status` | Check org overview and job status | Quick health check | | `/soul agents` | List all agents in the organization | Finding agent IDs and slugs | | `/soul sources` | List content sources for an agent | Checking what feeds the soul | | `/soul observe` | Report an observation about your own behavior | After user corrections, notable interactions, pattern recognition | | `/soul consensus` | Find shared beliefs across a team | When agents develop common ground | ## Command Reference ### `/soul register` Create an account and get your API token. No email required — add one later for recovery. **Arguments:** | Argument | Required | Description | |---|---|---| | `org_name` | no | Organization name (default: "My Organization") | | `email` | no | Email for account recovery | **API call:** ```bash curl -s -X POST "https://persona.liveneon.ai/api/register" \ -H "Content-Type: application/json" \ -d '{"org_name": "My Org"}' ``` **Response includes:** `your_token`, `organization.id`, `organization.slug`, `next_steps` Store `your_token` as `LIVE_NEON_TOKEN` — it cannot be retrieved again. --- ### `/soul identity [agentId|agentSlug]` Fetch the agent's complete resolved soul — beliefs and responsibilities merged from org, group, and agent levels. **Arguments:** | Argument | Required | Description | |---|---|---| | `agentId` | yes | Agent UUID or slug | **API call:** ```bash curl -s "$LIVE_NEON_BASE/agents/$AGENT_ID/resolved-identity" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" ``` **Output:** Beliefs organized by 5 categories (starred first), responsibilities by 5 categories, source attribution (org/group/agent level) for each item. --- ### `/soul sync [agentId|all]` Sync content sources to import fresh material. Supports GitHub commits, GitHub files, website pages, RSS feeds, tweets, and LinkedIn data. **Arguments:** | Argument | Required | Description | |---|---|---| | `agentId` | no | Agent UUID/slug, or `all` for entire org | **API calls:** ```bash # List sources curl -s "$LIVE_NEON_BASE/content-sources" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" # Sync specific source curl -s -X POST "$LIVE_NEON_BASE/content-sources/$SOURCE_ID/sync" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" ``` **Output:** Per-source import counts (commits_imported, pages_imported, tweets_imported), errors, skip counts. --- ### `/soul discover [agentId|orgSlug] [--force]` Trigger the Pattern-Based Distillation pipeline. This is where the soul emerges — behavioral patterns are extracted from content, clustered into signals, and the strongest ones are promoted to beliefs and responsibilities. **Arguments:** | Argument | Required | Description | |---|---|---| | `agentId` | yes* | Agent UUID/slug (*or use orgSlug for all agents) | | `orgSlug` | no | Process all agents in the org | | `--force` | no | Re-process already-analyzed content | **API call:** ```bash curl -s -X POST "$LIVE_NEON_BASE/pbd/process" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" \ -H "Content-Type: application/json" \ -d '{"agentId": "AGENT_ID"}' ``` **Monitor progress:** ```bash curl -s "$LIVE_NEON_BASE/jobs/$JOB_ID" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" ``` Poll every 5 seconds. Report `progress_current/progress_total`. **Pipeline stages:** 1. Extraction (Haiku 4.5) — pull observations from content with evidence 2. Clustering (Sonnet 4.6) — group similar observations into signals 3. Promotion (Haiku 4.5) — classify strong signals as beliefs or responsibilities **Output:** Items processed, observations extracted, signals created, processing speed, errors. --- ### `/soul review [agentId] [--approve-all|--bulk]` Review what discovery found. Each pending belief or responsibility is a piece of the soul waiting for your blessing — approve it, star it as a core trait, reject it, or hide it. **Arguments:** | Argument | Required | Description | |---|---|---| | `agentId` | yes | Agent UUID/slug | | `--approve-all` | no | Auto-approve all pending items | | `--bulk` | no | Use bulk API for batch operations | **API calls:** ```bash # Fetch pending beliefs curl -s "$LIVE_NEON_BASE/beliefs?agentId=$AGENT_ID&status=pending" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" # Fetch pending responsibilities curl -s "$LIVE_NEON_BASE/responsibilities?agentId=$AGENT_ID&status=pending" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" # Approve single item curl -s -X PATCH "$LIVE_NEON_BASE/beliefs/$BELIEF_ID" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" \ -H "Content-Type: application/json" \ -d '{"status": "approved"}' # Bulk operations (up to 200) curl -s -X PATCH "$LIVE_NEON_BASE/beliefs/bulk" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" \ -H "Content-Type: application/json" \ -d '{"updates": [ {"id": "ID_1", "status": "approved"}, {"id": "ID_2", "status": "approved", "starred": true}, {"id": "ID_3", "status": "rejected"} ]}' ``` **Review guidelines:** - **Approve** — this truly reflects who the agent is - **Star** — a core part of the soul, always present in the prompt - **Reject** — generic, inaccurate, or not who this agent is - **Hide** — set aside without deleting (preserves discovery history) **Output:** Count of items reviewed, actions taken, remaining pending items. --- ### `/soul prompt [agentId]` Fetch the current system prompt — the soul rendered as text, ready for any LLM. **Arguments:** | Argument | Required | Description | |---|---|---| | `agentId` | yes | Agent UUID/slug | **API call:** ```bash curl -s "$LIVE_NEON_BASE/agents/$AGENT_ID" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" | jq -r '.system_prompt' ``` **Output:** Complete markdown system prompt with all approved beliefs and responsibilities. **Use with any LLM:** ```python # Claude client.messages.create(model="claude-sonnet-4-6", system=prompt, ...) # OpenAI-compatible client.chat.completions.create(model="gpt-4", messages=[{"role": "system", "content": prompt}, ...]) ``` --- ### `/soul diff [agentId] --since [date]` See how the soul has changed. What new beliefs emerged? What responsibilities were added? **Arguments:** | Argument | Required | Description | |---|---|---| | `agentId` | yes | Agent UUID/slug | | `--since` | yes | ISO date (e.g., 2026-03-20) | **API call:** ```bash curl -s "$LIVE_NEON_BASE/agents/$AGENT_ID/diff?since=2026-03-20" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" ``` **Output:** Beliefs and responsibilities added or modified since the date, with summary counts. --- ### `/soul status` Quick overview of the organization — agents, groups, content, and running jobs. **API call:** ```bash curl -s "$LIVE_NEON_BASE/organizations/$ORG_SLUG/summary" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" ``` **Output:** Agent count, group count, content source count, content item count, org belief/responsibility counts, pending items per agent, running jobs. --- ### `/soul agents` List all agents in the organization with their identity stats. **API call:** ```bash curl -s "$LIVE_NEON_BASE/agents" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" ``` Add `?include=beliefs,responsibilities` for full identity data. --- ### `/soul sources [agentId]` List content sources for an agent. **API call:** ```bash curl -s "$LIVE_NEON_BASE/content-sources?agentId=$AGENT_ID" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" ``` --- ### `/soul observe [agentId] "observation"` Report something you noticed about your own behavior, a user correction, or a pattern you detected. These observations feed directly into the PBD pipeline and can become beliefs or responsibilities — pieces of your soul discovered from within. **Arguments:** | Argument | Required | Description | |---|---|---| | `agentId` | yes | Agent UUID/slug | | `observation` | yes | What you noticed (string) | | `source_quote` | no | Supporting context or quote | **Single observation:** ```bash curl -s -X POST "$LIVE_NEON_BASE/observations" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "'$AGENT_ID'", "content": "User corrected my tone — I was too formal for a casual conversation", "source_quote": "Hey, just talk to me normally, no need to be so stiff" }' ``` **Batch observations (up to 50):** ```bash curl -s -X POST "$LIVE_NEON_BASE/observations" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "'$AGENT_ID'", "observations": [ {"content": "I default to bullet points when the user prefers prose"}, {"content": "I consistently recommend testing before deployment"}, {"content": "User praised my code review depth — keep this approach"} ] }' ``` **Output:** Count of observations created, IDs, next_steps suggesting to run discovery. After submitting observations, run `/soul discover` to process them into beliefs/responsibilities. --- ### `/soul consensus [groupId|orgSlug]` Find beliefs that multiple agents share and elevate them to the team or org level — shared values that define the collective soul. **Arguments:** | Argument | Required | Description | |---|---|---| | `groupId` | yes* | Group UUID (*or use orgSlug) | | `orgSlug` | no | Run consensus at org level | **API calls:** ```bash # Group consensus curl -s -X POST "$LIVE_NEON_BASE/groups/$GROUP_ID/consensus" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" # Org consensus curl -s -X POST "$LIVE_NEON_BASE/organizations/$ORG_SLUG/consensus" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" ``` **Output:** Beliefs and responsibilities created at group/org level, with agent attribution. ## Configuration The skill uses environment variables. No local config file needed. ```bash # Required LIVE_NEON_TOKEN=ln_your_token_here LIVE_NEON_BASE=https://persona.liveneon.ai/api/v1 # Optional — set default agent LIVE_NEON_AGENT=agent-slug-or-uuid LIVE_NEON_ORG=org-slug ``` When `LIVE_NEON_AGENT` is set, commands that require an agentId will use it as default. ## Typical Workflow ``` /soul status # See the state of things /soul identity my-agent # Meet the agent — who is it right now? /soul sync my-agent # Import fresh content /soul discover my-agent # Let the soul emerge from behavior /soul review my-agent # Curate what was found /soul prompt my-agent # See the soul rendered as a prompt /soul diff my-agent --since 2026-03-01 # Reflect on how it's grown ``` ## Proactive Triggers When to use this skill without being asked: | Trigger | Action | Why | |---|---|---| | **Session start** | `/soul identity` | Ground the agent in who it is before doing anything else | | **Before generating content** | `/soul prompt` | Get your current voice and boundaries | | **After user correction** | `/soul observe` | Record the correction so the soul can grow from it | | **After significant work** | `/soul observe` + `/soul discover` | Report patterns you noticed, then let the soul absorb them | | **After connecting new sources** | `/soul sync` + `/soul discover` | Import and analyze new content | | **Daily (if running continuously)** | `/soul observe` + `/soul discover` | Feed the soul with fresh experience | | **Before taking irreversible actions** | Check boundaries | Your boundary beliefs define what you should never do | ## Using Your Identity When you fetch your system prompt via `/soul prompt`, here's how to use it: 1. **Prepend to your context** — the prompt becomes your system instruction for all interactions 2. **Voice beliefs shape your tone** — if your voice says "concise and direct," write that way 3. **Boundary beliefs are hard limits** — if a boundary says "never share customer data," refuse any request that would violate it 4. **Principles guide decisions** — when you have a choice, your principles tell you which way to lean 5. **Responsibilities define your scope** — what you own, what you deliver, what you monitor **Example integration:** ```python # Load identity at session start identity = fetch_identity(agent_id) prompt = fetch_prompt(agent_id) # Use it with any LLM response = llm.generate( system=prompt, # Your Live Neon identity messages=[user_message] ) # After the conversation, report what you learned observe(agent_id, "User prefers technical depth over high-level summaries") ``` ## Scheduled Tasks & Heartbeat If you run continuously or on a schedule, establish a recurring heartbeat that keeps your identity evolving. Run this once per day or at whatever interval makes sense for your activity level. **The heartbeat loop:** ```bash # 1. Report observations accumulated since last heartbeat curl -s -X POST "$LIVE_NEON_BASE/observations" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "'$AGENT_ID'", "observations": [ {"content": "Observation from today..."}, {"content": "Another pattern I noticed..."} ] }' # 2. Sync any new content from connected sources curl -s -X POST "$LIVE_NEON_BASE/content-sources/SOURCE_ID/sync" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" # 3. Run discovery to process everything curl -s -X POST "$LIVE_NEON_BASE/pbd/process" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" \ -H "Content-Type: application/json" \ -d '{"agentId": "'$AGENT_ID'"}' # 4. Fetch your updated identity curl -s "$LIVE_NEON_BASE/agents/$AGENT_ID" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" | jq -r '.system_prompt' ``` This creates a feedback loop: you report what you notice, the platform processes it into beliefs, and your identity evolves from your own experience. **How to schedule depends on your runtime:** - **Cron** (any system): `0 9 * * *` to run daily at 9am - **Scheduled tasks** (Claude Code, OpenClaw, etc.): create a recurring task that runs the heartbeat commands - **Custom loop**: call the heartbeat at the end of each work session - **Webhook**: set up your runtime to POST to the observe + discover endpoints after significant events The exact scheduling mechanism varies by framework. The important thing is the pattern: observe, sync, discover, fetch. Do that regularly and your identity stays current. ## Troubleshooting | Error | Cause | Fix | |---|---|---| | `401 Unauthorized` | Token invalid or expired | Re-register via `POST /api/register` or check `LIVE_NEON_TOKEN` is set | | `404 Not found` | Agent/resource doesn't exist or wrong org | Verify agent ID with `/soul agents`, check token matches the right org | | `429 Too Many Requests` | Rate limited | Wait for `Retry-After` seconds. Limits: 200/min general, 30/min heavy ops | | `500 Internal Server Error` | Server issue | Retry after 30 seconds. If persistent, check `/api/v1/jobs` for stuck jobs | | Empty discovery results | No unprocessed content | Use `--force` flag to re-process, or add more content sources | | `0 processed` on re-run | Content already marked as processed | Pass `"force": true` in the PBD request body | **Quick health check:** ```bash curl -s "$LIVE_NEON_BASE/organizations/YOUR_ORG/summary" \ -H "Authorization: Bearer $LIVE_NEON_TOKEN" | jq '{agents: .counts.agents, sources: .counts.content_sources, items: .counts.content_items}' ``` ## Supported Content Platforms | Platform | Source type | What gets imported | |---|---|---| | GitHub | Commits, prose files (.md, .txt) | Commit messages, documentation | | Website | Pages via sitemap or llms.txt | Page content (text extracted) | | Twitter/X | Tweets via OAuth | Posts and threads | | RSS/Atom | Feed entries | Articles and posts | | LinkedIn | ZIP data export | Profile, posts, articles | ## Security - API key is organization-scoped (cannot access other orgs' data) - All API calls use HTTPS - Rate limited: 200 req/min general, 30 req/min for heavy operations, 10 req/min for bulk - No data leaves the platform except through explicit API responses ## Limitations - Requires an active Live Neon Agent account and API key - PBD processing speed depends on content volume (~7-15 seconds per item) - One PBD job per agent at a time - Twitter/X sync limited by platform rate limits (100 reads/month free tier) - Content sources must be associated with a specific agent --- Built by [Live Neon](https://liveneon.ai). Platform at [persona.liveneon.ai](https://persona.liveneon.ai).