@delfos-ai/cli 1.0.9 → 1.0.11
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 +55 -0
- package/README.md +299 -39
- package/README.pt-BR.md +352 -0
- package/dist/commands/setup/steps/check-chromadb.js +1 -1
- package/package.json +2 -2
package/LICENSE
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
Delfos Proprietary License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Delfos (delfos.io). All rights reserved.
|
|
4
|
+
|
|
5
|
+
This software and associated documentation files (the "Software") are the
|
|
6
|
+
exclusive property of Delfos. The Software is not open source.
|
|
7
|
+
|
|
8
|
+
## Grant of Use
|
|
9
|
+
|
|
10
|
+
Subject to the Terms of Use published at https://ai.delfos.dev/terms (the "Terms"),
|
|
11
|
+
Delfos grants you a limited, non-exclusive, non-transferable, non-sublicensable,
|
|
12
|
+
revocable license to install and use the Software solely for its intended purpose
|
|
13
|
+
as described in the Terms.
|
|
14
|
+
|
|
15
|
+
## Restrictions
|
|
16
|
+
|
|
17
|
+
You may NOT, under any circumstances:
|
|
18
|
+
|
|
19
|
+
1. Copy, modify, adapt, or create derivative works of the Software.
|
|
20
|
+
2. Distribute, sublicense, sell, lease, or otherwise transfer the Software
|
|
21
|
+
to any third party.
|
|
22
|
+
3. Reverse engineer, decompile, disassemble, or otherwise attempt to derive
|
|
23
|
+
the source code of the Software, except to the extent expressly permitted
|
|
24
|
+
by applicable law.
|
|
25
|
+
4. Remove, alter, or obscure any copyright, trademark, or other proprietary
|
|
26
|
+
notices in the Software.
|
|
27
|
+
5. Use the Software to build or offer a competing product or service.
|
|
28
|
+
|
|
29
|
+
## Terms of Use
|
|
30
|
+
|
|
31
|
+
Your use of the Software is governed by the Delfos Terms of Use available at
|
|
32
|
+
https://ai.delfos.dev/terms. In the event of any conflict between this license
|
|
33
|
+
and the Terms, the Terms shall prevail.
|
|
34
|
+
|
|
35
|
+
## No Warranty
|
|
36
|
+
|
|
37
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
38
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
39
|
+
FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
|
|
40
|
+
|
|
41
|
+
## Limitation of Liability
|
|
42
|
+
|
|
43
|
+
IN NO EVENT SHALL DELFOS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY,
|
|
44
|
+
WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR
|
|
45
|
+
IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
46
|
+
|
|
47
|
+
## Termination
|
|
48
|
+
|
|
49
|
+
This license terminates automatically if you violate any of its terms or the
|
|
50
|
+
Terms of Use. Upon termination, you must immediately cease all use of the
|
|
51
|
+
Software and destroy all copies in your possession.
|
|
52
|
+
|
|
53
|
+
## Contact
|
|
54
|
+
|
|
55
|
+
For licensing inquiries: legal@delfos.io
|
package/README.md
CHANGED
|
@@ -1,57 +1,220 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
---
|
|
4
|
+
|
|
1
5
|
# Delfos CLI
|
|
2
6
|
|
|
3
|
-
|
|
7
|
+
<img src="docs/logo_delfos.png" alt="Delfos Logo" width="800" />
|
|
8
|
+
|
|
9
|
+
<span style="color: transparent">.</span>
|
|
10
|
+
|
|
11
|
+
**Your AI coding tools deserve a memory. Delfos gives them one.**
|
|
12
|
+
|
|
13
|
+
Give your AI assistants persistent, semantic memory powered by your Obsidian vault — across every IDE, every session.
|
|
14
|
+
|
|
15
|
+
[](https://www.npmjs.com/package/@delfos-ai/cli)
|
|
16
|
+
[](https://nodejs.org/)
|
|
17
|
+
[](./LICENSE)
|
|
18
|
+
<!--[](https://github.com/delfos-io/delfos-cli/actions/workflows/ci.yml)-->
|
|
19
|
+
|
|
20
|
+
[**Getting Started**](#-getting-started) ·
|
|
21
|
+
[**Features**](#-features) ·
|
|
22
|
+
[**Commands**](#-commands) ·
|
|
23
|
+
[**MCP Integration**](#-mcp-integration) ·
|
|
24
|
+
[**Docs**](https://docs.delfos.dev/cli)
|
|
25
|
+
|
|
26
|
+
*Read this in [Portugues](./README.pt-BR.md)*
|
|
27
|
+
|
|
28
|
+
</div>
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## The Problem
|
|
33
|
+
|
|
34
|
+
AI coding assistants are powerful — but **stateless**.
|
|
35
|
+
|
|
36
|
+
Every new session starts from scratch. Your architecture decisions, coding patterns, past migrations, and project context vanish the moment you close the chat.
|
|
37
|
+
|
|
38
|
+
## The Solution
|
|
4
39
|
|
|
5
|
-
|
|
40
|
+
Delfos CLI connects your **Obsidian vault** to a local vector database, turning your notes into a RAG-powered memory layer.
|
|
41
|
+
|
|
42
|
+
Your AI tools can then **read**, **write**, and **search** this memory through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).
|
|
43
|
+
|
|
44
|
+
```mermaid
|
|
45
|
+
flowchart TD
|
|
46
|
+
A[Your Obsidian Vault<br/>decisions · patterns · sessions]
|
|
47
|
+
B[ChromaDB<br/>local vectors<br/>384-dim embeddings]
|
|
48
|
+
C[Cursor]
|
|
49
|
+
D[Claude Code]
|
|
50
|
+
E[Windsurf]
|
|
51
|
+
F[VS Code Copilot]
|
|
52
|
+
|
|
53
|
+
A -->|scan + chunk + embed| B
|
|
54
|
+
B -->|MCP stdio| C
|
|
55
|
+
B -->|MCP stdio| D
|
|
56
|
+
B -->|MCP stdio| E
|
|
57
|
+
B -->|MCP stdio| F
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## Features
|
|
63
|
+
|
|
64
|
+
| Feature | Description |
|
|
65
|
+
|---------|-------------|
|
|
66
|
+
| **Semantic Search** | RAG-powered search across your vault with relevance scoring and deduplication |
|
|
67
|
+
| **Auto-Indexing** | Full and incremental indexing with heading-based chunking (H2 boundaries) |
|
|
68
|
+
| **MCP Server** | Expose memory tools to any MCP-compatible IDE via stdio transport |
|
|
69
|
+
| **Note Writing** | Programmatically create notes with YAML frontmatter, tags, and folder organization |
|
|
70
|
+
| **Local Embeddings** | Privacy-first — embeddings generated locally with `all-MiniLM-L6-v2` (384d) |
|
|
71
|
+
| **Cloud Auth** | OAuth PKCE browser flow, API key, or email/password authentication |
|
|
72
|
+
| **Setup Wizard** | Interactive guided setup — checks dependencies, scaffolds vault, configures MCP |
|
|
73
|
+
| **Vault Templates** | Pre-built vault structure with templates for decisions, migrations, and sessions |
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## Getting Started
|
|
78
|
+
|
|
79
|
+
### Prerequisites
|
|
80
|
+
|
|
81
|
+
- **Node.js** >= 22.0.0
|
|
82
|
+
- **Docker** (for ChromaDB) — or a remote ChromaDB instance
|
|
83
|
+
- An **Obsidian vault** (or let Delfos scaffold one for you)
|
|
84
|
+
|
|
85
|
+
### Install
|
|
6
86
|
|
|
7
87
|
```bash
|
|
8
88
|
npm install -g @delfos-ai/cli
|
|
9
89
|
```
|
|
10
90
|
|
|
11
|
-
|
|
91
|
+
### Quick Setup
|
|
12
92
|
|
|
13
|
-
|
|
93
|
+
The interactive wizard walks you through everything:
|
|
14
94
|
|
|
15
95
|
```bash
|
|
16
|
-
|
|
17
|
-
|
|
96
|
+
delfos setup
|
|
97
|
+
```
|
|
18
98
|
|
|
19
|
-
|
|
20
|
-
|
|
99
|
+
This will:
|
|
100
|
+
1. Check Node.js, Docker, and ChromaDB
|
|
101
|
+
2. Authenticate with the Delfos platform
|
|
102
|
+
3. Initialize or connect your Obsidian vault
|
|
103
|
+
4. Index your vault into ChromaDB
|
|
104
|
+
5. Configure MCP for your IDE
|
|
21
105
|
|
|
22
|
-
|
|
23
|
-
delfos logout
|
|
24
|
-
```
|
|
106
|
+
### Manual Setup
|
|
25
107
|
|
|
26
|
-
|
|
108
|
+
<details>
|
|
109
|
+
<summary>Prefer step-by-step? Click to expand.</summary>
|
|
27
110
|
|
|
28
111
|
```bash
|
|
29
|
-
#
|
|
112
|
+
# 1. Authenticate
|
|
113
|
+
delfos login --browser
|
|
114
|
+
|
|
115
|
+
# 2. Initialize vault structure
|
|
30
116
|
delfos memory init --vault-path ~/my-vault
|
|
31
117
|
|
|
32
|
-
#
|
|
118
|
+
# 3. Index your vault
|
|
33
119
|
delfos memory index
|
|
34
120
|
|
|
35
|
-
#
|
|
36
|
-
delfos
|
|
121
|
+
# 4. Start the MCP server
|
|
122
|
+
delfos mcp-server
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
</details>
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## Commands
|
|
130
|
+
|
|
131
|
+
```
|
|
132
|
+
delfos
|
|
133
|
+
├── setup Interactive guided setup wizard
|
|
134
|
+
├── login Authenticate with the Delfos platform
|
|
135
|
+
│ ├── --browser OAuth PKCE browser flow (recommended)
|
|
136
|
+
│ ├── --email + --api-key API key authentication
|
|
137
|
+
│ └── --email + --password Email/password authentication
|
|
138
|
+
├── logout Log out and clear stored credentials
|
|
139
|
+
└── memory Manage Delfos memory
|
|
140
|
+
├── init Scaffold Obsidian vault structure
|
|
141
|
+
│ └── --vault-path Path to your vault
|
|
142
|
+
├── index Index vault into ChromaDB
|
|
143
|
+
├── read Semantic search in your vault
|
|
144
|
+
├── write Write a note to the vault
|
|
145
|
+
│ ├── --folder Target folder in the vault
|
|
146
|
+
│ └── --tags Comma-separated tags
|
|
147
|
+
└── status Show memory service status
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### Examples
|
|
37
151
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
152
|
+
```bash
|
|
153
|
+
# Search your vault for relevant context
|
|
154
|
+
delfos memory read "authentication flow decisions"
|
|
155
|
+
|
|
156
|
+
# Write a decision record
|
|
157
|
+
delfos memory write "Use PostgreSQL for persistence" \
|
|
158
|
+
"## Context\nWe need a relational database...\n## Decision\nPostgreSQL 16." \
|
|
159
|
+
--folder "Projects/my-app/Decisions" \
|
|
41
160
|
--tags "architecture,database"
|
|
42
161
|
|
|
43
|
-
#
|
|
162
|
+
# Check indexing status
|
|
44
163
|
delfos memory status
|
|
45
164
|
```
|
|
46
165
|
|
|
47
|
-
|
|
166
|
+
---
|
|
48
167
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
168
|
+
## MCP Integration
|
|
169
|
+
|
|
170
|
+
Delfos exposes four tools via the [Model Context Protocol](https://modelcontextprotocol.io/):
|
|
171
|
+
|
|
172
|
+
| Tool | Description |
|
|
173
|
+
|------|-------------|
|
|
174
|
+
| `memory_read` | Semantic search with folder/tag filters and relevance scoring |
|
|
175
|
+
| `memory_write` | Create notes with YAML frontmatter and folder organization |
|
|
176
|
+
| `memory_index` | Trigger full or incremental vault indexing |
|
|
177
|
+
| `memory_status` | Get vault stats and vector DB health |
|
|
178
|
+
|
|
179
|
+
### Configure Your IDE
|
|
180
|
+
|
|
181
|
+
<details>
|
|
182
|
+
<summary><strong>Claude Code</strong></summary>
|
|
183
|
+
|
|
184
|
+
```json
|
|
185
|
+
// ~/.claude/mcp_servers.json
|
|
186
|
+
{
|
|
187
|
+
"mcpServers": {
|
|
188
|
+
"delfos-memory": {
|
|
189
|
+
"command": "delfos",
|
|
190
|
+
"args": ["mcp-server"]
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
}
|
|
52
194
|
```
|
|
53
195
|
|
|
54
|
-
|
|
196
|
+
</details>
|
|
197
|
+
|
|
198
|
+
<details>
|
|
199
|
+
<summary><strong>Cursor</strong></summary>
|
|
200
|
+
|
|
201
|
+
```json
|
|
202
|
+
// ~/.cursor/mcp.json
|
|
203
|
+
{
|
|
204
|
+
"mcpServers": {
|
|
205
|
+
"delfos-memory": {
|
|
206
|
+
"command": "delfos",
|
|
207
|
+
"args": ["mcp-server"]
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
</details>
|
|
214
|
+
|
|
215
|
+
<details>
|
|
216
|
+
<summary><strong>Windsurf</strong></summary>
|
|
217
|
+
|
|
55
218
|
```json
|
|
56
219
|
// ~/.windsurf/mcp.json
|
|
57
220
|
{
|
|
@@ -64,29 +227,126 @@ Configurar no IDE:
|
|
|
64
227
|
}
|
|
65
228
|
```
|
|
66
229
|
|
|
67
|
-
|
|
230
|
+
</details>
|
|
68
231
|
|
|
69
|
-
|
|
232
|
+
<details>
|
|
233
|
+
<summary><strong>VS Code (GitHub Copilot)</strong></summary>
|
|
70
234
|
|
|
71
235
|
```json
|
|
236
|
+
// .vscode/mcp.json
|
|
72
237
|
{
|
|
73
|
-
"
|
|
74
|
-
|
|
75
|
-
|
|
238
|
+
"servers": {
|
|
239
|
+
"delfos-memory": {
|
|
240
|
+
"command": "delfos",
|
|
241
|
+
"args": ["mcp-server"]
|
|
242
|
+
}
|
|
243
|
+
}
|
|
76
244
|
}
|
|
77
245
|
```
|
|
78
246
|
|
|
79
|
-
|
|
247
|
+
</details>
|
|
248
|
+
|
|
249
|
+
---
|
|
250
|
+
|
|
251
|
+
## How It Works
|
|
252
|
+
|
|
253
|
+
```
|
|
254
|
+
1. SCAN Your Obsidian vault is scanned for .md files
|
|
255
|
+
2. PARSE Markdown is parsed, frontmatter extracted
|
|
256
|
+
3. CHUNK Notes are split at H2 headings (min/max char limits)
|
|
257
|
+
4. EMBED Chunks are embedded locally (all-MiniLM-L6-v2, 384 dimensions)
|
|
258
|
+
5. STORE Embeddings are stored in ChromaDB with metadata
|
|
259
|
+
6. QUERY AI tools search via MCP → embed query → cosine similarity → ranked results
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
**Incremental indexing** — only changed files are re-indexed (based on file modification time), making subsequent runs fast.
|
|
263
|
+
|
|
264
|
+
**Privacy-first** — all embeddings are generated locally. Your notes never leave your machine unless you explicitly use a cloud embedding provider.
|
|
265
|
+
|
|
266
|
+
---
|
|
267
|
+
|
|
268
|
+
## Configuration
|
|
269
|
+
|
|
270
|
+
Config is stored at `~/.delfos/config.json`:
|
|
271
|
+
|
|
272
|
+
| Field | Default | Description |
|
|
273
|
+
|-------|---------|-------------|
|
|
274
|
+
| `apiBaseUrl` | `https://api-hml-ai.delfos.dev` | Delfos backend API |
|
|
275
|
+
| `directusUrl` | `https://cms-hml-ai.delfos.dev` | Directus CMS |
|
|
276
|
+
| `appUrl` | `https://hml-ai.delfos.dev` | Frontend app (OAuth callback) |
|
|
277
|
+
| `token` | — | Bearer token (set after login) |
|
|
278
|
+
| `userId` | — | Directus user ID |
|
|
279
|
+
|
|
280
|
+
### Memory Configuration
|
|
281
|
+
|
|
282
|
+
| Field | Default | Description |
|
|
283
|
+
|-------|---------|-------------|
|
|
284
|
+
| `vault_path` | *(required)* | Absolute path to your Obsidian vault |
|
|
285
|
+
| `vector_db.engine` | `chroma` | Vector DB engine |
|
|
286
|
+
| `embeddings.provider` | `local` | `local`, `openai`, or `nomic` |
|
|
287
|
+
| `embeddings.model` | `all-MiniLM-L6-v2` | Embedding model |
|
|
288
|
+
| `index_on_startup` | `false` | Auto-index vault when MCP server starts |
|
|
289
|
+
|
|
290
|
+
---
|
|
291
|
+
|
|
292
|
+
## Vault Structure
|
|
293
|
+
|
|
294
|
+
When you run `delfos memory init`, a best-practice vault structure is scaffolded:
|
|
295
|
+
|
|
296
|
+
```
|
|
297
|
+
my-vault/
|
|
298
|
+
├── AI-Context/
|
|
299
|
+
│ ├── global-rules.md # Cross-project AI rules
|
|
300
|
+
│ └── tool-preferences.md # IDE/tool preferences
|
|
301
|
+
├── Patterns/
|
|
302
|
+
│ ├── architecture-patterns.md
|
|
303
|
+
│ └── coding-standards.md
|
|
304
|
+
├── Projects/
|
|
305
|
+
│ └── example-project/
|
|
306
|
+
│ ├── Overview.md
|
|
307
|
+
│ ├── Decisions/ # ADRs and technical decisions
|
|
308
|
+
│ ├── Migrations/ # Migration logs
|
|
309
|
+
│ └── Sessions/ # AI pair-programming sessions
|
|
310
|
+
└── Templates/
|
|
311
|
+
├── decision.md
|
|
312
|
+
├── migration.md
|
|
313
|
+
└── session.md
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
---
|
|
317
|
+
|
|
318
|
+
## Tech Stack
|
|
319
|
+
|
|
320
|
+
| Component | Technology |
|
|
321
|
+
|-----------|-----------|
|
|
322
|
+
| CLI Framework | [Commander.js](https://github.com/tj/commander.js) |
|
|
323
|
+
| MCP Server | [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) |
|
|
324
|
+
| Vector Database | [ChromaDB](https://www.trychroma.com/) |
|
|
325
|
+
| Embeddings | [HuggingFace Transformers](https://huggingface.co/docs/transformers.js) (`all-MiniLM-L6-v2`) |
|
|
326
|
+
| Validation | [Zod](https://zod.dev/) |
|
|
327
|
+
| Logging | [Pino](https://getpino.io/) |
|
|
328
|
+
| Language | TypeScript (strict, ESM) |
|
|
329
|
+
|
|
330
|
+
---
|
|
331
|
+
|
|
332
|
+
## Contributing
|
|
333
|
+
|
|
334
|
+
This is a proprietary project. See the [LICENSE](./LICENSE) for details.
|
|
335
|
+
|
|
336
|
+
For bug reports and feature requests, contact us at [support@delfos.io](mailto:support@delfos.io).
|
|
337
|
+
|
|
338
|
+
---
|
|
339
|
+
|
|
340
|
+
## Links
|
|
80
341
|
|
|
81
|
-
-
|
|
82
|
-
-
|
|
342
|
+
- [Documentation](https://docs.delfos.dev/cli)
|
|
343
|
+
- [Delfos Platform](https://ai.delfos.dev)
|
|
344
|
+
- [Terms of Use](https://ai.delfos.dev/terms)
|
|
83
345
|
|
|
84
|
-
|
|
346
|
+
---
|
|
85
347
|
|
|
86
|
-
|
|
87
|
-
- [Backend API](https://api-hml-ai.delfos.dev/docs)
|
|
88
|
-
- [Repositório](https://github.com/delfos-io/delfos-cli)
|
|
348
|
+
<div align="center">
|
|
89
349
|
|
|
90
|
-
|
|
350
|
+
**Built with :purple_heart: by [Delfos](https://delfos.io)**
|
|
91
351
|
|
|
92
|
-
|
|
352
|
+
</div>
|
package/README.pt-BR.md
ADDED
|
@@ -0,0 +1,352 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Delfos CLI
|
|
6
|
+
|
|
7
|
+
<img src="docs/logo_delfos.png" alt="Delfos Logo" width="800" />
|
|
8
|
+
|
|
9
|
+
<span style="color: transparent">.</span>
|
|
10
|
+
|
|
11
|
+
**Suas ferramentas de IA merecem uma memoria. A Delfos da uma para elas.**
|
|
12
|
+
|
|
13
|
+
De aos seus assistentes de IA uma memoria persistente e semantica, alimentada pelo seu vault Obsidian — em qualquer IDE, em qualquer sessao.
|
|
14
|
+
|
|
15
|
+
[](https://www.npmjs.com/package/@delfos-ai/cli)
|
|
16
|
+
[](https://nodejs.org/)
|
|
17
|
+
[](./LICENSE)
|
|
18
|
+
<!--[](https://github.com/delfos-io/delfos-cli/actions/workflows/ci.yml)-->
|
|
19
|
+
|
|
20
|
+
[**Primeiros Passos**](#-primeiros-passos) ·
|
|
21
|
+
[**Funcionalidades**](#-funcionalidades) ·
|
|
22
|
+
[**Comandos**](#-comandos) ·
|
|
23
|
+
[**Integracao MCP**](#-integracao-mcp) ·
|
|
24
|
+
[**Docs**](https://docs.delfos.dev/cli)
|
|
25
|
+
|
|
26
|
+
*Read this in [English](./README.md)*
|
|
27
|
+
|
|
28
|
+
</div>
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## O Problema
|
|
33
|
+
|
|
34
|
+
Assistentes de IA para codigo sao poderosos — mas ele são **sem estado** (`stateless`).
|
|
35
|
+
|
|
36
|
+
Cada nova sessao comeca do zero. Suas decisoes de arquitetura, padroes de codigo, migracoes anteriores e contexto do projeto desaparecem no momento em que voce fecha o chat.
|
|
37
|
+
|
|
38
|
+
## A Solucao
|
|
39
|
+
|
|
40
|
+
O Delfos CLI conecta seu **vault Obsidian** a um banco de dados vetorial local, transformando suas notas em uma camada de memoria RAG.
|
|
41
|
+
|
|
42
|
+
Suas ferramentas de IA podem entao **ler**, **escrever** e **buscar** nessa memoria atraves do [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).
|
|
43
|
+
|
|
44
|
+
```mermaid
|
|
45
|
+
flowchart TD
|
|
46
|
+
A[Seu Vault Obsidian<br/>decisoes · padroes · sessoes]
|
|
47
|
+
B[ChromaDB<br/>vetores locais<br/>embeddings de 384 dim]
|
|
48
|
+
C[Cursor]
|
|
49
|
+
D[Claude Code]
|
|
50
|
+
E[Windsurf]
|
|
51
|
+
F[VS Code Copilot]
|
|
52
|
+
|
|
53
|
+
A -->|scan + chunk + embed| B
|
|
54
|
+
B -->|MCP stdio| C
|
|
55
|
+
B -->|MCP stdio| D
|
|
56
|
+
B -->|MCP stdio| E
|
|
57
|
+
B -->|MCP stdio| F
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## Funcionalidades
|
|
63
|
+
|
|
64
|
+
| Funcionalidade | Descricao |
|
|
65
|
+
|----------------|-----------|
|
|
66
|
+
| **Busca Semantica** | Busca RAG no vault com pontuacao de relevancia e deduplicacao |
|
|
67
|
+
| **Auto-Indexacao** | Indexacao full e incremental com chunking por headings (H2) |
|
|
68
|
+
| **Servidor MCP** | Expoe ferramentas de memoria para qualquer IDE compativel via stdio |
|
|
69
|
+
| **Escrita de Notas** | Crie notas programaticamente com frontmatter YAML, tags e organizacao por pastas |
|
|
70
|
+
| **Embeddings Locais** | Privacidade em primeiro lugar — embeddings gerados localmente com `all-MiniLM-L6-v2` (384d) |
|
|
71
|
+
| **Auth na Nuvem** | Fluxo OAuth PKCE via browser, API key ou email/senha |
|
|
72
|
+
| **Wizard de Setup** | Setup interativo guiado — verifica dependencias, scaffolda vault, configura MCP |
|
|
73
|
+
| **Templates de Vault** | Estrutura de vault pre-construida com templates para decisoes, migracoes e sessoes |
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## Primeiros Passos
|
|
78
|
+
|
|
79
|
+
### Pre-requisitos
|
|
80
|
+
|
|
81
|
+
- **Node.js** >= 22.0.0
|
|
82
|
+
- **Docker** (para ChromaDB) — ou uma instancia remota de ChromaDB
|
|
83
|
+
- Um **vault Obsidian** (ou deixe o Delfos criar um para voce)
|
|
84
|
+
|
|
85
|
+
### Instalacao
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
npm install -g @delfos-ai/cli
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Setup Rapido
|
|
92
|
+
|
|
93
|
+
O wizard interativo guia voce por tudo:
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
delfos setup
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Isso vai:
|
|
100
|
+
1. Verificar Node.js, Docker e ChromaDB
|
|
101
|
+
2. Autenticar na plataforma Delfos
|
|
102
|
+
3. Inicializar ou conectar seu vault Obsidian
|
|
103
|
+
4. Indexar seu vault no ChromaDB
|
|
104
|
+
5. Configurar MCP para sua IDE
|
|
105
|
+
|
|
106
|
+
### Setup Manual
|
|
107
|
+
|
|
108
|
+
<details>
|
|
109
|
+
<summary>Prefere passo a passo? Clique para expandir.</summary>
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
# 1. Autenticar
|
|
113
|
+
delfos login --browser
|
|
114
|
+
|
|
115
|
+
# 2. Inicializar estrutura do vault
|
|
116
|
+
delfos memory init --vault-path ~/meu-vault
|
|
117
|
+
|
|
118
|
+
# 3. Indexar seu vault
|
|
119
|
+
delfos memory index
|
|
120
|
+
|
|
121
|
+
# 4. Iniciar o servidor MCP
|
|
122
|
+
delfos mcp-server
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
</details>
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## Comandos
|
|
130
|
+
|
|
131
|
+
```
|
|
132
|
+
delfos
|
|
133
|
+
├── setup Wizard interativo de configuracao
|
|
134
|
+
├── login Autenticar na plataforma Delfos
|
|
135
|
+
│ ├── --browser Fluxo OAuth PKCE via browser (recomendado)
|
|
136
|
+
│ ├── --email + --api-key Autenticacao por API key
|
|
137
|
+
│ └── --email + --password Autenticacao por email/senha
|
|
138
|
+
├── logout Deslogar e limpar credenciais
|
|
139
|
+
└── memory Gerenciar memoria Delfos
|
|
140
|
+
├── init Scaffoldar estrutura do vault Obsidian
|
|
141
|
+
│ └── --vault-path Caminho para o vault
|
|
142
|
+
├── index Indexar vault no ChromaDB
|
|
143
|
+
├── read Busca semantica no vault
|
|
144
|
+
├── write Escrever uma nota no vault
|
|
145
|
+
│ ├── --folder Pasta destino no vault
|
|
146
|
+
│ └── --tags Tags separadas por virgula
|
|
147
|
+
└── status Mostrar status do servico de memoria
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### Exemplos
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
# Buscar contexto relevante no vault
|
|
154
|
+
delfos memory read "decisoes de autenticacao"
|
|
155
|
+
|
|
156
|
+
# Escrever um registro de decisao
|
|
157
|
+
delfos memory write "Usar PostgreSQL para persistencia" \
|
|
158
|
+
"## Contexto\nPrecisamos de um banco relacional...\n## Decisao\nPostgreSQL 16." \
|
|
159
|
+
--folder "Projects/meu-app/Decisions" \
|
|
160
|
+
--tags "arquitetura,banco-de-dados"
|
|
161
|
+
|
|
162
|
+
# Verificar status da indexacao
|
|
163
|
+
delfos memory status
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## Integracao MCP
|
|
169
|
+
|
|
170
|
+
O Delfos expoe quatro ferramentas via [Model Context Protocol](https://modelcontextprotocol.io/):
|
|
171
|
+
|
|
172
|
+
| Ferramenta | Descricao |
|
|
173
|
+
|------------|-----------|
|
|
174
|
+
| `memory_read` | Busca semantica com filtros de pasta/tag e pontuacao de relevancia |
|
|
175
|
+
| `memory_write` | Criar notas com frontmatter YAML e organizacao por pastas |
|
|
176
|
+
| `memory_index` | Disparar indexacao full ou incremental do vault |
|
|
177
|
+
| `memory_status` | Obter estatisticas do vault e saude do banco vetorial |
|
|
178
|
+
|
|
179
|
+
### Configurar sua IDE
|
|
180
|
+
|
|
181
|
+
<details>
|
|
182
|
+
<summary><strong>Claude Code</strong></summary>
|
|
183
|
+
|
|
184
|
+
```json
|
|
185
|
+
// ~/.claude/mcp_servers.json
|
|
186
|
+
{
|
|
187
|
+
"mcpServers": {
|
|
188
|
+
"delfos-memory": {
|
|
189
|
+
"command": "delfos",
|
|
190
|
+
"args": ["mcp-server"]
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
</details>
|
|
197
|
+
|
|
198
|
+
<details>
|
|
199
|
+
<summary><strong>Cursor</strong></summary>
|
|
200
|
+
|
|
201
|
+
```json
|
|
202
|
+
// ~/.cursor/mcp.json
|
|
203
|
+
{
|
|
204
|
+
"mcpServers": {
|
|
205
|
+
"delfos-memory": {
|
|
206
|
+
"command": "delfos",
|
|
207
|
+
"args": ["mcp-server"]
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
</details>
|
|
214
|
+
|
|
215
|
+
<details>
|
|
216
|
+
<summary><strong>Windsurf</strong></summary>
|
|
217
|
+
|
|
218
|
+
```json
|
|
219
|
+
// ~/.windsurf/mcp.json
|
|
220
|
+
{
|
|
221
|
+
"mcpServers": {
|
|
222
|
+
"delfos-memory": {
|
|
223
|
+
"command": "delfos",
|
|
224
|
+
"args": ["mcp-server"]
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
</details>
|
|
231
|
+
|
|
232
|
+
<details>
|
|
233
|
+
<summary><strong>VS Code (GitHub Copilot)</strong></summary>
|
|
234
|
+
|
|
235
|
+
```json
|
|
236
|
+
// .vscode/mcp.json
|
|
237
|
+
{
|
|
238
|
+
"servers": {
|
|
239
|
+
"delfos-memory": {
|
|
240
|
+
"command": "delfos",
|
|
241
|
+
"args": ["mcp-server"]
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
</details>
|
|
248
|
+
|
|
249
|
+
---
|
|
250
|
+
|
|
251
|
+
## Como Funciona
|
|
252
|
+
|
|
253
|
+
```
|
|
254
|
+
1. SCAN Seu vault Obsidian e escaneado em busca de arquivos .md
|
|
255
|
+
2. PARSE Markdown e parseado, frontmatter extraido
|
|
256
|
+
3. CHUNK Notas sao divididas nos headings H2 (limites min/max de caracteres)
|
|
257
|
+
4. EMBED Chunks sao embeddados localmente (all-MiniLM-L6-v2, 384 dimensoes)
|
|
258
|
+
5. STORE Embeddings sao armazenados no ChromaDB com metadados
|
|
259
|
+
6. QUERY Ferramentas de IA buscam via MCP → embed query → similaridade cosseno → resultados rankeados
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
**Indexacao incremental** — apenas arquivos alterados sao re-indexados (baseado no tempo de modificacao), tornando execucoes subsequentes rapidas.
|
|
263
|
+
|
|
264
|
+
**Privacidade em primeiro lugar** — todos os embeddings sao gerados localmente. Suas notas nunca saem da sua maquina, a menos que voce use explicitamente um provider de embeddings na nuvem.
|
|
265
|
+
|
|
266
|
+
---
|
|
267
|
+
|
|
268
|
+
## Configuracao
|
|
269
|
+
|
|
270
|
+
A configuracao e armazenada em `~/.delfos/config.json`:
|
|
271
|
+
|
|
272
|
+
| Campo | Padrao | Descricao |
|
|
273
|
+
|-------|--------|-----------|
|
|
274
|
+
| `apiBaseUrl` | `https://api-hml-ai.delfos.dev` | API do backend Delfos |
|
|
275
|
+
| `directusUrl` | `https://cms-hml-ai.delfos.dev` | CMS Directus |
|
|
276
|
+
| `appUrl` | `https://hml-ai.delfos.dev` | App frontend (callback OAuth) |
|
|
277
|
+
| `token` | — | Bearer token (definido apos login) |
|
|
278
|
+
| `userId` | — | ID do usuario no Directus |
|
|
279
|
+
|
|
280
|
+
### Configuracao de Memoria
|
|
281
|
+
|
|
282
|
+
| Campo | Padrao | Descricao |
|
|
283
|
+
|-------|--------|-----------|
|
|
284
|
+
| `vault_path` | *(obrigatorio)* | Caminho absoluto do vault Obsidian |
|
|
285
|
+
| `vector_db.engine` | `chroma` | Engine do banco vetorial |
|
|
286
|
+
| `embeddings.provider` | `local` | `local`, `openai` ou `nomic` |
|
|
287
|
+
| `embeddings.model` | `all-MiniLM-L6-v2` | Modelo de embedding |
|
|
288
|
+
| `index_on_startup` | `false` | Auto-indexar vault ao iniciar o servidor MCP |
|
|
289
|
+
|
|
290
|
+
---
|
|
291
|
+
|
|
292
|
+
## Estrutura do Vault
|
|
293
|
+
|
|
294
|
+
Ao executar `delfos memory init`, uma estrutura de vault com boas praticas e scaffoldada:
|
|
295
|
+
|
|
296
|
+
```
|
|
297
|
+
meu-vault/
|
|
298
|
+
├── AI-Context/
|
|
299
|
+
│ ├── global-rules.md # Regras de IA cross-projeto
|
|
300
|
+
│ └── tool-preferences.md # Preferencias de IDE/ferramentas
|
|
301
|
+
├── Patterns/
|
|
302
|
+
│ ├── architecture-patterns.md
|
|
303
|
+
│ └── coding-standards.md
|
|
304
|
+
├── Projects/
|
|
305
|
+
│ └── exemplo-projeto/
|
|
306
|
+
│ ├── Overview.md
|
|
307
|
+
│ ├── Decisions/ # ADRs e decisoes tecnicas
|
|
308
|
+
│ ├── Migrations/ # Logs de migracoes
|
|
309
|
+
│ └── Sessions/ # Sessoes de pair-programming com IA
|
|
310
|
+
└── Templates/
|
|
311
|
+
├── decision.md
|
|
312
|
+
├── migration.md
|
|
313
|
+
└── session.md
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
---
|
|
317
|
+
|
|
318
|
+
## Stack Tecnologica
|
|
319
|
+
|
|
320
|
+
| Componente | Tecnologia |
|
|
321
|
+
|------------|-----------|
|
|
322
|
+
| Framework CLI | [Commander.js](https://github.com/tj/commander.js) |
|
|
323
|
+
| Servidor MCP | [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) |
|
|
324
|
+
| Banco Vetorial | [ChromaDB](https://www.trychroma.com/) |
|
|
325
|
+
| Embeddings | [HuggingFace Transformers](https://huggingface.co/docs/transformers.js) (`all-MiniLM-L6-v2`) |
|
|
326
|
+
| Validacao | [Zod](https://zod.dev/) |
|
|
327
|
+
| Logging | [Pino](https://getpino.io/) |
|
|
328
|
+
| Linguagem | TypeScript (strict, ESM) |
|
|
329
|
+
|
|
330
|
+
---
|
|
331
|
+
|
|
332
|
+
## Contribuindo
|
|
333
|
+
|
|
334
|
+
Este e um projeto proprietario. Veja a [LICENCA](./LICENSE) para detalhes.
|
|
335
|
+
|
|
336
|
+
Para reportar bugs e solicitar funcionalidades, entre em contato em [support@delfos.io](mailto:support@delfos.io).
|
|
337
|
+
|
|
338
|
+
---
|
|
339
|
+
|
|
340
|
+
## Links
|
|
341
|
+
|
|
342
|
+
- [Documentacao](https://docs.delfos.dev/cli)
|
|
343
|
+
- [Plataforma Delfos](https://ai.delfos.dev)
|
|
344
|
+
- [Termos de Uso](https://ai.delfos.dev/terms)
|
|
345
|
+
|
|
346
|
+
---
|
|
347
|
+
|
|
348
|
+
<div align="center">
|
|
349
|
+
|
|
350
|
+
**Feito com :purple_heart: pela [Delfos](https://delfos.io)**
|
|
351
|
+
|
|
352
|
+
</div>
|
package/package.json
CHANGED