notebrain

Name: notebrain
Author: nmdra

25stars2forks

How to install notebrain?

nmdra/notebrain-cli/notebrain

$npx -y skills add nmdra/notebrain-cli --skill notebrain

Installs into the current project.

Summary

Use NoteBrain to search, and explore an Obsidian vault via ChromaDB. Make sure to use this skill whenever the user mentions their notes, knowledge base, Obsidian vault, semantic search, finding connections, unlinked notes, or asks general exploratory questions like "what do I kno

Files · 1

View on GitHub

SKILL.md

1	# NoteBrain CLI Skill for AI Agents
2
3	NoteBrain indexes an Obsidian vault into local ChromaDB for semantic search, graph traversal, and note retrieval.
4
5	## Scope & Boundaries
6
7	NoteBrain is read-only — it searches, retrieves, and explores notes that have already been indexed. It cannot create, rename, move, or edit notes. If the user's request requires writing or modifying vault files, use standard file tools (or the obsidian-cli skill if available) for those mutations, and use NoteBrain only for the discovery/search portion of the workflow.
8
9	## Pre-Flight: Verify NoteBrain Is Available
10
11	Before running your first query in a conversation, confirm NoteBrain is functional:
12
13	```bash
14	notebrain stats --format=json
15	```
16
17	- If the binary is missing or errors, tell the user plainly: _"NoteBrain doesn't appear to be installed or accessible. I can't search your vault without it."_ Do not fall back to `grep`/`find` against raw markdown files — results would be incomplete and miss semantic matches.
18	- If `stats` returns `0` chunks, the vault hasn't been indexed yet. Tell the user: _"Your vault hasn't been indexed. Run `notebrain ingest --vault-path /path/to/vault` first, then ask me again."_
19	- If `stats` succeeds with chunk counts > 0, proceed normally.
20
21	## Core Execution Principles
22
23	1. NoteBrain Only — No Generic Filesystem Search: Never use `grep`, `find`, `ls`, or ad-hoc shell scripts against markdown files. Treat `notebrain` as the sole interface to the vault. If a query returns nothing, refine the query (synonyms, broader/narrower phrasing) rather than falling back to bash.
24
25	2. Session Caching & Reuse: If `backlinks`, `connections`, or `hidden` was already executed for a given `note_slug` earlier in the conversation, reuse those results from context instead of re-querying — unless the user explicitly requests a fresh query or mentions they've just re-indexed/ingested the vault, in which case cached results may be stale.
26
27	3. Prioritize `--context-window N` + `--include-text` Over Blind `get`: Never blindly run `notebrain get <slug>` after a search hit. Full notes can be thousands of lines long; fetching entire notes floods context and wastes tokens. Instead, pass `--context-window N` (e.g., `--context-window 1` or `2`) on your `search`, `hidden`, or `boosted` queries to fetch ±N adjacent chunks around the match. Only use `get` when a task explicitly demands the entire note from start to finish.
28
29	4. Token-Efficient Extraction (`--jsonpath` & `tsv`):
30	- Matching text snippets: `--jsonpath="$.results[*].text"`
31	- Surrounding chunk context: `--jsonpath="$.results[*].context"`
32	- When scanning tabular lists without text content, use `--format tsv` to drop repeating JSON key names.
33	- When outputting full JSON (i.e., not using `--jsonpath`), the `file_path` field is omitted by default to cut token footprint by ~40–50%. Pass `--show-file-path` only if strictly needed.
34
35	5. Intelligent Query Splitting: When researching compound questions or orthogonal topics (e.g., comparing two technologies), split the query into distinct terms to activate multi-hit boosting:
36	- Positional arguments (when exact terms are known): `notebrain search "redis pubsub" "kafka brokers" --limit 5 --format json`
37	- `--split` flag (when splitting natural language by delimiters): `notebrain search "redis, kafka, rabbitmq" --split --limit 5 --format json`
38
39	6. Avoid Blanket Chaining: A single `search` with `--context-window 1 --include-text` answers most questions. Never blindly run `search → backlinks → connections → hidden` sequentially unless the user explicitly requests a comprehensive vault-wide audit of a topic. Pick the exact command tailored to the query.
40
41	7. Keep Result Sets Small: Default `--limit` and `--top-k` to 3–5. Larger result sets rarely add useful signal — they flood context with diminishing-relevance matches and inflate token costs. Only increase beyond 5 when the user explicitly asks for more results or the task requires exhaustive coverage (e.g., "list all notes tagged X").
42
43	## Progressive Retrieval Workflow (`notebrain search`)
44
45	To prevent excessive tool calls, token bloat, and redundant queries, follow a two-step tiered retrieval:
46
47	### Step 1: Start Lean (Candidate & Slug Discovery)
48
49	```bash
50	notebrain search "<query>" --format=json --include-text
51	```
52
53	Check the `score` of you

