@hasna/knowledge 0.2.28 → 0.2.29
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 +101 -101
- package/bin/{open-knowledge-mcp.js → knowledge-mcp.js} +9 -10
- package/bin/{open-knowledge.js → knowledge.js} +19 -19
- package/dist/index.js +2 -2
- package/docs/architecture/ai-native-knowledge-base.md +16 -16
- package/docs/architecture/hosted-wrapper-responsibilities.md +5 -5
- package/docs/architecture/hybrid-semantic-search.md +12 -12
- package/docs/canonical-secrets-bootstrap-2026-06-08.md +1 -1
- package/docs/examples/company-wiki-workflow.md +19 -19
- package/docs/migration/json-to-sqlite.md +17 -17
- package/package.json +4 -5
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
#
|
|
1
|
+
# knowledge
|
|
2
2
|
|
|
3
3
|
> Agent-friendly local knowledge CLI/MCP with JSON output, project workspaces, durable artifacts, and safe destructive actions.
|
|
4
4
|
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
[](LICENSE)
|
|
7
7
|
[](.github/workflows/ci.yml)
|
|
8
8
|
|
|
9
|
-
`
|
|
9
|
+
`knowledge` is evolving from a flat note store into a local-first knowledge
|
|
10
10
|
engine for AI agents. It stores simple knowledge items today, creates a Hasna
|
|
11
11
|
project workspace under `.hasna/apps/knowledge`, initializes a versioned
|
|
12
12
|
`knowledge.db`, writes generated wiki artifacts, and exposes a stdio MCP server.
|
|
@@ -69,98 +69,98 @@ available as package bins.
|
|
|
69
69
|
The SDK uses the same `.hasna/apps/knowledge` project workspace as the CLI. In
|
|
70
70
|
local mode it writes the SQLite catalog and generated artifacts under that path.
|
|
71
71
|
In hosted/canonical mode it can point generated artifacts at S3 while keeping
|
|
72
|
-
raw source ownership outside
|
|
73
|
-
`open-files://`, `file://`, `s3://`, or web refs;
|
|
72
|
+
raw source ownership outside knowledge. Source files remain referenced via
|
|
73
|
+
`open-files://`, `file://`, `s3://`, or web refs; knowledge stores derived
|
|
74
74
|
chunks, citations, indexes, run logs, and generated wiki artifacts.
|
|
75
75
|
|
|
76
76
|
## Quick Start
|
|
77
77
|
|
|
78
78
|
```bash
|
|
79
79
|
# Add a note
|
|
80
|
-
|
|
80
|
+
knowledge add "Rust ownership" "Every value has exactly one owner"
|
|
81
81
|
|
|
82
82
|
# List all notes
|
|
83
|
-
|
|
83
|
+
knowledge list
|
|
84
84
|
|
|
85
85
|
# List with search
|
|
86
|
-
|
|
86
|
+
knowledge list --search ownership
|
|
87
87
|
|
|
88
88
|
# List notes tagged "rust"
|
|
89
|
-
|
|
89
|
+
knowledge list --tag rust
|
|
90
90
|
|
|
91
91
|
# Get a note
|
|
92
|
-
|
|
92
|
+
knowledge get --id <id>
|
|
93
93
|
|
|
94
94
|
# Update a note
|
|
95
|
-
|
|
95
|
+
knowledge update --id <id> --title "Rust ownership model"
|
|
96
96
|
|
|
97
97
|
# Delete a note (requires --yes)
|
|
98
|
-
|
|
98
|
+
knowledge delete --id <id> --yes
|
|
99
99
|
|
|
100
100
|
# Export all notes as JSONL
|
|
101
|
-
|
|
101
|
+
knowledge export --format jsonl
|
|
102
102
|
|
|
103
103
|
# Show resolved workspace paths
|
|
104
|
-
|
|
104
|
+
knowledge paths --scope project --json
|
|
105
105
|
|
|
106
106
|
# Inspect local/S3 artifact storage and source ownership
|
|
107
|
-
|
|
107
|
+
knowledge storage status --scope project --json
|
|
108
108
|
|
|
109
109
|
# Configure optional hosted mode and inspect remote contracts
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
110
|
+
knowledge setup --mode hosted --api-url https://knowledge.hasna.xyz --scope project --json
|
|
111
|
+
knowledge auth whoami --scope project --json
|
|
112
|
+
knowledge remote contracts --scope project --json
|
|
113
113
|
|
|
114
114
|
# Initialize the project SQLite catalog
|
|
115
|
-
|
|
115
|
+
knowledge db init --scope project
|
|
116
116
|
|
|
117
117
|
# Initialize scalable wiki/schema/index/log artifacts
|
|
118
|
-
|
|
118
|
+
knowledge wiki init --scope project
|
|
119
119
|
|
|
120
120
|
# Compile cited wiki pages, file approved answers, and lint wiki health
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
121
|
+
knowledge wiki compile "handbook policy" --title "Handbook Policy" --scope project --json
|
|
122
|
+
knowledge wiki file-answer "How do we cite policy?" --content "Use cited source context." --approve-write --scope project --json
|
|
123
|
+
knowledge wiki lint --scope project --json
|
|
124
124
|
|
|
125
125
|
# Ingest an open-files source manifest into the project SQLite catalog
|
|
126
|
-
|
|
126
|
+
knowledge ingest manifest ./open-files-manifest.jsonl --scope project --json
|
|
127
127
|
|
|
128
128
|
# Ingest one read-only source ref directly
|
|
129
|
-
|
|
129
|
+
knowledge ingest source file:///absolute/path/to/handbook.md --purpose knowledge_index --scope project --json
|
|
130
130
|
|
|
131
131
|
# Consume open-files change events and invalidate stale source chunks
|
|
132
|
-
|
|
132
|
+
knowledge reindex outbox ./open-files-outbox.jsonl --scope project --json
|
|
133
133
|
|
|
134
134
|
# Inspect and refresh the embedding queue after source changes
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
135
|
+
knowledge reindex status --scope project --json
|
|
136
|
+
knowledge reindex enqueue --scope project --json
|
|
137
|
+
knowledge reindex embeddings --scope project --fake --json
|
|
138
138
|
|
|
139
139
|
# Resolve indexed source text and citation evidence through the read-only source boundary
|
|
140
|
-
|
|
140
|
+
knowledge source resolve open-files://file/f_123/revision/rev_456 --scope project --json
|
|
141
141
|
|
|
142
142
|
# Inspect local safety policy and approvals
|
|
143
|
-
|
|
143
|
+
knowledge safety status --scope project --json
|
|
144
144
|
|
|
145
145
|
# Inspect AI SDK provider credentials and model aliases
|
|
146
|
-
|
|
147
|
-
|
|
146
|
+
knowledge providers status --scope project --json
|
|
147
|
+
knowledge providers models --scope project --json
|
|
148
148
|
|
|
149
149
|
# Embed indexed chunks and run semantic search
|
|
150
|
-
|
|
151
|
-
|
|
150
|
+
knowledge embeddings index --scope project --model openai:text-embedding-3-small --json
|
|
151
|
+
knowledge embeddings search "company wiki policy" --scope project --json
|
|
152
152
|
|
|
153
153
|
# Hybrid search over source chunks, generated wiki pages, indexes, and optional vectors
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
154
|
+
knowledge search "company wiki policy" --scope project --json
|
|
155
|
+
knowledge search "company wiki policy" --scope project --semantic --json
|
|
156
|
+
knowledge search "company wiki policy" --scope project --context --json
|
|
157
157
|
|
|
158
158
|
# Build a citation answer/context draft for a prompt
|
|
159
|
-
|
|
159
|
+
knowledge ask "How do we cite handbook policy?" --scope project --json
|
|
160
160
|
knowledge "How do we cite handbook policy?" --scope project --json
|
|
161
161
|
|
|
162
162
|
# Provider-native web search, safety-gated for real network access
|
|
163
|
-
HASNA_KNOWLEDGE_WEB_SEARCH=1
|
|
163
|
+
HASNA_KNOWLEDGE_WEB_SEARCH=1 knowledge web search "latest AI SDK web search" --provider openai --json
|
|
164
164
|
```
|
|
165
165
|
|
|
166
166
|
## Guides
|
|
@@ -182,13 +182,13 @@ HASNA_KNOWLEDGE_WEB_SEARCH=1 open-knowledge web search "latest AI SDK web search
|
|
|
182
182
|
|
|
183
183
|
### add
|
|
184
184
|
```bash
|
|
185
|
-
|
|
185
|
+
knowledge add <title> <content> [--url <url>] [-t <tag>]
|
|
186
186
|
```
|
|
187
187
|
Add a new knowledge item.
|
|
188
188
|
|
|
189
189
|
### list
|
|
190
190
|
```bash
|
|
191
|
-
|
|
191
|
+
knowledge list|ls [options]
|
|
192
192
|
```
|
|
193
193
|
List items with pagination, search, and tag filtering.
|
|
194
194
|
|
|
@@ -203,13 +203,13 @@ List items with pagination, search, and tag filtering.
|
|
|
203
203
|
|
|
204
204
|
### get
|
|
205
205
|
```bash
|
|
206
|
-
|
|
206
|
+
knowledge get --id <id>
|
|
207
207
|
```
|
|
208
208
|
Retrieve a single item by ID.
|
|
209
209
|
|
|
210
210
|
### update
|
|
211
211
|
```bash
|
|
212
|
-
|
|
212
|
+
knowledge update|edit --id <id> [options]
|
|
213
213
|
```
|
|
214
214
|
Update an existing item.
|
|
215
215
|
|
|
@@ -222,46 +222,46 @@ Update an existing item.
|
|
|
222
222
|
|
|
223
223
|
### archive / restore
|
|
224
224
|
```bash
|
|
225
|
-
|
|
226
|
-
|
|
225
|
+
knowledge archive --id <id>
|
|
226
|
+
knowledge restore --id <id>
|
|
227
227
|
```
|
|
228
228
|
Archive hides an item from default `list` output without deleting it.
|
|
229
229
|
|
|
230
230
|
### upsert
|
|
231
231
|
```bash
|
|
232
|
-
|
|
232
|
+
knowledge upsert [title] [content] [--id <id>] [--title <title>] [--content <content>]
|
|
233
233
|
```
|
|
234
234
|
Create or update an item by ID.
|
|
235
235
|
|
|
236
236
|
### untag
|
|
237
237
|
```bash
|
|
238
|
-
|
|
238
|
+
knowledge untag --id <id> -t <tag>
|
|
239
239
|
```
|
|
240
240
|
Remove one tag from an item.
|
|
241
241
|
|
|
242
242
|
### delete
|
|
243
243
|
```bash
|
|
244
|
-
|
|
244
|
+
knowledge delete|rm --id <id> --yes
|
|
245
245
|
```
|
|
246
246
|
Delete an item. Requires `--yes` to confirm.
|
|
247
247
|
|
|
248
248
|
### export
|
|
249
249
|
```bash
|
|
250
|
-
|
|
250
|
+
knowledge export [--format jsonl]
|
|
251
251
|
```
|
|
252
252
|
Export all items. Use `--format jsonl` for newline-delimited JSON.
|
|
253
253
|
|
|
254
254
|
### paths
|
|
255
255
|
```bash
|
|
256
|
-
|
|
256
|
+
knowledge paths [--scope global|project|local] [--json]
|
|
257
257
|
```
|
|
258
258
|
Show the resolved Hasna app workspace, JSON compatibility store, SQLite path,
|
|
259
259
|
artifact directories, and config.
|
|
260
260
|
|
|
261
261
|
### storage
|
|
262
262
|
```bash
|
|
263
|
-
|
|
264
|
-
|
|
263
|
+
knowledge storage status [--scope project] [--json]
|
|
264
|
+
knowledge storage validate [--scope project] [--json]
|
|
265
265
|
```
|
|
266
266
|
Show the storage contract for local or S3-backed generated artifacts. Local mode
|
|
267
267
|
uses `.hasna/apps/knowledge` for config, SQLite, indexes, wiki artifacts, logs,
|
|
@@ -287,14 +287,14 @@ The future hosted database path, if provisioned, is
|
|
|
287
287
|
|
|
288
288
|
### setup / auth / remote
|
|
289
289
|
```bash
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
290
|
+
knowledge setup --mode local [--scope project] [--json]
|
|
291
|
+
knowledge setup --mode hosted [--api-url https://knowledge.hasna.xyz] [--scope project] [--json]
|
|
292
|
+
knowledge setup --mode hosted --canonical-hasna-xyz [--scope project] [--json]
|
|
293
|
+
knowledge auth login --api-key <key> [--email you@example.com] [--org <slug>] [--scope project] [--json]
|
|
294
|
+
knowledge auth whoami [--scope project] [--json]
|
|
295
|
+
knowledge auth logout [--scope project] [--json]
|
|
296
|
+
knowledge remote status [--scope project] [--json]
|
|
297
|
+
knowledge remote contracts [--scope project] [--json]
|
|
298
298
|
```
|
|
299
299
|
Hosted mode mirrors the `open-skills` open-core pattern: the OSS package stays
|
|
300
300
|
local-first, while `hosted.api_url`, `KNOWLEDGE_API_URL`, and
|
|
@@ -305,18 +305,18 @@ and artifact API contract that a future SaaS wrapper can implement.
|
|
|
305
305
|
|
|
306
306
|
### db
|
|
307
307
|
```bash
|
|
308
|
-
|
|
309
|
-
|
|
308
|
+
knowledge db init [--scope project]
|
|
309
|
+
knowledge db stats [--scope project]
|
|
310
310
|
```
|
|
311
311
|
Initialize or inspect the versioned SQLite catalog at
|
|
312
312
|
`.hasna/apps/knowledge/knowledge.db`.
|
|
313
313
|
|
|
314
314
|
### wiki
|
|
315
315
|
```bash
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
316
|
+
knowledge wiki init [--scope project]
|
|
317
|
+
knowledge wiki compile [query|source-ref...] [--title <title>] [--limit <n>] [--scope project] [--json]
|
|
318
|
+
knowledge wiki file-answer <prompt> --content <answer> [--approve-write] [--scope project] [--json]
|
|
319
|
+
knowledge wiki lint [--scope project] [--json]
|
|
320
320
|
```
|
|
321
321
|
Create starter generated-knowledge artifacts through the artifact store:
|
|
322
322
|
`schemas/v1.md`, `indexes/root.md`, `wiki/README.md`, and a dated JSONL log
|
|
@@ -332,7 +332,7 @@ source refs, contradiction markers, and new article candidates.
|
|
|
332
332
|
|
|
333
333
|
### source
|
|
334
334
|
```bash
|
|
335
|
-
|
|
335
|
+
knowledge source resolve <source-ref> [--purpose knowledge_answer|knowledge_index] [--limit <n>] [--scope project] [--json]
|
|
336
336
|
```
|
|
337
337
|
Resolve an indexed source through the read-only open-files boundary. The result
|
|
338
338
|
returns source metadata, permissions, the selected revision, derived chunk text,
|
|
@@ -341,8 +341,8 @@ raw source retrieval remains owned by `open-files`.
|
|
|
341
341
|
|
|
342
342
|
### ingest
|
|
343
343
|
```bash
|
|
344
|
-
|
|
345
|
-
|
|
344
|
+
knowledge ingest manifest <file|s3://bucket/key> [--scope project] [--json]
|
|
345
|
+
knowledge ingest source <source-ref> [--purpose knowledge_index] [--scope project] [--json]
|
|
346
346
|
```
|
|
347
347
|
Import an open-files JSON or JSONL source manifest into `knowledge.db`. This
|
|
348
348
|
upserts sources and source revisions, stores hash/MIME/status/permission
|
|
@@ -358,10 +358,10 @@ resolver API lands.
|
|
|
358
358
|
|
|
359
359
|
### reindex
|
|
360
360
|
```bash
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
361
|
+
knowledge reindex status [--model openai:text-embedding-3-small] [--scope project] [--json]
|
|
362
|
+
knowledge reindex enqueue [--model openai:text-embedding-3-small] [--scope project] [--json]
|
|
363
|
+
knowledge reindex embeddings [--full] [--limit <n>] [--model openai:text-embedding-3-small] [--scope project] [--json]
|
|
364
|
+
knowledge reindex outbox <file|s3://bucket/key> [--scope project] [--json]
|
|
365
365
|
```
|
|
366
366
|
Inspect and operate index refresh work. `reindex status` reports missing
|
|
367
367
|
embedding rows, stale revisions, queued jobs, and vector counts. `reindex
|
|
@@ -378,9 +378,9 @@ remain owned by `open-files`.
|
|
|
378
378
|
|
|
379
379
|
### search
|
|
380
380
|
```bash
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
381
|
+
knowledge search <query> [--scope project] [--limit <n>] [--json]
|
|
382
|
+
knowledge search <query> --semantic [--model openai:text-embedding-3-small] [--scope project] [--json]
|
|
383
|
+
knowledge search <query> --context [--semantic] [--scope project] [--json]
|
|
384
384
|
```
|
|
385
385
|
Run hybrid search over `chunks_fts`, generated wiki chunks, wiki/index catalog
|
|
386
386
|
rows, and optional vector results. The default path is local-only keyword and
|
|
@@ -395,8 +395,8 @@ assembled citations, freshness and permission notes, graph evidence from
|
|
|
395
395
|
|
|
396
396
|
### ask / build
|
|
397
397
|
```bash
|
|
398
|
-
|
|
399
|
-
|
|
398
|
+
knowledge ask <prompt> [--scope project] [--json]
|
|
399
|
+
knowledge build <prompt> [--generate] [--model default|provider:model] [--scope project] [--json]
|
|
400
400
|
knowledge <prompt> [--scope project] [--json]
|
|
401
401
|
```
|
|
402
402
|
Build an agent-native prompt run. The command first creates a read-only context
|
|
@@ -408,7 +408,7 @@ intent, but durable wiki writes remain deferred to the wiki compile/write task.
|
|
|
408
408
|
|
|
409
409
|
### web
|
|
410
410
|
```bash
|
|
411
|
-
|
|
411
|
+
knowledge web search <query> [--provider openai|anthropic] [--model provider:model] [--domain <domain>] [--file-results] [--scope project] [--json]
|
|
412
412
|
```
|
|
413
413
|
Run provider-native hosted web search and return cited web sources. Real network
|
|
414
414
|
search is disabled unless `safety.network.web_search_enabled=true` or
|
|
@@ -420,11 +420,11 @@ deterministic offline sources for tests.
|
|
|
420
420
|
|
|
421
421
|
### safety
|
|
422
422
|
```bash
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
423
|
+
knowledge safety status [--scope project] [--json]
|
|
424
|
+
knowledge safety check generated_write [target] [--scope project] [--json]
|
|
425
|
+
knowledge safety approve generated_write [target] [--scope project] [--json]
|
|
426
|
+
knowledge safety audit [--scope project] [--json]
|
|
427
|
+
knowledge safety redact <text> [--scope project] [--json]
|
|
428
428
|
```
|
|
429
429
|
Inspect and operate the local safety model. Source reads are read-only by
|
|
430
430
|
default, web search and S3 reads are opt-in, generated writes require approval
|
|
@@ -432,9 +432,9 @@ by default, and known secret patterns are redacted before chunk storage.
|
|
|
432
432
|
|
|
433
433
|
### providers
|
|
434
434
|
```bash
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
435
|
+
knowledge providers status [--scope project] [--json]
|
|
436
|
+
knowledge providers models [--scope project] [--json]
|
|
437
|
+
knowledge providers check [provider|model-alias] [--scope project] [--json]
|
|
438
438
|
```
|
|
439
439
|
Inspect AI SDK v6 provider readiness for OpenAI, Anthropic, and DeepSeek. The
|
|
440
440
|
provider layer resolves BYOK credentials from `OPENAI_API_KEY`,
|
|
@@ -445,9 +445,9 @@ reasoning, embeddings, and native web-search support.
|
|
|
445
445
|
|
|
446
446
|
### embeddings
|
|
447
447
|
```bash
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
448
|
+
knowledge embeddings status [--scope project] [--json]
|
|
449
|
+
knowledge embeddings index [--model openai:text-embedding-3-small] [--limit <n>] [--scope project] [--json]
|
|
450
|
+
knowledge embeddings search <query> [--model openai:text-embedding-3-small] [--limit <n>] [--scope project] [--json]
|
|
451
451
|
```
|
|
452
452
|
Build and query the local vector index over derived knowledge chunks. The first
|
|
453
453
|
implementation stores vectors in SQLite as JSON rows in `chunk_embeddings` and
|
|
@@ -461,7 +461,7 @@ deterministic local vectors for tests and offline smoke checks.
|
|
|
461
461
|
|
|
462
462
|
### help
|
|
463
463
|
```bash
|
|
464
|
-
|
|
464
|
+
knowledge help [command]
|
|
465
465
|
```
|
|
466
466
|
|
|
467
467
|
## Global Options
|
|
@@ -487,7 +487,7 @@ location with `--store <path>`.
|
|
|
487
487
|
## MCP Server
|
|
488
488
|
|
|
489
489
|
```bash
|
|
490
|
-
|
|
490
|
+
knowledge-mcp
|
|
491
491
|
```
|
|
492
492
|
|
|
493
493
|
The stable agent-facing MCP tools are:
|
|
@@ -541,18 +541,18 @@ run ledgers, and citation evidence. They do not expose raw source bytes from
|
|
|
541
541
|
|
|
542
542
|
## Source And Artifact Boundary
|
|
543
543
|
|
|
544
|
-
Raw files should be stored and resolved through `open-files`. `
|
|
544
|
+
Raw files should be stored and resolved through `open-files`. `knowledge`
|
|
545
545
|
stores source references such as `open-files://file/<id>`,
|
|
546
546
|
`open-files://file/<id>/revision/<revision_id>`, `s3://...`, `file://...`,
|
|
547
547
|
and `https://...`, plus citations, chunks, generated wiki pages, indexes,
|
|
548
548
|
logs, runs, and search metadata.
|
|
549
549
|
|
|
550
|
-
`
|
|
550
|
+
`knowledge source resolve` and the MCP `ok_resolve_source` tool resolve
|
|
551
551
|
only the indexed, derived knowledge catalog. The resolver enforces read-only
|
|
552
552
|
purpose labels from source permissions, returns chunk citation evidence, writes
|
|
553
553
|
an audit event, and keeps bytes/storage credentials inside `open-files`.
|
|
554
554
|
|
|
555
|
-
`
|
|
555
|
+
`knowledge ingest source` can also build derived chunks from an allowed
|
|
556
556
|
source ref. It does not copy raw files into the knowledge workspace; local file,
|
|
557
557
|
S3, web, and open-files inputs are converted into redacted chunks with offsets,
|
|
558
558
|
hashes, revision metadata, and FTS rows.
|
|
@@ -568,14 +568,14 @@ store raw S3 or local-file bytes in the knowledge app, so a future hosted/S3
|
|
|
568
568
|
wrapper can move generated artifacts to object storage while source ownership
|
|
569
569
|
and immutable object identity stay in `open-files`.
|
|
570
570
|
|
|
571
|
-
AI provider configuration is local/BYOK by default. `
|
|
571
|
+
AI provider configuration is local/BYOK by default. `knowledge` declares
|
|
572
572
|
AI SDK v6 provider support through `ai`, `@ai-sdk/openai`,
|
|
573
573
|
`@ai-sdk/anthropic`, and `@ai-sdk/deepseek`, but does not call providers until a
|
|
574
574
|
prompt, embedding, or agent command explicitly requests a model.
|
|
575
575
|
|
|
576
576
|
Generated knowledge artifacts can be stored locally under
|
|
577
577
|
`.hasna/apps/knowledge/artifacts` or through the S3 artifact-store adapter.
|
|
578
|
-
For Hasna XYZ production, `
|
|
578
|
+
For Hasna XYZ production, `knowledge setup --mode hosted
|
|
579
579
|
--canonical-hasna-xyz --scope project --json` configures generated artifacts
|
|
580
580
|
under `s3://hasna-xyz-opensource-knowledge-prod/.hasna/apps/knowledge/` and
|
|
581
581
|
keeps `open-files` as the raw-source owner.
|
|
@@ -608,7 +608,7 @@ Every command returns structured JSON when `--json` is passed:
|
|
|
608
608
|
## MCP Server
|
|
609
609
|
|
|
610
610
|
```bash
|
|
611
|
-
|
|
611
|
+
knowledge-mcp
|
|
612
612
|
```
|
|
613
613
|
|
|
614
614
|
## HTTP mode
|
|
@@ -616,9 +616,9 @@ open-knowledge-mcp
|
|
|
616
616
|
Run a shared Streamable HTTP MCP server (127.0.0.1 only):
|
|
617
617
|
|
|
618
618
|
```bash
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
MCP_HTTP=1
|
|
619
|
+
knowledge-mcp --http # default port 8819
|
|
620
|
+
knowledge-mcp --http --port 8819
|
|
621
|
+
MCP_HTTP=1 knowledge-mcp
|
|
622
622
|
```
|
|
623
623
|
|
|
624
624
|
- Health: `GET http://127.0.0.1:8819/health`
|
|
@@ -13660,7 +13660,7 @@ import { existsSync as existsSync8, readFileSync as readFileSync8, writeFileSync
|
|
|
13660
13660
|
// package.json
|
|
13661
13661
|
var package_default = {
|
|
13662
13662
|
name: "@hasna/knowledge",
|
|
13663
|
-
version: "0.2.
|
|
13663
|
+
version: "0.2.29",
|
|
13664
13664
|
description: "Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions",
|
|
13665
13665
|
type: "module",
|
|
13666
13666
|
exports: {
|
|
@@ -13672,9 +13672,8 @@ var package_default = {
|
|
|
13672
13672
|
main: "./dist/index.js",
|
|
13673
13673
|
types: "./dist/index.d.ts",
|
|
13674
13674
|
bin: {
|
|
13675
|
-
knowledge: "bin/
|
|
13676
|
-
"
|
|
13677
|
-
"open-knowledge-mcp": "bin/open-knowledge-mcp.js"
|
|
13675
|
+
knowledge: "bin/knowledge.js",
|
|
13676
|
+
"knowledge-mcp": "bin/knowledge-mcp.js"
|
|
13678
13677
|
},
|
|
13679
13678
|
files: [
|
|
13680
13679
|
"bin",
|
|
@@ -13686,7 +13685,7 @@ var package_default = {
|
|
|
13686
13685
|
scripts: {
|
|
13687
13686
|
test: "bun test",
|
|
13688
13687
|
"test:cli": "bun test tests/cli.test.ts",
|
|
13689
|
-
build: "rm -rf dist && bun build --target=bun --outfile=bin/
|
|
13688
|
+
build: "rm -rf dist && bun build --target=bun --outfile=bin/knowledge.js --minify --external @aws-sdk/client-s3 --external @aws-sdk/credential-providers --external ai --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/deepseek src/cli.ts && bun build --target=bun --outfile=bin/knowledge-mcp.js --external @modelcontextprotocol/sdk --external @aws-sdk/client-s3 --external @aws-sdk/credential-providers --external ai --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/deepseek src/mcp.js && bun build ./src/index.ts --outdir ./dist --target bun --external @aws-sdk/client-s3 --external @aws-sdk/credential-providers --external ai --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/deepseek && bunx tsc -p tsconfig.build.json",
|
|
13690
13689
|
prepublishOnly: "bun run build"
|
|
13691
13690
|
},
|
|
13692
13691
|
keywords: [
|
|
@@ -18882,7 +18881,7 @@ function agentSchemaTemplate() {
|
|
|
18882
18881
|
## Source Rules
|
|
18883
18882
|
|
|
18884
18883
|
- Treat open-files source references as the preferred source of truth.
|
|
18885
|
-
- Do not copy raw source files into
|
|
18884
|
+
- Do not copy raw source files into knowledge.
|
|
18886
18885
|
- Cite every durable fact with a source URI, revision/hash when available, and optional span.
|
|
18887
18886
|
- Mark uncertainty explicitly when sources disagree or are incomplete.
|
|
18888
18887
|
|
|
@@ -19143,7 +19142,7 @@ class KnowledgeService {
|
|
|
19143
19142
|
artifact_uri_prefix: storage.artifact_store.uri_prefix,
|
|
19144
19143
|
canonical_hasna_xyz: storage.canonical_hasna_xyz,
|
|
19145
19144
|
config_path: workspace.configPath,
|
|
19146
|
-
next: mode === "hosted" ? ["
|
|
19145
|
+
next: mode === "hosted" ? ["knowledge auth login --api-key <key>", "knowledge storage status --json", "knowledge remote contracts --json"] : ["knowledge search <query>", "knowledge <prompt>"],
|
|
19147
19146
|
message: `Set knowledge mode to ${mode}`
|
|
19148
19147
|
};
|
|
19149
19148
|
}
|
|
@@ -19930,7 +19929,7 @@ function registerKnowledgeResources(server) {
|
|
|
19930
19929
|
}
|
|
19931
19930
|
function buildServer() {
|
|
19932
19931
|
const server = new McpServer({
|
|
19933
|
-
name: "
|
|
19932
|
+
name: "knowledge",
|
|
19934
19933
|
version: package_default.version
|
|
19935
19934
|
});
|
|
19936
19935
|
registerKnowledgeResources(server);
|
|
@@ -20674,7 +20673,7 @@ function buildServer() {
|
|
|
20674
20673
|
return server;
|
|
20675
20674
|
}
|
|
20676
20675
|
function printHelp() {
|
|
20677
|
-
console.error(`Usage:
|
|
20676
|
+
console.error(`Usage: knowledge-mcp [options]
|
|
20678
20677
|
|
|
20679
20678
|
Runs the @hasna/knowledge MCP server (stdio by default).
|
|
20680
20679
|
|
|
@@ -20700,7 +20699,7 @@ async function main() {
|
|
|
20700
20699
|
const server = buildServer();
|
|
20701
20700
|
const transport = new StdioServerTransport;
|
|
20702
20701
|
await server.connect(transport);
|
|
20703
|
-
console.error("
|
|
20702
|
+
console.error("knowledge MCP server running on stdio");
|
|
20704
20703
|
}
|
|
20705
20704
|
if (import.meta.main) {
|
|
20706
20705
|
main().catch((err) => {
|