@titan-design/brain 0.2.2 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +113 -0
- package/dist/cli.js +4324 -1484
- package/dist/web-extract-K4LTMRW2.js +111 -0
- package/package.json +21 -11
- package/skill/SKILL.md +17 -3
package/README.md
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# Brain
|
|
2
|
+
|
|
3
|
+
Personal knowledge base and memory engine with hybrid RAG search (BM25 + vector embeddings), LLM-powered memory extraction, and temporal intelligence.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @titan-design/brain
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Requires Node >= 22.
|
|
12
|
+
|
|
13
|
+
## Quick Start
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
brain init # Initialize workspace
|
|
17
|
+
brain index # Index notes
|
|
18
|
+
brain search "query" # Hybrid search
|
|
19
|
+
brain quick "thought" # Capture to inbox
|
|
20
|
+
brain extract --all # Extract memories (requires Ollama)
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Commands
|
|
24
|
+
|
|
25
|
+
| Command | Description |
|
|
26
|
+
|---------|-------------|
|
|
27
|
+
| `brain init` | Initialize workspace and database |
|
|
28
|
+
| `brain index` | Index all markdown notes |
|
|
29
|
+
| `brain search "query"` | Hybrid BM25 + vector search |
|
|
30
|
+
| `brain add <file>` | Add a note from file or stdin |
|
|
31
|
+
| `brain quick "text"` | Zero-friction capture to inbox |
|
|
32
|
+
| `brain inbox` | View/manage inbox items |
|
|
33
|
+
| `brain ingest` | Bulk-import files to inbox |
|
|
34
|
+
| `brain feed` | Manage RSS feed subscriptions |
|
|
35
|
+
| `brain extract` | Extract memories from notes (Ollama) |
|
|
36
|
+
| `brain memories` | List, history, and stats for memories |
|
|
37
|
+
| `brain context <id>` | Show context for a note (relations + memories) |
|
|
38
|
+
| `brain profile` | Generate agent context profile |
|
|
39
|
+
| `brain tidy` | LLM-powered note cleanup suggestions |
|
|
40
|
+
| `brain doctor` | System health checks (`--fix` for auto-repair) |
|
|
41
|
+
| `brain install-hooks` | Set up launchd/systemd scheduled processing |
|
|
42
|
+
| `brain status` | Database stats |
|
|
43
|
+
| `brain stale` | Notes needing review |
|
|
44
|
+
| `brain graph <id>` | Show note relations |
|
|
45
|
+
| `brain template <type>` | Output frontmatter template |
|
|
46
|
+
| `brain archive` | Archive expired notes |
|
|
47
|
+
| `brain config` | View/set configuration |
|
|
48
|
+
|
|
49
|
+
## How It Works
|
|
50
|
+
|
|
51
|
+
Brain indexes markdown files with YAML frontmatter into a SQLite database. It combines three layers:
|
|
52
|
+
|
|
53
|
+
**Search** — Hybrid BM25 full-text search (FTS5) + vector similarity (sqlite-vec) with reciprocal rank fusion. Optional cross-encoder reranking via `--rerank`.
|
|
54
|
+
|
|
55
|
+
**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`).
|
|
56
|
+
|
|
57
|
+
**Capture pipeline** — Zero-friction ingestion from CLI quick capture, file import, and RSS feed subscriptions. Items flow through an inbox queue before being indexed.
|
|
58
|
+
|
|
59
|
+
### Embedding Backends
|
|
60
|
+
|
|
61
|
+
- **Local** — `@huggingface/transformers` (default, no external dependencies)
|
|
62
|
+
- **Ollama** — local Ollama server
|
|
63
|
+
- **Remote** — configurable API endpoint
|
|
64
|
+
|
|
65
|
+
### Note Tiers
|
|
66
|
+
|
|
67
|
+
- `slow` — permanent knowledge (decisions, patterns, research) with review intervals
|
|
68
|
+
- `fast` — ephemeral (meetings, session logs) with expiry dates
|
|
69
|
+
|
|
70
|
+
## Architecture
|
|
71
|
+
|
|
72
|
+
```
|
|
73
|
+
src/
|
|
74
|
+
cli.ts — Entry point, Commander program
|
|
75
|
+
types.ts — All TypeScript interfaces
|
|
76
|
+
utils.ts — Shared utilities
|
|
77
|
+
commands/ — CLI commands (22 commands)
|
|
78
|
+
services/
|
|
79
|
+
brain-db.ts — Database facade (delegates to repos)
|
|
80
|
+
brain-service.ts — Resource management (withBrain/withDb)
|
|
81
|
+
repos/
|
|
82
|
+
note-repo.ts — Notes, files, chunks, relations, FTS, search queries
|
|
83
|
+
memory-repo.ts — Memory entries, history, vectors
|
|
84
|
+
capture-repo.ts — Inbox items, feed records
|
|
85
|
+
config.ts — Configuration loading
|
|
86
|
+
file-scanner.ts — File change detection
|
|
87
|
+
markdown-parser.ts — Frontmatter + heading-aware chunking
|
|
88
|
+
search.ts — Hybrid search orchestration
|
|
89
|
+
graph.ts — Note relation traversal
|
|
90
|
+
indexing.ts — Index pipeline
|
|
91
|
+
memory-extractor.ts — LLM fact extraction and reconciliation
|
|
92
|
+
ollama.ts — Ollama client and health checks
|
|
93
|
+
health.ts — System health check service
|
|
94
|
+
reranker.ts — Cross-encoder reranking
|
|
95
|
+
adapters/ — Embedder backends (local/ollama/remote)
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
**Storage:** SQLite via better-sqlite3 with FTS5 and sqlite-vec
|
|
99
|
+
|
|
100
|
+
## Development
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
npm install
|
|
104
|
+
npm test # Vitest (380 tests)
|
|
105
|
+
npm run build # tsup → dist/cli.js
|
|
106
|
+
npm run typecheck # tsc --noEmit
|
|
107
|
+
npm run lint # ESLint
|
|
108
|
+
npx tsx src/cli.ts # Run CLI in dev
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## License
|
|
112
|
+
|
|
113
|
+
MIT
|