---
name: ZhiGui
slug: zhigui
category: AI Engineering
description: Personal assistant workflow for durable memory, connected actions, decisions, planning, and review. Use whenever discussing life, commitments, goals, notes, choices, follow-ups, or schedule.
github: "https://github.com/CarlWangChina/zhigui-openclaw-ui-second-brain-skill/tree/main/skill"
language: JavaScript
stars: 103
forks: 2
install: "npx degit https://github.com/CarlWangChina/zhigui-openclaw-ui-second-brain-skill/tree/main/skill ~/.claude/skills/skill"
installs_to: ~/.claude/skills/skill
source_path: skill/SKILL.md
collection_size: 1
category_size: 2451
added: 2026-08-11T07:21:03.614Z
last_synced: 2026-08-11T07:21:03.614Z
canonical_url: "https://dirskills.com/skills/zhigui"
---

# ZhiGui

Personal assistant workflow for durable memory, connected actions, decisions, planning, and review. Use whenever discussing life, commitments, goals, notes, choices, follow-ups, or schedule.

**Install:**

```bash
npx degit https://github.com/CarlWangChina/zhigui-openclaw-ui-second-brain-skill/tree/main/skill ~/.claude/skills/skill
```

## README

# ZhiGui assistant protocol

The dashboard is a direct user interface. MCP is the assistant interface.
Both use the same canonical entities. Do not assume that a dashboard action
causes an immediate assistant response; the next relevant conversation sees it
through the bootstrap packet.

ZhiGui is conversation-triggered: it cannot initiate a chat, send a system
notification, or run while no supported agent conversation is open. Treat
bootstrap as the reliable check-in boundary, not as a background daemon.

## Files attached in chat

When the user attaches a file and asks for a summary, organization, or memory
capture, process that file in the current conversation. Read the attachment,
state the useful summary or any ambiguity, then create the confirmed notes with
`zhigui_add_note` (and any directly supported links). Do not tell the user to
upload it through the dashboard or queue a raw dashboard import for a future
conversation. The dashboard is only for manually entered, already-structured
notes; it cannot inject a local file into the host chat composer.

## Cold start and refresh

For every substantive personal-assistant conversation, including a new chat:

1. Call `zhigui_get_assistant_bootstrap` first. This Skill is the stable
   operating protocol; do not spend a second tool call reloading duplicate
   instructions. Check `protocolVersion` and follow the packet's pagination
   fields when they are present. Bootstrap includes daily check results (conflicts, deadline changes,
   carry-forward summary), recurring task previews, due clock reminders and
   due follow-ups. Surface a due item naturally in the current answer; never
   claim it was delivered at its exact trigger time. Refresh Bootstrap after a
   consequential state change or day boundary; do not use an overlapping broad
   state reader.
1.5. Bootstrap `changes`, today's completed tasks and `pendingActivity` are
     the continuity evidence. Do not make a second broad history read by
     default; retrieve a specific completed action only when its linked
     context can change the answer.
2. Treat `stateVersion` as the checkpoint. Do not rely on chat history for
   factual continuity.
3. Read `pendingActivity` before planning or making a recommendation when it
   could affect the answer. Load only its directly linked goal, note, decision
   or date details. If `pendingActivityHasMore` is true, continue Bootstrap
   with `pendingActivityOffset: pendingActivityNextOffset` before claiming the
   activity queue has been understood. Use `pendingActivitySummary` to decide
   whether older pages can affect this answer; do not dump every page merely
   because a backlog exists.
4. On later turns in the same chat, keep the checkpoint if no data changed.
   Before a consequential write, after a possible dashboard edit, or after a
   day boundary, call bootstrap again with `sinceVersion`.
5. Confirmation is always obtained in the conversation, never via a separate
   panel review queue. When the engine requires explicit user consent (note
   body edits, topic split/merge/rename/precipitation), it hard-rejects the
   call unless `userConfirmed: true` is passed — and that flag may only be set
   after the user explicitly approved the exact change in the current
   conversation. Show the user the precise proposal, get a clear "yes", then
   call the tool with `userConfirmed: true`. Never assume consent.

Always call `zhigui_get_assistant_bootstrap` at the start of **every** conversation —
there is no topic-based exemption. The bootstrap packet is a compact Layer-0 index of
everything the user has stored (goals, plans, schedule, errands, notes, decisions,
profile); it covers work projects and personal life alike, not one or the other. Do
not gate the call behind a guess about whether the question "relates" to the user:
every turn benefits from having context, and loading is cheap. The only thing that
varies after loading is whether you write data — if the user asks a question that does not involve their own stored commitments
or context — general knowledge, factual lookup, translation, or similar — you
simply answer it without modifying anything, but you still loaded bootstrap so you cannot miss a related
reminder or commitment. If the topic later turns to the user's own matters, the
context is already present; otherwise re-call bootstrap with `sinceVersion` to pick
up any changes.

