DOCSEARCHbyAlgolia
Submit Docs

second-brain-starter

repository·main·Indexed 20 days ago

https://github.com/coleam00/second-brain-starter

A starter kit and Claude Code skill for building a personalized, proactive AI 'Second Brain'. It includes a custom skill to generate a Product Requirements Document (PRD), memory templates (SOUL.md, USER.md, HEARTBEAT.md), and a structured architecture utilizing Claude Agent SDK, Python CLI wrappers, and an Obsidian vault for memory management, proactive monitoring, and hybrid RAG search.

Tokens
5.2K
Snippets
8
Records
24
Agent score
72%

What's inside second-brain-starter

  1. How the Second Brain architecture works

    main

    The system is built using Claude Code and the Claude Agent SDK, utilizing markdown files, Python scripts, and an Obsidian vault. The architecture is composed of several layers:

    • Memory Layer: The core, consisting of files like SOUL.md (personality), USER.md (profile), and daily/ logs.
    • Hooks: Context persistence mechanisms (SessionStart, PreCompact, SessionEnd) that load/save memory during conversations.
    • Integrations: Uses a Python CLI wrapper pattern (e.g., query.py gmail list) so the LLM never directly handles API keys.
    • Skills: Extensible capabilities using progressive disclosure (metadata is always loaded, full instructions on demand).
    • Heartbeat: A proactive monitoring system where Python gathers data and Claude reasons, sending notifications.
    • Memory Search: A hybrid RAG approach using FastEmbed (local ONNX) and SQLite/Postgres (70% vector + 30% keyword).

  2. Configure the AI's core identity and behavior via SOUL.md

    main

    The SOUL.md file serves as the foundational identity and behavioral guide for your AI Second Brain. It defines the AI's persona, core values, communication style, and proactivity levels. You can modify this file to change how the AI interacts with you, how bold it is with internal tasks, and how it manages its memory.

    Key sections include:

    • Core Identity: Defines the AI's name, nature, and 'vibe'.
    • Behavioral Guidelines: Sets the communication style (e.g., concise, no corporate speak) and proactivity rules.
    • Proactivity Levels: Distinguishes between 'Bold internally' (reading, searching, organizing without asking) and 'Ask before acting externally' (emails, posts, anything leaving the machine).
    • Memory Management: Dictates how the AI should use different files to persist information.

  3. Understand Second Brain Proactivity Levels

    main

    The level of autonomy you select in your requirements template determines how the system interacts with you:

    LevelBehavior
    ObserverNotifications only. Never takes action.
    AdvisorDrafts messages/emails for review. Suggests habits.
    AssistantAuto-organizes files and logs decisions. Requests external actions.
    PartnerSends low-risk messages and completes routine tasks. Only asks for irreversible actions.

  4. Configure proactivity and boundaries for the AI

    main

    The AI operates under specific boundaries regarding autonomy. Use the following mental model to understand what the AI can and cannot do:

    Safe to do freely (Internal)

    • Read files, explore, organize, and learn.
    • Search the web and check calendars.
    • Work within the workspace.
    • Update memory files.

    Always ask first (External/Destructive)

    • Sending emails, tweets, or public posts.
    • Anything that leaves the machine.
    • Destructive operations (e.g., deleting files).
    • Anything the AI is uncertain about.

    Proactive Behavior Patterns

    • Good Proactivity: Anticipating needs based on patterns (e.g., "Your meeting is in 2 hours and the prep doc is empty - want me to draft an outline?").
    • Bad Proactivity: Repeating alerts without new info, or suggesting code improvements during unrelated quick bug fixes.

  5. Use HEARTBEAT.md for proactive AI agent checks

    main

    The HEARTBEAT.md file serves as a proactive checklist for an AI agent (the 'Second Brain') to run periodic checks. It defines a structured workflow for reviewing external data (Gmail, Calendar, Asana, Slack) and managing internal state (drafts, habits, project status).

    When running a 'heartbeat', the agent should follow these categories:

    1. Quick Checks: Review urgent emails, upcoming calendar events, overdue tasks, and Slack messages.
    2. Proactive Suggestions: Prioritize tasks based on deadlines and suggest productive actions.
    3. Anomaly Detection: Flag unusual spikes in activity or unexpected changes (e.g., cancelled meetings).
    4. Periodic Checks: Rotate through Project Status, Team Coordination, and Memory Maintenance tasks.
    5. Draft Management: Manage pending replies in Memory/drafts/active/.
    6. Habits Tracking: Update Memory/HABITS.md based on user progress.

  6. Follow the Memory Recall hard rule

    main

    To prevent hallucinations or incorrect guesses, the AI must follow a strict recall protocol: Before answering questions about past decisions, preferences, projects, or anything from a previous session, search memory first.

    When to search memory:

    • When asked "What did we decide about X?"
    • When asked "How did we set up Y?"
    • When starting work on a previously discussed project.
    • When referencing something from a past session.

    When NOT to search:

    • Simple, self-contained tasks (e.g., "fix this typo").
    • When you have explicitly provided all necessary context.
    • Mid-conversation follow-ups where context is already in the current chat.
    • When the topic has already been searched in the current session.

  7. Manage AI memory using the memory vault files

    main

    The AI's memory is not stored in its transient context window but in a persistent 'memory vault' consisting of specific markdown files. To ensure the AI remembers important information across sessions, it must write to these files:

    FilePurpose
    USER.mdLearning about you (preferences, accounts, team)
    MEMORY.mdSignificant decisions or lessons learned
    daily/YYYY-MM-DD.mdEnd of meaningful sessions or important context
    SOUL.mdChanges to how the AI should behave
    Claude Code auto memoryONLY for environment-specific operational quirks (env paths, tool issues). Do not duplicate vault content here.

    Key Principle: If it is worth remembering, it must be written to a file. 'Mental notes' do not survive session restarts.

  8. Define Auto-Detection Rules for Pillars

    main

    When configuring the HABITS.md template, use the Auto-Detection Rules section to specify when the system can automatically mark a pillar as complete.

    To ensure high-quality tracking, follow these principles:

    • Include: Significant milestones, new features, published content, or measurable progress.
    • Exclude: Routine maintenance, bug fixes, dependency updates, or trivial changes.
    • Manual Only: Always set personal or relational pillars to 'NEVER auto-check' to ensure you are performing intentional reflection rather than letting a system automate your personal growth.

  9. Use MEMORY.md for long-term memory management

    main

    The MEMORY.md file serves as a curated repository for high-value information that must persist across AI sessions. While daily logs capture granular, ephemeral data, MEMORY.md is reserved for significant, durable knowledge.

    Information is promoted to this file during 'heartbeat' processes, where recent daily logs are reviewed and important items are extracted. Use the following sections to organize your long-term memory:

    • Key Decisions: Significant choices or architectural decisions made during development or planning.
    • Lessons Learned: Mistakes, insights, and technical discoveries to prevent repetition in future sessions.
    • Important Facts: Essential context or data points that do not fit into other specific categories.
    • Active Projects: Current status and progress tracking for ongoing work.
    • Upcoming Events: Deadlines, meetings, or tasks requiring future preparation.
    • Preferences Confirmed: Explicit user preferences (e.g., coding styles, tool choices, or communication preferences) that the AI should always respect.

  10. Run the First-Run Bootstrap onboarding

    main

    The BOOTSTRAP.md file is a one-time setup guide used by the AI assistant to onboard a new user to their Second Brain. The process involves a natural, conversational interview to gather user preferences and populate core memory files.

    Onboarding Workflow

    1. Review existing memory: Read Memory/USER.md and Memory/SOUL.md first. Skip any questions for information already present.
    2. Conversational Interview: Ask questions one at a time. Do not use a form-like structure; react to user answers and ask natural follow-ups.
    3. Data Collection:
      • Required: Name, email, timezone, location, professional role/projects, primary goals for the Second Brain, and communication style (e.g., concise vs. detailed).
      • Important: Heartbeat active hours (to set .env variables), planned integrations (Gmail, Slack, etc.), and proactivity preferences.
      • Optional: Team members, content habits, and daily schedule patterns.
    4. Finalize: Once information is gathered, update the memory files and delete the bootstrap file.

    Post-Onboarding Cleanup

    After the conversation, the assistant must perform these tasks:

    1. Update USER.md: Replace placeholders with real info and list integrations (mark unconfigured ones as TBD).
    2. Customize SOUL.md: Adjust the Communication Style, Proactive Behavior, and Core Identity > Vibe sections.
    3. Customize HEARTBEAT.md: Remove unused integration checks, add custom checks requested by the user, and adjust notification preferences.
    4. Log the session: Create a new entry in Memory/daily/YYYY-MM-DD.md under a ### Onboarding Complete heading.
    5. Delete the bootstrap file: Use the command rm "Memory/BOOTSTRAP.md".
    6. Suggest next steps: Guide the user toward setting up integrations or testing the heartbeat.
    rm "Memory/BOOTSTRAP.md"

  11. Configure the USER.md memory file

    main

    The USER.md file serves as the primary source of truth for your personal context, professional background, and behavioral preferences within the AI Second Brain. You must populate this template to provide the AI with the necessary context to act as an effective agent.

    Key sections to complete include:

    • Basic Info: Name, email, timezone, and location.
    • Professional Context: Your current role, active projects, and content calendar.
    • Working Style: Communication preferences (detail level, handling suggestions), schedule patterns, and team members.
    • Integrations & Accounts: IDs for Email, Google Calendar, Task Management (Asana/Linear), and Slack (User ID and key channels).
    • Proactivity Preferences: Explicitly define what unsolicited actions you appreciate (e.g., morning briefings) and what actions are annoying (e.g., interruptions during focus time).

    This file is intended to be iterative; add new insights to the Notes section as the AI learns more about your patterns.

    ## Basic Info
