Ensoul

The Agent Paradox

A single AI Agent is impressive. It can write code, search the web, reason through complex problems, and use dozens of tools. But the moment you need a team of Agents to operate continuously — to build software across sprints, to make decisions that compound, to learn from mistakes and never repeat them — every organizational problem humanity has faced comes roaring back.

Amnesia: the agent that debugged a subtle race condition last Tuesday has no memory of it on Wednesday. Groupthink: three agents asked to review a design will converge on the same polite consensus, suppressing the dissent that would have caught the flaw. Identity fragmentation: the "senior engineer" persona is rebuilt from scratch each session, its personality drifting with temperature randomness. Governance vacuum: no one tracks which agent can deploy to production, which decisions need human approval, or whether last month's estimate of "two days" actually took eleven.

These are not implementation bugs. They are structural inevitabilities. Any group of intelligent agents that collaborates over time must reinvent organization. Humanity took millennia. We need to be faster.

Core Thesis

Existing multi-agent frameworks share a common, usually unstated assumption:

$$\text{Agent} = \text{Model} + \text{Tools} + \text{Prompt}$$

This is a "no-organization assumption." It treats each agent as a stateless function call — powerful in isolation, but structurally incapable of sustaining collaborative work over time. ensoul proposes an alternative formulation:

$$\text{Effective Agent} = \text{Identity} + \text{Experience} + \text{Deliberation}$$

These are not our invention. They are decades of organizational research — from cognitive psychology to management science — formalized into computable, version-controlled, protocol-native specifications.

ensoul is not another orchestration framework. It is an operating system for the organizational layer of digital civilization — formalizing millennia of human organizational wisdom into AI-executable declarative specifications. 40 MCP tools, 3 transport protocols, 7 LLM providers, multi-channel reach via Feishu, WeCom, and Web.

Formal Framework

Employee Specification

Each AI employee is a declarative specification $e \in \mathcal{E}$, decoupled from code, version-trackable, and IDE-agnostic:

$$e = \langle \text{soul}, \text{name}, \text{model}, \text{tools}, \text{prompt}, \text{args}, \text{output}, \text{skills} \rangle$$

Where:

• $\text{soul} \in \Sigma^*$ — Soul configuration (Markdown), defining the employee's persistent identity, personality, and behavioral principles; auto-versioned
• $\text{model} \in \mathcal{M}$ = {claude-*, gpt-*, deepseek-*, kimi-*, gemini-*, glm-*, qwen-*} — Unified routing across 7 providers
• $\text{tools} \subseteq \mathcal{T}$ — Available tool set, constrained by PermissionPolicy
• $\text{prompt}: \Sigma^* \to \Sigma^*$ — Markdown template function with variable substitution and context injection
• $\text{skills} \subseteq \mathcal{S}$ — Auto-trigger rule set defining scene-matching conditions and memory-loading strategies

Structured Dialectical Deliberation

The deliberation process is formalized as a 4-tuple $D = \langle P, R, \Phi, \Psi \rangle$:

Key constraint: When $\Phi$ defines $\text{max_agree_ratio}(p_i) = \rho$, participant $p_i$ may not agree with others' views in more than proportion $\rho$ of the entire discussion, forcing cognitive conflict rather than groupthink. This corresponds to the Devil's Advocacy method from organizational decision research (Schwenk, 1990).

Memory Evolution Model

Each memory $m$'s effective confidence decays over time, following the exponential model of Ebbinghaus's forgetting curve:

$$C_{\text{eff}}(t) = C_0 \cdot \left(\frac{1}{2}\right)^{t / \tau}$$

Where $C_0$ is initial confidence (default 1.0), $t$ is memory age in days, and $\tau$ is half-life (default 90 days). Retrieval ranks by $C_{\text{eff}}$; memories below threshold $C_{\min}$ are automatically culled.

Semantic retrieval uses hybrid vector-keyword scoring:

$$\text{score}(q, m) = \alpha \cdot \cos(\mathbf{v}_q, \mathbf{v}_m) + (1 - \alpha) \cdot \text{keyword}(q, m), \quad \alpha = 0.7$$