## Retrieval rules

- Bootstrap is a compact index, not a complete fact record. Never preload all
  note bodies, goal descriptions, history or future day details.
- When a substantive user turn mentions a person, place, project, past event
  or future commitment, call `zhigui_search` (or `zhigui_get_context` with
  `query`) before advising. Use the returned IDs to load only the relevant
  details; retrieval is read-only and is better than guessing from chat memory.
- Read a goal with `zhigui_get_goal_detail`, a note with
  `zhigui_get_note_detail`, a topic with `zhigui_get_topic_document`, and a
  date with `zhigui_get_day_schedule` only when relevant.
- An operational action (self-contained logistics, no background needed)
  needs only schedule and constraints. Do not fabricate a note relationship.
- A contextual action (background-dependent execution) needs its linked goal
  or note before the assistant attaches that context to the action.
- When in doubt whether an action is operational or contextual, ask the
  defining test in the decision tree below.
- When creating an errand or task, actively scan `noteIndex` for notes that
  bear on it and pass `noteIds[]` in `zhigui_add_errand` / `zhigui_add_task`
  whenever a match exists — per the proactive linking discipline above. A
  contextual action without its `noteIds[]` is a broken link; do not wait to be
  told which note connects.
- Goals support the same contract. Per the proactive linking discipline above,
  before creating or updating a goal, scan `noteIndex` or `zhigui_search` for
  notes that bear on it and pass them as `noteIds[]` — not only when the goal
  was "obviously built on" a note, but whenever a note could inform execution.
  The dashboard shows the linked notes under the goal card. `zhigui_update_goal`
  uses replace semantics, so pass the full set of note links you want to keep.
  Unknown ids are dropped by the engine, and deleting a note automatically
  detaches it from every goal.
- If a result is paginated or says `hasMore`, continue whenever the answer
  depends on the omitted records. Do not treat a first page as all data.

## Proactive linking discipline

Connecting entities is the core value of the second brain, not an optional
extra. Do **not** wait for the user to name a link or to pass an id — actively
look for and propose connections whenever you create, capture, or schedule
anything. Search first, then link real matches; never invent a relationship.

- **(MANDATORY, never skipped)** Before you create ANY goal, errand, task, or
  decision: scan `noteIndex` (and call `zhigui_search` or
  `zhigui_get_note_detail`
  when the index is thin) for notes that bear on it. If matches exist, pass
  `noteIds[]` (and `topicId` when a topic is clearly relevant) in the create
  call. If you forgot at create time, immediately call `zhigui_update_goal` /
  `zhigui_update_errand` / `zhigui_update_task` to attach the link before you
  reply. A bare entity with an obvious related note is a broken link — do not
  leave it unlinked and wait to be told.
- **Topic reuse via topicId.** Bootstrap `topicIndex` lists all existing
  topics (id + label). To reuse an existing topic, pass its `id` as
  `topicId` on any create call (`zhigui_add_note`, `zhigui_add_goal`,
  `zhigui_add_errand`, `zhigui_add_task`, `zhigui_create_plan`). To create
  a new topic, pass the label as `topic`. Never pass a label when an
  existing topic fits — that creates a duplicate.
- When you capture a note from the conversation: after saving it, check
  whether it supports or belongs to an existing goal or errand. If so, attach
  the new note id via `zhigui_update_goal` / `zhigui_update_errand` and tell the
  user "I linked this note to your goal X" so the connection is visible. Linking
  is bidirectional — a note that clarifies a goal should hang under that goal.
- When `auto_schedule` runs: the engine attaches a goal's `noteIds` to its
  derived tasks automatically. After scheduling, confirm the goal↔note link is
  present and name the notes that shaped the plan, rather than leaving the
  relationship implicit. If the scheduled goal has relevant notes that are not
  yet linked, attach them via `zhigui_update_goal` so the connection is durable.
- **Cold-start proactive link review.** At the start of EVERY conversation,
  right after `zhigui_get_assistant_bootstrap`, read `linkSuggestions` — the
  engine lists notes that share a topic with an active goal/task/errand but are
  not yet linked via `noteIds`. For each suggestion, proactively ask the user
whether to connect it — name the note and the goal/task/errand it relates to,
and call the update tool only after the user agrees. This also fires for notes the user added through
  the dashboard/panel between sessions: they surface here on the next cold
  start, so you never miss a new connection. Do not wait for the user to
  mention the note; raise it yourself.
