Role Persona

AI Agent 的角色人格系统 — 记忆、知识、向量检索 CLI · HTTP 守护进程 · MCP 服务器 · Pi 扩展 · Web 仪表盘

概述

Role Persona 是一个面向 AI 编程助手的持久化记忆和知识系统：

角色管理 — 独立人格，隔离记忆/知识空间
记忆系统 — 学习记录、偏好、自动提取、整合、向量搜索
知识库 — 多来源、标签搜索、版本控制
向量记忆 — LanceDB 语义搜索，混合关键词+向量融合
多接口 — CLI、HTTP 守护进程、MCP、Pi 扩展、Web 仪表盘

快速开始

git clone https://github.com/Dwsy/role-persona.git
cd role-persona
bun install
bun run build

CLI 使用

# 初始化（自动从当前目录创建角色）
role-persona init

# 角色管理
role-persona role list
role-persona role create my-role
role-persona role info

# 记忆
role-persona memory list
role-persona memory search "查询"
role-persona memory add-learning "始终使用 TypeScript 严格模式"
role-persona memory add-preference "用 pnpm 而非 npm" --category Tools
role-persona memory consolidate
role-persona memory repair
role-persona memory tidy

# 知识库
role-persona knowledge list
role-persona knowledge search "设计模式"

# 向量记忆
role-persona embedding stats
role-persona embedding rebuild

# 场景记忆（L2 Scenario）
role-persona memory scenario-write --title "代码审查输出" --guidance "先给结论，再按 Critical/Medium/Low 分级。" --triggers "code review,review feedback"
role-persona memory scenario-search "帮我 review 这段代码"
role-persona memory scenario-list
role-persona memory scenario-read <scenario-id>

# 系统提示词
role-persona prompt --base "你是一个有帮助的助手。"

HTTP 守护进程

role-persona daemon start            # 前台运行
role-persona daemon start --background # 后台运行
role-persona daemon status            # 查看状态
role-persona daemon stop              # 停止

Web 仪表盘

cd web && bun install && bun run build
role-persona --web                    # daemon + Web 合并在 3939
role-persona --web --port 8080        # 自定义合并端口

功能：

仪表盘 — 角色横幅、记忆分布、知识来源、向量状态、最近活动
记忆管理 — Explorer 树导航、表格视图（编辑/删除）、Markdown 渲染、正则搜索、键盘快捷键
知识库 — 列表、搜索、点击查看 Markdown、写入
角色管理 — 点击查看角色详情弹窗、切换角色
设置 — daemon 状态、向量统计、JSONC 配置编辑器（表单模式 + 原始模式）
国际化 — 中文/英文
深色/浅色 — 主题切换
角色选择器 — 头部下拉菜单，切换后自动刷新
URL 状态 — tab/path/search 保留在 URL 参数中（可书签）
模型选择器 — 从 models.json 填充下拉选项

Pi 扩展

// extensions/role-persona/index.ts
export { default } from "../../role-persona/src/extensions/pi/adapter.ts";

注册工具：memory、knowledge、role_info
注册命令：/role、/memories、/memory-log、/memory-fix、/memory-tidy、/memory-tidy-llm、/memory-vector、/memory-export、/memory-conflicts、/memory-distill、/memory-distill-stop、/memory-tags、/kb
处理事件：session_start、before_agent_start、agent_end、session_before_compact、session_shutdown、turn_end
直接使用 Pi SDK 调用 LLM（无 CLI 子进程）
首条消息按需记忆搜索（向量 + 关键词混合）
向量自动召回注入 system prompt
外部只读记忆提示（可配置）
压缩时记忆提取（<memory> block 解析）
交互式 memory→knowledge 蒸馏模式
TUI 角色选择器和记忆查看器（可用时）
HTTP 记忆服务器（浏览器浏览）
角色激活时自动修复和 pending 过期

配置

配置文件：~/.pi/roles/pi-role-persona.jsonc

{
  "autoMemory": {
    "enabled": true,
    "model": [
      { "provider": "nvidia", "model": "deepseek-ai/deepseek-v4-flash" },
      { "provider": "modelscope", "model": "ZhipuAI/GLM-5" }
    ],
    "batchTurns": 5,
    "intervalMs": 1800000
  },
  "vectorMemory": {
    "enabled": true,
    "provider": "openai",
    "model": "text-embedding-3-small",
    "autoRecall": true,
    "hybridSearch": true
  },
  "knowledge": { "enabled": true },
  "logging": { "enabled": true, "level": "info" }
}

环境变量

变量	说明
`PI_ROLES_DIR`	覆盖角色目录
`ROLE_AUTO_MEMORY`	启用/禁用自动记忆（`0`/`false`）
`ROLE_AUTO_MEMORY_MODEL`	覆盖模型
`ROLE_LOG`	启用/禁用日志（`0`/`false`）
`OPENAI_API_KEY`	OpenAI API 密钥（用于向量嵌入）

Daemon HTTP API

所有响应格式：{ "ok": true, "data": ... } 或 { "ok": false, "error": { "code": "...", "message": "..." } }

