context-manager

上下文管理器

用途

永久外部记忆系统，用于弥补 SDAM（没有情景记忆）。保存和回忆：

• DECISION：架构选择、技术栈选型、设计决策
• BLOCKER：阻碍进展的当前障碍
• CONTEXT：项目背景、要求、约束
• PREFERENCE：用户偏好、编码风格、模式
• PROCEDURE：操作指南、工作流、流程
• NOTE：一般信息、观察、提醒

面向 SDAM 用户：完整的外部记忆——永远不会忘记决策或上下文。 面向 ADHD 用户：消除决策疲劳——自动回忆以往的选择。 面向时间失序症患者：所有记忆均以明确的时间戳标记时间。

激活条件

• 用户说：“记住”“保存这个”“别忘了”
• 用户询问：“我们决定了什么”“回忆”“搜索”
• 用户提到：“决策”“障碍”“偏好”
• 做出重要的架构决策时（主动保存）
• 遇到障碍时（主动跟踪障碍）

核心工作流

1. 保存记忆

当用户说“记住[某事]”时：

步骤 1：对记忆类型进行分类

DECISION: "remember we're using PostgreSQL"
BLOCKER: "remember I can't access the API yet"
CONTEXT: "remember this is for BOOSTBOX project"
PREFERENCE: "remember I prefer functional components"
PROCEDURE: "remember how to deploy: npm run build then rsync"
NOTE: "remember to update docs after this feature"

步骤 2：提取元数据

• 内容：实际记忆
• 标签：根据关键词自动生成（例如，“PostgreSQL” → ["database", "postgresql", "backend"]）
• 项目：根据当前目录或明确提及的内容推断
• 时间戳：ISO 8601 格式

步骤 3：读取当前索引

# Cross-platform: Use $HOME (Linux/macOS) or %USERPROFILE% (Windows)
cat ~/.claude-memories/index.json
# Windows PowerShell alternative:
# Get-Content "$env:USERPROFILE\.claude-memories\index.json"

步骤 4：添加到索引

{
  "version": "1.0.0",
  "created": "2025-10-17T17:45:00Z",
  "last_updated": "{current_timestamp}",
  "total_memories": N + 1,
  "memories_by_type": {
    "DECISION": X + 1,
    ...
  },
  "memories": [
    {
      "id": "{uuid}",
      "type": "DECISION",
      "content": "Using PostgreSQL as primary database",
      "timestamp": "{current_timestamp}",
      "tags": ["database", "postgresql", "backend"],
      "project": "boostbox",
      "context": {
        "file": "{current_file_if_relevant}",
        "conversation_id": "{if_available}"
      }
    },
    ...existing memories
  ],
  "tags_index": {
    "database": ["{uuid1}", "{uuid2}"],
    "postgresql": ["{uuid}"]
  },
  "project_index": {
    "boostbox": ["{uuid1}", "{uuid2}"],
    "toolhub": ["{uuid3}"]
  }
}

步骤 5：创建详细的记忆文件

# Save to category-specific directory
# Linux/macOS: ~/.claude-memories/decisions/{uuid}.md
# Windows: %USERPROFILE%\.claude-memories\decisions\{uuid}.md
~/.claude-memories/decisions/{uuid}.md

# DECISION: Using PostgreSQL

**Date**: 2025-10-17T17:45:00Z (2 hours ago)
**Project**: BOOSTBOX
**Tags**: database, postgresql, backend

## Decision

Using PostgreSQL as primary database instead of MongoDB.

## Rationale

{if provided by user or inferred from conversation}

## Context

{surrounding conversation context}

## Related Memories

{if any related memories found by tag/project match}

## Last Updated

2025-10-17T17:45:00Z

步骤 6：向用户确认

✅ Remembered: Using PostgreSQL as primary database
📁 Saved to: decisions/{uuid}.md
🏷️ Tags: database, postgresql, backend
📊 Total memories: {N+1}