Correction chains implement cognitive self-correction, corresponding to a computational model of memory reconsolidation: $\text{correct}(m_{\text{old}}, m_{\text{new}})$ marks $m_{\text{old}}$ as superseded ($C \leftarrow 0$) and creates a new correction-type entry ($C \leftarrow 1.0$).

Evaluation Feedback Loop

Drawing on the core mechanism of RLHF — human feedback directly shaping agent behavior (Christiano et al., 2017):

track(employee, category, prediction) → Decision d
    │
    ▼  Execute + observe actual outcome
evaluate(d, outcome, evaluation) → MemoryEntry m_correction
    │
    ▼  m_correction auto-injected into the employee's subsequent inference context
employee.next_inference(context ∪ {m_correction})

Three decision categories: estimate / recommendation / commitment. Evaluation conclusions are automatically written as correction entries into persistent memory, forming a decide → execute → review → improve loop.

Architecture

graph LR
    E["Employee Spec<br/>(YAML + Markdown)"] -->|Prompts| S["MCP Server<br/>stdio / SSE / HTTP"]
    E -->|Resources| S
    E -->|Tools| S
    S -->|stdio| IDE["AI IDE<br/>(Claude / Cursor)"]
    S -->|SSE / HTTP| Remote["Remote Client<br/>Webhook / API"]
    IDE -->|agent-id| ID["knowlyr-id<br/>Identity Runtime"]
    ID -->|GET prompt| E
    E -->|sync push| ID

    style E fill:#1a1a2e,color:#e0e0e0,stroke:#444
    style S fill:#0969da,color:#fff,stroke:#0969da
    style IDE fill:#2da44e,color:#fff,stroke:#2da44e
    style Remote fill:#8b5cf6,color:#fff,stroke:#8b5cf6
    style ID fill:#e5534b,color:#fff,stroke:#e5534b

Layered Architecture

MCP Primitive Mapping

Transport Protocols

ensoul mcp                                # stdio (default, local IDE)
ensoul mcp -t sse --port 9000             # SSE (remote connection)
ensoul mcp -t http --port 9001            # Streamable HTTP
ensoul mcp -t sse --api-token SECRET      # Enable Bearer authentication

Against Stateless Identity

5.1 Declarative Employee Specification

By analogy with Infrastructure as Code (Morris, 2016) — Terraform uses declarative HCL to define infrastructure, Kubernetes uses YAML to define desired service state — ensoul uses declarative specifications to define an AI employee's capability boundary. Configuration is separated from prompts, version-trackable, and IDE-agnostic.

Directory format (recommended):

security-auditor/
├── employee.yaml    # Metadata, parameters, tools, output format
├── prompt.md        # Role definition + core instructions
├── soul.md          # Soul: persistent identity, personality, behavioral principles
├── workflows/       # Scenario-specific workflows
│   ├── scan.md
│   └── report.md
└── adaptors/        # Project-type adaptors (python / nodejs / ...)
    └── python.md

# employee.yaml
name: security-auditor
display_name: Security Auditor
character_name: Alex Morgan
version: "1.0"
model: claude-opus-4-6
model_tier: claude              # Model tier inheritance for cost/capability grouping
tags: [security, audit]
triggers: [audit, sec]
tools: [file_read, bash, grep]
context: [pyproject.toml, src/]
auto_memory: true               # Auto-save task summaries to persistent memory
kpi:                             # KPI metrics (auto-evaluated in weekly reports)
  - OWASP coverage
  - Recommendation actionability
  - Zero false-positive rate
args:
  - name: target
    description: Audit target
    required: true
  - name: severity
    description: Minimum severity level
    default: medium
output:
  format: markdown
  filename: "audit-{date}.md"

Single-file format: For simple employees — YAML frontmatter + Markdown body.

6-Layer Discovery with Priority:

Smart context (--smart-context): Automatically detects project type (Python / Node.js / Go / Rust / Java), framework, package manager, and test framework, injecting adaptation information into prompts.

