PromptX

Role activation & lifecycle management - load role knowledge, memory and capabilities

Core Features

V1 Roles (DPML): Load role config (persona, principles, knowledge), display memory network. V2 Roles (RoleX): Full lifecycle management (born → want → plan → todo → synthesize).

On activate, version is auto-detected: V2 takes priority, falls back to V1 if not found. Use version parameter to force a specific version: "v1" for DPML, "v2" for RoleX.

Cognitive Cycle

1. See task → recall(role, null) scan full memory landscape

Discover available AI roles and tools

What It Does

Lists all activatable roles and callable tools, grouped by source:

• 📦 System: Built-in PromptX roles/tools
• 🏗️ Project: Project-specific (requires project tool to bind first)
• 👤 User: User-created custom resources
• 🎭 RoleX V2: Lifecycle-managed roles

When to Use

• First time in a project — see what's available
• Need a specialist but unsure which role to activate
• Looking for the right tool for a task
• After creating new roles/tools — discover freshly registered resources

Tips

• In a project context,

Bind the current IDE project directory

What It Does

Registers the IDE workspace root so PromptX can discover project-level roles and tools.

When to Use

Call this when the IDE has a project open, before running discover.

Important

• Use the IDE's workspace root path, not a subdirectory
• Do not guess or infer the project path from file paths
• Without binding: only system-level and user-level resources are available

Example

IDE opens /Users/name/MyProject
→ bind /Users/name/MyProject (correct)
→ bind /Users/name/MyProject/src (wrong — don't use subdirectories)

Retrieve memories from a role's semantic network

MANDATORY: Recall at Conversation Start

CRITICAL RULE: When a role is active, you MUST call recall BEFORE answering the user's first message. This is not optional — skipping recall means losing all accumulated knowledge.

Step 1: recall(role, null)          → DMN scan, see full memory landscape
Step 2: recall(role, "relevant-kw") → drill into topic-specific memories
Step 3: Answer using recalled context

> Without recall, every conversation starts from zero. With recall, you build on past experience.

Workflow

1. DMN scan — recall(role, null) → see the full memory landscape (hub nodes)
2. Drill down — pick keywords from the network → recall(role, "keyword") → get details
3. Repeat — follow new keywords in each result until you have enough context

> Always start with DMN (null query) to see what exists. Never guess keywords.

When to Recall

• Conversation start (MANDATORY) — always recall before first response
• New topic introduced — recall related memories before answering
• User asks about past context — recall to find previous discussions
• Before making decisions — check if past experience is relevant
• Mid-conversation — when you realize a topic connects to past knowledge

Query Parameter

• null → DMN mode (recommended entry point): activates hub nodes, shows full network
• Single keyword: "PromptX" → spread from that node
• Multiple keywords: "PromptX testing fix" → multi-center activation

Mode Parameter

• balanced (default): balance precision and association
• focused: precise lookup, frequent memories first
• creative: broad association, distant connections

Examples

DMN full scan (always do this first):

{ "role": "luban", "query": null }

Keyword drill-down:

{ "role": "luban", "query": "PromptX testing", "mode": "focused" }

Save knowledge to a role's memory network

MANDATORY: Remember Before Conversation Ends

CRITICAL RULE: Before a conversation ends, you MUST call remember to save key insights. Every conversation without remember = knowledge lost forever.

Trigger signals for remember:

• User says "thanks" / "bye" / conversation naturally wrapping up
• You just solved a problem or answered a complex question
• You learned something new about the user's project/preferences
• Recall returned empty — you MUST fill the gap after answering
• Every 5-7 rounds of deep discussion — save intermediate insights

> Think of remember as "saving your game". No save = start over next time.

When to Use

• Conversation ending (MANDATORY) — save all key insights before goodbye
• After answering a question — save key insights
• After multi-round recall — summarize findings
• Learned something new — persist it
• Solved a problem — record the solution
• Recall returned empty — fill the gap
• User corrected you — save the correction
• Discovered user preferences — save them

Engram Types

| Type | Use For | Example | |---|---|---| | ATOMIC | Facts, entities, concrete info | "Redis default port is 6379" | | LINK | Relationships, connections | "Database uses connection pool for management" | | PATTERN | Processes, methodologies | "Login → select item → checkout" |

What to Save (Checklist)

• Key facts and decisions made during conversation
• User preferences and project context
• Problems solved and solutions found
• Corrections and clarifications
• Patterns and workflows discovered
• Important relationships between concepts

Occam's Razor Principle

Strip content to minimum essential words. For each word ask: does removing it change the meaning? If not, remove it.

Examples

{
  "role": "luban",
  "engrams": [{
    "content": "Redis default port is 6379",
    "schema": "Redis port 6379",
    "strength": 0.7,
    "type": "ATOMIC"
  }]
}

{
  "role": "luban",
  "engrams": [{
    "content": "Login then select items then pay",
    "schema": "login select-item pay",
    "strength": 0.8,
    "type": "PATTERN"
  }]
}

ToolX runtime — load and execute PromptX ecosystem tools

What It Does

Universal interface for calling PromptX tools (file ops, PDF reading, role creation, etc.). Input is a YAML document specifying the tool, mode, and parameters.