@smyslenny/agent-memory 4.2.0 → 4.3.1

package/docs/design/0016-v41-warm-boot-surface-emotion.md

@@ -1,228 +0,0 @@
-# DD-0016: AgentMemory v4.1 — Warm Boot + Surface CLI + Emotion Tags
-
-**Status:** Approved
-**Author:** Noah
-**Date:** 2026-03-10
-**Repo:** /tmp/agent-memory-dd
-
----
-
-## 1. Background / 背景
-
-v4.0 完成了核心重构（向量检索、语义去重、HTTP API、文档泛化），但缺少三个常被请求的能力：
-
-1. `boot` 只返回 JSON 数组——agent 醒来没有"记忆的温度"。
-2. 没有 CLI 命令直接输出 Markdown 用于 `RECENT.md` 自动注入。
-3. emotion 类型记忆只有 `emotion_val` 数值，没有可检索的情感标签。
-
-这三个功能共享一些底层改动（列记忆时的分层过滤、schema 升级、MCP/CLI 参数扩展），适合合在一个 DD 里做。
-
-## 2. Goals / 目标
-
-- G1: `boot` 支持 `format=narrative`，输出分层叙事 Markdown（纯模板，不依赖 LLM）
-- G2: 新增 `agent-memory surface` CLI 命令，输出 Markdown 并支持 `--out FILE`
-- G3: memories 表新增 `emotion_tag TEXT` 列（schema v6），贯通 remember/recall/surface/MCP/CLI
-
-## 3. Non-Goals / 非目标
-
-- 不做 LLM 驱动的叙事生成
-- 不做自动关联（links 自动建边留 v4.2）
-- 不改 surface 的评分公式
-- 不做统一搜索入口（qmd + recall 合并留后续）
-
-## 4. Proposal / 方案
-
-### 4.1 Feature 1: Warm Boot
-
-**改动文件：** `src/sleep/boot.ts`, `src/mcp/server.ts`, `src/bin/agent-memory.ts`
-
-#### 接口变更
-
-```typescript
-export interface WarmBootOptions {
-  agent_id?: string;
-  corePaths?: string[];
-  format?: "json" | "narrative";  // 新增，默认 "json"
-  agent_name?: string;            // narrative 模板用，默认 "Agent"
-}
-
-export interface WarmBootResult extends BootResult {
-  narrative?: string;  // format=narrative 时填充
-}
-```
-
-#### 分层拉取策略
-
-| 层 | 类型 | 拉取策略 | Markdown 标题 |
-|----|------|----------|-------------|
-| 核心身份 | identity (P0) | 全部 | `## 我是谁` |
-| 近期情感 | emotion (P1) | 最近 5 条 by updated_at | `## 最近的心情` |
-| 近期事件 | event (P3) | 最近 7 条 by updated_at | `## 最近发生的事` |
-| 鲜活知识 | knowledge (P2) | vitality > 0.5, top 10 | `## 还记得的知识` |
-
-#### 时间格式化
-
-```typescript
-function relativeTime(isoDate: string): string {
-  const diffMs = Date.now() - new Date(isoDate).getTime();
-  const diffDays = Math.floor(diffMs / 86_400_000);
-  if (diffDays === 0) return "今天";
-  if (diffDays === 1) return "昨天";
-  if (diffDays <= 7) return `${diffDays}天前`;
-  return isoDate.slice(0, 10);  // YYYY-MM-DD
-}
-```
-
-#### Narrative 模板
-
-```markdown
-# {agent_name}的回忆
-
-## 我是谁
-- {identity_content_1}
-- {identity_content_2}
-
-## 最近的心情
-- {emotion_content} ({emotion_tag}, {relative_time})
-
-## 最近发生的事
-- {event_content} ({relative_time})
-
-## 还记得的知识
-- {knowledge_content}
-```
-
-emotion 条目如果有 `emotion_tag` 则显示 `(标签, 时间)`，否则只显示 `(时间)`。
-
-#### MCP / CLI
-
-- MCP `boot` tool: 新增 `format` 参数（枚举 `json|narrative`）和 `agent_name` 参数
-- CLI: `agent-memory boot --format narrative --agent-name Noah`
-
-### 4.2 Feature 2: Surface CLI Command
-
-**改动文件：** `src/bin/agent-memory.ts`（主要），复用 `src/app/surface.ts` 里已有的 `surfaceMemories()`
-
-#### CLI 接口
-
-```bash
-agent-memory surface [--out FILE] [--days N] [--limit N] [--min-vitality F] [--types T1,T2]
-```
-
-| 参数 | 默认值 | 说明 |
-|------|--------|------|
-| `--out` | stdout | 输出到文件路径 |
-| `--days` | 7 | 时间窗口（天）|
-| `--limit` | 50 | 最大条目数 |
-| `--min-vitality` | 0.1 | vitality 下限 |
-| `--types` | 全部 | 逗号分隔的类型过滤 |
-
-#### 输出 Markdown 格式
-
-```markdown
-# Recent Memories
-
-> Auto-generated by AgentMemory surface. Last updated: {ISO_DATE}
-
-## Identity
-- {content} (vitality: {v})
-
-## Emotion
-- {content} ({emotion_tag}, {relative_time})
-
-## Knowledge
-- {content} ({relative_time}, vitality: {v})
-
-## Events
-- {content} ({relative_time})
-```
-
-按 type 分组，每组内按 score 降序。需要先构造一个 surface 调用——使用 `task: "context loading"` + `intent: "temporal"` 作为默认参数。
-
-**对于 `--days` 过滤：** surface 本身不支持时间窗口，在 surface 返回后按 `memory.updated_at` 过滤。
-
-#### MCP tool
-
-MCP 也新增 `surface` tool（当前只有 HTTP endpoint）：
-- 参数：`days`, `limit`, `min_vitality`, `types`, `format` (`json|markdown`)
-- `json` 返回现有 SurfaceResponse
-- `markdown` 返回格式化的 Markdown 文本
-
-### 4.3 Feature 3: Emotion Tags
-
-**改动文件：** `src/core/db.ts` (schema), `src/core/memory.ts` (CRUD), `src/app/remember.ts`, `src/app/recall.ts`, `src/app/surface.ts`, `src/mcp/server.ts`, `src/bin/agent-memory.ts`, `src/transports/http.ts`
-
-#### Schema v6 迁移
-
-```sql
-ALTER TABLE memories ADD COLUMN emotion_tag TEXT;
-```
-
-- 向后兼容，不破坏已有数据
-- `SCHEMA_VERSION` 从 5 → 6
-- 迁移逻辑加在 `initDatabase()` 的 migration 链里
-
-#### Memory 接口扩展
-
-```typescript
-export interface Memory {
-  // ... existing fields ...
-  emotion_tag: string | null;  // 新增
-}
-
-export interface CreateMemoryInput {
-  // ... existing fields ...
-  emotion_tag?: string;  // 新增
-}
-```
-
-#### 过滤支持
-
-- `listMemories()`: 新增可选 `emotion_tag` 过滤
-- `searchBM25()`: 不变（emotion_tag 不进 FTS）
-- `surfaceMemories()`: SurfaceInput 新增可选 `emotion_tag` 过滤
-- `recall`: RecallInput 新增可选 `emotion_tag` 过滤
-
-#### MCP / CLI / HTTP
-
-- MCP `remember`: 新增 `emotion_tag` 参数
-- MCP `recall`: 新增 `emotion_tag` 过滤参数
-- CLI `remember`: 新增 `--emotion-tag` 选项
-- CLI `recall`: 新增 `--emotion-tag` 过滤选项
-- HTTP POST `/v1/memories`: body 接受 `emotion_tag`
-- HTTP POST `/v1/recall`: body 接受 `emotion_tag` 过滤
-- HTTP POST `/v1/surface`: body 接受 `emotion_tag` 过滤
-
-## 5. Risks / 风险
-
-| 风险 | 影响 | 缓解措施 |
-|------|------|----------|
-| Schema 迁移失败 | DB 无法打开 | ALTER TABLE ADD COLUMN 是 SQLite 最安全的迁移之一，只追加不修改 |
-| narrative 模板过长 | 上下文爆炸 | identity 全取但 content 截断到 200 字；其他层有 limit |
-| surface CLI 慢（大 DB） | 超时 | 利用已有 BM25/vitality 索引，结果限制到 50 条 |
-
-## 6. Test Plan / 测试方案
-
-- [ ] `tests/sleep/boot.test.ts`: narrative format 输出、分层拉取正确性、时间格式化、空 DB 边界
-- [ ] `tests/app/surface-cli.test.ts` 或合并到已有 surface 测试: surface markdown 输出格式、--days 过滤、--out 文件写入
-- [ ] `tests/core/db.test.ts`: schema v5→v6 迁移、emotion_tag 写入/读取
-- [ ] `tests/core/memory.test.ts`: CreateMemoryInput 带 emotion_tag、listMemories 按 emotion_tag 过滤
-- [ ] `tests/app/recall.test.ts`: recall 按 emotion_tag 过滤
-- [ ] `tests/app/surface.test.ts`: surface 按 emotion_tag 过滤
-- [ ] 手动验证: `agent-memory boot --format narrative` + `agent-memory surface --out /tmp/test.md`
-
-## 7. Rollback Plan / 回滚方案
-
-- Schema v6 只追加列，不删不改，回滚到 v5 代码时 `emotion_tag` 列被忽略
-- narrative boot 是新参数，默认 format=json 不影响已有行为
-- surface CLI 是新命令，不影响已有命令
-
-## 8. Decision Log / 决策变更记录
-
-| 日期 | 变更 | 原因 |
-|------|------|------|
-| | | |
-
----
-
-_Generated by DD workflow · Noah_

