Macrame

A bitemporal graph ledger for knowledge management — embedded, single-file, no server.

Macrame stores concepts linked by typed, weighted relationships — where both concepts and relationships change over time, and the history of those changes is itself a first-class asset. Everything lives in one .db file on disk. No database server, no network protocol, no external service.

Why Macrame

as_of became as_of_valid and as_of_recorded in 0.13.2, and this is a break. Through 0.13.1 a single ts was compared against links.valid_from/valid_to — valid time — for the graph's shape and against transaction_log.recorded_at — transaction time — for concept attributes under AttributeMode::AtTime. So as_of("2020-06-01") returned the edges that held in 2020 labelled with what was believed in 2020: a title corrected today to fix a 2020 typo came back uncorrected. Right answer to "what did we believe"; wrong answer to "what was true", and the name promised the second.

The semantics were written down a release before they were changed, deliberately, so the change could be reviewed against a stated position rather than argued in the commit that made it (D-160, 0.12.17 → D-174, 0.13.2).

To migrate: as_of(t) for topology-at-t under current belief is now as_of_valid(t). as_of(t) paired with AttributeMode::AtTime, if what you wanted was belief as of t, is now as_of_recorded(t). Setting both is new and asks the bitemporal question. reconstruct() is unchanged.

as_of_recorded folds the hot transaction_log, so it raises RecordedInstantUnreachable on a database whose log has been archived — it takes a connection and no archive path, and answering from a partial fold would return nearly the right topology. AttributeMode::AtTime folds the same log for the text and raises the same error for the same reason (0.13.16). reconstruct() takes the path and answers the same question.

Quick Start

Rust

[dependencies]
macrame-db = "0.13"

use macrame::prelude::*;

async fn main() {
    let db = Database::open("knowledge.db").await?;

    db.upsert_concept(ConceptUpsert::new("quantum", "Quantum Computing")
        .valid_from("2026-01-01T00:00:00.000000Z"))
        .await?;

    db.upsert_concept(ConceptUpsert::new("entanglement", "Quantum Entanglement")
        .valid_from("2026-01-01T00:00:00.000000Z"))
        .await?;

    db.assert_edge(EdgeAssertion::new("quantum", "entanglement", "ENTAILS")
        .valid_from("2026-01-01T00:00:00.000000Z")
        .weight(1.0))
        .await?;

    let subgraph = db.traverse()
        .start_node("quantum")
        .max_depth(3)
        .execute(db.read_conn(), None)
        .await?;
}

Python

pip install macrame-db

import macrame

T0 = "2026-01-01T00:00:00.000000Z"

with macrame.Database.open("knowledge.db") as db:
    db.write_concepts([
        macrame.ConceptUpsert("quantum", "Quantum Computing", valid_from=T0),
        macrame.ConceptUpsert("entanglement", "Quantum Entanglement", valid_from=T0),
    ])
    db.assert_edge(
        macrame.EdgeAssertion("quantum", "entanglement", "ENTAILS", valid_from=T0)
    )
    graph = db.load_subgraph("quantum", 3, 1 << 20)
    print(graph.dijkstra("quantum"))

Architecture Highlights

Eight Doctrine Invariants

Every design decision derives from these invariants:

1. The boundary is sacred — Everything above libSQL is ours; everything below it is upstream. Never patch the engine.
2. Two clocks, never mixed — Valid time and transaction time are independent axes. No code path derives one from the other.
3. Assertions are immutable — Rows in links are never updated in place. The past is never rewritten; it is only ever superseded.
4. The ledger is a table, not the log — Transaction-time reconstruction reads transaction_log, not WAL or CDC frames.
5. No physical deletion in hot tables — Rows leave through the archive path only. Ad-hoc DELETE aborts at the trigger layer.
6. Derivative state is disposable — links_current is a rebuildable materialization. Drift is detectable, recoverable by rebuild.
7. Embeddings are immutable per version, excluded from the ledger — Vectors live in per-model tables; they never appear in transaction_log payloads.
8. Fidelity is a parameter, never a silent default — as_of_valid(ts), as_of_recorded(ts) and reconstruct(ts) say what they mean in their signatures.

