daftari 1.32.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 +123 -1
- package/README.md +472 -342
- package/dist/access/rbac.d.ts +1 -0
- package/dist/access/rbac.d.ts.map +1 -1
- package/dist/access/rbac.js +16 -0
- package/dist/access/rbac.js.map +1 -1
- package/dist/asof/index.d.ts.map +1 -1
- package/dist/asof/index.js +23 -2
- package/dist/asof/index.js.map +1 -1
- package/dist/asof/report.d.ts.map +1 -1
- package/dist/asof/report.js +24 -0
- package/dist/asof/report.js.map +1 -1
- package/dist/asof/snapshot.d.ts +7 -1
- package/dist/asof/snapshot.d.ts.map +1 -1
- package/dist/asof/snapshot.js +28 -1
- package/dist/asof/snapshot.js.map +1 -1
- package/dist/backfill/derive.d.ts.map +1 -1
- package/dist/backfill/derive.js +8 -0
- package/dist/backfill/derive.js.map +1 -1
- package/dist/canary/fixtures.d.ts +12 -0
- package/dist/canary/fixtures.d.ts.map +1 -0
- package/dist/canary/fixtures.js +132 -0
- package/dist/canary/fixtures.js.map +1 -0
- package/dist/canary/index.d.ts +16 -0
- package/dist/canary/index.d.ts.map +1 -0
- package/dist/canary/index.js +105 -0
- package/dist/canary/index.js.map +1 -0
- package/dist/canary/run.d.ts +39 -0
- package/dist/canary/run.d.ts.map +1 -0
- package/dist/canary/run.js +266 -0
- package/dist/canary/run.js.map +1 -0
- package/dist/canary/stats.d.ts +36 -0
- package/dist/canary/stats.d.ts.map +1 -0
- package/dist/canary/stats.js +143 -0
- package/dist/canary/stats.js.map +1 -0
- package/dist/canon/index.d.ts +15 -0
- package/dist/canon/index.d.ts.map +1 -0
- package/dist/canon/index.js +167 -0
- package/dist/canon/index.js.map +1 -0
- package/dist/canon/resolve.d.ts +12 -0
- package/dist/canon/resolve.d.ts.map +1 -0
- package/dist/canon/resolve.js +67 -0
- package/dist/canon/resolve.js.map +1 -0
- package/dist/canon/topic.d.ts +20 -0
- package/dist/canon/topic.d.ts.map +1 -0
- package/dist/canon/topic.js +81 -0
- package/dist/canon/topic.js.map +1 -0
- package/dist/canon/types.d.ts +37 -0
- package/dist/canon/types.d.ts.map +1 -0
- package/dist/canon/types.js +9 -0
- package/dist/canon/types.js.map +1 -0
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +6 -0
- package/dist/cli.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 +3 -0
- package/dist/curation/lint-voice.d.ts.map +1 -0
- package/dist/curation/lint-voice.js +87 -0
- package/dist/curation/lint-voice.js.map +1 -0
- package/dist/curation/lint.d.ts +5 -1
- package/dist/curation/lint.d.ts.map +1 -1
- package/dist/curation/lint.js +41 -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/curation/validity.d.ts +20 -0
- package/dist/curation/validity.d.ts.map +1 -0
- package/dist/curation/validity.js +191 -0
- package/dist/curation/validity.js.map +1 -0
- package/dist/fence/detect.d.ts +10 -0
- package/dist/fence/detect.d.ts.map +1 -0
- package/dist/fence/detect.js +161 -0
- package/dist/fence/detect.js.map +1 -0
- package/dist/fence/index.d.ts +22 -0
- package/dist/fence/index.d.ts.map +1 -0
- package/dist/fence/index.js +117 -0
- package/dist/fence/index.js.map +1 -0
- package/dist/frontmatter/schema.d.ts.map +1 -1
- package/dist/frontmatter/schema.js +28 -1
- package/dist/frontmatter/schema.js.map +1 -1
- package/dist/frontmatter/types.d.ts +6 -1
- package/dist/frontmatter/types.d.ts.map +1 -1
- package/dist/frontmatter/types.js +8 -0
- package/dist/frontmatter/types.js.map +1 -1
- package/dist/holders/registry.d.ts +8 -0
- package/dist/holders/registry.d.ts.map +1 -0
- package/dist/holders/registry.js +18 -0
- package/dist/holders/registry.js.map +1 -0
- package/dist/holders/types.d.ts +10 -0
- package/dist/holders/types.d.ts.map +1 -0
- package/dist/holders/types.js +2 -0
- package/dist/holders/types.js.map +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +10 -6
- package/dist/index.js.map +1 -1
- package/dist/interview/questions.d.ts.map +1 -1
- package/dist/interview/questions.js +41 -9
- package/dist/interview/questions.js.map +1 -1
- package/dist/resources.d.ts +27 -0
- package/dist/resources.d.ts.map +1 -0
- package/dist/resources.js +169 -0
- package/dist/resources.js.map +1 -0
- package/dist/search/current-source.d.ts +1 -0
- package/dist/search/current-source.d.ts.map +1 -1
- package/dist/search/current-source.js +3 -1
- package/dist/search/current-source.js.map +1 -1
- package/dist/search/hybrid.d.ts +6 -1
- package/dist/search/hybrid.d.ts.map +1 -1
- package/dist/search/hybrid.js +23 -4
- package/dist/search/hybrid.js.map +1 -1
- package/dist/search/reindex.d.ts.map +1 -1
- package/dist/search/reindex.js +48 -13
- package/dist/search/reindex.js.map +1 -1
- package/dist/search/valid-at-source.d.ts +25 -0
- package/dist/search/valid-at-source.d.ts.map +1 -0
- package/dist/search/valid-at-source.js +131 -0
- package/dist/search/valid-at-source.js.map +1 -0
- package/dist/serve/index.d.ts.map +1 -1
- package/dist/serve/index.js +58 -89
- package/dist/serve/index.js.map +1 -1
- package/dist/server.d.ts +3 -1
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +159 -11
- package/dist/server.js.map +1 -1
- package/dist/sleep/cycle.d.ts.map +1 -1
- package/dist/sleep/cycle.js +38 -6
- package/dist/sleep/cycle.js.map +1 -1
- package/dist/storage/index-db.d.ts +7 -1
- package/dist/storage/index-db.d.ts.map +1 -1
- package/dist/storage/index-db.js +133 -8
- package/dist/storage/index-db.js.map +1 -1
- package/dist/tools/canon.d.ts +3 -0
- package/dist/tools/canon.d.ts.map +1 -0
- package/dist/tools/canon.js +177 -0
- package/dist/tools/canon.js.map +1 -0
- package/dist/tools/consumes.d.ts.map +1 -1
- package/dist/tools/consumes.js +47 -1
- package/dist/tools/consumes.js.map +1 -1
- package/dist/tools/curation.d.ts +4 -0
- package/dist/tools/curation.d.ts.map +1 -1
- package/dist/tools/curation.js +647 -3
- package/dist/tools/curation.js.map +1 -1
- package/dist/tools/edge-staleness.d.ts.map +1 -1
- package/dist/tools/edge-staleness.js +115 -0
- package/dist/tools/edge-staleness.js.map +1 -1
- package/dist/tools/edges.d.ts.map +1 -1
- package/dist/tools/edges.js +94 -0
- package/dist/tools/edges.js.map +1 -1
- package/dist/tools/read.d.ts +14 -0
- package/dist/tools/read.d.ts.map +1 -1
- package/dist/tools/read.js +385 -6
- package/dist/tools/read.js.map +1 -1
- package/dist/tools/receipt.d.ts +1 -1
- package/dist/tools/receipt.d.ts.map +1 -1
- package/dist/tools/receipt.js +147 -2
- package/dist/tools/receipt.js.map +1 -1
- package/dist/tools/search.d.ts.map +1 -1
- package/dist/tools/search.js +456 -5
- package/dist/tools/search.js.map +1 -1
- package/dist/tools/staged-actions.d.ts +7 -0
- package/dist/tools/staged-actions.d.ts.map +1 -1
- package/dist/tools/staged-actions.js +106 -2
- package/dist/tools/staged-actions.js.map +1 -1
- package/dist/tools/themes.d.ts.map +1 -1
- package/dist/tools/themes.js +120 -0
- package/dist/tools/themes.js.map +1 -1
- package/dist/tools/tier1.d.ts.map +1 -1
- package/dist/tools/tier1.js +56 -0
- package/dist/tools/tier1.js.map +1 -1
- package/dist/tools/tier2.d.ts.map +1 -1
- package/dist/tools/tier2.js +111 -1
- package/dist/tools/tier2.js.map +1 -1
- package/dist/tools/witness.d.ts.map +1 -1
- package/dist/tools/witness.js +93 -0
- package/dist/tools/witness.js.map +1 -1
- package/dist/tools/write.d.ts +8 -0
- package/dist/tools/write.d.ts.map +1 -1
- package/dist/tools/write.js +391 -3
- package/dist/tools/write.js.map +1 -1
- package/dist/utils/config.d.ts +2 -0
- package/dist/utils/config.d.ts.map +1 -1
- package/dist/utils/config.js +74 -0
- package/dist/utils/config.js.map +1 -1
- package/package.json +5 -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 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`
|
|
@@ -93,6 +222,14 @@ deterministic summary flags, the vault's git HEAD as an as-of anchor, and a
|
|
|
93
222
|
recomputable hash over the whole receipt. Attach it to the answer so any
|
|
94
223
|
consumer can see what the answer stands on.
|
|
95
224
|
|
|
225
|
+
**Believe:** `vault_canon` — compute settled vs. contested belief across
|
|
226
|
+
holders over an emergent topic (params: `seed`, `holders?`, `as_of?`,
|
|
227
|
+
`depth?`). Returns a per-claim settled/contested classification, integrity
|
|
228
|
+
flags (`graph_completeness: "curated"`, `partial_visibility`, `unindexed`,
|
|
229
|
+
`ghost_holder_warning`), and an attached `vault_receipt` as the epistemic
|
|
230
|
+
anchor. Recorded, not omniscient: settled means no contradiction is on record,
|
|
231
|
+
not that none exists. Never auto-resolves.
|
|
232
|
+
|
|
96
233
|
**Witness:** `vault_witness` — per-principal track records from the vault's
|
|
97
234
|
own ledgers, priced by the wager schedule: write volume, live claims with
|
|
98
235
|
open exposure, contested claims with stake at risk, the settled book
|
|
@@ -100,21 +237,30 @@ open exposure, contested claims with stake at risk, the settled book
|
|
|
100
237
|
deterministic; includes the flat-curve monitor so a single-author vault is
|
|
101
238
|
reported as uninformative rather than as signal.
|
|
102
239
|
|
|
240
|
+
<details>
|
|
241
|
+
<summary><b>The full per-category tool registry and the tool-tier config (▸ expand for full reference)</b></summary>
|
|
242
|
+
|
|
103
243
|
**Search:** `vault_search` (hybrid BM25 + vector; hits carry their unresolved
|
|
104
244
|
tensions inline and foreground the current source of superseded documents),
|
|
105
245
|
`vault_search_related`, `vault_themes` (thematic clustering), `vault_reindex`
|
|
106
246
|
|
|
107
|
-
**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)
|
|
108
250
|
|
|
109
|
-
**
|
|
251
|
+
**Edges:** `vault_edge_observe`, `vault_edge_contest`, `vault_edges`, `vault_consumes` (query the compiled dependency graph)
|
|
110
252
|
|
|
111
|
-
**
|
|
253
|
+
**Dispatch:** `vault_tier1` (type-directed change dispatch), `vault_tier2_queue`, `vault_tier2_verdict` (semantic-review queue + verdict)
|
|
112
254
|
|
|
113
255
|
**Ratify:** `vault_stage_action`, `vault_ratify`
|
|
114
256
|
|
|
115
257
|
The curation engine is advisory: `vault_lint` reports problems and
|
|
116
258
|
`vault_tension_log` records contradictions. Neither auto-fixes anything. Every
|
|
117
|
-
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.
|
|
118
264
|
|
|
119
265
|
### Tool tiers
|
|
120
266
|
|
|
@@ -134,291 +280,157 @@ tools:
|
|
|
134
280
|
`core` is the search-before-derive loop (`vault_search`, `vault_read`,
|
|
135
281
|
`vault_write`, `vault_index`, `vault_lint`, `vault_status`); `standard` adds
|
|
136
282
|
the full document lifecycle (append/promote/deprecate/supersede/merge,
|
|
137
|
-
confidence and tier setters, propose/ratify) plus
|
|
138
|
-
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
|
|
139
285
|
only changes what is *advertised* — calls to any registered tool still work,
|
|
140
286
|
so an agent holding a cached tool name keeps working across a tier change.
|
|
141
287
|
Unknown names in `include`/`exclude` warn at startup and are ignored, so a
|
|
142
288
|
config written for a newer daftari still loads.
|
|
143
289
|
|
|
290
|
+
</details>
|
|
291
|
+
|
|
144
292
|
**Evaluate (opt-in, requires an Anthropic API key):** `daftari eval` — scores how
|
|
145
293
|
well an LLM can use the curation surface to answer multi-hop questions about the
|
|
146
294
|
vault. See the [design spec](docs/superpowers/specs/2026-05-31-cortex-quality-metric-design.md)
|
|
147
295
|
for the rationale and the cortex framing.
|
|
148
296
|
|
|
149
|
-
##
|
|
150
|
-
|
|
151
|
-
Every document declares a `domain`. The distinction drives how the curation
|
|
152
|
-
layer treats it.
|
|
297
|
+
## Circadian memory
|
|
153
298
|
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
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):
|
|
157
301
|
|
|
158
|
-
|
|
159
|
-
|
|
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
|
+
```
|
|
160
306
|
|
|
161
|
-
The
|
|
162
|
-
|
|
163
|
-
|
|
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.
|
|
164
314
|
|
|
165
|
-
|
|
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.
|
|
166
320
|
|
|
167
|
-
|
|
321
|
+
## Tension Court
|
|
168
322
|
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
read: ["*"]
|
|
176
|
-
write: [moonshot, _drafts]
|
|
177
|
-
admin:
|
|
178
|
-
read: ["*"]
|
|
179
|
-
write: ["*"]
|
|
180
|
-
promote: true
|
|
181
|
-
ratify: true # may approve/reject staged actions and contest edges
|
|
182
|
-
```
|
|
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.
|
|
183
329
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
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.
|
|
187
334
|
|
|
188
|
-
|
|
335
|
+
```bash
|
|
336
|
+
# The docket — a 5-minute weekly ritual
|
|
337
|
+
daftari court --vault ./my-vault
|
|
189
338
|
|
|
190
|
-
|
|
191
|
-
|
|
339
|
+
# One case's full brief (verbatim rationales from cited precedents)
|
|
340
|
+
daftari court --tension tension-abc123
|
|
192
341
|
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
domain: accumulation
|
|
197
|
-
collection: competitive-intel
|
|
198
|
-
status: canonical
|
|
199
|
-
confidence: medium
|
|
200
|
-
created: 2026-05-17
|
|
201
|
-
updated: 2026-05-17
|
|
202
|
-
updated_by: agent:claude-code
|
|
203
|
-
provenance: synthesized
|
|
204
|
-
sources:
|
|
205
|
-
- aurora-product-page
|
|
206
|
-
ttl_days: 120
|
|
207
|
-
tags: [aurora, ingestion, competitive]
|
|
208
|
-
questions_answered:
|
|
209
|
-
- "How does Aurora frame the ingestion/transformation boundary?"
|
|
210
|
-
questions_raised:
|
|
211
|
-
- "Does an authored-pipeline model slow teams down at small scale?"
|
|
212
|
-
---
|
|
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."
|
|
213
345
|
```
|
|
214
346
|
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
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.
|
|
220
353
|
|
|
221
|
-
##
|
|
354
|
+
## The principal interview
|
|
222
355
|
|
|
223
|
-
|
|
224
|
-
|
|
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:
|
|
225
361
|
|
|
226
362
|
```bash
|
|
227
|
-
#
|
|
228
|
-
daftari
|
|
363
|
+
# The sheet — read-only, priority-ordered
|
|
364
|
+
daftari interview --vault ./my-vault
|
|
229
365
|
|
|
230
|
-
#
|
|
231
|
-
daftari
|
|
366
|
+
# Sit for it. Answers are recorded VERBATIM; empty skips, 'q' ends.
|
|
367
|
+
daftari interview ask --vault ./my-vault
|
|
232
368
|
```
|
|
233
369
|
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
### Cloud-synced vaults (iCloud, Dropbox, …)
|
|
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.
|
|
244
378
|
|
|
245
|
-
|
|
246
|
-
|
|
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.
|
|
247
383
|
|
|
248
|
-
|
|
249
|
-
daftari import obsidian "~/Library/Mobile Documents/.../my-vault" \
|
|
250
|
-
--apply --scope notes --external-git-dir
|
|
251
|
-
```
|
|
384
|
+
## Belief archaeology
|
|
252
385
|
|
|
253
|
-
|
|
254
|
-
`
|
|
255
|
-
|
|
256
|
-
Pass `--external-git-dir=/path` for an explicit location, or set `git_dir`
|
|
257
|
-
directly in config to apply the same to any vault. History is per-device; your
|
|
258
|
-
notes still sync everywhere.
|
|
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:
|
|
259
389
|
|
|
260
|
-
|
|
390
|
+
```bash
|
|
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
|
|
261
393
|
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
Use it directly for non-Obsidian trees:
|
|
394
|
+
# One document's trajectory: frontmatter then vs now, commits in between
|
|
395
|
+
daftari asof HEAD~20 --doc pricing/helios-consumption-pricing.md
|
|
265
396
|
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
daftari
|
|
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
|
|
269
400
|
```
|
|
270
401
|
|
|
271
|
-
|
|
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`.
|
|
272
411
|
|
|
273
|
-
|
|
274
|
-
is Google Cloud's vendor-neutral spec for the LLM-wiki pattern: a directory of
|
|
275
|
-
markdown files with YAML frontmatter that any producer can emit and any consumer
|
|
276
|
-
can read without translation. A Daftari vault *is* that pattern, so `daftari
|
|
277
|
-
okf` bridges the two directions.
|
|
278
|
-
[v0.2](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals/)
|
|
279
|
-
adds opt-in **trust signals** — raw credibility indicators (provenance,
|
|
280
|
-
verification, lifecycle, freshness), never computed scores — and Daftari maps
|
|
281
|
-
them from/to its native metadata.
|
|
282
|
-
|
|
283
|
-
**Export** renders the vault as a portable OKF bundle — every doc becomes an OKF
|
|
284
|
-
concept doc (the core `type` / `title` / `description` / `resource` / `tags`
|
|
285
|
-
fields, plus a verbatim `daftari` sidecar for lossless round-trip), with
|
|
286
|
-
generated `index.md` (progressive-disclosure listing) and `log.md`
|
|
287
|
-
(chronological history). Trust signals derive from native metadata:
|
|
288
|
-
`updated`/`updated_by` become `generated`, the lifecycle maps to
|
|
289
|
-
`draft`/`stable`/`deprecated`, `ttl_days` becomes an absolute `stale_after`
|
|
290
|
-
date, and `sources` become structured entries. `verified` is never fabricated —
|
|
291
|
-
Daftari records authorship, not independent confirmations, so exported docs
|
|
292
|
-
honestly read as unverified. The source vault is never mutated.
|
|
293
|
-
|
|
294
|
-
```bash
|
|
295
|
-
daftari okf export ./my-vault --out ./okf-bundle
|
|
296
|
-
daftari okf export ./my-vault --out ./okf-bundle --collection pricing
|
|
297
|
-
```
|
|
298
|
-
|
|
299
|
-
**Import** adopts an OKF bundle into a vault. A bundle produced by `okf export`
|
|
300
|
-
round-trips exactly via its sidecar; a foreign bundle is mapped conservatively
|
|
301
|
-
(docs land as `draft` in the `accumulation` domain, the original OKF `type` is
|
|
302
|
-
preserved in an `okf_type` field). Trust signals inform the mapping: a
|
|
303
|
-
human-reviewed doc (a `human:*` entry in `verified`) imports with `confidence:
|
|
304
|
-
high`, `status: deprecated` stays `deprecated` (retired knowledge must not
|
|
305
|
-
resurface as a fresh draft), and `stale_after` converts to `ttl_days`. An
|
|
306
|
-
`Attested Computation` is surfaced in an import warning but **not**
|
|
307
|
-
auto-write-protected: `tier: source` is enforcement, and its only sanctioned
|
|
308
|
-
grant path is `vault_set_tier` (reason required, provenance-logged) — a foreign
|
|
309
|
-
bundle's self-declared `type` doesn't buy it. Review the doc, then elevate
|
|
310
|
-
deliberately. OKF fields with no lossless Daftari slot (the trust record,
|
|
311
|
-
attestation machinery) are preserved under `okf_*` keys. Writes auto-commit and
|
|
312
|
-
the index is rebuilt.
|
|
313
|
-
|
|
314
|
-
```bash
|
|
315
|
-
daftari okf import ./okf-bundle --into ./my-vault --dry-run
|
|
316
|
-
daftari okf import ./okf-bundle --into ./my-vault
|
|
317
|
-
```
|
|
318
|
-
|
|
319
|
-
## Server mode (self-hosted)
|
|
320
|
-
|
|
321
|
-
By default daftari is a per-user stdio process. `daftari serve` starts the
|
|
322
|
-
same vault as **one always-on instance over Streamable HTTP** — for a team, or
|
|
323
|
-
for clients that can't spawn a local process (claude.ai web/mobile, Cowork):
|
|
324
|
-
|
|
325
|
-
```bash
|
|
326
|
-
daftari serve --vault ./my-vault # http://127.0.0.1:8787/mcp
|
|
327
|
-
daftari serve --vault ./my-vault --bind 0.0.0.0 --port 9000
|
|
328
|
-
```
|
|
329
|
-
|
|
330
|
-
Identity is **per MCP session**, resolved when the session opens, so every
|
|
331
|
-
RBAC and existence-disclosure rule applies per connection with zero tool
|
|
332
|
-
changes. Two composable auth schemes, both declared in config:
|
|
333
|
-
|
|
334
|
-
```yaml
|
|
335
|
-
server:
|
|
336
|
-
transport_security: external # required off-loopback: TLS terminates upstream
|
|
337
|
-
auth:
|
|
338
|
-
tokens: # static bearer tokens (agents, ETL)
|
|
339
|
-
- env: DAFTARI_TOKEN_ETL # the VALUE lives in this env var, never in config
|
|
340
|
-
user: agent:etl
|
|
341
|
-
role: admin
|
|
342
|
-
oauth: # OAuth 2.1 resource server (humans via your IdP)
|
|
343
|
-
issuer: https://idp.example.com
|
|
344
|
-
audience: daftari
|
|
345
|
-
jwks_uri: https://idp.example.com/.well-known/jwks.json
|
|
346
|
-
subjects:
|
|
347
|
-
"alice@example.com": { user: human:alice, role: analyst }
|
|
348
|
-
```
|
|
349
|
-
|
|
350
|
-
The posture is fail-loud, never silent-downgrade: a non-loopback bind refuses
|
|
351
|
-
to start without auth **and** the explicit `transport_security: external`
|
|
352
|
-
acknowledgment (daftari never terminates TLS itself — put Caddy/nginx/a load
|
|
353
|
-
balancer in front); with any auth configured, a bad or missing credential is
|
|
354
|
-
a 401 at session open and a valid JWT whose subject isn't mapped is a 403 —
|
|
355
|
-
neither ever becomes the guest. Guest sessions exist only in the no-auth
|
|
356
|
-
loopback configuration. A running server also refuses to be silently killed:
|
|
357
|
-
stray stdio invocations against the same vault refuse to start, and replacing
|
|
358
|
-
a live holder requires a deliberate `daftari serve --takeover`.
|
|
359
|
-
|
|
360
|
-
## Storage backing
|
|
361
|
-
|
|
362
|
-
A self-hosted vault can push to durable object storage (#6). The local git
|
|
363
|
-
working copy stays canonical — reads, writes, auto-commits, locks, and the
|
|
364
|
-
index all stay exactly as above — and the backing is a dumb sync target:
|
|
365
|
-
|
|
366
|
-
```yaml
|
|
367
|
-
# .daftari/config.yaml
|
|
368
|
-
storage:
|
|
369
|
-
backend: s3 # fs | s3 | azure
|
|
370
|
-
bucket: team-vault
|
|
371
|
-
region: us-east-1
|
|
372
|
-
# endpoint: https://… # MinIO / R2 / GCS S3-interop endpoints
|
|
373
|
-
# sync_interval_minutes: 15 # daftari serve pushes on this cadence
|
|
374
|
-
```
|
|
375
|
-
|
|
376
|
-
```bash
|
|
377
|
-
daftari sync --vault ./my-vault # incremental push
|
|
378
|
-
daftari sync --vault ./my-vault --dry-run # show the diff only
|
|
379
|
-
daftari sync --vault ./empty-dir --restore --backend s3 --bucket team-vault
|
|
380
|
-
```
|
|
381
|
-
|
|
382
|
-
The push covers the markdown tree, the `.git` directory, and durable
|
|
383
|
-
`.daftari` journals; the rebuildable SQLite index and lock files never sync.
|
|
384
|
-
Neither do `.git/config` and `.git/hooks` — git *executes* what those
|
|
385
|
-
declare, and a backup channel must not deliver code (`git clone` refuses to
|
|
386
|
-
transmit them for the same reason), so re-add remotes and local git config
|
|
387
|
-
by hand after a restore.
|
|
388
|
-
Cloud backends load their SDKs (`@aws-sdk/client-s3`, `@azure/storage-blob`)
|
|
389
|
-
as optional dependencies — install the one you use; credentials come from the
|
|
390
|
-
SDK's standard environment chain, never from vault config. GCS is reached via
|
|
391
|
-
its S3-interoperability endpoint. Restore refuses non-empty directories and
|
|
392
|
-
reindexes when done.
|
|
412
|
+
## The vault as witness — and the wager layer
|
|
393
413
|
|
|
394
|
-
|
|
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.
|
|
395
424
|
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|Who writes? |Humans |Nobody (retrieval only) |Agents + humans |
|
|
399
|
-
|Scales? |One file, doesn’t|Scales storage, not coherence|Structured collections with lifecycle|
|
|
400
|
-
|Knowledge compounds?|No |No |Yes, draft → canonical → deprecated |
|
|
401
|
-
|Contradictions? |Invisible |Invisible |Tension log surfaces them |
|
|
402
|
-
|Staleness? |Silent |Silent |TTL-based decay with advisory lint |
|
|
425
|
+
<details>
|
|
426
|
+
<summary><b>The two kill conditions that travel with the tool (▸ expand for full reference)</b></summary>
|
|
403
427
|
|
|
404
|
-
|
|
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).
|
|
405
432
|
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
- **Cloud-hosted multi-tenant SaaS** (self-hosted server mode HAS shipped —
|
|
409
|
-
see [Server mode](#server-mode-self-hosted) and
|
|
410
|
-
[Storage backing](#storage-backing); the project itself hosts nothing)
|
|
411
|
-
- **Conflict resolution beyond file-level locks** (CRDTs, semantic merge)
|
|
412
|
-
- **Background curation agent** running lint on a cadence
|
|
413
|
-
- **Enforced domain separation** (v1 documents the convention; v2 enforces it —
|
|
414
|
-
advisory boundary warnings shipped in the meantime: `vault_lint`'s
|
|
415
|
-
`domainLeaks` check and write-time `domain_warnings`)
|
|
416
|
-
|
|
417
|
-
(LLM reranking, deferred here originally, has since shipped as the opt-in
|
|
418
|
-
agent-as-judge `rerank_candidates` on `vault_search`: the server prepares the
|
|
419
|
-
fused candidate pool and the protocol; the calling agent is the judge.)
|
|
420
|
-
|
|
421
|
-
Each is a clean increment on a surface that already works.
|
|
433
|
+
</details>
|
|
422
434
|
|
|
423
435
|
## Coherence audit
|
|
424
436
|
|
|
@@ -485,6 +497,9 @@ staleness check still runs over the in-repo link graph.
|
|
|
485
497
|
Catches the case where you keep touching an index page while the docs it
|
|
486
498
|
links to are rotting.
|
|
487
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
|
+
|
|
488
503
|
### Sample output
|
|
489
504
|
|
|
490
505
|
```markdown
|
|
@@ -579,131 +594,245 @@ fail_on:
|
|
|
579
594
|
transitive_staleness: 100 # default: generous; teams tune
|
|
580
595
|
```
|
|
581
596
|
|
|
582
|
-
|
|
597
|
+
</details>
|
|
583
598
|
|
|
584
|
-
|
|
585
|
-
tension a logger and a ruling. `vault_witness` aggregates that ledger into a
|
|
586
|
-
**track record per principal** — and prices it. Confidence is free to claim,
|
|
587
|
-
so the wager schedule makes it cost something: writing at `high` stakes 3
|
|
588
|
-
points, `medium` 1, `low` 0 (hedged claims are the honest default and are
|
|
589
|
-
never taxed). A claim later corrected by a ruling or retired by someone else
|
|
590
|
-
burns the stake; a claim maintained through a full TTL cycle earns credit.
|
|
591
|
-
The balance is arithmetic on recorded facts — advisory, provisional
|
|
592
|
-
constants, nothing enforced: routing a high-stakes write to the agent with
|
|
593
|
-
the earned balance is your policy, not the vault's. Both kill conditions
|
|
594
|
-
from the design travel with the tool: the flat-curve monitor (one author ≥95%
|
|
595
|
-
of writes → curves declared uninformative) and the longitudinal write-volume
|
|
596
|
-
series (if stake-fear suppresses honest claims, it shows up here first).
|
|
599
|
+
<!-- Running it -->
|
|
597
600
|
|
|
598
|
-
##
|
|
601
|
+
## Access control
|
|
599
602
|
|
|
600
|
-
|
|
601
|
-
|
|
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):
|
|
602
633
|
|
|
603
634
|
```bash
|
|
604
|
-
|
|
605
|
-
|
|
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
|
|
606
637
|
```
|
|
607
638
|
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
`.daftari/wake-queue.jsonl` for an external agent to consume — re-verify each
|
|
612
|
-
document against its sources, stage the diff — because the vault never
|
|
613
|
-
re-verifies on its own. Generative documents going stale are expected, not a
|
|
614
|
-
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.
|
|
615
642
|
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
the rubber-stamp monitor — zero rejections over a long decision history is
|
|
619
|
-
printed as a warning, not a compliment. The agent proposes overnight; you
|
|
620
|
-
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>
|
|
621
645
|
|
|
622
|
-
|
|
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
|
+
```
|
|
623
661
|
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
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
|
+
```
|
|
630
692
|
|
|
631
693
|
```bash
|
|
632
|
-
|
|
633
|
-
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
|
+
```
|
|
634
698
|
|
|
635
|
-
|
|
636
|
-
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.
|
|
637
710
|
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
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
|
|
641
724
|
```
|
|
642
725
|
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
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.
|
|
649
734
|
|
|
650
|
-
|
|
735
|
+
### Cloud-synced vaults (iCloud, Dropbox, …)
|
|
651
736
|
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
first, longest-carried first), canonical accumulation docs past their TTL,
|
|
655
|
-
and `questions_raised` entries no document answers — deterministic and
|
|
656
|
-
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:
|
|
657
739
|
|
|
658
740
|
```bash
|
|
659
|
-
|
|
660
|
-
|
|
741
|
+
daftari import obsidian "~/Library/Mobile Documents/.../my-vault" \
|
|
742
|
+
--apply --scope notes --external-git-dir
|
|
743
|
+
```
|
|
661
744
|
|
|
662
|
-
|
|
663
|
-
|
|
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
|
|
664
761
|
```
|
|
665
762
|
|
|
666
|
-
|
|
667
|
-
collection — `tier: source` (your words, body immutable), `provenance:
|
|
668
|
-
direct`, no TTL (testimony doesn't expire) — committed like any other write,
|
|
669
|
-
with `sources` tracing each question back to the tension or document that
|
|
670
|
-
prompted it. The pattern is the companion interview on a living-summary
|
|
671
|
-
page: the compiler's highest-value move is not more compilation, it is
|
|
672
|
-
asking the principal about the unclear spots and folding the verbatim
|
|
673
|
-
answers back into the corpus.
|
|
763
|
+
## Open Knowledge Format (OKF)
|
|
674
764
|
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
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.
|
|
679
774
|
|
|
680
|
-
|
|
775
|
+
<details>
|
|
776
|
+
<summary><b>OKF export / import field-mapping and the <code>daftari okf</code> commands (▸ expand for full reference)</b></summary>
|
|
681
777
|
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
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.
|
|
685
788
|
|
|
686
789
|
```bash
|
|
687
|
-
|
|
688
|
-
daftari
|
|
790
|
+
daftari okf export ./my-vault --out ./okf-bundle
|
|
791
|
+
daftari okf export ./my-vault --out ./okf-bundle --collection pricing
|
|
792
|
+
```
|
|
689
793
|
|
|
690
|
-
|
|
691
|
-
|
|
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.
|
|
692
808
|
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
daftari
|
|
809
|
+
```bash
|
|
810
|
+
daftari okf import ./okf-bundle --into ./my-vault --dry-run
|
|
811
|
+
daftari okf import ./okf-bundle --into ./my-vault
|
|
696
812
|
```
|
|
697
813
|
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
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.
|
|
707
836
|
|
|
708
837
|
## Development
|
|
709
838
|
|
|
@@ -725,7 +854,7 @@ Design tenets: functions and types, no classes; tool handlers return
|
|
|
725
854
|
## Integrations
|
|
726
855
|
|
|
727
856
|
- [`integrations/langchain/`](integrations/langchain/) — `langchain-daftari`, a
|
|
728
|
-
Python package that exposes
|
|
857
|
+
Python package that exposes all 35 daftari tools as LangChain `BaseTool`s
|
|
729
858
|
for use with LangGraph / `create_react_agent`. Sync + async, schemas pulled
|
|
730
859
|
live from `tools/list`.
|
|
731
860
|
- [`packages/router`](packages/router) — multi-vault MCP router that fans out across N Daftari vaults
|
|
@@ -745,3 +874,4 @@ retention, and contact.
|
|
|
745
874
|
## License
|
|
746
875
|
|
|
747
876
|
MIT.
|
|
877
|
+
|