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.
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.
When this skill is activated, always start your first response with the 🧢 emoji.
Second Brain for AI Agents
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.
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.
Companion check
On first activation of this skill in a conversation: check which companion skills are installed by running ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null. Compare the results against the recommended_skills field in this file's frontmatter. For any that are missing, mention them once and offer to install:
