pi-mono 使用建议与最佳实践

pi-mono 记忆系统适用场景、不适用场景、最佳实践和未来演进预测

5.1 适用场景

✅ 强烈推荐

场景 1：个人开发者日常编码

特征：

单人项目或小团队协作（<5 人）
需要跨会话连续性
偏好终端工作流

收益：

JSONL 文件便于备份和版本控制
--continue 快速恢复上下文
AGENTS.md 记录项目规范

配置建议：

# 全局配置
~/.pi/agent/agents.md

# 项目配置
<project>/.pi/agents.md

场景 2：多模型实验

特征：

需要对比不同模型表现
预算敏感，需精确追踪成本
可能需要切换开源/闭源模型

收益：

跨模型上下文传递
精确 per-message 成本追踪
无厂商锁定

使用示例：

# 从 Claude 开始
pi --model claude-sonnet-4-5

# 中途切换到 GPT
/settings model openai/gpt-5.1-codex

# 上下文自动传递

场景 3：教学与学习

特征：

需要检查 AI 决策过程
可能回看历史对话
希望理解 Agent 行为

收益：

JSONL 可直接阅读
树状分支展示不同尝试
完整成本透明

⚠️ 推荐使用（需扩展）

场景 4：中长期项目（1-6 个月）

特征：

项目周期长
记忆条目可能过万
需要快速检索历史决策

挑战：

线性扫描性能下降
无智能遗忘机制

解决方案：

// 扩展：向量检索
await vectorStore.add(entry)

// 扩展：时间衰减
const weight = calculateDecayWeight(entry)

场景 5：知识密集型任务

特征：

大量领域知识需要记忆
需要跨项目知识复用
频繁检索历史经验

挑战：

JSONL 无语义检索
知识组织靠手动

解决方案：

开发记忆检索工具
结合外部知识库
定期手动整理 AGENTS.md

❌ 不推荐

场景 6：企业级多团队协作

原因：

无多用户支持
无共享记忆机制
无权限管理

替代方案：Mem0、Letta

场景 7：需要高级记忆功能

原因：

无内置向量检索
无自动分类
无重要性评分

替代方案：Mem0（内置）或 pi-mono + 大量扩展

场景 8：IDE 重度用户

原因：

CLI 工作流与 IDE 割裂
无代码自动索引
无侧边栏集成

替代方案：Cursor

5.2 不适用场景详细分析

限制 1：大规模记忆检索

问题：当会话超过 10,000 条消息时

记忆条数 | 加载时间 | 建议
---------|---------|-------
<1,000   | <50ms   | ✅ 无问题
1,000-5,000 | <200ms | ⚠️ 可接受
5,000-10,000 | <500ms | ⚠️ 考虑压缩
>10,000  | >1s     | ❌ 需向量检索

缓解措施：

定期手动压缩旧会话
使用 --branch 拆分主题
开发增量加载扩展

限制 2：跨项目知识共享

问题：pi-mono 会话隔离在项目维度

项目 A/                  项目 B/
  └─ sessions/             └─ sessions/
      └─ session.jsonl         └─ session.jsonl
      
# 无法直接访问对方记忆

缓解措施：

手动导出/导入 JSONL
开发跨项目检索工具
使用全局 AGENTS.md 记录通用知识

限制 3：实时协作

问题：无并发控制

用户 1 ──┐
         ├──> 同一 JSONL 文件 ← 冲突！
用户 2 ──┘

替代方案：

使用 Git 管理 JSONL（手动合并）
考虑云端方案（Mem0）

5.3 最佳实践

实践 1：AGENTS.md 分层管理

# 全局 ~/.pi/agent/agents.md

## 编码规范
- 使用 TypeScript
- 优先使用函数式编程
- 所有函数添加 JSDoc

## 个人偏好
- 详细注释
- 错误处理优先

# 项目 <project>/.pi/agents.md

## 项目架构
- 分层：controller/service/repository
- 数据库：PostgreSQL + Prisma

## 当前任务
- [x] 实现 JWT 认证
- [ ] 添加刷新令牌
- [ ] 编写单元测试

好处：

全局规范 + 项目特定分离
新会话自动加载上下文
便于维护

实践 2：定期会话整理

# 每周执行
# 1. 查看本周所有会话
pi --list --since "1 week ago"

# 2. 导出重要会话
cp ~/.pi/agent/sessions/.../session.jsonl ./backups/

# 3. 删除临时会话
pi --delete <session-id>

实践 3：分支探索策略

# 开始新功能
pi --branch --summary "开始实现 OAuth 功能"

# 遇到问题，尝试方案 A
pi "用 Authorization Code 流"
# ... 实现 ...

# 不理想，回溯
pi --goto <分支点>

# 尝试方案 B
pi --branch --summary "改用 PKCE 流"

实践 4：成本监控

# 每日检查
pi --stats --today

# 周报告
pi --stats --since "1 week ago" --group-by day

# 异常检测
# 设置阈值告警（需扩展）

实践 5：扩展开发指南

最小可行扩展：

// extensions/simple-memory/src/index.ts
export async function activate(context: ExtensionContext) {
  // 1. 监听消息
  context.agent.on('message', (entry) => {
    console.log('Message:', entry.message.role)
  })
  
  // 2. 添加工具
  context.agent.tools.push({
    name: 'hello',
    description: 'Say hello',
    parameters: Type.Object({}),
    execute: async () => ({
      output: 'Hello from extension!'
    })
  })
}

发布扩展：

# 打包
pi package build

# 发布到 npm
npm publish

# 安装
pi install npm:@my/simple-memory

5.4 未来演进预测

短期（2026 Q2-Q3）

预测功能：

内置向量检索（可选）
- 轻量级嵌入式向量库
- 无需外部依赖
智能压缩
- 基于重要性而非仅时间
- 保留关键决策
改进的分支 UI
- TUI 树状可视化
- 一键切换分支

置信度：70%

中期（2026 Q4-2027 Q1）