[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75BAWH69AFJRNS1YX3RV4QP":3,"skill-same:01M75BAWH69AFJRNS1YX3RV4QP":71},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":41,"commitSha":42,"skillDirectory":43,"forksCount":14,"repositoryHtmlUrl":44,"repositoryHomepageUrl":6,"ownerHtmlUrl":45,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":46,"install":47,"resources":60},"01M75BAWH69AFJRNS1YX3RV4QP","brain-search",null,"Generic template — FTS5 + semantic search engine for a PARA-first Second Brain vault. Use for concept-level queries, keyword search, and vault exploration. Customize vault path and embedding model for each deployment.","fmercurio\u002Fclawdia-custom-skills","fmercurio","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F15571697?v=4","01M75B9TGVV3RPB40SY7AT0VNH","Felippe Mercurio","01M75B9THMAWYGFT755CR1PT9A",1,"MIT","https:\u002F\u002Fgithub.com\u002Ffmercurio\u002Fclawdia-custom-skills\u002Fblob\u002Fmain\u002Fskills\u002Fnote-taking\u002Fbrain-search\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: brain-search\ndescription: Generic template — FTS5 + semantic search engine for a PARA-first Second Brain vault. Use for concept-level queries, keyword search, and vault exploration. Customize vault path and embedding model for each deployment.\nversion: 1.0.0\nauthor: Hermes Agent\nlicense: MIT\nmetadata:\n  hermes:\n    tags: [second-brain, search, fts5, embeddings, semantic, knowledge-retrieval, template]\n    related_skills: [pull-brain, push-brain, second-brain-operations, second-brain-knowledge-architecture]\n---\n\n# Brain Search (Generic Template)\n\n> **Customization required.** Replace all `\u003CPLACEHOLDER>` values with deployment-specific paths, names, and model endpoints. This is a parameterized template, not a ready-to-use skill.\n\n## Overview\n\n`brain-search` provides FTS5 + optional semantic search over a PARA-first Second Brain vault.\n\nIt uses a standalone Python script (`brain_search.py`) that builds a SQLite\u002FFTS5 index with optional local embedding model integration for concept-level retrieval.\n\nEmbedding egress is localhost-only by default. Remote embedding providers receive vault text and search queries, so they require an explicit `--allow-remote-embeddings` opt-in plus an approved `BRAIN_EMBED_URL`.\n\nCanonical vault (CUSTOMIZE):\n\n```text\n\u003CVAULT_ROOT>\u002F\n```\n\nIndex location:\n\n```text\n\u003CVAULT_ROOT>\u002F.brain-index\u002Fbrain_search.sqlite\n```\n\n## When to Use\n\n- **pull-brain** needs to find vault content by concept, not just keyword\n- User asks \"what do we know about X?\" and keyword search misses relevant notes\n- Agent needs to explore the vault before a session\n- Rebuilding or updating the search index after vault changes\n\n## Commands\n\n### Rebuild full index (with embeddings)\n\n```bash\ncd \u003CVAULT_ROOT>\nBRAIN_EMBED_MODEL=\"\u003CEMBED_MODEL_NAME>\" \\\n  python3 scripts\u002Fbrain_search.py --rebuild --embeddings --json\n```\n\nRun when:\n- After a push-brain session that added\u002Fmodified files\n- On demand when search seems stale\n- Local model server (`\u003CEMBED_ENDPOINT>`) must be running\n\n### Quick rebuild (FTS only, no embeddings)\n\n```bash\ncd \u003CVAULT_ROOT>\npython3 scripts\u002Fbrain_search.py --rebuild --json\n```\n\nTakes \u003C1s. Good enough for keyword search when embeddings aren't needed.\n\n### Search (FTS only)\n\n```bash\ncd \u003CVAULT_ROOT>\npython3 scripts\u002Fbrain_search.py --query \"search terms\" --limit 8 --json\n```\n\n### Search (FTS + semantic)\n\n```bash\ncd \u003CVAULT_ROOT>\nBRAIN_EMBED_MODEL=\"\u003CEMBED_MODEL_NAME>\" \\\n  python3 scripts\u002Fbrain_search.py --query \"concept or question\" --vector --limit 8 --json\n```\n\nSemantic search finds results even when exact keywords don't appear in the vault. Similarity scores above ~0.65 are usually relevant.\n\n### Update a single file\n\n```bash\ncd \u003CVAULT_ROOT>\npython3 scripts\u002Fbrain_search.py --update \"10_Projects\u002Fmy-project\u002FProjeto.md\" --json\n```\n\n### Stats\n\n```bash\ncd \u003CVAULT_ROOT>\npython3 scripts\u002Fbrain_search.py --stats --json\n```\n\n## How it Works\n\n1. **Chunking**: Markdown files split by headings (##\u002F###). Oversized sections split by paragraphs. Each chunk keeps its heading context.\n2. **FTS5**: Full-text search with unicode61 tokenizer (good for accented languages). Matches keywords with relevance ranking.\n3. **Embeddings** (optional): Uses a local model server's OpenAI-compatible API. Stores float32 vectors in SQLite. Cosine similarity for semantic ranking.\n4. **Combined search**: FTS results first, then unique vector results not already found by FTS. Deduplication by path+heading.\n5. **PARA awareness**: Each chunk tagged with its layer (project\u002Farea\u002Fresource\u002Farchive) from path detection and frontmatter.\n\n## Integration with pull-brain\n\nWhen pull-brain needs to search the vault, prefer brain_search over raw grep:\n\n```bash\n# Instead of: search_files(pattern=\"term\", path=\"\u003CVAULT_ROOT>\")\n# Use:\nBRAIN_EMBED_MODEL=\"\u003CEMBED_MODEL_NAME>\" \\\n  python3 \u003CVAULT_ROOT>\u002Fscripts\u002Fbrain_search.py \\\n  --query \"term or concept\" --vector --limit 8 --json\n```\n\n## Integration with push-brain\n\nAfter push-brain writes files and commits, rebuild the index:\n\n```bash\ncd \u003CVAULT_ROOT>\npython3 scripts\u002Fbrain_search.py --rebuild --json\n# Or with embeddings:\nBRAIN_EMBED_MODEL=\"\u003CEMBED_MODEL_NAME>\" \\\n  python3 scripts\u002Fbrain_search.py --rebuild --embeddings --json\n```\n\n## Customization Checklist\n\nBefore deploying, replace these placeholders:\n\n| Placeholder | Description | Example |\n|-------------|-------------|---------|\n| `\u003CVAULT_ROOT>` | Absolute path to the vault | `\u002Fhome\u002Fuser\u002Fmy-brain` |\n| `\u003CEMBED_MODEL_NAME>` | Local embedding model identifier | `text-embedding-nomic-embed-text-v1.5` |\n| `\u003CEMBED_ENDPOINT>` | OpenAI-compatible API endpoint | `http:\u002F\u002F127.0.0.1:1234\u002Fv1\u002Fembeddings` |\n\n## Pitfalls\n\n1. **Model server must be running for embeddings.** Check connectivity to `\u003CEMBED_ENDPOINT>`. FTS-only rebuild is always available as fallback.\n2. **Remote embeddings are data egress.** The script rejects non-local endpoints unless `--allow-remote-embeddings` or `BRAIN_ALLOW_REMOTE_EMBEDDINGS=1` is set for an approved provider.\n3. **Model name mismatch.** Always set `BRAIN_EMBED_MODEL` env var; don't rely on defaults.\n4. **Index is cache, not source of truth.** The `.brain-index\u002F` directory is gitignored and can be rebuilt at any time.\n5. **Rebuild is cheap.** FTS-only: \u003C1s. With embeddings: ~17s for ~75 files. Don't hesitate to rebuild.\n6. **Semantic similarity threshold.** Scores below ~0.60 are usually noise. Above 0.70 is good. Above 0.80 is strong.\n7. **Tokenizer limitations.** FTS5 unicode61 handles accents but not stemming (singular ≠ plural won't match without OR).\n\n## Verification Checklist\n\n- [ ] `brain_search.py` placed in `\u003CVAULT_ROOT>\u002Fscripts\u002F`\n- [ ] `.brain-index\u002F` added to `.gitignore`\n- [ ] FTS-only rebuild tested (exit 0, stats show files\u002Fchunks)\n- [ ] Embedding rebuild tested (requires running model server)\n- [ ] Search (FTS) returns relevant results\n- [ ] Search (semantic) returns relevant results\n- [ ] Skill installed at `~\u002F.hermes\u002Fskills\u002Fnote-taking\u002Fbrain-search\u002FSKILL.md`\n- [ ] `\u002Freload-skills` run after installation\n- [ ] Integration with pull-brain tested\n- [ ] Integration with push-brain tested\n","# Brain Search (Generic Template)\n\n> **Customization required.** Replace all `\u003CPLACEHOLDER>` values with deployment-specific paths, names, and model endpoints. This is a parameterized template, not a ready-to-use skill.\n\n## Overview\n\n`brain-search` provides FTS5 + optional semantic search over a PARA-first Second Brain vault.\n\nIt uses a standalone Python script (`brain_search.py`) that builds a SQLite\u002FFTS5 index with optional local embedding model integration for concept-level retrieval.\n\nEmbedding egress is localhost-only by default. Remote embedding providers receive vault text and search queries, so they require an explicit `--allow-remote-embeddings` opt-in plus an approved `BRAIN_EMBED_URL`.\n\nCanonical vault (CUSTOMIZE):\n\n```text\n\u003CVAULT_ROOT>\u002F\n```\n\nIndex location:\n\n```text\n\u003CVAULT_ROOT>\u002F.brain-index\u002Fbrain_search.sqlite\n```\n\n## When to Use\n\n- **pull-brain** needs to find vault content by concept, not just keyword\n- User asks \"what do we know about X?\" and keyword search misses relevant notes\n- Agent needs to explore the vault before a session\n- Rebuilding or updating the search index after vault changes\n\n## Commands\n\n### Rebuild full index (with embeddings)\n\n```bash\ncd \u003CVAULT_ROOT>\nBRAIN_EMBED_MODEL=\"\u003CEMBED_MODEL_NAME>\" \\\n  python3 scripts\u002Fbrain_search.py --rebuild --embeddings --json\n```\n\nRun when:\n- After a push-brain session that added\u002Fmodified files\n- On demand when search seems stale\n- Local model server (`\u003CEMBED_ENDPOINT>`) must be running\n\n### Quick rebuild (FTS only, no embeddings)\n\n```bash\ncd \u003CVAULT_ROOT>\npython3 scripts\u002Fbrain_search.py --rebuild --json\n```\n\nTakes \u003C1s. Good enough for keyword search when embeddings aren't needed.\n\n### Search (FTS only)\n\n```bash\ncd \u003CVAULT_ROOT>\npython3 scripts\u002Fbrain_search.py --query \"search terms\" --limit 8 --json\n```\n\n### Search (FTS + semantic)\n\n```bash\ncd \u003CVAULT_ROOT>\nBRAIN_EMBED_MODEL=\"\u003CEMBED_MODEL_NAME>\" \\\n  python3 scripts\u002Fbrain_search.py --query \"concept or question\" --vector --limit 8 --json\n```\n\nSemantic search finds results even when exact keywords don't appear in the vault. Similarity scores above ~0.65 are usually relevant.\n\n### Update a single file\n\n```bash\ncd \u003CVAULT_ROOT>\npython3 scripts\u002Fbrain_search.py --update \"10_Projects\u002Fmy-project\u002FProjeto.md\" --json\n```\n\n### Stats\n\n```bash\ncd \u003CVAULT_ROOT>\npython3 scripts\u002Fbrain_search.py --stats --json\n```\n\n## How it Works\n\n1. **Chunking**: Markdown files split by headings (##\u002F###). Oversized sections split by paragraphs. Each chunk keeps its heading context.\n2. **FTS5**: Full-text search with unicode61 tokenizer (good for accented languages). Matches keywords with relevance ranking.\n3. **Embeddings** (optional): Uses a local model server's OpenAI-compatible API. Stores float32 vectors in SQLite. Cosine similarity for semantic ranking.\n4. **Combined search**: FTS results first, then unique vector results not already found by FTS. Deduplication by path+heading.\n5. **PARA awareness**: Each chunk tagged with its layer (project\u002Farea\u002Fresource\u002Farchive) from path detection and frontmatter.\n\n## Integration with pull-brain\n\nWhen pull-brain needs to search the vault, prefer brain_search over raw grep:\n\n```bash\n# Instead of: search_files(pattern=\"term\", path=\"\u003CVAULT_ROOT>\")\n# Use:\nBRAIN_EMBED_MODEL=\"\u003CEMBED_MODEL_NAME>\" \\\n  python3 \u003CVAULT_ROOT>\u002Fscripts\u002Fbrain_search.py \\\n  --query \"term or concept\" --vector --limit 8 --json\n```\n\n## Integration with push-brain\n\nAfter push-brain writes files and commits, rebuild the index:\n\n```bash\ncd \u003CVAULT_ROOT>\npython3 scripts\u002Fbrain_search.py --rebuild --json\n# Or with embeddings:\nBRAIN_EMBED_MODEL=\"\u003CEMBED_MODEL_NAME>\" \\\n  python3 scripts\u002Fbrain_search.py --rebuild --embeddings --json\n```\n\n## Customization Checklist\n\nBefore deploying, replace these placeholders:\n\n| Placeholder | Description | Example |\n|-------------|-------------|---------|\n| `\u003CVAULT_ROOT>` | Absolute path to the vault | `\u002Fhome\u002Fuser\u002Fmy-brain` |\n| `\u003CEMBED_MODEL_NAME>` | Local embedding model identifier | `text-embedding-nomic-embed-text-v1.5` |\n| `\u003CEMBED_ENDPOINT>` | OpenAI-compatible API endpoint | `http:\u002F\u002F127.0.0.1:1234\u002Fv1\u002Fembeddings` |\n\n## Pitfalls\n\n1. **Model server must be running for embeddings.** Check connectivity to `\u003CEMBED_ENDPOINT>`. FTS-only rebuild is always available as fallback.\n2. **Remote embeddings are data egress.** The script rejects non-local endpoints unless `--allow-remote-embeddings` or `BRAIN_ALLOW_REMOTE_EMBEDDINGS=1` is set for an approved provider.\n3. **Model name mismatch.** Always set `BRAIN_EMBED_MODEL` env var; don't rely on defaults.\n4. **Index is cache, not source of truth.** The `.brain-index\u002F` directory is gitignored and can be rebuilt at any time.\n5. **Rebuild is cheap.** FTS-only: \u003C1s. With embeddings: ~17s for ~75 files. Don't hesitate to rebuild.\n6. **Semantic similarity threshold.** Scores below ~0.60 are usually noise. Above 0.70 is good. Above 0.80 is strong.\n7. **Tokenizer limitations.** FTS5 unicode61 handles accents but not stemming (singular ≠ plural won't match without OR).\n\n## Verification Checklist\n\n- [ ] `brain_search.py` placed in `\u003CVAULT_ROOT>\u002Fscripts\u002F`\n- [ ] `.brain-index\u002F` added to `.gitignore`\n- [ ] FTS-only rebuild tested (exit 0, stats show files\u002Fchunks)\n- [ ] Embedding rebuild tested (requires running model server)\n- [ ] Search (FTS) returns relevant results\n- [ ] Search (semantic) returns relevant results\n- [ ] Skill installed at `~\u002F.hermes\u002Fskills\u002Fnote-taking\u002Fbrain-search\u002FSKILL.md`\n- [ ] `\u002Freload-skills` run after installation\n- [ ] Integration with pull-brain tested\n- [ ] Integration with push-brain tested\n",{"name":5,"author":24,"license":15,"version":25,"metadata":26,"description":7},"Hermes Agent","1.0.0",{"hermes":27},{"tags":28,"related_skills":36},[29,30,31,32,33,34,35],"second-brain","search","fts5","embeddings","semantic","knowledge-retrieval","template",[37,38,39,40],"pull-brain","push-brain","second-brain-operations","second-brain-knowledge-architecture","main","b5c05537c2a696d4f96f17b51e5e2951fcab8f5b","skills\u002Fnote-taking\u002Fbrain-search","https:\u002F\u002Fgithub.com\u002Ffmercurio\u002Fclawdia-custom-skills","https:\u002F\u002Fgithub.com\u002Ffmercurio","2026-11-07 04:26:06",{"source":8,"skillName":5,"commands":48,"prompt":58,"zipAvailable":59},[49,52,55],{"tool":50,"command":51},"npx","npx skills add fmercurio\u002Fclawdia-custom-skills --skill brain-search",{"tool":53,"command":54},"bunx","bunx skills add fmercurio\u002Fclawdia-custom-skills --skill brain-search",{"tool":56,"command":57},"pnpm","pnpm dlx skills add fmercurio\u002Fclawdia-custom-skills --skill brain-search","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Ffmercurio\u002Fclawdia-custom-skills\u002Fblob\u002Fmain\u002Fskills\u002Fnote-taking\u002Fbrain-search\u002FSKILL.md",true,[61,67],{"path":62,"resourceType":63,"resourceTypeDesc":64,"sizeBytes":65,"sourceHtmlUrl":66},"scripts\u002Fbrain_search.py","SCRIPT","脚本",36324,"https:\u002F\u002Fgithub.com\u002Ffmercurio\u002Fclawdia-custom-skills\u002Fblob\u002Fmain\u002Fskills\u002Fnote-taking\u002Fbrain-search\u002Fscripts\u002Fbrain_search.py",{"path":68,"resourceType":63,"resourceTypeDesc":64,"sizeBytes":69,"sourceHtmlUrl":70},"tests\u002Ftest_brain_search_paths.py",13939,"https:\u002F\u002Fgithub.com\u002Ffmercurio\u002Fclawdia-custom-skills\u002Fblob\u002Fmain\u002Fskills\u002Fnote-taking\u002Fbrain-search\u002Ftests\u002Ftest_brain_search_paths.py",[72,79,85,91,97,102],{"skillNo":73,"name":74,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":19},"01M75BDD9N7RSFBWGDNTZK9NYT","overlay-skill","Fixture skill for deployment planner tests.","https:\u002F\u002Fgithub.com\u002Ffmercurio\u002Fclawdia-custom-skills\u002Fblob\u002Fmain\u002Ftools\u002Fskill_deploy\u002Ftests\u002Ffixtures\u002Fworkspace\u002Fskills\u002Fproductivity\u002Foverlay-skill\u002FSKILL.md",[],[],{"skillNo":80,"name":81,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M75BDAV2X86DYXADGV8B1ZCZ","candidate-skill","https:\u002F\u002Fgithub.com\u002Ffmercurio\u002Fclawdia-custom-skills\u002Fblob\u002Fmain\u002Ftools\u002Fskill_deploy\u002Ftests\u002Ffixtures\u002Fworkspace\u002Fskills\u002Fproductivity\u002Fcandidate-skill\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":19},"01M75BD9NPF9EKPHAZMBVDM8GN","builtin-collision","https:\u002F\u002Fgithub.com\u002Ffmercurio\u002Fclawdia-custom-skills\u002Fblob\u002Fmain\u002Ftools\u002Fskill_deploy\u002Ftests\u002Ffixtures\u002Fworkspace\u002Fskills\u002Fproductivity\u002Fbuiltin-collision\u002FSKILL.md",[],[],{"skillNo":92,"name":93,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":19},"01M75BD7NV55ZMQVC0GY7FSG2F","approved-global","https:\u002F\u002Fgithub.com\u002Ffmercurio\u002Fclawdia-custom-skills\u002Fblob\u002Fmain\u002Ftools\u002Fskill_deploy\u002Ftests\u002Ffixtures\u002Fworkspace\u002Fskills\u002Fproductivity\u002Fapproved-global\u002FSKILL.md",[],[],{"skillNo":98,"name":93,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":19},"01M75BD54973NF4BHPZR3F4Z8A","https:\u002F\u002Fgithub.com\u002Ffmercurio\u002Fclawdia-custom-skills\u002Fblob\u002Fmain\u002Ftools\u002Fskill_deploy\u002Ftests\u002Ffixtures\u002Fworkspace\u002Fskills\u002Fproductivity\u002Fapproved-global-duplicate\u002FSKILL.md",[],[],{"skillNo":103,"name":74,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":104,"categories":105,"keywords":106,"publishedAt":19},"01M75BD2N1FJZ142MYPJ19R29Z","https:\u002F\u002Fgithub.com\u002Ffmercurio\u002Fclawdia-custom-skills\u002Fblob\u002Fmain\u002Ftools\u002Fskill_deploy\u002Ftests\u002Ffixtures\u002Fworkspace\u002Fruntime\u002Fskills\u002Fproductivity\u002Foverlay-skill\u002FSKILL.md",[],[]]