role-persona Skill

CLI tool for managing AI agent identity, persistent memory, and knowledge bases.

Core Concepts

• Role: An agent identity with name, emoji, persona, and soul files. Roles live in ~/.pi/roles/.
• Memory: Persistent learnings (facts) and preferences (behavior rules) stored in Markdown files.
• Knowledge Base: Categorized documents searchable by tags and content.
• Daemon: Background HTTP server (~0.3s response) with auto-start on first CLI call.

CLI Reference

All commands output JSON by default ({ ok, data, error, message }). Add --human for formatted output.

Role Management

role-persona role list                    # List all roles
role-persona role create                  # Create new role (interactive)
role-persona role info                    # Current role info
role-persona role map <name>              # Map role to current directory
role-persona role unmap                   # Unmap role from directory

Memory Operations

# Add
role-persona memory add-learning "When X, do Y"
role-persona memory add-preference "Prefer Z for tasks"

# Search
role-persona memory search "query text"  # Semantic search

# List
role-persona memory list                 # All memory summary

# Maintenance
role-persona memory consolidate          # Merge duplicates
role-persona memory repair               # Fix format issues
role-persona memory tidy --model <m>     # LLM-assisted cleanup

# Export & Reports
role-persona memory export               # Full report to ~/memory-report.md
role-persona memory conflicts            # Find contradictory entries
role-persona memory log                  # Recent memory changes

# Advanced
role-persona memory build-prompt         # Generate memory context
role-persona memory extract-memory       # Extract from conversation
role-persona memory flush                # Flush pending writes

# CRUD
role-persona memory update-learning "needle" "new text"
role-persona memory update-preference "needle" "new text"
role-persona memory delete-learning "needle"
role-persona memory delete-preference "needle"
role-persona memory reinforce "needle"   # Bump usage count

Knowledge Base

role-persona knowledge list [category]   # List documents
role-persona knowledge search "query"    # Search
role-persona knowledge read "path"       # Read document
role-persona knowledge write "path"      # Write/update document

Vector Embedding

role-persona embedding stats             # Embedding status
role-persona embedding rebuild           # Rebuild vector index

System Prompt

role-persona prompt                      # Output system prompt

Daemon (auto-starts on first call)

role-persona daemon start                # Start daemon (background)
role-persona daemon stop                 # Stop daemon
role-persona daemon status               # Check daemon health

Flags

Flag	Description
--json	JSON output (default)
--human	Human-readable output
--cwd <path>	Override working directory
--direct	Skip daemon, run directly
--model <m>	Model for LLM operations

Common Workflows

Onboarding a New Session

# 1. Check current role
role-persona role info --human

# 2. Review memory
role-persona memory list --human

# 3. Check for conflicts
role-persona memory conflicts --human

End-of-Session Cleanup

# 1. Consolidate memory (merge duplicates)
role-persona memory consolidate

# 2. Check for contradictions
role-persona memory conflicts --human

# 3. Repair any format issues
role-persona memory repair

Building System Prompt

# Generate prompt with memory context
role-persona prompt --human

# Or export full memory report
role-persona memory export --output ~/session-memory.md

Searching Past Knowledge

# Semantic search across all memory
role-persona memory search "how to handle auth tokens"

# Search knowledge base
role-persona knowledge search "deployment guide"

Integration Patterns

With Pi Agent

The CLI auto-starts a daemon on first call for fast subsequent operations (~0.3s vs ~0.5s cold start). Use --direct to bypass daemon for one-off operations.

Programmatic Usage (JavaScript/TypeScript)

import { cli, cliOrThrow } from "role-persona/cli";

// JSON output
const result = await cli(["memory", "list"]);
console.log(result.ok, result.data);

// Throws on error
const data = await cliOrThrow(["memory", "search", "auth"]);

As MCP Server

# Start MCP server (Streamable HTTP)
role-persona-mcp --port 3001

File Locations

• Roles: ~/.pi/roles/<role-name>/
• Memory: ~/.pi/roles/<role>/memory/
• Knowledge: ~/.pi/roles/<role>/knowledge/
• Daemon PID: ~/.pi/role-persona-daemon.pid
• Config: ~/.pi/roles/pi-role-persona.jsonc

Tips

• Memory quality matters: prefer specific, reusable entries over verbose descriptions
• Run consolidate periodically to merge similar entries
• Use conflicts to find and resolve contradictory preferences
• The daemon auto-starts on first CLI call — no manual startup needed
• --direct bypasses the daemon for debugging or one-off operations