Concurrency Model

• One writer — a dedicated Tokio task holds the sole write-capable connection
• Many readers — WAL journaling; readers never block on writer
• Two-tier priority channels — high-priority (user-driven) preempts low-priority (background)
• Shared as Arc<Database>, not cloned — every method but close() takes &self, and close() takes self because shutdown has exactly one owner; Arc::into_inner(db).expect("last handle").close().await is the pattern. Clone is refused rather than missing: cadence_stop is a cloneable watch::Sender whose drop is what stops the snapshot task, so a second copy keeps it running against a closing database with nothing raising an error (D-203)
• Cooperative chunking — bounded to ~3 ms per chunk, sized from each chunk's measured hold rather than from a constant, under four per-path ceilings (90 edges, 70 concepts, 600 annotations, 30 embeddings) and a 35-row floor

Operational Controls (0.13.0)

Everything below defaults to leave it alone. None of them spells "off" as the absent value, which is the failure the tri-state types exist to prevent (D-155) — a default that silently disables a mechanism reaches every caller who never heard of the knob.

analyze() misses the ~3 ms chunk budget by ~6× on a populated ledger, and that is reported rather than hidden. Measured: 19.1 ms at 40,000 edges. ANALYZE is one indivisible statement, and PRAGMA analysis_limit = 400 damps its cost 3–4× without making it independent of the table — the claim that it did was corrected in D-166 after §8's acceptance asked for a measurement instead of an argument. metrics().budget_violations() names analyze after every call and is meant to. The exemption could not be decided while one kind covered both analyze() and the optimize() that close() runs unprompted (D-168); that split shipped in 0.13.24, and both kinds stayed budget-counted for opposite reasons — Analyze's miss is structural and constant, Optimize's is rare and therefore the informative one (D-197).

Schema Versioning

v8 is the last rung that could change a primary key before the 1.0 freeze: rowid_pk INTEGER PRIMARY KEY costs id the primary key, and D-036 forbids a primary-key change after 1.0 (D-119). It also drops idx_annotations_label and idx_lc_tgt_active, which shipped in the v7 baseline with no query that seeks on them — measured at −7.9% off assert_edge (D-089, D-118).

Rust Implementation

Module Map

Python Bindings (v0.13.0)

Key design decisions

• Synchronous surface — The Write Actor serialises every write through one channel, so exposing await advertises concurrency the architecture does not grant.
• Opaque Subgraph — A #[pyclass] with forwarded accessors; .to_dict() for callers who want the copy. It paid for itself in 0.8.0: the crate re-represented EdgeRef and no binding signature moved, because there is no converted copy whose layout had to follow (D-101, D-123).
• Open intervals cross as None — Not a sentinel datetime, because datetime.max cannot survive .astimezone() east of UTC.
• Absent content crosses as None — load_subgraph does not fetch document text unless asked (content=True). "" cannot mark not loaded, because it is a valid value of the type (D-116, D-123).
• Every error is typed — 35 exception classes under MacrameError (36 including the base), of which six are intermediate groups for catching sets — IntegrityError, ValidationError, VectorError, TemporalError, WriterError, BudgetError — leaving 29 leaves.
• metrics shipped on — The wheel ships with the metrics feature enabled because feature flags do not survive into binary artifacts. It has been a Rust default since 0.12.11 too, so the two sides no longer differ (D-154).
• Parity is a wave, not a side effect — 0.13.0 closed six gaps at once (W6): the archive-session and chunk-row constants, registered_models() / declared_dimension(), the maintenance calls and tuning keywords above, and a clock seam for tests. A gap opened in the release that created the feature is the one that never becomes a convention — the constants had gone eight releases for want of being anyone's next task.
• The chunk-row constants are ceilings, not sizes — CHUNK_ROWS_EDGES and its three siblings bound the adaptive loop from above; a populated database converges below them. Dividing a batch by one to predict transaction count reads a 0.11.0 fact (D-161).
• Three methods are deliberately absent — raw(), read_conn() and shadow_step. The first two would dissolve the single-writer property or hand out a shared connection; the third is safe in Rust but its epoch obligation would cross as a convention where it is currently a type, on a method whose failure mode is a stale projection swapped over a live one without erroring (D-165). A test asserts all three stay absent, so adding one means answering the register rather than deleting a line.

