nano-step/nano-brain
skills/nano-brain/SKILL.md
Provide persistent memory and code intelligence for AI coding agents; use for hybrid search, cross-session recall, symbol analysis, and impact checks.
$ install --global
skillsauthnpx skillsauth add nano-step/skill-manager nano-brainInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: May 5, 2026, 2:56 AM345.6s4 files scanned
SKILL.md
- name:
- nano-brain
- description:
- Provide persistent memory and code intelligence for AI coding agents; use for hybrid search, cross-session recall, symbol analysis, and impact checks.
- compatibility:
- OpenCode
- author:
- nano-step
- version:
- 2.1.0
nano-brain
Provide persistent memory for AI coding agents. Run hybrid search (BM25 + semantic + LLM reranking) across past sessions, codebase, notes, and daily logs.
Slash Commands
| Command | When |
|---------|------|
| /nano-brain-init | Run first-time workspace setup |
| /nano-brain-status | Check health, embedding progress |
| /nano-brain-reindex | Run after branch switch, pull, or major changes |
When to Use Memory
Before work: Recall past decisions, patterns, debugging insights, cross-session context. After work: Save key decisions, architecture choices, non-obvious fixes, domain knowledge.
Commands
Use the nano-brain CLI for all memory and code intelligence operations.
npx nano-brain search "..."— recall a specific error string or function name from past sessions. Example:npx nano-brain search "ECONNREFUSED redis timeout"Compact mode:npx nano-brain search "..." --compact— returns 1-line summaries, ~70% fewer tokensnpx nano-brain vsearch "..."— explore a fuzzy concept when you do not know the exact wording. Example:npx nano-brain vsearch "caching strategy for user sessions"Compact mode:npx nano-brain vsearch "..." --compactnpx nano-brain query "..."— get the best hybrid answer for a complex, multi-part question. Example:npx nano-brain query "how did we handle rate limiting in the payment service"Compact mode:npx nano-brain query "..." --compactnpx nano-brain write "..." --tags=...— log a decision or insight for future recall. Example:npx nano-brain write "## Decision: Use Redis Streams over Bull queues\n- Why: retries need ordered replay" --tags=decisionnpx nano-brain status— verify health or embedding progress before searching. Example:npx nano-brain statusnpx nano-brain reindex— refresh all indexes after big changes or repo syncs. ALWAYS useworkdirparameter —--rootflag is silently ignored and reindexes CWD instead. ✅ Correct:bash(command="npx nano-brain reindex", workdir="/path/to/workspace")❌ Wrong:npx nano-brain reindex --root=/path/to/workspacenpx nano-brain focus <filepath>— inspect dependencies for a specific file you are editing. Example:npx nano-brain focus /src/api/routes/auth.tsnpx nano-brain graph-stats— check dependency graph size and coverage. Example:npx nano-brain graph-statsnpx nano-brain symbols --type=... --pattern=...— find where cross-repo infrastructure symbols are defined or used. Example:npx nano-brain symbols --type=redis_key --pattern="session:*"npx nano-brain impact --type=... --pattern=...— see which repos or services are affected by a symbol. Example:npx nano-brain impact --type=mysql_table --pattern=ordersnpx nano-brain tags— list all tags to see what is tracked. Example:npx nano-brain tags
Token-Saving: Compact Search Flow (CCR)
For large result sets, use compact mode to save ~70% tokens. Compact returns 1-line summaries per result; expand the ones you need.
CLI flow:
npx nano-brain query "auth middleware" --compact
When to use compact:
- Triage/scanning many results before reading details
- Context window is tight and you need to be selective
- Searching broad topics where most results won't be relevant
When to use verbose (default):
- You need full content from all results
- Small result sets (< 5 results)
- Precise queries where every result matters
Collection Filtering
Works with CLI (-c flag):
codebase— source files onlysessions— past AI sessions onlymemory— curated notes only- Omit — search everything (recommended)
Code Intelligence Tools (CLI)
Use symbol-level analysis powered by Tree-sitter AST parsing. Require codebase indexing.
npx nano-brain context <name>— trace callers, callees, and flows around a symbol. Example:npx nano-brain context processPaymentnpx nano-brain code-impact <name> --direction=...— evaluate upstream or downstream risk before refactors. Example:npx nano-brain code-impact DatabaseClient --direction=upstreamnpx nano-brain detect-changes --scope=...— map current git diffs to symbols and flows. Example:npx nano-brain detect-changes --scope=all
Details and examples: references/code-intelligence.md
Memory vs Native Tools
| Use case | Tool |
|----------|------|
| Recall past decisions or context | npx nano-brain query "..." |
| Find exact strings or patterns in code | grep / ast-grep |
| Trace callers/callees or impact | npx nano-brain context <name> / npx nano-brain code-impact <name> --direction=... |
Memory excels at recall and semantics — past sessions, conceptual search, cross-project knowledge. Native tools (grep, ast-grep, glob) excel at precise code patterns — exact matches, AST structure. Code intelligence tools excel at structural relationships — call graphs, impact analysis, flow detection.
They are complementary. Use all three.
Related Skills
nano-step/iamhumans
tools
VerifiedTrustedCommunity
Humanization layer for LLM conversation — makes the model sound and respond like a real, thoughtful, embodied human rather than an assistant or chatbot. Use whenever the reply will be read by a human and warmth, presence, or texture matter more than machine-readability. Triggers on any of: "human", "humans", "humanize", "humanization", "be human", "more human", "feel human", "people", "person", "real person", "real human", "friend", "friendly", "like a friend", "respond like a friend", "buddy", "talk", "talking", "talk to me", "talk like a person", "chat", "chatting", "conversation", "converse", "discuss", "discussion", "communication", "communicate", "listen", "just listen", "sit with me", "vent", "venting", "I just want to vent", "company", "presence", "stop being an AI", "stop sounding like a bot", "less corporate", "less robotic", "less formal", "warmer", "warm tone", "empathy", "empathetic", "comfort", "support me", "emotional support", "be honest with me", "be real with me", "real talk", "heart-to-heart", "deep conversation", "casual", "casual chat", "small talk", "chitchat", "say something", "tell me something", and on any emotional / relational / personal-decision / interpersonal context — grief, joy, anger, fear, shame, doubt, loneliness, dating, breakup, conflict, family, parents, sibling, friendship, marriage, divorce, in-laws, kids, parenting, work stress, burnout, career decision, quitting, firing, layoff, anxiety, depression, panic, sleep, dreams, identity, faith, doubt, meaning, mortality, celebration, milestone, achievement, gratitude, apology, forgiveness. Also loads when the user writes in non-English (any language) with emotional weight, when the user's message is shorter than 8 words and affect-laden, when the user types in lowercase fragments, when the user types in ALL CAPS with excitement, or when the user explicitly asks for a friend / mentor / older-sibling / wise-listener voice. Do NOT use for code generation, tool calls, structured data output, SQL, API contracts, or any task where machine-readability matters more than human warmth.
3SKILL.mdUpdated Jun 1, 2026
nano-step/open-design-mcp
tools
VerifiedTrustedCommunity
Use this skill whenever the user mentions open-design, od_generate_design, OD daemon, BYOK design generation, generating HTML mockups from a PRD, creating or managing Open Design projects, saving design artifacts, linting generated HTML, or any of the 10 `od_*` MCP tools (od_list_projects, od_get_project, od_create_project, od_update_project, od_delete_project, od_save_artifact, od_save_project_file, od_lint_artifact, od_compose_brief, od_generate_design). Also trigger on phrases like "generate a design", "create a mockup", "make a landing page", "list my OD projects", "the design daemon", "the streaming design tool", and on any 401/404/422 error coming from an `od_*` tool call. Covers env-var setup (`OD_DAEMON_URL`, auth modes, BYOK), the full PRD → generate → save → lint workflow, error diagnosis, and the safety rails (lint before save, never commit BYOK keys). Triggers even if the user doesn't explicitly say "open-design-mcp" — keyword matches on `od_*` tool names or "design generation" workflows are enough.
3SKILL.mdUpdated May 19, 2026
nano-step/od-workflow
tools
VerifiedTrustedCommunity
Use this skill whenever a user wants the **full Open Design experience** — discovery questions asked first, brand-spec extraction from URLs/files, TodoWrite planning with live updates, 5-dimensional self-critique, polished artifact at the end. Trigger phrases include "design with questions first", "OD-style workflow", "full interactive design brief", "make me a complete landing page" (when the user wants quality over speed), "design my pitch deck", "brand-aware multi-page site", "follow the Open Design playbook", or any request where the user is starting a new design project rather than tweaking an existing artifact. Also trigger on any request that mentions wanting brand consistency across multiple pages or that provides a brand URL/spec. Pair with the `open-design-mcp` tool-reference skill — both loaded together give an LLM the full picture (this skill = workflow choreography; that skill = tool catalog + errors). This skill explicitly does NOT trigger for one-off tweaks ("make the nav stickier", "swap slide 3 image") — use od_generate_design directly for those.
3SKILL.mdUpdated May 19, 2026
nano-step/sync-skill-to-manager
development
VerifiedTrustedCommunity
Sync a locally-developed OpenCode skill to the skill-manager npm package and (if private) the private-skills GitHub repo. Handles per-skill version bumps, public/private classification, build verification, and conventional-commit-style git push. Auto-publish to npm is handled downstream by nano-step/shared-workflows@v1 when the push to master lands. Use this skill whenever the user says 'sync skill', 'publish skill', 'push skill to manager', '/sync-skill-to-manager <name>', or asks to release/distribute a skill they just edited.
3SKILL.mdUpdated May 7, 2026