@nano-step/nano-brain 2026.1.14

package/SKILL.md

@@ -0,0 +1,109 @@
+# nano-brain
+
+Persistent memory for AI coding agents. Hybrid search (BM25 + semantic + LLM reranking) across past sessions, codebase, notes, and daily logs.
+
+## Slash Commands
+
+| Command | When to Use |
+|---------|-------------|
+| `/nano-brain-init` | First time in a workspace — indexes codebase and sets up memory |
+| `/nano-brain-status` | Check health: document counts, embedding progress, server status |
+| `/nano-brain-reindex` | After git pull, branch switch, or major code changes |
+
+## CLI Commands
+
+All memory operations use the `npx nano-brain` CLI via the Bash tool.
+
+### Search
+
+| Command | Use When | Speed |
+|---------|----------|-------|
+| `npx nano-brain query "search terms"` | Best quality, complex questions (BM25 + vector + reranking) | Slower |
+| `npx nano-brain search "search terms"` | Exact keyword: error messages, function names, specific terms | Fast |
+| `npx nano-brain vsearch "search terms"` | Conceptual: "how does auth work", "payment flow" | Medium |
+
+**Default: Use `npx nano-brain query`** — it gives best results for most questions.
+
+**Search options:**
+- `-n <limit>` — Max results (default: 10)
+- `-c <collection>` — Filter by collection (codebase, sessions, memory)
+- `--full` — Show full content of results
+- `--json` — Output as JSON
+- `--files` — Show file paths only
+- `--min-score=<n>` — Minimum score threshold
+
+### Retrieval
+
+| Command | Use When |
+|---------|----------|
+| `npx nano-brain get <docid-or-path>` | Retrieve specific document by path or docid |
+| `npx nano-brain get <id> --full` | Full content with all metadata |
+| `npx nano-brain get <id> --from=<line> --lines=<n>` | Specific line range |
+
+### Management
+
+| Command | Use When |
+|---------|----------|
+| `npx nano-brain status` | Check index health, embedding progress |
+| `npx nano-brain update` | Refresh all collection indexes |
+| `npx nano-brain harvest` | Harvest past AI sessions into searchable markdown |
+| `npx nano-brain embed` | Generate embeddings for unembedded chunks |
+| `npx nano-brain init --root=<path>` | Re-index a workspace |
+
+### Writing Notes
+
+There is no CLI write command. To save a note, create a markdown file directly:
+
+```bash
+# Save a decision or insight
+cat > ~/.nano-brain/memory/$(date +%Y-%m-%d)-topic.md << 'EOF'
+## Summary
+- Decision: ...
+- Why: ...
+- Files: ...
+EOF
+```
+
+Then run `npx nano-brain update` to index the new file.
+
+## When to Use Memory
+
+**Before starting work:**
+- Recall past decisions on similar features
+- Find debugging insights from previous sessions
+- Check existing patterns in codebase
+
+**After completing work:**
+- Save key architectural decisions
+- Document non-obvious fixes
+- Record domain knowledge for future sessions
+
+## Collection Filtering
+
+Add `-c <collection>` to narrow search scope:
+
+| Collection | Contains |
+|------------|----------|
+| `codebase` | Source files from workspace |
+| `sessions` | Past AI coding sessions |
+| `memory` | Daily logs (tagged with workspace context) |
+
+Omit `-c` to search everything (recommended for most queries).
+
+## Memory vs Native Tools
+
+| Task | Use |
+|------|-----|
+| Semantic search, past context, cross-session recall | **nano-brain** |
+| Exact code patterns, AST structure, precise matches | **grep, ast-grep, glob** |
+
+They complement each other. Use both.
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| 0 codebase docs | Run `/nano-brain-init` |
+| Embeddings stuck | Check Ollama running: `ollama serve` |
+| Stale results | Run `/nano-brain-reindex` |
+| New notes not searchable | Run `npx nano-brain update` |

