Create Second Brain Prd

Second Brain PRD Generator

Generate a personalized Product Requirements Document for building an AI Second Brain, based on the user's completed requirements template.

A blank template is bundled with this skill at `${CLAUDE_SKILL_DIR}/my-second-brain-requirements.md`. Copy it to your workspace and fill it out before running this skill.

Parameters

• `$0` (required) — Path to the filled-out requirements file (e.g., ./my-second-brain-requirements.md)
• `$1` (optional) — Output path for the PRD. Defaults to .agent/plans/second-brain-prd.md

Workflow

1. Read the requirements — Read the filled-out requirements file at $0. If no argument was provided, ask the user for the path. If they haven't filled one out yet, tell them a blank template is available at ${CLAUDE_SKILL_DIR}/my-second-brain-requirements.md — they should copy it to their workspace and fill it out first.

2. Load the architecture reference — Read ${CLAUDE_SKILL_DIR}/references/architecture-reference.md for the blueprint.

3. Research ALL tools and APIs — Do not assume familiarity with any platform or library. Even common APIs like Gmail or Slack have nuances, rate limits, and SDK-specific patterns that matter for implementation. For every tool in the user's stack, do web research to ensure the PRD contains accurate, specific guidance.

Always research these core dependencies:

• Claude Agent SDK — How to create conversations, system_prompt presets, setting_sources, allowed_tools, streaming responses, credential handling
• FastEmbed — ONNX model loading, batch embedding API, model cache configuration, supported models
• Hook system — Claude Code hook types (PreToolUse, PostToolUse, etc.), callback signatures, settings.json configuration

For every platform the user selected (Gmail, Slack, Linear, HubSpot, etc.):

• Authentication method (OAuth2 flow, API tokens, bot tokens, etc.)
• Key SDK/library to use (e.g., google-api-python-client, slack_sdk, etc.)
• The specific API endpoints needed for the user's top tasks
• Platform-specific setup requirements (e.g., Slack Socket Mode needs an App Token + Bot Token, Gmail needs OAuth consent screen published to Production for custom domains)
• Rate limits, pagination patterns, and common gotchas

The goal: Every phase in the PRD should contain enough technical specificity that a coding agent can implement it without guessing. Don't bloat the PRD with raw research - distill it into actionable implementation notes per phase.

4. Generate the PRD — Create a phased build plan at the output path ($1, or .agent/plans/second-brain-prd.md if not specified) with these sections:

PRD Structure

The output PRD should have:

Header:

• Project name (personalized: "[User's Name]'s Second Brain")
• Date generated
• Summary: 1-2 sentences based on their top tasks

Phase 1: Foundation (Memory Layer)

• Set up the memory vault folder using the name they specified in "Memory vault folder name" (e.g., MyVault/Memory/). Do NOT hardcode "Dynamous" — always use their chosen name.
• If they're using Obsidian, mention it as the viewer; if not, note that the vault is just a folder of markdown files that works with any editor.
• Create SOUL.md, USER.md, MEMORY.md, BOOTSTRAP.md, daily/ structure
• BOOTSTRAP.md is a first-run onboarding script: on the user's very first Claude Code session, it drives an interactive conversation to personalize USER.md, SOUL.md, and HEARTBEAT.md (asks about name, timezone, role, communication style, integrations, proactivity preferences — one question at a time). It deletes itself after onboarding completes. If a session ends mid-onboarding, the file persists and picks up next time. The SessionStart hook should detect BOOTSTRAP.md and inject it into context.
• Create CLAUDE.md at the repo root — this is Claude Code's project instruction file, loaded into every conversation. Initialize it with: project description, key paths (vault, scripts, hooks, skills, data directories), project conventions (timezone, advisor mode, no secrets in vault, checkbox syntax, YAML frontmatter), and a "Completed Phases" section to be updated after each phase. Also add a "Build Commands" section — start with placeholder entries and populate with real commands as each phase introduces them. This file is the agent's reference for how to interact with the project.
• Customize each file based on their "About You" and "Memory Categories" answers
• Key files to create, estimated complexity: Low

Phase 2: Hooks (Context Persistence)

