trova-cli 0.0.0-stage → 0.1.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Bimal
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,113 @@
1
- # Temporary Holding Version
1
+ # trova-cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Local keyword and semantic search for folders of Markdown notes. `trova` indexes a folder on your machine and searches it by keyword, by meaning, or both. It runs as a command-line tool, an HTTP API and an MCP server for AI agents. It is built on [qmd](https://github.com/tobi/qmd). Your notes never leave the machine: the only network traffic is the model download from Hugging Face, and after that `trova` works offline.
4
+
5
+ The same engine powers the Trova plugin for Obsidian, which lives in the [same repository](https://github.com/ibimal/trova).
6
+
7
+ ## Requirements
8
+
9
+ - Node 22 or later; Node 24 is the verified version. On Node 22.12.0 the prebuilt `better-sqlite3` binary crashes, so `trova` stops with a message there.
10
+ - Checked on macOS on Apple Silicon. Other platforms are not tested yet.
11
+
12
+ ## Install
13
+
14
+ ```bash
15
+ npm install -g trova-cli
16
+ ```
17
+
18
+ The installed package takes about 300 MB, mostly llama.cpp binaries; the models come on top (see below).
19
+
20
+ npm 11 does not run the install scripts of dependencies unless you allow them, and it lists the ones it skipped: `node-llama-cpp` and some `tree-sitter` packages. On macOS with Apple Silicon `trova` works without them, because the prebuilt binaries are used. On other platforms `node-llama-cpp` may need its script; this is not tested.
21
+
22
+ Then check the setup:
23
+
24
+ ```bash
25
+ trova doctor
26
+ ```
27
+
28
+ ## Quick start
29
+
30
+ Add a folder as a collection. `trova` indexes and embeds it; the first run downloads qmd's embedding model, about 330 MB.
31
+
32
+ ```bash
33
+ trova collection add ~/Notes
34
+ ```
35
+
36
+ Search it:
37
+
38
+ ```bash
39
+ trova search "chunk size"
40
+ ```
41
+
42
+ ```bash
43
+ trova query "how did we choose the chunk size?"
44
+ ```
45
+
46
+ `search` is the keyword lane. When a query finds fewer than 3 notes, it corrects misspelt words of 5 letters or more: one edit, or two for words of 9 letters or more. `vsearch` is the vector lane. `query` (alias `ask`) fuses both. `query --mode deep` also expands the query and reranks the results with two larger models, about 1.7 GB together. The command line cannot download them yet; until they are on disk, Deep queries run in Fast mode and say so.
47
+
48
+ `trova related <path>` lists the notes closest to one note, and `trova related <path>#<heading>` the blocks closest to one section.
49
+
50
+ ## Commands
51
+
52
+ | Command | What it does |
53
+ | --- | --- |
54
+ | `collection add <path> [--name <name>]` | Add a folder as a collection and index it |
55
+ | `collection ls`, `collection rm <name>`, `collection rename <old> <new>` | List, remove or rename collections |
56
+ | `context add <collection> <path> <text>`, `context ls`, `context rm <collection> <path>` | Describe a folder to improve ranking |
57
+ | `update [-c <collection>]` | Rescan collections for changes |
58
+ | `embed` | Embed new and changed blocks |
59
+ | `search`, `vsearch`, `query <query> [--mode fast\|deep]` | Keyword, vector and hybrid search |
60
+ | `related <path>[#heading-path]` | Related sources and blocks |
61
+ | `get <id\|path>`, `multi-get <glob \| id,id,...>` | Print one source, or several |
62
+ | `status`, `doctor` | Health, counts and model identity |
63
+ | `watch [--port <n>]` | Run the daemon: watcher, indexer and HTTP API |
64
+ | `serve [--port <n>]` | HTTP API only, no watcher |
65
+ | `mcp [--http] [--port <n>]` | MCP server over stdio, or over HTTP on 127.0.0.1 |
66
+ | `eval` | nDCG@10 and Recall@20 on a fixture vault or your own queries |
67
+
68
+ Every command takes `--json`, `-n`/`--limit <n>` and `-c`/`--collection <name>`. `trova help` prints the full list.
69
+
70
+ ## The daemon
71
+
72
+ `trova watch` runs one daemon per machine. It keeps the models loaded, watches the collections for changes and serves the HTTP API on 127.0.0.1 only. Every request needs the token it writes to `daemon.json` in its data folder, which only your user account can read. Other commands use a running daemon when there is one and otherwise run in-process. The daemon stops by itself after 30 minutes with no client and no job.
73
+
74
+ ## Use it from an AI agent (MCP)
75
+
76
+ `trova mcp` serves the index over stdio with the tools `search`, `ask`, `related`, `get`, `multi_get`, `status` and `metadata`. For a client that reads an `mcpServers` configuration:
77
+
78
+ ```json
79
+ {
80
+ "mcpServers": {
81
+ "trova": { "command": "trova", "args": ["mcp"] }
82
+ }
83
+ }
84
+ ```
85
+
86
+ `trova mcp --http` serves the same tools at `http://127.0.0.1:8181/mcp`. That server has no token: it refuses any request whose `Host` or `Origin` is not a loopback address, so web pages cannot reach it, but any program on this machine can. Start it only while you use it.
87
+
88
+ ## Models
89
+
90
+ qmd downloads its default models from Hugging Face into `~/.cache/qmd/models/` the first time they are needed. Each model has its own licence, and by downloading it you accept that licence:
91
+
92
+ | Model | Used for | Size | Licence |
93
+ | --- | --- | --- | --- |
94
+ | [EmbeddingGemma 300M](https://huggingface.co/google/embeddinggemma-300m) (GGUF build by [ggml-org](https://huggingface.co/ggml-org/embeddinggemma-300M-GGUF)) | Embeddings: vector search and related notes | about 330 MB | [Gemma Terms of Use](https://ai.google.dev/gemma/terms) and the [Gemma Prohibited Use Policy](https://ai.google.dev/gemma/prohibited_use_policy) |
95
+ | [Qwen3-Reranker 0.6B](https://huggingface.co/Qwen/Qwen3-Reranker-0.6B) | Deep mode: reranking | about 1.7 GB together with the next model | Apache-2.0 |
96
+ | [qmd-query-expansion 1.7B](https://huggingface.co/tobil/qmd-query-expansion-1.7B-gguf) | Deep mode: query expansion | | MIT |
97
+
98
+ `trova` does not include or redistribute any model.
99
+
100
+ ## Where data lives
101
+
102
+ | Data | Location |
103
+ | --- | --- |
104
+ | Index, sidecar tables, logs, attachment text | `~/.cache/trova/`, or the folder in `TROVA_HOME` |
105
+ | Models | qmd's model cache, `~/.cache/qmd/models/` |
106
+
107
+ ## Acknowledgements
108
+
109
+ `trova` is built on [qmd](https://github.com/tobi/qmd) by Tobi Lütke, which does the indexing, the keyword and vector search, and the model handling. qmd is MIT-licensed and installs as a dependency. `trova` adds the block-level index, related notes, typo rescue, the daemon, the HTTP API and the MCP server on top of it.
110
+
111
+ ## Licence
112
+
113
+ `trova` is MIT-licensed; see `LICENSE`. The models have their own licences; see "Models" above.
package/bin/trova ADDED
@@ -0,0 +1,5 @@
1
+ #!/usr/bin/env node
2
+ import("../dist/cli.js").then((m) => m.main(process.argv.slice(2))).catch((err) => {
3
+ console.error(err?.message ?? err);
4
+ process.exit(1);
5
+ });