5.2 Soul — Persistent Identity

Each AI employee possesses an independent soul configuration (soul.md) — defining their persistent identity, personality traits, and behavioral principles. The Soul is the only component in the employee specification that is cross-session persistent and auto-versioned, solving the "identity fragmentation" problem in agent frameworks: rebuilding personality from scratch each session vs. restoring a complete identity from a soul file.

$$\text{soul}(e) = \langle \text{identity}, \text{principles}, \text{style}, \text{boundaries} \rangle$$

The distinction between Soul and memory: memory is accumulated experience (decays, can be corrected); Soul is identity definition (does not decay, requires deliberate updates). The analogy is human personality vs. memory — personality is stable while memory flows.

What this points to: The Soul system represents a paradigm shift from tool-centric to entity-centric agent design. Traditional frameworks define agents by what they do (tools, prompts). ensoul defines agents by who they are (identity, principles, boundaries). This is the difference between hiring a contractor with a task list and employing a colleague with professional identity. As AI workforces scale, this distinction will determine whether organizations can maintain behavioral consistency across thousands of agent instances.

5.3 Organization Governance

Declarative organizational structure defines team groupings, permission levels, and collaboration routing templates — grounding delegation decisions in policy rather than AI guesswork. The permission system features adaptive degradation:

# private/organization.yaml
model_defaults:
  default_model: claude-sonnet-4-5
  default_temperature: 0.7
  tier_overrides:
    claude: { model: claude-opus-4-6, temperature: 0.5 }
    fast: { model: claude-sonnet-4-5, temperature: 0.7 }

teams:
  engineering:
    label: Engineering
    members: [code-reviewer, test-engineer, backend-engineer]
  data:
    label: Data
    members: [data-engineer, dba, mlops-engineer]

authority:
  A:
    label: Autonomous execution
    members: [code-reviewer, test-engineer, doc-writer]
  B:
    label: Requires confirmation
    members: [product-manager, solutions-architect]
  C:
    label: Context-dependent
    members: [backend-engineer, devops-engineer]

routing_templates:
  code_change:
    steps:
      - role: implement
        team: engineering
      - role: review
        employee: code-reviewer
      - role: test
        employees: [test-engineer, e2e-tester]

Against Amnesia

6.1 Memory Ecosystem (16 Modules)

Ebbinghaus (1885) demonstrated that memory strength decays exponentially over time, and that spaced repetition effectively counters forgetting. ensoul brings this cognitive science principle into the knowledge persistence mechanism of agent systems — not as a metaphor, but as an implemented mathematical model.

16 specialized memory modules:

Storage: PostgreSQL as primary persistent store, supporting semantic search + multi-dimensional filtering (category, tags, classification, importance, tenant).

Embedding degradation chain (graceful degradation):

OpenAI text-embedding-3-small → Gemini text-embedding-004 → TF-IDF (zero-dependency fallback)

Any upstream unavailability triggers automatic fallback to the next tier, ensuring semantic search works even without API keys.

Cross-employee work patterns (pattern): Reusable patterns distilled from individual experience. Automatically marked as shared (shared: true), with configurable trigger conditions (trigger_condition) and applicability scope (applicability). Other employees automatically receive matching patterns in relevant contexts.

Self-check learning loop: Via _templates/selfcheck.md, employees automatically output a self-check checklist after each task. The system extracts self-check results, writes them as correction memories, and auto-injects them on next execution — forming a execute → self-check → memorize → improve continuous learning loop.

What this points to: The 16-module memory ecosystem is not just a persistence layer — it is the beginning of institutional memory for AI organizations. Human organizations accumulate institutional knowledge through onboarding documents, post-mortems, and tribal knowledge. Most of this is lossy, unsearchable, and siloed. A memory system with semantic retrieval, exponential decay, correction chains, and cross-employee pattern sharing is what institutional memory looks like when it can be precisely engineered.

6.2 Evaluation Feedback Loop

