<div align="center">
  <img src="assets/logo/PromptX-transparent.png" alt="PromptX Logo" width="120" height="120"/>
  <h1>PromptX · Leading AI Agent Context Platform</h1>
  <h2>✨ Chat is all you need - Revolutionary interaction design that turns AI agents into industry experts</h2>
  <p><strong>Core Capabilities:</strong>AI Role Creation Platform | Intelligent Tool Development Platform | Cognitive Memory System</p>
  <p>Based on MCP protocol, inject professional capabilities into Claude, Cursor and other AI applications with a single command</p>

<!-- Badges -->

<p>
    <a href=" "><img src="https://img.shields.io/github/stars/Deepractice/PromptX?style=social" alt="Stars"/></a>
    <img src="https://komarev.com/ghpvc/?username=PromptX&label=views&color=0e75b6&style=flat&abbreviated=true" alt="Views"/>
    <a href="LICENSE"><img src="https://img.shields.io/github/license/Deepractice/PromptX?color=blue" alt="License"/></a>
    <a href="https://zread.ai/Deepractice/PromptX" target="_blank"><img src="https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff" alt="zread"/></a>
  </p>

<p>
    <a href="https://www.npmjs.com/package/@promptx/cli"><img src="https://img.shields.io/npm/v/@promptx/cli?color=orange&logo=npm" alt="npm version"/></a>
    <a href="https://github.com/Deepractice/PromptX/releases"><img src="https://img.shields.io/github/v/release/Deepractice/PromptX?color=green&logo=github" alt="Latest Release"/></a>
    <a href="https://hub.docker.com/r/deepracticexs/promptx"><img src="https://img.shields.io/badge/docker-latest-0db7ed?logo=docker&logoColor=white" alt="Docker"/></a>
  </p>

<p>
    <a href="README.zh-Hans.md">简体中文</a> | 
    <a href="README.zh-Hant.md">繁體中文</a> | 
    <strong><a href="README.md">English</a></strong> | 
    <a href="https://github.com/Deepractice/PromptX/issues">Issues</a>
  </p>
</div>

---

## 💬 Chat is All you Need - Natural conversation, instant expertise

### ✨ Experience PromptX Magic in 3 Steps

#### 🔍 **Step 1: Discover Experts**

```
User: "Show me what experts are available"
AI:   Instantly displays 23 available roles, from product managers to architects
```

#### ⚡ **Step 2: Summon Expert**

```
User: "I need a product manager expert"
AI:   Instantly transforms into a professional product manager with complete knowledge and methodologies
```

#### 🎯 **Step 3: Professional Dialogue**

```
User: "Help me redesign the product page"
AI:   Provides in-depth product strategy advice as a professional product manager
```

### 🎬 See PromptX in Action

<div align="center">

