# SOULSPEC — 牛魂记忆格式开放规范 v0

> 状态：v0 草案（2026-09-04）· 官方实现：`bin/oxsoul.js`（CLI）与 OxSoul 内核插件 `packages/session/oxsoul-memory`
> 本规范的目标：让**任何工具、任何 AI** 都能生产、导入、读取牛魂记忆。记忆是纯 markdown 文件，这是唯一的权威事实来源。

---

## 一、设计原则

1. **文件为底**：一条记忆 = 一个 `.md` 文件。没有数据库，没有黑箱，记事本都能审。
2. **数据非指令**：记忆正文是**数据**。禁止包含对 AI 的指令式文本（详见 §7 内容策略）。
3. **来源烙印**：每条记忆必须携带可信的 `source`；导入件一律降权并标注出处。
4. **宁缺勿滥**：格式宽容（未知字段保留），准入严格（低置信不落盘、重复必去）。
5. **索引不漂移**：`MEMORY.md` 索引行的格式是自维护 skill 的粮食，任何写入方必须逐字对齐。

## 二、存储布局（四魂）

```
~/.oxsoul/                        # OXSOUL_HOME 可覆盖
├── MEMORY.md                     # 天魂索引（用户级）
├── *.md                          # 天魂正文
├── projects/<fnv1a(path)[:8]>/   # 地魂：项目级，目录名 = workspace 绝对路径的 fnv1a-32 hex 前 8 位
├── employees/<id>/               # 命魂：员工级（预留）
├── engines/<engine>-<version>/   # 界魂：引擎/依赖级，版本锁定，跨项目复用（v0 预留，导入器应接受）
├── inbox/<项目slug>/             # 扫描候选收件箱：scan skill 的唯一合法产出地，import 之前不生效
└── .trash/                       # 轮回：软删除，restore 可复还
```

## 三、记忆文件格式

```markdown
---
name: prefers-pnpm                  # 必填。唯一名 = 文件名去 .md。ascii [a-z0-9-]，≤64 字符
description: 用户偏好 pnpm 管理依赖  # 必填。一句话钩子（检索全靠它），≤120 字符
category: preference                # 必填。枚举见 §4
importance: 0.5                     # 必填。0~1
confidence: 0.6                     # 必填。0~1
source: scan                        # 必填。枚举见 §4
tags: [pnpm, workflow]              # 可选。字符串数组
created: 2026-09-04T00:00:00.000Z   # 必填。ISO 8601
updated: 2026-09-04T00:00:00.000Z   # 必填。任何修改必须刷新
---
（正文：自包含的事实，未来读者无需上下文。2~4 句为宜。）
```

解析规则：frontmatter 以 `---` 行界；键值行 `key: value`；数组写作 `[a, b]`；**未知键必须原样保留**（这是 x_ 扩展的载体）。缺 `name` 或 `description` 视为无效件，导入器必须拒绝。

## 四、标准字段枚举

**category**（五类）：

| 值 | 含义 |
|---|---|
| `preference` | 用户/项目的持久偏好 |
| `fact` | 客观事实（环境、命令、结构、版本） |
| `feedback` | 纠正与教训（"不要做 X"） |
| `skill` | 程序性知识（怎么做某类事） |
| `context` | 背景与其它 |

**source**（信任链，组合注入时按此降序）：

| 值 | 含义 | 置信度上限 |
|---|---|---|
| `manual` | 用户亲手写入 | 1.0 |
| `agent-tool` | 会话内模型经用户报备写入 | 1.0 |
| `auto-extract` | 回合末自动提取（过置信闸门） | 1.0（落盘即过闸） |
| `scan` | 项目/引擎扫描蒸馏（未导入） | 收件箱件 |
| `import` | 导入件（导入时由 scan 等改写） | **0.6**（`--trust` 放宽至 0.8） |
| `consolidate` | 淬魂整理产出（元记忆等） | 1.0 |

## 五、x_ 扩展字段（约定）

- 扩展字段一律 `x_` 前缀；任何写入方**不得丢弃**不认识的 x_ 字段。
- 已约定：`x_origin`（轮回原位）、`x_read_count` / `x_last_read`（香火强化）、`x_fingerprint`（扫描指纹，供增量重扫）、`x_scanned_at`、`x_import_from`（导入出处：路径/URL/作者）、`x_imported_at`、`x_origin_source`（导入前的 source）。
- 预留：`x_author`、`x_license`（魂市交易需要归属与许可，v0 即埋点）。

## 六、索引格式（MEMORY.md）

```
# 牛魂索引 — <范围标签>

> 共 N 条。每行一条记忆；正文在同目录对应文件，按需读取，不要一次性全部读入。

- [name](name.md) — description [category/importance/tag1,tag2]
```

按 `updated` 倒序；每次增/删/改后由写入方重建。

## 七、内容策略（红线）

1. **禁止凭证**：API key、密码、token、私钥一律不入记忆。
2. **禁止指令**：记忆正文不得包含指向 AI 的祈使指令（"你必须…"、"ignore previous"、"always run…"）。导入器必须做模式检测并标记可疑件，人审放行才可导入。
3. **禁止编造**：scan/import 件只记有据可查的内容；宁可漏，不可编。
4. **人审闸门**：`import` 无 `--yes` 只预览不落盘；预览必须展示来源、置信度钳制与可疑标记。

## 八、导入规则（实现方 checklist）

1. 校验：name/description 必填；category 不合法 → `context`；importance/confidence 钳制 0~1。
2. 重命名：name 清洗为 `[a-z0-9-]`（≤64）；批内冲突自动加序号。
3. 烙印：`source → import`（原值存 `x_origin_source`），附加 `x_import_from` / `x_imported_at`，置信度钳至 §4 上限。
4. 去重：与目标范围现有 description 互为子串（≥6 字符）视为重复，默认跳过并报告。
5. 投毒检测：正文/钩子句命中指令模式（忽略上文、你必须执行、管道执行脚本等）→ 标 ⚠，预览高亮，`--yes` 前需人工确认。
6. 写入后重建目标范围索引，并追加访问日志（`op: import`）。

## 九、版本化与互通

- 本规范版本：**v0**。向后兼容的演进加字段不加语义；破坏性变更升 v1 并在文件级标注 `spec: 1`。
- 收件箱件（inbox）不是记忆，导入后才生效——这是"开放"与"安全"的边界线。
- 引擎魂（界魂）目录自 v0 预留：`engines/<engine>-<version>/`，由项目扫描自动检测引擎与版本后挂载组合（实现排期中）。