role-persona 是一个命令行工具，用于管理 AI 智能体的身份（角色）、持久记忆和知识库。角色包含名称、emoji、persona 与 soul 文件，存放在 ~/.pi/roles/ 下；记忆分为学习（事实）与偏好（行为规则），以 Markdown 文件保存；知识库为可按标签和内容检索的分类文档。首次调用 CLI 会自动启动后台 HTTP 守护进程，后续操作响应约 0.3 秒，可用 --direct 跳过守护进程。
主要能力：角色管理（list、create、info、map、unmap）；记忆操作（add-learning、add-preference、search 语义搜索、list、consolidate 合并重复、repair 修复格式、tidy、export、conflicts 查找矛盾、log、build-prompt、extract-memory、flush，以及 update/delete/reinforce 等 CRUD）；知识库（list、search、read、write）；向量嵌入（embedding stats、rebuild）；系统提示输出（prompt）；守护进程（start、stop、status）。命令默认输出 JSON（{ ok, data, error, message }），加 --human 输出可读格式。
使用方式：通过命令行调用上述子命令，常用标志包括 --json、--human、--cwd <path>、--direct、--model <m>。也可在 JavaScript/TypeScript 中通过 import { cli, cliOrThrow } from "role-persona/cli" 编程调用，或以 MCP 服务器方式运行：role-persona-mcp --port 3001。文件位置包括角色目录、记忆目录、知识目录、守护进程 PID 文件及配置文件 ~/.pi/roles/pi-role-persona.jsonc。
适用场景：为智能体维护跨会话的身份与记忆、检索历史知识、生成带记忆上下文的系统提示、整理和检测记忆冲突。限制：资料未提供具体模型依赖、性能上限、收费或平台支持等细节，暂未提供。