@voidwire/lore 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rudy Ruiz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# lore
+
+Unified knowledge CLI — search, list, and capture your indexed knowledge fabric.
+
+## Philosophy
+
+- **Unified** — Single entry point for all knowledge operations
+- **Library-first** — Import functions directly, CLI is a thin wrapper
+- **Composable** — JSON output pipes to jq, grep, other Unix tools
+- **Zero duplication** — Re-exports from lore-search and lore-capture
+
+## Installation
+
+```bash
+cd llmcli-tools/packages/lore
+bun link
+```
+
+## CLI Usage
+
+```bash
+lore search <query>                    # Search all sources
+lore search <source> <query>           # Search specific source
+lore search --sources                  # List indexed sources
+
+lore list <domain>                     # List domain entries
+lore list --domains                    # List available domains
+
+lore capture task|knowledge|note       # Capture knowledge
+```
+
+### Search Options
+
+- `--limit <n>` — Maximum results (default: 20)
+- `--since <date>` — Filter by date (today, yesterday, this-week, YYYY-MM-DD)
+- `--sources` — List indexed sources with counts
+
+### List Options
+
+- `--limit <n>` — Maximum entries
+- `--format <fmt>` — Output format: json (default), jsonl, human
+- `--domains` — List available domains
+
+### Capture Types
+
+```bash
+# Task completion
+lore capture task --project=myproject --name="Task name" \
+  --problem="What was solved" --solution="How it was solved"
+
+# Knowledge insight
+lore capture knowledge --context=myproject \
+  --text="Insight learned" --type=learning
+
+# Quick note
+lore capture note --text="Remember this" --tags=tag1,tag2
+```
+
+## Library Usage
+
+The real power is programmatic access:
+
+```typescript
+import {
+  // Search (from lore-search)
+  search,
+  listSources,
+  type SearchResult,
+  type SearchOptions,
+
+  // List (local)
+  list,
+  listDomains,
+  DOMAINS,
+  type Domain,
+  type ListResult,
+
+  // Capture (from lore-capture)
+  captureKnowledge,
+  captureTask,
+  captureNote,
+  type KnowledgeInput,
+  type TaskInput,
+  type NoteInput,
+} from "lore";
+
+// Search
+const results = search("authentication", { limit: 10 });
+
+// List
+const devProjects = list("development");
+
+// Capture
+captureKnowledge({
+  context: "myproject",
+  text: "Important insight",
+  type: "learning",
+});
+```
+
+## Domains
+
+15 domains available for `lore list`:
+
+| Domain | Description |
+|--------|-------------|
+| development | Development projects |
+| tasks | Flux tasks and ideas |
+| events | Events by project |
+| blogs | Blog posts |
+| commits | Git commits |
+| explorations | Project explorations |
+| readmes | Project READMEs |
+| obsidian | Obsidian vault notes |
+| captures | Quick captures |
+| books | Books read |
+| movies | Movies watched |
+| podcasts | Podcast subscriptions |
+| interests | Personal interests |
+| people | People and relationships |
+| habits | Habit tracking |
+
+## Knowledge Types
+
+For `lore capture knowledge --type`:
+
+- `decision` — Architectural or design decisions
+- `learning` — Something learned during work
+- `gotcha` — Pitfall or gotcha to remember
+- `preference` — User preference discovered
+- `project` — Project-level insight
+- `conversation` — Insight from conversation
+- `knowledge` — General knowledge
+
+## Architecture
+
+```
+lore/
+├── index.ts              # Re-exports from lib/
+├── cli.ts                # Unified CLI (search|list|capture)
+├── lib/
+│   ├── search.ts         # FTS5 search (SQLite)
+│   ├── list.ts           # Domain listing
+│   └── capture.ts        # JSONL capture
+└── package.json          # Zero dependencies
+```
+
+Self-contained package. No workspace dependencies. Ready for npm publish.
+
+## Data Locations
+
+- `~/.local/share/lore/lore.db` — SQLite FTS5 database (search, list)
+- `~/.local/share/lore/log.jsonl` — Capture event log
+
+## Exit Codes
+
+- `0` — Success
+- `1` — Validation error (missing args, invalid domain)
+- `2` — Runtime error (database not found)

package/cli.ts

