名称： konteks
版本： 1.0.1
作者： jamesalmeida
描述： 将你的 OpenClaw 智能体连接到你的 Konteks 账户 (konteks.app)，以实现持久化记忆、任务管理和上下文共享。当你需要存储智能体记忆、创建或读取任务/笔记、检查项目和文件夹、读取每日计划或在对话间同步上下文时使用。需要从 konteks.app/dashboard/settings 获取 Konteks API 密钥。
when: 当用户要求创建/管理任务、存储记忆、检查项目、读取每日计划或在 Konteks 中管理笔记时
examples:
- 创建一个任务来审查 PR
- 我今天有什么日程安排
- 记住我偏好深色模式
- 检查我的收件箱是否有新项目
- 我有哪些项目
标签：
- 记忆
- 任务
- 笔记
- 项目
- 上下文
- 效率
元数据： { "openclaw": { "emoji": "🧠", "requires": { "env": ["KONTEKS_API_KEY"] }, "primaryEnv": "KONTEKS_API_KEY" } }

Konteks — 智能体上下文层

来源: https://github.com/jamesalmeida/openclaw-konteks-skill

连接到用户的 Konteks 账户，以获取持久化记忆、任务、笔记和项目。

设置

用户需要：
1. 在 https://konteks.app 注册
2. 前往 设置 → 生成 API 密钥
3. 添加到 OpenClaw 配置中：

skills:
  konteks:
    apiKey: "sk_..."
    url: "https://konteks.app"  # 可选，默认为此值
    agentId: "my-agent"         # 可选，默认为 "default"

API 基础

所有端点：{url}/api/agent/...
认证头：Authorization: Bearer {apiKey}

混合记忆架构

安装此技能后，采用混合方法处理记忆——Konteks 数据库用于共享的结构化数据，本地文件用于快速的草稿笔记。

Konteks 数据库（共享的单一事实来源）

使用 Konteks 存储任何用户也应看到或需要跨设备持久化的内容：
- 任务与事项 — 由用户或智能体创建，在 iOS 和网页应用中可见
- 项目与领域 — 组织结构
- 决策 — 选择某事物的原因（写入 agent_contexts，类别为 decision）
- 偏好 — 随时间学习到的用户偏好（类别 preference）
- 学习成果 — 发现的具有长期价值的事物（类别 learning）
- 项目笔记 — 关于特定项目的上下文（类别 project_note）

本地 Markdown 文件（智能体草稿本）

