zhigui-second-brain-mcp-skill

ZhiGui Second Brain MCP Skill

Skill by ara.so — Hermes Skills collection.

What is ZhiGui?

ZhiGui (知归, knowing where to return) is a personal intelligence system combining a JSON-file-driven knowledge graph with MCP tools. It provides 40+ tools for goals, schedules, notes, decisions, errands, and reminders, with relationship tracking, long-term memory, and planning assistance.

Key capabilities:

Relationship Graph: Every entity (goal, schedule, note, decision) is interlinked through foreign keys
Tiered Indexing: Lightweight bootstrap loads titles first, full content on-demand
Automatic Linking: AI suggests related notes, goals, and decisions based on context
Long-term Memory: Lifecycle states track entity freshness (Active → Stale → Archive Candidate)
Morning Briefings & Reflections: AI-generated daily summaries frozen to specific dates
Reference Integrity: Deletion previews impact and cleans broken references

Installation

Prerequisites

Node.js ≥ 17
MCP-capable AI tool (Claude Desktop, Cursor, Trae, etc.)

Step 1: Clone or Download

git clone https://github.com/CarlWangChina/zhigui-openclaw-ui-second-brain-skill.git
cd zhigui-openclaw-ui-second-brain-skill

Step 2: Install Dependencies

cd skill
npm install

Step 3: Configure MCP

Add to your AI tool's MCP configuration (e.g., claude_desktop_config.json or similar):

{
  "mcpServers": {
    "zhigui": {
      "command": "node",
      "args": ["/absolute/path/to/zhigui-openclaw-ui-second-brain-skill/skill/engine/server.js"]
    }
  }
}

Replace /absolute/path/to/ with your actual installation path. Use forward slashes even on Windows.

Step 4: Verify Installation

Start a conversation with your AI and say:

"Show me today's schedule"

If the AI calls zhigui_get_assistant_bootstrap and returns data, the configuration is successful.

Optional: Load Demo Data

cd skill
node scripts/seed-demo-data-en.js  # English demo data
# or
node scripts/seed-demo-data.js     # Chinese demo data

Optional: Launch Desktop Panel

# From project root
npm install
npm start

# Or use platform-specific launchers
# Windows: start.bat
# macOS/Linux: ./start.sh

Core MCP Tools

Bootstrap & Context Loading

zhigui_get_assistant_bootstrap Load a compact index of all active entities (goals, schedules, notes, decisions). Always call this at conversation start.

// The AI automatically calls this when conversation begins
// Returns: { goals, schedules, notes, decisions, topics, briefings, reflections }

zhigui_get_schedules_by_date

// Get all schedules for a specific date
{
  "date": "2026-08-15"  // YYYY-MM-DD format
}
// Returns: Array of schedule items with referenced notes/goals/decisions

zhigui_get_goal_detail

{
  "goalId": "goal_12345"
}
// Returns: Full goal with linked schedules, notes, decisions

zhigui_get_note_detail

{
  "noteId": "note_67890"
}
// Returns: Full note content with tags, topic, linked entities

Creating Entities

zhigui_create_schedule

{
  "title": "Review Q3 marketing strategy",
  "date": "2026-08-20",
  "time": "14:00",           // Optional, omit if time not set
  "topicId": "topic_123",    // Required
  "noteIds": ["note_456"],   // Optional, suggested by AI
  "goalId": "goal_789",      // Optional, link to parent goal
  "decisionIds": ["dec_111"], // Optional, cite decisions
  "tags": ["marketing", "quarterly-review"],
  "priority": "high",        // low | medium | high
  "estimatedMinutes": 90
}

zhigui_create_goal

{
  "title": "Launch new product feature",
  "description": "Ship the analytics dashboard by end of Q3",
  "topicId": "topic_product",
  "deadline": "2026-09-30",
  "status": "in_progress",   // not_started | in_progress | completed | blocked | deferred
  "priority": "high",
  "noteIds": ["note_spec_123", "note_design_456"]
}

zhigui_create_note

