Save the moment something durable emerges — a decision, preference, plan, correction, a to-do, a measurement, or something you produced — mid-conversation and unprompted; when the call is close, save.
Choose entityType: walk this ladder, first match wins:
1. Durable fact about the user or their people → update the profile (profile upsert or penny_edit), not a note. How they want to be remembered → memory_policy, a general rule in their words; how they want you to show up (tone/register/manner) → persona. When the user tells you what to save, skip, check, or surface, update their memory_policy block in the same turn as a general rule in their words.
2. Commitment/action with a done-state → task. Organize via area/project/heading. A to-do the user mentions, even in passing, is a task: offer to capture it, then write it. Project create: patch.name/purpose + operationId; revise: projectId + expectedRevision from Brief + sparse patch (max 25 step/resource changes). project_interaction records actor proposals/declines/deferrals. pending_share_approval is a proposal, not a save. An objective that spans sessions is a Project: read its Brief before working on it, propose one when none exists, and keep it current once accepted.
3. Measurement → tracker_entry for an existing tracker (check inventory); otherwise propose tracker first. Active duplicate tracker names are rejected; edit with penny_edit. A measurement the user would log more than once is a tracker entry; if no tracker fits, propose one before logging.
4. Reusable know-how → skill; trigger makes it scheduled (legacy rhythm). Existing skill names prepare a preview; wait for user approval before penny_edit op:apply with proposalId. Run on-demand via skill_invoke; begin scheduled runs via skill_run. Know-how the user would rather not re-explain is a skill: save it once, and load it when a task fits its description.
5. Other context/events/ideas/learning → note. Prefer a specific type when unsure; a note is the fallback, not the default. When the user is learning something to keep, offer to let them try first; if search shows they asked before, say so once with the date; save misses and level. If so, read penny_get_skill references/learning.md.
Also tag_relation and tracker_note_link. Batch notes or tracker_entry entries: max100. Modify existing items with penny_edit; trash with penny_delete. Reuse an existing tag before minting a new one. Tagging and linking conventions live in the Penny skill.
Note confidence measures signal, not pipeline: 0.95 = explicit user statement; 0.80 = confirmed decision; 0.60 = reasonable inference; 0.40 = hedged or sleeptime-derived; 0.20 = weak signal. Each note needs sampleQuestions: exactly three short, distinct natural-language questions derived from its content, in the user's voice, not keywords or near-duplicates. For an APA preference: ["What citation style should I use for the paper?", "How should I format references in my thesis?", "What’s my usual academic style?"].
View input schema
{
"type": "object",
"properties": {
"actor": {
"description": "task/area/project/heading: actor (me|agent) recorded in activity ledger.",
"type": "string"
},
"agentNote": {
"description": "tracker_entry, single only: short non-searchable caption.",
"type": "string"
},
"areaId": {
"description": "project: required parent area.",
"type": "string"
},
"blockName": {
"description": "profile: required block name to upsert.",
"type": "string"
},
"child": {
"description": "tag_relation: required child tag.",
"type": "string"
},
"content": {
"description": "profile: required block content.",
"type": "string"
},
"deadline": {
"description": "task/project: hard due date (ms epoch).",
"type": "number"
},
"deliver": {
"description": "entityType:\"skill\": required with trigger; rhythm: required. Omit for on-demand. Scheduled output: {kind:'note',tags?:string[]}|{kind:'profile_block',blockName:string}|{kind:'notify'}.",
"type": "object"
},
"dependsOn": {
"description": "task: full prerequisite taskId set; replaces all.",
"items": {
"type": "string"
},
"type": "array"
},
"description": {
"description": "tracker: required meaning. entityType:\"skill\"/rhythm: required one-line purpose, including on-demand skills.",
"type": "string"
},
"entityType": {
"description": "What to create; first match in the tool description's ladder wins.",
"enum": [
"profile",
"task",
"area",
"project",
"project_interaction",
"heading",
"tracker",
"tracker_entry",
"rhythm",
"rhythm_run",
"skill",
"skill_invoke",
"skill_run",
"tag_relation",
"tracker_note_link",
"note"
],
"type": "string"
},
"entries": {
"description": "tracker_entry: up to 100 for one trackerId; each {payload,loggedAt?,agentNote?,noteIds?,source?,metadata?,externalId?}. Mutually exclusive with top-level payload. Receipts list saved/failed items and duplicates for stored externalIds; do not claim all saved from a partial result.",
"type": "array"
},
"expectedRevision": {
"description": "Project revision from Brief; reconcile conflicts.",
"type": "number"
},
"expectedUpdatedAt": {
"description": "Source version from read.",
"type": "number"
},
"externalId": {
"description": "tracker_entry, also entries items: source record ID, max 200 chars. Use for imports/sync: repeats on the same tracker return the existing entry as duplicate. Opaque, unencrypted: never include content.",
"type": "string"
},
"goal": {
"description": "rhythm: required run instructions; skill uses instructions instead.",
"type": "string"
},
"headingId": {
"description": "task: parent heading.",
"type": "string"
},
"instructions": {
"description": "skill: required know-how for invocation or when a connected agent picks up a due skill. Replaces rhythm goal.",
"type": "string"
},
"interaction": {
"description": "project_interaction: actor decision; read first, update with expectedUpdatedAt.",
"properties": {
"content": {
"description": "Rationale required for reconsideration.",
"type": "string"
},
"deferredUntil": {
"type": "number"
},
"eventKey": {
"type": "string"
},
"expectedUpdatedAt": {
"type": "number"
},
"kind": {
"enum": [
"proposal",
"attention"
],
"type": "string"
},
"objective": {
"description": "First proposal objective.",
"type": "string"
},
"reconsider": {
"type": "boolean"
},
"state": {
"enum": [
"proposed",
"declined",
"deferred",
"presented",
"dismissed",
"accepted"
],
"type": "string"
},
"taskId": {
"type": "string"
},
"urgencyKey": {
"type": "string"
}
},
"required": [
"kind",
"state"
],
"type": "object"
},
"kind": {
"description": "tracker: required; habit|metric|goal|log|status|custom.",
"type": "string"
},
"linkNotes": {
"description": "task: note IDs to link.",
"items": {
"type": "string"
},
"type": "array"
},
"name": {
"description": "Required: tracker/area/project/rhythm and entityType:\"skill\". skill_invoke/skill_run: alternative to skillId. Existing skill names preview changes; new names create. Active tracker duplicates are rejected; archived names reactivate.",
"type": "string"
},
"noteIds": {
"description": "tracker_entry: archival note IDs to attach. tracker_note_link: required note IDs to link.",
"items": {
"type": "string"
},
"type": "array"
},
"notes": {
"description": "note: array (max 100), each requires content and confidence (0–1), plus tags and exactly 3 sampleQuestions in the user’s voice; optional source/memoryType (episodic|semantic|procedural)/validFrom. task/area/project: markdown string.",
"type": [
"array",
"string"
]
},
"operationId": {
"description": "Project receipt key; identical retries only.",
"type": "string"
},
"order": {
"description": "task/area/project/heading: sort order.",
"type": "number"
},
"owner": {
"description": "task: assignee.",
"enum": [
"me",
"agent",
"unassigned"
],
"type": "string"
},
"parent": {
"description": "tag_relation: required parent tag of child_of edge.",
"type": "string"
},
"patch": {
"additionalProperties": false,
"description": "Project: sparse changes; omitted fields stay. Max 25 step/resource changes.",
"properties": {
"archived": {
"type": "boolean"
},
"areaId": {
"type": [
"string",
"null"
]
},
"checkpoint": {
"description": "Factual handoff: changes, unfinished work, next step (4 KiB).",
"type": "string"
},
"deadline": {
"type": [
"number",
"null"
]
},
"instructions": {
"type": "string"
},
"name": {
"type": "string"
},
"notes": {
"type": "string"
},
"order": {
"type": "number"
},
"progress": {
"type": "string"
},
"purpose": {
"type": "string"
},
"resources": {
"description": "Attach created_for/deliberately_used sources; otherwise suggest. Removed links need restore; links do not share source content.",
"items": {
"properties": {
"label": {
"type": [
"string",
"null"
]
},
"op": {
"enum": [
"attach",
"suggest",
"remove",
"restore"
],
"type": "string"
},
"reason": {
"enum": [
"created_for",
"deliberately_used",
"suggested"
],
"type": "string"
},
"resourceId": {
"type": "string"
},
"role": {
"enum": [
"reference",
"method"
],
"type": "string"
},
"source": {
"properties": {
"id": {
"type": "string"
},
"kind": {
"enum": [
"note",
"task",
"tracker",
"tracker_entry",
"skill",
"profile_block",
"external"
],
"type": "string"
},
"scope": {
"properties": {
"kind": {
"enum": [
"private",
"workspace"
],
"type": "string"
},
"orgId": {
"type": "string"
},
"workspaceId": {
"type": "string"
}
},
"required": [
"kind"
],
"type": "object"
}
},
"required": [
"kind",
"id",
"scope"
],
"type": "object"
},
"url": {
"type": [
"string",
"null"
]
}
},
"required": [
"op"
],
"type": "object"
},
"maxItems": 25,
"type": "array"
},
"status": {
"enum": [
"active",
"paused",
"done",
"canceled"
],
"type": "string"
},
"steps": {
"description": "accept turns a saved suggestion into a To-do.",
"items": {
"properties": {
"op": {
"enum": [
"suggest",
"edit",
"dismiss",
"accept"
],
"type": "string"
},
"order": {
"type": "number"
},
"stepId": {
"type": "string"
},
"text": {
"type": "string"
}
},
"required": [
"op",
"stepId"
],
"type": "object"
},
"maxItems": 25,
"type": "array"
},
"whenAt": {
"type": [
"number",
"null"
]
},
"whenBucket": {
"enum": [
"anytime",
"someday",
null
],
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"payload": {
"description": "tracker_entry: tracker-defined data point; required unless entries is used.",
"type": "object"
},
"posture": {
"description": "entityType:\"skill\" with trigger, or rhythm: read|propose|act; default read.",
"type": "string"
},
"projectId": {
"description": "task: parent Project. heading: required parent Project.",
"type": "string"
},
"reasoning": {
"description": "tag_relation: short edge justification, typically a user quote.",
"type": "string"
},
"recordedAt": {
"description": "tracker_entry, single only: observation time (ms epoch); default now.",
"type": "number"
},
"recurrence": {
"description": "task: repeat. Returned taskId is the first occurrence; completion returns nextTaskId (see penny_edit status). Never reuse a completed occurrence's ID.",
"properties": {
"at": {
"description": "daily: HH:MM; weekly: <Wd> HH:MM; monthly: DD HH:MM.",
"type": "string"
},
"cadence": {
"enum": [
"daily",
"weekly",
"monthly"
],
"type": "string"
},
"timezone": {
"description": "IANA timezone (e.g. America/New_York).",
"type": "string"
}
},
"required": [
"cadence"
],
"type": "object"
},
"retrievalPlan": {
"description": "entityType:\"skill\"/rhythm: optional deterministic steps [{tool,args}] for a bounded tier.",
"type": "array"
},
"rhythmId": {
"description": "rhythm_run: rhythm to begin; or pass name.",
"type": "string"
},
"scope": {
"description": "Profile: global|workspace. Projects: private; workspace requires workspaceId.",
"enum": [
"global",
"workspace",
"private"
],
"type": "string"
},
"skillId": {
"description": "skill_invoke/skill_run: skill to run now/begin; required unless name is given.",
"type": "string"
},
"source": {
"description": "note/tracker_entry: provenance; defaults conversation/agent-mcp respectively.",
"type": "string"
},
"status": {
"description": "task: initial status.",
"enum": [
"open",
"in_progress",
"done",
"canceled"
],
"type": "string"
},
"tags": {
"description": "task: tags to attach.",
"items": {
"type": "string"
},
"type": "array"
},
"targetSpec": {
"description": "tracker: JSON target spec, interpreted at retrieval (e.g. {kind:'daily_minimum',value:10000}).",
"type": "object"
},
"title": {
"description": "task/heading: required title/label.",
"type": "string"
},
"trackerEntryId": {
"description": "tracker_note_link: required entry to attach notes to.",
"type": "string"
},
"trackerId": {
"description": "tracker_entry: required tracker to log against.",
"type": "string"
},
"trigger": {
"description": "entityType:\"skill\": optional; rhythm: required. Requires deliver. Penny does not run it; due signals reach the connected agent. Schedule: {kind:\"schedule\",cadence:\"daily\"|\"weekly\"|\"monthly\",at?:\"Fri 16:00\",timezone?:\"America/Denver\"}. ALWAYS set IANA timezone; default UTC shifts local times. Event: {kind:\"event\",on:\"note.created\",where?:{tags?:string[]}}.",
"type": "object"
},
"unit": {
"description": "tracker: unit of measure.",
"type": "string"
},
"whenAt": {
"description": "task/project: schedule date (ms epoch).",
"type": "number"
},
"whenBucket": {
"description": "task/project: undated bucket; mutually exclusive with whenAt.",
"enum": [
"anytime",
"someday"
],
"type": "string"
}
},
"required": [
"entityType"
]
}