daftari 2.0.0 → 3.0.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/CHANGELOG.md +14 -0
- package/README.md +465 -366
- package/dist/backfill/derive.d.ts.map +1 -1
- package/dist/backfill/derive.js +1 -0
- package/dist/backfill/derive.js.map +1 -1
- package/dist/court/index.d.ts.map +1 -1
- package/dist/court/index.js +48 -0
- package/dist/court/index.js.map +1 -1
- package/dist/court/triage.d.ts +5 -0
- package/dist/court/triage.d.ts.map +1 -0
- package/dist/court/triage.js +71 -0
- package/dist/court/triage.js.map +1 -0
- package/dist/curation/lint-voice.js +1 -1
- package/dist/curation/lint-voice.js.map +1 -1
- package/dist/curation/lint.d.ts +1 -1
- package/dist/curation/lint.d.ts.map +1 -1
- package/dist/curation/lint.js +5 -5
- package/dist/curation/lint.js.map +1 -1
- package/dist/curation/read-heat.d.ts +16 -0
- package/dist/curation/read-heat.d.ts.map +1 -0
- package/dist/curation/read-heat.js +52 -0
- package/dist/curation/read-heat.js.map +1 -0
- package/dist/curation/structural.d.ts +1 -1
- package/dist/curation/structural.d.ts.map +1 -1
- package/dist/curation/structural.js +8 -7
- package/dist/curation/structural.js.map +1 -1
- package/dist/curation/tension-triage.d.ts +57 -0
- package/dist/curation/tension-triage.d.ts.map +1 -0
- package/dist/curation/tension-triage.js +155 -0
- package/dist/curation/tension-triage.js.map +1 -0
- package/dist/frontmatter/schema.d.ts.map +1 -1
- package/dist/frontmatter/schema.js +2 -1
- package/dist/frontmatter/schema.js.map +1 -1
- package/dist/frontmatter/types.d.ts +4 -1
- package/dist/frontmatter/types.d.ts.map +1 -1
- package/dist/frontmatter/types.js +6 -0
- package/dist/frontmatter/types.js.map +1 -1
- package/dist/search/hybrid.d.ts +1 -1
- package/dist/search/hybrid.d.ts.map +1 -1
- package/dist/sleep/cycle.d.ts.map +1 -1
- package/dist/sleep/cycle.js +27 -11
- package/dist/sleep/cycle.js.map +1 -1
- package/dist/tools/curation.d.ts +2 -0
- package/dist/tools/curation.d.ts.map +1 -1
- package/dist/tools/curation.js +141 -0
- package/dist/tools/curation.js.map +1 -1
- package/dist/tools/read.js +4 -4
- package/dist/tools/read.js.map +1 -1
- package/dist/tools/search.js +3 -3
- package/dist/tools/search.js.map +1 -1
- package/dist/tools/write.d.ts +7 -0
- package/dist/tools/write.d.ts.map +1 -1
- package/dist/tools/write.js +67 -6
- package/dist/tools/write.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -14,6 +14,20 @@ Daftari is the **long-term memory cortex for your LLM agents** — a persistent,
|
|
|
14
14
|
structured vault they read, write, and curate over time, **portable across any
|
|
15
15
|
model.** A cortex, not a clipboard.
|
|
16
16
|
|
|
17
|
+
## Contents
|
|
18
|
+
|
|
19
|
+
**Why Daftari** — [Rent the brain, own the memory](#rent-the-brain-own-the-memory) · [Not a second brain](#not-a-second-brain) · [It remembers, it doesn't resolve](#it-remembers--it-doesnt-resolve-for-you) · [How it compares](#how-it-compares)
|
|
20
|
+
|
|
21
|
+
**Concepts** — [What it is](#what-it-is) · [The four layers](#the-four-layers) · [Two kinds of knowledge](#two-kinds-of-knowledge) · [File format](#file-format)
|
|
22
|
+
|
|
23
|
+
**The rituals** — [The tools](#the-tools) · [Circadian memory](#circadian-memory) · [Tension Court](#tension-court) · [The principal interview](#the-principal-interview) · [Belief archaeology](#belief-archaeology) · [The vault as witness](#the-vault-as-witness--and-the-wager-layer) · [Coherence audit](#coherence-audit)
|
|
24
|
+
|
|
25
|
+
**Running it** — [Access control](#access-control) · [Server mode](#server-mode-self-hosted) · [Storage backing](#storage-backing) · [Adopting a vault + OKF](#adopting-an-existing-vault)
|
|
26
|
+
|
|
27
|
+
**Reference** — [What's not in v1](#whats-not-in-v1) · [Development](#development) · [Documentation](#documentation) · [Integrations](#integrations) · [Privacy](#privacy) · [License](#license)
|
|
28
|
+
|
|
29
|
+
<!-- Why Daftari -->
|
|
30
|
+
|
|
17
31
|
## Rent the brain, own the memory
|
|
18
32
|
|
|
19
33
|
LLMs are stateless; they forget. So memory is being bolted on everywhere — but
|
|
@@ -54,9 +68,46 @@ It resolves only by discovery — a real edge — never by invention. The agent
|
|
|
54
68
|
compiles; the vault preserves; *you* keep the judgment. See
|
|
55
69
|
[the manifesto](docs/manifesto.md) for the full argument.
|
|
56
70
|
|
|
71
|
+
```mermaid
|
|
72
|
+
flowchart TD
|
|
73
|
+
A[Two docs disagree] --> B{Is there a real edge?<br/>source / supersession link}
|
|
74
|
+
B -- yes --> C[Supersede: one current,<br/>lineage preserved]
|
|
75
|
+
B -- no --> D[Tension: both held open, live]
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## How it compares
|
|
79
|
+
|
|
80
|
+
The real question a memory layer has to answer: **what happens when two facts
|
|
81
|
+
contradict?**
|
|
82
|
+
|
|
83
|
+
| What happens to a contradiction? | Systems |
|
|
84
|
+
|---|---|
|
|
85
|
+
| Invisible | AGENTS.md, RAG |
|
|
86
|
+
| Synthesis-overwrite (association only) | Mem0 (OSS), ChatGPT / Claude memory, Glean |
|
|
87
|
+
| New wins, old tagged-invalid | Zep / Graphiti, Sentra |
|
|
88
|
+
| Resolved by graph / majority-vote | Cognee, ElephantBroker |
|
|
89
|
+
| **Held open, live & queryable** | **Daftari** |
|
|
90
|
+
|
|
91
|
+
And the honest cost, since compounding isn't free:
|
|
92
|
+
|
|
93
|
+
| Who has to do the curation work? | |
|
|
94
|
+
|---|---|
|
|
95
|
+
| RAG | Nobody — retrieval only, zero authoring cost |
|
|
96
|
+
| AGENTS.md | One file, hand-maintained |
|
|
97
|
+
| **Daftari** | **An agent (or human) curates — the heaviest of the three, and the reason knowledge compounds** |
|
|
98
|
+
|
|
99
|
+
> The nearest formal prior art is **TOKI** ([arXiv 2606.06240](https://arxiv.org/abs/2606.06240),
|
|
100
|
+
> with a [reference implementation](https://github.com/ZenAlexa/toki-bitemporal-memory)):
|
|
101
|
+
> a bitemporal operator algebra whose opt-in `await-confirmation` operator can hold a
|
|
102
|
+
> contradiction open. The line: TOKI resolves at write time (hold-open is one of four
|
|
103
|
+
> operators) and keeps the loser in an *archival* audit row; Daftari makes non-resolution
|
|
104
|
+
> the *default* and keeps both facts *live and queryable* in retrieval.
|
|
105
|
+
|
|
106
|
+
<!-- Concepts -->
|
|
107
|
+
|
|
57
108
|
## What it is
|
|
58
109
|
|
|
59
|
-
A directory of markdown files with YAML frontmatter, exposed to agents as
|
|
110
|
+
A directory of markdown files with YAML frontmatter, exposed to agents as 35
|
|
60
111
|
MCP tools over stdio. The vault is plain text: you can read it in any editor,
|
|
61
112
|
`git log` it, grep it. Daftari adds the machinery agents need to treat it as a
|
|
62
113
|
shared workspace.
|
|
@@ -82,6 +133,84 @@ layers 3 and 4.
|
|
|
82
133
|
|**Write arbitration**|File-level locks (60s TTL), auto-commit to git, structured provenance log. |Concurrent agents write safely. Every mutation is attributable. |
|
|
83
134
|
|**Curation** |Draft-to-canonical lifecycle, TTL-based staleness, tension logging, advisory linter. |Knowledge that stops being true gets surfaced, not silently trusted. |
|
|
84
135
|
|
|
136
|
+
## Two kinds of knowledge
|
|
137
|
+
|
|
138
|
+
Every document declares a `domain`. The distinction drives how the curation
|
|
139
|
+
layer treats it.
|
|
140
|
+
|
|
141
|
+
**Accumulation** documents compile and compound. A competitive-intel note, a
|
|
142
|
+
pricing breakdown, a researched comparison. Each write builds on the last.
|
|
143
|
+
Going stale is a problem to fix.
|
|
144
|
+
|
|
145
|
+
**Generative** documents speculate. A moonshot sketch, a brainstorm, a “what
|
|
146
|
+
if.” Going stale is expected, not a defect.
|
|
147
|
+
|
|
148
|
+
Applied uniformly, the same curation rules would either nag about every
|
|
149
|
+
brainstorm or wave through every stale fact. The domain split lets the system
|
|
150
|
+
hold each to the right standard.
|
|
151
|
+
|
|
152
|
+
## File format
|
|
153
|
+
|
|
154
|
+
Markdown with YAML frontmatter. Frontmatter is the metadata layer; there is no
|
|
155
|
+
separate database.
|
|
156
|
+
|
|
157
|
+
```yaml
|
|
158
|
+
---
|
|
159
|
+
title: "Aurora Pipelines — Positioning Overview"
|
|
160
|
+
domain: accumulation
|
|
161
|
+
collection: competitive-intel
|
|
162
|
+
status: canonical
|
|
163
|
+
confidence: medium
|
|
164
|
+
created: 2026-05-17
|
|
165
|
+
updated: 2026-05-17
|
|
166
|
+
updated_by: agent:claude-code
|
|
167
|
+
provenance: synthesized
|
|
168
|
+
sources:
|
|
169
|
+
- aurora-product-page
|
|
170
|
+
ttl_days: 120
|
|
171
|
+
valid_from: 2026-05-01
|
|
172
|
+
valid_until: null
|
|
173
|
+
tags: [aurora, ingestion, competitive]
|
|
174
|
+
questions_answered:
|
|
175
|
+
- "How does Aurora frame the ingestion/transformation boundary?"
|
|
176
|
+
questions_raised:
|
|
177
|
+
- "Does an authored-pipeline model slow teams down at small scale?"
|
|
178
|
+
---
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Documents can make their epistemic edges explicit: `questions_answered` is what
|
|
182
|
+
later agents can take as settled, `questions_raised` is where to build next.
|
|
183
|
+
`vault_lint` turns the open questions across the vault into a coverage map.
|
|
184
|
+
|
|
185
|
+
`valid_from` / `valid_until` are the second temporal axis. Everything else in
|
|
186
|
+
the file records **transaction time** — when the vault came to believe
|
|
187
|
+
something; these record **valid time** — when the claim was true in the world. A
|
|
188
|
+
document edited this morning can describe a price that stopped applying in
|
|
189
|
+
March, and only the second axis can tell you so. That makes supersession
|
|
190
|
+
checkable rather than merely asserted:
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
daftari asof 2026-04-01 --valid 2026-01-15
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
"On April 1st, what did the vault believe was true on January 15th?"
|
|
197
|
+
|
|
198
|
+
<details>
|
|
199
|
+
<summary><b>Half-open valid-time intervals and the authoring rules (▸ expand for full reference)</b></summary>
|
|
200
|
+
|
|
201
|
+
The window is half-open — `[valid_from, valid_until)` — so `valid_until` is the
|
|
202
|
+
first day the claim no longer held, and a successor's `valid_from` is exactly
|
|
203
|
+
its predecessor's `valid_until`. Handoffs share no day and leave no gap. The
|
|
204
|
+
fields are optional and always authored: nothing derives them from git dates or
|
|
205
|
+
mtime, because that would manufacture a claim nobody made. Both null means
|
|
206
|
+
unknown, which is never read as "always true".
|
|
207
|
+
|
|
208
|
+
Full field reference in <docs/file-format.md>.
|
|
209
|
+
|
|
210
|
+
</details>
|
|
211
|
+
|
|
212
|
+
<!-- The rituals -->
|
|
213
|
+
|
|
85
214
|
## The tools
|
|
86
215
|
|
|
87
216
|
**Read:** `vault_read`, `vault_index`, `vault_status`
|
|
@@ -108,21 +237,30 @@ open exposure, contested claims with stake at risk, the settled book
|
|
|
108
237
|
deterministic; includes the flat-curve monitor so a single-author vault is
|
|
109
238
|
reported as uninformative rather than as signal.
|
|
110
239
|
|
|
240
|
+
<details>
|
|
241
|
+
<summary><b>The full per-category tool registry and the tool-tier config (▸ expand for full reference)</b></summary>
|
|
242
|
+
|
|
111
243
|
**Search:** `vault_search` (hybrid BM25 + vector; hits carry their unresolved
|
|
112
244
|
tensions inline and foreground the current source of superseded documents),
|
|
113
245
|
`vault_search_related`, `vault_themes` (thematic clustering), `vault_reindex`
|
|
114
246
|
|
|
115
|
-
**Write:** `vault_write`, `vault_append`, `vault_promote`, `vault_deprecate`, `vault_supersede`, `vault_merge`, `vault_set_confidence`
|
|
247
|
+
**Write:** `vault_write`, `vault_append`, `vault_promote`, `vault_deprecate`, `vault_supersede`, `vault_merge`, `vault_set_confidence`, `vault_set_tier`
|
|
248
|
+
|
|
249
|
+
**Curate:** `vault_tension_log`, `vault_tension_resolve`, `vault_tension_clusters`, `vault_tension_blast`, `vault_tension_triage` (the unranked triage card / `court --triage`), `vault_lint`, `vault_provenance`, `vault_staleness` (edge-staleness: pending upstream changes / broken-read rate)
|
|
116
250
|
|
|
117
|
-
**
|
|
251
|
+
**Edges:** `vault_edge_observe`, `vault_edge_contest`, `vault_edges`, `vault_consumes` (query the compiled dependency graph)
|
|
118
252
|
|
|
119
|
-
**
|
|
253
|
+
**Dispatch:** `vault_tier1` (type-directed change dispatch), `vault_tier2_queue`, `vault_tier2_verdict` (semantic-review queue + verdict)
|
|
120
254
|
|
|
121
255
|
**Ratify:** `vault_stage_action`, `vault_ratify`
|
|
122
256
|
|
|
123
257
|
The curation engine is advisory: `vault_lint` reports problems and
|
|
124
258
|
`vault_tension_log` records contradictions. Neither auto-fixes anything. Every
|
|
125
|
-
change is a deliberate, attributable act.
|
|
259
|
+
change is a deliberate, attributable act. Retraction is surfaced, not enforced:
|
|
260
|
+
the `retiredStillLinked` lint check / `retired_still_linked` read-time advisory
|
|
261
|
+
flags canonical docs still citing a deprecated or superseded source, and
|
|
262
|
+
`vault_deprecate`/`vault_supersede` return a `dependents` advisory (the
|
|
263
|
+
downstream blast) at retraction time.
|
|
126
264
|
|
|
127
265
|
### Tool tiers
|
|
128
266
|
|
|
@@ -142,314 +280,157 @@ tools:
|
|
|
142
280
|
`core` is the search-before-derive loop (`vault_search`, `vault_read`,
|
|
143
281
|
`vault_write`, `vault_index`, `vault_lint`, `vault_status`); `standard` adds
|
|
144
282
|
the full document lifecycle (append/promote/deprecate/supersede/merge,
|
|
145
|
-
confidence and tier setters, propose/ratify) plus
|
|
146
|
-
everything. `--tools <tier>` overrides the tier for one invocation. Filtering
|
|
283
|
+
confidence and tier setters, propose/ratify) plus `vault_search_related`,
|
|
284
|
+
`vault_provenance`, and diagnostics; `full` is everything. `--tools <tier>` overrides the tier for one invocation. Filtering
|
|
147
285
|
only changes what is *advertised* — calls to any registered tool still work,
|
|
148
286
|
so an agent holding a cached tool name keeps working across a tier change.
|
|
149
287
|
Unknown names in `include`/`exclude` warn at startup and are ignored, so a
|
|
150
288
|
config written for a newer daftari still loads.
|
|
151
289
|
|
|
290
|
+
</details>
|
|
291
|
+
|
|
152
292
|
**Evaluate (opt-in, requires an Anthropic API key):** `daftari eval` — scores how
|
|
153
293
|
well an LLM can use the curation surface to answer multi-hop questions about the
|
|
154
294
|
vault. See the [design spec](docs/superpowers/specs/2026-05-31-cortex-quality-metric-design.md)
|
|
155
295
|
for the rationale and the cortex framing.
|
|
156
296
|
|
|
157
|
-
##
|
|
158
|
-
|
|
159
|
-
Every document declares a `domain`. The distinction drives how the curation
|
|
160
|
-
layer treats it.
|
|
297
|
+
## Circadian memory
|
|
161
298
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
Going stale is a problem to fix.
|
|
299
|
+
The vault sleeps. `daftari sleep` is the nightly metabolic pass — deterministic,
|
|
300
|
+
LLM-free, write-free (documents are never touched):
|
|
165
301
|
|
|
166
|
-
|
|
167
|
-
|
|
302
|
+
```bash
|
|
303
|
+
# In cron (any scheduler works; daftari ships the cycle, not a daemon):
|
|
304
|
+
0 3 * * * cd /path/to/vault && npx daftari sleep --output .daftari/morning-report.md
|
|
305
|
+
```
|
|
168
306
|
|
|
169
|
-
The
|
|
170
|
-
|
|
171
|
-
|
|
307
|
+
The cycle sweeps expired staged actions, scores every document's decay, and
|
|
308
|
+
builds the **wake list**: canonical accumulation documents past their TTL
|
|
309
|
+
with downstream dependents, ranked by blast radius. The list is written to
|
|
310
|
+
`.daftari/wake-queue.jsonl` for an external agent to consume — re-verify each
|
|
311
|
+
document against its sources, stage the diff — because the vault never
|
|
312
|
+
re-verifies on its own. Generative documents going stale are expected, not a
|
|
313
|
+
defect: counted, never woken.
|
|
172
314
|
|
|
173
|
-
|
|
315
|
+
The **Morning Report** ends where the human begins: tension aging and the
|
|
316
|
+
court docket head, the ratification queue with soon-to-expire proposals, and
|
|
317
|
+
the rubber-stamp monitor — zero rejections over a long decision history is
|
|
318
|
+
printed as a warning, not a compliment. The agent proposes overnight; you
|
|
319
|
+
ratify over coffee.
|
|
174
320
|
|
|
175
|
-
|
|
321
|
+
## Tension Court
|
|
176
322
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
read: ["*"]
|
|
184
|
-
write: [moonshot, _drafts]
|
|
185
|
-
admin:
|
|
186
|
-
read: ["*"]
|
|
187
|
-
write: ["*"]
|
|
188
|
-
promote: true
|
|
189
|
-
ratify: true # may approve/reject staged actions and contest edges
|
|
190
|
-
```
|
|
323
|
+
Tensions wait in a log; the court turns them into decidable cases. `daftari
|
|
324
|
+
court` compiles a **docket** — every open tension briefed and ranked (stale
|
|
325
|
+
first, then by blast radius): both sides' claims, the present state of their
|
|
326
|
+
documents, the downstream stakes, cluster membership, and **precedents** —
|
|
327
|
+
past rulings on disputes that shared a document, a collection pair, or a
|
|
328
|
+
kind.
|
|
191
329
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
330
|
+
The **triage card** (`daftari court --triage` / `vault_tension_triage`) is the
|
|
331
|
+
deliberately **unranked**, cluster-grouped companion view — legibility, not a
|
|
332
|
+
severity score. Each contested side surfaces `criticality`, `provenance`, and
|
|
333
|
+
`updated_by`, so a resolver can judge trust without opening the documents.
|
|
195
334
|
|
|
196
|
-
|
|
335
|
+
```bash
|
|
336
|
+
# The docket — a 5-minute weekly ritual
|
|
337
|
+
daftari court --vault ./my-vault
|
|
197
338
|
|
|
198
|
-
|
|
199
|
-
|
|
339
|
+
# One case's full brief (verbatim rationales from cited precedents)
|
|
340
|
+
daftari court --tension tension-abc123
|
|
200
341
|
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
domain: accumulation
|
|
205
|
-
collection: competitive-intel
|
|
206
|
-
status: canonical
|
|
207
|
-
confidence: medium
|
|
208
|
-
created: 2026-05-17
|
|
209
|
-
updated: 2026-05-17
|
|
210
|
-
updated_by: agent:claude-code
|
|
211
|
-
provenance: synthesized
|
|
212
|
-
sources:
|
|
213
|
-
- aurora-product-page
|
|
214
|
-
ttl_days: 120
|
|
215
|
-
valid_from: 2026-05-01
|
|
216
|
-
valid_until: null
|
|
217
|
-
tags: [aurora, ingestion, competitive]
|
|
218
|
-
questions_answered:
|
|
219
|
-
- "How does Aurora frame the ingestion/transformation boundary?"
|
|
220
|
-
questions_raised:
|
|
221
|
-
- "Does an authored-pipeline model slow teams down at small scale?"
|
|
222
|
-
---
|
|
342
|
+
# Rule. The rationale is recorded verbatim and cited by future dockets.
|
|
343
|
+
daftari court rule tension-abc123 --kind corrected \
|
|
344
|
+
--rationale "Vendor pricing page confirmed the entry tier on 2026-07-10."
|
|
223
345
|
```
|
|
224
346
|
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
something. These record **valid time**: when the claim was true in the world. A
|
|
232
|
-
document edited this morning can describe a price that stopped applying in
|
|
233
|
-
March, and only the second axis can tell you so.
|
|
347
|
+
Rulings go through the same `resolveTension` write path as
|
|
348
|
+
`vault_tension_resolve` — a ruling records the closure, it never edits the
|
|
349
|
+
disputed documents. Precedent retrieval is deterministic (shared-document >
|
|
350
|
+
collection-pair > same-kind; no LLM): the court retrieves how this house has
|
|
351
|
+
resolved similar disputes before, and whether a precedent applies stays the
|
|
352
|
+
human's judgment. Memory grows case law.
|
|
234
353
|
|
|
235
|
-
The
|
|
236
|
-
first day the claim no longer held, and a successor's `valid_from` is exactly
|
|
237
|
-
its predecessor's `valid_until`. Handoffs share no day and leave no gap. The
|
|
238
|
-
fields are optional and always authored: nothing derives them from git dates or
|
|
239
|
-
mtime, because that would manufacture a claim nobody made. Both null means
|
|
240
|
-
unknown, which is never read as "always true".
|
|
354
|
+
## The principal interview
|
|
241
355
|
|
|
242
|
-
|
|
356
|
+
The vault interrogates you. `daftari interview` assembles a question sheet
|
|
357
|
+
from what the vault already knows is unclear — open tensions (contested
|
|
358
|
+
first, longest-carried first), canonical accumulation docs past their TTL,
|
|
359
|
+
and `questions_raised` entries no document answers — deterministic and
|
|
360
|
+
LLM-free, like the circadian pass:
|
|
243
361
|
|
|
244
362
|
```bash
|
|
245
|
-
|
|
363
|
+
# The sheet — read-only, priority-ordered
|
|
364
|
+
daftari interview --vault ./my-vault
|
|
365
|
+
|
|
366
|
+
# Sit for it. Answers are recorded VERBATIM; empty skips, 'q' ends.
|
|
367
|
+
daftari interview ask --vault ./my-vault
|
|
246
368
|
```
|
|
247
369
|
|
|
248
|
-
|
|
370
|
+
Answered questions become a transcript document in an `interviews/`
|
|
371
|
+
collection — `tier: source` (your words, body immutable), `provenance:
|
|
372
|
+
direct`, no TTL (testimony doesn't expire) — committed like any other write,
|
|
373
|
+
with `sources` tracing each question back to the tension or document that
|
|
374
|
+
prompted it. The pattern is the companion interview on a living-summary
|
|
375
|
+
page: the compiler's highest-value move is not more compilation, it is
|
|
376
|
+
asking the principal about the unclear spots and folding the verbatim
|
|
377
|
+
answers back into the corpus.
|
|
249
378
|
|
|
250
|
-
|
|
379
|
+
Recording testimony resolves nothing. The transcript is *evidence*: the CLI
|
|
380
|
+
ends by pointing at `daftari court rule <id> --references <transcript>` for
|
|
381
|
+
tensions it touched, and at re-verified writes for stale docs. Operator-only,
|
|
382
|
+
like the court — no MCP tool, no access context.
|
|
251
383
|
|
|
252
|
-
##
|
|
384
|
+
## Belief archaeology
|
|
253
385
|
|
|
254
|
-
|
|
255
|
-
|
|
386
|
+
Git is the version layer, so the vault can answer **"what did we believe on
|
|
387
|
+
March 3?"** `daftari asof` is a read-only report over the repo's history — no
|
|
388
|
+
checkout, no index, no API key:
|
|
256
389
|
|
|
257
390
|
```bash
|
|
258
|
-
#
|
|
259
|
-
daftari
|
|
260
|
-
|
|
261
|
-
# Adopt one folder at a time (per-folder ratification; --yes to skip the prompt)
|
|
262
|
-
daftari import obsidian ~/my-vault --apply --scope notes
|
|
263
|
-
```
|
|
264
|
-
|
|
265
|
-
The import is non-destructive to your content. It fills only the *missing*
|
|
266
|
-
Daftari frontmatter — collection from the folder, dates from git history (or file
|
|
267
|
-
mtime), sensible defaults for the rest — and preserves everything you already
|
|
268
|
-
had, including custom frontmatter fields. Obsidian specifics: inline `#tags` are
|
|
269
|
-
merged into `tags`, a Web Clipper `source` is mapped into `sources`, and
|
|
270
|
-
`[[wikilinks]]` are left untouched (Daftari resolves them as written). Filling
|
|
271
|
-
frontmatter is deliberate, not automatic — re-run the import to pick up newly
|
|
272
|
-
added notes.
|
|
391
|
+
# The vault's belief state at a date (or any git ref), plus the drift since
|
|
392
|
+
daftari asof 2026-03-03 --vault ./my-vault
|
|
273
393
|
|
|
274
|
-
|
|
394
|
+
# One document's trajectory: frontmatter then vs now, commits in between
|
|
395
|
+
daftari asof HEAD~20 --doc pricing/helios-consumption-pricing.md
|
|
275
396
|
|
|
276
|
-
|
|
277
|
-
|
|
397
|
+
# Counterfactual replay: this fact turned out wrong — who had inherited it
|
|
398
|
+
# at the time, and where are they now?
|
|
399
|
+
daftari asof 2026-03-03 --blast pricing/helios-consumption-pricing.md
|
|
400
|
+
```
|
|
278
401
|
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
directly in config to apply the same to any vault. History is per-device; your
|
|
289
|
-
notes still sync everywhere.
|
|
290
|
-
|
|
291
|
-
### Lower-level: `backfill`
|
|
292
|
-
|
|
293
|
-
`daftari import obsidian` is a thin, Obsidian-aware wrapper over `daftari
|
|
294
|
-
backfill` — the git-driven frontmatter migration that works on any markdown wiki.
|
|
295
|
-
Use it directly for non-Obsidian trees:
|
|
296
|
-
|
|
297
|
-
```bash
|
|
298
|
-
daftari backfill --plan
|
|
299
|
-
daftari backfill --apply --scope specs
|
|
300
|
-
```
|
|
301
|
-
|
|
302
|
-
## Open Knowledge Format (OKF)
|
|
303
|
-
|
|
304
|
-
[OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/)
|
|
305
|
-
is Google Cloud's vendor-neutral spec for the LLM-wiki pattern: a directory of
|
|
306
|
-
markdown files with YAML frontmatter that any producer can emit and any consumer
|
|
307
|
-
can read without translation. A Daftari vault *is* that pattern, so `daftari
|
|
308
|
-
okf` bridges the two directions.
|
|
309
|
-
[v0.2](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals/)
|
|
310
|
-
adds opt-in **trust signals** — raw credibility indicators (provenance,
|
|
311
|
-
verification, lifecycle, freshness), never computed scores — and Daftari maps
|
|
312
|
-
them from/to its native metadata.
|
|
313
|
-
|
|
314
|
-
**Export** renders the vault as a portable OKF bundle — every doc becomes an OKF
|
|
315
|
-
concept doc (the core `type` / `title` / `description` / `resource` / `tags`
|
|
316
|
-
fields, plus a verbatim `daftari` sidecar for lossless round-trip), with
|
|
317
|
-
generated `index.md` (progressive-disclosure listing) and `log.md`
|
|
318
|
-
(chronological history). Trust signals derive from native metadata:
|
|
319
|
-
`updated`/`updated_by` become `generated`, the lifecycle maps to
|
|
320
|
-
`draft`/`stable`/`deprecated`, `ttl_days` becomes an absolute `stale_after`
|
|
321
|
-
date, and `sources` become structured entries. `verified` is never fabricated —
|
|
322
|
-
Daftari records authorship, not independent confirmations, so exported docs
|
|
323
|
-
honestly read as unverified. The source vault is never mutated.
|
|
324
|
-
|
|
325
|
-
```bash
|
|
326
|
-
daftari okf export ./my-vault --out ./okf-bundle
|
|
327
|
-
daftari okf export ./my-vault --out ./okf-bundle --collection pricing
|
|
328
|
-
```
|
|
329
|
-
|
|
330
|
-
**Import** adopts an OKF bundle into a vault. A bundle produced by `okf export`
|
|
331
|
-
round-trips exactly via its sidecar; a foreign bundle is mapped conservatively
|
|
332
|
-
(docs land as `draft` in the `accumulation` domain, the original OKF `type` is
|
|
333
|
-
preserved in an `okf_type` field). Trust signals inform the mapping: a
|
|
334
|
-
human-reviewed doc (a `human:*` entry in `verified`) imports with `confidence:
|
|
335
|
-
high`, `status: deprecated` stays `deprecated` (retired knowledge must not
|
|
336
|
-
resurface as a fresh draft), and `stale_after` converts to `ttl_days`. An
|
|
337
|
-
`Attested Computation` is surfaced in an import warning but **not**
|
|
338
|
-
auto-write-protected: `tier: source` is enforcement, and its only sanctioned
|
|
339
|
-
grant path is `vault_set_tier` (reason required, provenance-logged) — a foreign
|
|
340
|
-
bundle's self-declared `type` doesn't buy it. Review the doc, then elevate
|
|
341
|
-
deliberately. OKF fields with no lossless Daftari slot (the trust record,
|
|
342
|
-
attestation machinery) are preserved under `okf_*` keys. Writes auto-commit and
|
|
343
|
-
the index is rebuilt.
|
|
344
|
-
|
|
345
|
-
```bash
|
|
346
|
-
daftari okf import ./okf-bundle --into ./my-vault --dry-run
|
|
347
|
-
daftari okf import ./okf-bundle --into ./my-vault
|
|
348
|
-
```
|
|
349
|
-
|
|
350
|
-
## Server mode (self-hosted)
|
|
351
|
-
|
|
352
|
-
By default daftari is a per-user stdio process. `daftari serve` starts the
|
|
353
|
-
same vault as **one always-on instance over Streamable HTTP** — for a team, or
|
|
354
|
-
for clients that can't spawn a local process (claude.ai web/mobile, Cowork):
|
|
355
|
-
|
|
356
|
-
```bash
|
|
357
|
-
daftari serve --vault ./my-vault # http://127.0.0.1:8787/mcp
|
|
358
|
-
daftari serve --vault ./my-vault --bind 0.0.0.0 --port 9000
|
|
359
|
-
```
|
|
360
|
-
|
|
361
|
-
Identity is **per MCP session**, resolved when the session opens, so every
|
|
362
|
-
RBAC and existence-disclosure rule applies per connection with zero tool
|
|
363
|
-
changes. Two composable auth schemes, both declared in config:
|
|
364
|
-
|
|
365
|
-
```yaml
|
|
366
|
-
server:
|
|
367
|
-
transport_security: external # required off-loopback: TLS terminates upstream
|
|
368
|
-
auth:
|
|
369
|
-
tokens: # static bearer tokens (agents, ETL)
|
|
370
|
-
- env: DAFTARI_TOKEN_ETL # the VALUE lives in this env var, never in config
|
|
371
|
-
user: agent:etl
|
|
372
|
-
role: admin
|
|
373
|
-
oauth: # OAuth 2.1 resource server (humans via your IdP)
|
|
374
|
-
issuer: https://idp.example.com
|
|
375
|
-
audience: daftari
|
|
376
|
-
jwks_uri: https://idp.example.com/.well-known/jwks.json
|
|
377
|
-
subjects:
|
|
378
|
-
"alice@example.com": { user: human:alice, role: analyst }
|
|
379
|
-
```
|
|
380
|
-
|
|
381
|
-
The posture is fail-loud, never silent-downgrade: a non-loopback bind refuses
|
|
382
|
-
to start without auth **and** the explicit `transport_security: external`
|
|
383
|
-
acknowledgment (daftari never terminates TLS itself — put Caddy/nginx/a load
|
|
384
|
-
balancer in front); with any auth configured, a bad or missing credential is
|
|
385
|
-
a 401 at session open and a valid JWT whose subject isn't mapped is a 403 —
|
|
386
|
-
neither ever becomes the guest. Guest sessions exist only in the no-auth
|
|
387
|
-
loopback configuration. A running server also refuses to be silently killed:
|
|
388
|
-
stray stdio invocations against the same vault refuse to start, and replacing
|
|
389
|
-
a live holder requires a deliberate `daftari serve --takeover`.
|
|
390
|
-
|
|
391
|
-
## Storage backing
|
|
392
|
-
|
|
393
|
-
A self-hosted vault can push to durable object storage (#6). The local git
|
|
394
|
-
working copy stays canonical — reads, writes, auto-commits, locks, and the
|
|
395
|
-
index all stay exactly as above — and the backing is a dumb sync target:
|
|
396
|
-
|
|
397
|
-
```yaml
|
|
398
|
-
# .daftari/config.yaml
|
|
399
|
-
storage:
|
|
400
|
-
backend: s3 # fs | s3 | azure
|
|
401
|
-
bucket: team-vault
|
|
402
|
-
region: us-east-1
|
|
403
|
-
# endpoint: https://… # MinIO / R2 / GCS S3-interop endpoints
|
|
404
|
-
# sync_interval_minutes: 15 # daftari serve pushes on this cadence
|
|
405
|
-
```
|
|
406
|
-
|
|
407
|
-
```bash
|
|
408
|
-
daftari sync --vault ./my-vault # incremental push
|
|
409
|
-
daftari sync --vault ./my-vault --dry-run # show the diff only
|
|
410
|
-
daftari sync --vault ./empty-dir --restore --backend s3 --bucket team-vault
|
|
411
|
-
```
|
|
412
|
-
|
|
413
|
-
The push covers the markdown tree, the `.git` directory, and durable
|
|
414
|
-
`.daftari` journals; the rebuildable SQLite index and lock files never sync.
|
|
415
|
-
Neither do `.git/config` and `.git/hooks` — git *executes* what those
|
|
416
|
-
declare, and a backup channel must not deliver code (`git clone` refuses to
|
|
417
|
-
transmit them for the same reason), so re-add remotes and local git config
|
|
418
|
-
by hand after a restore.
|
|
419
|
-
Cloud backends load their SDKs (`@aws-sdk/client-s3`, `@azure/storage-blob`)
|
|
420
|
-
as optional dependencies — install the one you use; credentials come from the
|
|
421
|
-
SDK's standard environment chain, never from vault config. GCS is reached via
|
|
422
|
-
its S3-interoperability endpoint. Restore refuses non-empty directories and
|
|
423
|
-
reindexes when done.
|
|
424
|
-
|
|
425
|
-
## How it compares
|
|
426
|
-
|
|
427
|
-
| |AGENTS.md |RAG |Daftari |
|
|
428
|
-
|--------------------|-----------------|-----------------------------|-------------------------------------|
|
|
429
|
-
|Who writes? |Humans |Nobody (retrieval only) |Agents + humans |
|
|
430
|
-
|Scales? |One file, doesn’t|Scales storage, not coherence|Structured collections with lifecycle|
|
|
431
|
-
|Knowledge compounds?|No |No |Yes, draft → canonical → deprecated |
|
|
432
|
-
|Contradictions? |Invisible |Invisible |Tension log surfaces them |
|
|
433
|
-
|Staleness? |Silent |Silent |TTL-based decay with advisory lint |
|
|
402
|
+
The default report shows the document and tension state at that point and
|
|
403
|
+
the drift since: documents added/removed, `status`/`confidence` transitions,
|
|
404
|
+
and tensions opened or resolved. `--blast` computes the blast radius of a
|
|
405
|
+
document over the tree *as of the commit* (same source/link edge semantics as
|
|
406
|
+
`vault_tension_blast`), annotating each downstream document with its status
|
|
407
|
+
today — the post-mortem view for a fact that was later corrected. Markdown to
|
|
408
|
+
stdout by default; `--output` / `--output-json` write files. Pairs with
|
|
409
|
+
`vault_receipt`: a receipt's `vaultHead` is exactly the anchor to hand back
|
|
410
|
+
to `asof`.
|
|
434
411
|
|
|
435
|
-
##
|
|
412
|
+
## The vault as witness — and the wager layer
|
|
436
413
|
|
|
437
|
-
|
|
414
|
+
Every write already carries an identity, every proposal an outcome, every
|
|
415
|
+
tension a logger and a ruling. `vault_witness` aggregates that ledger into a
|
|
416
|
+
**track record per principal** — and prices it. Confidence is free to claim,
|
|
417
|
+
so the wager schedule makes it cost something: writing at `high` stakes 3
|
|
418
|
+
points, `medium` 1, `low` 0 (hedged claims are the honest default and are
|
|
419
|
+
never taxed). A claim later corrected by a ruling or retired by someone else
|
|
420
|
+
burns the stake; a claim maintained through a full TTL cycle earns credit.
|
|
421
|
+
The balance is arithmetic on recorded facts — advisory, provisional
|
|
422
|
+
constants, nothing enforced: routing a high-stakes write to the agent with
|
|
423
|
+
the earned balance is your policy, not the vault's.
|
|
438
424
|
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
[Storage backing](#storage-backing); the project itself hosts nothing)
|
|
442
|
-
- **Conflict resolution beyond file-level locks** (CRDTs, semantic merge)
|
|
443
|
-
- **Background curation agent** running lint on a cadence
|
|
444
|
-
- **Enforced domain separation** (v1 documents the convention; v2 enforces it —
|
|
445
|
-
advisory boundary warnings shipped in the meantime: `vault_lint`'s
|
|
446
|
-
`domainLeaks` check and write-time `domain_warnings`)
|
|
425
|
+
<details>
|
|
426
|
+
<summary><b>The two kill conditions that travel with the tool (▸ expand for full reference)</b></summary>
|
|
447
427
|
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
428
|
+
Both kill conditions from the design travel with the tool: the flat-curve
|
|
429
|
+
monitor (one author ≥95% of writes → curves declared uninformative) and the
|
|
430
|
+
longitudinal write-volume series (if stake-fear suppresses honest claims, it
|
|
431
|
+
shows up here first).
|
|
451
432
|
|
|
452
|
-
|
|
433
|
+
</details>
|
|
453
434
|
|
|
454
435
|
## Coherence audit
|
|
455
436
|
|
|
@@ -516,6 +497,9 @@ staleness check still runs over the in-repo link graph.
|
|
|
516
497
|
Catches the case where you keep touching an index page while the docs it
|
|
517
498
|
links to are rotting.
|
|
518
499
|
|
|
500
|
+
<details>
|
|
501
|
+
<summary><b>Sample output, CI integration, exit codes, CLI flags, and the full <code>audit.yaml</code> schema (▸ expand for full reference)</b></summary>
|
|
502
|
+
|
|
519
503
|
### Sample output
|
|
520
504
|
|
|
521
505
|
```markdown
|
|
@@ -610,131 +594,245 @@ fail_on:
|
|
|
610
594
|
transitive_staleness: 100 # default: generous; teams tune
|
|
611
595
|
```
|
|
612
596
|
|
|
613
|
-
|
|
597
|
+
</details>
|
|
614
598
|
|
|
615
|
-
|
|
616
|
-
tension a logger and a ruling. `vault_witness` aggregates that ledger into a
|
|
617
|
-
**track record per principal** — and prices it. Confidence is free to claim,
|
|
618
|
-
so the wager schedule makes it cost something: writing at `high` stakes 3
|
|
619
|
-
points, `medium` 1, `low` 0 (hedged claims are the honest default and are
|
|
620
|
-
never taxed). A claim later corrected by a ruling or retired by someone else
|
|
621
|
-
burns the stake; a claim maintained through a full TTL cycle earns credit.
|
|
622
|
-
The balance is arithmetic on recorded facts — advisory, provisional
|
|
623
|
-
constants, nothing enforced: routing a high-stakes write to the agent with
|
|
624
|
-
the earned balance is your policy, not the vault's. Both kill conditions
|
|
625
|
-
from the design travel with the tool: the flat-curve monitor (one author ≥95%
|
|
626
|
-
of writes → curves declared uninformative) and the longitudinal write-volume
|
|
627
|
-
series (if stake-fear suppresses honest claims, it shows up here first).
|
|
599
|
+
<!-- Running it -->
|
|
628
600
|
|
|
629
|
-
##
|
|
601
|
+
## Access control
|
|
630
602
|
|
|
631
|
-
|
|
632
|
-
|
|
603
|
+
No user-management system. Roles live in config, the server starts with one.
|
|
604
|
+
No `--role` or an unknown name falls back to deny-all. An agent identity is
|
|
605
|
+
just a role too — e.g. a `curation-loop` role that reads and writes but leaves
|
|
606
|
+
`ratify` off: the agent proposes, humans ratify.
|
|
607
|
+
|
|
608
|
+
<details>
|
|
609
|
+
<summary><b>Roles config example (▸ expand for full reference)</b></summary>
|
|
610
|
+
|
|
611
|
+
```yaml
|
|
612
|
+
roles:
|
|
613
|
+
analyst:
|
|
614
|
+
read: [competitive-intel, pricing]
|
|
615
|
+
write: [competitive-intel, _drafts]
|
|
616
|
+
researcher:
|
|
617
|
+
read: ["*"]
|
|
618
|
+
write: [moonshot, _drafts]
|
|
619
|
+
admin:
|
|
620
|
+
read: ["*"]
|
|
621
|
+
write: ["*"]
|
|
622
|
+
promote: true
|
|
623
|
+
ratify: true # may approve/reject staged actions and contest edges
|
|
624
|
+
```
|
|
625
|
+
|
|
626
|
+
</details>
|
|
627
|
+
|
|
628
|
+
## Server mode (self-hosted)
|
|
629
|
+
|
|
630
|
+
By default daftari is a per-user stdio process. `daftari serve` starts the
|
|
631
|
+
same vault as **one always-on instance over Streamable HTTP** — for a team, or
|
|
632
|
+
for clients that can't spawn a local process (claude.ai web/mobile, Cowork):
|
|
633
633
|
|
|
634
634
|
```bash
|
|
635
|
-
|
|
636
|
-
|
|
635
|
+
daftari serve --vault ./my-vault # http://127.0.0.1:8787/mcp
|
|
636
|
+
daftari serve --vault ./my-vault --bind 0.0.0.0 --port 9000
|
|
637
637
|
```
|
|
638
638
|
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
`.daftari/wake-queue.jsonl` for an external agent to consume — re-verify each
|
|
643
|
-
document against its sources, stage the diff — because the vault never
|
|
644
|
-
re-verifies on its own. Generative documents going stale are expected, not a
|
|
645
|
-
defect: counted, never woken.
|
|
639
|
+
Identity is **per MCP session**, resolved when the session opens, so every
|
|
640
|
+
RBAC and existence-disclosure rule applies per connection with zero tool
|
|
641
|
+
changes. Two composable auth schemes, both declared in config.
|
|
646
642
|
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
the rubber-stamp monitor — zero rejections over a long decision history is
|
|
650
|
-
printed as a warning, not a compliment. The agent proposes overnight; you
|
|
651
|
-
ratify over coffee.
|
|
643
|
+
<details>
|
|
644
|
+
<summary><b>Auth config (bearer tokens + OAuth 2.1) and the fail-loud posture (▸ expand for full reference)</b></summary>
|
|
652
645
|
|
|
653
|
-
|
|
646
|
+
```yaml
|
|
647
|
+
server:
|
|
648
|
+
transport_security: external # required off-loopback: TLS terminates upstream
|
|
649
|
+
auth:
|
|
650
|
+
tokens: # static bearer tokens (agents, ETL)
|
|
651
|
+
- env: DAFTARI_TOKEN_ETL # the VALUE lives in this env var, never in config
|
|
652
|
+
user: agent:etl
|
|
653
|
+
role: admin
|
|
654
|
+
oauth: # OAuth 2.1 resource server (humans via your IdP)
|
|
655
|
+
issuer: https://idp.example.com
|
|
656
|
+
audience: daftari
|
|
657
|
+
jwks_uri: https://idp.example.com/.well-known/jwks.json
|
|
658
|
+
subjects:
|
|
659
|
+
"alice@example.com": { user: human:alice, role: analyst }
|
|
660
|
+
```
|
|
654
661
|
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
662
|
+
The posture is fail-loud, never silent-downgrade: a non-loopback bind refuses
|
|
663
|
+
to start without auth **and** the explicit `transport_security: external`
|
|
664
|
+
acknowledgment (daftari never terminates TLS itself — put Caddy/nginx/a load
|
|
665
|
+
balancer in front); with any auth configured, a bad or missing credential is
|
|
666
|
+
a 401 at session open and a valid JWT whose subject isn't mapped is a 403 —
|
|
667
|
+
neither ever becomes the guest. Guest sessions exist only in the no-auth
|
|
668
|
+
loopback configuration. A running server also refuses to be silently killed:
|
|
669
|
+
stray stdio invocations against the same vault refuse to start, and replacing
|
|
670
|
+
a live holder requires a deliberate `daftari serve --takeover`.
|
|
671
|
+
|
|
672
|
+
</details>
|
|
673
|
+
|
|
674
|
+
## Storage backing
|
|
675
|
+
|
|
676
|
+
A self-hosted vault can push to durable object storage (#6). The local git
|
|
677
|
+
working copy stays canonical — reads, writes, auto-commits, locks, and the
|
|
678
|
+
index all stay exactly as above — and the backing is a dumb sync target.
|
|
679
|
+
|
|
680
|
+
<details>
|
|
681
|
+
<summary><b>Storage config, <code>daftari sync</code> commands, and sync semantics (▸ expand for full reference)</b></summary>
|
|
682
|
+
|
|
683
|
+
```yaml
|
|
684
|
+
# .daftari/config.yaml
|
|
685
|
+
storage:
|
|
686
|
+
backend: s3 # fs | s3 | azure
|
|
687
|
+
bucket: team-vault
|
|
688
|
+
region: us-east-1
|
|
689
|
+
# endpoint: https://… # MinIO / R2 / GCS S3-interop endpoints
|
|
690
|
+
# sync_interval_minutes: 15 # daftari serve pushes on this cadence
|
|
691
|
+
```
|
|
661
692
|
|
|
662
693
|
```bash
|
|
663
|
-
|
|
664
|
-
daftari
|
|
694
|
+
daftari sync --vault ./my-vault # incremental push
|
|
695
|
+
daftari sync --vault ./my-vault --dry-run # show the diff only
|
|
696
|
+
daftari sync --vault ./empty-dir --restore --backend s3 --bucket team-vault
|
|
697
|
+
```
|
|
665
698
|
|
|
666
|
-
|
|
667
|
-
daftari
|
|
699
|
+
The push covers the markdown tree, the `.git` directory, and durable
|
|
700
|
+
`.daftari` journals; the rebuildable SQLite index and lock files never sync.
|
|
701
|
+
Neither do `.git/config` and `.git/hooks` — git *executes* what those
|
|
702
|
+
declare, and a backup channel must not deliver code (`git clone` refuses to
|
|
703
|
+
transmit them for the same reason), so re-add remotes and local git config
|
|
704
|
+
by hand after a restore.
|
|
705
|
+
Cloud backends load their SDKs (`@aws-sdk/client-s3`, `@azure/storage-blob`)
|
|
706
|
+
as optional dependencies — install the one you use; credentials come from the
|
|
707
|
+
SDK's standard environment chain, never from vault config. GCS is reached via
|
|
708
|
+
its S3-interoperability endpoint. Restore refuses non-empty directories and
|
|
709
|
+
reindexes when done.
|
|
668
710
|
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
711
|
+
</details>
|
|
712
|
+
|
|
713
|
+
## Adopting an existing vault
|
|
714
|
+
|
|
715
|
+
Already have a wiki or an Obsidian vault? Daftari adopts it **in place** — it
|
|
716
|
+
indexes and curates the same markdown files you already edit, not a separate copy.
|
|
717
|
+
|
|
718
|
+
```bash
|
|
719
|
+
# Dry run — see what would change, write nothing
|
|
720
|
+
daftari import obsidian ~/my-vault --plan
|
|
721
|
+
|
|
722
|
+
# Adopt one folder at a time (per-folder ratification; --yes to skip the prompt)
|
|
723
|
+
daftari import obsidian ~/my-vault --apply --scope notes
|
|
672
724
|
```
|
|
673
725
|
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
726
|
+
The import is non-destructive to your content. It fills only the *missing*
|
|
727
|
+
Daftari frontmatter — collection from the folder, dates from git history (or file
|
|
728
|
+
mtime), sensible defaults for the rest — and preserves everything you already
|
|
729
|
+
had, including custom frontmatter fields. Obsidian specifics: inline `#tags` are
|
|
730
|
+
merged into `tags`, a Web Clipper `source` is mapped into `sources`, and
|
|
731
|
+
`[[wikilinks]]` are left untouched (Daftari resolves them as written). Filling
|
|
732
|
+
frontmatter is deliberate, not automatic — re-run the import to pick up newly
|
|
733
|
+
added notes.
|
|
680
734
|
|
|
681
|
-
|
|
735
|
+
### Cloud-synced vaults (iCloud, Dropbox, …)
|
|
682
736
|
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
first, longest-carried first), canonical accumulation docs past their TTL,
|
|
686
|
-
and `questions_raised` entries no document answers — deterministic and
|
|
687
|
-
LLM-free, like the circadian pass:
|
|
737
|
+
Daftari versions every change with git, and a `.git/` directory churning inside a
|
|
738
|
+
cloud-synced folder can corrupt. For a synced vault, keep git's data outside it:
|
|
688
739
|
|
|
689
740
|
```bash
|
|
690
|
-
|
|
691
|
-
|
|
741
|
+
daftari import obsidian "~/Library/Mobile Documents/.../my-vault" \
|
|
742
|
+
--apply --scope notes --external-git-dir
|
|
743
|
+
```
|
|
692
744
|
|
|
693
|
-
|
|
694
|
-
|
|
745
|
+
This writes `git_dir: external` to `.daftari/config.yaml`, so Daftari uses
|
|
746
|
+
`git init --separate-git-dir`: only a tiny static `.git` *file* stays in the vault
|
|
747
|
+
(syncs harmlessly) while the repo data lives under `~/.local/share/daftari/git/`.
|
|
748
|
+
Pass `--external-git-dir=/path` for an explicit location, or set `git_dir`
|
|
749
|
+
directly in config to apply the same to any vault. History is per-device; your
|
|
750
|
+
notes still sync everywhere.
|
|
751
|
+
|
|
752
|
+
### Lower-level: `backfill`
|
|
753
|
+
|
|
754
|
+
`daftari import obsidian` is a thin, Obsidian-aware wrapper over `daftari
|
|
755
|
+
backfill` — the git-driven frontmatter migration that works on any markdown wiki.
|
|
756
|
+
Use it directly for non-Obsidian trees:
|
|
757
|
+
|
|
758
|
+
```bash
|
|
759
|
+
daftari backfill --plan
|
|
760
|
+
daftari backfill --apply --scope specs
|
|
695
761
|
```
|
|
696
762
|
|
|
697
|
-
|
|
698
|
-
collection — `tier: source` (your words, body immutable), `provenance:
|
|
699
|
-
direct`, no TTL (testimony doesn't expire) — committed like any other write,
|
|
700
|
-
with `sources` tracing each question back to the tension or document that
|
|
701
|
-
prompted it. The pattern is the companion interview on a living-summary
|
|
702
|
-
page: the compiler's highest-value move is not more compilation, it is
|
|
703
|
-
asking the principal about the unclear spots and folding the verbatim
|
|
704
|
-
answers back into the corpus.
|
|
763
|
+
## Open Knowledge Format (OKF)
|
|
705
764
|
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
765
|
+
[OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/)
|
|
766
|
+
is Google Cloud's vendor-neutral spec for the LLM-wiki pattern: a directory of
|
|
767
|
+
markdown files with YAML frontmatter that any producer can emit and any consumer
|
|
768
|
+
can read without translation. A Daftari vault *is* that pattern, so `daftari
|
|
769
|
+
okf` bridges the two directions.
|
|
770
|
+
[v0.2](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals/)
|
|
771
|
+
adds opt-in **trust signals** — raw credibility indicators (provenance,
|
|
772
|
+
verification, lifecycle, freshness), never computed scores — and Daftari maps
|
|
773
|
+
them from/to its native metadata.
|
|
710
774
|
|
|
711
|
-
|
|
775
|
+
<details>
|
|
776
|
+
<summary><b>OKF export / import field-mapping and the <code>daftari okf</code> commands (▸ expand for full reference)</b></summary>
|
|
712
777
|
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
778
|
+
**Export** renders the vault as a portable OKF bundle — every doc becomes an OKF
|
|
779
|
+
concept doc (the core `type` / `title` / `description` / `resource` / `tags`
|
|
780
|
+
fields, plus a verbatim `daftari` sidecar for lossless round-trip), with
|
|
781
|
+
generated `index.md` (progressive-disclosure listing) and `log.md`
|
|
782
|
+
(chronological history). Trust signals derive from native metadata:
|
|
783
|
+
`updated`/`updated_by` become `generated`, the lifecycle maps to
|
|
784
|
+
`draft`/`stable`/`deprecated`, `ttl_days` becomes an absolute `stale_after`
|
|
785
|
+
date, and `sources` become structured entries. `verified` is never fabricated —
|
|
786
|
+
Daftari records authorship, not independent confirmations, so exported docs
|
|
787
|
+
honestly read as unverified. The source vault is never mutated.
|
|
716
788
|
|
|
717
789
|
```bash
|
|
718
|
-
|
|
719
|
-
daftari
|
|
790
|
+
daftari okf export ./my-vault --out ./okf-bundle
|
|
791
|
+
daftari okf export ./my-vault --out ./okf-bundle --collection pricing
|
|
792
|
+
```
|
|
720
793
|
|
|
721
|
-
|
|
722
|
-
|
|
794
|
+
**Import** adopts an OKF bundle into a vault. A bundle produced by `okf export`
|
|
795
|
+
round-trips exactly via its sidecar; a foreign bundle is mapped conservatively
|
|
796
|
+
(docs land as `draft` in the `accumulation` domain, the original OKF `type` is
|
|
797
|
+
preserved in an `okf_type` field). Trust signals inform the mapping: a
|
|
798
|
+
human-reviewed doc (a `human:*` entry in `verified`) imports with `confidence:
|
|
799
|
+
high`, `status: deprecated` stays `deprecated` (retired knowledge must not
|
|
800
|
+
resurface as a fresh draft), and `stale_after` converts to `ttl_days`. An
|
|
801
|
+
`Attested Computation` is surfaced in an import warning but **not**
|
|
802
|
+
auto-write-protected: `tier: source` is enforcement, and its only sanctioned
|
|
803
|
+
grant path is `vault_set_tier` (reason required, provenance-logged) — a foreign
|
|
804
|
+
bundle's self-declared `type` doesn't buy it. Review the doc, then elevate
|
|
805
|
+
deliberately. OKF fields with no lossless Daftari slot (the trust record,
|
|
806
|
+
attestation machinery) are preserved under `okf_*` keys. Writes auto-commit and
|
|
807
|
+
the index is rebuilt.
|
|
723
808
|
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
daftari
|
|
809
|
+
```bash
|
|
810
|
+
daftari okf import ./okf-bundle --into ./my-vault --dry-run
|
|
811
|
+
daftari okf import ./okf-bundle --into ./my-vault
|
|
727
812
|
```
|
|
728
813
|
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
814
|
+
</details>
|
|
815
|
+
|
|
816
|
+
<!-- Reference / meta -->
|
|
817
|
+
|
|
818
|
+
## What’s not in v1
|
|
819
|
+
|
|
820
|
+
Deliberately deferred to keep the surface tight:
|
|
821
|
+
|
|
822
|
+
- **Cloud-hosted multi-tenant SaaS** (self-hosted server mode HAS shipped —
|
|
823
|
+
see [Server mode](#server-mode-self-hosted) and
|
|
824
|
+
[Storage backing](#storage-backing); the project itself hosts nothing)
|
|
825
|
+
- **Conflict resolution beyond file-level locks** (CRDTs, semantic merge)
|
|
826
|
+
- **Background curation agent** running lint on a cadence
|
|
827
|
+
- **Enforced domain separation** (v1 documents the convention; v2 enforces it —
|
|
828
|
+
advisory boundary warnings shipped in the meantime: `vault_lint`'s
|
|
829
|
+
`domainLeaks` check and write-time `domain_warnings`)
|
|
830
|
+
|
|
831
|
+
(LLM reranking, deferred here originally, has since shipped as the opt-in
|
|
832
|
+
agent-as-judge `rerank_candidates` on `vault_search`: the server prepares the
|
|
833
|
+
fused candidate pool and the protocol; the calling agent is the judge.)
|
|
834
|
+
|
|
835
|
+
Each is a clean increment on a surface that already works.
|
|
738
836
|
|
|
739
837
|
## Development
|
|
740
838
|
|
|
@@ -756,7 +854,7 @@ Design tenets: functions and types, no classes; tool handlers return
|
|
|
756
854
|
## Integrations
|
|
757
855
|
|
|
758
856
|
- [`integrations/langchain/`](integrations/langchain/) — `langchain-daftari`, a
|
|
759
|
-
Python package that exposes
|
|
857
|
+
Python package that exposes all 35 daftari tools as LangChain `BaseTool`s
|
|
760
858
|
for use with LangGraph / `create_react_agent`. Sync + async, schemas pulled
|
|
761
859
|
live from `tools/list`.
|
|
762
860
|
- [`packages/router`](packages/router) — multi-vault MCP router that fans out across N Daftari vaults
|
|
@@ -776,3 +874,4 @@ retention, and contact.
|
|
|
776
874
|
## License
|
|
777
875
|
|
|
778
876
|
MIT.
|
|
877
|
+
|