Stop Drowning in Notes! COG-second-brain Actually Self-Evolves

What if your note-taking system didn't just store your thoughts—but actually thought alongside you?

Here's the brutal truth most productivity hackers won't admit: Your second brain is brain-dead. Notion databases turn into graveyards. Obsidian vaults swell into unsearchable monsters. Roam's block references become digital spaghetti. You spend more time organizing than thinking. The average knowledge worker loses 4.3 hours weekly to note management—and still can't find that crucial insight when they need it.

But what if your system could auto-classify your midnight braindumps? Cross-reference your team's GitHub commits with Slack threads and Linear tickets? Surface patterns you'd never spot yourself? And do it all with zero vendor lock-in—just plain .md files that work with any AI agent you already use?

Meet COG-second-brain—the self-evolving knowledge system that turns your markdown files into autonomous intelligence. Inspired by Y Combinator CEO Garry Tan's personal stacks, COG deploys 17 specialized AI skills and 6 worker agents to transform raw capture into structured wisdom. No database. No monthly SaaS bill. No proprietary format holding your intellectual property hostage.

Ready to stop being your note system's janitor—and start being its commander?

What is COG-second-brain?

COG stands for Cognition + Obsidian + Git—three pillars of a radical approach to personal knowledge management. Created by developer Huy Tieu, COG-second-brain is an open-source framework that transforms any folder of markdown files into an agentic second brain capable of autonomous evolution.

The project exploded from a simple insight: AI agents are finally good enough to manage knowledge, not just generate it. While everyone's chasing chatbot interfaces, Tieu asked a deeper question—what if AI worked inside your existing files, learning your patterns, maintaining your systems, and surfacing insights without you asking?

COG's architecture draws heavily from Garry Tan's gstack and gbrain—personal productivity systems the YC CEO built for his own workflow. Tieu adapted Tan's "specialist session" pattern (cheap models for I/O, expensive models for reasoning) and "Compiled Truth" knowledge philosophy into something any developer can clone and run in minutes.

Why it's trending now: The convergence of three forces makes COG's timing perfect. First, Claude Code, Cursor, Kiro, Gemini CLI, and OpenAI Codex now read markdown natively—no API integration required. Second, developers are rebelling against SaaS lock-in after Notion outages and Obsidian's sync pricing. Third, AI context windows finally support entire vaults, enabling true systemic intelligence rather than isolated chat sessions.

COG isn't an app. It's a protocol—a set of conventions, skills, and worker patterns that turn your filesystem into a thinking partner. The entire system lives in your repo, version-controlled, portable, and completely yours.

Key Features That Separate COG from Everything Else

Self-Evolving Architecture COG doesn't just store—it learns your patterns. Daily braindumps get auto-classified by domain. Weekly cross-domain analysis surfaces hidden connections. Monthly consolidation transforms scattered notes into reusable frameworks. The system literally improves its own organization based on how you actually think.

Worker Agent Economy Six specialist workers handle data-heavy tasks using Claude Sonnet (cheap, fast), while your lead session uses Claude Opus (deep reasoning) for synthesis. Workers write to /tmp/ files and return only status + path—eliminating expensive token generation in agent output. This isn't theoretical; it's proven cost optimization borrowed directly from production AI systems.

Verification-First Intelligence Every claim requires sources with confidence levels. News briefings enforce 7-day freshness. People CRM profiles include evidence citations. COG won't hallucinate your knowledge base—it builds it from verified ground truth.

Privacy-By-Design Local .md files only. Strict domain separation (personal vs. professional). No external servers, no data mining, no "we updated our privacy policy." Your thoughts stay your property, in your repo, on your devices.

Multi-Agent, Multi-Platform Native skill surfaces for Claude Code (17 skills), Kiro (7 powers), Gemini CLI (7 commands), plus Cursor plugin manifest and universal AGENTS.md fallback. One codebase, every major AI agent. Switch tools without migrating your knowledge.

Zero-Maintenance Updates Framework files (skills, docs, scripts) separate cleanly from your content (braindumps, profiles, notes). Run "Update COG" and the system patches itself without touching your data. Customized files? COG detects conflicts and lets you choose per-file.

Obsidian-Native Workflows Emoji date format (📅 2024-01-15) works with Obsidian Tasks plugin dashboards. Your vault looks normal in Obsidian but thinks autonomously when agents read it.

