Agent Autonomy Primitives
Turn any AI agent into a self-directing worker using five composable primitives: typed memory, task files, project grouping, template schemas, and heartbeat loops.
Prerequisites
CODEBLOCK0
The Five Primitives
1. Typed Memory
Every memory has a type. The type determines where it lives and how it's retrieved.
| Type | Directory | When to Use |
|---|
| INLINECODE0 | INLINECODE1 | Recording a choice with rationale |
| INLINECODE2 |
lessons/ | Something learned from experience |
|
person |
people/ | Contact info, relationship context |
|
commitment |
commitments/ | Promise made, deliverable owed |
|
preference |
preferences/ | How someone likes things done |
|
fact |
inbox/ | Raw information to file later |
|
project |
projects/ | Workstream with goals and status |
Store with type:
CODEBLOCK1
Rule: If you know WHAT KIND of thing it is, use the right command. Dumping everything into daily notes defeats retrieval later.
2. Task Primitives
A task is a markdown file with YAML frontmatter in tasks/:
CODEBLOCK2
Create tasks:
CODEBLOCK3
Update status:
CODEBLOCK4
Statuses: open → in-progress → done (or blocked)
Priorities: critical > high > medium > INLINECODE22
3. Project Grouping
Projects group related tasks with metadata:
CODEBLOCK5
Tasks reference projects via the project field. Filter tasks by project:
CODEBLOCK6
4. Template Schemas
Templates are YAML schema definitions that control what fields exist on every primitive. They live in templates/ in your vault.
See references/template-customization.md for full customization guide.
Key points:
- - Vault templates override builtins — drop a
task.md in templates/ to change the schema - Add fields (e.g.,
sprint, effort, client) by editing the template - Remove fields you don't need
- Change defaults (e.g., default priority =
high) - Validation is advisory — warns but never blocks
5. Heartbeat Loop
The heartbeat is the autonomy mechanism. Wire it into your agent's periodic wake cycle.
Every heartbeat (e.g., every 30 minutes):
CODEBLOCK7
Implementation for OpenClaw agents:
Add to your HEARTBEAT.md:
CODEBLOCK8
For cron-based agents, schedule a recurring job:
CODEBLOCK9
Composing Primitives into Autonomy
The power is in composition, not any single primitive:
CODEBLOCK10
Each cycle compounds:
- - Memory feeds context into task execution (decisions, lessons, preferences inform how work gets done)
- Task execution generates new memories (lessons learned, decisions made, commitments created)
- Lessons improve future execution (mistakes aren't repeated)
- Wiki-links (
[[entity-name]]) build a knowledge graph across all files - Projects provide scope boundaries so the agent doesn't drift
Adapting to Your Setup
See references/adaptation-guide.md for detailed patterns on:
- - Wiring primitives into existing agent frameworks (OpenClaw, LangChain, CrewAI, custom)
- Choosing which primitives to adopt (start minimal, add as needed)
- Multi-agent collaboration through shared vaults
- Migrating from other memory systems
Quick Start: Zero to Autonomous in 5 Minutes
CODEBLOCK11
Anti-Patterns
| Don't | Do Instead |
|---|
| Store everything in one big memory file | Use typed memory — decisions/, lessons/, people/ |
| Create tasks without owner/project |
Always set
--owner and
--project |
| Ask "what should I work on?" | Read your task queue and decide |
| Forget lessons after learning them |
clawvault remember lesson immediately |
| Skip marking tasks done | Always
task done --reason — the ledger tracks transitions |
| Create tasks for vague ideas | Put ideas in
backlog/, promote to
tasks/ when ready |
| Modify template schemas constantly | Stabilize schemas early — field renames break existing files |
Obsidian Integration
Because everything is markdown + YAML frontmatter, Obsidian renders your agent's workspace as a human-readable dashboard:
- - Kanban board — open
all-tasks.base in Obsidian Bases, drag between status columns - Blocked view —
blocked.base shows what needs human input - By owner —
by-owner.base shows what each agent is working on - By project —
by-project.base scopes views per workstream
The same file is both the agent's data structure AND the human's UI. No sync layer needed.
智能体自主性原语
使用五种可组合原语将任何AI智能体转变为自我导向的工作者：类型化记忆、任务文件、项目分组、模板模式和心跳循环。
前置条件
bash
npm install -g clawvault
clawvault init
五种原语
1. 类型化记忆
每条记忆都有类型。类型决定了它的存储位置和检索方式。
| 类型 | 目录 | 使用场景 |
|---|
| decision | decisions/ | 记录带有理由的决策 |
| lesson |
lessons/ | 从经验中学到的东西 |
| person | people/ | 联系信息、关系背景 |
| commitment | commitments/ | 做出的承诺、应交付的成果 |
| preference | preferences/ | 某人喜欢的工作方式 |
| fact | inbox/ | 待归档的原始信息 |
| project | projects/ | 带有目标和状态的工作流 |
使用类型存储：
bash
clawvault remember decision 选择Resend而非SendGrid --content 成本更低、开发者体验更好、支持webhook
clawvault remember lesson LLM在压缩过程中会重写关键词 --content 始终使用正则表达式进行后处理
规则： 如果你知道某事物属于什么类型，就使用正确的命令。将所有内容都转储到每日笔记中会妨碍后续检索。
2. 任务原语
任务是tasks/目录中带有YAML前置元数据的markdown文件：
yaml
status: open
priority: high
owner: your-agent-name
project: my-project
due: 2026-03-01
tags: [infrastructure, deploy]
estimate: 2h
将API部署到生产环境
上下文
服务器已配置。需要修复Dockerfile。
后续步骤
- - 修复绑定到0.0.0.0
- 添加健康检查端点
- 推送并验证
创建任务：
bash
clawvault task add 将API部署到生产环境 \
--priority high \
--owner my-agent \
--project my-project \
--due 2026-03-01 \
--tags infrastructure,deploy
更新状态：
bash
clawvault task update deploy-api-to-production --status in-progress
clawvault task done deploy-api-to-production --reason 已部署，健康检查通过
状态： open → in-progress → done（或blocked）
优先级： critical > high > medium > low
3. 项目分组
项目将相关任务与元数据分组：
bash
clawvault project add 外发引擎 \
--owner pedro \
--client versatly \
--tags gtm,sales \
--deadline 2026-03-15
任务通过project字段引用项目。按项目筛选任务：
bash
clawvault task list --project outbound-engine
4. 模板模式
模板是YAML模式定义，控制每个原语上存在的字段。它们位于你的保险库中的templates/目录下。
完整自定义指南请参见references/template-customization.md。
关键点：
- - 保险库模板覆盖内置模板——在templates/中放置task.md以更改模式
- 通过编辑模板添加字段（例如sprint、effort、client）
- 移除不需要的字段
- 更改默认值（例如默认优先级 = high）
- 验证是建议性的——会发出警告但不会阻止操作
5. 心跳循环
心跳是自主机制。将其接入智能体的周期性唤醒循环。
每次心跳（例如每30分钟）：
- 1. clawvault task list --owner --status open
- 排序：优先级（关键优先），然后截止日期（最早优先）
- 选择可以立即执行的最高影响任务
- 执行它
- 完成后：clawvault task done --reason 完成了什么
- 遇到阻碍：clawvault task update --status blocked --blocked-by 原因
- 发现新工作：clawvault task add 新任务 --priority
--project
- 学到教训：clawvault remember lesson 发生了什么
- 回到休眠状态
OpenClaw智能体的实现：
添加到你的HEARTBEAT.md：
markdown
任务驱动的自主性
每次心跳：
- 1. clawvault task list --owner --status open → 你的工作队列
- 按优先级+截止日期排序
- 选择现在可以执行的最高影响任务
- 执行它。更新状态。标记完成。报告。
- 检查24小时内到期的任务——这些任务获得优先处理
对于基于cron的智能体，安排一个定期任务：
计划：每30分钟
操作：读取任务队列，选择最高优先级，执行，报告
将原语组合成自主性
力量在于组合，而非任何单一原语：
唤醒 → 读取记忆 → 检查任务 → 执行 → 学习 → 更新记忆 → 休眠
↑ |
└──────────────────────────────────────┘
每个循环都会累积：
- - 记忆为任务执行提供上下文（决策、教训、偏好指导工作如何完成）
- 任务执行产生新的记忆（学到的教训、做出的决策、创建的承诺）
- 教训改进未来的执行（错误不会重复）
- Wiki链接（[[entity-name]]）在所有文件中构建知识图谱
- 项目提供范围边界，使智能体不会偏离
适配你的设置
有关详细模式，请参见references/adaptation-guide.md：
- - 将原语接入现有智能体框架（OpenClaw、LangChain、CrewAI、自定义）
- 选择采用哪些原语（从最小开始，按需添加）
- 通过共享保险库实现多智能体协作
- 从其他记忆系统迁移
快速入门：5分钟从零到自主
bash
1. 安装并初始化
npm install -g clawvault
clawvault init
2. 创建你的第一个项目
clawvault project add 我的项目 --owner my-agent
3. 创建任务
clawvault task add 设置监控 --priority high --owner my-agent --project my-project
clawvault task add 编写API文档 --priority medium --owner my-agent --project my-project
4. 接入心跳（添加到HEARTBEAT.md或cron）
每30分钟：clawvault task list --owner my-agent --status open，选择顶部任务，执行
5. 开始工作
clawvault task update set-up-monitoring --status in-progress
... 执行工作 ...
clawvault task done set-up-monitoring --reason Prometheus + Grafana已配置
clawvault remember lesson UptimeRobot免费版仅每5分钟检查一次 --content 使用Better Stack实现<1分钟检查
反模式
| 不要这样做 | 应该这样做 |
|---|
| 将所有内容存储在一个大记忆文件中 | 使用类型化记忆——decisions/、lessons/、people/ |
| 创建没有owner/project的任务 |
始终设置--owner和--project |
| 问我应该做什么？ | 读取你的任务队列并决定 |
| 学到教训后忘记 | 立即clawvault remember lesson |
| 跳过标记任务完成 | 始终task done --reason——账本跟踪转换 |
| 为模糊想法创建任务 | 将想法放入backlog/，准备好时提升到tasks/ |
| 不断修改模板模式 | 尽早稳定模式——字段重命名会破坏现有文件 |
Obsidian集成
因为一切都是markdown + YAML前置元数据，Obsidian将智能体的工作空间渲染为人类可读的仪表板：
- - 看板——在Obsidian Bases中打开all-tasks.base，在状态列之间拖拽
- 阻塞视图——blocked.base显示需要人类输入的内容
- 按负责人——by-owner.base显示每个智能体正在做什么
- 按项目——by-project.base按工作流限定视图范围
同一个文件既是智能体的数据结构，也是人类的UI。无需同步层。