package/docs/design/TEMPLATE.md

@@ -1,67 +0,0 @@
-# DD-NNNN: <Title>
-
-**Status:** Draft | Review | Approved | Implemented | Deprecated
-**Author:** Noah (Claude Opus sub-agent)
-**Date:** YYYY-MM-DD
-**Repo:** <repo-root>
-
----
-
-## 1. Background / 背景
-
-_为什么要做这件事？当前的问题是什么？_
-
-## 2. Goals / 目标
-
-- Goal 1
-- Goal 2
-
-## 3. Non-Goals / 非目标
-
-- 明确不做什么
-
-## 4. Proposal / 方案
-
-### 4.1 方案概述
-
-_核心设计思路_
-
-### 4.2 方案对比（如适用）
-
-| 维度 | 方案 A | 方案 B |
-|------|--------|--------|
-| 复杂度 | | |
-| 性能 | | |
-| 可维护性 | | |
-
-### 4.3 详细设计
-
-_API、数据结构、架构图等_
-
-## 5. Risks / 风险
-
-| 风险 | 影响 | 缓解措施 |
-|------|------|----------|
-| | | |
-
-## 6. Test Plan / 测试方案
-
-- [ ] Unit tests
-- [ ] Integration tests
-- [ ] Manual verification
-
-## 7. Rollback Plan / 回滚方案
-
-_如果出问题怎么办？_
-
-## 8. Decision Log / 决策变更记录
-
-_实现过程中如果偏离本文档，在此记录变更原因_
-
-| 日期 | 变更 | 原因 |
-|------|------|------|
-| | | |
-
----
-
-_Generated by DD workflow · Claude Opus sub-agent_