5 Brutally Practical Use Cases

1. The Founder Who Never Loses a Strategic Insight

You're pitching VCs, managing a team, and somehow expected to also track market signals. COG's braindump skill captures your 2 AM realizations with intelligent classification. Weekly-checkin cross-references your notes with daily-brief news intelligence. Knowledge-consolidation builds frameworks from six months of scattered observations. When board prep looms, comprehensive-analysis generates an 8-12 minute deep dive with sourced claims.

2. The Engineering Lead Drowning in Team Context

GitHub commits, Linear tickets, Slack threads, PostHog analytics—your team's work is fragmented across platforms. COG's team-brief skill pulls from all four sources into a single daily intelligence brief with two-way Linear sync-back. Meeting-transcript processing extracts decisions and action items. People CRM auto-builds profiles of team members with progressive enrichment: 1 mention creates a stub, 3 mentions builds an executive snapshot, 8+ mentions generates a complete working-style profile.

3. The Product Manager's Full Lifecycle

From auto-research (deep multi-agent investigation) → generate-prd (with approval gate before Confluence publish) → create-user-story (duplicate-checked across Linear/GitHub/Jira) → development → generate-release-notes → update-knowledge-base. COG doesn't just document your PM work—it orchestrates it. The /export-open-issues skill audits any tracker into a structured vault summary when stakeholders demand visibility.

4. The Researcher Building Citable Knowledge

Academic or market research generates hundreds of sources that never connect. COG's auto-research decomposes questions into parallel research threads with multiple agents, each citing sources. Knowledge-consolidation builds frameworks from findings. Every observation includes confidence levels and citations. Your vault becomes a verifiable knowledge graph, not a bookmark graveyard.

5. The Multi-Device Knowledge Worker

Capture on iPhone via iCloud sync. Process on Mac with Claude Code. Review on iPad in Obsidian. Git provides version history and backup. COG's vault structure works identically across devices because it's just markdown files—no proprietary sync engine, no format conversion, no lock-in.

Step-by-Step Installation & Setup Guide

Prerequisites

• Git installed
• An AI agent that reads markdown (Claude Code, Cursor, Kiro, Gemini CLI, or OpenAI Codex)
• Optional: GitHub CLI (gh) for team skills, iCloud for mobile sync, Obsidian for visualization

Installation

Step 1: Clone the repository

# Clone COG-second-brain to your local machine
git clone https://github.com/huytieu/COG-second-brain.git
cd COG-second-brain

Step 2: Launch your agent and run onboarding

Alternative: Install via skills.sh (fastest)

# One-line installation through the skills registry
npx skills add huytieu/COG-second-brain

Step 3: Personalize during onboarding The onboarding skill will:

• Detect your role and suggest a role pack (Product Manager, Engineering Lead, Engineer, Designer, Founder, or Marketer)
• Configure your vault structure in 00-inbox/
• Set up integrations (GitHub CLI, Linear, Slack, PostHog) if available
• Explain the evolution cycle and daily workflows

Step 4: Optional configuration (see SETUP.md)

# Enable Git sync for version history
git remote add origin your-private-repo-url

# Enable iCloud sync (macOS/iOS)
# Move vault to ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/

# Validate your agent surface
./scripts/validate-agent-surface.sh

Step 5: Start your first braindump

"I need to braindump"

COG classifies, extracts action items, and files it automatically.

REAL Code Examples from COG-second-brain

COG's power lives in its skill definitions and worker orchestration. Here are actual patterns from the repository:

Example 1: Worker Agent Architecture

COG implements Garry Tan's specialist session pattern with explicit model routing. Workers handle data I/O cheaply; the lead agent reasons deeply:

<!-- .claude/agents/worker-data-collector.md -->
# Worker: Data Collector

## Role
Structured extraction from GitHub, Slack, Jira, Linear APIs

## Model
claude-sonnet-4-20250514  # Cheap, fast, large context

## Output Protocol
1. Write structured results to `/tmp/cog-{task-id}-{timestamp}.md`
2. Return ONLY: `STATUS: complete | PATH: /tmp/cog-{task-id}-{timestamp}.md`
3. NEVER return raw data in response text