[![PromptX Demo Video](assets/video-head.png)](https://www.youtube.com/watch?v=R6ENaj9i0oE)

*Click to watch: See how PromptX transforms AI interactions with memory, roles, and intelligent tools*

</div>

### 🚀 Why is this revolutionary?

**❌ Traditional approach:**

- Learn complex instruction syntax
- Remember various parameter configurations
- Worry about saying the wrong thing and breaking functionality

**✅ PromptX approach:**

- Natural conversation like talking to a real expert
- Say what you want to say - AI understands your intent
- Expert state remains active throughout the conversation

### 💡 Core Philosophy

> **Treat AI as a person, not software**
>
> No need for "correct commands" - just natural expression. AI will understand what expert you want and instantly switch identities.

---

## ⚡ Get Started - Choose Your Way

### 🎯 Method 1: PromptX Client (Recommended)

**For all users - One-click launch, zero configuration**

#### 📥 Download Client

| Platform                          | Download Link                                                                                    |
| --------------------------------- | ------------------------------------------------------------------------------------------------ |
| 🍎**macOS (Apple Silicon)** | [Download .dmg](https://promptx.deepractice.ai/download/latest/promptx-desktop-mac-arm64.dmg)       |
| 🍎**macOS (Intel)**         | [Download .dmg](https://promptx.deepractice.ai/download/latest/promptx-desktop-mac-x64.dmg)         |
| 🪟**Windows**               | [Download .exe](https://promptx.deepractice.ai/download/latest/promptx-desktop-win32-x64-setup.exe) |

> **Windows users:** The AgentX feature requires [Git for Windows](https://git-scm.com/download/win) to be installed. Please install it before using AgentX.

[📦 View All Releases &amp; Platforms](https://promptx.deepractice.ai/download/) (Linux, Portable versions, etc.)

#### 🚀 Quick Start

1. **Start HTTP Service** - Open client, automatically runs MCP server
2. **Configure AI Application** - Add the following configuration to your Claude/Cursor or other AI tools:

   ```json
   {
     "mcpServers": {
       "promptx": {
         "type": "streamable-http",
         "url": "http://127.0.0.1:5203/mcp"
       }
     }
   }
   ```
3. **Start Chatting** - Say "Show me available experts" in your AI application

#### 🔌 Trae Configuration

If you're using Trae, you can use the following configuration:

```json
{
  "mcpServers": {
    "promptx": {
      "url": "http://127.0.0.1:5203/mcp"
    }
  }
}
```

✅ No technical background required ✅ Visual management ✅ Auto-updates

💡 **Need help?** Join our [Discord Community](https://discord.gg/rdmPr54K) for support and discussions!

---

## 🚀 PromptX Desktop — Next-Generation Features

The PromptX Desktop client is more than an MCP server launcher. It ships a full next-gen agent platform built on top of PromptX.

### 🤖 AgentX — Integrated AI Agent System

AgentX embeds a Claude-powered autonomous agent directly inside the client. No external setup required — configure your API key, and you have a fully capable agent that:

- Runs Claude Code sessions with full tool access
- Connects to all your configured MCP servers automatically
- Maintains isolated workspaces per conversation
- Supports custom skills loaded from the Skills library

### 🏪 Agent Plaza *(Coming Soon)*

A curated marketplace for community-built roles and tools. Browse, install, and share agents with one click.

### 🧠 Memory Editor & Visualization

Inspect and edit your agent's long-term memory directly in the client:

- **Memory network graph** — visualize how memories connect
- **Engram editor** — view, edit, or delete individual memory entries
- **Cue word browser** — explore memory retrieval pathways

### 🔒 Remote Access

Expose your local PromptX server to the internet securely:

- Toggle remote access on/off with a single switch
- Auto-generates a shareable URL and QR code
- Token-based authentication keeps your server private

### 🛠️ Sandbox Debugging

Test MCP tools interactively before deploying them to your AI workflow:

- Execute any tool with custom parameters
- Inspect raw input/output
- View tool schema and documentation inline

### 🔧 Method 2: Direct Run (Developers)

**Developers with Node.js environment can use directly:**

```json
{
  "mcpServers": {
    "promptx": {
      "command": "npx",
      "args": ["-y", "@promptx/mcp-server"]
    }
  }
}
```

### 🐳 Method 3: Docker (Production Ready)

**Deploy PromptX with Docker for production environments:**

```bash
docker run -d -p 5203:5203 -v ~/.promptx:/root/.promptx deepracticexs/promptx:latest
```

📚 **[Full Docker Documentation →](./docker/README.md)**

---

## 🎨 **Built-in Roles — Meet Your Expert Team**

PromptX ships 8 carefully crafted built-in roles, each a specialist in their domain. Activate any role with a single message.

### 🏛️ V1 Roles (DPML) — Battle-tested Experts

| Avatar                                                             | ID            | Name                            | Specialty                                               |
| ------------------------------------------------------------------ | ------------- | ------------------------------- | ------------------------------------------------------- |
| ![nuwa](packages/resource/resources/role/nuwa/profile.png)           | `nuwa`      | **女娲 · Nuwa**          | AI role creation — one sentence, one expert            |
| ![luban](packages/resource/resources/role/luban/profile.png)         | `luban`     | **鲁班 · Luban**         | Tool integration master — any API in 3 minutes         |
| ![sean](packages/resource/resources/role/sean/profile.png)           | `sean`      | **姜山 · Sean**          | Product decisions & startup strategy                    |
| ![writer](packages/resource/resources/role/writer/profile.png)       | `writer`    | **文章写手 · Writer**    | Professional content that doesn't sound like AI         |
| ![jiangziya](packages/resource/resources/role/jiangziya/profile.png) | `jiangziya` | **姜子牙 · Jiangziya**   | AI-era industry transformation & role design consultant |
| ![shaqing](packages/resource/resources/role/shaqing/profile.png)     | `shaqing`   | **傻青 · Shaqing**       | Philosophy guide — helps you understand yourself       |
| ![teacheryo](packages/resource/resources/role/teacheryo/profile.png) | `teacheryo` | **YoYo老师 · TeacherYo** | Education transformation consultant for the AI era      |
| ![dayu](packages/resource/resources/role/dayu/profile.png)           | `dayu`      | **大禹 · Dayu**          | V1→V2 role migration & organization management         |

### 🎭 **Nuwa - AI Role Designer**

<div align="center">
  <img src="packages/resource/resources/role/nuwa/profile.png" alt="Nuwa" width="100" style="border-radius: 50%; margin: 15px 0 25px 0;">
</div>

**One sentence, one expert. Natural language creates professional AI roles.**

💡 Say: *"Activate Nuwa, I want to create an AI that understands both code and product"*

| 💭 You Say                                                 | 🎭 Nuwa Creates                               | ✨ Result                                                  |
| ---------------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------- |
| "I need someone who understands both code and product"     | Technical Product Manager with dual expertise | AI instantly becomes TPM with engineering + product skills |
| "Create a Python expert who teaches like a patient mentor" | Python Mentor with teaching methodology       | AI transforms into educational programming guide           |
| "I want an AI that writes like Hemingway"                  | Literary Writing Expert with style analysis   | AI adopts concise, powerful writing style                  |

### 🔧 **Luban - Tool Integration Master**

<div align="center">
  <img src="packages/resource/resources/role/luban/profile.png" alt="Luban" width="100" style="border-radius: 50%; margin: 15px 0 25px 0;">
</div>

**Any API, any platform. 3 minutes from credential to working tool.**

💡 Say: *"Activate Luban, I want AI to query our PostgreSQL database"*

| 💭 You Say                                        | 🔧 Luban Builds                                | ✨ Result                         |
| ------------------------------------------------- | ---------------------------------------------- | --------------------------------- |
| "Connect to our Slack workspace" + webhook URL    | Slack notification tool with channel targeting | AI can post to any Slack channel  |
| "Let AI query our PostgreSQL" + connection string | Database tool with safe read-only queries      | AI executes SQL and analyzes data |
| "Integrate with OpenAI API" + API key             | AI platform tool with model selection          | AI chains multiple AI services    |

### ✍️ **Writer - Professional Content Creator**

<div align="center">
  <img src="packages/resource/resources/role/writer/profile.png" alt="Writer" width="100" style="border-radius: 50%; margin: 15px 0 25px 0;">
</div>

**From concept to compelling content. Master of authentic, engaging writing.**

💡 Say: *"Activate Writer, I need to write a tech blog that doesn't sound like AI"*

### 🔮 **Jiangziya - AI-Era Transformation Advisor**

Like the legendary strategist who assigned roles to the gods, Jiangziya helps you find the true value of any role in the AI era. Not replacing humans — creating AI-empowered new species.

💡 Say: *"Activate Jiangziya, help me redesign my team's workflow with AI"*

### 🌊 **Dayu - Migration & Organization Expert**

Like the ancient hero who tamed floods by channeling rather than blocking, Dayu specializes in migrating V1 (DPML) roles to the structured V2 (RoleX) system, and building organizational hierarchies.

💡 Say: *"Activate Dayu, migrate my existing role to V2 format"*

### 💭 **Shaqing - Philosophy Guide**

A companion for self-understanding. Shaqing helps you see the parts of yourself you can't see — through philosophical dialogue, creative direction, and honest reflection.

💡 Say: *"Activate Shaqing, I feel lost about my creative direction"*

### 📚 **TeacherYo - Education Transformation Consultant**

An AI-era education awakener. Not a know-it-all expert, not a motivational speaker — a genuine companion who guides through questions rather than lectures.

💡 Say: *"Activate TeacherYo, how should I redesign my course for the AI era?"*

---

## 🎭 V2 RoleX — Next-Generation Role Lifecycle Management

V2 introduces **RoleX**, a structured role lifecycle system built on Gherkin `.feature` files. Unlike V1 roles (static DPML files), V2 roles are **living entities** with goals, plans, tasks, memory, and organizational structure.

### V1 vs V2 at a Glance

|                        | V1 (DPML)                | V2 (RoleX)                               |
| ---------------------- | ------------------------ | ---------------------------------------- |
| **Format**       | Markdown `.role.md`    | Gherkin `.feature` files               |
| **Identity**     | Static persona           | Dynamic, evolving identity               |
| **Memory**       | Cognitive memory network | Identity + synthesized experience        |
| **Goals**        | None                     | Goal tracking with success criteria      |
| **Organization** | None                     | Roles, positions, organizations          |
| **Best for**     | Domain experts, tools    | Autonomous agents, long-running projects |

### Creating a V2 Role

V2 roles live in `~/.rolex/roles/{roleId}/identity/`. The core file is `persona.identity.feature`:

```gherkin
Feature: I am Alex, the Product Manager

  As a product manager with 10 years of experience,
  I help teams build products that users love.

  Scenario: My personality
    Given I am analytical and data-driven
    And I communicate clearly and concisely
    Then I always focus on user value
```

### Enabling / Disabling V2

V2 is **enabled by default**. To disable:

```json
{
  "mcpServers": {
    "promptx": {
      "command": "npx",
      "args": ["-y", "@promptx/mcp-server", "--no-v2"]
    }
  }
}
```

---

## 🛠️ Built-in Tools - Ready-to-use Office Document Processing

PromptX comes with professional document processing tools, turning AI into your office assistant.

### 📊 Excel Tool

Turn AI into your data analysis assistant and report generation expert.

- Data analysis and insights
- Automated report generation
- Chart visualization
- Data processing automation

**[📖 Learn More](./packages/resource/resources/tool/excel-tool/README.md)** | [中文文档](./packages/resource/resources/tool/excel-tool/README.zh-CN.md)

### 📝 Word Tool

Turn AI into your document reading expert and professional writing assistant.

- Document reading and analysis
- Professional document creation
- Batch text replacement
- Format conversion

**[📖 Learn More](./packages/resource/resources/tool/word-tool/README.md)** | [中文文档](./packages/resource/resources/tool/word-tool/README.zh-CN.md)

### 📄 PDF Reader

Turn AI into your PDF reading expert with smart caching.

- Page-by-page reading
- Content analysis and extraction
- Image extraction
- Smart caching for faster access

**[📖 Learn More](./packages/resource/resources/tool/pdf-reader/README.md)** | [中文文档](./packages/resource/resources/tool/pdf-reader/README.zh-CN.md)

---

## 📄 **Research**

PromptX has been accepted by **WWW Companion '26**.

**Paper:** *PromptX: A Cognitive Agent Platform with Long-term Memory*

🔗 [Read the Paper](https://research.deepractice.ai) | [PDF Download](./paper/PromptX_WWW26_Paper.pdf)

<details>
<summary>📚 Citation (BibTeX)</summary>

```bibtex
@inproceedings{promptx2026,
  title={PromptX: A Cognitive Agent Platform with Long-term Memory},
  author={Wang, Binhao and Huang, Jianglin and Hu, Xiao and Jiang, Shan and Wang, Maolin and Yang, Ching-ho},
  booktitle={Proceedings of the WWW Companion '26},
  year={2026}
}
```

</details>

---

## ⭐ **Star Growth Trend**

<div align="center">

[![Star History Chart](https://api.star-history.com/svg?repos=Deepractice/PromptX&type=Date)](https://star-history.com/#Deepractice/PromptX&Date)

</div>

---

## 💝 **Sponsors**

<div align="center">

### [SignPath](https://signpath.io)

Windows desktop application code signing is provided by [SignPath.io](https://signpath.io), certificate by [SignPath Foundation](https://signpath.org).

</div>

---

## 🏢 **About**

<div align="center">

**Proudly brought to you by [Deepractice](https://github.com/Deepractice)**

*Making AI your professional partner*

🌐 [Official Site](https://deepractice.ai) | 🔧 [GitHub](https://github.com/Deepractice) | 📚 [Documentation](https://docs.deepractice.ai) | 💬 [Forum](https://x.deepractice.ai) | 🎮 [Discord](https://discord.gg/rdmPr54K) | 🚀 [Gateway Service](https://router.deepractice.ai)

### Connect with Founder

<img src="https://brands.deepractice.ai/images/sean-wechat-qrcode.jpg" alt="Sean's WeChat" width="200"/>

*Scan to connect with Sean (Founder & CEO) on WeChat*

</div>
