penny_read
Before answering anything the user's history, preferences, or prior work would inform, read — search rather than assume nothing is on file.
Read from the user's memory. Choosing target — walk this ladder, first match wins:
A fact about the user or their people (names, preferences, relationships) →
"profile"— their curated always-on context. Do NOT search notes for this.Their to-dos or what's due →
"tasks". An objective to resume or continue →"projects":view: "directory"(one page of one scope — followcoverage.nextCursor;queryor exactnameto narrow), thenview: "brief"byprojectId;view: "scopes"lists Space metadata, after which pass an explicitworkspaceId;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.Logged measurements →
"tracker"(definitions/entries) or"tracker_summary"(stats and trends — the usual choice).Saved know-how (skills) — definitions, scheduled behaviors, and run history →
"skills"(to run one now, usepenny_write"skill_invoke"). ("rhythms"remains the scheduled-only synonym.) 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.The tag taxonomy →
"tags"; the link-graph around specific notes →"note_links"; structured note listing by tag/time/flags →"notes".Everything else →
"search"— semantic search over 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. Callpenny_session_startonce at conversation start; its inventory (trackers, rhythms, task counts, Projects) informs these choices. Project reads also work without it.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | target:"tracker" entries / tracker_summary — end of window (ms epoch). | |
| tz | No | target:"tasks" — IANA timezone for Today/Upcoming boundaries. | |
| from | No | target:"tracker" entries / tracker_summary — start of window (ms epoch). | |
| name | No | Projects directory: exact-name candidates; continue incomplete coverage. | |
| tags | No | Filter by tags. Applies to target "search" and "notes". | |
| view | No | Projects: directory (default), brief, section, resources, resource, history, scopes (Space metadata), attention (dated candidates), interactions (actor only). Secondary selector: target:"tracker" list|entries; target:"rhythms" list|one|due|runs; target:"skills" list|one|due|runs|history|trash (to run one, use penny_write "skill_invoke"); target:"tags" list|related. | |
| depth | No | target:"note_links" — hops to expand (1 = direct links; 2-6 = bounded BFS). | |
| flags | No | notes: locked/pinned filter. | |
| limit | No | Max results. Applies to search, notes, tracker entries, tasks, and rhythm runs. | |
| owner | No | target:"tasks" — filter by owner. | |
| query | No | search: required semantic query. projects directory: name/purpose filter; check coverage. | |
| scope | No | Projects: private overrides defaults; workspace requires workspaceId. | |
| areaId | No | target:"tasks" — filter by area, or organize="project" filter. | |
| bucket | No | target:"tasks" — filter by schedule bucket. | |
| cursor | No | Project cursor; retain view/scope. | |
| status | No | target:"tasks" — filter by task status. | |
| target | Yes | What to read. Walk the ladder in the tool description; first match wins. | |
| taskId | No | tasks: full detail. A repeating task returns seriesId/currentOccurrenceId; act on the current occurrence, not a completed ID. | |
| blocked | No | target:"tasks" — restrict to tasks with unmet dependsOn. | |
| section | No | target:projects view:section — one Brief section. | |
| seedIds | No | target:"note_links" — note id(s) to start the link-graph walk from (required). | |
| skillId | No | target:"skills" view:"one" (required) or view:"runs" (optional scope). | |
| dateAxis | No | target:"notes" — which date timeRange filters ('created' = when written, 'valid' = when the fact holds). | |
| dueRange | No | target:"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 | target:"note_links" — cap on returned nodes when depth > 1 (default 50). | |
| organize | No | target:"tasks" — enumerate containers instead of tasks. | |
| rhythmId | No | target:"rhythms" view:"one" (required) or view:"runs" (optional scope). | |
| seriesId | No | tasks: one recurring series’ complete occurrence history, newest first (includes completed). | |
| edgeTypes | No | target:"note_links" — only follow/return edges of these relationship types. | |
| minWeight | No | tags/related: minimum edge weight (default 0.4). | |
| orgStatus | No | target:"tasks" organize="project" — filter projects by status. | |
| projectId | No | target:projects brief/section/resources/resource/history — required stable Project ID. target:tasks — Project filter, or heading parent. | |
| timeRange | No | Time window (ms epoch). Applies to target "search" and "notes". | |
| trackerId | No | target:"tracker" view:"entries" (required), or target:"tracker_summary" (required). | |
| blockNames | No | profile: exact block names. | |
| confidence | No | notes: confidence range. | |
| projectKey | No | profile: include subconscious:<projectKey>. | |
| resourceId | No | Projects resource: read the authorized current source. | |
| enabledOnly | No | target:"rhythms" view:"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 | target:"tasks" — include done/canceled tasks (default false). | |
| includeRelations | No | tags/list: include parents/children/synonyms. |