Performance (measured, not gated)

Re-measured at 0.8.0, because B2 changed how a Subgraph is represented, B3 changed what a load carries, and B4 dropped an index — three reasons a table of 0.7.0 numbers would have been describing a different crate.

There is no 0.11.0 or 0.12.0 column, and the second absence needs a word. 0.11.0 changed no code that runs, so a column would have been a second measurement of the same crate. 0.12.0 does change one of these rows — bulk_import no longer commits 90-row chunks. 90 is now the ceiling it starts from and it settles at 35 within a chunk or two (D-146), so "chunk commit, edges, 90 rows" still names a real measurement of a real transaction and no longer names what that method does. A 0.12.0 column is not published rather than half-published: this table is a per-release series measured as a whole under one control, and adding one row measured in a different session is the practice D-070 and D-145 exist to prevent. What 0.12.0 measured instead is in §5.1.5, against the fixed size rather than against previous releases.

0.10.0's column is a full re-measurement, median of three sessions, controls published below. Every row is inside its budget. Eight of the ten are within ±8% of 0.9.0 — below the ~11% single-arm variance D-134 measured and far below D-070's ~29% session spread — which is the expected answer, because 0.10.0 changed no traversal, no search, no fold and no write path. control/select_1 reads 1.55–1.69 µs per group against D-090's recorded 1.589–1.639 µs, so the machine is where it was.

One row read high, and 0.12.0 explained it: the machine, not the chunk (D-145). Chunk commit has published 2.39 / 2.40 / 2.38 ms for three releases and this column reads 2.71 ms — five measurements at a 1.1% spread, which was taken at the time as evidence that a 14% rise could not be session variance. It was not evidence about that at all: a tight spread within a session says nothing about the spread between sessions, which D-070 had already measured at ~29%. Re-run over six sessions, the arm tracks control/select_1 monotonically — with the control at or below D-090's recorded band it reads 2.356 / 2.358 / 2.365 ms, a 0.4% spread agreeing with 2.39; with an elevated control it reads 2.54-2.73. The cell is left at 2.71 because that is what was measured here, and this table is a per-release series rather than a statement of current cost. The current cost is 2.39 ms.

It never overturned chunk_rows::EDGES, and by 0.11.0 it could not have. D-058 solved the 90-row constant against the 3 ms bound from the 2.39 ms figure, which is why a 14% move in that figure looked consequential. It is not any more: D-143 re-derived all four constants against the fixture matrix, on grounds that never mention this number. The constant stays at 90 for those reasons, and would have whichever way this row resolved.

Two controls, or the read-path numbers would mean nothing. A uniform improvement across unrelated paths is what a faster machine looks like, so: the fixed control/select_1 row reads 1.51–1.62 µs against the 1.589–1.639 µs D-090 recorded, and the chunk-commit path — which 0.8.0 did not touch — is 2.39 → 2.40 ms. The machine has not moved and an untouched path has not moved, so the 12–36% on the read paths is the code.

0.9.0 re-measured the same rows and the answer is "nothing moved", which is the result rather than the absence of one. 0.9.0 changed the archive path and two triggers; it touched no traversal, no search and no fold, so a table that showed a change would be evidence of a problem. Every carried-over row but one is within 3.2% of its 0.8.0 figure — the largest being three-hop traversal at −3.1% — with control/select_1 at 1.51–1.54 µs across every group.

The new row is the one 0.9.0 could plausibly have cost something. The v9 → v10 rung puts a WHEN NOT EXISTS (SELECT 1 FROM sqlite_master …) clause on the concepts insert log trigger, and it is evaluated on every concept write, not only during an archive. At 198 µs against a 3 ms budget the gating is not measurable on this fixture — worth stating, because "we added a subquery to the hot write path" is the kind of change that is usually paid for somewhere.