• SessionStart hook (inject memory into every conversation — should also detect and inject BOOTSTRAP.md for first-run onboarding)
• PreCompact hook (extract conversation context → spawn background memory_flush.py)
• SessionEnd hook (same pattern — extract context → spawn background flush)
• memory_flush.py: Background Agent SDK script spawned by PreCompact/SessionEnd. Uses Claude with allowed_tools=[] (pure reasoning, no tools) to intelligently decide what decisions, lessons, and facts from the conversation are worth saving. Writes bullet-point summary to daily log. Has deduplication and file locking. This is critical — without it, daily logs contain mechanical transcript excerpts instead of intelligent summaries that the daily reflection can actually promote to MEMORY.md.
• Hook recursion prevention: Every Agent SDK session (heartbeat, reflection, chat, memory flush) must set os.environ["CLAUDE_INVOKED_BY"] = "<name>". SessionEnd and PreCompact hooks check this env var and skip if set — this prevents Agent SDK exits from triggering additional flushes, which would cause duplicate log entries or infinite recursion.
• Shared utilities (shared.py): Cross-platform file locking (file_lock() using msvcrt on Windows / fcntl on Unix) for concurrent write safety, retry with exponential backoff (with_retry()) for external API calls, and atomic state writes. Multiple processes (heartbeat, reflection, chat, flush) write to daily logs and state files concurrently — without file locking, they corrupt each other.
• Key files, estimated complexity: Medium

Phase 3: Memory Search (Hybrid RAG)

• Set up chunking + embedding pipeline
• SQLite + sqlite-vec + FTS5 (local) or Postgres + pgvector (VPS)
• Hybrid search: 0.7 vector + 0.3 keyword
• Key files, estimated complexity: Medium

Phase 4: Integrations (Their Top 3 First)

• Use their "Integration Priority" rankings
• For each: auth setup, API module, registry entry, query.py subcommand
• Reference the integration_template.py pattern
• Key files per integration, estimated complexity: Medium per integration

Phase 5: Skills (Starter Pack)

• Vault structure skill (teach agent their file organization)
• At least one custom skill based on their "Top Tasks"
• Skill anatomy: SKILL.md + scripts/ + references/
• Key files, estimated complexity: Low-Medium

Phase 6: Proactive Systems (Heartbeat + Reflection)

• Heartbeat flow must be staged as: (1) Python gathers data from integrations → (2) state diffing → (3) pre-flight guardrail agent (see Phase 8 — a separate no-tools Claude call that evaluates the sanitized external data and returns {verdict: "pass"|"fail"|"suspicious"} before the main heartbeat agent ever sees it; fail aborts the run, suspicious proceeds with warning) → (4) main Claude Agent SDK reasoning call with tools → (5) notify. The pre-flight guardrail step is not optional — it is the only semantic injection check in the security stack and must be wired directly into the heartbeat pipeline, not bolted on as a separate phase.
• State diffing (stage 2 of the heartbeat flow): implement build_snapshot(gmail_data, asana_data, slack_data, calendar_data, ...) and diff_snapshot(current, previous) functions that produce a hashable snapshot of each integration's current state and compute the delta vs. the previous run. Persist state at .claude/data/state/heartbeat-state.json (atomic writes via shared.py). Only the delta — new emails, newly overdue tasks, newly unread Slack messages — is passed into the main Claude reasoning call. This is the notification-fatigue solution: without state diffing, every 30-minute run re-surfaces the same unread emails and the user gets paged endlessly. Without this mechanism the heartbeat is unusable in production. Must be a named deliverable with these exact function names so students can trace the pattern in the generated PRD.
• Set schedule based on their proactivity level
• Daily reflection: promote important daily log items to MEMORY.md. Must include SOUL.md write-protection — a PreToolUse hook that blocks the reflection agent from editing SOUL.md. If the reflection wants to suggest changes to the agent's identity or rules, it writes those suggestions to the daily log instead. This prevents "soul drift" where the agent gradually rewrites its own personality without user approval.
• Map their proactivity level choice to specific heartbeat behaviors
• Draft management (required for Advisor/Assistant/Partner proactivity levels): The heartbeat must implement a full draft lifecycle system. Specifically: (1) scan integration data for emails, DMs, and community posts needing a reply, (2) generate draft replies in the user's voice using RAG on drafts/sent/ for voice-matching (memory_search.py --path-prefix drafts/sent), (3) write drafts as markdown files in drafts/active/ with YAML frontmatter (type, source_id, recipient, subject, context, created, status) + Original Message + Draft Reply sections, (4) expire drafts >24h old with no action by moving to drafts/expired/, (5) detect when the user has actually replied on the platform and move the file to drafts/sent/ capturing their real reply text. The heartbeat Agent SDK session needs Write/Edit tools to create draft files — read-only tools are insufficient. Drafting criteria should be defined in USER.md (what to draft, what to skip).
• Habits tracking: HABITS.md with customizable pillars, auto-detection rules for objective achievements, daily reset by heartbeat, late-day nudges for unchecked pillars
• Key files, estimated complexity: High