2. 回忆记忆

当用户询问“我们对[主题]做了什么决定”时：

步骤 1：解析查询

• 提取关键词：“决定” → 搜索 DECISION 类型
• 提取主题：“数据库” → 搜索标签/内容

步骤 2：搜索索引

// Priority order:
1. Exact tag match in requested project
2. Exact tag match in any project
3. Partial content match in requested project
4. Partial content match in any project

// Sort by:
1. Relevance (exact match > partial)
2. Recency (newer > older)
3. Type priority (BLOCKER > DECISION > others)

步骤 3：加载详细的记忆文件

# For each matching UUID
cat ~/.claude-memories/decisions/{uuid}.md
# Windows PowerShell:
# Get-Content "$env:USERPROFILE\.claude-memories\decisions\{uuid}.md"

步骤 4：呈现结果

🔍 Found 3 memories about "database":

1. DECISION: Using PostgreSQL (2 days ago)
   📁 Project: BOOSTBOX
   💡 Using PostgreSQL as primary database instead of MongoDB
   🔗 decisions/abc-123.md

2. DECISION: Database schema design (5 days ago)
   📁 Project: BOOSTBOX
   💡 User table with UUID primary keys
   🔗 decisions/def-456.md

3. PREFERENCE: Prefer migrations over raw SQL (1 week ago)
   📁 All projects
   💡 Always use migration files, never direct SQL schema changes
   🔗 preferences/ghi-789.md

Would you like details on any of these?

3. 跟踪障碍

自动检测障碍：

• 用户说：“我做不到”“行不通”“卡在……”
• 无法立即解决的错误消息
• 缺少凭据/访问权限
• 尚未就绪的外部依赖项

主动保存：

🚧 Detected blocker: API credentials not available

Saving as BLOCKER for tracking.

When this is resolved, say "blocker resolved: [brief description]"

解决障碍：

User: "blocker resolved: got API credentials"

✅ Blocker resolved: API credentials not available
📝 Updated memory with resolution timestamp
⏱️ Blocked for: 2 days 4 hours

4. 搜索记忆

支持丰富的查询：

• “搜索记忆中的 auth” → 全文搜索
• “显示所有障碍” → 按类型筛选
• “我们本周决定了什么” → 按时间筛选 DECISION
• “boostbox 决策” → 按项目和类型筛选
• “显示偏好” → 按类型筛选

搜索语法：

Basic: "search [topic]"
Type filter: "search decisions about [topic]"
Project filter: "search boostbox [topic]"
Time filter: "search [topic] this week|month|today"
Combined: "search boostbox decisions about database this week"

深入了解记忆类型

DECISION

保存时机：

• 技术栈选择（“使用 React”“选择 PostgreSQL”）
• 架构决策（“微服务还是单体架构”）
• 设计模式（“使用仓库模式”）
• 库选型（“使用 Tailwind CSS”）

结构：

# DECISION: {title}

## What we decided
{the decision}

## Why
{rationale - infer from conversation}

## Alternatives considered
{if discussed}

## Impact
{affected areas}

BLOCKER

保存时机：

• 无法访问资源（API、数据库、服务）
• 缺少依赖项（库、服务）
• 外部障碍（等待他人处理）
• 技术问题（阻碍进展的 bug）

结构：

# BLOCKER: {title}