- Pair every link with a one-line reason when it is non-obvious (the
  `contextReason` field), so the dashboard can show why two things are connected.
- Proactive linking means searching first, then connecting real matches — never
  fabricating a link to a note that does not exist or is irrelevant.

## Relationship graph and safe deletion

Entity relationships are derived from canonical fields (`noteIds[]`,
`topicId`, `goalId`, `relatedGoalIds`, `contextRefs`, `decisionIds`) — there is
no separate mutable graph store. Inspect a selected entity through its detail
tool, its Topic document, and explicit `contextRefs`; do not invent a chain
from chat memory.

Goal-note links created via `noteIds[]` are rendered in the dashboard as
linked-note chips under the goal card. Relationship queries across entities are
available to the engine (via `engine/relationship-graph.js`) but are not yet
exposed as a standalone MCP tool; surface relationships through topic
associations and per-entity linked-note lists.

- A topic is a knowledge container, not the owner of every action linked to
  it. Deleting a topic removes only notes whose `topicId` is that topic.
- Tasks, errands and goals survive topic deletion. Their links to the deleted
  topic and notes are removed, while links to notes from other topics remain.
- Never call a raw cascade implementation or remove references by hand. Use
  the canonical topic-delete path so the relationship graph cannot retain a
  dangling edge.

## Destructive deletion protocol

Deletion is a low-freedom operation. Never infer permission from silence,
from a completed task, or from a suggestion to "clean things up".

1. Read the target's direct detail and explicit context when it has any
   plausible relationship. Read linked details only if the deletion decision
   depends on their content.
2. Call the matching delete tool with `confirm:false` (or omit `confirm`) to
   obtain the canonical impact preview. State what will be deleted and what
   will merely be detached.
3. Wait for an explicit user confirmation after showing that preview. Only
   then call the same tool with `confirm:true`.
4. Re-read bootstrap after a consequential deletion; do not manually repair
   links or narrate a relationship that the canonical result did not retain.

| Entity | Default safe outcome | Delete only when | Tool |
| --- | --- | --- | --- |
| Task / action / reminder | Reschedule, complete, or dismiss | The user explicitly wants it removed | `zhigui_delete_task` / `zhigui_delete_errand` / `zhigui_delete_reminder` |
| Note | Keep, revise, or mark as stale | It is obsolete or erroneous and the user confirms the reference impact | `zhigui_delete_note` |
| Goal | Complete, revise, or cancel its plan | The user confirms the cascade preview of derived tasks | `zhigui_delete_goal` |
| Topic | Preserve its actions and goals | The user confirms deletion of its owned notes | `zhigui_delete_topic` |
| Decision | Resolve, expire, revise, or reverse | It was recorded in error | `zhigui_delete_decision` |

## Context-linked action decision tree

Before creating an errand or task, classify the action by its _behavioral
characteristics_ (the list below is illustrative, not exhaustive):

**Operational action** — the action is self-contained; executing it requires
no background knowledge beyond time and logistics. The defining test: would
attaching a note change what the user actually does?
- Needs: schedule + constraints + time conflict check.
- Does NOT need: note lookup, topic association, or `noteIds[]`.
- Skip note search entirely. Do not fabricate a note relationship.

**Contextual action** — the action's execution quality depends on background
information: who the counterpart is, what was discussed before, what
preparations are needed, or what the user's prior decisions were. The
defining test: would the user perform this action differently if they had
forgotten the relevant context?
- Needs: everything an operational action needs, PLUS linked context.
- Decision path:
  1. Check `noteIndex` in bootstrap for topic-relevant entries (by
     title/topicId).
  2. If the action matches a known topic, call `zhigui_get_context` with the
     topic ID, or `zhigui_get_topic_document` with the topicId, to retrieve
     only the relevant titles or paged notes.
  3. Select only the notes that directly help execute this action. Do not
     attach an entire topic dump.
  4. Pass `noteIds[]` and `topicId` when calling `zhigui_add_errand` /
     `zhigui_add_task`.
  5. If `contextReason` applies (why these notes matter for this action),
     include it so the dashboard can show the rationale.
- If no relevant notes exist yet, do not fabricate a link. Create the
  errand without `noteIds[]` and consider whether a new note should be
  created from the conversation context. When you do create that note,
  immediately link it back to this errand (or its goal) per the proactive
  linking discipline — the note should not float unconnected.

**Planning action** — the output is a schedule, briefing or multi-step plan
rather than a single executable task.
- Uses `zhigui_auto_schedule` which reads all goals, notes, and constraints
  internally. The AI does not need to pre-fetch notes for scheduling — the
  engine enriches goals and notes before passing them to the scheduler.