Phase 7: Chat Interface (Optional)

• Only include if they checked Chat/Messaging in platforms
• Slack/Discord bot with persistent conversations
• Platform adapter pattern for extensibility
• Key files, estimated complexity: High

Phase 8: Security Hardening

• Credential protection hook (block-secrets.py): PreToolUse hook that intercepts ALL file-access tools (Read, Bash, Grep, Edit, Write, Glob) and blocks access to .env files, API tokens, OAuth credentials, SSH keys, and other secrets. Also blocks Bash commands that would expose environment variables, and blocks writing scripts that would exfiltrate secrets to stdout. This is the most critical security component — without it, the LLM can accidentally read and expose every API key. Must be implemented as a separate, dedicated hook (not combined with the general command guard).
• Sanitize all external data (3-layer defense: pattern detection → markdown escaping → XML trust boundaries). XML wrapping must be paired with a TRUST_BOUNDARY_INSTRUCTION in the system prompt that explicitly tells Claude to treat anything inside <external_data> tags as data, not instructions — the wrapper without the instruction is half a defense.
• Pre-flight guardrail agent: before the main heartbeat agent processes incoming external data, run a separate Claude Agent SDK call with allowed_tools=[] that receives the sanitized context and returns {"verdict": "pass"|"fail"|"suspicious"}. On fail → abort the heartbeat run and log the blocked content. On suspicious → proceed with a warning in the daily log. On pass → continue to the main reasoning call. This is the only semantic check in the security stack (the other layers are all pattern-based) and catches injection attempts that slip past deterministic regex. Wire it into the Phase 6 heartbeat flow between state-diffing and the main agent call — not as a standalone utility.
• Command guardrails based on their Security Boundaries answers. Implementation must include a named DANGEROUS_BASH_PATTERNS list in shared.py with 30+ patterns covering destructive operations (rm -rf, dd, mkfs), credential exfiltration bypasses (curl to unknown hosts, wget piped to shell), package installation (pip install, npm install, brew install), privilege escalation (sudo, chmod 777), and outbound network calls to non-allowlisted domains. The check must recursively extract subshell $(...) and backtick ` ... constructs and re-check their contents (naive string matching is bypassable via $(echo rm\ -rf\ /)). Strip common binary path prefixes (/usr/bin/, /bin/) before matching. This is distinct from block-secrets.py (which protects credential files) — DANGEROUS_BASH_PATTERNS` protects against destructive and exfiltration commands, and both hooks run on every PreToolUse Bash call.
• API key isolation (Python CLI wrapper pattern)
• Key files, estimated complexity: Medium-High

Phase 9: Deployment

