mache

Every projection follows the same shape: a schema declares the topology, walkers extract nodes and edges from the source (JSONPath for JSON, direct SQL for SQLite, AST queries for code), and the resulting graph is served over MCP or mounted as a filesystem. The source-code path — the most developed — looks like this:

flowchart LR
    Source["source dir"] -->|"leyline parse<br/>(pure Go)"| Graph
    LSP["leyline lsp<br/>(LSP enrichment from<br/>ley-line-open)"] -->|"sibling .bindings.capnp<br/>(typed event log)"| BindingLog
    BindingLog -->|"ReadBindingLog"| Graph["Graph<br/>(MemoryStore or<br/>SQLiteGraph)"]
    Graph -->|"v_refs / v_defs<br/>(canonical views,<br/>fidelity poset)"| MCP["MCP tools"]
    Graph -->|"NFS server"| FS["mounted fs"]
    MCP -. "primary" .- Agent["Agent<br/>(Claude Code, etc)"]
    FS -.- Agent

1. Parse — leyline parse (from ley-line-open) turns source into an _ast database. mache reads it pure-Go via the ASTWalker; in-process CGO tree-sitter was removed in ADR-0012 step 4.
2. Infer — schema inference (FCA + greedy entropy) discovers the natural groupings (functions/, types/, classes/)
3. Link — cross-reference extraction builds a call graph from identifiers and imports. When the LSP pass from ley-line-open has run, refs flow through a sibling .bindings.capnp typed event log (per ADR-0013) rather than SQL columns — the wire format is the cross-runtime contract.
4. Project — the graph is exposed as MCP tools (primary) or a mounted filesystem (optional)

The graph is the same on either path; MCP and the filesystem are two ways to talk to it.

Agents operate without topology. They see flat files, grep for strings, build a mental model, forget it next turn, rebuild it. The structure is in the data — functions call other functions, types reference types, configs depend on configs — but nothing exposes it.

Mache does. Point it at data, it figures out the shape. Source code gets parsed by leyline parse. JSON and YAML get walked. Schema inference discovers the natural groupings without config. The agent can then explore the topology directly: follow call chains, find definitions, read context, write back.

Built for agents first. The design choices — stable node paths across edits, identity-preserving write-back — exist because agents need to reference things reliably across turns. The outputs are human-discernible because the representations are filesystems and SQL, but the topology is the point.

Both structured data and filesystems are graphs. Your JSON object has nodes and edges (containment). Your filesystem has nodes and edges (parent-child). They're isomorphic.

Operating systems never formalized this mapping. Mache does:

• SQL is the graph operator — queries define projections from one topology to another
• Schema defines topology — the formal specification of how source nodes map to filesystem nodes
• The filesystem exposes traversal primitives: cd traverses an edge, ls enumerates children, cat reads node data

ADR-0011 takes this further: every navigable thing in mache (path, token, SHA, range, record, ref) is a Pointer; the graph is a network of pointers; mache resolves them on demand.

See Architecture for the full picture.

mache pins an exact ley-line-open release and caches it version-namespaced under ~/.mache/bin, which is not on PATH. So a bare leyline in your shell runs whatever copy PATH happens to hold — often an older one — against .db files mache parsed with the pin. Both are named leyline; neither warns. Since leyline v0.13.0 shipped leyline cdc enable / leyline cdc gc, invoking leyline directly is a real workflow, so this is a real skew.

Two subcommands make the version question unaskable instead of answered-by-PATH-convention:

# Absolute path of the pinned binary, and nothing else on stdout.
mache leyline path

# Compose it — version-correct by construction.
$(mache leyline path) cdc enable --db ./mache.db

# Or proxy straight through: args, stdin/stdout/stderr and exit status forwarded.
mache leyline exec -- cdc enable --db ./mache.db
mache leyline exec cdc gc --db ./mache.db