@@ -0,0 +1,433 @@
+#!/usr/bin/env bun
+/**
+ * lore - Unified knowledge CLI
+ *
+ * Philosophy:
+ * - Single entry point for knowledge operations
+ * - Search, list, and capture indexed knowledge
+ * - JSON output for composability
+ *
+ * Usage:
+ *   lore search <query>                   Search all sources
+ *   lore search <source> <query>          Search specific source
+ *   lore list <domain>                    List domain entries
+ *   lore capture task|knowledge|note      Capture knowledge
+ *
+ * Exit codes:
+ *   0 - Success
+ *   1 - Validation error
+ *   2 - Runtime error
+ */
+
+import {
+  search,
+  listSources,
+  list,
+  listDomains,
+  captureTask,
+  captureKnowledge,
+  captureNote,
+  DOMAINS,
+  type SearchResult,
+  type ListResult,
+  type ListEntry,
+  type Domain,
+  type TaskInput,
+  type KnowledgeInput,
+  type NoteInput,
+  type KnowledgeCaptureType,
+} from "./index";
+
+// ============================================================================
+// Argument Parsing
+// ============================================================================
+
+function parseArgs(args: string[]): Map<string, string> {
+  const parsed = new Map<string, string>();
+  let i = 0;
+
+  while (i < args.length) {
+    const arg = args[i];
+
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+
+      if (key.includes("=")) {
+        const [k, v] = key.split("=", 2);
+        parsed.set(k, v);
+        i++;
+      } else if (i + 1 < args.length && !args[i + 1].startsWith("--")) {
+        parsed.set(key, args[i + 1]);
+        i += 2;
+      } else {
+        parsed.set(key, "true");
+        i++;
+      }
+    } else {
+      i++;
+    }
+  }
+
+  return parsed;
+}
+
+function getPositionalArgs(args: string[]): string[] {
+  return args.filter((arg) => !arg.startsWith("--"));
+}
+
+function hasFlag(args: string[], flag: string): boolean {
+  return args.includes(`--${flag}`) || args.includes(`-${flag.charAt(0)}`);
+}
+
+function parseList(value: string | undefined): string[] | undefined {
+  if (!value) return undefined;
+  const items = value
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return items.length > 0 ? items : undefined;
+}
+
+// ============================================================================
+// Output Helpers
+// ============================================================================
+
+interface OutputResult {
+  success: boolean;
+  [key: string]: unknown;
+}
+
+function output(result: OutputResult): void {
+  console.log(JSON.stringify(result, null, 2));
+}
+
+function fail(error: string, code: number = 1): never {
+  output({ success: false, error });
+  console.error(`❌ ${error}`);
+  process.exit(code);
+}
+
+// ============================================================================
+// Search Command
+// ============================================================================
+
+function handleSearch(args: string[]): void {
+  const parsed = parseArgs(args);
+  const positional = getPositionalArgs(args);
+
+  // Handle --sources flag
+  if (hasFlag(args, "sources")) {
+    const sources = listSources();
+    output({ success: true, sources });
+    console.error(`✅ ${sources.length} sources indexed`);
+    process.exit(0);
+  }
+
+  if (positional.length === 0) {
+    fail("Missing search query. Use: lore search <query>");
+  }
+
+  // Determine source and query
+  let source: string | undefined;
+  let query: string;
+
+  if (positional.length === 1) {
+    query = positional[0];
+  } else {
+    source = positional[0];
+    query = positional.slice(1).join(" ");
+  }
+
+  const limit = parsed.has("limit") ? parseInt(parsed.get("limit")!, 10) : 20;
+  const since = parsed.get("since");
+
+  try {
+    const results = search(query, { source, limit, since });
+    output({
+      success: true,
+      results,
+      count: results.length,
+    });
+    console.error(
+      `✅ ${results.length} result${results.length !== 1 ? "s" : ""} found`,
+    );
+    process.exit(0);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    fail(message, 2);
+  }
+}
+
+// ============================================================================
+// List Command
+// ============================================================================
+
+function formatHumanOutput(result: ListResult): string {
+  const lines: string[] = [`${result.domain} (${result.count} entries):`, ""];
+
+  for (const entry of result.entries) {
+    lines.push(`  ${entry.title}`);
+    if (entry.metadata.description) {
+      lines.push(`    ${entry.metadata.description}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function handleList(args: string[]): void {
+  const parsed = parseArgs(args);
+  const positional = getPositionalArgs(args);
+
+  // Handle --domains flag
+  if (hasFlag(args, "domains")) {
+    output({ success: true, domains: listDomains() });
+    console.error(`✅ ${DOMAINS.length} domains available`);
+    process.exit(0);
+  }
+
+  if (positional.length === 0) {
+    fail(`Missing domain. Available: ${DOMAINS.join(", ")}`);
+  }
+
+  const domain = positional[0] as Domain;
+
+  if (!DOMAINS.includes(domain)) {
+    fail(`Invalid domain: ${domain}. Available: ${DOMAINS.join(", ")}`);
+  }
+
+  const limit = parsed.has("limit")
+    ? parseInt(parsed.get("limit")!, 10)
+    : undefined;
+  const format = parsed.get("format") || "json";
+
+  try {
+    const result = list(domain, { limit });
+
+    if (format === "human") {
+      console.log(formatHumanOutput(result));
+    } else if (format === "jsonl") {
+      for (const entry of result.entries) {
+        console.log(JSON.stringify(entry));
+      }
+    } else {
+      output({
+        success: true,
+        domain: result.domain,
+        entries: result.entries,
+        count: result.count,
+      });
+    }
+
+    console.error(`✅ ${result.count} entries in ${domain}`);
+    process.exit(0);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    fail(message, 2);
+  }
+}
+
+// ============================================================================
+// Capture Command
+// ============================================================================
+
+function handleCaptureTask(args: string[]): void {
+  const parsed = parseArgs(args);
+
+  const required = ["project", "name", "problem", "solution"];
+  const missing = required.filter((f) => !parsed.has(f));
+  if (missing.length > 0) {
+    fail(`Missing required fields: ${missing.join(", ")}`);
+  }
+
+  const input: TaskInput = {
+    project: parsed.get("project")!,
+    name: parsed.get("name")!,
+    problem: parsed.get("problem")!,
+    solution: parsed.get("solution")!,
+    code: parsed.get("code"),
+    discoveries: parseList(parsed.get("discoveries")),
+    deviations: parsed.get("deviations"),
+    pattern: parsed.get("pattern"),
+    keywords: parseList(parsed.get("keywords")),
+    tech: parseList(parsed.get("tech")),
+    difficulty: parsed.get("difficulty"),
+  };
+
+  const result = captureTask(input);
+  output(result);
+
+  if (result.success) {
+    console.error("✅ Task logged");
+    process.exit(0);
+  } else {
+    console.error(`❌ ${result.error}`);
+    process.exit(2);
+  }
+}
+
+function handleCaptureKnowledge(args: string[]): void {
+  const parsed = parseArgs(args);
+
+  const required = ["context", "text", "type"];
+  const missing = required.filter((f) => !parsed.has(f));
+  if (missing.length > 0) {
+    fail(`Missing required fields: ${missing.join(", ")}`);
+  }
+
+  const input: KnowledgeInput = {
+    context: parsed.get("context")!,
+    text: parsed.get("text")!,
+    type: parsed.get("type")! as KnowledgeCaptureType,
+  };
+
+  const result = captureKnowledge(input);
+  output(result);
+
+  if (result.success) {
+    console.error("✅ Knowledge logged");
+    process.exit(0);
+  } else {
+    console.error(`❌ ${result.error}`);
+    process.exit(1);
+  }
+}
+
+function handleCaptureNote(args: string[]): void {
+  const parsed = parseArgs(args);
+
+  if (!parsed.has("text")) {
+    fail("Missing required field: text");
+  }
+
+  const input: NoteInput = {
+    text: parsed.get("text")!,
+    tags: parseList(parsed.get("tags")),
+    context: parsed.get("context"),
+  };
+
+  const result = captureNote(input);
+  output(result);
+
+  if (result.success) {
+    console.error("✅ Note logged");
+    process.exit(0);
+  } else {
+    console.error(`❌ ${result.error}`);
+    process.exit(2);
+  }
+}
+
+function handleCapture(args: string[]): void {
+  if (args.length === 0) {
+    fail("Missing capture type. Use: task, knowledge, or note");
+  }
+
+  const captureType = args[0];
+  const captureArgs = args.slice(1);
+
+  switch (captureType) {
+    case "task":
+      handleCaptureTask(captureArgs);
+      break;
+    case "knowledge":
+      handleCaptureKnowledge(captureArgs);
+      break;
+    case "note":
+      handleCaptureNote(captureArgs);
+      break;
+    default:
+      fail(
+        `Unknown capture type: ${captureType}. Use: task, knowledge, or note`,
+      );
+  }
+}
+
+// ============================================================================
+// Help & Main
+// ============================================================================
+
+function showHelp(): void {
+  console.log(`
+lore - Unified knowledge CLI
+
+Philosophy:
+  Single entry point for your knowledge fabric.
+  Search, list, and capture indexed knowledge.
+  JSON output for composability with jq, grep, etc.
+
+Usage:
+  lore search <query>                   Search all sources
+  lore search <source> <query>          Search specific source
+  lore search --sources                 List indexed sources
+  lore list <domain>                    List domain entries
+  lore list --domains                   List available domains
+  lore capture task|knowledge|note      Capture knowledge
+
+Search Options:
+  --limit <n>       Maximum results (default: 20)
+  --since <date>    Filter by date (today, yesterday, this-week, YYYY-MM-DD)
+  --sources         List indexed sources with counts
+
+List Options:
+  --limit <n>       Maximum entries
+  --format <fmt>    Output format: json (default), jsonl, human
+  --domains         List available domains
+
+Capture Types:
+  task              Log task completion
+    --project       Project name (required)
+    --name          Task name (required)
+    --problem       Problem solved (required)
+    --solution      Solution pattern (required)
+
+  knowledge         Log insight
+    --context       Context/project name (required)
+    --text          Insight text (required)
+    --type          Type: decision, learning, gotcha, preference (required)
+
+  note              Quick note
+    --text          Note content (required)
+    --tags          Comma-separated tags
+    --context       Optional context
+
+Examples:
+  lore search "authentication"
+  lore search blogs "typescript patterns"
+  lore list development
+  lore list commits --limit 10 --format human
+  lore capture knowledge --context=lore --text="Unified CLI works" --type=learning
+`);
+  process.exit(0);
+}
+
+function main(): void {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || hasFlag(args, "help") || args[0] === "-h") {
+    showHelp();
+  }
+
+  const command = args[0];
+  const commandArgs = args.slice(1);
+
+  switch (command) {
+    case "search":
+      handleSearch(commandArgs);
+      break;
+    case "list":
+      handleList(commandArgs);
+      break;
+    case "capture":
+      handleCapture(commandArgs);
+      break;
+    case "--help":
+    case "-h":
+      showHelp();
+      break;
+    default:
+      fail(`Unknown command: ${command}. Use: search, list, or capture`);
+  }
+}
+
+main();

package/index.ts

@@ -0,0 +1,41 @@
+/**
+ * lore - Library exports
+ *
+ * Unified knowledge CLI: search, list, and capture indexed knowledge.
+ * Self-contained package with zero workspace dependencies.
+ *
+ * Usage:
+ *   import { search, list, captureKnowledge } from "lore";
+ */
+
+// Search
+export {
+  search,
+  listSources,
+  type SearchResult,
+  type SearchOptions,
+} from "./lib/search";
+
+// List
+export {
+  list,
+  listDomains,
+  DOMAINS,
+  type Domain,
+  type ListOptions,
+  type ListEntry,
+  type ListResult,
+} from "./lib/list";
+
+// Capture
+export {
+  captureKnowledge,
+  captureTask,
+  captureNote,
+  type CaptureResult,
+  type KnowledgeInput,
+  type KnowledgeCaptureType,
+  type TaskInput,
+  type NoteInput,
+  type CaptureEvent,
+} from "./lib/capture";

package/lib/capture.ts

@@ -0,0 +1,211 @@
+/**
+ * lib/capture.ts - Knowledge capture functions
+ *
+ * Pure functions for capturing tasks, insights, and notes.
+ * Writes to ~/.local/share/lore/log.jsonl
+ */
+
+import { appendFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+export interface CaptureResult {
+  success: boolean;
+  error?: string;
+}
+
+export type KnowledgeCaptureType =
+  | "project"
+  | "conversation"
+  | "decision"
+  | "learning"
+  | "gotcha"
+  | "preference"
+  | "knowledge";
+
+export interface KnowledgeInput {
+  context: string;
+  text: string;
+  type: KnowledgeCaptureType;
+}
+
+export interface TaskInput {
+  project: string;
+  name: string;
+  problem: string;
+  solution: string;
+  code?: string;
+  discoveries?: string[];
+  deviations?: string;
+  pattern?: string;
+  keywords?: string[];
+  tech?: string[];
+  difficulty?: string;
+}
+
+export interface NoteInput {
+  text: string;
+  tags?: string[];
+  context?: string;
+}
+
+interface TaskEvent {
+  event: "captured";
+  type: "task";
+  timestamp: string;
+  data: {
+    project: string;
+    task_name: string;
+    problem_solved: string;
+    solution_pattern: string;
+    code_snippet?: string;
+    discoveries?: string[];
+    deviations?: string;
+    reusable_pattern?: string;
+    keywords?: string[];
+    tech_used?: string[];
+    difficulty_notes?: string;
+  };
+}
+
+interface KnowledgeEvent {
+  event: "captured";
+  type: "knowledge";
+  timestamp: string;
+  data: {
+    context: string;
+    capture: string;
+    type: KnowledgeCaptureType;
+  };
+}
+
+interface NoteEvent {
+  event: "captured";
+  type: "note";
+  timestamp: string;
+  data: {
+    content: string;
+    tags?: string[];
+    context?: string;
+  };
+}
+
+type CaptureEvent = TaskEvent | KnowledgeEvent | NoteEvent;
+
+function getLogPath(): string {
+  const dataHome =
+    process.env.XDG_DATA_HOME || join(homedir(), ".local", "share");
+  return join(dataHome, "lore", "log.jsonl");
+}
+
+function ensureLogDirectory(): void {
+  const logPath = getLogPath();
+  const logDir = join(logPath, "..");
+
+  if (!existsSync(logDir)) {
+    mkdirSync(logDir, { recursive: true });
+  }
+}
+
+function getTimestamp(): string {
+  return new Date().toISOString();
+}
+
+function writeEvent(event: CaptureEvent): CaptureResult {
+  ensureLogDirectory();
+
+  const logPath = getLogPath();
+  const eventWithTimestamp = { ...event, timestamp: getTimestamp() };
+  const jsonLine = JSON.stringify(eventWithTimestamp) + "\n";
+
+  try {
+    appendFileSync(logPath, jsonLine, "utf8");
+    return { success: true };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Failed to write event to ${logPath}: ${error}`,
+    };
+  }
+}
+
+const VALID_KNOWLEDGE_TYPES: KnowledgeCaptureType[] = [
+  "project",
+  "conversation",
+  "decision",
+  "learning",
+  "gotcha",
+  "preference",
+  "knowledge",
+];
+
+/**
+ * Capture a knowledge insight
+ */
+export function captureKnowledge(input: KnowledgeInput): CaptureResult {
+  if (!VALID_KNOWLEDGE_TYPES.includes(input.type)) {
+    return {
+      success: false,
+      error: `Invalid type: ${input.type}. Must be one of: ${VALID_KNOWLEDGE_TYPES.join(", ")}`,
+    };
+  }
+
+  const event: KnowledgeEvent = {
+    event: "captured",
+    type: "knowledge",
+    timestamp: "",
+    data: {
+      context: input.context,
+      capture: input.text,
+      type: input.type,
+    },
+  };
+
+  return writeEvent(event);
+}
+
+/**
+ * Capture a task completion
+ */
+export function captureTask(input: TaskInput): CaptureResult {
+  const event: TaskEvent = {
+    event: "captured",
+    type: "task",
+    timestamp: "",
+    data: {
+      project: input.project,
+      task_name: input.name,
+      problem_solved: input.problem,
+      solution_pattern: input.solution,
+      code_snippet: input.code,
+      discoveries: input.discoveries,
+      deviations: input.deviations,
+      reusable_pattern: input.pattern,
+      keywords: input.keywords,
+      tech_used: input.tech,
+      difficulty_notes: input.difficulty,
+    },
+  };
+
+  return writeEvent(event);
+}
+
+/**
+ * Capture a quick note
+ */
+export function captureNote(input: NoteInput): CaptureResult {
+  const event: NoteEvent = {
+    event: "captured",
+    type: "note",
+    timestamp: "",
+    data: {
+      content: input.text,
+      tags: input.tags,
+      context: input.context,
+    },
+  };
+
+  return writeEvent(event);
+}
+
+export type { CaptureEvent };

package/lib/list.ts

@@ -0,0 +1,183 @@
+/**
+ * lib/list.ts - Domain listing functions
+ *
+ * Browse indexed domains without search queries.
+ * Uses Bun's built-in SQLite for zero external dependencies.
+ */
+
+import { Database } from "bun:sqlite";
+import { homedir } from "os";
+import { existsSync } from "fs";
+
+// Domain types - sources that can be listed
+export type Domain =
+  | "development"
+  | "tasks"
+  | "events"
+  | "blogs"
+  | "commits"
+  | "explorations"
+  | "readmes"
+  | "obsidian"
+  | "captures"
+  | "books"
+  | "movies"
+  | "podcasts"
+  | "interests"
+  | "people"
+  | "habits";
+
+export const DOMAINS: Domain[] = [
+  "development",
+  "tasks",
+  "events",
+  "blogs",
+  "commits",
+  "explorations",
+  "readmes",
+  "obsidian",
+  "captures",
+  "books",
+  "movies",
+  "podcasts",
+  "interests",
+  "people",
+  "habits",
+];
+
+// Domains that query the 'personal' source with type filter
+const PERSONAL_SUBTYPES: Partial<Record<Domain, string>> = {
+  books: "book",
+  movies: "movie",
+  podcasts: "podcast",
+  interests: "interest",
+  people: "person",
+  habits: "habit",
+};
+
+export interface ListOptions {
+  limit?: number;
+}
+
+export interface ListEntry {
+  title: string;
+  content: string;
+  metadata: Record<string, unknown>;
+}
+
+export interface ListResult {
+  domain: Domain;
+  entries: ListEntry[];
+  count: number;
+}
+
+// Database path following XDG spec
+function getDatabasePath(): string {
+  return `${homedir()}/.local/share/lore/lore.db`;
+}
+
+interface RawRow {
+  title: string;
+  content: string;
+  metadata: string;
+}
+
+/**
+ * Query entries by source
+ */
+function queryBySource(
+  db: Database,
+  source: string,
+  limit?: number,
+): ListEntry[] {
+  const sql = limit
+    ? `SELECT title, content, metadata FROM search WHERE source = ? LIMIT ?`
+    : `SELECT title, content, metadata FROM search WHERE source = ?`;
+
+  const stmt = limit ? db.prepare(sql) : db.prepare(sql);
+  const rows = (limit ? stmt.all(source, limit) : stmt.all(source)) as RawRow[];
+
+  return rows.map((row) => ({
+    title: row.title,
+    content: row.content,
+    metadata: JSON.parse(row.metadata || "{}"),
+  }));
+}
+
+/**
+ * Query personal entries by subtype
+ */
+function queryPersonalType(
+  db: Database,
+  type: string,
+  limit?: number,
+): ListEntry[] {
+  // Query personal source, then filter by type in metadata
+  const sql = limit
+    ? `SELECT title, content, metadata FROM search WHERE source = 'personal' LIMIT ?`
+    : `SELECT title, content, metadata FROM search WHERE source = 'personal'`;
+
+  const stmt = db.prepare(sql);
+  const rows = (limit ? stmt.all(limit * 10) : stmt.all()) as RawRow[]; // Over-fetch for filtering
+
+  const filtered = rows
+    .map((row) => ({
+      title: row.title,
+      content: row.content,
+      metadata: JSON.parse(row.metadata || "{}"),
+    }))
+    .filter((entry) => entry.metadata.type === type);
+
+  return limit ? filtered.slice(0, limit) : filtered;
+}
+
+/**
+ * List all entries in a domain
+ *
+ * @param domain - The domain to list (development, tasks, blogs, etc.)
+ * @param options - Optional limit
+ * @returns ListResult with entries and count
+ * @throws Error if database doesn't exist or domain is invalid
+ */
+export function list(domain: Domain, options: ListOptions = {}): ListResult {
+  if (!DOMAINS.includes(domain)) {
+    throw new Error(
+      `Invalid domain: ${domain}. Valid domains: ${DOMAINS.join(", ")}`,
+    );
+  }
+
+  const dbPath = getDatabasePath();
+
+  if (!existsSync(dbPath)) {
+    throw new Error(`Database not found: ${dbPath}. Run lore-index-all first.`);
+  }
+
+  const db = new Database(dbPath, { readonly: true });
+
+  try {
+    let entries: ListEntry[];
+
+    // Check if this is a personal subtype domain
+    const personalType = PERSONAL_SUBTYPES[domain];
+    if (personalType) {
+      entries = queryPersonalType(db, personalType, options.limit);
+    } else {
+      entries = queryBySource(db, domain, options.limit);
+    }
+
+    return {
+      domain,
+      entries,
+      count: entries.length,
+    };
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Get available domains
+ */
+export function listDomains(): Domain[] {
+  return [...DOMAINS];
+}

package/lib/search.ts

@@ -0,0 +1,112 @@
+/**
+ * lib/search.ts - SQLite FTS5 query functions
+ *
+ * Pure functions for querying the Lore FTS5 database.
+ * Uses Bun's built-in SQLite for zero external dependencies.
+ */
+
+import { Database } from "bun:sqlite";
+import { homedir } from "os";
+import { existsSync } from "fs";
+
+export interface SearchResult {
+  source: string;
+  title: string;
+  content: string;
+  metadata: string;
+  rank: number;
+}
+
+export interface SearchOptions {
+  source?: string;
+  limit?: number;
+  since?: string;
+}
+
+function getDatabasePath(): string {
+  return `${homedir()}/.local/share/lore/lore.db`;
+}
+
+/**
+ * Search the Lore FTS5 database
+ *
+ * @param query - FTS5 search query (supports AND, OR, NOT, phrases)
+ * @param options - Optional source filter and result limit
+ * @returns Array of search results ranked by relevance
+ * @throws Error if database doesn't exist or query fails
+ */
+export function search(
+  query: string,
+  options: SearchOptions = {},
+): SearchResult[] {
+  const dbPath = getDatabasePath();
+
+  if (!existsSync(dbPath)) {
+    throw new Error(`Database not found: ${dbPath}. Run lore-db-init first.`);
+  }
+
+  const db = new Database(dbPath, { readonly: true });
+
+  try {
+    const limit = options.limit ?? 20;
+
+    const conditions: string[] = ["search MATCH ?"];
+    const params: (string | number)[] = [query];
+
+    if (options.source) {
+      conditions.push("source = ?");
+      params.push(options.source);
+    }
+
+    if (options.since) {
+      conditions.push(
+        "json_extract(metadata, '$.date') IS NOT NULL AND json_extract(metadata, '$.date') != 'unknown' AND json_extract(metadata, '$.date') >= ?",
+      );
+      params.push(options.since);
+    }
+
+    params.push(limit);
+
+    const sql = `
+      SELECT source, title, snippet(search, 2, '→', '←', '...', 32) as content, metadata, rank
+      FROM search
+      WHERE ${conditions.join(" AND ")}
+      ORDER BY rank
+      LIMIT ?
+    `;
+
+    const stmt = db.prepare(sql);
+    const results = stmt.all(...params) as SearchResult[];
+
+    return results;
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * List all available sources in the database
+ *
+ * @returns Array of source names with entry counts
+ */
+export function listSources(): { source: string; count: number }[] {
+  const dbPath = getDatabasePath();
+
+  if (!existsSync(dbPath)) {
+    throw new Error(`Database not found: ${dbPath}. Run lore-db-init first.`);
+  }
+
+  const db = new Database(dbPath, { readonly: true });
+
+  try {
+    const stmt = db.prepare(`
+      SELECT source, COUNT(*) as count
+      FROM search
+      GROUP BY source
+      ORDER BY count DESC
+    `);
+    return stmt.all() as { source: string; count: number }[];
+  } finally {
+    db.close();
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@voidwire/lore",
+  "version": "0.1.0",
+  "description": "Unified knowledge CLI - Search, list, and capture your indexed knowledge",
+  "type": "module",
+  "main": "./index.ts",
+  "bin": {
+    "lore": "./cli.ts"
+  },
+  "exports": {
+    ".": "./index.ts",
+    "./cli": "./cli.ts"
+  },
+  "files": [
+    "index.ts",
+    "cli.ts",
+    "lib/**/*.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test"
+  },
+  "keywords": [
+    "knowledge",
+    "search",
+    "capture",
+    "fts5",
+    "sqlite",
+    "cli",
+    "llcli"
+  ],
+  "author": "nickpending <nickpending@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nickpending/llmcli-tools.git",
+    "directory": "packages/lore"
+  },
+  "homepage": "https://github.com/nickpending/llmcli-tools/tree/main/packages/lore#readme",
+  "bugs": {
+    "url": "https://github.com/nickpending/llmcli-tools/issues"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "devDependencies": {
+    "bun-types": "latest"
+  }
+}