@gmickel/gno 0.3.4 → 0.3.5
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 +134 -56
- package/assets/badges/license.svg +12 -0
- package/assets/badges/npm.svg +13 -0
- package/assets/badges/twitter.svg +22 -0
- package/assets/badges/website.svg +22 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,10 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
**Your Local Second Brain** — Index, search, and synthesize your entire digital life.
|
|
4
4
|
|
|
5
|
-
[](https://www.npmjs.com/package/@gmickel/gno)
|
|
6
|
+
[](./LICENSE)
|
|
7
|
+
[](https://gno.sh)
|
|
8
|
+
[](https://twitter.com/gmickel)
|
|
7
9
|
|
|
8
|
-
GNO is a local knowledge engine for privacy-conscious
|
|
10
|
+
GNO is a local knowledge engine for privacy-conscious developers and AI agents. Index your notes, code, PDFs, and Office docs. Get hybrid search (BM25 + vector + reranking) and AI-powered answers—all running 100% on your machine.
|
|
9
11
|
|
|
10
12
|
---
|
|
11
13
|
|
|
@@ -16,6 +18,7 @@ GNO is a local knowledge engine for privacy-conscious individuals and AI agents.
|
|
|
16
18
|
- [Search Modes](#search-modes)
|
|
17
19
|
- [Agent Integration](#agent-integration)
|
|
18
20
|
- [How It Works](#how-it-works)
|
|
21
|
+
- [Features](#features)
|
|
19
22
|
- [Local Models](#local-models)
|
|
20
23
|
- [Architecture](#architecture)
|
|
21
24
|
- [Development](#development)
|
|
@@ -25,21 +28,18 @@ GNO is a local knowledge engine for privacy-conscious individuals and AI agents.
|
|
|
25
28
|
## Quick Start
|
|
26
29
|
|
|
27
30
|
```bash
|
|
28
|
-
#
|
|
29
|
-
gno
|
|
30
|
-
|
|
31
|
-
#
|
|
32
|
-
gno index
|
|
33
|
-
|
|
34
|
-
# Search
|
|
35
|
-
gno query "authentication best practices"
|
|
36
|
-
gno ask "summarize the API discussion" --answer
|
|
31
|
+
gno init ~/notes --name notes # Point at your docs
|
|
32
|
+
gno index # Build search index
|
|
33
|
+
gno query "auth best practices" # Hybrid search
|
|
34
|
+
gno ask "summarize the API" --answer # AI answer with citations
|
|
37
35
|
```
|
|
38
36
|
|
|
39
37
|
---
|
|
40
38
|
|
|
41
39
|
## Installation
|
|
42
40
|
|
|
41
|
+
### Install GNO
|
|
42
|
+
|
|
43
43
|
Requires [Bun](https://bun.sh/) >= 1.0.0.
|
|
44
44
|
|
|
45
45
|
```bash
|
|
@@ -47,59 +47,101 @@ bun install -g @gmickel/gno
|
|
|
47
47
|
```
|
|
48
48
|
|
|
49
49
|
**macOS**: Vector search requires Homebrew SQLite:
|
|
50
|
+
|
|
50
51
|
```bash
|
|
51
52
|
brew install sqlite3
|
|
52
53
|
```
|
|
53
54
|
|
|
54
|
-
Verify:
|
|
55
|
+
Verify everything works:
|
|
56
|
+
|
|
55
57
|
```bash
|
|
56
58
|
gno doctor
|
|
57
59
|
```
|
|
58
60
|
|
|
61
|
+
### Connect to AI Agents
|
|
62
|
+
|
|
63
|
+
#### MCP Server (Claude Desktop, Cursor, Zed, etc.)
|
|
64
|
+
|
|
65
|
+
One command to add GNO to your AI assistant:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
gno mcp install # Claude Desktop (default)
|
|
69
|
+
gno mcp install --target cursor # Cursor
|
|
70
|
+
gno mcp install --target claude-code # Claude Code CLI
|
|
71
|
+
gno mcp install --target zed # Zed
|
|
72
|
+
gno mcp install --target windsurf # Windsurf
|
|
73
|
+
gno mcp install --target codex # OpenAI Codex CLI
|
|
74
|
+
gno mcp install --target opencode # OpenCode
|
|
75
|
+
gno mcp install --target amp # Amp
|
|
76
|
+
gno mcp install --target lmstudio # LM Studio
|
|
77
|
+
gno mcp install --target librechat # LibreChat
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Check status: `gno mcp status`
|
|
81
|
+
|
|
82
|
+
#### Skills (Claude Code, Codex, OpenCode)
|
|
83
|
+
|
|
84
|
+
Skills integrate via CLI—no MCP overhead:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
gno skill install --scope user # User-wide
|
|
88
|
+
gno skill install --target codex # Codex
|
|
89
|
+
gno skill install --target all # Both Claude + Codex
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
> **Full setup guide**: [MCP Integration](https://gno.sh/docs/MCP/) · [CLI Reference](https://gno.sh/docs/CLI/)
|
|
93
|
+
|
|
59
94
|
---
|
|
60
95
|
|
|
61
96
|
## Search Modes
|
|
62
97
|
|
|
63
98
|
| Command | Mode | Best For |
|
|
64
99
|
|:--------|:-----|:---------|
|
|
65
|
-
| `gno search` | BM25 | Exact phrases,
|
|
100
|
+
| `gno search` | BM25 | Exact phrases, code identifiers |
|
|
66
101
|
| `gno vsearch` | Vector | Natural language, concepts |
|
|
67
|
-
| `gno query` | Hybrid |
|
|
68
|
-
| `gno ask` | RAG | Direct answers with citations |
|
|
102
|
+
| `gno query` | Hybrid | Best accuracy (BM25 + vector + reranking) |
|
|
103
|
+
| `gno ask --answer` | RAG | Direct answers with citations |
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
gno search "handleAuth" # Find exact matches
|
|
107
|
+
gno vsearch "error handling patterns" # Semantic similarity
|
|
108
|
+
gno query "database optimization" # Full pipeline
|
|
109
|
+
gno ask "what did we decide" --answer # AI synthesis
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Output formats: `--json`, `--files`, `--csv`, `--md`, `--xml`
|
|
69
113
|
|
|
70
114
|
---
|
|
71
115
|
|
|
72
116
|
## Agent Integration
|
|
73
117
|
|
|
74
|
-
###
|
|
75
|
-
|
|
76
|
-
```bash
|
|
77
|
-
gno skill install --scope user # Claude Code
|
|
78
|
-
gno skill install --target codex # Codex
|
|
79
|
-
gno skill install --target all # Both
|
|
80
|
-
```
|
|
118
|
+
### MCP Server
|
|
81
119
|
|
|
82
|
-
|
|
120
|
+
GNO exposes 6 tools via [Model Context Protocol](https://modelcontextprotocol.io):
|
|
83
121
|
|
|
84
|
-
|
|
122
|
+
| Tool | Description |
|
|
123
|
+
|:-----|:------------|
|
|
124
|
+
| `gno_search` | BM25 keyword search |
|
|
125
|
+
| `gno_vsearch` | Vector semantic search |
|
|
126
|
+
| `gno_query` | Hybrid search (recommended) |
|
|
127
|
+
| `gno_get` | Retrieve document by ID |
|
|
128
|
+
| `gno_multi_get` | Batch document retrieval |
|
|
129
|
+
| `gno_status` | Index health check |
|
|
85
130
|
|
|
86
|
-
|
|
87
|
-
{
|
|
88
|
-
"mcpServers": {
|
|
89
|
-
"gno": { "command": "gno", "args": ["mcp"] }
|
|
90
|
-
}
|
|
91
|
-
}
|
|
92
|
-
```
|
|
131
|
+
**Design**: MCP tools are retrieval-only. Your AI assistant (Claude, GPT-4) synthesizes answers from retrieved context—best retrieval (GNO) + best reasoning (your LLM).
|
|
93
132
|
|
|
94
|
-
|
|
133
|
+
### Skills
|
|
95
134
|
|
|
96
|
-
|
|
135
|
+
Skills add GNO search to Claude Code/Codex without MCP protocol overhead:
|
|
97
136
|
|
|
98
137
|
```bash
|
|
99
|
-
gno
|
|
100
|
-
gno search "API design" --files # File paths only
|
|
138
|
+
gno skill install --scope user
|
|
101
139
|
```
|
|
102
140
|
|
|
141
|
+
Then ask your agent: *"Search my notes for the auth discussion"*
|
|
142
|
+
|
|
143
|
+
> **Detailed docs**: [MCP Integration](https://gno.sh/docs/MCP/) · [Use Cases](https://gno.sh/docs/USE-CASES/)
|
|
144
|
+
|
|
103
145
|
---
|
|
104
146
|
|
|
105
147
|
## How It Works
|
|
@@ -110,30 +152,44 @@ graph TD
|
|
|
110
152
|
B --> C{Lexical Variants}
|
|
111
153
|
B --> D{Semantic Variants}
|
|
112
154
|
B --> E{HyDE Passage}
|
|
113
|
-
A --> F[Original Query]
|
|
114
155
|
|
|
115
156
|
C --> G(BM25 Search)
|
|
116
157
|
D --> H(Vector Search)
|
|
117
158
|
E --> H
|
|
118
|
-
|
|
119
|
-
|
|
159
|
+
A --> G
|
|
160
|
+
A --> H
|
|
120
161
|
|
|
121
|
-
G --> I(Ranked
|
|
122
|
-
H --> J(Ranked
|
|
162
|
+
G --> I(Ranked Results)
|
|
163
|
+
H --> J(Ranked Results)
|
|
123
164
|
I --> K{RRF Fusion}
|
|
124
165
|
J --> K
|
|
125
166
|
|
|
126
|
-
K --> L(Top Candidates)
|
|
167
|
+
K --> L(Top 20 Candidates)
|
|
127
168
|
L --> M(Cross-Encoder Rerank)
|
|
128
169
|
M --> N[Final Results]
|
|
129
170
|
```
|
|
130
171
|
|
|
131
|
-
1. **Query Expansion** — LLM generates lexical variants, semantic
|
|
132
|
-
2. **Parallel Retrieval** — BM25 +
|
|
172
|
+
1. **Query Expansion** — LLM generates lexical variants, semantic rephrases, and a [HyDE](https://arxiv.org/abs/2212.10496) passage
|
|
173
|
+
2. **Parallel Retrieval** — BM25 + vector search run concurrently on all variants
|
|
133
174
|
3. **Fusion** — Reciprocal Rank Fusion merges results with position-based scoring
|
|
134
|
-
4. **
|
|
175
|
+
4. **Reranking** — Cross-encoder rescores top 20, blended with fusion scores
|
|
176
|
+
|
|
177
|
+
> **Deep dive**: [How Search Works](https://gno.sh/docs/HOW-SEARCH-WORKS/)
|
|
178
|
+
|
|
179
|
+
---
|
|
180
|
+
|
|
181
|
+
## Features
|
|
135
182
|
|
|
136
|
-
|
|
183
|
+
| Feature | Description |
|
|
184
|
+
|:--------|:------------|
|
|
185
|
+
| **Hybrid Search** | BM25 + vector + RRF fusion + cross-encoder reranking |
|
|
186
|
+
| **Multi-Format** | Markdown, PDF, DOCX, XLSX, PPTX, plain text |
|
|
187
|
+
| **Local LLM** | AI answers via llama.cpp—no API keys |
|
|
188
|
+
| **Privacy First** | 100% offline, zero telemetry, your data stays yours |
|
|
189
|
+
| **MCP Server** | Works with Claude Desktop, Cursor, Zed, + 8 more |
|
|
190
|
+
| **Collections** | Organize sources with patterns, excludes, contexts |
|
|
191
|
+
| **Multilingual** | 30+ languages, auto-detection, cross-lingual search |
|
|
192
|
+
| **Incremental** | SHA-256 tracking—only changed files re-indexed |
|
|
137
193
|
|
|
138
194
|
---
|
|
139
195
|
|
|
@@ -143,9 +199,24 @@ Models auto-download on first use to `~/.cache/gno/models/`.
|
|
|
143
199
|
|
|
144
200
|
| Model | Purpose | Size |
|
|
145
201
|
|:------|:--------|:-----|
|
|
146
|
-
| bge-m3 | Embeddings | ~500MB |
|
|
147
|
-
| bge-reranker-v2-m3 |
|
|
148
|
-
| Qwen
|
|
202
|
+
| bge-m3 | Embeddings (1024-dim, multilingual) | ~500MB |
|
|
203
|
+
| bge-reranker-v2-m3 | Cross-encoder reranking | ~700MB |
|
|
204
|
+
| Qwen/SmolLM | Query expansion + AI answers | ~600MB-1.2GB |
|
|
205
|
+
|
|
206
|
+
### Model Presets
|
|
207
|
+
|
|
208
|
+
| Preset | Disk | Best For |
|
|
209
|
+
|:-------|:-----|:---------|
|
|
210
|
+
| `slim` | ~1GB | Fast, lower quality |
|
|
211
|
+
| `balanced` | ~2GB | Good balance (default) |
|
|
212
|
+
| `quality` | ~2.5GB | Best answers |
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
gno models use balanced
|
|
216
|
+
gno models pull --all
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
> **Configuration**: [Model Setup](https://gno.sh/docs/CONFIGURATION/)
|
|
149
220
|
|
|
150
221
|
---
|
|
151
222
|
|
|
@@ -153,16 +224,18 @@ Models auto-download on first use to `~/.cache/gno/models/`.
|
|
|
153
224
|
|
|
154
225
|
```
|
|
155
226
|
┌─────────────────────────────────────────────────┐
|
|
156
|
-
│
|
|
227
|
+
│ GNO CLI / MCP │
|
|
157
228
|
├─────────────────────────────────────────────────┤
|
|
158
|
-
│ Ports: Converter, Store, Embedding, Rerank
|
|
229
|
+
│ Ports: Converter, Store, Embedding, Rerank │
|
|
159
230
|
├─────────────────────────────────────────────────┤
|
|
160
|
-
│ Adapters: SQLite, FTS5, sqlite-vec, llama-cpp
|
|
231
|
+
│ Adapters: SQLite, FTS5, sqlite-vec, llama-cpp │
|
|
161
232
|
├─────────────────────────────────────────────────┤
|
|
162
|
-
│ Core: Identity, Mirrors, Chunking, Retrieval
|
|
233
|
+
│ Core: Identity, Mirrors, Chunking, Retrieval │
|
|
163
234
|
└─────────────────────────────────────────────────┘
|
|
164
235
|
```
|
|
165
236
|
|
|
237
|
+
> **Details**: [Architecture](https://gno.sh/docs/ARCHITECTURE/)
|
|
238
|
+
|
|
166
239
|
---
|
|
167
240
|
|
|
168
241
|
## Development
|
|
@@ -171,14 +244,19 @@ Models auto-download on first use to `~/.cache/gno/models/`.
|
|
|
171
244
|
git clone https://github.com/gmickel/gno.git && cd gno
|
|
172
245
|
bun install
|
|
173
246
|
bun test
|
|
174
|
-
bun run lint
|
|
175
|
-
bun run typecheck
|
|
247
|
+
bun run lint && bun run typecheck
|
|
176
248
|
```
|
|
177
249
|
|
|
178
|
-
|
|
250
|
+
> **Contributing**: [CONTRIBUTING.md](.github/CONTRIBUTING.md)
|
|
179
251
|
|
|
180
252
|
---
|
|
181
253
|
|
|
182
254
|
## License
|
|
183
255
|
|
|
184
256
|
[MIT](./LICENSE)
|
|
257
|
+
|
|
258
|
+
---
|
|
259
|
+
|
|
260
|
+
<p align="center">
|
|
261
|
+
made with ❤️ by <a href="https://twitter.com/gmickel">@gmickel</a>
|
|
262
|
+
</p>
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="85" height="28" viewBox="0 0 85 28">
|
|
2
|
+
<defs>
|
|
3
|
+
<linearGradient id="bg-lic" x1="0%" y1="0%" x2="100%" y2="100%">
|
|
4
|
+
<stop offset="0%" style="stop-color:#1a1a2e"/>
|
|
5
|
+
<stop offset="100%" style="stop-color:#0f0f1a"/>
|
|
6
|
+
</linearGradient>
|
|
7
|
+
</defs>
|
|
8
|
+
<rect width="85" height="28" rx="6" fill="url(#bg-lic)"/>
|
|
9
|
+
<rect x="1" y="1" width="83" height="26" rx="5" fill="none" stroke="#2dd4bf" stroke-opacity="0.3"/>
|
|
10
|
+
<text x="10" y="18" font-family="ui-monospace,SFMono-Regular,Menlo,Monaco,monospace" font-size="11" fill="#94a3b8">MIT</text>
|
|
11
|
+
<text x="34" y="18" font-family="ui-monospace,SFMono-Regular,Menlo,Monaco,monospace" font-size="11" fill="#2dd4bf">License</text>
|
|
12
|
+
</svg>
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="66" height="28" viewBox="0 0 66 28">
|
|
2
|
+
<defs>
|
|
3
|
+
<linearGradient id="bg-npm" x1="0%" y1="0%" x2="100%" y2="100%">
|
|
4
|
+
<stop offset="0%" style="stop-color:#1a1a2e"/>
|
|
5
|
+
<stop offset="100%" style="stop-color:#0f0f1a"/>
|
|
6
|
+
</linearGradient>
|
|
7
|
+
</defs>
|
|
8
|
+
<rect width="66" height="28" rx="6" fill="url(#bg-npm)"/>
|
|
9
|
+
<rect x="1" y="1" width="64" height="26" rx="5" fill="none" stroke="#cb3837" stroke-opacity="0.4"/>
|
|
10
|
+
<rect x="8" y="7" width="32" height="14" rx="3" fill="#cb3837"/>
|
|
11
|
+
<text x="13" y="18" font-family="ui-monospace,SFMono-Regular,Menlo,Monaco,monospace" font-size="10" font-weight="700" fill="#fff">npm</text>
|
|
12
|
+
<text x="46" y="18" font-family="ui-monospace,SFMono-Regular,Menlo,Monaco,monospace" font-size="12" fill="#e2e8f0">↗</text>
|
|
13
|
+
</svg>
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="130" height="28" viewBox="0 0 130 28">
|
|
2
|
+
<defs>
|
|
3
|
+
<linearGradient id="bg2" x1="0%" y1="0%" x2="100%" y2="100%">
|
|
4
|
+
<stop offset="0%" style="stop-color:#1a1a2e"/>
|
|
5
|
+
<stop offset="100%" style="stop-color:#0f0f1a"/>
|
|
6
|
+
</linearGradient>
|
|
7
|
+
<filter id="glow2">
|
|
8
|
+
<feGaussianBlur stdDeviation="0.5" result="coloredBlur"/>
|
|
9
|
+
<feMerge>
|
|
10
|
+
<feMergeNode in="coloredBlur"/>
|
|
11
|
+
<feMergeNode in="SourceGraphic"/>
|
|
12
|
+
</feMerge>
|
|
13
|
+
</filter>
|
|
14
|
+
</defs>
|
|
15
|
+
<rect width="130" height="28" rx="6" fill="url(#bg2)"/>
|
|
16
|
+
<rect x="1" y="1" width="128" height="26" rx="5" fill="none" stroke="#2dd4bf" stroke-opacity="0.3"/>
|
|
17
|
+
<!-- X logo -->
|
|
18
|
+
<g transform="translate(10, 7)" fill="#e2e8f0">
|
|
19
|
+
<path d="M10.5 1.5L6.75 6.5L10.75 12.5H8.5L5.75 8.5L2.5 12.5H0.25L4.25 7L0.5 1.5H2.75L5.25 5.25L8.25 1.5H10.5Z" transform="scale(1.1)"/>
|
|
20
|
+
</g>
|
|
21
|
+
<text x="32" y="18" font-family="ui-monospace,SFMono-Regular,Menlo,Monaco,monospace" font-size="12" font-weight="500" fill="#e2e8f0" filter="url(#glow2)">@gmickel</text>
|
|
22
|
+
</svg>
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="120" height="28" viewBox="0 0 120 28">
|
|
2
|
+
<defs>
|
|
3
|
+
<linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
|
|
4
|
+
<stop offset="0%" style="stop-color:#1a1a2e"/>
|
|
5
|
+
<stop offset="100%" style="stop-color:#0f0f1a"/>
|
|
6
|
+
</linearGradient>
|
|
7
|
+
<filter id="glow">
|
|
8
|
+
<feGaussianBlur stdDeviation="1" result="coloredBlur"/>
|
|
9
|
+
<feMerge>
|
|
10
|
+
<feMergeNode in="coloredBlur"/>
|
|
11
|
+
<feMergeNode in="SourceGraphic"/>
|
|
12
|
+
</feMerge>
|
|
13
|
+
</filter>
|
|
14
|
+
</defs>
|
|
15
|
+
<rect width="120" height="28" rx="6" fill="url(#bg)"/>
|
|
16
|
+
<rect x="1" y="1" width="118" height="26" rx="5" fill="none" stroke="#2dd4bf" stroke-opacity="0.3"/>
|
|
17
|
+
<text x="10" y="18" font-family="ui-monospace,SFMono-Regular,Menlo,Monaco,monospace" font-size="11" fill="#2dd4bf" filter="url(#glow)">❯</text>
|
|
18
|
+
<text x="24" y="18" font-family="ui-monospace,SFMono-Regular,Menlo,Monaco,monospace" font-size="12" font-weight="600" fill="#e2e8f0">gno.sh</text>
|
|
19
|
+
<rect x="74" y="9" width="2" height="12" fill="#2dd4bf" opacity="0.8">
|
|
20
|
+
<animate attributeName="opacity" values="0.8;0.2;0.8" dur="1.2s" repeatCount="indefinite"/>
|
|
21
|
+
</rect>
|
|
22
|
+
</svg>
|