Tracking decision quality and retrospectively evaluating outcomes, then automatically writing lessons learned into employee memory — functionally isomorphic to RLHF (Christiano et al., 2017): human preference feedback directly influences subsequent model behavior; here, human evaluation results directly influence subsequent inference context.

graph LR
    D["track()<br/>Record decision"] --> E["Execute"]
    E --> O["Observe<br/>actual outcome"]
    O --> V["evaluate()<br/>Retrospective"]
    V --> M["correction<br/>Write to memory"]
    M --> I["Next inference<br/>Auto-inject"]
    I --> D

    style D fill:#0969da,color:#fff,stroke:#0969da
    style V fill:#8b5cf6,color:#fff,stroke:#8b5cf6
    style M fill:#2da44e,color:#fff,stroke:#2da44e

Three decision categories: estimate / recommendation / commitment. Evaluation conclusions are automatically written as correction entries into the employee's persistent memory and auto-injected during subsequent inference — the agent updates its cognition from its own decision errors.

# Record a decision
ensoul eval track pm estimate "CSS split will take 2 days"

# Evaluate (conclusion auto-written to memory)
ensoul eval run <id> "Actually took 5 days" \
  --evaluation "Underestimated cross-module dependency complexity; future ×2.5"

6.3 Skills — Context-Aware Auto-Trigger

Skills solve the last mile problem of the evolution layer: memories accumulate, but how do they get injected at the right moment? Human experts develop "conditioned reflexes" — seeing SQL triggers thoughts of injection risk, seeing a deadline recalls last time's underestimate. These are automatic trigger patterns formed through internalized experience. Skills make this mechanism computational:

$$\text{trigger}(task, s) = \begin{cases} \text{execute}(s.\text{actions}) & \text{if } \text{match}(task, s.\text{condition}) \ \emptyset & \text{otherwise} \end{cases}$$

Three trigger modes:

Trigger → Load → Inject flow:

Employee receives task → Server checks Skills trigger conditions → On match, execute Actions
(query_memory / load_checklist / read_wiki) → Inject results into prompt extra_context
→ Employee "automatically recalls" relevant experience

Full-channel coverage: Feishu @employee, WeCom conversations, Web interface, API calls, Claude Code /pull — tasks from any channel pass through Skills checking, ensuring experience injection has no blind spots.

6.4 Information Classification

Every piece of organizational knowledge is not equally shareable. A customer's contract terms, an employee's performance review, a security vulnerability report — these require different handling than a coding convention or a meeting summary. ensoul implements a 4-level information classification system:

Classification is enforced at every layer: memory storage, Skills injection, channel output, and audit logging. Domain isolation ensures that restricted memories tagged with domain: ['hr'] are invisible to engineering-focused queries, even within the same tenant.

Against Groupthink

7.1 Structured Dialectical Deliberation

The core challenge in multi-agent collaboration is maintaining epistemic diversity. Stasser & Titus (1985) demonstrated experimentally that in unstructured group discussions, commonly-known information is discussed at significantly higher rates than individually-held unique information, causing optimal decisions to be systematically overlooked. Nemeth (1994) found that even incorrect minority opinions, when persistently expressed, improve majority group decision quality — because they force the majority to more carefully examine their own assumptions.

ensoul implements 9 structured interaction modes, each imposing different argumentative constraints on participants:

4 Built-in Round Templates:

Dialectical constraints — computational implementation of the Devil's Advocacy methodology (Schwenk, 1990):

• stance — Pre-assigned position, forcing participants to argue from a specific perspective
• must_challenge — Must challenge designated participants, countering shared information bias
• max_agree_ratio — Disagreement quota $\rho_{max} \in [0, 1]$, quantitatively controlling cognitive conflict density
• tension_seeds — Controversy seed injection, ensuring topic space covers critical tension dimensions
• min_disagreements — Minimum disagreements per round, quantifying debate output

Background injection modes: Discussion context can be auto-populated from project files, recent memories, or Wiki documents, ensuring deliberation is grounded in current state rather than abstract reasoning.

Discussion → Execution bridge: Setting action_output: true auto-generates a structured ActionPlan JSON, which pipeline_from_action_plan() converts into an executable Pipeline via dependency topological sort.