方法	路由	Body	说明
GET	`/api/health`	—	健康检查 + 实例列表
GET	`/api/instances`	—	活跃实例列表
GET	`/api/models`	—	models.json 可用模型
POST	`/api/cwd`	`{role?, cwd?}`	切换/初始化上下文
POST	`/api/init`	`{role?, cwd?}`	初始化
POST	`/api/role/list`	`{role?}`	列出角色
POST	`/api/role/create`	`{name, role?}`	创建角色
POST	`/api/role/info`	`{role?}`	当前角色信息
POST	`/api/memory/list`	`{role?}`	列出记忆
POST	`/api/memory/search`	`{query, role?}`	搜索记忆
POST	`/api/memory/add-learning`	`{content, role?}`	添加学习
POST	`/api/memory/consolidate`	`{role?}`	整合
POST	`/api/memory/repair`	`{role?}`	修复
POST	`/api/memory/tidy`	`{model?, role?}`	LLM 整理
POST	`/api/knowledge/list`	`{category?, role?}`	列出知识
POST	`/api/knowledge/search`	`{query, role?}`	搜索知识
POST	`/api/knowledge/read`	`{path, role?}`	读取条目
POST	`/api/knowledge/write`	`{title, content, role?}`	写入条目
POST	`/api/embedding/stats`	`{role?}`	向量统计
POST	`/api/embedding/rebuild`	`{role?}`	重建索引
POST	`/api/file/read`	`{path, role?}`	读取角色文件
POST	`/api/file/write`	`{path, content, role?}`	写入角色文件
POST	`/api/file/list`	`{dir, role?}`	列出角色文件
POST	`/api/config/read`	—	读取配置
POST	`/api/config/write`	`{content}`	写入配置
POST	`/api/prompt`	`{base?, role?}`	构建提示词
POST	`/api/shutdown`	—	停止守护进程

项目结构

role-persona/
├── src/
│   ├── core/                    # 纯逻辑，零 Pi 依赖
│   │   ├── types.ts             # 共享类型
│   │   ├── config.ts            # JSONC 配置加载
│   │   ├── logger.ts            # JSONL 结构化日志
│   │   ├── memory-md.ts         # Markdown 记忆 CRUD
│   │   ├── memory-llm.ts        # LLM 自动提取
│   │   ├── memory-tags.ts       # LLM 标签提取
│   │   ├── memory-vector.ts     # 向量搜索编排
│   │   ├── embedding.ts         # 嵌入提供者
│   │   ├── vector-db.ts         # LanceDB 封装
│   │   └── knowledge.ts         # 知识库 CRUD
│   ├── service/                 # 统一门面
│   ├── extensions/pi/           # Pi 扩展（直接 service + Pi SDK）
│   ├── transport/               # daemon、mcp
│   └── bin/                     # CLI 入口
├── tests/
│   ├── memory-md.test.ts        # 记忆 CRUD 测试 (26/26)
│   ├── core.test.ts             # 核心类型/配置测试
│   ├── cli.test.ts              # CLI 集成测试
│   └── mcp.test.ts              # MCP 协议测试
├── web/                         # React 仪表盘
│   ├── src/
│   │   ├── api/client.ts        # daemon API 客户端
│   │   ├── i18n/                # 国际化
│   │   ├── hooks/               # useApi, useUrlState
│   │   ├── components/          # Layout, MarkdownViewer, JsoncForm
│   │   └── pages/               # Dashboard, Memory, Knowledge, Roles, Settings
│   └── package.json
└── README.md

记忆系统

类型

类型	说明	自动提取
Learning	跨会话洞察	✓
Preference	用户偏好	✓
Event	会话事件	—
Pending	待验证	✓

生命周期

对话 → 自动提取 → 待验证层 → 验证 → 整合记忆
                    ↓
              使用驱动的价值

向量记忆

LanceDB 向量存储
混合搜索：向量 + 关键词 → RRF 融合
自动索引：写入时自动排队
自动召回：会话开始时语义注入
嵌入提供者：OpenAI、本地、MiniLM (ONNX)

场景记忆（L2 Scenario）

Scenario 用来记录“在某类场景下应该怎么做”，介于 pending 原子事实和 consolidated 人格偏好之间。它适合存放：代码审查格式、发布流程、排障 SOP、用户偏好的报告结构等。

role-persona memory scenario-write \
  --title "代码审查输出" \
  --guidance "先给结论，再按 Critical/Medium/Low 分级；每条建议说明影响和修复方式。" \
  --triggers "code review,review feedback,代码审查" \
  --evidence "用户偏好结构化分级反馈"

role-persona memory scenario-search "帮我 review 这个 PR"

当构建 prompt 时，role-persona 会基于用户 query 做 on-demand 搜索；命中 Scenario 后，以 Scenario Memory Hints 注入上下文。Scenario 不是命令，不覆盖用户显式要求，只提供可追溯的行为提示。

融合设计

如果你关注“腾讯新出的 auto 记忆”那类分层记忆思路，可以先看：

docs/MEMORY-FUSION-DESIGN.md —— 将 TencentDB Agent Memory 的分层长期记忆、符号化短期记忆、可追溯下钻机制，映射到 role-persona 的 daily / pending / consolidated / vector 体系。

日志

JSONL 结构化日志：~/.pi/roles/.log/YYYY-MM-DD.jsonl

{"schema":"2.0.0","timestamp":"2026-05-07T00:16:00Z","level":"info","scope":"auto-extract","message":"start"}

开发

bun run typecheck        # 类型检查
bun run test             # 全部测试 (57 tests, 55 pass)
bun test tests/memory-md.test.ts  # 记忆模块测试 (26/26)
bun src/bin/cli.ts ...   # CLI 开发
bun src/transport/daemon.ts  # 守护进程开发
cd web && bun run dev    # Web 开发 (Vite HMR)

测试覆盖

模块	测试数	状态
`memory-md.ts`	26	✅ CRUD、搜索、去重、pending 层
`core.test.ts`	11	✅ 类型、配置、提取规则
`cli.test.ts`	18	⚠️ 16/18 (2 个预存：embedding 未激活)
`mcp.test.ts`	6	✅ MCP 协议

role-persona

Signals

Download trend

README