package/bin/cli.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const entry = join(__dirname, '..', 'src', 'index.ts');
+const args = process.argv.slice(2);
+
+let tsxBin;
+try {
+  const require = createRequire(join(__dirname, '..', 'package.json'));
+  tsxBin = join(dirname(require.resolve('tsx/package.json')), 'dist', 'cli.mjs');
+} catch {
+  tsxBin = join(__dirname, '..', 'node_modules', '.bin', 'tsx');
+}
+
+try {
+  execFileSync('node', [tsxBin, entry, ...args], { stdio: 'inherit' });
+} catch (err) {
+  if (err.message && !err.status) {
+    console.error('nano-brain: failed to start —', err.message);
+  }
+  process.exit(err.status || 1);
+}

package/commands/nano-brain-init.md

@@ -0,0 +1,36 @@
+---
+description: Initialize nano-brain persistent memory for the current workspace.
+---
+
+## Prerequisites
+
+nano-brain MCP server must be configured in opencode.json. If `memory_status` tool is not available, tell user to add nano-brain to their MCP config first.
+
+## Steps
+
+1. Call `memory_status` tool to check current state
+   - If codebase > 0 docs: already initialized, skip to step 4
+   - If error "tool not found": MCP not configured, stop and instruct user
+
+2. Call `memory_index_codebase` with `root` = current workspace path
+   - This indexes source files (respects .gitignore)
+
+3. Call `memory_update` to index sessions and curated notes
+
+4. Call `memory_status` again and report:
+   - Total documents indexed
+   - Pending embeddings count
+   - Embedding server status (connected/disconnected)
+
+## Output Format
+
+```
+nano-brain initialized:
+- Codebase: X files
+- Sessions: Y documents  
+- Pending embeddings: Z (processing in background)
+- Embedding server: ✅ connected / ❌ disconnected
+```
+
+If pending embeddings > 0, explain they process automatically when MCP server runs.
+If embedding server disconnected, suggest: "Start Ollama: `ollama serve`"

package/commands/nano-brain-reindex.md

@@ -0,0 +1,31 @@
+---
+description: Rescan codebase and refresh all nano-brain indexes after branch switch or code changes.
+---
+
+## When to Use
+
+- After `git checkout`, `git pull`, or branch switch
+- After major code changes (new files, deleted files, refactors)
+- When search results seem stale or missing recent changes
+
+## Steps
+
+1. Call `memory_index_codebase` with `root` = current workspace path
+   - Detects new, changed, and deleted files via content hash
+   - Only re-indexes what changed (incremental)
+
+2. Call `memory_update` to refresh session and note indexes
+
+3. Call `memory_status` and report:
+
+```
+Reindex complete:
+- Codebase: X files (Y new, Z updated)
+- Pending embeddings: N
+```
+
+## Notes
+
+- Reindexing is incremental — unchanged files are skipped
+- New/changed files need embedding — happens in background
+- If many pending embeddings, they process automatically over time

package/commands/nano-brain-status.md

@@ -0,0 +1,32 @@
+---
+description: Show nano-brain memory health and statistics.
+---
+
+## Steps
+
+1. Call `memory_status` tool
+
+2. Present results in this format:
+
+```
+nano-brain Status
+─────────────────
+Documents: X total
+  - codebase: A files
+  - sessions: B documents
+  - memory: C notes
+
+Embeddings: Y embedded, Z pending
+Server: ✅ connected (model) / ❌ disconnected
+```
+
+## Suggested Actions
+
+Based on status, suggest ONE relevant action:
+
+| Condition | Suggestion |
+|-----------|------------|
+| codebase = 0 | "Run `/nano-brain-init` to index this workspace" |
+| pending > 100 | "Embeddings processing in background. Check again in a few minutes." |
+| server disconnected | "Start Ollama: `ollama serve`" |
+| all good | "Memory system healthy. Use `memory_query` to search." |