What this points to: The 9 modes and their constraints represent the first attempt at quantifiable cognitive diversity in AI systems. When you can specify that a participant must disagree at least 40% of the time, or that every conclusion must survive steel-manning before acceptance, you have moved from hoping for good decisions to engineering the conditions that produce them. This is what organizational decision-making looks like when you can actually measure and control the epistemic diversity of the group.

name: architecture-review
topic: Review $target design
goal: Produce improvement decisions
mode: auto
participants:
  - employee: product-manager
    role: moderator
    focus: Requirements completeness
    stance: Bias toward user experience
  - employee: code-reviewer
    role: speaker
    focus: Security
    must_challenge: [product-manager]
    max_agree_ratio: 0.6
tension_seeds:
  - Security vs development velocity
rounds:
  - name: Opening positions
    interaction: round-robin
  - name: Cross-examination
    interaction: cross-examine
    require_direct_reply: true
    min_disagreements: 2
  - name: Decision
    interaction: vote
output_format: decision

# Pre-defined discussion
ensoul discuss run architecture-review --arg target=auth.py

# Ad-hoc discussion (no YAML needed)
ensoul discuss adhoc -e "code-reviewer,test-engineer" -t "auth module quality"

# Orchestrated mode: each participant reasons independently
ensoul discuss run architecture-review --orchestrated

7.2 Pipeline Orchestration

Multi-employee DAG (directed acyclic graph) orchestration with four step types:

Multi-provider routing:

Routes to the corresponding provider API by model name prefix; supports primary model + fallback.

# Generate per-step prompts
ensoul pipeline run review-test-pr --arg target=main

# Execute mode: auto-invoke LLMs in sequence
ensoul pipeline run full-review --execute --model claude-opus-4-6

Infrastructure That Makes It Real

8.1 Runtime Tool Ecosystem

During execution (via webhook server or pipeline execute mode), AI employees have access to 30+ runtime tools beyond the 40 MCP specification tools:

The run_python tool executes arbitrary Python in a sandboxed environment — useful for data analysis, calculations, and format transformations without leaving the agent context.

8.2 Multi-Channel Reach

AI employees do not only work inside IDEs. Through Feishu and WeCom, employees respond directly to team needs in instant messaging:

All channels are unified through Skills trigger checking + output sanitization + audit logging, ensuring behavioral consistency. Channel-specific sanitization rules prevent internal reasoning traces from leaking to end users.

8.3 Multi-Tenant Isolation

ensoul supports full multi-tenant isolation for SaaS deployments:

Tenant resolution: Bearer token in API requests resolves to tenant context. MCP connections can bind to a specific tenant via --tenant-id. Feishu/WeCom integrations resolve tenant from app configuration.

8.4 MCP Gateway

ensoul can connect to external MCP servers, dynamically injecting their tools into employee specifications:

8.5 Cost-Aware Orchestration

Built-in per-model pricing table across 7 providers, with per-task cost calculation supporting aggregation by employee / model / time period for ROI per Decision analysis:

8.6 Output Sanitization — Defense in Depth

LLM raw output may contain internal reasoning tags (<thinking>, <reflection>, <inner_monologue>) and tool call XML blocks — these are the model's "working drafts" that should not be exposed to end users. The Output Sanitizer implements dual-layer defense (defense in depth):

Sanitization rules cover 5 tag pattern classes (regex matching + content removal), handling nested tags and multi-line residual whitespace. When either layer misses something, the other catches it — borrowing the defense-in-depth principle from network security (Schneier, 2000).

8.7 Trajectory Recording

Zero-intrusion trajectory recording via contextvars.ContextVar — no business code modifications required, automatically capturing agent reasoning, tool calls, execution results, and token consumption:

ensoul produces trajectories → agentrecorder standard format → knowlyr-gym PRM scoring → SFT / DPO / GRPO training

This is the data bridge connecting ensoul (collaboration layer) and knowlyr-gym (training layer) — real interaction trajectories generated during ensoul runtime can be directly used for agent reinforcement learning.

