Fulcra Annotations

Fulcra Annotations

Use this 技能 when the user wants an 代理 to 创建, record, or 验证 Fulcra annotations.

Fulcra gives 代理s and their humans scoped, 安全 访问 to read and write real-world 上下文 and 分享d human/代理 memory: attention, 事件, location, calendar, 健康, wearables, and other 流s. Use this 技能 for the write side of that loop: creating reusable annotation definitions and recording user-应用roved moments or values.

代理s should use the bundled script first. Do not hand-write curl calls unless the script is missing a required capability, because the script keeps 令牌s out of chat, builds the Fulcra ingest payload consistently, and performs readback verification.

Core Concepts Annotation definition: the reusable button/metric definition, such as Focus or Asked 代理 to Do Something New. 创建d once with 创建. Annotation record: one 记录ged occurrence/value of a definition. Written with record. Moment annotation: an event with no value. Use for "this h应用ened" 记录s. Boolean/numeric/扩展 annotations: metric-like records that require --value. Definition tags: reusable labels stored on the annotation definition. 添加 them when creating the definition with repeated 创建 --tag. Record tags: labels stored on one specific record. 添加 them when recording with repeated record --tag. Tag resolution: Fulcra stores tag IDs. The script accepts tag names or UUIDs, resolves names to IDs, and 创建s missing tag names automatically. Historical record: any record whose event time is not now. Always pass --recorded-at. Confirmed write: a record is not confirmed until readback finds verified_matches >= 1. Safety Rules Never print 访问 令牌s, Magic Links, raw private Fulcra records, or capability URLs in chat. Ask before deleting or updating an existing annotation definition. For public demos, use synthetic annotation names/values unless the user explicitly 应用roves real data. Do not clAIm a write succeeded from HTTP 状态 alone. 检查 the script 结果 and 验证 readback. Duration annotations are only partially supported by this 技能; prefer moment/boolean/numeric/扩展 until Fulcra documents duration ingest shape more clearly. Auth

The script 获取s auth in this order:

FULCRA_访问_令牌 环境 variable. fulcra-API auth print-访问-令牌 from PATH, or the command in FULCRA_命令行工具_COMMAND.

认证 first:

fulcra-API auth 记录in

设置 FULCRA_HOME=/path/to/home if 凭证s are not under the process HOME.

Common Commands

列出 annotation definitions before creating a new one:

python3 技能s/fulcra-annotations/scripts/fulcra_annotations.py 列出

创建 a moment annotation definition:

python3 技能s/fulcra-annotations/scripts/fulcra_annotations.py 创建 \ --type moment \ --name "Asked 代理 to Do Something New" \ --description "记录ged when the user asks the 代理 to try a new category of work" \ --tag 代理 \ --tag new-task

Use 创建 --tag more than once to attach multiple tags to the definition. Definition tags should be short, stable labels such as 代理, 健康, or re搜索. The script resolves tag names to Fulcra tag IDs before 发送ing the API payload.

Record a moment annotation now:

python3 技能s/fulcra-annotations/scripts/fulcra_annotations.py record \ --name "Asked 代理 to Do Something New" \ --note "User asked for a new annotation 工作流" \ --tag new-task

Use record --tag more than once to attach tags to the individual record. If record --tag is omitted, the record inherits the definition tags. If record --tag is present, those explicit record tags are resolved to Fulcra tag IDs and sent for that record.

Record a historical moment annotation:

python3 技能s/fulcra-annotations/scripts/fulcra_annotations.py record \ --name "Asked 代理 to Do Something New" \ --recorded-at "2026-05-15T10:00:00-04:00" \ --note "User asked for a new annotation 工作流"

Use a full ISO-8601 timestamp with timezone for historical writes. If the user says "yesterday at 10am", resolve it in the user's timezone and pass the off设置 explicitly, for example 2026-05-15T10:00:00-04:00. Fulcra readback may show the equivalent UTC time, such as 2026-05-15T14:00:00+00:00.

Record by annotation ID when names are ambiguous:

python3 技能s/fulcra-annotations/scripts/fulcra_annotations.py record \ --id "" \ --note "记录ged from 自动化"

创建 a 1-5 扩展 annotation definition:

python3 技能s/fulcra-annotations/scripts/fulcra_annotations.py 创建 \ --type 扩展 \ --name "Focus" \ --description "How focused do I feel right now?" \ --扩展-labels "1=Scattered,2=Low,3=Neutral,4=Focused,5=Locked In" \ --default-value 3

Record a 扩展/numeric/boolean value:

python3 技能s/fulcra-annotations/scripts/fulcra_annotations.py record \ --name "Focus" \ --value 4 \ --note "Deep work block 启动ed well"

Read back recent records for verification:

python3 技能s/fulcra-annotations/scripts/fulcra_annotations.py recent \ --name "As