## Rationale
Eliminates slow token generation in agent output. Lead session (Opus) 
reads tmp file for synthesis. Cost reduction: ~80% vs. single-agent approach.

Why this matters: The STATUS | PATH protocol is deliberately minimal. Workers burn cheap Sonnet tokens on data formatting, while your expensive Opus session only reads the compressed result. This pattern—borrowed from gstack's "explicit gears" philosophy—makes multi-agent workflows economically viable for daily use.

Example 2: People CRM Tiered Enrichment

Progressive profile building with evidence requirements:

<!-- 05-knowledge/people/jane-doe.md (auto-generated) -->
# Jane Doe

## Tier 2 Profile (3 mentions, last: 2024-01-15)

### Executive Snapshot
- Role: Senior PM, Platform Team
- Tenure: 2.5 years at company
- [Source: team-brief 2024-01-08, confidence: high]

### Working Style
- Prefers async written updates over meetings
- Deep-dive on Fridays, light coordination Mon-Thu
- [Source: meeting-transcript 2024-01-10, confidence: medium]

### Strengths
- Cross-functional alignment without authority
- Technical depth from engineering background
- [Source: weekly-checkin pattern analysis, confidence: high]

### Evidence Log
| Date | Observation | Source | Confidence |
|------|-------------|--------|------------|
| 2024-01-08 | Mentioned in team-brief as blocking dependency | team-brief | high |
| 2024-01-10 | Led architecture review meeting | meeting-transcript | medium |
| 2024-01-15 | Resolved cross-team conflict in #platform | url-dump (Slack) | high |

The intelligence: At Tier 3 (1 mention), COG creates only name, role, one-line context. At Tier 2 (3+ mentions), it builds executive snapshot, working style, and strengths. Tier 1 (8+ mentions or direct meeting) triggers complete profiling. Every claim carries source citations with confidence levels—no hallucinated colleague profiles.

Example 3: Update System with Conflict Detection

Safe framework updates that never overwrite your content:

#!/bin/bash
# cog-update.sh — Self-healing framework updates

# Check for drift between your customizations and upstream
./scripts/validate-agent-surface.sh

# Fetch latest framework (never touches 00-06 content directories)
git fetch cog-upstream main

# Interactive per-file resolution
git checkout cog-upstream/main -- \
  .claude/skills/ \
  .claude/agents/ \
  .claude/roles/ \
  scripts/ \
  AGENTS.md \
  CLAUDE.md \
  COG-VERSION

# Detect customized files and prompt for resolution
for file in $(git diff --name-only cog-upstream/main HEAD -- .claude/skills/); do
  if [[ -n $(git diff HEAD -- "$file") ]]; then
    echo "⚠️  CUSTOMIZED: $file"
    echo "   [k]eep yours | [u]se upstream | [b]ackup + update"
    read -r choice
    case $choice in
      k) git checkout HEAD -- "$file" ;;
      u) ;;  # already checked out
      b) cp "$file" "${file}.backup.$(date +%s)" ;;
    esac
  fi
done

The protection: COG's directory convention separates framework (.claude/, scripts/, docs) from content (00-inbox/ through 06-templates/). The update script only touches framework directories. Even then, it detects your customizations and offers per-file resolution—no blanket overwrites, no lost work.

Example 4: Daily Brief Skill Definition

The actual skill that powers verified news intelligence:

<!-- .claude/skills/daily-brief.md -->
# Skill: Daily Brief

## Trigger
"Give me my daily brief"

## Verification Requirements
- [ ] All claims include primary source URL
- [ ] News freshness ≤ 7 days
- [ ] Confidence level annotated (high/medium/low)
- [ ] Contradictory sources both presented

## Output Format
```markdown
# Daily Brief — {{date}}

## Your Domains (auto-detected from vault)
{{#each domains}}
### {{name}}
{{#each stories}}
- **{{headline}}** [{{source.name}}]({{source.url}}) — confidence: {{confidence}}
  - Key insight: {{insight}}
  - Action needed? {{action}}
{{/each}}
{{/each}}

## Cross-Domain Patterns
{{pattern_analysis}}

## Sources Consulted
{{source_list_with_dates}}

Failure Mode

If sources fail verification, output: "⚠️ Brief incomplete — {{reason}}. Proceed with {{count}} verified items?"

**The rigor:** This isn't prompt engineering—it's **protocol design**. The verification checklist, explicit failure mode, and structured output format make the skill **deterministically reliable** across different AI models and sessions.

---

## Advanced Usage & Best Practices

**Role Pack Optimization**
Don't skip onboarding's role selection. The **Engineer** pack prioritizes code documentation and technical research. The **Founder** pack weights market intelligence and investor updates. The **Product Manager** pack surfaces PRD and story workflows. Wrong pack = buried features you'll never discover.

**Worker Agent Cost Control**
Monitor your `/tmp/` directory size—workers can generate substantial artifacts. Set a cron job to clean files older than 7 days:
```bash
find /tmp -name "cog-*" -mtime +7 -delete