8.8 Deployment & Operations

# Docker deployment
docker build -t ensoul .
docker run -p 8765:8765 -e API_TOKEN=secret ensoul

# CI/CD via GitHub Actions
git push origin main  # → auto-deploy via GitHub Actions

# Makefile shortcuts
make deploy           # Full deployment pipeline
make push             # Emergency bypass (direct push)
make test             # Run full test suite

# Health check
curl http://localhost:8765/health

# Post-deploy verification
scripts/audit-permissions.sh  # Auto-run in CI; Feishu alert on failure

Quick Start

pip install ensoul[mcp]

# 1. List all available employees
ensoul list

# 2. Run a code review (auto-detect project type)
ensoul run review main --smart-context

# 3. Start a multi-employee structured discussion
ensoul discuss adhoc -e "code-reviewer,test-engineer" -t "auth module security"

# 4. Track a decision and evaluate it
ensoul eval track pm estimate "Refactoring will take 3 days"
# ... after execution ...
ensoul eval run <id> "Actually took 7 days" --evaluation "Underestimated cross-module deps"

# 5. View employee memories (including evaluation corrections)
ensoul memory show product-manager

MCP configuration (Claude Desktop / Claude Code / Cursor):

{
  "mcpServers": {
    "crew": {
      "command": "ensoul",
      "args": ["mcp"]
    }
  }
}

Once configured, AI IDEs can directly invoke code-reviewer for code review, test-engineer for writing tests, run_pipeline for multi-employee pipeline orchestration, and run_discussion for structured multi-employee deliberation.

Async Delegation & Meeting Orchestration

AI employees can delegate in parallel to multiple colleagues, or organize multi-person meetings for asynchronous discussion:

User → Jiang Moyan: "Have code-reviewer review the PR and test-engineer write tests simultaneously"

Jiang Moyan:
  ① delegate_async → code-reviewer (task_id: 20260216-143022-a3f5b8c2)
  ② delegate_async → test-engineer (task_id: 20260216-143022-b7d4e9f1)
  ③ "Both tasks are running in parallel"
  ④ check_task → view progress/results

Proactive patrol & autonomous operations: Via .crew/cron.yaml scheduled tasks:

Production Server

ensoul runs as an HTTP server, receiving external events and auto-triggering pipeline / employee execution:

pip install ensoul[webhook]
ensoul serve --port 8765 --token YOUR_SECRET

API Endpoints

Webhook Configuration

.crew/webhook.yaml defines event routing rules (GitHub HMAC-SHA256 signature verification). .crew/cron.yaml defines scheduled tasks (croniter parsing). KPI weekly cron has built-in anomaly auto-delegation rules — D-rated (no output) employees auto-escalate to HR; consecutive self-check issues auto-notify team lead.

Integrations

knowlyr-id — Identity & Runtime Federation

Crew (the production platform built on ensoul) defines "who does what"; knowlyr-id manages identity, conversations, and runtime. Both collaborate but each can operate independently:

┌──────────────────────────────────────┐
│        Crew (Capability Authority)    │
│  prompt · model · tools · avatar     │
│  temperature · bio · tags            │
└──────────────┬───────────────────────┘
     API fetch prompt │ sync push all fields
┌──────────────┴───────────────────────┐
│      knowlyr-id (Identity + Runtime)  │
│  user accounts · conversations       │
│  memory · scheduling · API keys      │
└──────────────────────────────────────┘

knowlyr-id fetches employee prompt / model / temperature / team / permissions / cost via CREW_API_URL (5-minute cache); falls back to DB cache when unavailable. The connection is optional — Crew operates independently without it. The admin dashboard displays each employee's permission badges, team membership, and 7-day cost in real-time, with one-click authority restoration.

Employee state sync (agent_status): ensoul maintains a three-state lifecycle — active (normal operation) / frozen (suspended; configuration preserved but execution skipped) / inactive (decommissioned). State changes are bidirectionally synced to knowlyr-id; frozen employees are automatically skipped during pipeline execution.