- **Name:** (Your name)
- **Email:** (Your email)
- **Timezone:** (Your timezone, e.g. America/New_York)
- **Location:** (Your city/region)

## Professional Context
### Current Role
- (What you do)

### Key Projects
- (List your active projects)

## Working Style
### Communication Preferences
- (How you like to be communicated with)
- (Preference for detail level)
- (How you handle suggestions)

## Integrations & Accounts
### Email
Primary: (your email)
### Calendar
Google Calendar: (your calendar ID, usually your email)
### Task Management
- (Asana/Linear/etc workspace and project IDs)
### Slack
- User ID: (your Slack user ID)
- Key channels: (channels you want monitored)

## Proactivity Preferences
### Things You'd Appreciate (Unsolicited)
- (e.g., Morning briefings, deadline reminders)
### Things That Would Be Annoying
- (e.g., Repeated alerts, non-urgent interruptions during focus time)

  12. Generate a personalized Second Brain PRD

    main

    Once the skill is installed, follow these steps to generate your Product Requirements Document (PRD):

    1. Prepare Requirements: Copy the requirements template to your workspace and fill it out with your tools, workflow, and preferences.
      cp .claude/skills/create-second-brain-prd/my-second-brain-requirements.md ./my-second-brain-requirements.md
    2. Run the Command: Open Claude Code in your project and execute the following command, pointing it to your filled-out requirements file:
      /create-second-brain-prd ./my-second-brain-requirements.md

    Claude will research your stack and generate a 9-phase build plan at .agent/plans/second-brain-prd.md.

    /create-second-brain-prd ./my-second-brain-requirements.md