Under the hood

Two targets and a helper

Syncretic.app — SwiftUI only, macOS 26. App/ (window, model, session, settings, license, publishing), Shape/, Graph/ (canvas, inspector, composers, lens, arrange chrome), Ask/ (bar, engine, controls, results, pager), Build/ (panel, chat, review list, history), Notes/ (editor, tags, embeds, drawing, iPad bridge, export), Embedding/ (model manager, per-project service), MCP/ (service, tools, connections, received drafts), Canvas/ (viewport, edge geometry), Links/, Library/ (sidebar, gallery, palette), DesignSystem/ (Lumen theme, tips).
SyncreticKit — a Swift package with no UI, unit-tested: schema model and identifiers; the graph store (LadybugDB), DDL builder, value mapping, result paging; the Cypher guard, tokenizer and completion; scoped search and loose text matching; the AI client with Claude Code and Codex transports, prompt builder, query router, graph builder, shape designer, build history; the MCP protocol, tools and client configs; text chunking, the llama.cpp embedder, the embedding index and reconciler, the model downloader; link previews and the source reader; the project library; force layout and arrangement geometry; licensing.
syncretic-mcp — a small tool in the app bundle, not sandboxed, started by AI apps; it talks only to Syncretic on loopback.

Engines

LadybugDB through its official Swift bindings, prebuilt (fetched by a script, not checked in). All reads and writes use prepared, parameterised statements. The log is checkpointed into the file when a project closes.
llama.cpp as a prebuilt Metal-enabled xcframework, running the EmbeddingGemma 2 Q8_0 GGUF. The engine is loaded on first use, released after three minutes idle, and torn down carefully at quit so nothing is left on the GPU.
Quickdraw (bundled HTML/JS) for drawings, with an ipad.html served over the local network for Apple Pencil.

Pipelines

A question (Text to Cypher): question + rendered shape → structured JSON {cypher, explanation} → keyword guard → read-only transaction, 500-row cap → rows mapped to typed values → canvas highlight and table; errors go back for up to two repairs; the same question on the same shape reuses the saved query.

Auto: embedded properties present → router call (strategy, semantic query, scope, graph question, explanation) → one of four flows; the route is saved with a context fingerprint (SHA-256 of the routing prompt) and reused.

Vector: query → embedder → cosine over the sidecar index (Float32, Accelerate) within scope and candidates → band of 0.15 below the best → grouped per record, 20 matches → cards; the index is maintained by the reconciler on every edit.

Build: message + sources read locally + images → structured draft → reviewed against the shape (skipped items) and the graph (exact and similar titles via the title index) → changes’ queries run to find targets (repaired up to twice) → draft UI → one undoable plan: removals, inserts, fills, edits, relationships.

MCP: client → helper → loopback → the app’s tool handlers on the open session; proposals become Build turns marked with their source.

Layout

A force simulation (quadtree many-body, link springs, collision) steps two ticks at a time off the main thread while “alpha” is above a threshold; any change reheats it. An Arrangement is pure geometry: given each node’s value and lane, it says where every node belongs (rows, rings, spiral, stacks) and the simulation takes them there, with forces only keeping nodes apart in rows and off entirely in the other forms. The lens chrome (ruler, pills, bands) is drawn in screen space at one size.

Files

See How it works. The export is plain JSON; the database file is Ladybug’s own format and not interchangeable with Kuzu’s; vectors are a sidecar (embeddings.json + embeddings.vec), keyed by record id and property id with a hash of model, title and text.

Tests

swift test in Packages/SyncreticKit covers identifier sanitising, DDL, store CRUD against a temp database, the guard, prompt rendering, response parsing, chunking, the index, the reconciler, the router, scoped search, note embeds, build history, checkpoints, result paging, arrangement geometry and licensing. The embedding model itself is tested when its file is pointed at.