@titan-design/brain 0.3.0 → 0.5.0

package/README.md

@@ -1,6 +1,15 @@
-# Brain
+# @titan-design/brain
 
-Personal knowledge base and memory engine with hybrid RAG search (BM25 + vector embeddings), LLM-powered memory extraction, and temporal intelligence.
+Developer second brain — hybrid RAG search (BM25 + vector embeddings), LLM-powered memory extraction, project management with AI orchestration, and temporal intelligence.
+
+## Features
+
+- **Hybrid Search** — BM25 + vector with RRF/score fusion, optional cross-encoder reranking
+- **Memory Engine** — LLM-extracted facts with version chaining, temporal validity, auto-forgetting
+- **Project Management** — Full PM module: projects, workstreams, tasks, dependencies, waves, dispatch
+- **AI Orchestration** — Agent routing, claim tokens, worktree isolation, verification, cost tracking
+- **Inbox Pipeline** — Zero-friction capture from CLI, file import, RSS feeds
+- **Module System** — Extensible plugin architecture with namespace isolation
 
 ## Install
 
@@ -15,13 +24,28 @@ Requires Node >= 22.
 ```bash
 brain init                    # Initialize workspace
 brain index                   # Index notes
-brain search "query"          # Hybrid search
+brain search "query"          # Hybrid BM25 + vector search
 brain quick "thought"         # Capture to inbox
 brain extract --all           # Extract memories (requires Ollama)
 ```
 
+## PM Module Quick Start
+
+```bash
+brain pm init "My Project" --prefix MY
+brain pm use MY
+brain pm workstream add "Core Features" --project MY
+brain pm task add "First task" --project MY --workstream 1 --category implementation
+brain pm waves
+brain pm briefing
+```
+
+See [PM Quick Start](docs/pm-module/quickstart.md) for the full 5-minute guide.
+
 ## Commands
 
+### Core
+
 | Command | Description |
 |---------|-------------|
 | `brain init` | Initialize workspace and database |
@@ -35,6 +59,7 @@ brain extract --all           # Extract memories (requires Ollama)
 | `brain extract` | Extract memories from notes (Ollama) |
 | `brain memories` | List, history, and stats for memories |
 | `brain context <id>` | Show context for a note (relations + memories) |
+| `brain lineage <id>` | Show memory version lineage |
 | `brain profile` | Generate agent context profile |
 | `brain tidy` | LLM-powered note cleanup suggestions |
 | `brain doctor` | System health checks (`--fix` for auto-repair) |
@@ -46,13 +71,67 @@ brain extract --all           # Extract memories (requires Ollama)
 | `brain archive` | Archive expired notes |
 | `brain config` | View/set configuration |
 
+### Project Management (`brain pm`)
+
+| Command | Description |
+|---------|-------------|
+| `brain pm init <name> --prefix <P>` | Initialize a new project |
+| `brain pm use <prefix>` | Set active project context |
+| `brain pm list` | List all projects |
+| `brain pm status [prefix]` | Show project status |
+| `brain pm workstream add <name>` | Add a workstream |
+| `brain pm task add <name>` | Create a task |
+| `brain pm task list` | List tasks (filterable by status, workstream) |
+| `brain pm task done <id>` | Mark task done |
+| `brain pm next` | Show eligible tasks (all deps satisfied) |
+| `brain pm waves` | Topological wave grouping of remaining tasks |
+| `brain pm dispatch <id>` | Assemble context bundle for a task |
+| `brain pm complete <id>` | Mark done, run impact analysis |
+| `brain pm briefing` | Session briefing with project state overview |
+| `brain pm audit summary` | Activity log, cost tracking |
+| `brain pm check [--deep]` | Consistency check (structural + semantic analysis) |
+| `brain pm setup` | Configure PM module (paths, hooks) |
+| `brain pm install-hooks` | Install PM hooks and skills (orchestrator + sanity-check) |
+
+## Architecture
+
+```
+src/
+  cli.ts                 — Entry point, Commander program
+  types.ts               — TypeScript interfaces and constants
+  utils.ts               — Shared utilities
+  commands/              — 22 core CLI commands
+  modules/
+    types.ts             — Module system interfaces
+    registry.ts          — ModuleRegistry class
+    context.ts           — Module context factory
+    loader.ts            — Module discovery and loading
+    validation.ts        — Frontmatter schema validation
+    pm/                  — Project management module
+      commands/          — 15 command groups (incl. check)
+      data/              — CRUD operations and queries
+      engine/            — Dependency waves, dispatch, state machine, claims, consistency
+  services/
+    brain-db.ts          — Database facade
+    brain-service.ts     — Resource lifecycle (withBrain/withDb)
+    repos/               — Domain repositories (note, memory, capture)
+    config.ts            — Configuration loading
+    search.ts            — Hybrid search orchestration
+    memory-extractor.ts  — LLM fact extraction and reconciliation
+    indexing.ts          — Index pipeline
+    reranker.ts          — Cross-encoder reranking
+  adapters/              — Embedder backends (local/ollama/remote)
+```
+
+**Storage:** SQLite via better-sqlite3 with FTS5 full-text search and sqlite-vec for vector search.
+
 ## How It Works
 
 Brain indexes markdown files with YAML frontmatter into a SQLite database. It combines three layers:
 
 **Search** — Hybrid BM25 full-text search (FTS5) + vector similarity (sqlite-vec) with reciprocal rank fusion. Optional cross-encoder reranking via `--rerank`.
 
