@titan-design/brain 0.2.0

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@titan-design/brain",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Developer second brain with hybrid RAG search",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/titan-design/brain.git"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "scripts"
+  ],
+  "bin": {
+    "brain": "dist/cli.js"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src __tests__ --no-error-on-unmatched-pattern",
+    "postinstall": "node scripts/postinstall.js",
+    "preuninstall": "node scripts/preuninstall.js"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "@commander-js/extra-typings": "^13.1.0",
+    "better-sqlite3": "^11.8.1",
+    "sqlite-vec": "^0.1.6",
+    "ollama": "^0.5.14",
+    "gray-matter": "^4.0.3",
+    "glob": "^11.0.1",
+    "env-paths": "^3.0.0"
+  },
+  "optionalDependencies": {
+    "@huggingface/transformers": "^3.3.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5",
+    "tsup": "^8.3.6",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.13.4",
+    "tsx": "^4.19.2",
+    "eslint": "^9.20.0",
+    "@eslint/js": "^9.20.0",
+    "typescript-eslint": "^8.24.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/scripts/install.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_URL="https://github.com/hjewkes/brain.git"
+INSTALL_DIR="${BRAIN_INSTALL_DIR:-$HOME/.local/share/brain-cli}"
+BIN_DIR="${HOME}/.local/bin"
+SKILL_NAME="second-brain"
+
+info() { echo "[brain] $*"; }
+error() { echo "[brain] ERROR: $*" >&2; exit 1; }
+
+# Clone or update the repo
+if [ -d "$INSTALL_DIR/.git" ]; then
+  info "Updating existing installation at $INSTALL_DIR"
+  git -C "$INSTALL_DIR" pull --ff-only
+else
+  info "Cloning brain to $INSTALL_DIR"
+  mkdir -p "$(dirname "$INSTALL_DIR")"
+  git clone "$REPO_URL" "$INSTALL_DIR"
+fi
+
+# Build
+info "Installing dependencies and building..."
+cd "$INSTALL_DIR"
+npm ci
+npm run build
+
+# Symlink binary
+mkdir -p "$BIN_DIR"
+ln -sf "$INSTALL_DIR/dist/cli.js" "$BIN_DIR/brain"
+chmod +x "$BIN_DIR/brain"
+info "Linked brain to $BIN_DIR/brain"
+
+# Ensure bin dir is on PATH
+if ! echo "$PATH" | tr ':' '\n' | grep -q "^$BIN_DIR$"; then
+  info "WARNING: $BIN_DIR is not on your PATH"
+  info "Add this to your shell profile: export PATH=\"$BIN_DIR:\$PATH\""
+fi
+
+# Initialize brain if not already done
+if ! brain status --json >/dev/null 2>&1; then
+  info "Running brain init..."
+  brain init
+fi
+
+# Install skill
+SKILL_SOURCE="$INSTALL_DIR/skills/$SKILL_NAME"
+if command -v chezmoi >/dev/null 2>&1; then
+  CHEZMOI_SOURCE="$(chezmoi source-path)"
+  SKILL_DEST="$CHEZMOI_SOURCE/dot_claude/skills/$SKILL_NAME"
+  mkdir -p "$SKILL_DEST"
+  cp "$SKILL_SOURCE/SKILL.md" "$SKILL_DEST/SKILL.md"
+  chezmoi apply
+  info "Installed skill via chezmoi"
+else
+  SKILL_DEST="$HOME/.claude/skills/$SKILL_NAME"
+  mkdir -p "$SKILL_DEST"
+  ln -sf "$SKILL_SOURCE/SKILL.md" "$SKILL_DEST/SKILL.md"
+  info "Linked skill to $SKILL_DEST"
+fi
+
+info "Installation complete!"
+info "Run 'brain --help' to get started."

package/scripts/postinstall.js

@@ -0,0 +1,22 @@
+import { mkdirSync, copyFileSync, existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const skillSource = join(__dirname, '..', 'skill', 'SKILL.md')
+const claudeDir = join(homedir(), '.claude')
+const claudeSkillsDir = join(claudeDir, 'skills', 'brain')
+
+// Skip silently if ~/.claude doesn't exist (user doesn't use Claude Code)
+if (!existsSync(claudeDir)) {
+  process.exit(0)
+}
+
+try {
+  mkdirSync(claudeSkillsDir, { recursive: true })
+  copyFileSync(skillSource, join(claudeSkillsDir, 'SKILL.md'))
+  console.log(`brain: installed Claude Code skill to ${claudeSkillsDir}`)
+} catch {
+  // Don't fail npm install if skill copy fails
+}

package/scripts/preuninstall.js

@@ -0,0 +1,14 @@
+import { rmSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const claudeSkillsDir = join(homedir(), '.claude', 'skills', 'brain')
+
+if (existsSync(claudeSkillsDir)) {
+  try {
+    rmSync(claudeSkillsDir, { recursive: true })
+    console.log(`brain: removed Claude Code skill from ${claudeSkillsDir}`)
+  } catch {
+    // Don't fail npm uninstall if cleanup fails
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: brain
+description: Search and manage your second brain knowledge base. Use when the user asks about their notes, wants to find information, or needs to add/organize knowledge.
+---
+
+# Brain -- Knowledge Management
+
+A CLI for managing a developer second brain with hybrid BM25 + vector search over markdown notes.
+
+## When to Use
+
+- User asks "what do I know about X" or "find my notes on Y"
+- User wants to save something to their knowledge base
+- User asks about stale or outdated notes
+- User wants to check their knowledge base status
+
+## Commands
+
+Use `--json` flag on all commands when processing output programmatically.
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `brain search "<query>" --json` | Hybrid search (BM25 + vector) | `brain search "authentication patterns" --json --limit 5` |
+| `brain search "<query>" --json --expand` | Search with graph-connected notes | `brain search "auth" --json --expand` |
+| `brain add <file>` | Add a note from file | `brain add ~/draft.md --type research --tier slow` |
+| `brain add --title "X" --type note` | Add from stdin | `echo "content" \| brain add --title "My Note" --type note` |
+| `brain status --json` | Database stats | Shows note count, embeddings, staleness |
+| `brain stale --json` | Notes needing review | `brain stale --tier slow --json` |
+| `brain index` | Re-index all notes | Only run when user asks -- this is slow |
+| `brain template <type>` | Output frontmatter template | `brain template research` |
+| `brain graph <note-id> --json` | Show note relations | `brain graph my-note --json` |
+| `brain config get` | Show config | `brain config get` |
+
+## Search Filters
+
+```bash
+brain search "query" --tier slow --tags "typescript,patterns" --confidence high --since 2025-01-01 --json
+```
+
+## Note Conventions
+
+**Types:** `note`, `decision`, `pattern`, `research`, `meeting`, `session-log`, `guide`
+
+**Tiers:**
+- `slow` -- permanent knowledge (notes, decisions, patterns, research). Has review intervals.
+- `fast` -- ephemeral (meetings, session logs). Has expiry dates. Auto-archived.
+
+**Key frontmatter fields:** `title`, `type`, `tier`, `tags`, `summary`, `confidence` (high/medium/low/speculative), `status` (current/outdated/deprecated/draft), `review-interval`, `related`
+
+## Rules
+
+- Always use `--json` when you need to parse output
+- Search before claiming information isn't in the knowledge base
+- Do NOT run `brain index` unless the user explicitly asks -- it processes all files and is slow
+- When adding notes, include frontmatter with at minimum: title, type, tier
+- Present search results with score, file path, and excerpt