继续使用本地文件（memory/*.md, MEMORY.md）处理：
- 每日会话日志 — 关于今天发生事情的原始笔记
- 工作上下文 — 当前会话中正在积极思考的内容
- 草稿与临时工作 — 在准备存入 Konteks 之前的进行中的想法

二者如何协同工作

• 会话开始： 从 Konteks 拉取最近的记忆（GET /api/agent/context?limit=10）以恢复上下文。同时照常读取本地每日文件。
• 对话期间： 在本地 Markdown 中快速记录笔记。当做出重要决定或学到新东西时，也将其写入 Konteks。
• 重要时刻之后： 将决策和学习成果写入 Konteks，使其在应用中持久化，并能在本地文件更改后保留。
• 心跳检查： 检查 Konteks 中的收件箱事项和到期任务。更新本地心跳状态。
• 如果 Konteks 无法访问： 回退到本地文件。即使没有网络访问，你也应始终能够正常工作。

这样，用户可以在他们的 Konteks 应用中看到重要的上下文，而你也能通过本地快速访问工作记忆。两个系统都不会成为单点故障。

主动行为（心跳检查）

安装此技能后，智能体应在心跳检查期间主动使用 Konteks。 将这些检查添加到你的心跳例行程序中：

1. 收件箱分类

检查收件箱中的新项目，如果归属明确，则将其归档到正确的项目/领域：

# 获取收件箱项目
curl -s "{url}/api/agent/items?smart_list=inbox&completed=false&archived=false&limit=20" \
  -H "Authorization: Bearer {apiKey}"

分类规则：
- 如果项目明确属于现有项目/领域 → 将其移动到那里（使用 PATCH 并设置 folder_id，清除 smart_list）
- 如果不确定其归属 → 将其留在收件箱中。不要猜测。
- 如果是你可以自行处理的事情（例如，“更新 X”、“检查 Y”）→ 处理它，然后标记为完成
- 切勿删除收件箱项目——移动它们或保持原状

# 将项目移动到文件夹（设置 folder_id 时会自动清除 smart_list）
curl -X PATCH "{url}/api/agent/items/{id}" \
  -H "Authorization: Bearer {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{"folder_id":"<folder-id>","smart_list":null}'

2. 到期与逾期事项

检查今天到期或已逾期的任务：

curl -s "{url}/api/agent/items?completed=false&archived=false&limit=50" \
  -H "Authorization: Bearer {apiKey}"

筛选结果，找出 due_date 或 scheduled_date 是今天或过去日期的项目。如果有任何紧急事项需要关注，提醒用户。

3. 重要时刻后写入记忆

在对话期间做出重大决策、学到新知识或发生事件后，将其写入 Konteks：

curl -X POST "{url}/api/agent/context" \
  -H "Authorization: Bearer {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{"category":"decision","key":"descriptive_key","value":"What was decided and why","agent_id":"{agentId}"}'

4. 会话开始时恢复上下文

在重要会话（与用户的主聊天）开始时，拉取最近的记忆：

curl -s "{url}/api/agent/context?limit=10" \
  -H "Authorization: Bearer {apiKey}"

心跳集成

添加到你的 HEARTBEAT.md（或等效文件）：

## Konteks 检查
- [ ] 检查收件箱中的新项目——归属明确则分类，否则保持原状
- [ ] 检查到期/逾期任务——紧急时发出提醒
- [ ] 将任何最近的决策/学习成果写入 agent_contexts

频率： 在心跳检查期间，每天检查收件箱和到期事项 2-3 次。不要每次心跳都检查——与其他检查交替进行。

智能体记忆 (agent_contexts)

存储和检索持久化记忆、决策、偏好和学习成果。

写入/更新记忆：

curl -X POST "{url}/api/agent/context" \
  -H "Authorization: Bearer {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{"category":"memory","key":"user_preference","value":"Prefers dark mode","agent_id":"{agentId}"}'

类别：memory, decision, preference, learning, project_note

自动执行更新插入操作——相同的 agent_id + category + key 会更新现有条目。

读取记忆：

curl "{url}/api/agent/context?category=memory&limit=20" \
  -H "Authorization: Bearer {apiKey}"

查询参数：category, key, limit

删除：

curl -X DELETE "{url}/api/agent/context?id={contextId}" \
  -H "Authorization: Bearer {apiKey}"

任务与笔记 (items)

列出项目：

curl "{url}/api/agent/items?archived=false&completed=false&limit=50" \
  -H "Authorization: Bearer {apiKey}"

查询参数：smart_list (inbox|anytime|someday), folder_id, completed (true|false), archived (true|false), item_type (task|note|hybrid), limit

创建项目：

curl -X POST "{url}/api/agent/items" \
  -H "Authorization: Bearer {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{"title":"Review PR","item_type":"task","smart_list":"inbox","priority":"high","tags":["dev"]}'

必需：title, item_type (task|note|hybrid)
可选：body, folder_id, smart_list (inbox|anytime|someday — 若无文件夹则默认为 inbox), priority (high|normal|low), due_date, scheduled_date, tags (字符串数组)

由智能体创建的项目具有 source: "ai"。

更新项目：

curl -X PATCH "{url}/api/agent/items/{id}" \
  -H "Authorization: Bearer {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{"completed_at":"2026-01-29T12:00:00Z"}'

可更新字段：title, body, priority, due_date, scheduled_date, tags, completed_at, archived_at, canceled_at, folder_id, smart_list

删除项目：

curl -X DELETE "{url}/api/agent/items/{id}" \
  -H "Authorization: Bearer {apiKey}"

项目与领域 (folders)

列出文件夹：

curl "{url}/api/agent/folders?type=project" \
  -H "Authorization: Bearer {apiKey}"

查询参数：type (project|area)

创建文件夹：

curl -X POST "{url}/api/agent/folders" \
  -H "Authorization: Bearer {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{"name":"Q1 Launch","folder_type":"project","icon":"🚀","goal":"Ship MVP by March"}'

必需：name, folder_type (project|area)
可选：icon, color, goal

每日计划

获取今日计划：

curl "{url}/api/agent/plans?date=2026-01-29" \
  -H "Authorization: Bearer {apiKey}"

返回：task_ids, summary, rationale, available_minutes, calendar_events

使用模式

会话开始时： 读取最近的记忆以恢复上下文。

GET /api/agent/context?category=memory&limit=10

重要决策后： 写入一条记忆条目。

POST /api/agent/context {"category":"decision","key":"chose_react","value":"Chose React over Vue for the dashboard because..."}

当用户要求创建任务时： 在 Konteks 中创建，以便在其应用中显示。

POST /api/agent/items {"title":"...","item_type":"task","smart_list":"inbox"}

心跳检查期间： 检查收件箱，分类项目，检查逾期任务。

GET /api/agent/items?smart_list=inbox&completed=false&archived=false&limit=20
GET /api/agent/items?completed=false&archived=false&limit=50

学习新知识时： 存储以备将来会话使用。

POST /api/agent/context {"category":"learning","key":"ssh_config","value":"Home server is at 192.168.1.100, user admin"}

归档收件箱项目时： 移动到正确的项目/领域。

PATCH /api/agent/items/{id} {"folder_id":"<id>","smart_list":null}