@smyslenny/agent-memory 4.0.0-alpha.1 → 4.2.0

package/docs/design/.next-id

@@ -0,0 +1 @@
+17

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

@@ -0,0 +1,228 @@
+# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smyslenny/agent-memory",
-  "version": "4.0.0-alpha.1",
+  "version": "4.2.0",
   "description": "Agent-native memory layer with lifecycle management for AI agents — SQLite-first, Write Guard, hybrid recall, MCP, CLI, and HTTP API.",
   "type": "module",
   "main": "dist/index.js",