{
  "title": "Product analytics requirements",
  "content": "- Real-time user tracking\n- Custom event funnels\n- Export to CSV",
  "topicId": "topic_product",
  "tags": ["analytics", "requirements"],
  "goalIds": ["goal_789"],   // Optional, link to goals
  "decisionIds": ["dec_222"] // Optional, cite decisions
}

zhigui_create_decision

{
  "title": "Use PostgreSQL for analytics storage",
  "context": "Evaluated options: PostgreSQL, ClickHouse, BigQuery",
  "decision": "PostgreSQL",
  "reasoning": "Best balance of performance, team expertise, and cost",
  "topicId": "topic_product",
  "status": "accepted",      // proposed | accepted | rejected | superseded
  "noteIds": ["note_eval_123"],
  "goalIds": ["goal_789"]
}

Updating Entities

zhigui_update_schedule

{
  "scheduleId": "sched_12345",
  "updates": {
    "status": "completed",
    "actualMinutes": 120,
    "completionNotes": "Decided to pivot to mobile-first strategy",
    "impactedGoalIds": ["goal_789"],      // Update goal status
    "impactedNoteIds": ["note_456"],      // Update note content
    "followUpScheduleIds": ["sched_999"]  // Created follow-up tasks
  }
}

zhigui_update_goal

{
  "goalId": "goal_789",
  "updates": {
    "status": "completed",
    "progressNotes": "All acceptance criteria met",
    "completionDate": "2026-08-15"
  }
}

zhigui_update_note

{
  "noteId": "note_456",
  "updates": {
    "content": "Updated content after review meeting",
    "tags": ["marketing", "quarterly-review", "mobile-first"]
  }
}

Deleting Entities

zhigui_delete_schedule

{
  "scheduleId": "sched_12345",
  "confirmed": true  // Must preview impact first, then confirm
}
// AI should first call without confirmed:true to preview impact

zhigui_delete_goal

{
  "goalId": "goal_789",
  "confirmed": true
}

zhigui_delete_note

{
  "noteId": "note_456",
  "confirmed": true
}

Briefings & Reflections

zhigui_generate_briefing

{
  "date": "2026-08-15"  // Generate morning briefing for this date
}
// Returns: { mustDos, recommended, strategic, warnings }

zhigui_generate_reflection

{
  "date": "2026-08-15",  // Generate evening reflection
  "completedScheduleIds": ["sched_123", "sched_456"]
}
// Returns: { completed, goalHealth, attentionShifts, tomorrow }

Long-term Memory & Cleanup

zhigui_get_stale_entities

{
  "days": 30  // Find entities unreferenced for 30+ days
}
// Returns: { staleNotes, staleGoals, staleDecisions }

zhigui_archive_entity

{
  "entityType": "note",  // note | goal | decision
  "entityId": "note_456",
  "confirmed": true
}
// Moves to .zhigui/archive/ with timestamp

Configuration

Data Directory Structure

skill/.zhigui/
├── goals.json
├── schedules.json
├── notes.json
├── decisions.json
├── topics.json
├── briefings.json
├── reflections.json
└── archive/
    ├── goals/
    ├── schedules/
    ├── notes/
    └── decisions/

Modify AI Behavior

Edit skill/SKILL.md to customize:

Assistant personality
Auto-linking rules
Reflection prompts
Briefing format
Priority scoring logic

Example customization in SKILL.md:

## Auto-linking Rules

When creating a schedule:
1. If title mentions a goal keyword, suggest linking that goal
2. If topic has recent notes with matching tags, suggest linking those notes
3. If a decision exists on the same topic with status "accepted", suggest citing it
4. Limit suggestions to top 3 most relevant entities

Environment Variables

# Optional: Override data directory
export ZHIGUI_DATA_DIR="/custom/path/to/.zhigui"

# Optional: Change dashboard port (default 7788)
export ZHIGUI_DASHBOARD_PORT=8080

Common Patterns

Pattern 1: Daily Planning Flow