People who liked this also viewed

6 picks

Type

notebrain

25stars2forks

View on GitHub

How to install notebrain?

nmdra/notebrain-cli/notebrain

$npx -y skills add nmdra/notebrain-cli --skill notebrain

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# NoteBrain CLI Skill for AI Agents
2
3	NoteBrain indexes an Obsidian vault into local ChromaDB for semantic search, graph traversal, and note retrieval.
4
5	## Scope & Boundaries
6
7	NoteBrain is read-only — it searches, retrieves, and explores notes that have already been indexed. It cannot create, rename, move, or edit notes. If the user's request requires writing or modifying vault files, use standard file tools (or the obsidian-cli skill if available) for those mutations, and use NoteBrain only for the discovery/search portion of the workflow.
8
9	## Pre-Flight: Verify NoteBrain Is Available
10
11	Before running your first query in a conversation, confirm NoteBrain is functional:
12
13	```bash
14	notebrain stats --format=json
15	```
16
17	- If the binary is missing or errors, tell the user plainly: _"NoteBrain doesn't appear to be installed or accessible. I can't search your vault without it."_ Do not fall back to `grep`/`find` against raw markdown files — results would be incomplete and miss semantic matches.
18	- If `stats` returns `0` chunks, the vault hasn't been indexed yet. Tell the user: _"Your vault hasn't been indexed. Run `notebrain ingest --vault-path /path/to/vault` first, then ask me again."_
19	- If `stats` succeeds with chunk counts > 0, proceed normally.
20
21	## Core Execution Principles
22
23	1. NoteBrain Only — No Generic Filesystem Search: Never use `grep`, `find`, `ls`, or ad-hoc shell scripts against markdown files. Treat `notebrain` as the sole interface to the vault. If a query returns nothing, refine the query (synonyms, broader/narrower phrasing) rather than falling back to bash.
24
25	2. Session Caching & Reuse: If `backlinks`, `connections`, or `hidden` was already executed for a given `note_slug` earlier in the conversation, reuse those results from context instead of re-querying — unless the user explicitly requests a fresh query or mentions they've just re-indexed/ingested the vault, in which case cached results may be stale.
26
27	3. Prioritize `--context-window N` + `--include-text` Over Blind `get`: Never blindly run `notebrain get <slug>` after a search hit. Full notes can be thousands of lines long; fetching entire notes floods context and wastes tokens. Instead, pass `--context-window N` (e.g., `--context-window 1` or `2`) on your `search`, `hidden`, or `boosted` queries to fetch ±N adjacent chunks around the match. Only use `get` when a task explicitly demands the entire note from start to finish.
28
29	4. Token-Efficient Extraction (`--jsonpath` & `tsv`):
30	- Matching text snippets: `--jsonpath="$.results[*].text"`
31	- Surrounding chunk context: `--jsonpath="$.results[*].context"`
32	- When scanning tabular lists without text content, use `--format tsv` to drop repeating JSON key names.
33	- When outputting full JSON (i.e., not using `--jsonpath`), the `file_path` field is omitted by default to cut token footprint by ~40–50%. Pass `--show-file-path` only if strictly needed.
34
35	5. Intelligent Query Splitting: When researching compound questions or orthogonal topics (e.g., comparing two technologies), split the query into distinct terms to activate multi-hit boosting:
36	- Positional arguments (when exact terms are known): `notebrain search "redis pubsub" "kafka brokers" --limit 5 --format json`
37	- `--split` flag (when splitting natural language by delimiters): `notebrain search "redis, kafka, rabbitmq" --split --limit 5 --format json`
38
39	6. Avoid Blanket Chaining: A single `search` with `--context-window 1 --include-text` answers most questions. Never blindly run `search → backlinks → connections → hidden` sequentially unless the user explicitly requests a comprehensive vault-wide audit of a topic. Pick the exact command tailored to the query.
40
41	7. Keep Result Sets Small: Default `--limit` and `--top-k` to 3–5. Larger result sets rarely add useful signal — they flood context with diminishing-relevance matches and inflate token costs. Only increase beyond 5 when the user explicitly asks for more results or the task requires exhaustive coverage (e.g., "list all notes tagged X").
42
43	## Progressive Retrieval Workflow (`notebrain search`)
44
45	To prevent excessive tool calls, token bloat, and redundant queries, follow a two-step tiered retrieval:
46
47	### Step 1: Start Lean (Candidate & Slug Discovery)
48
49	```bash
50	notebrain search "<query>" --format=json --include-text
51	```
52
53	Check the `score` of you

People who liked this also viewed

6 picks

Type