claudemem

claudemem — AI Agent 的持久记忆

跨对话捕获并检索知识。两种行为：

1. 自动在工作期间保存知识笔记（静默进行，无需用户操作）
2. 按需（/wrapup）保存结构化会话报告，并与笔记交叉关联

斜杠命令

• /wrapup [title] — 会话结束时：提取知识笔记 + 保存详细会话报告 + 交叉关联所有内容。
• /recall [topic] — 搜索持久记忆中的某个主题，或显示近期活动。

自然语言触发词：“记住这个”、“你还记得……吗”、“总结一下”、“上次我们做了什么”

设置

如果 claudemem 不在 PATH 中：

curl -fsSL https://raw.githubusercontent.com/zelinewang/claudemem/main/skills/claudemem/scripts/install.sh | bash

CLI 参考

所有命令都支持 --format json，用于生成结构化输出。

# Notes
claudemem note add <category> --title "..." --content "..." --tags "..." [--session-id "..."]
claudemem note search "query" [--in category] [--tag tags]
claudemem note list [category]
claudemem note get <id> [--tag X]              # Supports 8-char prefix; --tag: only if tagged X
claudemem note append <id> "additional content"
claudemem note update <id> --content "..." [--title "..."] [--tags "..."]   # --tags replaces all tags
claudemem note update <id> --add-tag X,Y --remove-tag Z                     # tags only, keeps the rest
claudemem note delete <id>
claudemem note categories
claudemem note tags

# Sessions
claudemem session save --title "..." --branch "..." --project "..." --session-id "..." [--tags "..."] [--related-notes "id:title:cat,..."]
claudemem session list [--last N] [--date today] [--date-range 7d] [--branch X] [--tag X]
claudemem session search "query" [--branch X] [--tag X]
claudemem session get <id> [--tag X]
claudemem session update <id> --add-tag X --remove-tag Y

# Search
claudemem search "query" [--type note|session] [--limit N]
claudemem search "query" --compact              # IDs + titles only
claudemem search "query" --category X --tag Y   # Faceted filters (whole tags, all required; --tag repeatable)
claudemem search "query" --after 2025-01-01     # Date range
claudemem search "query" --sort date            # Chronological (default: relevance + recency boost)
claudemem search "query" --semantic             # Force semantic even if feature flag off

# Tags
claudemem context inject --tag project-x  # inject only entries carrying the tag
claudemem stats --tag project-x           # the statistics of the tagged entries
claudemem tag apply --file tags.jsonl [--dry-run]   # bulk: {"id","kind":"note|session","add":[],"remove":[]} per line

# Several stores
claudemem config set stores.read "~/team-memory"  # reads also return ~/team-memory's entries, each naming its store
claudemem search "query" --read-stores ""         # this store alone, for one call
claudemem --store ~/team-memory note append <id> "..."   # writes go to --store only: write where the entry lives
claudemem move --to ~/team-memory --file ids.txt --dry-run   # then without --dry-run: moves the listed ids there, keeping them

# Context
claudemem context inject [--limit N] [--project path] [--tag X]  # Recent notes + sessions overview

# Code
claudemem code outline <file>                   # Structural symbols (Go/Python/TS/Rust)

# Knowledge Graph
claudemem graph                                 # DOT format (pipe to Graphviz)
claudemem graph --format json                   # Adjacency list

# Utilities
claudemem stats [--top-accessed]                # Storage stats + access tracking
claudemem reindex [--vectors] [--all]           # Rebuild search/vector indexes
claudemem config set/get/list/delete | export | import | verify | repair

---

协议（固定 — 始终遵循）

这些协议的输入和输出可预测。每次都要严格遵循。

协议 1：保存笔记

每次保存笔记时，都按以下顺序操作：

1. 搜索重复内容：note search "<key phrase>" --format json
2. 如果主题已存在：note append <id> "new info"
3. 如果是新主题：note add <category> --title "..." --content "..." --tags "..."
4. 先检查现有类别：note categories
5. 显示提示：[noted: "title" -> category]

协议 2：会话报告（/wrapup）

会话报告只能通过显式执行 /wrapup 或说“wrap up”来创建，绝不自动创建。 每份会话报告都使用以下确切模板：

## Summary
2-3 substantial paragraphs: goal, accomplished, current state, significance.

