keep (keep-skill)#

一句话定位#

为 AI 代理提供反思性记忆能力的语义存储与检索系统。

核心能力#

语义存储与检索#

• 向量搜索：按含义而非关键词检索，底层使用向量嵌入
• 多格式支持：URL、文本文件、PDF、HTML、Office 文档、音频、图像
• 自动摘要与标签：入库时自动生成摘要、嵌入向量、提取标签
• 内容寻址 ID：相同文本生成相同 ID（% 前缀），支持去重

反思性记忆机制#

• 上下文反馈：检索时自动关联开放的承诺、过往经验、历史教训
• 当前意图追踪：keep now 命令记录当前工作内容，版本化保存
• 版本历史：每个笔记都有完整版本链，可回溯历史（@V{1} 语法）

标签与组织#

• 结构化标签：支持 project、topic、type、status 等维度
• 精确过滤 + 语义发现：标签用于精确筛选，搜索用于模糊发现

文档分析#

• 分解分析：analyze 将文档拆分为可独立检索的段落，每段有自己的嵌入和标签

架构设计#

存储层#

• 向量数据库：ChromaDB（嵌入向量存储与相似度检索）
• 元数据与版本：SQLite（文档元数据、标签、版本历史）

嵌入与摘要后端#

• 本地模型：MLX（macOS Apple Silicon）、Ollama（自动检测）
• 云端 API：OpenAI、Google Gemini、Voyage（嵌入）、Anthropic（摘要）
• 托管服务：keepnotes.ai

集成层#

• Skill prompt：系统提示词中嵌入反思指导
• Hooks：会话开始、提交提示、会话结束时注入 keep now 上下文
• MCP：提供 9 个工具的 stdio 服务器，兼容 MCP 协议
• LangChain：提供 LangGraph BaseStore、retriever、tools、middleware

安装与快速开始#

# 推荐：使用 uv
uv tool install keep-skill

# 或使用 pip
pip install keep-skill

# 配置 API 密钥（本地 Ollama 运行时无需配置）
export OPENAI_API_KEY=...

# 基本使用
keep put "Rate limit is 100 req/min" -t topic=api
keep find "what's the rate limit?"
keep now "Debugging auth flow"
keep list --tag project=myapp

Python API#

from keep import Keeper

kp = Keeper()

# 存储
kp.put(uri="file:///path/to/doc.md", tags={"project": "myapp"})
kp.put("Rate limit is 100 req/min", tags={"topic": "api"})

# 语义搜索
results = kp.find("rate limit", limit=5)
for r in results:
    print(f"[{r.score:.2f}] {r.summary}")

# 版本历史
prev = kp.get_version("doc:1", offset=1)

AI 工具集成#

首次使用时自动检测并安装：

• Claude Code：CLAUDE.md 反思提示词 + settings.json hooks
• VS Code Copilot：自动读取 Claude Code hooks
• Kiro：实践提示词 + 代理 hooks
• OpenAI Codex：AGENTS.md 提示词
• OpenClaw：提示词 + 插件 + Daily cron 深度反思

可通过 KEEP_NO_SETUP=1 环境变量跳过自动安装。

适用场景#

• AI 代理记忆：为 AI 编程助手提供持久化语义记忆
• 个人知识管理：存储笔记、文档、URL，按语义检索
• 团队上下文延续：keep now 追踪工作进度，跨会话自动恢复上下文
• 文档知识提取：对长篇文档进行分解，使各部分可独立检索
• 反思性实践：配合 SKILL.md 指导 AI 代理进行结构化反思