daftari 2.0.0 → 3.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +33 -0
- package/README.md +471 -366
- package/dist/access/locks.d.ts +1 -0
- package/dist/access/locks.d.ts.map +1 -1
- package/dist/access/locks.js +13 -0
- package/dist/access/locks.js.map +1 -1
- package/dist/access/rbac.js +3 -3
- package/dist/access/rbac.js.map +1 -1
- package/dist/asof/git-read.d.ts.map +1 -1
- package/dist/asof/git-read.js +4 -0
- package/dist/asof/git-read.js.map +1 -1
- package/dist/backfill/derive.d.ts.map +1 -1
- package/dist/backfill/derive.js +4 -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.d.ts.map +1 -1
- package/dist/curation/lint-voice.js +2 -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 +85 -5
- package/dist/curation/lint.js.map +1 -1
- package/dist/curation/positions.d.ts +29 -0
- package/dist/curation/positions.d.ts.map +1 -0
- package/dist/curation/positions.js +164 -0
- package/dist/curation/positions.js.map +1 -0
- 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/staleness.d.ts +0 -7
- package/dist/curation/staleness.d.ts.map +1 -1
- package/dist/curation/staleness.js +0 -30
- package/dist/curation/staleness.js.map +1 -1
- 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/curation/tension.d.ts +5 -2
- package/dist/curation/tension.d.ts.map +1 -1
- package/dist/curation/tension.js +169 -103
- package/dist/curation/tension.js.map +1 -1
- package/dist/curation/vault-docs.d.ts +10 -0
- package/dist/curation/vault-docs.d.ts.map +1 -1
- package/dist/curation/vault-docs.js +101 -10
- package/dist/curation/vault-docs.js.map +1 -1
- package/dist/eval/llm-openrouter.d.ts.map +1 -1
- package/dist/eval/llm-openrouter.js +8 -0
- package/dist/eval/llm-openrouter.js.map +1 -1
- package/dist/frontmatter/schema.d.ts.map +1 -1
- package/dist/frontmatter/schema.js +119 -1
- package/dist/frontmatter/schema.js.map +1 -1
- package/dist/frontmatter/types.d.ts +29 -2
- package/dist/frontmatter/types.d.ts.map +1 -1
- package/dist/frontmatter/types.js +13 -0
- package/dist/frontmatter/types.js.map +1 -1
- package/dist/lifecycle/lock.d.ts +2 -0
- package/dist/lifecycle/lock.d.ts.map +1 -1
- package/dist/lifecycle/lock.js +98 -18
- package/dist/lifecycle/lock.js.map +1 -1
- package/dist/search/hybrid.d.ts +1 -1
- package/dist/search/hybrid.d.ts.map +1 -1
- package/dist/search/providers/openai-3-small.d.ts.map +1 -1
- package/dist/search/providers/openai-3-small.js +8 -0
- package/dist/search/providers/openai-3-small.js.map +1 -1
- package/dist/search/reindex.d.ts.map +1 -1
- package/dist/search/reindex.js +39 -13
- package/dist/search/reindex.js.map +1 -1
- package/dist/serve/index.d.ts +4 -1
- package/dist/serve/index.d.ts.map +1 -1
- package/dist/serve/index.js +28 -12
- package/dist/serve/index.js.map +1 -1
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +2 -0
- package/dist/server.js.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/storage/index-db.d.ts +1 -0
- package/dist/storage/index-db.d.ts.map +1 -1
- package/dist/storage/index-db.js +17 -2
- package/dist/storage/index-db.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/positions.d.ts +42 -0
- package/dist/tools/positions.d.ts.map +1 -0
- package/dist/tools/positions.js +711 -0
- package/dist/tools/positions.js.map +1 -0
- package/dist/tools/read.d.ts +24 -1
- package/dist/tools/read.d.ts.map +1 -1
- package/dist/tools/read.js +190 -6
- 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 +32 -2
- package/dist/tools/write.d.ts.map +1 -1
- package/dist/tools/write.js +130 -16
- package/dist/tools/write.js.map +1 -1
- package/dist/utils/concurrency.d.ts +2 -0
- package/dist/utils/concurrency.d.ts.map +1 -0
- package/dist/utils/concurrency.js +39 -0
- package/dist/utils/concurrency.js.map +1 -0
- package/dist/utils/git.d.ts.map +1 -1
- package/dist/utils/git.js +5 -1
- package/dist/utils/git.js.map +1 -1
- package/package.json +2 -2
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 38
|
|
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,32 @@ 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
|
|
|
257
|
+
**Positions:** `vault_assert` (a principal's assert/dispute/qualify stance on a claim doc; conflicting live stances mark it contested and cap confidence), `vault_positions` (query positions by doc or principal), `vault_consolidate` (ratify-gated org stance; clears the contested confidence cap, dissent computed server-side)
|
|
258
|
+
|
|
123
259
|
The curation engine is advisory: `vault_lint` reports problems and
|
|
124
260
|
`vault_tension_log` records contradictions. Neither auto-fixes anything. Every
|
|
125
|
-
change is a deliberate, attributable act.
|
|
261
|
+
change is a deliberate, attributable act. Retraction is surfaced, not enforced:
|
|
262
|
+
the `retiredStillLinked` lint check / `retired_still_linked` read-time advisory
|
|
263
|
+
flags canonical docs still citing a deprecated or superseded source, and
|
|
264
|
+
`vault_deprecate`/`vault_supersede` return a `dependents` advisory (the
|
|
265
|
+
downstream blast) at retraction time.
|
|
126
266
|
|
|
127
267
|
### Tool tiers
|
|
128
268
|
|
|
@@ -142,314 +282,157 @@ tools:
|
|
|
142
282
|
`core` is the search-before-derive loop (`vault_search`, `vault_read`,
|
|
143
283
|
`vault_write`, `vault_index`, `vault_lint`, `vault_status`); `standard` adds
|
|
144
284
|
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
|
|
285
|
+
confidence and tier setters, propose/ratify) plus `vault_search_related`,
|
|
286
|
+
`vault_provenance`, and diagnostics; `full` is everything. `--tools <tier>` overrides the tier for one invocation. Filtering
|
|
147
287
|
only changes what is *advertised* — calls to any registered tool still work,
|
|
148
288
|
so an agent holding a cached tool name keeps working across a tier change.
|
|
149
289
|
Unknown names in `include`/`exclude` warn at startup and are ignored, so a
|
|
150
290
|
config written for a newer daftari still loads.
|
|
151
291
|
|
|
292
|
+
</details>
|
|
293
|
+
|
|
152
294
|
**Evaluate (opt-in, requires an Anthropic API key):** `daftari eval` — scores how
|
|
153
295
|
well an LLM can use the curation surface to answer multi-hop questions about the
|
|
154
296
|
vault. See the [design spec](docs/superpowers/specs/2026-05-31-cortex-quality-metric-design.md)
|
|
155
297
|
for the rationale and the cortex framing.
|
|
156
298
|
|
|
157
|
-
##
|
|
158
|
-
|
|
159
|
-
Every document declares a `domain`. The distinction drives how the curation
|
|
160
|
-
layer treats it.
|
|
299
|
+
## Circadian memory
|
|
161
300
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
Going stale is a problem to fix.
|
|
301
|
+
The vault sleeps. `daftari sleep` is the nightly metabolic pass — deterministic,
|
|
302
|
+
LLM-free, write-free (documents are never touched):
|
|
165
303
|
|
|
166
|
-
|
|
167
|
-
|
|
304
|
+
```bash
|
|
305
|
+
# In cron (any scheduler works; daftari ships the cycle, not a daemon):
|
|
306
|
+
0 3 * * * cd /path/to/vault && npx daftari sleep --output .daftari/morning-report.md
|
|
307
|
+
```
|
|
168
308
|
|
|
169
|
-
The
|
|
170
|
-
|
|
171
|
-
|
|
309
|
+
The cycle sweeps expired staged actions, scores every document's decay, and
|
|
310
|
+
builds the **wake list**: canonical accumulation documents past their TTL
|
|
311
|
+
with downstream dependents, ranked by blast radius. The list is written to
|
|
312
|
+
`.daftari/wake-queue.jsonl` for an external agent to consume — re-verify each
|
|
313
|
+
document against its sources, stage the diff — because the vault never
|
|
314
|
+
re-verifies on its own. Generative documents going stale are expected, not a
|
|
315
|
+
defect: counted, never woken.
|
|
172
316
|
|
|
173
|
-
|
|
317
|
+
The **Morning Report** ends where the human begins: tension aging and the
|
|
318
|
+
court docket head, the ratification queue with soon-to-expire proposals, and
|
|
319
|
+
the rubber-stamp monitor — zero rejections over a long decision history is
|
|
320
|
+
printed as a warning, not a compliment. The agent proposes overnight; you
|
|
321
|
+
ratify over coffee.
|
|
174
322
|
|
|
175
|
-
|
|
323
|
+
## Tension Court
|
|
176
324
|
|
|
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
|
-
```
|
|
325
|
+
Tensions wait in a log; the court turns them into decidable cases. `daftari
|
|
326
|
+
court` compiles a **docket** — every open tension briefed and ranked (stale
|
|
327
|
+
first, then by blast radius): both sides' claims, the present state of their
|
|
328
|
+
documents, the downstream stakes, cluster membership, and **precedents** —
|
|
329
|
+
past rulings on disputes that shared a document, a collection pair, or a
|
|
330
|
+
kind.
|
|
191
331
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
332
|
+
The **triage card** (`daftari court --triage` / `vault_tension_triage`) is the
|
|
333
|
+
deliberately **unranked**, cluster-grouped companion view — legibility, not a
|
|
334
|
+
severity score. Each contested side surfaces `criticality`, `provenance`, and
|
|
335
|
+
`updated_by`, so a resolver can judge trust without opening the documents.
|
|
195
336
|
|
|
196
|
-
|
|
337
|
+
```bash
|
|
338
|
+
# The docket — a 5-minute weekly ritual
|
|
339
|
+
daftari court --vault ./my-vault
|
|
197
340
|
|
|
198
|
-
|
|
199
|
-
|
|
341
|
+
# One case's full brief (verbatim rationales from cited precedents)
|
|
342
|
+
daftari court --tension tension-abc123
|
|
200
343
|
|
|
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
|
-
---
|
|
344
|
+
# Rule. The rationale is recorded verbatim and cited by future dockets.
|
|
345
|
+
daftari court rule tension-abc123 --kind corrected \
|
|
346
|
+
--rationale "Vendor pricing page confirmed the entry tier on 2026-07-10."
|
|
223
347
|
```
|
|
224
348
|
|
|
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.
|
|
349
|
+
Rulings go through the same `resolveTension` write path as
|
|
350
|
+
`vault_tension_resolve` — a ruling records the closure, it never edits the
|
|
351
|
+
disputed documents. Precedent retrieval is deterministic (shared-document >
|
|
352
|
+
collection-pair > same-kind; no LLM): the court retrieves how this house has
|
|
353
|
+
resolved similar disputes before, and whether a precedent applies stays the
|
|
354
|
+
human's judgment. Memory grows case law.
|
|
234
355
|
|
|
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".
|
|
356
|
+
## The principal interview
|
|
241
357
|
|
|
242
|
-
|
|
358
|
+
The vault interrogates you. `daftari interview` assembles a question sheet
|
|
359
|
+
from what the vault already knows is unclear — open tensions (contested
|
|
360
|
+
first, longest-carried first), canonical accumulation docs past their TTL,
|
|
361
|
+
and `questions_raised` entries no document answers — deterministic and
|
|
362
|
+
LLM-free, like the circadian pass:
|
|
243
363
|
|
|
244
364
|
```bash
|
|
245
|
-
|
|
365
|
+
# The sheet — read-only, priority-ordered
|
|
366
|
+
daftari interview --vault ./my-vault
|
|
367
|
+
|
|
368
|
+
# Sit for it. Answers are recorded VERBATIM; empty skips, 'q' ends.
|
|
369
|
+
daftari interview ask --vault ./my-vault
|
|
246
370
|
```
|
|
247
371
|
|
|
248
|
-
|
|
372
|
+
Answered questions become a transcript document in an `interviews/`
|
|
373
|
+
collection — `tier: source` (your words, body immutable), `provenance:
|
|
374
|
+
direct`, no TTL (testimony doesn't expire) — committed like any other write,
|
|
375
|
+
with `sources` tracing each question back to the tension or document that
|
|
376
|
+
prompted it. The pattern is the companion interview on a living-summary
|
|
377
|
+
page: the compiler's highest-value move is not more compilation, it is
|
|
378
|
+
asking the principal about the unclear spots and folding the verbatim
|
|
379
|
+
answers back into the corpus.
|
|
249
380
|
|
|
250
|
-
|
|
381
|
+
Recording testimony resolves nothing. The transcript is *evidence*: the CLI
|
|
382
|
+
ends by pointing at `daftari court rule <id> --references <transcript>` for
|
|
383
|
+
tensions it touched, and at re-verified writes for stale docs. Operator-only,
|
|
384
|
+
like the court — no MCP tool, no access context.
|
|
251
385
|
|
|
252
|
-
##
|
|
386
|
+
## Belief archaeology
|
|
253
387
|
|
|
254
|
-
|
|
255
|
-
|
|
388
|
+
Git is the version layer, so the vault can answer **"what did we believe on
|
|
389
|
+
March 3?"** `daftari asof` is a read-only report over the repo's history — no
|
|
390
|
+
checkout, no index, no API key:
|
|
256
391
|
|
|
257
392
|
```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.
|
|
393
|
+
# The vault's belief state at a date (or any git ref), plus the drift since
|
|
394
|
+
daftari asof 2026-03-03 --vault ./my-vault
|
|
273
395
|
|
|
274
|
-
|
|
396
|
+
# One document's trajectory: frontmatter then vs now, commits in between
|
|
397
|
+
daftari asof HEAD~20 --doc pricing/helios-consumption-pricing.md
|
|
275
398
|
|
|
276
|
-
|
|
277
|
-
|
|
399
|
+
# Counterfactual replay: this fact turned out wrong — who had inherited it
|
|
400
|
+
# at the time, and where are they now?
|
|
401
|
+
daftari asof 2026-03-03 --blast pricing/helios-consumption-pricing.md
|
|
402
|
+
```
|
|
278
403
|
|
|
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.
|
|
404
|
+
The default report shows the document and tension state at that point and
|
|
405
|
+
the drift since: documents added/removed, `status`/`confidence` transitions,
|
|
406
|
+
and tensions opened or resolved. `--blast` computes the blast radius of a
|
|
407
|
+
document over the tree *as of the commit* (same source/link edge semantics as
|
|
408
|
+
`vault_tension_blast`), annotating each downstream document with its status
|
|
409
|
+
today — the post-mortem view for a fact that was later corrected. Markdown to
|
|
410
|
+
stdout by default; `--output` / `--output-json` write files. Pairs with
|
|
411
|
+
`vault_receipt`: a receipt's `vaultHead` is exactly the anchor to hand back
|
|
412
|
+
to `asof`.
|
|
424
413
|
|
|
425
|
-
##
|
|
414
|
+
## The vault as witness — and the wager layer
|
|
426
415
|
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
416
|
+
Every write already carries an identity, every proposal an outcome, every
|
|
417
|
+
tension a logger and a ruling. `vault_witness` aggregates that ledger into a
|
|
418
|
+
**track record per principal** — and prices it. Confidence is free to claim,
|
|
419
|
+
so the wager schedule makes it cost something: writing at `high` stakes 3
|
|
420
|
+
points, `medium` 1, `low` 0 (hedged claims are the honest default and are
|
|
421
|
+
never taxed). A claim later corrected by a ruling or retired by someone else
|
|
422
|
+
burns the stake; a claim maintained through a full TTL cycle earns credit.
|
|
423
|
+
The balance is arithmetic on recorded facts — advisory, provisional
|
|
424
|
+
constants, nothing enforced: routing a high-stakes write to the agent with
|
|
425
|
+
the earned balance is your policy, not the vault's.
|
|
434
426
|
|
|
435
|
-
|
|
427
|
+
<details>
|
|
428
|
+
<summary><b>The two kill conditions that travel with the tool (▸ expand for full reference)</b></summary>
|
|
436
429
|
|
|
437
|
-
|
|
430
|
+
Both kill conditions from the design travel with the tool: the flat-curve
|
|
431
|
+
monitor (one author ≥95% of writes → curves declared uninformative) and the
|
|
432
|
+
longitudinal write-volume series (if stake-fear suppresses honest claims, it
|
|
433
|
+
shows up here first).
|
|
438
434
|
|
|
439
|
-
|
|
440
|
-
see [Server mode](#server-mode-self-hosted) and
|
|
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`)
|
|
447
|
-
|
|
448
|
-
(LLM reranking, deferred here originally, has since shipped as the opt-in
|
|
449
|
-
agent-as-judge `rerank_candidates` on `vault_search`: the server prepares the
|
|
450
|
-
fused candidate pool and the protocol; the calling agent is the judge.)
|
|
451
|
-
|
|
452
|
-
Each is a clean increment on a surface that already works.
|
|
435
|
+
</details>
|
|
453
436
|
|
|
454
437
|
## Coherence audit
|
|
455
438
|
|
|
@@ -516,6 +499,9 @@ staleness check still runs over the in-repo link graph.
|
|
|
516
499
|
Catches the case where you keep touching an index page while the docs it
|
|
517
500
|
links to are rotting.
|
|
518
501
|
|
|
502
|
+
<details>
|
|
503
|
+
<summary><b>Sample output, CI integration, exit codes, CLI flags, and the full <code>audit.yaml</code> schema (▸ expand for full reference)</b></summary>
|
|
504
|
+
|
|
519
505
|
### Sample output
|
|
520
506
|
|
|
521
507
|
```markdown
|
|
@@ -610,131 +596,249 @@ fail_on:
|
|
|
610
596
|
transitive_staleness: 100 # default: generous; teams tune
|
|
611
597
|
```
|
|
612
598
|
|
|
613
|
-
|
|
599
|
+
</details>
|
|
614
600
|
|
|
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).
|
|
601
|
+
<!-- Running it -->
|
|
628
602
|
|
|
629
|
-
##
|
|
603
|
+
## Access control
|
|
630
604
|
|
|
631
|
-
|
|
632
|
-
|
|
605
|
+
No user-management system. Roles live in config, the server starts with one.
|
|
606
|
+
No `--role` or an unknown name falls back to deny-all. An agent identity is
|
|
607
|
+
just a role too — e.g. a `curation-loop` role that reads and writes but leaves
|
|
608
|
+
`ratify` off: the agent proposes, humans ratify.
|
|
609
|
+
|
|
610
|
+
<details>
|
|
611
|
+
<summary><b>Roles config example (▸ expand for full reference)</b></summary>
|
|
612
|
+
|
|
613
|
+
```yaml
|
|
614
|
+
roles:
|
|
615
|
+
analyst:
|
|
616
|
+
read: [competitive-intel, pricing]
|
|
617
|
+
write: [competitive-intel, _drafts]
|
|
618
|
+
researcher:
|
|
619
|
+
read: ["*"]
|
|
620
|
+
write: [moonshot, _drafts]
|
|
621
|
+
admin:
|
|
622
|
+
read: ["*"]
|
|
623
|
+
write: ["*"]
|
|
624
|
+
promote: true
|
|
625
|
+
ratify: true # may approve/reject staged actions and contest edges
|
|
626
|
+
```
|
|
627
|
+
|
|
628
|
+
</details>
|
|
629
|
+
|
|
630
|
+
## Server mode (self-hosted)
|
|
631
|
+
|
|
632
|
+
By default daftari is a per-user stdio process. `daftari serve` starts the
|
|
633
|
+
same vault as **one always-on instance over Streamable HTTP** — for a team, or
|
|
634
|
+
for clients that can't spawn a local process (claude.ai web/mobile, Cowork):
|
|
633
635
|
|
|
634
636
|
```bash
|
|
635
|
-
|
|
636
|
-
|
|
637
|
+
daftari serve --vault ./my-vault # http://127.0.0.1:8787/mcp
|
|
638
|
+
daftari serve --vault ./my-vault --bind 0.0.0.0 --port 9000
|
|
639
|
+
daftari serve --vault ./my-vault --legacy-http # also answer 2025-era MCP clients
|
|
637
640
|
```
|
|
638
641
|
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
defect: counted, never woken.
|
|
642
|
+
Identity is **per request**, resolved from the bearer on every request (MCP
|
|
643
|
+
2026-07-28 is stateless — there are no sessions), so every RBAC and
|
|
644
|
+
existence-disclosure rule applies per caller with zero tool changes. Two
|
|
645
|
+
composable auth schemes, both declared in config. `--legacy-http` is a
|
|
646
|
+
temporary, opt-in migration flag for clients still on 2025-era MCP: same
|
|
647
|
+
process, same per-request auth, no session table (removal tracked in #371).
|
|
646
648
|
|
|
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.
|
|
649
|
+
<details>
|
|
650
|
+
<summary><b>Auth config (bearer tokens + OAuth 2.1) and the fail-loud posture (▸ expand for full reference)</b></summary>
|
|
652
651
|
|
|
653
|
-
|
|
652
|
+
```yaml
|
|
653
|
+
server:
|
|
654
|
+
transport_security: external # required off-loopback: TLS terminates upstream
|
|
655
|
+
auth:
|
|
656
|
+
tokens: # static bearer tokens (agents, ETL)
|
|
657
|
+
- env: DAFTARI_TOKEN_ETL # the VALUE lives in this env var, never in config
|
|
658
|
+
user: agent:etl
|
|
659
|
+
role: admin
|
|
660
|
+
oauth: # OAuth 2.1 resource server (humans via your IdP)
|
|
661
|
+
issuer: https://idp.example.com
|
|
662
|
+
audience: daftari
|
|
663
|
+
jwks_uri: https://idp.example.com/.well-known/jwks.json
|
|
664
|
+
subjects:
|
|
665
|
+
"alice@example.com": { user: human:alice, role: analyst }
|
|
666
|
+
```
|
|
654
667
|
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
668
|
+
The posture is fail-loud, never silent-downgrade: a non-loopback bind refuses
|
|
669
|
+
to start without auth **and** the explicit `transport_security: external`
|
|
670
|
+
acknowledgment (daftari never terminates TLS itself — put Caddy/nginx/a load
|
|
671
|
+
balancer in front); with any auth configured, a bad or missing credential is
|
|
672
|
+
a 401 at session open and a valid JWT whose subject isn't mapped is a 403 —
|
|
673
|
+
neither ever becomes the guest. Guest sessions exist only in the no-auth
|
|
674
|
+
loopback configuration. A running server also refuses to be silently killed:
|
|
675
|
+
stray stdio invocations against the same vault refuse to start, and replacing
|
|
676
|
+
a live holder requires a deliberate `daftari serve --takeover`.
|
|
677
|
+
|
|
678
|
+
</details>
|
|
679
|
+
|
|
680
|
+
## Storage backing
|
|
681
|
+
|
|
682
|
+
A self-hosted vault can push to durable object storage (#6). The local git
|
|
683
|
+
working copy stays canonical — reads, writes, auto-commits, locks, and the
|
|
684
|
+
index all stay exactly as above — and the backing is a dumb sync target.
|
|
685
|
+
|
|
686
|
+
<details>
|
|
687
|
+
<summary><b>Storage config, <code>daftari sync</code> commands, and sync semantics (▸ expand for full reference)</b></summary>
|
|
688
|
+
|
|
689
|
+
```yaml
|
|
690
|
+
# .daftari/config.yaml
|
|
691
|
+
storage:
|
|
692
|
+
backend: s3 # fs | s3 | azure
|
|
693
|
+
bucket: team-vault
|
|
694
|
+
region: us-east-1
|
|
695
|
+
# endpoint: https://… # MinIO / R2 / GCS S3-interop endpoints
|
|
696
|
+
# sync_interval_minutes: 15 # daftari serve pushes on this cadence
|
|
697
|
+
```
|
|
661
698
|
|
|
662
699
|
```bash
|
|
663
|
-
|
|
664
|
-
daftari
|
|
700
|
+
daftari sync --vault ./my-vault # incremental push
|
|
701
|
+
daftari sync --vault ./my-vault --dry-run # show the diff only
|
|
702
|
+
daftari sync --vault ./empty-dir --restore --backend s3 --bucket team-vault
|
|
703
|
+
```
|
|
665
704
|
|
|
666
|
-
|
|
667
|
-
daftari
|
|
705
|
+
The push covers the markdown tree, the `.git` directory, and durable
|
|
706
|
+
`.daftari` journals; the rebuildable SQLite index and lock files never sync.
|
|
707
|
+
Neither do `.git/config` and `.git/hooks` — git *executes* what those
|
|
708
|
+
declare, and a backup channel must not deliver code (`git clone` refuses to
|
|
709
|
+
transmit them for the same reason), so re-add remotes and local git config
|
|
710
|
+
by hand after a restore.
|
|
711
|
+
Cloud backends load their SDKs (`@aws-sdk/client-s3`, `@azure/storage-blob`)
|
|
712
|
+
as optional dependencies — install the one you use; credentials come from the
|
|
713
|
+
SDK's standard environment chain, never from vault config. GCS is reached via
|
|
714
|
+
its S3-interoperability endpoint. Restore refuses non-empty directories and
|
|
715
|
+
reindexes when done.
|
|
668
716
|
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
717
|
+
</details>
|
|
718
|
+
|
|
719
|
+
## Adopting an existing vault
|
|
720
|
+
|
|
721
|
+
Already have a wiki or an Obsidian vault? Daftari adopts it **in place** — it
|
|
722
|
+
indexes and curates the same markdown files you already edit, not a separate copy.
|
|
723
|
+
|
|
724
|
+
```bash
|
|
725
|
+
# Dry run — see what would change, write nothing
|
|
726
|
+
daftari import obsidian ~/my-vault --plan
|
|
727
|
+
|
|
728
|
+
# Adopt one folder at a time (per-folder ratification; --yes to skip the prompt)
|
|
729
|
+
daftari import obsidian ~/my-vault --apply --scope notes
|
|
672
730
|
```
|
|
673
731
|
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
732
|
+
The import is non-destructive to your content. It fills only the *missing*
|
|
733
|
+
Daftari frontmatter — collection from the folder, dates from git history (or file
|
|
734
|
+
mtime), sensible defaults for the rest — and preserves everything you already
|
|
735
|
+
had, including custom frontmatter fields. Obsidian specifics: inline `#tags` are
|
|
736
|
+
merged into `tags`, a Web Clipper `source` is mapped into `sources`, and
|
|
737
|
+
`[[wikilinks]]` are left untouched (Daftari resolves them as written). Filling
|
|
738
|
+
frontmatter is deliberate, not automatic — re-run the import to pick up newly
|
|
739
|
+
added notes.
|
|
680
740
|
|
|
681
|
-
|
|
741
|
+
### Cloud-synced vaults (iCloud, Dropbox, …)
|
|
682
742
|
|
|
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:
|
|
743
|
+
Daftari versions every change with git, and a `.git/` directory churning inside a
|
|
744
|
+
cloud-synced folder can corrupt. For a synced vault, keep git's data outside it:
|
|
688
745
|
|
|
689
746
|
```bash
|
|
690
|
-
|
|
691
|
-
|
|
747
|
+
daftari import obsidian "~/Library/Mobile Documents/.../my-vault" \
|
|
748
|
+
--apply --scope notes --external-git-dir
|
|
749
|
+
```
|
|
692
750
|
|
|
693
|
-
|
|
694
|
-
|
|
751
|
+
This writes `git_dir: external` to `.daftari/config.yaml`, so Daftari uses
|
|
752
|
+
`git init --separate-git-dir`: only a tiny static `.git` *file* stays in the vault
|
|
753
|
+
(syncs harmlessly) while the repo data lives under `~/.local/share/daftari/git/`.
|
|
754
|
+
Pass `--external-git-dir=/path` for an explicit location, or set `git_dir`
|
|
755
|
+
directly in config to apply the same to any vault. History is per-device; your
|
|
756
|
+
notes still sync everywhere.
|
|
757
|
+
|
|
758
|
+
### Lower-level: `backfill`
|
|
759
|
+
|
|
760
|
+
`daftari import obsidian` is a thin, Obsidian-aware wrapper over `daftari
|
|
761
|
+
backfill` — the git-driven frontmatter migration that works on any markdown wiki.
|
|
762
|
+
Use it directly for non-Obsidian trees:
|
|
763
|
+
|
|
764
|
+
```bash
|
|
765
|
+
daftari backfill --plan
|
|
766
|
+
daftari backfill --apply --scope specs
|
|
695
767
|
```
|
|
696
768
|
|
|
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.
|
|
769
|
+
## Open Knowledge Format (OKF)
|
|
705
770
|
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
771
|
+
[OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/)
|
|
772
|
+
is Google Cloud's vendor-neutral spec for the LLM-wiki pattern: a directory of
|
|
773
|
+
markdown files with YAML frontmatter that any producer can emit and any consumer
|
|
774
|
+
can read without translation. A Daftari vault *is* that pattern, so `daftari
|
|
775
|
+
okf` bridges the two directions.
|
|
776
|
+
[v0.2](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals/)
|
|
777
|
+
adds opt-in **trust signals** — raw credibility indicators (provenance,
|
|
778
|
+
verification, lifecycle, freshness), never computed scores — and Daftari maps
|
|
779
|
+
them from/to its native metadata.
|
|
710
780
|
|
|
711
|
-
|
|
781
|
+
<details>
|
|
782
|
+
<summary><b>OKF export / import field-mapping and the <code>daftari okf</code> commands (▸ expand for full reference)</b></summary>
|
|
712
783
|
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
784
|
+
**Export** renders the vault as a portable OKF bundle — every doc becomes an OKF
|
|
785
|
+
concept doc (the core `type` / `title` / `description` / `resource` / `tags`
|
|
786
|
+
fields, plus a verbatim `daftari` sidecar for lossless round-trip), with
|
|
787
|
+
generated `index.md` (progressive-disclosure listing) and `log.md`
|
|
788
|
+
(chronological history). Trust signals derive from native metadata:
|
|
789
|
+
`updated`/`updated_by` become `generated`, the lifecycle maps to
|
|
790
|
+
`draft`/`stable`/`deprecated`, `ttl_days` becomes an absolute `stale_after`
|
|
791
|
+
date, and `sources` become structured entries. `verified` is never fabricated —
|
|
792
|
+
Daftari records authorship, not independent confirmations, so exported docs
|
|
793
|
+
honestly read as unverified. The source vault is never mutated.
|
|
716
794
|
|
|
717
795
|
```bash
|
|
718
|
-
|
|
719
|
-
daftari
|
|
796
|
+
daftari okf export ./my-vault --out ./okf-bundle
|
|
797
|
+
daftari okf export ./my-vault --out ./okf-bundle --collection pricing
|
|
798
|
+
```
|
|
720
799
|
|
|
721
|
-
|
|
722
|
-
|
|
800
|
+
**Import** adopts an OKF bundle into a vault. A bundle produced by `okf export`
|
|
801
|
+
round-trips exactly via its sidecar; a foreign bundle is mapped conservatively
|
|
802
|
+
(docs land as `draft` in the `accumulation` domain, the original OKF `type` is
|
|
803
|
+
preserved in an `okf_type` field). Trust signals inform the mapping: a
|
|
804
|
+
human-reviewed doc (a `human:*` entry in `verified`) imports with `confidence:
|
|
805
|
+
high`, `status: deprecated` stays `deprecated` (retired knowledge must not
|
|
806
|
+
resurface as a fresh draft), and `stale_after` converts to `ttl_days`. An
|
|
807
|
+
`Attested Computation` is surfaced in an import warning but **not**
|
|
808
|
+
auto-write-protected: `tier: source` is enforcement, and its only sanctioned
|
|
809
|
+
grant path is `vault_set_tier` (reason required, provenance-logged) — a foreign
|
|
810
|
+
bundle's self-declared `type` doesn't buy it. Review the doc, then elevate
|
|
811
|
+
deliberately. OKF fields with no lossless Daftari slot (the trust record,
|
|
812
|
+
attestation machinery) are preserved under `okf_*` keys. Writes auto-commit and
|
|
813
|
+
the index is rebuilt.
|
|
723
814
|
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
daftari
|
|
815
|
+
```bash
|
|
816
|
+
daftari okf import ./okf-bundle --into ./my-vault --dry-run
|
|
817
|
+
daftari okf import ./okf-bundle --into ./my-vault
|
|
727
818
|
```
|
|
728
819
|
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
820
|
+
</details>
|
|
821
|
+
|
|
822
|
+
<!-- Reference / meta -->
|
|
823
|
+
|
|
824
|
+
## What’s not in v1
|
|
825
|
+
|
|
826
|
+
Deliberately deferred to keep the surface tight:
|
|
827
|
+
|
|
828
|
+
- **Cloud-hosted multi-tenant SaaS** (self-hosted server mode HAS shipped —
|
|
829
|
+
see [Server mode](#server-mode-self-hosted) and
|
|
830
|
+
[Storage backing](#storage-backing); the project itself hosts nothing)
|
|
831
|
+
- **Conflict resolution beyond file-level locks** (CRDTs, semantic merge)
|
|
832
|
+
- **Background curation agent** running lint on a cadence
|
|
833
|
+
- **Enforced domain separation** (v1 documents the convention; v2 enforces it —
|
|
834
|
+
advisory boundary warnings shipped in the meantime: `vault_lint`'s
|
|
835
|
+
`domainLeaks` check and write-time `domain_warnings`)
|
|
836
|
+
|
|
837
|
+
(LLM reranking, deferred here originally, has since shipped as the opt-in
|
|
838
|
+
agent-as-judge `rerank_candidates` on `vault_search`: the server prepares the
|
|
839
|
+
fused candidate pool and the protocol; the calling agent is the judge.)
|
|
840
|
+
|
|
841
|
+
Each is a clean increment on a surface that already works.
|
|
738
842
|
|
|
739
843
|
## Development
|
|
740
844
|
|
|
@@ -756,7 +860,7 @@ Design tenets: functions and types, no classes; tool handlers return
|
|
|
756
860
|
## Integrations
|
|
757
861
|
|
|
758
862
|
- [`integrations/langchain/`](integrations/langchain/) — `langchain-daftari`, a
|
|
759
|
-
Python package that exposes
|
|
863
|
+
Python package that exposes all 38 daftari tools as LangChain `BaseTool`s
|
|
760
864
|
for use with LangGraph / `create_react_agent`. Sync + async, schemas pulled
|
|
761
865
|
live from `tools/list`.
|
|
762
866
|
- [`packages/router`](packages/router) — multi-vault MCP router that fans out across N Daftari vaults
|
|
@@ -776,3 +880,4 @@ retention, and contact.
|
|
|
776
880
|
## License
|
|
777
881
|
|
|
778
882
|
MIT.
|
|
883
|
+
|