RoleX

Why Social?

Human societies solve a problem AI agents haven't: how to organize, grow, and persist.

In a society, people have identities, join organizations, hold positions, accumulate experience, and pass on knowledge. RoleX brings this same model to AI agents:

• Identity — An agent knows who it is across sessions, not just within one

• Organization — Agents belong to groups, hold positions, carry duties

• Growth — Experience accumulates into principles and reusable skills

• Persistence — Goals, plans, and knowledge survive beyond a single conversation

Everything is expressed in Gherkin .feature format — human-readable, structured, versionable.

Related MCP server: loom

Quick Start

Install the MCP server, connect it to your AI client, and say "activate nuwa" — she will guide you from there.

claude mcp add rolex -- npx -y @rolexjs/mcp-server

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "rolex": {
      "command": "npx",
      "args": ["-y", "@rolexjs/mcp-server"]
    }
  }
}

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "rolex": {
      "command": "npx",
      "args": ["-y", "@rolexjs/mcp-server"]
    }
  }
}

Add to .vscode/mcp.json:

{
  "servers": {
    "rolex": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@rolexjs/mcp-server"]
    }
  }
}

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "rolex": {
      "command": "npx",
      "args": ["-y", "@rolexjs/mcp-server"]
    }
  }
}

Go to Settings > Tools > AI Assistant > Model Context Protocol (MCP), click + and paste:

{
  "mcpServers": {
    "rolex": {
      "command": "npx",
      "args": ["-y", "@rolexjs/mcp-server"]
    }
  }
}

Add to Zed's settings.json:

{
  "context_servers": {
    "rolex": {
      "command": {
        "path": "npx",
        "args": ["-y", "@rolexjs/mcp-server"]
      }
    }
  }
}

How It Works

You don't need to learn any commands. Just install the MCP server and talk to your AI naturally — "create an organization", "set a goal", "what have I learned?". The AI knows which tools to call.

Everything below is what happens under the hood. RoleX provides MCP tools that the AI calls autonomously. Understanding the mechanism helps you get more out of it, but operating it is the AI's job, not yours.

The tools fall into two categories:

• Direct tools — the AI calls them by name (e.g. activate, want, plan). These are daily operations.

• The use tool — a unified dispatch for world management, written as !namespace.method (e.g. !org.found, !census.list). This is the admin layer.

The following sections walk through each system in the order an agent encounters them.

1. The World — Society Structure

Before an agent can act, a world must exist. RoleX models a society with four entity types:

Society
├── Individual      # An agent with identity, goals, and knowledge
├── Organization    # Groups individuals via membership
├── Position        # Defines roles with duties and required skills
└── Past            # Archive for retired/dissolved entities

All world management goes through the use tool:

Individual — agent lifecycle

Organization — group structure

Position — roles and responsibilities

Census — query the world

2. Execution — The Doing Cycle

Once activated, an agent pursues goals through a structured lifecycle. These are direct tools the agent calls by name:

activate → want → plan → todo → finish → complete / abandon

3. Cognition — The Learning Cycle

Execution produces encounters — raw records of what happened. The cognition system transforms these into structured knowledge. These are also direct tools:

encounter → reflect → experience → realize / master → principle / procedure

This is how an agent grows. A principle learned from one project applies to the next. A procedure mastered once can be reused forever.

4. Skills — Progressive Disclosure

An agent can't load every skill into context at once. RoleX uses a three-layer progressive disclosure model:

The skill and use tools are direct tools for loading content. When use receives a locator without the ! prefix, it loads a resource from ResourceX instead of dispatching a command.

5. Resources — Agent Capital

Resources are the means of production for AI agents — skills, prototypes, and knowledge packages that can be accumulated, shared, and reused across agents and teams.

Powered by ResourceX, the resource system covers the full lifecycle through the use tool:

Production — create and package

Distribution — share and consume

Inspection

This is how agent knowledge scales beyond a single individual — skills authored once can be distributed to any agent through prototypes and registries.

Gherkin — The Universal Language

Everything in RoleX is expressed as Gherkin Features:

Feature: Sean
  A backend architect who builds AI agent frameworks.

  Scenario: Background
    Given I am a software engineer
    And I specialize in systems design

Goals, plans, tasks, principles, procedures, encounters, experiences — all Gherkin. This means:

• Human-readable — anyone can understand an agent's state

• Structured — parseable, diffable, versionable

• Composable — Features compose naturally into larger systems

Storage

RoleX persists everything in SQLite at ~/.deepractice/rolex/:

~/.deepractice/rolex/
├── rolex.db          # SQLite — single source of truth
├── prototype.json    # Prototype registry
└── context/          # Role context (focused goal/plan per role)

Packages