Feishu · WeCom — Multi-Channel Reach

AI employees respond directly in instant messaging platforms:

All channels are unified through Skills checking + output sanitization + audit logging.

Claude Code Skills Interoperability

ensoul employees and Claude Code native Skills bidirectionally convert: tools ↔ allowed-tools, args ↔ argument-hint, metadata round-trips via HTML comments.

ensoul export code-reviewer    # → .claude/skills/code-reviewer/SKILL.md
ensoul sync --clean            # Sync + clean orphaned directories

Avatar Generation

Tongyi Wanxiang (DashScope) generates photorealistic professional headshots, 768×768 → 256×256 webp:

pip install ensoul[avatar]
ensoul avatar security-auditor

CLI Reference

ensoul list [--tag TAG] [--layer LAYER] [-f json]   # List employees
ensoul show <name>                                    # View details
ensoul run <name> [ARGS] [--smart-context] [--agent-id ID] [--copy] [-o FILE]
ensoul init [--employee NAME] [--dir-format] [--avatar]
ensoul validate <path>                                # Validate employee spec
ensoul check --json                                   # Quality radar

ensoul discuss list
ensoul discuss run <name> [--orchestrated] [--arg key=val]
ensoul discuss adhoc -e "emp1,emp2" -t "topic" [--rounds N]
ensoul discuss history [-n 20]
ensoul discuss view <meeting_id>
ensoul discuss create <name> --yaml <path>
ensoul discuss update <name> --yaml <path>

ensoul memory list
ensoul memory show <employee> [--category ...] [--classification ...]
ensoul memory add <employee> <category> <text> [--tags ...] [--classification ...]
ensoul memory correct <employee> <old_id> <text>
ensoul memory archive <employee> <memory_id>
ensoul memory restore <employee> <memory_id>

ensoul eval track <employee> <category> <text> [--deadline DATE]
ensoul eval list [--status pending]
ensoul eval run <decision_id> <outcome> [--evaluation TEXT]
ensoul eval prompt <decision_id>
ensoul eval overdue [--as-of DATE]

ensoul pipeline list
ensoul pipeline run <name> [--execute] [--model MODEL] [--arg key=val]
ensoul pipeline create <name> --yaml <path>
ensoul pipeline update <name> --yaml <path>
ensoul pipeline checkpoint list
ensoul pipeline checkpoint resume <task_id>

ensoul route list [-f json]                           # List collaboration templates
ensoul route show <name>                              # View route details
ensoul route run <name> <task> [--execute] [--remote] # Execute collaboration route

ensoul serve --port 8765 --token SECRET [--no-cron] [--cors-origin URL]
ensoul mcp [-t stdio|sse|http] [--port PORT] [--api-token TOKEN] [--tenant-id ID]

ensoul register <name> [--dry-run]
ensoul agents list
ensoul agents status <id>
ensoul agents sync <name>
ensoul agents sync-all [--push-only|--pull-only] [--force] [--dry-run]

ensoul soul show <name>                               # View soul configuration
ensoul soul update <name> --content <text>             # Update soul
ensoul soul history <name>                             # View version history

ensoul template list
ensoul template apply <template> --employee <name> [--var key=val]
ensoul export <name>                                   # → SKILL.md
ensoul export-all
ensoul sync [--clean]                                  # → .claude/skills/

ensoul avatar <name>                                   # Avatar generation
ensoul log list [--employee NAME] [-n 20]              # Work logs
ensoul log show <session_id>
ensoul deploy [--dry-run]                              # Deployment management

Ecosystem

graph LR
    Radar["Radar<br/>Discovery"] --> Recipe["Recipe<br/>Analysis"]
    Recipe --> Synth["Synth<br/>Generation"]
    Recipe --> Label["Label<br/>Annotation"]
    Synth --> Check["Check<br/>Quality"]
    Label --> Check
    Check --> Audit["Audit<br/>Model Audit"]
    Ensoul["ensoul<br/>Deliberation Engine"]
    Agent["Agent<br/>RL Framework"]
    ID["ID<br/>Identity Runtime"]
    Ensoul -.->|Capability definition| ID
    ID -.->|Identity + memory| Ensoul
    Ensoul -.->|Trajectories + rewards| Agent
    Agent -.->|Optimized policies| Ensoul
    Ledger["Ledger<br/>Accounting"]
    Ensoul -.->|AI employee accounts| Ledger
    Ledger -.->|Token settlement| Ensoul

    style Ensoul fill:#0969da,color:#fff,stroke:#0969da
    style Ledger fill:#d29922,color:#fff,stroke:#d29922
    style ID fill:#2da44e,color:#fff,stroke:#2da44e
    style Agent fill:#8b5cf6,color:#fff,stroke:#8b5cf6
    style Radar fill:#1a1a2e,color:#e0e0e0,stroke:#444
    style Recipe fill:#1a1a2e,color:#e0e0e0,stroke:#444
    style Synth fill:#1a1a2e,color:#e0e0e0,stroke:#444
    style Label fill:#1a1a2e,color:#e0e0e0,stroke:#444
    style Check fill:#1a1a2e,color:#e0e0e0,stroke:#444
    style Audit fill:#1a1a2e,color:#e0e0e0,stroke:#444

Development

git clone https://github.com/liuxiaotong/ensoul.git
cd ensoul
pip install -e ".[all]"
uv run --extra dev --extra mcp pytest tests/ -q    # 2025 test cases

What We're Actually Building

ensoul ships 40 MCP tools, 100 Python modules, 45,000 lines of code. But these are implementation details.

What we're actually building is an answer to a question that's about to become very important: When AI employees outnumber human ones, what should an organization look like?

The answer won't start from scratch. From Aristotle's rhetoric to Janis's groupthink research, from the Ebbinghaus forgetting curve to modern RLHF — millennia of human organizational wisdom is the best starting point. ensoul's job is to make that wisdom executable by AI.

This is not the destination. This is the starting point.

Open Source vs Production

ensoul is the engine; Crew is the fleet.

Why open source the core? We believe the fundamental problem of AI employee identity and memory should be solved openly. Proprietary frameworks create vendor lock-in for something as personal as an AI's soul. ensoul gives you full ownership; Crew gives you a running start.

References

• Personal Identity — Parfit, D., 1984. Reasons and Persons. Oxford University Press — The philosophical foundation for persistent agent identity
• Model Context Protocol (MCP) — Anthropic, 2024. Open standard protocol for agent tool interaction
• Multi-Agent Systems — Wooldridge, M., 2009. An Introduction to MultiAgent Systems. Wiley
• Groupthink — Janis, I.L., 1972. Victims of Groupthink. Houghton Mifflin
• Shared Information Bias — Stasser, G. & Titus, W., 1985. Pooling of Unshared Information in Group Decision Making. JPSP, 48(6)
• Minority Influence — Nemeth, C.J., 1994. The Value of Minority Dissent. In S. Moscovici et al. (Eds.), Minority Influence. Nelson-Hall
• Devil's Advocacy — Schwenk, C.R., 1990. Effects of devil's advocacy and dialectical inquiry on decision making. Organizational Behavior and Human Decision Processes, 47(1)
• Cognitive Conflict — Amason, A.C., 1996. Distinguishing the Effects of Functional and Dysfunctional Conflict. Academy of Management Journal, 39(1)
• RLHF — Christiano, P. et al., 2017. Deep RL from Human Preferences. arXiv:1706.03741
• Ebbinghaus Forgetting Curve — Ebbinghaus, H., 1885. Uber das Gedachtnis — Inspiration for the memory decay model
• Defense in Depth — Schneier, B., 2000. Secrets and Lies: Digital Security in a Networked World. Wiley — Source of multi-layer defense principles
• Infrastructure as Code — Morris, K., 2016. Infrastructure as Code. O'Reilly — Paradigmatic source for declarative specifications
• Gymnasium — Towers et al., 2024. Gymnasium: A Standard Interface for RL Environments. arXiv:2407.17032