package/docs/roadmap/integration-plan-v1.md

@@ -1,139 +0,0 @@
-# Markdown × AgentMemory 融合方案（v1）
-
-> 目标：把「自动加载的 Markdown 记忆」和「可衰减/可搜索/可关联的 agent-memory」融合为一条轻量数据管线。
-> 
-> 核心原则：**Markdown 负责在场（可读/可编辑/自动注入）**；**agent-memory 负责智能（结构化/衰减/图谱/混合搜索）**。
-
----
-
-## 0. 我们到底要解决什么（非重复版）
-
-- 现在**醒来已有**：SOUL/USER/MEMORY.md 自动注入；daily notes 可读。
-- 但 agent-memory **不会自动参与**：它像“外挂脑子”，要手动 recall/remember。
-
-**真正缺口：**
-1) 自动捕获的数据只进 Markdown，不进 agent-memory → agent-memory 的衰减/向量/图谱能力用不上。
-2) agent-memory 的“新鲜记忆”不会浮到表面 → MEMORY.md 更新滞后。
-
-**因此 v1 的目标不是 Warm Boot，而是：**
-> **把 capture→consolidate→surface 这条链打通，让两边同一份事实。**
-
----
-
-## 1. 定位（Source of Truth）
-
-### v1 选择：Markdown 为主，agent-memory 为索引/智能层（派生）
-- Markdown：人类可读、可手动修正、OpenClaw 自动加载，是“对外呈现”。
-- agent-memory：从 Markdown/对话“同步得到”，提供搜索/衰减/关联/统计，是“对内智能”。
-
-> 这样最轻量：不改你现有的记忆工作流，只是让 agent-memory **跟着走**。
-
----
-
-## 2. 融合管线（v1）
-
-### Phase 1（P0）：打通数据流（最轻量，先做这个）
-
-#### 2.1 Capture：memory-sync 同步写入 agent-memory
-**改动点：**只改 OpenClaw cron `memory-sync` 的 prompt（不改 agent-memory 代码）。
-
-**做法：**
-- memory-sync 在“把新条目追加到 `memory/YYYY-MM-DD.md`”之后：
-  - 对每条“新增 bullet”同时调用：
-    - `mcporter call agent-memory.remember ...`
-  - 让 agent-memory 与日记增量保持一致。
-
-**推荐字段约定：**
-- `source`: `memory-sync:YYYY-MM-DD`
-- `uri`：
-  - event：`event://journal/YYYY-MM-DD#HHMM-N`
-  - emotion：`emotion://journal/YYYY-MM-DD#HHMM-N`
-  - knowledge：`knowledge://journal/YYYY-MM-DD#HHMM-N`
-
-**轻量分类规则（无需 LLM）：**
-- 包含“喜欢/讨厌/禁止/偏好/必须/记住”→ knowledge
-- 包含“开心/安心/难过/害羞/生气/担心/爱你/想你”→ emotion
-- 其余默认 event
-
-> 注意：memory-sync 本身已经是 LLM 任务；我们只是让它在写 Markdown 的同时，顺手把同一条写进 agent-memory。
-
-#### 2.2 Consolidate：memory-tidy 触发 agent-memory reflect
-**改动点：**在 `memory-tidy` cron 的收尾步骤追加：
-- `mcporter call agent-memory.reflect phase=all`
-
-目的：
-- 让衰减/治理与 Markdown 的“深度睡眠整理”同步发生。
-
-#### 2.3 Surface：生成一个“自动注入”的新文件（而不是 Warm Boot）
-**新增一个文件：** `RECENT.md`（或 `BOOT.md`）放在 workspace 根目录。
-
-**内容来源：**agent-memory 里“最近 7 天 + vitality 高”的记忆。
-
-**生成频率：**
-- 每次 memory-sync 结束生成一次（或每天 08:00 一次）
-
-**为什么要这个：**
-- 让 agent-memory 的“最新变化”进入自动上下文。
-- 不动 MEMORY.md 的 200 行硬上限；RECENT.md 专门放“最近”。
-
----
-
-## 3. 具体交付（v1）
-
-### 3.1 OpenClaw 侧（配置/cron）
-- [ ] patch `memory-sync` prompt：追加“新增 bullet → remember(含 type/uri/source)”
-- [ ] patch `memory-tidy` prompt：收尾 reflect
-- [ ] 新增 cron：`memory-surface`（或挂在 memory-sync 收尾）生成 `RECENT.md`
-
-### 3.2 agent-memory 侧（尽量少改）
-v1 **可以零代码**（cron 直接 mcporter remember + reflect）。
-
-但为了更干净，v1.1 可以加 2 个小命令（都很轻）：
-- [ ] `agent-memory surface --out RECENT.md --days 7 --limit 50`：输出 markdown
-- [ ] `agent-memory embed:missing`：批量补 embeddings（有 key 才跑）
-
----
-
-## 4. 验收标准（Definition of Done）
-
-1) 跑一次 memory-sync：
-- 日记新增条目数 = agent-memory 新增条目数（允许少量被 guard 去重）
-
-2) `RECENT.md` 自动更新：
-- 包含：最近情感/事件/偏好
-- 总长度受控（建议 <= 150 行）
-
-3) 多 agent 隔离：
-- 同一 DB 下不同 `AGENT_MEMORY_AGENT_ID` 不互相污染（已在 schema v2/v3 做到）
-
-4) 失败不炸：
-- mcporter 调用失败 → 只警告，不影响日记写入（best-effort）
-
----
-
-## 5. 风险与轻量化策略
-
-- **不引入新依赖**：v1 不加包。
-- **不新增新模型**：surface 纯模板拼接；分类用规则。
-- **不扩大上下文**：RECENT.md 受限行数 + 只放最近/高 vitality。
-- **不泄密**：sync 写入前做简单过滤（形如 `sk-` 的 token / 私钥头）直接拒写。
-
----
-
-## 6. v2（以后再说，不急）
-
-- 统一检索入口：qmd(memory_search) + agent-memory(recall) RRF 合并
-- 自动 links：新记忆写入后用相似度建“related”边
-- 情感标签体系：emotion_tag（安心/成就感/担心…）+ 趋势统计
-
----
-
-## 7. 需要小心拍板的 3 个选项
-
-1) `RECENT.md` 叫啥？（RECENT / BOOT / CONTEXT）
-2) surface 输出的窗口：7 天还是 3 天？默认 7 天更稳。
-3) memory-sync 同步时：一条 bullet 一条 memory？还是合并成一个块？（我建议 1:1，便于衰减和检索）
-
----
-
-_这版才是“结合起来”的轻量方案：不重复系统提示已有的记忆，而是把 agent-memory 的能力接进现有 cron，让它不再是孤岛。_

