mache

command module

v0.8.0 Latest Latest Go to latest Published: May 9, 2026 License: Apache-2.0 Imports: 1 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/agentic-research/mache

Links

README ¶

Mache

Mache turns code and structured data into a navigable graph — functions, types, cross-references, and call chains — exposed as MCP tools or a mounted filesystem.

Point it at a codebase. It parses the code, discovers the structure, and lets your agent (or you) explore by following call chains, jumping to definitions, and reading context — instead of grepping through flat files.

Mache (/mɑʃe/ mah-shay): from papier-mâché — raw material, crushed and remolded into shape.

Mache Demo

Quick start

git clone https://github.com/agentic-research/mache.git
cd mache && task build && task install
mache serve .
claude mcp add --transport http mache http://localhost:7532/mcp

That's the 30-second path. For the full first-run flow — install on Linux/macOS, Claude Desktop / stdio configs, mount as filesystem, write-back, schema inference, troubleshooting — see GETTING-STARTED.md.

What it gives an agent

Seventeen MCP tools wrap the projected graph (sixteen read-surface plus write_file). Fourteen work standalone; three (semantic_search, get_type_info, get_diagnostics) require ley-line-open enrichment. find_smells covers nine structural code-smell rules (dead_code, cyclomatic_complexity, god_file, fan_out_skew, untested_function, …); four of those require an LLO-built .db.

For the full tool inventory and capability matrix (which tools need which tables), see ARCHITECTURE.md § MCP Server and § Interplay with ley-line-open.

How it works

flowchart LR
    Source["source dir"] -->|"tree-sitter (CGO)<br/>OR leyline parse"| Graph
    LSP["LLO leyline lsp<br/>(LSP enrichment)"] -->|"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

Parse — tree-sitter parses source into AST nodes (28 languages). LLO's leyline parse is the modern path; CGO SitterWalker is the fallback.
Infer — schema inference (FCA + greedy entropy) discovers the natural groupings (functions/, types/, classes/)
Link — cross-reference extraction builds a call graph from identifiers and imports. When LLO's LSP pass 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.
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.

Status

Capability	Status
Tree-sitter parsing (28 langs)	Stable
MCP server (17 tools, stdio + HTTP)	Stable
Cross-repo serve (`--mount NAME=PATH`)	Stable (find_callers federates; find_callees stays per-mount for now)
Cross-references (callers/callees)	Stable
`find_smells` (9 structural rules)	Stable. `fan_out_skew` is qualifier-aware via LLO `BindingRecord.qualifier`
Canonical views (ADR-0013)	Stable. `v_refs`/`v_defs` with fidelity poset (`mention` ⊑ `binding`)
Capnp event-log readthrough	Stable. `${db}.bindings.capnp` is the cross-runtime contract for binding refs
E2E tool harness + flamegraphs	Stable. `task profile-tools-pprof` + `task flamegraphs` produce per-tool pprof + SVG flamegraphs
`MemoryStore.{Defs,Refs}Map` cache	Stable. Memoized snapshots; invalidated on AddDef / AddRef / DeleteFileNodes
NFS mount + write-back	Stable
Schema inference (FCA)	Beta
Community detection (Louvain)	Beta
LSP enrichment (type info, diagnostics)	Optional — ley-line-open
Semantic search (embeddings)	Optional — ley-line-open

Why this exists

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 tree-sitter. 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.

The graph isomorphism argument

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.

Docs

Getting started — install + first run
Architecture — graph backends, write pipeline, virtual directories, LLO interplay
Roadmap — what's landed, near-term, long-term
ADRs — Architectural Decision Records
Prior art & landscape — what mache builds on, how it compares
Example schemas — NVD, KEV, Go source, MCP registry
Contributing

License

Apache 2.0

Documentation ¶

There is no documentation for this package.

Source Files ¶

View all Source files

main.go

Directories ¶

Path	Synopsis
api
cmd
graph Package graph provides the public graph API for mache.	Package graph provides the public graph API for mache.
ingest Package ingest provides the public ingestion API for mache.	Package ingest provides the public ingestion API for mache.
internal
control
graph Package graph — store.go defines the pluggable storage interface for persisting and restoring projected graphs to/from remote backends.	Package graph — store.go defines the pluggable storage interface for persisting and restoring projected graphs to/from remote backends.
ingest
lang Package lang is the single source of truth for all supported languages.	Package lang is the single source of truth for all supported languages.
lattice
leyline Package leyline provides Go bindings to the ley-line C FFI.	Package leyline provides Go bindings to the ley-line C FFI.
leyline/schema
linter
lsp Package lsp consumes LLO's typed event-log artifacts (.bindings.capnp, future .ast.capnp / .source.capnp) sitting next to a SQLite .db.	Package lsp consumes LLO's typed event-log artifacts (.bindings.capnp, future .ast.capnp / .source.capnp) sitting next to a SQLite .db.
lsp/bindings
materialize
nfsmount Package nfsmount provides an NFS-based mount backend for mache.	Package nfsmount provides an NFS-based mount backend for mache.
refsvtab
template Package template provides mache's schema template rendering functions.	Package template provides mache's schema template rendering functions.
treesitter/elixir
vfs Package vfs provides a pluggable virtual handler chain for mache's virtual path types (_schema.json, PROMPT.txt, _diagnostics/, context, callers/, callees/, .query/).	Package vfs provides a pluggable virtual handler chain for mache's virtual path types (_schema.json, PROMPT.txt, _diagnostics/, context, callers/, callees/, .query/).
writeback
materialize Package materialize provides the public materializer API for mache.	Package materialize provides the public materializer API for mache.
mount Package mount provides the public NFS mount API for mache.	Package mount provides the public NFS mount API for mache.
tools
fuzz-gen command
fuzz-gen/subject
fuzz-gen/tasks/task_1771121798
gen-lsp-fixture command gen-lsp-fixture generates a SQLite test fixture database that simulates the output of ley-line's ll-open/ts and ll-open/lsp pipelines.	gen-lsp-fixture generates a SQLite test fixture database that simulates the output of ley-line's ll-open/ts and ll-open/lsp pipelines.
mcp-fetch command mcp-fetch fetches MCP server entries from the official registry and stores them in a SQLite database compatible with mache.	mcp-fetch fetches MCP server entries from the official registry and stores them in a SQLite database compatible with mache.
notion-fetch command notion-fetch queries a Notion database via the Notion API and stores pages as JSON records in a SQLite database compatible with mache.	notion-fetch queries a Notion database via the Notion API and stores pages as JSON records in a SQLite database compatible with mache.
validate Package validate exposes tree-sitter syntax validation for external consumers.	Package validate exposes tree-sitter syntax validation for external consumers.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL