second-brain

Use this skill when managing persistent user memory in ~/.memory/ - a structured, hierarchical second brain for AI agents. Triggers on conversation start (auto-load relevant memories by matching context against tags), "remember this", "what do you know about X", "update my memory", completing complex tasks (auto-propose saving learnings), onboarding a new user, searching past learnings, or maintaining the memory graph - splitting large files, pruning stale entries, and updating cross-references.

What is second-brain?

Quick Start

Open your terminal or command prompt
Run: npx skills add AbsolutelySkilled/AbsolutelySkilled --skill second-brain
Start your AI coding agent (Claude Code, Cursor, Gemini CLI, or any supported agent)
The second-brain skill is now active and ready to use

Overview Files

second-brain

second-brain is a production-ready AI agent skill for claude-code, gemini-cli, openai-codex, and 1 more. Managing persistent user memory in ~/.memory/ - a structured, hierarchical second brain for AI agents.

Quick Facts

Field	Value
Category	devtools
Version	0.1.0
Platforms	claude-code, gemini-cli, openai-codex, mcp
License	MIT

How to Install

Make sure you have Node.js installed on your machine.
Run the following command in your terminal:

npx skills add AbsolutelySkilled/AbsolutelySkilled --skill second-brain

The second-brain skill is now available in your AI coding agent (Claude Code, Gemini CLI, OpenAI Codex, etc.).

Overview

Second Brain turns ~/.memory/ into a persistent, hierarchical knowledge store that works across projects and tools. Unlike project-level context files (CLAUDE.md, .cursorrules), Second Brain holds personal, cross-project knowledge - your preferences, learnings, workflows, and domain expertise. It is designed for AI agents: tag-indexed for fast relevance matching, wiki-linked for graph traversal, and capped at 100 lines per file for context-window efficiency.

Platforms

claude-code
gemini-cli
openai-codex
mcp

Related Skills

Pair second-brain with these complementary skills:

Frequently Asked Questions

What is second-brain?

How do I install second-brain?

Run npx skills add AbsolutelySkilled/AbsolutelySkilled --skill second-brain in your terminal. The skill will be immediately available in your AI coding agent.

What AI agents support second-brain?

This skill works with claude-code, gemini-cli, openai-codex, mcp. Install it once and use it across any supported AI coding agent.

Maintainers

@maddhruv

Generated from AbsolutelySkilled

SKILL.md

Second Brain for AI Agents

When to use this skill

Trigger this skill when the user:

Starts a new conversation (auto-load relevant memories based on context)
Says "remember this", "save this for later", or "update my memory"
Asks "what do you know about X" or "what are my preferences for Y"
Completes a complex or multi-step task (auto-propose saving learnings)
Needs to set up ~/.memory for the first time (onboarding)
Wants to search, organize, or clean up their memories
Asks about their past learnings, workflows, or preferences

Do NOT trigger this skill for:

Project-specific context (that belongs in CLAUDE.md or similar project files)
Storing sensitive data like passwords, API keys, or tokens

Key principles

Ask before saving - Never write to ~/.memory without user consent. After complex tasks, propose what to remember and let the user approve before writing. The user owns their memory.
Relevance over completeness - At conversation start, read index.yaml, match tags against the current context, and load only the top 3-5 matching files. Never load all memory files - most won't be relevant and they waste context.
100-line ceiling - Each memory topic file stays under 100 lines (including frontmatter). When a file grows beyond this, split it into sub-files in a subdirectory. This keeps individual loads cheap and forces concise writing.
Cross-project, not project-specific - ~/.memory stores personal knowledge, preferences, and universal learnings. Project-specific rules, configs, and context belong in project-level files like CLAUDE.md.
Tags + wiki-links for navigation - Every memory file has YAML frontmatter with tags for index lookup. Cross-references use [[path/to/file.md]] wiki-links. The root index.yaml maps tags to files for fast retrieval.

Core concepts

Directory structure - ~/.memory/ uses a hierarchical layout: index.yaml at root as the master registry, profile.md for user identity from onboarding, and category directories (e.g., coding/, marketing/) each containing an index.md overview and topic-specific .md files.

Memory file format - Each .md file has YAML frontmatter with tags, created, updated, and links (wiki-links to related files), followed by a concise markdown body. This is a knowledge dump, not documentation - keep entries terse and scannable.

index.yaml - The master lookup table. Maps tags to file paths, tracks categories, records line counts and last-updated timestamps per file. Always read this first to determine what to load.

Relevance matching - Extract keywords from the current context (working directory, file types, tools, user's stated topic). Score each file's tags against these keywords (exact match = 3 points, partial = 1). Load the top 3-5 scoring files. If nothing scores above threshold, load only profile.md.

Memory lifecycle (CRUSP) - Create (onboarding or post-task save), Read (auto-load or explicit query), Update (append or revise existing entries), Split (when file exceeds 100 lines), Prune (remove stale/outdated entries).

Common tasks

First-run onboarding

Detect first run by checking if ~/.memory/ exists and contains index.yaml. If missing, run a structured interview with 7 questions covering work domains, tools, communication style, active projects, workflows, learning goals, and golden rules. Use answers to bootstrap the directory structure: create index.yaml, profile.md, category directories with index.md files, and initial topic files.

See references/onboarding.md for the full question set, bootstrapping templates, and a worked example.

Auto-load relevant memories at conversation start

Read ~/.memory/index.yaml
Extract keywords from current context: project name, file extensions being edited, tools/frameworks mentioned, user's explicit topic
Match keywords against the tags map in index.yaml
Score matches: exact tag hit = 3 points, substring match = 1 point
Load the top 3-5 scoring files (read their content into context)
If no files score above threshold, load only profile.md as baseline
Briefly note which memories were loaded so the user knows what context is active

User-initiated save ("remember this")

When the user says "remember this" or similar:

Identify what to remember from the conversation
Determine the right category - check existing categories in index.yaml first; if ambiguous, ask the user
Check if a relevant topic file already exists in that category
If yes: append the new knowledge to the existing file (check 100-line limit)
If no: create a new file with proper YAML frontmatter (tags, timestamps, links)
Update index.yaml with new tags and file metadata
Scan existing files for related tags and add [[wiki-links]] if appropriate

Auto-propose learnings after complex task

After completing a multi-step or complex task, identify learnable patterns:

New tool configurations or setup steps discovered
Debugging techniques that worked
Workflow preferences revealed during the task
Domain knowledge gained

Present the proposed memories to the user in a concise summary. Include which file each would be saved to. Only write on explicit user approval. Never save silently.

Search memories ("what do you know about X")

Search index.yaml tags for matches against the query
If tag matches found: read those files and present relevant excerpts
If no tag match: do a content search across all memory files as fallback
Present results with source file paths so user can verify or update
Offer to update, correct, or prune any found memories

Split an oversized memory file

When a file exceeds 100 lines:

Propose a split to the user - identify 2-4 natural sub-topics
Create a subdirectory named after the original file (without extension)
Move each sub-topic into its own file within the subdirectory
Replace the original file with an index.md linking to the sub-files
Update all [[wiki-links]] across ~/.memory that pointed to the old file
Update index.yaml with the new file paths and tags

See references/maintenance.md for the detailed splitting protocol.

Handle conflicting or outdated memories

When new information contradicts an existing memory:

Flag the conflict - show the existing memory and the new information
Ask the user which version is correct
Update the file with the correct version; set a new updated timestamp
Optionally add a supersedes note in frontmatter to track the change
If the old memory was cross-referenced, check if linked files need updates

Gotchas

index.yaml out of sync crashes relevance matching - If files are added or renamed without updating index.yaml, the tag-based lookup silently misses them. Always update index.yaml atomically when creating, renaming, or splitting memory files.
Splitting too eagerly fragments context - Splitting a file at 90 lines into 5 sub-files can make each one too narrow to load usefully on its own. Before splitting, ask whether the sub-topics are actually queried independently. If not, keep them together and only split when a specific sub-topic is consistently relevant on its own.
Tags that are too generic defeat lookup - Tags like coding or work match everything and score everything equally. Tags should be specific enough to differentiate: typescript, react-patterns, vim-config rather than just tools.
Proposing saves mid-task breaks focus - Offering to save a learning while the user is still in the middle of a complex task pulls them out of flow. Batch all proposed saves for the end of the task in one approval round.
Wiki-links to non-existent files break the graph - When splitting or pruning files, update all [[wiki-links]] that pointed to the old path. A broken link silently orphans the cross-reference and the graph loses its traversal utility.

Anti-patterns / common mistakes

Mistake	Why it's wrong	What to do instead
Storing passwords, API keys, or tokens	Memory files are plaintext, readable by any tool	Use env vars, keychains, or secret managers
Duplicating project-specific context	~/.memory and CLAUDE.md serve different purposes	Project rules in CLAUDE.md; personal knowledge in ~/.memory
Loading all memory files at start	Wastes context window; most files won't be relevant	Load only tag-matched files; max 3-5 per conversation
Saving without user approval	User may not want everything remembered	Always propose and get explicit approval first
Saving obvious or generic knowledge	"Python is interpreted" wastes space	Only store personal preferences, specific learnings, non-obvious patterns
Letting files grow past 100 lines	Large files defeat the purpose of selective loading	Split into sub-topic files in a subdirectory
Ignoring timestamps	Stale memories can mislead future sessions	Always set `updated` timestamp; periodically review old entries

References

For detailed specs and workflows, read the relevant file from references/:

references/onboarding.md - Full onboarding interview questions, bootstrapping templates, and worked example. Load when setting up ~/.memory for a new user.
references/memory-format.md - index.yaml schema, memory file format spec, wiki-link resolution, and profile.md template. Load when creating or updating files.
references/maintenance.md - File splitting protocol, pruning strategy, relevance matching algorithm details, and index rebuild procedure. Load for memory cleanup tasks.

Only load a references file if the current task requires it.

References

maintenance.md

Memory Maintenance

File splitting protocol

Trigger: A memory file exceeds 100 lines (including frontmatter).

Process:

Identify sub-topics - Read the file and find 2-4 natural groupings based on the ## headers or thematic clusters

Propose the split - Show the user the proposed structure:

coding/react.md (120 lines) ->
  coding/react/index.md    (overview + links)
  coding/react/hooks.md    (hooks patterns, 35 lines)
  coding/react/patterns.md (component patterns, 40 lines)
  coding/react/testing.md  (React testing, 30 lines)

Create subdirectory - Name it after the original file without extension: coding/react.md becomes coding/react/
Write sub-files - Each sub-file gets:
- Its own YAML frontmatter with appropriate tags
- The content from its section of the original file
- Wiki-links back to the parent index.md and sibling files

Create index.md - Replace the original file's content with an index that links to all sub-files:

---
tags: [react, frontend]
created: "<original-created-date>"
updated: "<today>"
links:
  - "[[coding/react/hooks.md]]"
  - "[[coding/react/patterns.md]]"
  - "[[coding/react/testing.md]]"
---

# React Memory

## Topics
- [[coding/react/hooks.md]] - Hook patterns and preferences
- [[coding/react/patterns.md]] - Component architecture
- [[coding/react/testing.md]] - Testing React components

Update wiki-links - Search all other memory files for [[coding/react.md]] and update to [[coding/react/index.md]]
Update index.yaml - Remove the old file entry, add entries for each new sub-file with their tags, line counts, and timestamps

Pruning stale memories

When to prune:

Memory hasn't been accessed or updated in 6+ months
Information is clearly outdated (deprecated tool, abandoned project)
User explicitly says a memory is no longer relevant

Process:

Identify candidates - Scan index.yaml for files where updated is older than 6 months from today

Present to user - List stale files with their last-updated date and a brief content summary:

Stale memories (not updated in 6+ months):
- coding/webpack.md (updated 2025-08-12) - Webpack 4 config patterns
- marketing/facebook-ads.md (updated 2025-06-03) - FB ad targeting rules

User decides - For each file, user can:
- Keep (update timestamp to mark as still-relevant)
- Prune (delete the file)
- Update (revise the content then keep)
Clean up - For pruned files:
- Delete the file
- Remove from index.yaml (tags, files, category topics)
- Search for and remove any wiki-links pointing to the deleted file
- If a category becomes empty, remove the category directory

Relevance matching algorithm

Used at conversation start to determine which memories to load.

Step 1: Extract context keywords

Build a keyword set from the current context:

Working directory name - e.g., "my-react-app" yields react, app
File types being edited - .tsx yields react, typescript; .py yields python
Tool names in context - imports, configs, package.json dependencies
User's explicit topic - if they state what they're working on
Project-level files - CLAUDE.md, package.json, pyproject.toml metadata

Step 2: Match against index.yaml tags

For each keyword, look up matching tags in index.yaml.tags:

Exact match: keyword equals a tag exactly -> 3 points per file
Substring match: keyword is contained in a tag or vice versa -> 1 point

Step 3: Score and rank files

Sum points per file across all keyword matches. Example:

Context keywords: [react, typescript, hooks, testing]

coding/react.md:     react(3) + hooks(3) + testing(3) = 9 points
coding/typescript.md: typescript(3) = 3 points
coding/testing.md:   testing(3) = 3 points
marketing/seo.md:    (no match) = 0 points

Step 4: Load top files

Load the top 3-5 scoring files (configurable, default 5)
Always load profile.md as baseline context
If no files score above 0, load only profile.md
Never load more than 5 files to avoid context bloat

Step 5: Explicit query fallback

When the user explicitly asks "what do you know about X":

First try the tag-based matching above
If no tag matches: do a full-text search across all memory file bodies
Present results with file paths for verification

Index rebuild

If index.yaml gets corrupted, out of sync, or deleted:

Walk the entire ~/.memory/ directory tree
For each .md file found, read its YAML frontmatter
Extract tags, created/updated dates, and wiki-links
Count lines per file
Rebuild the categories list from directory names
Rebuild the tags map from all files' tag lists
Rebuild the files map with metadata
Write the new index.yaml

This is a safe operation - it only reads existing files and writes the index.

Handling domain sprawl

Too many categories (10+):

Review categories for overlap (e.g., "frontend" and "ui-design" might merge)
Propose consolidation to the user
Move files from deprecated category to the merged one
Update all wiki-links and index.yaml

Too many topic files in a category (15+):

Propose hierarchical restructuring
Group related topics into subdirectories
e.g., coding/ with 20 files becomes coding/frontend/, coding/backend/, coding/devops/ with topic files distributed appropriately

Cross-reference maintenance

On file creation

After creating a new memory file, scan existing files for matching tags
If strong overlap found (3+ shared tags), suggest adding wiki-links between the new file and existing files

On file deletion or move

Search all memory files for wiki-links pointing to the old path
Update or remove stale links
Update index.yaml to reflect the change

On file update

If tags were added or removed, update index.yaml tag mappings
If content now contradicts a linked file, flag for user review

Periodic review

When performing any maintenance, check for broken wiki-links (links pointing to files that no longer exist)
Report broken links to user and suggest fixes

memory-format.md

Memory File Format Specification

index.yaml schema

The master registry at ~/.memory/index.yaml. Always read this first to determine what memories exist and which to load.

version: 1
last_updated: "2026-03-14T10:30:00Z"

categories:
  - name: coding
    path: coding/
    topics: [react, typescript, nodejs, testing]
  - name: marketing
    path: marketing/
    topics: [seo, email-marketing, analytics]

tags:
  react: [coding/react.md]
  typescript: [coding/typescript.md, coding/react.md]
  hooks: [coding/react.md]
  testing: [coding/react.md, coding/testing.md]
  seo: [marketing/seo.md]
  email: [marketing/email-marketing.md]
  profile: [profile.md]

files:
  profile.md:
    tags: [profile, identity, preferences]
    lines: 42
    updated: "2026-03-14T10:30:00Z"
  coding/react.md:
    tags: [react, frontend, hooks, components]
    lines: 67
    updated: "2026-03-14T10:30:00Z"
  coding/typescript.md:
    tags: [typescript, types, generics, strict-mode]
    lines: 38
    updated: "2026-03-12T15:00:00Z"
  marketing/seo.md:
    tags: [seo, content, keywords]
    lines: 25
    updated: "2026-03-10T09:00:00Z"

Required fields:

version: Always 1 (for future schema migrations)
last_updated: ISO 8601 timestamp of last index modification
categories: List of top-level domains with directory path and topic list
tags: Map of tag name to list of file paths containing that tag
files: Map of file path to metadata (tags, line count, last updated)

Update rules:

Update last_updated on every index modification
Update files.<path>.lines whenever a memory file is written
Update files.<path>.updated whenever a memory file is modified
Add/remove entries in tags when files are created, deleted, or re-tagged

Memory file format

Every .md file in ~/.memory/ (except index.yaml) follows this format:

---
tags: [react, hooks, state-management]
created: "2026-03-14"
updated: "2026-03-14"
links:
  - "[[coding/typescript.md]]"
  - "[[coding/index.md]]"
---

# React Patterns

## Hooks preferences
- Always use useReducer for complex state over nested useState
- Custom hooks for any logic shared between 2+ components
- Never call hooks conditionally

## Component patterns
- Prefer function components exclusively
- Colocate styles with components
- Extract components when JSX exceeds 50 lines

Frontmatter fields

Field	Required	Format	Description
`tags`	Yes	List of lowercase, hyphenated strings	Used by index.yaml for lookup
`created`	Yes	ISO 8601 date (YYYY-MM-DD)	When this file was first created
`updated`	Yes	ISO 8601 date (YYYY-MM-DD)	When this file was last modified
`links`	No	List of `[[path]]` strings	Wiki-links to related memory files
`supersedes`	No	String (file path)	If this replaced an older memory

Content rules

Max 100 lines per file (including frontmatter)
Use markdown headers (##) to organize sub-topics within the file
Write in terse, scannable format - bullet points over paragraphs
This is a knowledge dump, not documentation - skip preambles and explanations
Use concrete values, not vague descriptions ("8px spacing" not "appropriate spacing")
One topic per file - if covering multiple topics, split into separate files

Category index.md format

Each category directory has an index.md that serves as the category overview:

---
tags: [coding]
created: "2026-03-14"
updated: "2026-03-14"
links: []
---

# Coding Memory

High-level coding preferences and cross-topic patterns.

## Topics
- [[coding/react.md]] - React patterns, hooks, component preferences
- [[coding/typescript.md]] - TypeScript config, type patterns, strict mode rules
- [[coding/testing.md]] - Testing philosophy, TDD approach, framework preferences

## Cross-cutting preferences
- Always prefer explicit over implicit
- Type safety over convenience
- Readable code over clever code

profile.md format

Special file at ~/.memory/profile.md. Loaded as baseline context when no specific memories match. Contains the user's identity and universal preferences.

---
tags: [profile, identity, preferences]
created: "2026-03-14"
updated: "2026-03-14"
links: []
---

# User Profile

## Work Style
- Primary domains: software engineering, marketing
- Core tools: React, TypeScript, Node.js, Mailchimp

## Communication Preferences
- Direct and concise, code-first
- Minimal hand-holding, show the solution
- Use bullet points over long paragraphs

## Active Projects
- SaaS dashboard: Next.js app with Prisma + PostgreSQL
- Newsletter growth: Mailchimp automation project

## Learning Goals
- Rust systems programming
- Advanced CSS animations

## Golden Rules
- Always use TypeScript strict mode
- Never use default exports
- Conventional commits on all projects
- Prefer composition over inheritance

Wiki-link resolution

Wiki-links use the format [[relative/path/to/file.md]] and always resolve relative to the ~/.memory/ root.

Examples:

[[coding/react.md]] resolves to ~/.memory/coding/react.md
[[profile.md]] resolves to ~/.memory/profile.md
[[marketing/email/templates.md]] resolves to ~/.memory/marketing/email/templates.md

Resolution rules:

Path is always relative to ~/.memory/ (never absolute)
Extension (.md) is always included
If a linked file doesn't exist, the link is stale - flag for cleanup
When a file is moved or renamed, update all wiki-links pointing to it

Conflict resolution strategy

When new information contradicts an existing memory:

Detection - Agent notices the contradiction when reading existing memory during a save or update operation
Flagging - Present both versions to the user: "Existing memory says X (from ). New information says Y. Which is correct?"
Resolution - User picks the correct version
Update - Write the correct version, set new updated timestamp
Tracking - Optionally add supersedes: "<old-info-summary>" in frontmatter

Timestamp rule: When in doubt and the user doesn't respond, newer information is preferred but the agent should still flag the conflict for future review.

onboarding.md

Onboarding - First-Run Setup

Detection logic

Check these conditions to determine if onboarding is needed:

Does ~/.memory/ directory exist?
Does ~/.memory/index.yaml exist?
Does ~/.memory/profile.md exist?

If any are missing, trigger onboarding. If all exist but index.yaml is empty or malformed, offer to rebuild (see maintenance.md).

The 7 onboarding questions

Ask these questions sequentially. Each question seeds a specific part of the memory structure. Adapt follow-ups based on answers.

Question 1: Work domains

"What are your primary work domains? (e.g., software engineering, marketing, data science, design, product management, writing, devops)"

Purpose: Seeds the top-level directory structure. Each domain becomes a category directory in ~/.memory/.

Follow-up: If they list more than 5, ask them to pick the top 3-5 they work in most frequently. Others can be added later organically.

Question 2: Tools, languages, and frameworks

"What tools, languages, and frameworks do you use most regularly?"

Purpose: Creates initial tags and topic files within categories. "React, TypeScript, PostgreSQL" creates coding/react.md, coding/typescript.md, coding/postgresql.md with basic tag entries.

Follow-up: Group their answers into the domains from Question 1. Ask for clarification if a tool spans multiple domains.

Question 3: Communication style

"How do you prefer AI agents to communicate with you? (e.g., direct and concise, detailed explanations, code-first with minimal prose, casual, formal)"

Purpose: Stored in profile.md under Communication Preferences. Agents load this to calibrate their response style.

Question 4: Active projects

"What are your current active projects? Just names and a one-line description each."

Purpose: Creates context mappings for relevance matching - helps the agent know which memories are relevant when working in a specific project. Does NOT create project-specific memory (that belongs in CLAUDE.md).

Stored in: profile.md under Active Projects. Updated as projects change.

Question 5: Workflows and processes

"What workflows or processes do you follow? (e.g., git branching strategy, PR review process, testing philosophy, deployment approach, writing process)"

Purpose: Stored in relevant category files. "I use conventional commits and squash-merge PRs" goes into coding/workflows.md or similar.

Question 6: Learning goals

"What areas are you currently learning or growing in?"

Purpose: Helps the agent prioritize what to remember from future sessions. If the user is learning Rust, the agent should be more proactive about saving Rust-related learnings. Stored in profile.md under Learning Goals.

Question 7: Golden rules

"Any strong preferences or things you always want AI agents to know about you? These are your non-negotiable rules."

Purpose: The highest-priority memories. Things like "never use semicolons in JS", "always use TypeScript strict mode", "I hate ORMs", "prefer functional over OOP". Stored in profile.md under Golden Rules - these are loaded in almost every session via profile.md.

Bootstrapping the directory structure

After collecting answers, create the following structure:

Step 1: Create ~/.memory/ directory

mkdir -p ~/.memory

Step 2: Create profile.md

---
tags: [profile, identity, preferences]
created: "<today>"
updated: "<today>"
links: []
---

# User Profile

## Work Style
- Primary domains: <from Q1>
- Core tools: <from Q2>

## Communication Preferences
- <from Q3>

## Active Projects
- <project>: <one-line description> (from Q4)

## Workflows
- <key workflow items from Q5>

## Learning Goals
- <from Q6>

## Golden Rules
- <from Q7 - these are non-negotiable>

Step 3: Create category directories

For each domain from Q1, create:

~/.memory/<domain>/index.md

Category index.md template:

---
tags: [<domain>]
created: "<today>"
updated: "<today>"
links: []
---

# <Domain> Memory

Overview of <domain>-related knowledge and preferences.

## Topics
- [[<domain>/<topic>.md]] - <brief description>

Step 4: Create initial topic files

For each tool/framework from Q2, create a topic file in the matching category:

---
tags: [<tool-name>, <category>]
created: "<today>"
updated: "<today>"
links:
  - "[[<category>/index.md]]"
---

# <Tool Name>

<Any initial preferences or knowledge from the onboarding answers>

Step 5: Create index.yaml

version: 1
last_updated: "<today>T<now>Z"
categories:
  - name: <domain-1>
    path: <domain-1>/
    topics: [<topic-1>, <topic-2>]
  - name: <domain-2>
    path: <domain-2>/
    topics: [<topic-3>]
tags:
  <tag-1>: [<file-path-1>, <file-path-2>]
  <tag-2>: [<file-path-3>]
  profile: [profile.md]
files:
  profile.md:
    tags: [profile, identity, preferences]
    lines: <count>
    updated: "<today>T<now>Z"
  <domain>/<topic>.md:
    tags: [<tag-1>, <tag-2>]
    lines: <count>
    updated: "<today>T<now>Z"

Worked example

User answers:

Domains: software engineering, marketing
Tools: React, TypeScript, Node.js, Mailchimp
Style: "Direct and concise, code-first"
Projects: "SaaS dashboard (Next.js app)", "Newsletter growth project"
Workflows: "Conventional commits, PR reviews, TDD"
Learning: "Rust, advanced CSS animations"
Golden rules: "Always use TypeScript strict mode", "Never use default exports"

Resulting structure:

~/.memory/
  index.yaml
  profile.md
  coding/
    index.md
    react.md
    typescript.md
    nodejs.md
  marketing/
    index.md
    mailchimp.md

profile.md would contain:

Work Style: software engineering + marketing, React/TS/Node/Mailchimp
Communication: Direct, concise, code-first
Active Projects: SaaS dashboard (Next.js), Newsletter growth
Workflows: Conventional commits, PR reviews, TDD
Learning Goals: Rust, advanced CSS animations
Golden Rules: Always TypeScript strict mode, never default exports

Edge cases

Multi-domain users - Create separate category directories. Use tags for cross-domain connections. A user doing both "marketing analytics" and "data engineering" might have [[marketing/analytics.md]] linking to [[coding/data-pipelines.md]].

Uncertain answers - Create a minimal structure with just profile.md and one or two categories. The memory will grow organically as the user works. Don't force categories that feel uncertain.

Importing existing notes - If the user has existing knowledge in other formats, help them restructure into the memory format: add YAML frontmatter, split into sub-100-line files, assign tags, and build the index.yaml.

Frequently Asked Questions

What is second-brain?

How do I install second-brain?

Run npx skills add AbsolutelySkilled/AbsolutelySkilled --skill second-brain in your terminal. The skill will be immediately available in your AI coding agent.

What AI agents support second-brain?

second-brain works with claude-code, gemini-cli, openai-codex, mcp. Install it once and use it across any supported AI coding agent.

Is second-brain free?

Yes, second-brain is completely free and open source under the MIT license. Install it with a single command and start using it immediately.

What is the difference between second-brain and similar tools?

second-brain is an AI agent skill that teaches your coding agent specialized developer tools knowledge. Unlike standalone tools, it integrates directly into claude-code, gemini-cli, openai-codex and other AI agents.

Can I use second-brain with Cursor or Windsurf?

second-brain works with any AI coding agent that supports the skills protocol, including Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, and 40+ more.

second-brain

What is second-brain?

Quick Start

second-brain

Quick Facts

How to Install

Overview

Tags

Platforms

Related Skills

Frequently Asked Questions

What is second-brain?

How do I install second-brain?

What AI agents support second-brain?

Maintainers

SKILL.md

Second Brain for AI Agents

When to use this skill

Key principles

Core concepts

Common tasks

First-run onboarding

Auto-load relevant memories at conversation start

User-initiated save ("remember this")

Auto-propose learnings after complex task

Search memories ("what do you know about X")

Split an oversized memory file

Handle conflicting or outdated memories

Gotchas

Anti-patterns / common mistakes

References

References

maintenance.md

Memory Maintenance

File splitting protocol

Pruning stale memories

Relevance matching algorithm

Step 1: Extract context keywords

Step 2: Match against index.yaml tags

Step 3: Score and rank files

Step 4: Load top files

Step 5: Explicit query fallback

Index rebuild

Handling domain sprawl

Cross-reference maintenance

On file creation

On file deletion or move

On file update

Periodic review

memory-format.md

Memory File Format Specification

index.yaml schema

Memory file format

Frontmatter fields

Content rules

Category index.md format

profile.md format

Wiki-link resolution

Conflict resolution strategy

onboarding.md

Onboarding - First-Run Setup

Detection logic

The 7 onboarding questions

Question 1: Work domains

Question 2: Tools, languages, and frameworks

Question 3: Communication style

Question 4: Active projects

Question 5: Workflows and processes

Question 6: Learning goals

Question 7: Golden rules

Bootstrapping the directory structure

Step 1: Create ~/.memory/ directory

Step 2: Create profile.md

Step 3: Create category directories

Step 4: Create initial topic files

Step 5: Create index.yaml

Worked example

Edge cases

Frequently Asked Questions

What is second-brain?