zhigui-second-brain-mcp-skill

# ZhiGui Second Brain MCP Skill > Skill by [ara.so](https://ara.so) — Hermes Skills collection. ## What is ZhiGui? ZhiGui (知归, "knowing where to return") is a personal intelligence system that combines a JSON-file-driven knowledge graph with MCP (Model Context Protocol) tools. It provides 40+ MCP tools for managing goals, schedules, notes, decisions, errands, and reminders with automatic relationship tracking, long-term memory, and intelligent 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 ```bash git clone https://github.com/CarlWangChina/zhigui-openclaw-ui-second-brain-skill.git cd zhigui-openclaw-ui-second-brain-skill ``` ### Step 2: Install Dependencies ```bash cd skill npm install ``` ### Step 3: Configure MCP Add to your AI tool's MCP configuration (e.g., `claude_desktop_config.json` or similar): ```json { "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 ```bash 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 ```bash # 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. ```javascript // The AI automatically calls this when conversation begins // Returns: { goals, schedules, notes, decisions, topics, briefings, reflections } ``` **`zhigui_get_schedules_by_date`** ```javascript // 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`** ```javascript { "goalId": "goal_12345" } // Returns: Full goal with linked schedules, notes, decisions ``` **`zhigui_get_note_detail`** ```javascript { "noteId": "note_67890" } // Returns: Full note content with tags, topic, linked entities ``` ### Creating Entities **`zhigui_create_schedule`** ```javascript { "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`** ```javascript { "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`** ```javascript { "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`** ```javascript { "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`** ```javascript { "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`** ```javascript { "goalId": "goal_789", "updates": { "status": "completed", "progressNotes": "All acceptance criteria met", "completionDate": "2026-08-15" } } ``` **`zhigui_update_note`** ```javascript { "noteId": "note_456", "updates": { "content": "Updated content after review meeting", "tags": ["marketing", "quarterly-review", "mobile-first"] } } ``` ### Deleting Entities **`zhigui_delete_schedule`** ```javascript { "scheduleId": "sched_12345", "confirmed": true // Must preview impact first, then confirm } // AI should first call without confirmed:true to preview impact ``` **`zhigui_delete_goal`** ```javascript { "goalId": "goal_789", "confirmed": true } ``` **`zhigui_delete_note`** ```javascript { "noteId": "note_456", "confirmed": true } ``` ### Briefings & Reflections **`zhigui_generate_briefing`** ```javascript { "date": "2026-08-15" // Generate morning briefing for this date } // Returns: { mustDos, recommended, strategic, warnings } ``` **`zhigui_generate_reflection`** ```javascript { "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`** ```javascript { "days": 30 // Find entities unreferenced for 30+ days } // Returns: { staleNotes, staleGoals, staleDecisions } ``` **`zhigui_archive_entity`** ```javascript { "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`: ```markdown ## 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 ```bash # 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 ```javascript // 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 ```javascript // 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 ```javascript // 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" });