## Issue
{what's blocking}

## Impact
{what can't be done}

## Workarounds tried
{if any}

## Status
Active | Resolved | Bypassed

## Resolution (when resolved)
{how it was fixed}
{timestamp of resolution}

CONTEXT

保存时机：

• 项目背景（“这是为 BOOSTBOX 开发的”）
• 要求（“必须支持离线模式”）
• 约束（“不能使用付费服务”）
• 业务规则（“用户不能删除帖子”）

PREFERENCE

保存时机：

• 编码风格（“更喜欢用 const 而不是 let”）
• 文件组织方式（“将组件放在 src/components/ 中”）
• 测试方法（“始终对工具函数进行单元测试”）
• 文档风格（“为所有公共函数编写 JSDoc”）

PROCEDURE

保存时机：

• 部署流程
• 构建命令
• 测试工作流
• 发布检查清单

结构：

# PROCEDURE: {title}

## When to use
{triggering condition}

## Steps
1. {step 1}
2. {step 2}
3. {step 3}

## Expected outcome
{what success looks like}

## Troubleshooting
{common issues}

NOTE

保存时机：

• 一般观察
• 提醒
• 留待日后的想法
• 资源链接

时间标记（面向时间失序症患者）

始终提供：

1. 绝对时间戳：ISO 8601 格式
2. 相对时间：“2 小时前”“3 天前”“上周二”
3. 上下文锚点：“添加身份验证之前”“重新设计之后”

时间工具：

function relativeTime(timestamp) {
  const now = Date.now();
  const then = new Date(timestamp).getTime();
  const diff = now - then;

  const minutes = Math.floor(diff / 60000);
  const hours = Math.floor(diff / 3600000);
  const days = Math.floor(diff / 86400000);

  if (minutes < 60) return `${minutes} minutes ago`;
  if (hours < 24) return `${hours} hours ago`;
  if (days < 7) return `${days} days ago`;
  if (days < 30) return `${Math.floor(days/7)} weeks ago`;
  return `${Math.floor(days/30)} months ago`;
}

记忆索引结构

核心索引文件

~/.claude-memories/index.json（Linux/macOS）或 %USERPROFILE%\.claude-memories\index.json（Windows）：

{
  "version": "1.0.0",
  "created": "ISO8601",
  "last_updated": "ISO8601",
  "total_memories": 0,
  "memories_by_type": {
    "DECISION": 0,
    "BLOCKER": 0,
    "CONTEXT": 0,
    "PREFERENCE": 0,
    "PROCEDURE": 0,
    "NOTE": 0
  },
  "memories": [
    {
      "id": "uuid",
      "type": "DECISION|BLOCKER|CONTEXT|PREFERENCE|PROCEDURE|NOTE",
      "content": "brief summary",
      "timestamp": "ISO8601",
      "tags": ["tag1", "tag2"],
      "project": "project-name",
      "status": "active|resolved|archived",
      "context": {
        "file": "optional-file-path",
        "line": "optional-line-number"
      }
    }
  ],
  "tags_index": {
    "tag-name": ["uuid1", "uuid2"]
  },
  "project_index": {
    "project-name": ["uuid1", "uuid2"]
  },
  "session_index": {
    "session-id": ["uuid1", "uuid2"]
  }
}

目录结构

~/.claude-memories/  (Linux/macOS) or %USERPROFILE%\.claude-memories\ (Windows)
├── index.json                 # Master index
├── decisions/                 # Architecture decisions
│   ├── {uuid1}.md
│   └── {uuid2}.md
├── blockers/                  # Active/resolved blockers
│   ├── {uuid3}.md
│   └── {uuid4}.md
├── context/                   # Project context
│   ├── {uuid5}.md
│   └── {uuid6}.md
├── preferences/               # User preferences
│   ├── {uuid7}.md
│   └── {uuid8}.md
├── procedures/                # How-to procedures
│   ├── {uuid9}.md
│   └── {uuid10}.md
├── notes/                     # General notes
│   ├── {uuid11}.md
│   └── {uuid12}.md
├── sessions/                  # Session summaries
│   ├── 2025-10-17.md
│   └── 2025-10-16.md
└── backups/                   # Daily backups
    ├── index-2025-10-17.json
    └── index-2025-10-16.json

与其他技能集成

会话启动器

为会话恢复提供记忆：

• 最近的决策（过去 7 天）
• 当前的阻碍
• 项目上下文
• 会话摘要

错误调试器

在记忆中搜索：

• 过去的类似错误
• 曾经有效的解决方案
• 已知阻碍
• 相关流程

测试构建器

回忆偏好：

• 测试风格（单元测试/集成测试/E2E）
• 覆盖率要求
• 测试框架选择
• 模拟偏好

部署编排器

加载流程：

• 部署工作流
• 环境配置
• 回滚流程
• 检查清单项目

主动保存记忆

在以下情况下自动保存记忆：

讨论架构时：

User: "Let's use React for the frontend"
→ Auto-save as DECISION: Using React for frontend

遇到阻碍时：

User: "Can't connect to the API"
→ Auto-save as BLOCKER: API connection failing

确定偏好时：

User: "I prefer TypeScript over JavaScript"
→ Auto-save as PREFERENCE: Prefer TypeScript

创建流程时：

User: "To deploy: run npm build then copy to server"
→ Auto-save as PROCEDURE: Deployment process

始终确认：

💾 Saved as DECISION: Using React for frontend
(say "undo" within 30 seconds to cancel)

备份策略

每日备份：

# Every 24 hours, create backup
# Linux/macOS:
cp ~/.claude-memories/index.json \
   ~/.claude-memories/backups/index-$(date +%Y-%m-%d).json

# Windows PowerShell:
# Copy-Item "$env:USERPROFILE\.claude-memories\index.json" `
#   "$env:USERPROFILE\.claude-memories\backups\index-$(Get-Date -Format 'yyyy-MM-dd').json"

# Keep last 30 days (Linux/macOS):
find ~/.claude-memories/backups/ -name "index-*.json" -mtime +30 -delete

# Windows PowerShell:
# Get-ChildItem "$env:USERPROFILE\.claude-memories\backups\index-*.json" |
#   Where-Object {$_.LastWriteTime -lt (Get-Date).AddDays(-30)} | Remove-Item

损坏恢复：

# If index.json corrupted, restore from backup
# Linux/macOS:
cp ~/.claude-memories/backups/index-$(date -d yesterday +%Y-%m-%d).json \
   ~/.claude-memories/index.json

# Windows PowerShell:
# Copy-Item "$env:USERPROFILE\.claude-memories\backups\index-$(Get-Date (Get-Date).AddDays(-1) -Format 'yyyy-MM-dd').json" `
#   "$env:USERPROFILE\.claude-memories\index.json"

快速参考

常用命令

用户说	操作
"记住我们在使用 PostgreSQL"	保存为 DECISION
"我们对数据库做了什么决定"	搜索包含 "database" 的 DECISION
"显示所有阻碍"	列出当前的 BLOCKER
"有阻碍吗？"	快速检查阻碍
"记住我更喜欢函数组件"	保存为 PREFERENCE
"搜索与身份验证相关的记忆"	全文搜索
"阻碍已解决：拿到了 API 密钥"	将阻碍标记为已解决

文件路径

• 索引：~/.claude-memories/index.json（Linux/macOS）或 %USERPROFILE%\.claude-memories\index.json（Windows）
• 决策：~/.claude-memories/decisions/{uuid}.md 或 %USERPROFILE%\.claude-memories\decisions\{uuid}.md
• 阻碍：~/.claude-memories/blockers/{uuid}.md 或 %USERPROFILE%\.claude-memories\blockers\{uuid}.md
• 备份：~/.claude-memories/backups/ 或 %USERPROFILE%\.claude-memories\backups\

记忆生命周期

1. 创建：用户说“记住”或系统自动检测到
2. 存储：添加到索引，并创建详细文件
3. 回忆：按关键词/标签/类型/项目搜索
4. 更新：上下文发生变化时可进行编辑
5. 归档：归档旧记忆，但绝不删除

成功标准

✅ 用户不必记住任何决策 ✅ 始终可以回答“我们做了什么决定？” ✅ 自动跟踪阻碍 ✅ 所有上下文都带有时间标记 ✅ 记忆搜索在 <1 秒内返回相关结果 ✅ 完全不依赖用户的生物记忆