Memory Management

Auto-Generated Memory (remember.py)

scripts/remember.py reads the SQLite unified index and writes structured memory files:

Usage:

python3 scripts/remember.py                    # write all
python3 scripts/remember.py --dry-run          # preview only
python3 scripts/remember.py --only skill       # single category

Auto-generated files follow the same frontmatter format, respect dedup rules, and are rebuilt from scratch on each run (no stale data from partial updates).

Memory File Format

Frontmatter schema (simple key: value, NOT general YAML):

---
name: <string, required>           # short identifier
description: <string, required>    # one-line summary for relevance matching
type: <enum, required>             # value | user | feedback | project | reference | insight
---

• All values are plain strings, no quoting needed unless value contains :
• No nested structures, no lists, no multi-line values
• Body follows after the closing --- delimiter as markdown

MEMORY.md Index Format

• Plain markdown file, no frontmatter
• Contains links to individual memory files with brief descriptions
• Lines after 200 are truncated by Claude Code's loader — keep concise
• Entry format: - [filename.md](filename.md) — brief description
• When writing: create individual .md file first, then append entry

Staleness Scoring

Exponential decay: score = 100 * (1 - exp(-age_days * ln(2) / half_life))

insight 类型用于经验合成（experience-synthesis）产生的跨会话模式：

• "X 模式下 Y 工具效率最高"
• "反复出现 Z 模式，应提取为 skill"
• 有效期同 user 类型，但 deep verification 不适用（insight 无法验证文件/URL 是否存在）

Score-to-action: 0-50 = keep, 50-75 = review, 75-100 = prune.

Deep verification modifiers (additive, capped at 100):

• +20 if referenced file is missing
• +30 if referenced function/class not found
• +10 if URL returns non-200
• +15 if referenced branch doesn't exist

Claim Extraction Heuristics (Deep Audit)

Skip generic descriptions that aren't verifiable (e.g., "use a database" vs "uses PostgreSQL 15").

Destination Routing

Priority: Value choices are the most durable memories. When extracting, surface them first. Facts decay (files move, APIs change); values persist (readability > cleverness survives any rewrite).

Rule: Always target the session's originating project, not the current shell cwd.

Mutation Rules

Archive Convention

• Location: memory/archive/ subdirectory
• Files preserved intact (frontmatter + content)
• MEMORY.md entry removed on archive
• iter_memories() skips archive/ — invisible to dashboard/audit/tokens
• Standalone MEMORY.md: archiving not supported (offer delete or keep)
• Restore: manual move from archive/ + re-add to MEMORY.md

下游协作

Dedup Heuristics

写入记忆前，先检查是否已存在相似内容：

1. 同名文件已存在: 对比 body，若 Same → 跳过；若 Superset → 更新旧文件
2. 不同名但内容相似: 用 keyword overlap (>60% shared rare words) 检测，合并为单一文件
3. 同一 insight 被 multiple sessions 重复提取: 只保留最近一次（timestamp 最新），追加 source 行到 body 末尾

CLI History Recovery

当 ~/.claude/history.jsonl 中的 sessionId 在 ~/.claude/projects/ 找不到对应 JSONL 时：

1. 该会话已被 Claude Code 压缩/清理，但 display 字段保留了用户原始 prompt
2. 从 history.jsonl 提取 display + timestamp，可用于：
   • 识别反复出现的 prompt 模式（用户在问什么）
   • 估算会话丢失率（本环境 60%）
3. 工具: sd-recall.py schema ~/.claude/history.jsonl 查看可用字段

DO NOT

• 从零创建新 skill → skill-creator
• 需要提炼经验模式 → experience-synthesis（先提炼再写入）
• 需要解析原始会话数据 → jsonl-core
• 重复写入相同 insight → 先检查同名文件和内容 overlap