-**Memory extraction** — Ollama LLM extracts discrete facts from notes, then reconciles them against existing memories (ADD/UPDATE/DELETE). Memories are versioned with parent chains, temporal validity (`valid_at`/`invalid_at`), and automatic forgetting (`forget_after`).
+**Memory extraction** — Ollama LLM extracts discrete facts from notes, reconciled against existing memories (ADD/UPDATE/DELETE). Memories are versioned with parent chains, temporal validity (`valid_at`/`invalid_at`), and automatic forgetting (`forget_after`).
 
 **Capture pipeline** — Zero-friction ingestion from CLI quick capture, file import, and RSS feed subscriptions. Items flow through an inbox queue before being indexed.
 
@@ -67,46 +146,23 @@ Brain indexes markdown files with YAML frontmatter into a SQLite database. It co
 - `slow` — permanent knowledge (decisions, patterns, research) with review intervals
 - `fast` — ephemeral (meetings, session logs) with expiry dates
 
-## Architecture
+## Testing
 
-```
-src/
-  cli.ts                — Entry point, Commander program
-  types.ts              — All TypeScript interfaces
-  utils.ts              — Shared utilities
-  commands/             — CLI commands (22 commands)
-  services/
-    brain-db.ts         — Database facade (delegates to repos)
-    brain-service.ts    — Resource management (withBrain/withDb)
-    repos/
-      note-repo.ts      — Notes, files, chunks, relations, FTS, search queries
-      memory-repo.ts    — Memory entries, history, vectors
-      capture-repo.ts   — Inbox items, feed records
-    config.ts           — Configuration loading
-    file-scanner.ts     — File change detection
-    markdown-parser.ts  — Frontmatter + heading-aware chunking
-    search.ts           — Hybrid search orchestration
-    graph.ts            — Note relation traversal
-    indexing.ts         — Index pipeline
-    memory-extractor.ts — LLM fact extraction and reconciliation
-    ollama.ts           — Ollama client and health checks
-    health.ts           — System health check service
-    reranker.ts         — Cross-encoder reranking
-  adapters/             — Embedder backends (local/ollama/remote)
+```bash
+npm test          # 1,095 tests (Vitest)
+npm run typecheck # TypeScript checking
+npm run lint      # ESLint
+npm run build     # Production build (tsup)
+npx tsx src/cli.ts # Run CLI in development
 ```
 
-**Storage:** SQLite via better-sqlite3 with FTS5 and sqlite-vec
+## Documentation
 
-## Development
-
-```bash
-npm install
-npm test              # Vitest (380 tests)
-npm run build         # tsup → dist/cli.js
-npm run typecheck     # tsc --noEmit
-npm run lint          # ESLint
-npx tsx src/cli.ts    # Run CLI in dev
-```
+- [PM Quick Start](docs/pm-module/quickstart.md)
+- [PM User Guide](docs/pm-module/guide.md)
+- [PM Architecture](docs/pm-module/architecture.md)
+- [PM Command Reference](docs/pm-module/commands.md)
+- [Demo Workflow](docs/pm-module/demo.md)
 
 ## License
 

package/dist/adapters-ZNJ4FL2E.js

@@ -0,0 +1,14 @@
+import {
+  LocalEmbedder,
+  OllamaEmbedder,
+  RemoteEmbedder,
+  createEmbedder,
+  getEmbedderInfo
+} from "./chunk-BDNH2E2O.js";
+export {
+  LocalEmbedder,
+  OllamaEmbedder,
+  RemoteEmbedder,
+  createEmbedder,
+  getEmbedderInfo
+};

package/dist/brain-service-2QO6JM3Z.js

@@ -0,0 +1,11 @@
+import {
+  withBrain,
+  withDb
+} from "./chunk-QL2GPXP6.js";
+import "./chunk-BDNH2E2O.js";
+import "./chunk-4SD4JRLS.js";
+import "./chunk-PO3GJPIC.js";
+export {
+  withBrain,
+  withDb
+};