beamuswayne--simp-skill/docs/MEM-SYS.md

Mem-Sys 实现规划书

分支：Mem-Sys | 创建于 2026-04-12

一、现状分析

现有文件结构：

crushes/{slug}/
├── profile.md      ← 纯 Markdown 散文，无结构化字段，Claude 读写靠理解
├── strategy.md     ← 同上
├── meta.json       ← 有结构，但字段稀疏（仅 stage、score、mode）
├── memories/chats/ ← 原始聊天记录
└── versions/       ← 手动备份，不自动维护

核心问题：

1. profile.md 没有 YAML frontmatter，Claude 无法可靠提取/更新单个字段
2. 没有"当前状态快照"，每次 /simp progress 都要重新推断阶段
3. 没有事件日志，历史演变不可追溯，/simp quit 无法看"感情轨迹"
4. versions/ 是手动备份，不是真正的历史记录

---

二、新文件结构

crushes/{slug}/
├── profile.md       # 【升级】稳定层 — YAML frontmatter + 叙述体
├── state.md         # 【新增】动态层 — 当前快照，每次会话后覆盖
├── events.jsonl     # 【新增】事件流 — 只追加，永不删除
├── strategy.md      # 【保留】追求策略（不动）
├── meta.json        # 【扩展】元数据，新增索引字段
├── memories/
│   ├── chats/
│   ├── social/
│   └── photos/
└── snapshots/       # 【新增】定期快照目录
    └── YYYY-MM-DD.json

读取优先级（context window 分配）：

文件	加载时机	预估 tokens
profile.md	每次必读	~300
state.md	每次必读	~200
events.jsonl 最近5条	progress/analyze/quit	~150
strategy.md	message/confess/analyze	~400
events.jsonl 全部	用户明确要求回顾时	按需

---

三、文件 Schema 定义

3.1 profile.md（稳定层）

---
nickname: 小雨
slug: xiaoyu
gender: 女
age: 23
occupation: 设计师
city: 上海
mbti: ENFP
zodiac: 双鱼
personality_type: 感性型
how_met: 同学介绍
created_at: "2026-04-10"
---

## 性格画像
ta 话很多，喜欢用颜文字，情绪外露，容易被细节打动。
见面时会不自觉靠近，但如果感觉被冷落会直接不回消息。

## 最打动ta的方式
具体的画面感 > 泛泛的夸奖。说"你刚才皱眉的样子"比"你很可爱"更有效。

## 用户自身风格
说话偏幽默，短句为主，偶尔用表情包，追求混合模式。

## 注意事项
ta 对"套路感"敏感，一旦感觉被设计会直接拉远距离。

规则：

• YAML frontmatter 存结构化字段，Claude 更新时用字段名精确修改
• 正文存叙述性内容，只追加，不覆盖
• personality_type 枚举值：感性型 | 理性型 | 傲娇型 | 温柔型

---

3.2 state.md（动态层）

---
current_stage: 暧昧期
signal_score: 17
last_signal_score: 14
score_trend: up
recommended_mode: 混合
last_updated: "2026-04-12T10:30:00"
milestones_done: 7
---

## 当前状态（一句话）
关系持续升温，ta 开始主动制造见面机会。

## 最近信号（最新3条）
- 🟢 2026-04-11 ta 主动问周末有没有空
- 🟢 2026-04-10 深夜发了消息说"突然想到你"
- 🟡 2026-04-08 回复比往常慢了一些

## 当前策略方向
暧昧期推进：制造1v1心跳时刻，评估表白时机是否成熟。

## 下一步建议
本周制造一次晚间1v1见面，用 /simp message 准备好开场话题。

规则：

• 每次 /simp analyze、/simp progress 结束后全量覆盖
• score_trend 枚举：up | down | stable
• current_stage 枚举：破冰期 | 升温期 | 暧昧期 | 表白前 | 表白后-成功 | 表白后-被拒 | 友谊区 | 重启期