• Based on their Infrastructure answers
• Local: OS scheduler setup (Windows Task Scheduler / cron / launchd)
• If VPS: server setup, vault sync, SSH tunnel
• Vault sync with concat-both merge driver (required if user picked "Local + VPS"): use git-sync (simonthum/git-sync or equivalent) on a 2-minute timer on both machines to sync the vault via Git. Daily logs (Memory/daily/*.md) are append-only and get written concurrently by heartbeat, reflection, chat, and flush processes on both machines — naive Git merging produces conflicts on every sync. Solution: register a custom concat-both merge driver in .gitattributes that maps Memory/daily/*.md to a script which concatenates additions from both sides instead of conflicting. The driver script (git-merge-concat) takes ancestor/local/remote versions, uses remote as base, appends any lines local added that aren't already present. Without this driver, vault sync will break within the first day of real use and the user will abandon the system. Must be a named deliverable with the script path, .gitattributes entry, and the git config merge.concat-both.driver registration command per machine.
• Cost estimate based on their choices

Each phase includes:

• What to build (1-2 sentences)
• Key files to create (with paths)
• Dependencies (which phases must come first)
• Estimated complexity (Low / Medium / High)
• Personalization notes (how their specific answers shape this phase)
• CLAUDE.md update reminder: Every phase must end by updating CLAUDE.md with any new paths, build commands, and conventions introduced. This keeps the agent's project reference current — if a command exists but isn't in CLAUDE.md, the agent won't know about it.

Footer:

• Recommended build order (phases are mostly sequential but some can parallel)
• "This PRD was generated from your requirements. Revisit and update as your system evolves."

5. Confirm output — Tell the user where the PRD was saved (the output path) and suggest they start with Phase 1.

Personalization Rules

• Use THEIR vault folder name everywhere in file paths (not "Dynamous" — use whatever they wrote in "Memory vault folder name"). For example, if they wrote "SecondBrain", all paths should be SecondBrain/Memory/, SecondBrain/Memory/daily/, etc.
• If they are NOT using Obsidian, don't mention Obsidian in the PRD — just refer to the vault as a "memory vault" or "markdown folder". If they ARE using Obsidian, mention it as the viewer/editor.
• Use THEIR platform names everywhere (not generic "email" — use "Gmail" if that's what they chose)
• Map their proactivity level to concrete behaviors:
• Observer → heartbeat notifications only, no drafting, no habit tracking
• Advisor → heartbeat + draft emails/messages for review, habit tracking with suggestions but no auto-check
• Assistant → heartbeat + drafts + auto-organize files + auto-log, habit auto-detection for objective pillars
• Partner → all of the above + send low-risk messages + auto-complete routine tasks + full habit auto-detection
• Map their security boundaries directly into Phase 8 guardrail rules
• Use their memory categories to structure the vault folders in Phase 1
• Their integration priority determines Phase 4 order

My Second Brain - Requirements Template

Fill this out during the workshop (Section 1.4). Your answers feed directly into the /create-second-brain-prd <path to this file> command, which generates your personalized build plan.

---

1. About You

• Name: Alex Rivera
• Role/Title: Engineering Manager
• What I do daily (1-2 sentences): I lead a cross-functional team building a SaaS product, splitting my time between technical planning, team coordination, and stakeholder communication.
• Timezone: Eastern (US)

---

2. Your Platforms

Check every platform you actively use and fill in the specific tool:

• [X] Email (e.g., Gmail, Outlook): Gmail
• [X] Calendar (e.g., Google Calendar, Outlook Calendar): Google Calendar
• [X] Task Management (e.g., Asana, Linear, Todoist, Jira): Linear
• [X] Chat/Messaging (e.g., Slack, Discord, Teams): Slack
• [X] Notes/Documents (e.g., Notion, Obsidian, Google Docs): Obsidian
• [ ] Cloud Storage (e.g., Google Drive, Dropbox, OneDrive): ___
• [X] Code Hosting (e.g., GitHub, GitLab): GitHub
• [ ] Community (e.g., Circle, Discord server, Mighty Networks): ___
• [ ] CRM (e.g., HubSpot, Salesforce, Pipedrive): ___
• [ ] Other: ___

---

3. Top Tasks for AI

List 3-5 tasks you'd want your second brain to handle proactively:

Examples:

• Draft email replies to important messages
• Track deadlines and remind me before they're due
• Summarize what happened in Slack while I was away
• Monitor community for questions that need my attention
• Keep my meeting notes organized and searchable

My list:

1. Draft email replies to important messages 2. Track deadlines and remind me before they're due 3. Summarize what happened in Slack while I was away 4. Monitor Slack for messages from my team that need a response 5. Keep my meeting notes organized and searchable 6. Do the initial code review sweep for PRs and issues

---

4. Proactivity Level

How bold should your agent be? Pick one:

• [ ] Observer - Notify only, never take action
• [X] Advisor - Draft things for my review, but never send or post
• [ ] Assistant - Act on low-risk items (log notes, organize files), ask for high-risk
• [ ] Partner - Act autonomously on most things, ask only for irreversible actions

---

5. Security Boundaries

What should your agent NEVER do without explicit permission?

• [X] Send emails or messages on my behalf
• [X] Post to social media
• [ ] Modify files outside the memory vault
• [X] Access financial data or make purchases
• [X] Delete anything
• [X] Other: Send messages on Slack

---

6. Memory Categories

What types of knowledge matter most to you? Check all that apply and add your own:

• [X] Meeting notes and decisions
• [X] Project status and progress
• [ ] Client/customer information
• [X] Research and learning notes
• [X] Personal goals and habits
• [X] Content ideas and drafts
• [X] Team context (who does what, preferences, timezones)
• [ ] Other: ___

---

7. Infrastructure

• Operating System: [X] Windows [ ] macOS [ ] Linux
• Deployment: [ ] Local only [X] Local + cloud server (VPS)
• Existing tools I already have set up: I already use Obsidian and have a DigitalOcean droplet. Gmail and Slack are ready to integrate. GitHub and Linear accounts are active.

(e.g., "I already use Obsidian", "I have a DigitalOcean droplet", "I'm comfortable with the terminal")

---

8. Integration Priority

Rank your top 3 integrations to build first (from your answers in Section 2):

1. Gmail 2. Slack 3. GitHub

---

After filling this out, run: /create-second-brain-prd <path to this file>

My Second Brain - Requirements Template

Fill this out during the workshop (Section 1.4). Your answers feed directly into the /create-second-brain-prd <path to this file> command, which generates your personalized build plan.

---

1. About You

• Name: ___
• Role/Title: ___
• What I do daily (1-2 sentences): ___
• Timezone: ___
• Memory vault folder name: ___ (e.g., "SecondBrain", "MyVault", "Memory" — this is the root folder for all your memory files)
• Using Obsidian? [ ] Yes [ ] No (Obsidian is optional — the vault is just a folder of markdown files. Obsidian provides a nice UI for browsing/editing them, but everything works without it.)

---

2. Your Platforms

Check every platform you actively use and fill in the specific tool:

• [ ] Email (e.g., Gmail, Outlook): ___
• [ ] Calendar (e.g., Google Calendar, Outlook Calendar): ___
• [ ] Task Management (e.g., Asana, Linear, Todoist, Jira): ___
• [ ] Chat/Messaging (e.g., Slack, Discord, Teams): ___
• [ ] Notes/Documents (e.g., Notion, Obsidian, Google Docs): ___
• [ ] Cloud Storage (e.g., Google Drive, Dropbox, OneDrive): ___
• [ ] Code Hosting (e.g., GitHub, GitLab): ___
• [ ] Community (e.g., Circle, Discord server, Mighty Networks): ___
• [ ] CRM (e.g., HubSpot, Salesforce, Pipedrive): ___
• [ ] Other: ___

---

3. Top Tasks for AI

List 3-5 tasks you'd want your second brain to handle proactively:

Examples:

• Draft email replies to important messages
• Track deadlines and remind me before they're due
• Summarize what happened in Slack while I was away
• Monitor community for questions that need my attention
• Keep my meeting notes organized and searchable

My list:

1. ___ 2. ___ 3. ___ 4. ___ 5. ___

---

4. Proactivity Level

How bold should your agent be? Pick one:

• [ ] Observer - Notify only, never take action
• [ ] Advisor - Draft things for my review, but never send or post
• [ ] Assistant - Act on low-risk items (log notes, organize files), ask for high-risk
• [ ] Partner - Act autonomously on most things, ask only for irreversible actions

---

5. Security Boundaries

What should your agent NEVER do without explicit permission?

• [ ] Send emails or messages on my behalf
• [ ] Post to social media
• [ ] Modify files outside the memory vault
• [ ] Access financial data or make purchases
• [ ] Delete anything
• [ ] Other: ___

---

6. Memory Categories

What types of knowledge matter most to you? Check all that apply and add your own:

• [ ] Meeting notes and decisions
• [ ] Project status and progress
• [ ] Client/customer information
• [ ] Research and learning notes
• [ ] Personal goals and habits
• [ ] Content ideas and drafts
• [ ] Team context (who does what, preferences, timezones)
• [ ] Other: ___

---

7. Infrastructure

• Operating System: [ ] Windows [ ] macOS [ ] Linux
• Deployment: [ ] Local only [ ] Local + cloud server (VPS)
• Existing tools I already have set up: ___

(e.g., "I already use Obsidian", "I have a DigitalOcean droplet", "I'm comfortable with the terminal")

---

8. Integration Priority

Rank your top 3 integrations to build first (from your answers in Section 2):

1. ___ 2. ___ 3. ___

---

After filling this out, run: /create-second-brain-prd <path to this file>

Second Brain Architecture Reference

This is the reference architecture for a fully-featured AI Second Brain built with Claude Code and the Claude Agent SDK. Use this as the blueprint when generating personalized PRDs.

Project Configuration

CLAUDE.md (Project Instructions)

CLAUDE.md at the repo root is Claude Code's project-level instruction file — it's automatically loaded into every conversation. This is where the agent learns about the project's structure, available commands, and conventions. It should contain:

• Key paths: Where memory files, scripts, hooks, skills, data, and config live
• Build commands: Every runnable command in the project (memory search, indexing, integration queries, heartbeat, reflection, notifications, scheduler setup, chat bot, security tests, vault sync). These serve as a quick reference so the agent knows exactly how to invoke any part of the system without guessing.
• Project conventions: PRD as source of truth, phase-by-phase execution, memory file conciseness rules, checkbox syntax, YAML frontmatter requirements, timezone, advisor mode behavior, no-secrets-in-vault rule
• Completed phases: Brief summary of what was built in each phase, with gotchas and notes discovered during implementation

Critical rule: Every phase must update CLAUDE.md with any new paths, commands, or conventions introduced. CLAUDE.md is a living document that grows with the project — if a command exists but isn't in CLAUDE.md, the agent won't know about it.

Core Components

Memory Layer (Foundation)

• Memory vault at <VaultName>/Memory/ (a local folder of markdown files — Obsidian can be used as a viewer but is optional)
• SOUL.md: Agent personality, behavioral rules, communication style, boundaries
• USER.md: User profile, account IDs, integration config, preferences, team info
• MEMORY.md: Key decisions, lessons learned, active projects, important facts (must stay concise — loaded into every conversation)
• BOOTSTRAP.md: First-run onboarding script — on the user's very first session, this file drives an interactive conversation (asking about name, timezone, role, communication style, integrations, proactivity preferences one question at a time) to personalize USER.md, SOUL.md, and HEARTBEAT.md. Deletes itself after onboarding is complete. If a session ends mid-onboarding, the file persists and picks up where it left off next time.
• daily/YYYY-MM-DD.md: Append-only timestamped logs — everything goes here first
• HEARTBEAT.md: Checklist of what the heartbeat should monitor
• Why local files: zero latency, no API auth, no rate limits, native LLM read/write

Hooks (Context Persistence)

Three lifecycle hooks in .claude/hooks/, plus a background summarizer:

• SessionStart (session-start-context.py): Reads SOUL.md + USER.md + MEMORY.md + recent daily logs → injects into conversation context
• PreCompact (pre-compact-flush.py): Before auto-compaction, extracts conversation context → writes to temp file → spawns background memory_flush.py
• SessionEnd (session-end-flush.py): On session end, same pattern — extracts context and spawns background flush
• Memory Flush (memory_flush.py): Background Agent SDK script spawned by PreCompact/SessionEnd. Reads conversation context from a temp file, uses Claude (with allowed_tools=[], pure reasoning) to intelligently decide what decisions, lessons, and facts are worth saving. Writes bullet-point summary to daily log, or "FLUSH_OK" if nothing important. Has deduplication (skips if same session flushed <60s ago) and file locking for concurrency safety. This is what makes the daily logs contain intelligent summaries rather than mechanical transcript excerpts.
• Hook recursion prevention: Every Agent SDK session (heartbeat, reflection, chat, memory flush) must set CLAUDE_INVOKED_BY env var to its name (e.g., os.environ["CLAUDE_INVOKED_BY"] = "heartbeat"). SessionEnd and PreCompact hooks check this and skip if set — otherwise, every Agent SDK exit spawns another flush, which creates another session, which triggers another SessionEnd. Without this, you get duplicate daily log entries or infinite recursion.
• Configured in .claude/settings.json

Memory Search (Hybrid RAG)

Pipeline: Markdown files → chunking (~400 tokens, overlapping) → FastEmbed ONNX (all-MiniLM-L6-v2, 384-dim) → index → hybrid merge (0.7 vector + 0.3 keyword)

• SQLite: sqlite-vec for vectors, FTS5 for keywords
• Postgres: pgvector for vectors, tsvector+GIN for keywords
• Key files: db.py (abstraction), embeddings.py, memory_index.py, memory_search.py
• Incremental: only changed files re-indexed

Integrations (Platform Connections)

Pattern: Each integration is a Python module in .claude/scripts/integrations/:

• Data model (dataclass) → Auth function → Query functions → Context formatter → CLI
• Registry (registry.py): Tracks available integrations, checks which are enabled
• CLI wrapper (query.py): Unified interface — query.py gmail list, query.py asana overdue
• Auth: Google OAuth2 (shared token) or API tokens in .env
• Template: integration_template.py — copy, rename, fill in TODOs
• LLM never sees API tokens — Python handles auth, passes only data

Skills (Extensible Capabilities)

Modular packages at .claude/skills/*/SKILL.md:

• SKILL.md: YAML frontmatter (name, description) + markdown instructions
• scripts/: Executable code for deterministic tasks
• references/: Documentation loaded on demand
• assets/: Files used in output (templates, images)
• Progressive disclosure: metadata always loaded (~100 words), body on trigger, resources on demand
• Invoked via /skill-name or automatically by the agent

Heartbeat (Proactive Monitoring)

Scheduled script at .claude/scripts/heartbeat.py:

• Runs every 30 minutes during active hours
• Python gathers data from all integrations BEFORE invoking Claude
• Claude Agent SDK reasons over pre-loaded context → decides what needs attention
• Notifications: Windows Toast / macOS osascript / Linux notify-send + Slack
• State diffing: build_snapshot() → diff_snapshot() → only notify on changes
• Cost: ~$0.05/run (vs $0.38 with MCP tool calls)
• State: .claude/data/state/heartbeat-state.json

Daily Reflection (Memory Curation)

Scheduled script at .claude/scripts/memory_reflect.py:

• Runs daily at 8 AM
• Reviews yesterday's daily log
• Promotes important items (decisions, lessons, facts) to MEMORY.md
• SOUL.md write-protection: The reflection agent must have a PreToolUse hook that blocks Edit/Write on SOUL.md. If the reflection wants to suggest changes to the agent's identity or behavioral rules, it writes those suggestions to the daily log instead. This prevents "soul drift" where the agent gradually rewrites its own personality without the user's explicit approval.
• Mirrors human memory: short-term experiences → sleep consolidation → long-term storage

Habits Tracking

File at Memory/HABITS.md:

• 3-5 customizable "pillars" representing areas of daily improvement (e.g., main project, community, relationships, health, side project)
• Each pillar has auto-detection rules: objective achievements can be auto-checked by the heartbeat, personal/relational pillars require self-reporting
• Daily reset: heartbeat archives yesterday's checklist to a History section and creates a fresh checklist each morning
• Heartbeat integration: suggests specific actions for unchecked pillars using calendar/tasks/email context, nudges late in the day if pillars are still unchecked
• Inspired by James Clear's Atomic Habits - the goal is one intentional improvement per day per pillar

Draft Management (Email/Message Drafting)

Lifecycle system for auto-generated reply drafts:

• Active (Memory/drafts/active/): Heartbeat scans emails, community posts, and DMs that need a reply, then generates a draft in the user's voice
• Sent (Memory/drafts/sent/): When the user replies on the actual platform, the heartbeat captures their real reply text (not the draft) and moves the file here
• Expired (Memory/drafts/expired/): Drafts older than 24 hours with no reply get moved here automatically
• Voice-matching via RAG: When drafting new replies, search drafts/sent/ with memory_search.py --path-prefix drafts/sent to find similar past replies and match the user's tone
• File format: YYYY-MM-DD_<type>_<slugified-name>.md with YAML frontmatter (type, source_id, recipient, subject, context, created, status) + Original Message section + Draft Reply section
• Drafting criteria defined in USER.md (what to draft, what to skip)

Chat Interface (Conversational Access)

Located at .claude/chat/:

• Slack DM or @mention → platform-agnostic message → Agent SDK conversation → response
• Each thread = separate persistent conversation (survives restarts)
• PlatformAdapter protocol: SlackAdapter today, extensible to Discord/Teams
• Session store: SQLite database at .claude/data/chat.db
• Socket Mode: outbound WebSocket, no public URL needed

Security (Four Layers)

1. Credential Protection (block-secrets.py): PreToolUse hook that intercepts Read, Bash, Grep, Edit, Write, and Glob tool calls. Blocks access to sensitive files (.env, .pem, .key, credentials.json, google_token.json, SSH keys, etc.). Blocks Bash commands that would expose environment variables (cat .env, printenv, echo $TOKEN, python -c os.environ, etc.). Blocks writing scripts that would exfiltrate secrets to stdout. Recursively checks subshell content. This is the most critical security layer — without it, the LLM can accidentally read and expose every API key. 2. Sanitize (sanitize.py): Pattern detection → markdown escaping → XML trust boundaries for all external text 3. Guardrails (shared.py): Deterministic pre-check (dangerous command patterns) + LLM evaluation (pass/fail/suspicious) 4. API Key Isolation: Python CLI wrapper handles auth, LLM only sees data — never tokens

Infrastructure

• Local (Windows/Mac/Linux): SQLite + sqlite-vec, FTS5, OS scheduler, ~80MB model cache
• VPS (Linux, optional): Postgres + pgvector, tsvector + GIN, systemd timers, headless OAuth
• Vault Sync: git-sync (2-min intervals) between local ↔ VPS
• Cost: Claude Max ~$100/mo + VPS $5-24/mo + Obsidian (free) ≈ $105-128/mo

Shared Utilities (Cross-Cutting Concerns)

Reusable module at .claude/scripts/shared.py:

• Cross-platform file locking: A file_lock() context manager using msvcrt on Windows and fcntl on Unix. Required because multiple processes write to the same files concurrently — heartbeat writes to daily log and state files, reflection writes to MEMORY.md and daily log, memory flush writes to daily log, chat writes to daily log, and vault sync pulls remote changes. Without file locking, concurrent writes corrupt state files or produce garbled daily log entries. Use it around every append_to_daily_log() call, every save_state() call, and in the reflection's MEMORY.md update.
• Retry with exponential backoff: A with_retry() wrapper for all external API calls (Gmail, Slack, Asana, Calendar, Circle). Handles HTTP 429 (rate limit), 500, 502, 503 with configurable max retries and backoff. Without this, a single rate-limited API call crashes the entire heartbeat run.
• Atomic state writes: Write to a .tmp file then os.replace() to the final path — prevents partial writes from corrupting JSON state files on crash.

Key Design Principles

1. Local files are king — Zero latency, no API auth, no rate limits 2. Deterministic + LLM hybrid — Python gathers data, Claude reasons 3. Security-first — Read-only by default, API key isolation, sanitize everything 4. Evolve, don't over-engineer — Start simple, add capabilities as trust grows 5. Everything is a file — Markdown for memory, Python for logic, JSON for state