The single-assertion row reads 13% lower and that is not claimed as an improvement. Nothing in 0.9.0 touches the links write path, and no mechanism explains it. It is reported as measured and attributed to nothing. The 0.9.0 text added a second reason to distrust the figure — that the row is complexity-bound rather than a stable constant, "since it remains linear in out-degree" — and that half is now withdrawn: it was never measured, and D-134 measured it. What remains is an unexplained 13%, which is the smaller and more honest claim.

Figures are the median of three runs, and the reason is a 21% excursion that the control did not catch. The first pass read the full fold at 20.4 ms — with control/select_1 sitting normal at 1.59 µs — and two repeats returned 16.96 and 17.09 ms. A SELECT 1 round trip bounds machine, scheduler and engine-overhead noise; it does not bound page-cache state or fsync variance, so an I/O-bound row needs repetition as well as a control. D-070 put this project's session-to-session noise at ~29%, which is exactly the size of the thing that almost got written down here as a regression.

The single-assertion row's caveat is retired, and it was wrong for four minor versions. This paragraph used to say the row "remains linear in out-degree, so a high-degree hub still exceeds it". overlap_guard now measures the assertion into tables of 0, 2,000 and 8,000 edges — hub out-degree 0, 666 and 2,666 — at 983 / 920 / 882 µs, median of three sessions against a 1.52 µs control, so out-degree rises by thousands and latency does not move (D-134). The claim described the access path as it stood in 0.5.5 and has been false since the v5 → v6 rung shipped idx_lc_open_interval (D-059) — it outlived the defect by four releases because nothing measured it. The real cost is O(version count per edge key), which archival caps. Dropping idx_lc_tgt_active bought −7.9% on that path (D-118); the complexity claim it was said not to change was not there to change.

Those figures are a shape, not a decimal: session-to-session spread on this path is ~11%, and normalising by the control does not remove it (D-070).

All budgets measured on named reference hardware, and deliberately not CI gates (D-055) — an absolute ≤ 5 ms on a shared runner is an assertion about whichever machine picked up the job. Regression detection uses criterion baselines, machine against itself. See §9 of the architecture docs for full table.

Known Risks

--all-features is not a configuration this project supports or gates, and 0.10.0 stopped publishing a test count for it. --all-features is metrics + property-tests together, which puts the R15-prone binaries back inside the main run — the exact arrangement the step above exists to avoid. Measured 2026-08-07: 4 of 4 runs crashed at one attempt, and 4 of 5 still went red at the six-attempt retry budget the quarantined step uses. A required job that fails four times in five is not a gate, it is noise that teaches people to re-run CI without reading it. Run --features metrics and --features property-tests as the two separate steps CI does (D-140).

Minimum Supported Rust Version

1.88, verified rather than declared — cargo +1.88.0 check --all-features --all-targets passes and 1.85 does not. The constraint comes from libsql-ffi's build dependency chain (bindgen → which → home), not from this crate's own code (which needs only 1.73).

Documentation

• Architecture specification — normative surfaces: §4 (schema) and Appendix A (API)
• Architecture Quick Reference — API, schema, decisions, performance. Marked v0.12.0 and current to D-148; it does not yet carry the 0.13.0 wave (D-149…D-169) or the 0.13.x series toward 1.0 (D-170…D-212), which includes the public-surface changes of D-205…D-208 — so its API section names paths this crate no longer offers. Refreshing it is not scheduled, and that is recorded rather than glossed: it is a derived document, and the architecture set below is the one kept true by gates. This README said "v0.9.0 reference" until 0.12.25, which was wrong about its own pointer. Where it disagrees with the architecture set, the architecture set wins — it is the normative one.
• Python bindings — §14: async→sync boundary, error tree, stubs
• Decision register — D-001…D-173 with rationale

Naming

Distribution macrame-db, import macrame — on both crates.io and PyPI. The Rust side has no caveat: a crate's [lib] name is namespaced per build graph, so macrame-db providing macrame collides with nothing. site-packages is flat.

The PyPI package macrame is an unrelated, effectively abandoned build tool (0.0.1, 2021). If it installs a top-level macrame/, then installing both leaves two distributions contending for one directory — pip warns on file conflicts, so this is a known and non-silent risk. Importing as macrame_db is the fallback if it ever matters.

License

See LICENSE for details.