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

Quick Start

Rust

[dependencies]
macrame-db = "0.9"

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(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)
• Cooperative chunking — bounded to ~3 ms per chunk, four paths with different row counts (90 edges, 70 concepts, 600 annotations, 30 embeddings)

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.9.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, with six intermediate groups for catching sets: IntegrityError, ValidationError, VectorError, TemporalError, WriterError, BudgetError.
• metrics shipped on — The wheel ships with the metrics feature enabled because feature flags do not survive into binary artifacts.

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.

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; the row is also the one this project already flags as complexity-bound rather than a stable constant, since it remains linear in out-degree. It is reported as measured and attributed to nothing.

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 is a fixture measurement and the caveat is the load-bearing part: it is under budget on this fixture and remains linear in out-degree, so a high-degree hub still exceeds it. Dropping idx_lc_tgt_active bought −7.9% on that path (D-118); it did not change the complexity.

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

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 — v0.9.0 reference: API, schema, decisions, performance
• Python bindings — §14: async→sync boundary, error tree, stubs
• Decision register — D-001…D-109 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.