## What Happened
Numbered paragraphs. Each phase: what, why, file paths, cause-and-effect, decisions. Minimum 3 phases.

## Key Decisions
- **Decision**: Rationale. Alternatives considered and why rejected.

## What Changed
- `path/to/file` — What changed and why

## Problems & Solutions
- **Problem**: Root cause (not just symptoms)
  **Solution**: Fix and why it works

## Learning Insights
- Reusable knowledge for future sessions

## Related Notes
- `note-id` — "Title" (category)

## Next Steps
- [ ] Concrete actionable follow-up

协议 3：交叉引用

在 /wrapup 期间，笔记和会话必须双向关联：

• 在 wrapup 期间保存的笔记：包含 --session-id "$SESSION_REF"，将笔记关联到会话
• 保存会话：包含 --related-notes "id:title:category,..."，将会话关联到笔记

这样便可追溯：从任意笔记找到生成它的会话；从任意会话找到提取出的知识。

协议 4：检索提示

找到并使用先前知识时，始终显示：

[memory: Found "TikTok Rate Limits" — 100/min per API key]

---

功能（灵活 — 由 Agent 决定何时及如何使用）

这些功能会因上下文而异。请根据以下权衡自行判断。

搜索模式

方式	适用场景	Token 开销
search "X" --compact --format json	快速浏览：“我了解这个吗？”	~100 tokens
search "X" --format json	需要包含预览的完整上下文	~2000 tokens
search "X" --category Y --tag Z	知道所属领域，需要精准结果	不定
search "X" --semantic	即使功能标记关闭，也强制使用混合搜索	~100-2000
note get <id>	需要某条特定笔记的完整内容	~500 tokens
context inject	会话开始时：查看近期知识概览	~1-2KB
stats --top-accessed	查看使用最频繁的笔记（ROI 跟踪）	~200 tokens
graph --format json	了解笔记 ↔ 会话之间的关系结构	~500-2000

默认按相关性排序，并提升近期内容的权重（<7 天的条目最高可获得 20% 的分数加成，该加成在 30 天内逐渐衰减）。使用 --sort date 按时间顺序排序。

启用 features.semantic_search 后，混合搜索会自动运行。它使用 Ollama 嵌入（或 TF-IDF 回退方案），并通过 Reciprocal Rank Fusion 与 FTS5 结合。无需使用 --semantic 标记——每次搜索都会受益于语义匹配。设置方法：config set features.semantic_search true && reindex --vectors。

代码智能

code outline <file> 可提取结构化符号——函数签名、类、类型——而不包含主体。每个符号约需 10-20 tokens，而读取完整文件则需约 500+ tokens。

支持 Go（约 95% 准确率）、Python（约 90%）、TypeScript/JS（约 80%）、Rust（约 85%）。不支持的语言会返回空结果。

上下文注入

context inject 会返回近期笔记、会话和统计信息（约 1-2KB）。可将其配置为 SessionStart 钩子以自动加载，也可以在开始重要工作时手动运行。

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{ "type": "command", "command": "claudemem context inject --limit 5", "timeout": 10000 }]
    }]
  }
}

---

领域知识（参考 — 为决策提供依据）

值得保存的内容

高价值（Claude 在未来会话中不会知道的内容）：

• 项目特定的决策及其理由（为什么选择 X 而非 Y、放弃的替代方案）
• 此代码库特有的 Bug 根因和诊断模式
• 配置方面的特殊情况、特定环境下的注意事项、未记录的 API 行为
• 工作过程中发现的用户偏好（命名惯例、工作流选择）

低价值（跳过——Claude 已经知道或不需要）：

• 临时调试状态、临时输出
• 公开文档中的通用编程知识
• 用户明确表示是临时的信息

数据模型

• 笔记：包含类别、标签、内容和元数据的知识片段。事实来源：~/.claudemem/notes/<category>/<title>.md
• 会话：包含结构化章节的工作报告。事实来源：~/.claudemem/sessions/<title>.md
• 交叉引用：Note.metadata.session_id → Session；Session.RelatedNotes[] → Notes
• 索引：位于 ~/.claudemem/.index/search.db 的 SQLite FTS5（可重新生成的缓存，并非事实来源）

所有数据均为带有 YAML frontmatter 的纯 Markdown——易于阅读、适合 Git 管理且便于移植。