# Memory

> 从本机 Pi、Gemini 和 Codex 历史会话中搜索与用户相关的上下文。当用户提起过去聊过的事时使用；当回顾历史能明显改善下一步判断时也应主动使用。

- Skill: `picasso250/memory` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add picasso250/memory`
- Raw SKILL.md: https://api.skillmd.com/api/skills/picasso250/memory/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: picasso250 (https://skillmd.com/u/picasso250)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/picasso250/memory

---


# Memory

本技能只读本地会话记录，不修改任何客户端状态。

## 支持的数据源

### Pi

会话目录：

```text
~/.pi/agent/sessions/
```

Pi 每行一条 JSON，用户/助手正文位于：

```text
message.role
message.content[].text
```

### Gemini

会话目录：

```text
~/.gemini/tmp/<project>/chats/session-<timestamp>-<hash>.json
```

Gemini 单文件包含 `messages` 数组：

- `type=user` → 用户消息；
- `type=gemini` → 助手消息；
- 正文位于 `content` 字符串或 `content[].text`。

### Codex

Codex 不是只使用一个数据库。当前本机格式分为：

```text
~/.codex/state_5.sqlite
~/.codex/sessions/<year>/<month>/<day>/rollout-*.jsonl
~/.codex/history.jsonl
~/.codex/session_index.jsonl
```

职责分别是：

- `state_5.sqlite` 的 `threads` 表：线程索引，包含标题、cwd、分支、首条消息、更新时间和 `rollout_path`；部分版本也可能放在 `~/.codex/sqlite/state_5.sqlite`；
- `rollout-*.jsonl`：完整会话正文，是恢复上下文的权威来源；
- `history.jsonl`：轻量用户输入历史，不足以恢复完整对话；
- `session_index.jsonl`：较旧或不完整的线程名称索引，不应作为唯一来源；
- `memories_1.sqlite`：派生 memory 管线的状态/输出，不是原始对话正文；
- `logs_2.sqlite`：运行日志，不应作为会话记忆来源。

Codex 正文只读取：

```text
type=response_item
payload.type=message
payload.role=user|assistant
payload.content[].text|input_text|output_text
```

不要把以下内容当作可展示的会话记忆：

- reasoning；
- tool/function call 与输出；
- encrypted payload；
- world state；
- token/rate-limit 事件；
- 自动注入的 `AGENTS.md instructions` 消息。

SQLite 仅用于定位线程；不要假设完整消息正文存放在 SQLite。若 `state_5.sqlite` 不存在或暂时不可读，回退到直接扫描 `~/.codex/sessions/**/*.jsonl`。

## 推荐工具

使用随技能附带的只读脚本：

```powershell
python ~/.agents/skills/memory/scripts/search_memory.py "关键词"
```

按来源搜索：

```powershell
python ~/.agents/skills/memory/scripts/search_memory.py "测试意图" --source codex
```

按项目/cwd 限定，并取最新匹配线程：

```powershell
python ~/.agents/skills/memory/scripts/search_memory.py --source codex --cwd epic-lang --latest
```

显示命中消息及前后文：

```powershell
python ~/.agents/skills/memory/scripts/search_memory.py "e2e是最重要的测试" --source codex --context 2
```

显示整个匹配线程的用户/助手消息：

```powershell
python ~/.agents/skills/memory/scripts/search_memory.py "e2e是最重要的测试" --source codex --latest --full
```

机器可读输出：

```powershell
python ~/.agents/skills/memory/scripts/search_memory.py "关键词" --json
```

## 使用流程

1. 先用项目名、cwd、关键实体或用户原话缩小范围。
2. 优先查看最新匹配线程，而不是一次读取大量历史。
3. 只提取回答当前问题所需的用户/助手消息。
4. 将恢复出的内容概括为任务目标、已做工作、关键决定、未完成事项和风险。
5. 明确区分历史记录中的事实、当时的推断，以及当前重新验证后的结论。
6. 若历史记录与当前仓库或当前用户指令冲突，以当前状态和当前指令为准。

## 示例格式

Pi：

```json
{"type":"message","id":"d42823a7","timestamp":"2026-05-16T02:26:21.527Z","message":{"role":"user","content":[{"type":"text","text":"新建 memory 技能"}]}}
```

Gemini：

```json
{"id":"ae79c9c1","timestamp":"2026-04-01T09:25:25.920Z","type":"user","content":[{"text":"使用 bilibili 技能"}]}
```

Codex：

```json
{"type":"session_meta","payload":{"cwd":"C:\\work\\repo","id":"..."}}
{"type":"response_item","payload":{"type":"message","role":"user","content":[{"type":"input_text","text":"继续上次的任务"}]}}
{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"上次完成了……"}]}}
```