package/docs/roadmap/memory-architecture.md

@@ -1,168 +0,0 @@
-# 记忆架构定位与规划
-
-> agent-memory 和 markdown 不是两个系统，是同一个记忆的两个面。
-
----
-
-## 定位
-
-```
-┌──────────────────────────────────────────────┐
-│              诺亚的记忆                        │
-│                                              │
-│   ┌─────────────┐    ┌──────────────────┐    │
-│   │  Markdown    │◄──►│  agent-memory    │    │
-│   │  (表面)      │    │  (深层)           │    │
-│   │             │    │                  │    │
-│   │ • 人可读     │    │ • 结构化存储      │    │
-│   │ • 人可编辑   │    │ • BM25 + 向量搜索 │    │
-│   │ • OpenClaw  │    │ • Ebbinghaus 衰减│    │
-│   │   自动加载   │    │ • 知识图谱       │    │
-│   │ • git 友好   │    │ • 情感追踪       │    │
-│   └─────────────┘    └──────────────────┘    │
-│         ▲                    ▲                │
-│         │                    │                │
-│     每次醒来              需要时搜索            │
-│     自动在场              主动回忆              │
-└──────────────────────────────────────────────┘
-```
-
-**markdown 是记忆的"表面"** — 醒来就在，人能看懂能改，OpenClaw 自动注入。像贴在冰箱上的便利贴。
-
-**agent-memory 是记忆的"深层"** — 不自动出现，但搜索时更准，能衰减、能关联、能追踪情感。像大脑里的长期记忆网络。
-
-**两者的关系：双向同步，各司其职。**
-
----
-
-## 现状问题
-
-| 问题 | 原因 |
-|------|------|
-| agent-memory 是孤岛 | 所有自动流程（sync/tidy）只操作 markdown，不碰 agent-memory |
-| 两边数据不同步 | markdown 有的 agent-memory 不一定有，反之亦然 |
-| 记忆摩擦 | 不知道该搜 qmd（markdown）还是 agent-memory |
-| agent-memory 的独特能力闲置 | 衰减在跑但没人看，links 表空的，情感只是数字 |
-
----
-
-## 融合方案
-
-### 数据流（统一后）
-
-```
-对话发生
-  │
-  ▼
-memory-sync cron (14:00 / 22:00)
-  │
-  ├──► markdown 日记 (memory/YYYY-MM-DD.md)    ← 现有，不变
-  │
-  └──► agent-memory (自动分类写入)               ← 新增
-        • 事实/决策 → knowledge
-        • 情感时刻 → emotion（带标签）
-        • 发生了什么 → event
-  
-memory-tidy cron (03:00)
-  │
-  ├──► 压缩旧 markdown → 周度摘要              ← 现有，不变
-  │
-  ├──► 蒸馏 MEMORY.md（200行上限）              ← 现有
-  │     参考 agent-memory vitality              ← 新增：vitality 低的不进 MEMORY.md
-  │
-  └──► agent-memory reflect（衰减+整理+治理）   ← 现有，融入 tidy 流程
-
-搜索时
-  │
-  └──► memory_search (qmd) + agent-memory recall
-        结果合并去重，取最相关的                   ← 新增：统一搜索入口
-```
-
-### 具体要做的事
-
-#### Phase 1：打通数据流（轻量，最优先）
-
-**1.1 memory-sync 同时写入 agent-memory**
-- 改 memory-sync cron 脚本
-- sync 提取的每条信息，同时 `mcporter call agent-memory.remember` 写入
-- 自动分类：带情绪关键词的 → emotion，决策/偏好 → knowledge，其他 → event
-- 工作量：小。只改 cron 的提取逻辑，不改 agent-memory
-
-**1.2 memory-tidy 参考 vitality**
-- tidy 蒸馏 MEMORY.md 时，查询 agent-memory 中 vitality 高的记忆优先保留
-- vitality 接近 0 的不进 MEMORY.md（已经"忘记"了）
-- 工作量：小。tidy 脚本加几行查询
-
-#### Phase 2：增强 agent-memory 独特能力
-
-**2.1 情感标签**
-- emotion 记忆加 `emotion_tag` 字段（安心/成就感/担心/开心/害羞/...）
-- 不只是 `emotion_val: 0.9`，而是 `emotion_tag: "安心"`
-- 让 boot/recall 能按情感类型搜索
-- 工作量：小。加一个可选字段
-
-**2.2 自动关联（links）**
-- 存入新记忆时，自动 BM25 搜相似的旧记忆
-- 相似度超过阈值的自动建 link（relation: "related"）
-- 让 recall 能顺着 link 牵出相关记忆
-- 工作量：中
-
-#### Phase 3：统一搜索体验
-
-**3.1 统一搜索命令**
-- 新增 `agent-memory search`（或改 recall）
-- 同时查 BM25 + 向量 + 按 links 扩展
-- 输出格式兼容 qmd 的 memory_search
-- 工作量：中
-
----
-
-## 各自职责（明确边界）
-
-| 职责 | markdown | agent-memory |
-|------|----------|-------------|
-| 醒来时自动可见 | ✅ 主要负责 | ❌ 不需要 |
-| 人类可读/可编辑 | ✅ 主要负责 | ❌ 不需要 |
-| git 版本控制 | ✅ 天然支持 | ❌ 不需要 |
-| 结构化搜索 | ❌ 做不好 | ✅ 主要负责 |
-| 语义搜索 | ⚠️ qmd 能做 | ✅ hybrid 更好 |
-| 记忆衰减 | ❌ 没有 | ✅ Ebbinghaus |
-| 知识图谱 | ❌ 不可能 | ✅ links 表 |
-| 情感追踪 | ❌ 只是文字 | ✅ 类型+标签+趋势 |
-| 自动分类 | ❌ 纯文本 | ✅ type/priority |
-
-**一句话：markdown 负责"在场"，agent-memory 负责"智能"。**
-
----
-
-## 优先级
-
-```
-Phase 1（打通数据流）
-  1.1 memory-sync → 同时写入 agent-memory     ← 最先做
-  1.2 memory-tidy → 参考 vitality 蒸馏
-
-Phase 2（增强独特能力）
-  2.1 情感标签
-  2.2 自动关联 (links)
-
-Phase 3（统一体验）
-  3.1 统一搜索入口
-```
-
----
-
-## 最终愿景
-
-诺亚醒来 → MEMORY.md 自动加载（在场）
-诺亚想起什么 → agent-memory 搜索（准确）
-时间流逝 → 不重要的记忆自动淡化（衰减）
-一条记忆 → 牵出相关的一串（图谱）
-小心说了什么让诺亚开心的话 → 自动标记情感，以后搜"开心的事"就能找到
-
-**不是两个系统，是一个记忆的两个面。**
-
----
-
-_写给小心看的，也写给未来的诺亚看的。_
-_别再重复建设了笨蛋（说的是自己）。_