Both resolve through mache's pin-checked chokepoint, so a non-pinned leyline earlier on PATH is reported on stderr and ignored rather than silently used. Neither mutates PATH, your shell rc, or the unversioned ~/.mache/bin/leyline path (which stays never-written — see internal/leyline/binary_cache_path.go).

MACHE_NO_LEYLINE=1 still disables provisioning; MACHE_LEYLINE_BINARY still overrides the pin for LLO development.

mache cache push/pulls the projected .db as a content-addressed bundle so CI / new dev machines / agents don't re-parse a million lines on every cold start.

# Emit a portable bundle from a built db.
mache cache push --db ./mache.db ./cache-out

# Restore a fresh db from a bundle.
mache cache pull --out-db ./restored.db ./cache-out

# Push to a remote OCI registry (build-cache/v1 transport).
mache cache push --db ./mache.db ./cache-out \
    --remote https://cache.example.com --scope myrepo/abc123 --tag latest

# Pull from a remote registry into a local cache dir, then restore.
mache cache pull --out-db ./restored.db ./cache-in \
    --remote https://cache.example.com --scope myrepo/abc123 --ref latest

# CI-friendly: assert a bundle is intact + verifiable, without restoring.
mache cache verify \
    --remote https://cache.example.com --scope myrepo/abc123 --ref latest

When the source db has an _ast table, chunks carry the AST node rows too — pull restores both _source AND _ast, so the restored db is queryable without re-parsing. When _ast is absent, chunks are raw source bytes (Phase 1 fallback).

See docs/cache/phase-4-chunk-shape.md for the wire format and cloister-spec/build-cache/v1/ for the OCI transport spec.

Mache has two supported deployment shapes:

Bundle / image (canonical production path). Mache ships its own apko + melange configs to produce a distroless OCI image (mache:0.22.0, ~33MB, x86_64 + aarch64). This is the unit that a cluster orchestrator (e.g. cloister) deploys; inside the bundle, mache speaks to a co-located ley-line daemon over a UDS socket and is unreachable except via the orchestrator-mediated wire.

task image                          # → mache.tar (mache:0.22.0)
docker load -i mache.tar
docker run --rm -i mache:0.22.0 serve --stdio /path/to/source

Given a fixed melange.rsa signing key and pinned toolchain, the build is reproducible — same input git tree, same image hash. task image auto-generates a dev keypair when one is missing (APK signatures will differ across freshly-generated keys), so for byte-stable artifacts in CI inject a fixed keypair from a secret. The melange recipe builds with CGO_ENABLED=0 — mache is pure Go since ADR-0012 step 4 removed in-process tree-sitter. mache links no external C libraries; it consumes leyline as a subprocess/daemon over its UDS socket, not via FFI.

On release, mache also self-publishes a separate leyline-bundled multi-arch image to ghcr.io/agentic-research/mache (debian-slim + libsqlite3, since leyline links sqlite; the distroless apko image above stays the local-dev build). This image gets the ley-line-open-paired path with no runtime fetch.

Its ENTRYPOINT is ["mache", "serve"], so docker run args append to mache serve — do not repeat serve, or you get mache serve serve:

docker run --rm -i ghcr.io/agentic-research/mache:v0.22.0 --stdio /source

Mache declares its own source via server.json's packages[].oci entry, tag-pinned — see ARCHITECTURE.md § OCI distribution for the full framing.

Local / dev path — running mache serve or the root mount form (mache <mountpoint>) directly on your machine. Useful for laptop work, debugging, and writing schemas. In this mode mache may auto-discover or auto-download a leyline binary (legacy code path; the bundle ships everything, so this only kicks in for non-bundle invocations). Set MACHE_NO_LEYLINE=1 to disable auto-download in CI or when leyline-open hasn't published a release for your platform. Exposing this mode externally requires a reverse proxy in front for auth; mache itself does not implement perimeter auth (the bundle gets it from the orchestrator).