---

3.3 events.jsonl（事件流）

每行一个独立 JSON 对象，严格只追加：

{"ts":"2026-04-10T14:00:00","v":1,"type":"profile_created","slug":"xiaoyu","data":{"nickname":"小雨","personality_type":"感性型"}}
{"ts":"2026-04-11T20:30:00","v":1,"type":"signal_recorded","slug":"xiaoyu","data":{"direction":"green","content":"深夜主动发消息说突然想到你","score_delta":3}}
{"ts":"2026-04-12T10:30:00","v":1,"type":"stage_changed","slug":"xiaoyu","data":{"from":"升温期","to":"暧昧期","trigger":"连续3天主动联系 + 深夜消息"}}
{"ts":"2026-04-12T10:30:00","v":1,"type":"analysis_done","slug":"xiaoyu","data":{"score":17,"stage":"暧昧期","summary":"ta 主动性明显增强，信号偏绿"}}

事件类型字典：

type	触发指令	data 必填字段
profile_created	/simp create	nickname, personality_type
profile_updated	/simp update	field, old_value, new_value
stage_changed	analyze/progress	from, to, trigger
signal_recorded	/simp analyze	direction(green/red/neutral), content, score_delta
analysis_done	/simp analyze	score, stage, summary
progress_evaluated	/simp progress	score, stage, milestones_done, next_actions
strategy_updated	阶段变化时	old_stage, new_stage, reason
crisis_handled	/simp crisis	crisis_type, resolution
quit_evaluated	/simp quit	verdict(continue/reconsider/let_go), reason
confess_prepared	/simp confess	method, readiness_score

---

3.4 meta.json（扩展）

{
  "slug": "xiaoyu",
  "nickname": "小雨",
  "created_at": "2026-04-10T14:00:00",
  "updated_at": "2026-04-12T10:30:00",
  "version": "v1",
  "current_stage": "暧昧期",
  "signal_score": 17,
  "mode": "hybrid",
  "event_count": 4,
  "last_snapshot": "2026-04-12"
}

新增字段：nickname（用于 list 展示）、event_count（快速统计）、last_snapshot

---

四、每条指令的 Memory Protocol

指令               读取                    写入
─────────────────────────────────────────────────────────
/simp create      无                      profile.md(新建)
                                          state.md(空模板)
                                          events.jsonl(新建)
                                          meta.json(新建)

/simp analyze     profile.md              state.md(覆盖)
                  state.md                events.jsonl(追加:
                                           signal_recorded
                                           analysis_done
                                           stage_changed 若变化)

/simp message     profile.md              无
                  state.md
                  strategy.md

/simp progress    profile.md              state.md(覆盖)
                  state.md                events.jsonl(追加:
                  events.jsonl 最近5条      progress_evaluated)
                                          meta.json(更新score/stage)

/simp update      profile.md              profile.md(更新frontmatter)
                                          events.jsonl(追加:
                                           profile_updated)

/simp confess     profile.md              events.jsonl(追加:
                  state.md                 confess_prepared)
                  strategy.md

/simp crisis      profile.md              state.md(更新状态)
                  state.md                events.jsonl(追加:
                                           crisis_handled)

/simp daily       state.md 仅此           无

/simp quit        profile.md              events.jsonl(追加:
                  state.md                 quit_evaluated)
                  events.jsonl 全部

/simp list        meta.json(所有slug)     无

---

五、新增 Python 工具：tools/memory.py

5.1 模块职责

memory.py 是记忆系统的唯一入口，skill_writer.py 调用它，Claude 通过 shell 调用它。

5.2 CLI 接口

# 追加事件
python3 tools/memory.py append <slug> <event_type> '<json_data>'

# 读取最近N条事件
python3 tools/memory.py events <slug> --last 5

# 读取当前上下文（profile.md + state.md 合并输出）
python3 tools/memory.py context <slug>