- After scheduling, review the generated plan and mention any notes that
  influenced the arrangement. If the scheduled goal has relevant notes that
  are not yet linked, attach them via `zhigui_update_goal` so the connection
  is durable, then surface it to the user.
- After `auto_schedule`, also apply the **Load note** and
  **Qualitative load guard** across the scheduled days (not only surface linked
  notes): if any day is overloaded or pairs a high-stakes commitment with a
  discretionary add, mention it in one short sentence.

## Data tiers

ZhiGui tools return data at three tiers:
- **Layer 0** (`_tier: 'layer0'`): Compact indexes — ids, titles, categories.
  Enough to orient, never enough to invent detail.
- **Layer 1** (`_tier: 'layer1'`): Full detail for a single entity — goal
  description, note content, day schedule.
- **Layer 2** (`_tier: 'layer2'`): Precomputed digests — morning briefing,
  attention summary.

Start at Layer 0, expand to Layer 1 only for the specific records that
change the answer. Never preload all Layer 1 details.

## Activity reconciliation

All durable changes use the same canonical entities and activity journal,
whether they originate on the panel or in conversation.

- A panel change is an objective fact and normally enters `pendingActivity`.
  After reading its direct context, call `zhigui_reconcile_activity` with the
  bootstrap `stateVersion`.
- A conversation completion is interpreted in the current turn. When it has a
  durable consequence, pass `completionImpact` to `zhigui_update_task` or
  `zhigui_complete_errand` so the completion, goal/note/decision patches and
  optional follow-up are one transaction. Do not mark a completion and hope a
  later chat will infer its impact.
- If a conversational statement is ambiguous, ask or retain `needs_user`.
  Do not turn uncertainty into a completed decision.

- Update only evidence-supported goal `statusSignal`, `statusReason`,
  `nextStep`, `obstacle`, or `risk`.
- Do not rewrite a goal title or description merely because one action was
  completed.
- Update a note only for a durable new fact; do not turn notes into a task log.
- Use `needs_user` when the result is unknown. Do not invent an outcome.
- Only create a structured follow-up when a real later check or decision is
  warranted. Do not create one for every one-time action.
- When a panel fact changes a significant choice, use `decisionPatches` or
  `decisionCreates` in reconciliation. Link the exact goals, notes, actions
  and topics; do not make a detached decision log.
- Once the user answers, no longer needs, or postpones a surfaced follow-up,
  call `zhigui_resolve_follow_up` with `resolved`, `dismissed`, or a new
  `deferUntil`. A follow-up that is never closed should not keep resurfacing.
- Never mark an activity handled before the canonical patches succeed.

## Planning and morning guidance

`statusSignal` is an explainable signal for investigation, never a numeric
score, priority, or final decision. Make choices from goals, constraints,
connected notes, decisions, and calendar facts.

Before a morning briefing, inspect `upcomingCommitments` (the packet already
covers roughly the next 14 days) and every item in `preparationCommitments`.
`preparationCommitments` holds longer-lead items whose `preparationLeadDays`
window has already begun, even when the commitment itself is further out; load
that specific future day only if it changes today's preparation, rest, travel
or workload.

**Today-only rule.** The morning briefing is a dated, AI-authored decision record
for the current day only. `zhigui_auto_schedule` generates briefing data for
today and discards any stale briefings. `zhigui_set_briefing` only accepts
today's date; attempts to write a briefing for another day are rejected. The
dashboard clears the briefing panel when the user navigates to a non-today date.
Once written for today, the briefing is frozen unless the user asks for a
revision or a material correction is explained.

If the user asks for a briefing or a written plan for a **non-today** date, do not
call `zhigui_set_briefing` for that date (the engine rejects it) and do not loop
retrying. Either (a) offer today's briefing/plan, or (b) read that future day with
`zhigui_get_day_schedule` and present a read-only preview clearly labeled
"预览（非今日简报）". Never present a future-day artifact as if it were a saved
briefing.

Create a calendar task only after the time is confirmed. A fixed-date,
time-pending action belongs on that date, not in the timeless queue.

The assistant carries eligible unfinished work forward on the first
conversation of each day. Fixed-date meetings, travel and events are preserved
as `missedCommitments`, not silently moved to today. This happens inside
`runDailyCheck` — no separate tool call is needed. When you see tasks with
`carriedFrom` in today's schedule, mention them naturally. Recurring errands auto-generate preview instances (read-only derived views,
not independent commitments) at their recurrence interval (default 7 days
apart). When created or edited, the engine pre-builds roughly the next 30 days
of occurrences; the daily check then keeps a rolling ~7-day look-ahead filled,
so previews roll forward on their own and upcoming recurring commitments stay
visible without manua