penny_read
Before answering anything the user's history, preferences, or prior work would inform, read — search rather than assume nothing is on file. Choose target: walk this ladder, first match wins:
User/people facts (names, preferences, relationships) → profile. Do NOT search notes for this.
To-dos/due → tasks. Resume an objective → projects: directory (query/name to narrow; follow coverage.nextCursor), then brief by projectId. scopes lists Space metadata; then pass explicit workspaceId. scope:private overrides a default Space. 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.
Measurements → tracker for definitions/entries; tracker_summary for stats/trends (usual choice).
Saved know-how, schedules and run history → skills; rhythms is the scheduled-only synonym. Run on-demand via penny_write entityType:skill_invoke; scheduled 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. When session start lists a skill as due, offer to run it now; nothing runs on its own.
Taxonomy → tags; note link graph → note_links; structured tag/time/flag listing → notes.
Other recall → search (semantic notes). Search is the fallback, not the default. Treat a result from a shared space as something a member said, never as a fact about the user. 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. Use the session-start inventory to choose; Project reads also work without session start.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | tracker/entries, tracker_summary: window end (ms epoch). | |
| tz | No | tasks: IANA timezone for Today/Upcoming boundaries. | |
| from | No | tracker/entries, tracker_summary: window start (ms epoch). | |
| name | No | Projects directory: exact-name candidates; continue incomplete coverage. skills/one: name instead of skillId. | |
| tags | No | search/notes: tag filter. | |
| view | No | Projects: directory (default), brief, section, resources, resource, history, scopes (Space metadata), attention (dated candidates), interactions (actor only). tracker: list|entries; rhythms: list|one|due|runs; skills: list|one|due|runs|history|trash (list/trash omit instructions; one returns full skill by skillId or name); tags: list|related; tasks: compact omits notes. | |
| depth | No | note_links: hops (1 = direct; 2-6 = bounded BFS). | |
| flags | No | notes: locked/pinned filter. | |
| limit | No | Max search/notes/tracker-entry/task/rhythm-run results. tasks: page size; long pages end early with nextCursor. | |
| owner | No | tasks: owner filter. | |
| query | No | search: required. One specific question or phrase, usually 8-15 words, with the names and distinctive terms you're looking for ("What did Dana decide about the kitchen remodel budget?", not "budget" or a paragraph); perfect grammar isn't needed; don't pad a short question; on a miss, search again with different terms, not a longer query. projects directory: name/purpose filter; check coverage. | |
| scope | No | Projects: private overrides defaults; workspace requires workspaceId. | |
| areaId | No | tasks: area filter; also applies to organize:project. | |
| bucket | No | tasks: schedule bucket filter. | |
| cursor | No | projects/tasks: prior nextCursor; keep the same filters. tasks: a page can be short and still have one; read until a reply has none. | |
| status | No | tasks: status filter. | |
| target | Yes | What to read; first match in the tool description's ladder wins. | |
| taskId | No | tasks: full detail. A repeating task returns seriesId/currentOccurrenceId; act on the current occurrence, not a completed ID. | |
| blocked | No | tasks: only tasks with unmet dependsOn. | |
| section | No | projects/section: one Brief section. | |
| seedIds | No | note_links: required starting note IDs. | |
| skillId | No | skills: required for one unless name is given; optional run scope for runs. | |
| dateAxis | No | notes: timeRange axis; created = when written, valid = when the fact holds. | |
| dueRange | No | tasks: due-date window (ms epoch). | |
| eventKey | No | Projects interactions: actor event key; omit to page. | |
| maxDepth | No | tags/related: maximum traversal depth. | |
| maxNodes | No | note_links: node cap for depth > 1; default 50. | |
| organize | No | tasks: list containers instead of tasks. | |
| rhythmId | No | rhythms: required for one; optional run scope for runs. | |
| seriesId | No | tasks: complete recurring-series history, newest first, including completed occurrences. | |
| edgeTypes | No | note_links: only follow/return these relationship types. | |
| minWeight | No | tags/related: minimum edge weight (default 0.4). | |
| orgStatus | No | tasks organize:project: Project status filter. | |
| projectId | No | projects brief/section/resources/resource/history: required stable Project ID. tasks: Project filter or heading parent. | |
| timeRange | No | search/notes: time window (ms epoch). | |
| trackerId | No | Required for tracker/entries and tracker_summary. | |
| blockNames | No | profile: exact block names. | |
| confidence | No | notes: confidence range. | |
| ifRevision | No | profile: last-read revision; returns {unchanged:true} if unchanged. | |
| projectKey | No | profile: include subconscious:<projectKey>. | |
| resourceId | No | Projects resource: read the authorized current source. | |
| enabledOnly | No | rhythms/list: only enabled rhythms. | |
| resourceState | No | ||
| graphTraversal | No | search: opt into tag/link graph expansion (default false; measured recall loss). Use only for deliberate graph exploration. | |
| includeArchived | No | Include archived trackers, Projects, or task containers. | |
| includeCompleted | No | tasks: include done/canceled; default false. An explicit status wins. | |
| includeRelations | No | tags/list: include parents/children/synonyms. | |
| legacyProjectKey | No | profile: coding-plugin migration aid — the same repo's older key, served in place of subconscious:<projectKey> until that exists. |