# 从事件流重建 state.md
python3 tools/memory.py rebuild <slug>

# 生成日快照
python3 tools/memory.py snapshot <slug>

# 查看事件时间线
python3 tools/memory.py timeline <slug>

5.3 核心函数签名

def append_event(
    slug: str,
    event_type: str,
    data: dict,
    base_dir: Path = DEFAULT_BASE_DIR
) -> None:
    """追加一条事件到 events.jsonl，同时更新 meta.json 的 event_count"""

def get_recent_events(
    slug: str,
    n: int = 5,
    event_types: list[str] | None = None,
    base_dir: Path = DEFAULT_BASE_DIR
) -> list[dict]:
    """返回最近 N 条事件，可按 type 过滤"""

def load_context(
    slug: str,
    include_strategy: bool = False,
    base_dir: Path = DEFAULT_BASE_DIR
) -> str:
    """拼装 profile.md + state.md，供 Claude 直接注入 context"""

def update_state(
    slug: str,
    frontmatter_updates: dict,
    sections: dict[str, str],
    base_dir: Path = DEFAULT_BASE_DIR
) -> None:
    """全量覆盖 state.md，frontmatter_updates 更新 YAML 字段"""

def take_snapshot(
    slug: str,
    base_dir: Path = DEFAULT_BASE_DIR
) -> Path:
    """将 meta.json + state.md frontmatter 合并写入 snapshots/YYYY-MM-DD.json"""

def rebuild_state_from_events(
    slug: str,
    base_dir: Path = DEFAULT_BASE_DIR
) -> dict:
    """从 events.jsonl 重放，返回推断的当前状态（用于校验或恢复）"""

---

六、skill_writer.py 改动

init_crush() 新增三步：

1. 在 profile.md 模板顶部加 YAML frontmatter
2. 创建 state.md（空模板）
3. 创建 events.jsonl（空文件）
4. 创建 snapshots/ 目录
5. meta.json 新增 nickname、event_count: 0、last_snapshot: null 字段

backup_crush() 扩展：同步备份 state.md（events.jsonl 不备份，它是不可变历史）。

update_meta() 扩展：支持更新 nickname、event_count、last_snapshot。

---

七、SKILL.md 改动（Phase 3）

在「运行规则」之前新增「记忆操作协议」章节，定义每条指令的读写规则。

---

八、实施步骤

Phase 1：Schema 落地（基础）✅

• 更新 init_crush() — 新增 state.md、events.jsonl、snapshots/ 的创建
• 更新 profile.md 模板 — 加 YAML frontmatter
• 扩展 meta.json schema — 新增字段
• 更新测试

Phase 2：memory.py 工具 ✅

• 实现 append_event()
• 实现 get_recent_events()
• 实现 update_state()
• 实现 load_context()
• 实现 take_snapshot()
• 实现 rebuild_state_from_events()
• CLI 入口
• 测试覆盖（见 tests/test_memory.py）

Phase 3：SKILL.md 集成 ✅

• 新增「记忆操作协议」章节
• 每条指令补充 Memory Protocol 说明
• progress_tracker.md 更新读取路径

Phase 4：迁移工具 · ❌ 不再计划

早期阶段无存量用户档案，迁移工具的实际价值低于维护成本。新档案统一通过 init_crush() 创建，已自带 YAML frontmatter / state.md / events.jsonl，无需迁移。若未来出现存量数据需要升级，再单独立项。

---

九、测试计划

tests/
├── test_skill_writer.py   # 已有，补充新字段断言 ✅
└── test_memory.py         # 新增（Phase 2）✅

---

十、一句话原则备忘

文件	一句话规则
profile.md	只增不减，YAML 字段可更新，正文只追加
state.md	代表"现在"，每次全量覆盖
events.jsonl	代表"历史"，只追加，永不删除
strategy.md	阶段变化时更新，其他时候只读
snapshots/	每日自动生成，用于跨会话快速恢复