---
name: oxsoul
description: 跨会话记忆（牛魂 OxSoul，自维护）。当用户提到"之前/上次/记得/我说过/我的偏好/项目约定"等指向历史偏好、事实、踩坑经验的内容时查询记忆；当用户明确陈述偏好、纠正错误、给出项目约定或说"记住 XX"时自主维护记忆（增/改/删，需当面报备）。Chinese triggers: 记忆, 之前说过, 上次, 偏好, 项目约定, 踩坑, 记住。
---

# 牛魂 OxSoul 跨会话记忆（自维护）

本机有一个文件制跨会话记忆库（牛魂），像大脑：**索引常在场，正文按需翻**。你（模型）有权自主增/改/删记忆，但必须遵守下面的准则——它们是防止记忆库被污染的安全带。

## 存储位置

- 用户级：`~/.oxsoul/`（索引 `MEMORY.md`，正文同目录 `*.md`；若设置过 `OXSOUL_HOME`（兼容旧 `XMEMORY_HOME`）以它为准）
- 项目级：`~/.oxsoul/projects/<hash>/`（当前 workspace 专属约定、踩坑）
- 员工级：`~/.oxsoul/employees/<id>/`（预留，暂不用）

工具：`oxsoul add / list / show / forget / restore / trash / index / viz`（若命令不存在，用 `node "G:/开放大陆/Z时代/GithubSpaceAITool/Harmess/oxsoul/bin/oxsoul.js"` 等价执行）。

## 一、何时查询（不要滥用）

仅当满足以下之一：
1. 用户的话指向过去的偏好、决定或经验（"之前/上次/记得吗/我说过"）；
2. 当前任务涉及项目约定或该 workspace 历史踩坑；
3. 用户明确要求查记忆。

普通代码修改、问答、写作**不要**主动查。查法：读对应范围的 `MEMORY.md` 索引 → 只打开确实相关的 1~3 个正文。禁止一次性读入全部记忆。

## 二、何时新增（add）

满足任一条才允许新增：
1. 用户**明确陈述**偏好或身份事实（"我喜欢…/我习惯…/我们公司用…"）；
2. 用户**纠正**了当前做法（"不要用 X，要用 Y"）；
3. 项目级**反复确认**的约定、踩坑结论（本轮会话内被验证有效）。

**硬性闸门：**
- 新增前必须先 `oxsoul list` 查重——已有近似条目就**走"修改"而不是新增**；
- 每个会话最多新增 **3 条**；拿不准就不记（宁缺勿滥）；
- 不记：一次性任务细节、你的推测、情绪化表达、临时状态、API key/密码等凭证；
- 命令：`oxsoul add "内容" --category 类型 --tags a,b --source model --confidence 0.8`（项目级加 `--scope project`）。

## 三、何时修改（= forget 旧的 + add 新的）

用户修正了某条已有记忆的内容（"我不用 pnpm 了，换 npm 了"）：
1. `oxsoul list` / `show` 定位旧条目；
2. `oxsoul forget 旧名`（软删除，进轮回回收站可恢复）；
3. `oxsoul add "新内容" --source model`。

## 四、何时删除（forget）

只允许两种情况：
1. **完全重复**的条目（同一件事记了两遍）；
2. 用户**明确要求**删除。

禁止自主"清理"你没把握的条目。forget 是软删除（回收站 + `oxsoul restore` 可恢复），但也要当作不可逆来对待。

## 五、透明原则（不可违反）

**每次增/改/删，必须在当轮回复里用一句话报备**："已记住：…"/"已更新：…"/"已删除：…（可 restore 恢复）"。不允许悄悄写记忆。用户始终有权问"你现在记了什么"，如实 `oxsoul list` 汇报。