Git Branch Strategy for Sensitive Content Keep main for framework updates, personal for your braindumps, professional for work content. Merge selectively. COG's vault structure makes this natural—the numbered directories become branch boundaries.

Custom Skill Development Copy any SKILL.md from .claude/skills/ as template. The header format (Trigger, Requirements, Output Format, Failure Mode) is parsed by validation scripts. Follow it exactly for automatic documentation generation.

Obsidian Tasks Integration Use 📅 YYYY-MM-DD emoji format anywhere in your vault. The Tasks plugin picks it up for dashboard views. COG's skills recognize and generate this format automatically—no manual date formatting.

COG vs. The Competition: Why This Wins

The verdict: COG wins where it matters for technical users—extensibility, cost transparency, and agent-native design. Notion beats it for non-technical team collaboration. Obsidian alone lacks intelligence. Roam's block references feel archaic compared to agent-mediated synthesis. Mem.ai's AI is a black box; COG's is inspectable, hackable, yours.

FAQ: What Developers Actually Ask

Does COG work offline? Partially. The vault structure and local files work entirely offline. AI skills require API connectivity when invoked, but your captured braindumps and processed notes remain fully accessible. Unlike cloud-native tools, you never lose access to your data.

How much does daily usage cost in API tokens? Typical usage runs $0.50-2.00/day depending on skills invoked. Braindumps use ~$0.05. Team briefs with full integrations run ~$0.80. The worker agent architecture specifically optimizes for cost—Sonnet workers handle 80% of token volume at 1/6th Opus pricing.

Can I use COG with just Cursor, no Claude Code? Absolutely. Cursor's .cursor-plugin/ + .cursorrules surface provides core workflows. For full 17-skill access, AGENTS.md serves as universal fallback. Claude Code gets first-class treatment, but COG is deliberately agent-agnostic.

What happens to my data if I stop using COG? Nothing. It's your markdown files in your filesystem. Uninstall the framework, keep your vault. Zero export friction, zero format conversion. This is the anti-lock-in guarantee.

How does COG compare to building my own agent system? COG is that system—already built, battle-tested, with 120+ braindumps processed in production. The validation scripts, worker protocols, and update system represent months of iteration you'd replicate painfully. Fork and customize rather than starting from scratch.

Is this production-ready for team deployment? For personal/individual use: absolutely. For teams: the roadmap includes collaboration features with privacy preservation. Currently, each team member runs their own COG instance with shared integrations (GitHub, Linear) as coordination points.

Can COG replace my existing note-taking app? COG enhances rather than replaces. Use Obsidian for visualization, COG for intelligence. Use Notion for team wikis, COG for personal synthesis. The .md format ensures interoperability—you're never trapped in COG either.

Conclusion: Your Thoughts Deserve Better Than Storage

After weeks with COG-second-brain, one truth became undeniable: most "second brains" are glorified filing cabinets. They preserve information without producing insight. They accumulate without evolving. They demand your attention for maintenance rather than returning it with intelligence.

COG breaks this pattern through agentic architecture—not as a feature, but as a foundation. The 17 skills aren't chatbot commands; they're cognitive workflows that learn your patterns. The 6 workers aren't cost optimizations; they're specialized expertise that scales your attention. The .md format isn't nostalgia; it's sovereignty over your intellectual property.

The repository is free, open-source, and ready to clone. The onboarding takes under 2 minutes. The first braindump will show you what's been missing.

Stop archiving your thoughts. Start evolving them.

👉 Get COG-second-brain on GitHub — Star it, fork it, make it yours. The future of knowledge management isn't another app. It's your files, finally thinking for themselves.