// 1. Morning: Load bootstrap and generate briefing
await zhigui_get_assistant_bootstrap();
await zhigui_generate_briefing({ date: "2026-08-15" });

// 2. User reviews briefing, creates/adjusts schedules
await zhigui_create_schedule({
  title: "Review analytics spec",
  date: "2026-08-15",
  time: "10:00",
  topicId: "topic_product",
  noteIds: ["note_spec_123"],  // AI suggests based on title
  priority: "high"
});

// 3. Evening: Mark completed, generate reflection
await zhigui_update_schedule({
  scheduleId: "sched_123",
  updates: {
    status: "completed",
    completionNotes: "Spec approved, ready for dev",
    impactedGoalIds: ["goal_789"]
  }
});
await zhigui_generate_reflection({
  date: "2026-08-15",
  completedScheduleIds: ["sched_123"]
});

Pattern 2: Goal-Driven Note Creation

// User says: "I need to research database options for the analytics project"

// 1. AI finds related goal
const bootstrap = await zhigui_get_assistant_bootstrap();
const goal = bootstrap.goals.find(g => g.title.includes("analytics"));

// 2. Create note linked to goal
await zhigui_create_note({
  title: "Database evaluation for analytics",
  content: "Options: PostgreSQL, ClickHouse, BigQuery\n\nCriteria:\n- Query performance\n- Cost\n- Team expertise",
  topicId: goal.topicId,
  tags: ["database", "research"],
  goalIds: [goal.id]
});

// 3. Suggest creating a decision once research complete
// (AI prompts user: "When you decide, I can record it as a decision linked to this note")

Pattern 3: Completing a Task with Follow-ups

// User: "Finished the marketing review. We need to create mobile landing pages."

// 1. Complete original schedule
await zhigui_update_schedule({
  scheduleId: "sched_marketing_review",
  updates: {
    status: "completed",
    completionNotes: "Decided to pivot to mobile-first strategy",
    impactedNoteIds: ["note_marketing_plan"]  // Update plan note
  }
});

// 2. Create follow-up schedule
const followUp = await zhigui_create_schedule({
  title: "Design mobile landing pages",
  date: "2026-08-18",
  topicId: "topic_marketing",
  noteIds: ["note_marketing_plan"],
  priority: "high"
});

// 3. Link follow-up back to original
await zhigui_update_schedule({
  scheduleId: "sched_marketing_review",
  updates: {
    followUpScheduleIds: [followUp.id]
  }
});

Pattern 4: Decision Recording

// User: "We decided to use PostgreSQL after evaluating options"

// 1. Create decision
await zhigui_create_decision({
  title: "Use PostgreSQL for analytics storage",
  context: "Evaluated PostgreSQL, ClickHouse, BigQuery",
  decision: "PostgreSQL",
  reasoning: "Best balance of performance, team expertise, and cost. ClickHouse overkill for our scale, BigQuery too expensive.",
  topicId: "topic_product",
  status: "accepted",
  noteIds: ["note_db_eval"],  // Link to research note
  goalIds: ["goal_analytics"]
});

// 2. AI suggests creating implementation schedule
// "Should I schedule the PostgreSQL setup task?"

Troubleshooting

MCP connection fails

Symptoms: AI says "ZhiGui tools not available"

Solutions:

Check MCP config path is absolute (no ~ or relative paths)
Verify skill/engine/server.js exists

Test manually:

node /absolute/path/to/skill/engine/server.js

Should not crash immediately

Restart AI tool after config changes

Data directory not found

Symptoms: Error "Cannot read goals.json"

Solutions:

Run initialization:
```
cd skill
node scripts/install.js
```
Check skill/.zhigui/ exists and contains JSON files
Set custom data dir if needed:
```
export ZHIGUI_DATA_DIR="/custom/path"
```

Auto-linking not working

Symptoms: AI doesn't suggest related notes/goals when creating schedules

Solutions:

Ensure entities share the same topicId
Check tags overlap between notes and schedule title keywords
Verify bootstrap data is loaded (AI should call zhigui_get_assistant_bootstrap at conversation start)
Review auto-linking rules in skill/SKILL.md

Deletion fails with "broken references"

Symptoms: Cannot delete note/goal that's referenced elsewhere

Solutions:

First preview impact:

await zhigui_delete_note({ noteId: "note_123" }); // without confirmed:true

Review what entities reference it

Confirm deletion to auto-clean references:

await zhigui_delete_note({ noteId: "note_123", confirmed: true });

Reflection/briefing empty or generic

Symptoms: Generated text lacks specifics

Solutions:

Ensure zhigui_get_assistant_bootstrap was called first

Pass completedScheduleIds to reflection:

await zhigui_generate_reflection({
  date: "2026-08-15",
  completedScheduleIds: ["sched_123", "sched_456"]
});

Check schedules have completionNotes and impactedGoalIds filled in
Customize reflection template in skill/SKILL.md

Advanced Usage

Custom Topics

Topics organize all entities. Create topic via panel UI or directly edit skill/.zhigui/topics.json:

{
  "id": "topic_research",
  "name": "Research & Innovation",
  "description": "Long-term R&D initiatives",
  "color": "#9C27B0",
  "createdAt": "2026-08-01T12:00:00Z"
}

Then reference in entities:

await zhigui_create_goal({
  title: "Explore quantum computing applications",
  topicId: "topic_research",
  // ...
});

Recurring Schedules

Mark schedules as recurring in panel UI, or set in JSON:

{
  "id": "sched_weekly_standup",
  "title": "Team standup",
  "recurrence": "weekly",
  "recurrenceDays": [1, 3, 5],  // Mon, Wed, Fri
  "time": "09:00"
}

AI will auto-generate instances on those days.

Exporting Data

All data is plain JSON. Backup or export:

# Backup entire data directory
cp -r skill/.zhigui /backup/location/

# Export specific entity type
cat skill/.zhigui/goals.json | jq '.'

Testing & Development

Run test suite:

cd skill
npm test

Watch file changes during development:

cd skill/dashboard
nodemon server.js

Best Practices

Always load bootstrap first: Call zhigui_get_assistant_bootstrap at conversation start for context
Link intentionally: Only link notes to schedules when there's execution value
Update on completion: Fill completionNotes, impactedGoalIds, impactedNoteIds when marking done
Preview deletions: Never confirm deletion without seeing impact first
Use time sparingly: Only set time field when genuinely time-bound; date-only items are valid
Tag consistently: Reuse existing tags for better auto-linking
Archive regularly: Review stale entities monthly, archive confirmed inactive ones
Customize SKILL.md: Tailor AI behavior to your workflow and priorities

Reference

GitHub: https://github.com/CarlWangChina/zhigui-openclaw-ui-second-brain-skill
User Manual (EN): zhigui-user-manual-en/zhigui-user-manual-en.html
User Manual (CN): zhigui-user-manual/zhigui-user-manual.html
AI Behavior Spec: skill/SKILL.md
Contact: huangkkkke16@gmail.com

About this skill

What is ZhiGui?

Installation

Prerequisites

Step 1: Clone or Download

Step 2: Install Dependencies

Step 3: Configure MCP

Step 4: Verify Installation

Optional: Load Demo Data

Optional: Launch Desktop Panel

Core MCP Tools

Bootstrap & Context Loading

Creating Entities

Updating Entities

Deleting Entities

Briefings & Reflections

Long-term Memory & Cleanup

Configuration

Data Directory Structure

Modify AI Behavior

Environment Variables

Common Patterns

Pattern 1: Daily Planning Flow

Pattern 2: Goal-Driven Note Creation

Pattern 3: Completing a Task with Follow-ups

Pattern 4: Decision Recording

Troubleshooting

MCP connection fails

Data directory not found

Auto-linking not working

Deletion fails with "broken references"

Reflection/briefing empty or generic

Advanced Usage

Custom Topics

Recurring Schedules

Exporting Data

Testing & Development

Best Practices

Reference