mache

🗂️ Mache

Mache (/mɑʃe/ mah-shay): From the French mâché, meaning "crushed and ground" (as in papier-mâché). Just as waste paper is shredded and remolded into strong, complex shapes, Mache remolds raw data into navigable filesystems.

Mache: The Graph-Native Filesystem

We realized that JSON, YAML, Source Code, and Filesystems are all just Graphs.

Mache is the engine that aligns them. It treats your structured data not as text to be parsed, but as a Graph to be mounted. By bridging the gap between your Data's structure (ASTs, Objects) and your OS's structure (Directories, Inodes), Mache allows you to traverse complex logic as easily as you traverse a directory tree.

And because it's a Graph, Mache gives you the ultimate tool to query it: SQL.

graph TD
    DH["<b>Data Graph</b><br/>(JSON / Code / YAML)"]

    root["Root Object"]
    root --> key1["{key}"]
    root --> key2["{key}"]
    root --> arr["[Array]"]
    key1 --> val["'value'"]
    key2 --> obj["{object}"]
    arr --> item["{item}"]

    bridge["<b>Mache Bridge: SQL Projection</b><br/>Graph → Tree"]

    OSH["<b>OS Graph</b><br/>(Filesystem)"]

    mount["/  (mount)"]
    mount --> dir1["/key/"]
    mount --> dir2["/key/"]
    mount --> dirArr["/Arr/"]
    dir1 --> file["file"]
    dir2 --> subdir["dir/"]
    dirArr --> itemdir["dir/"]

    DH --> root
    val --> bridge
    obj --> bridge
    item --> bridge
    bridge --> mount
    mount --> OSH

    style DH fill:#e1f5ff,stroke:#333,stroke-width:2px
    style bridge fill:#fff4e1,stroke:#333,stroke-width:2px
    style OSH fill:#ffe1f5,stroke:#333,stroke-width:2px
    style root fill:#b3e5fc
    style mount fill:#f8bbd0

The Core Insight: Graph Isomorphism

Both structured data and filesystems are graphs. Your JSON object has nodes (keys, arrays) and edges (containment). Your filesystem has nodes (files, directories) and edges (parent-child relationships). They're the same structure.

The gap exists because operating systems never formalized this mapping. Mache does:

• SQL is the graph operator. Queries define projections from one graph topology to another.
• Schema defines topology. It's not configuration—it's the formal specification of how source nodes map to filesystem nodes.
• The filesystem exposes traversal primitives (via NFS or FUSE):
  • cd traverses an edge
  • ls enumerates children
  • cat reads node data

This isn't metaphorical. Mache literally treats both sides as graphs and uses SQL to transform one into the other.

Table of Contents

• Status
• Feature Matrix
• Quick Start
• Usage
  • Example: NVD Vulnerability Database
  • Example: Projecting JSON Data
  • Example: Projecting Source Code
  • Write-Back Mode
  • Goto: Call-Chain Navigation
• How It Works
• Documentation
• Contributing
• License

Status

Mache is in early development. The core pipeline (schema + ingestion + FUSE mount) works end-to-end across multiple data sources.

Feature Matrix

Quick Start

Prerequisites

• macOS: brew install go-task (NFS backend is built-in, no fuse-t needed)
• macOS (FUSE backend): brew install --cask fuse-t (only if using --backend fuse)
• Linux: apt-get install libfuse-dev and install Task

Building

git clone https://github.com/agentic-research/mache.git
cd mache

# Build (checks for fuse-t on macOS, builds and codesigns)
task build

# Run tests
task test

Usage

Basic Commands

# Mount a SQLite database (instant — zero-copy, direct SQL queries)
./mache --schema examples/nvd-schema.json --data results.db /tmp/nvd

# Mount with zero-config schema inference (no schema authoring needed)
./mache --infer --data results.db /tmp/nvd

# Mount a JSON file (ingests into memory)
./mache --schema schema.json --data data.json /tmp/mount

# Mount source code with write-back (edits splice back into source files)
./mache --infer --data ./src --writable /tmp/mache-src

# Explicitly select backend (default: nfs on macOS, fuse on Linux)
./mache --backend nfs --infer --data results.db /tmp/nvd

Using with LLMs and Agents

Mache mounts as a standard POSIX filesystem — no special tooling required. LLMs can use normal file operations.

Quick Start - Agent Mode:

# Auto-mount your codebase with one command
mache --agent -d ~/my-project

# Mache will:
# - Auto-infer schema from your code
# - Enable write-back for editing
# - Mount to /tmp/mache/my-project-abc123/
# - Generate PROMPT.txt with instructions for your LLM
# - Track the mount with git-aware naming

# The mount runs in the foreground. Open a new terminal and:
cd /tmp/mache/my-project-abc123
cat PROMPT.txt    # Read agent instructions
claude            # Start your LLM

# When done, press Ctrl+C in the mache terminal, or:
mache unmount my-project-abc123

# List all active mounts anytime:
mache list

# Clean up stale mounts:
mache clean

Manual Mode (full control):

# 1. Mount your codebase
mache --infer --data ~/my-project --writable /tmp/project

# 2. Navigate and work inside the mount
cd /tmp/project

# 3. Use any LLM with standard file tools (Read, Write, Edit)
claude
# or: aider, cursor, copilot, etc.

Key Points for Agents:

• It's just files. Use standard Read/Write/Edit tools — no special bash commands needed.
• Structure mirrors semantics. Navigate by function name, not file path: cd functions/HandleRequest/
• Virtual files provide context:
  • source — the function/type body (AST node content)
  • context — imports, types, globals visible to this scope
  • callers/ — directory of functions that call this one (cross-references)
  • callees/ — directory of functions this one calls
  • _diagnostics/ — write status, AST errors, lint output
• Write-back preserves identity. Edit source files and changes splice back into the original source tree. Invalid writes save as drafts in _diagnostics/ast-errors.

Important: Writes only work on AST-backed source files. Raw text files and virtual files are read-only. If a write fails validation (syntax error), the node path stays stable and the error is available in _diagnostics/ so the agent can retry.

Example: NVD Vulnerability Database

Mount 323K NVD CVE records as a browsable filesystem, sharded by year and month. (Data can be generated using Venturi):

./mache --schema examples/nvd-schema.json \
        --data /path/to/nvd/results.db \
        /tmp/nvd

/tmp/nvd/
  by-cve/
    2024/
      01/
        CVE-2024-0001/
          description   # "A buffer overflow in FooBar..."
          published     # "2024-01-15T00:00:00Z"
          raw.json      # Full JSON record

Example: Projecting JSON Data

Given a data.json with users, you can project it into a users/ directory where each file contains specific fields.

Example: Projecting Source Code

Mache auto-detects source files (.go, .py, .js, .ts, .rs, .tf, .hcl, .yaml, .sql). Use tree-sitter queries in your schema to map AST nodes (functions, types) to directories.

• Source: The source file contains the function/type body.
• Context: The context file (virtual) contains imports, types, and global variables visible to that scope. This is critical for LLM agents to understand dependencies without reading the whole file.

Write-Back Mode

With --writable (-w), file nodes backed by tree-sitter source code become editable.

# Mount Go source with write-back enabled
./mache -w --infer -d ./src /tmp/mache-src

The write-back pipeline is identity-preserving — node paths stay stable across writes:

1. Validate — tree-sitter checks syntax before touching the source file
2. Format — gofumpt formats Go buffers in-memory (no external CLI, no offset drift)
3. Splice — atomic byte-range replacement in the source file
4. Surgical update — node content and origin updated in-place (no full re-ingest)
5. Shift siblings — adjacent node offsets adjusted to match the new file layout

If validation fails, the write is saved as a draft — the node path remains stable, and the error is available via _diagnostics/ast-errors. The agent can read its broken code and fix it without losing the file path.

Goto: Call-Chain Navigation

Mache exposes cross-references as a virtual callers/ directory. For any function or type, callers/ lists every node in the graph that references it — turning "who calls this?" into a simple ls.

# What calls HandleRequest?
ls /functions/HandleRequest/callers/
# → functions_Main_source  functions_Router_source

# Read the calling code directly
cat /functions/HandleRequest/callers/functions_Main_source
# → func Main() { ... HandleRequest(ctx) ... }

The callers/ directory is self-gating — it only appears when a function actually has callers. No flag needed. This works on both NFS and FUSE backends, for both source code and SQLite mounts with cross-reference data.

Combined with cat /functions/HandleRequest/source for the definition, you get full call-chain tracing through filesystem paths alone — no grep, no LSP, no IDE required.

How It Works

Mache uses a Topology Schema to map data from SQLite, JSON, or source code into a filesystem structure.

1. Direct Mode: For SQLite, it queries the DB on-demand (zero-copy).
2. Ingest Mode: For JSON/Code, it loads data into an in-memory graph.
3. Inference: With --infer, it uses Formal Concept Analysis to guess the best folder structure.

See Architecture for details.

Documentation

• Architecture & Design - Deep dive into internals, pipelines, and abstractions.
• Roadmap - Future plans and known limitations.
• Example Schemas - Details on the included examples.
• ADRs - Architectural Decision Records.

Contributing

See CONTRIBUTING.md for details.

License

Apache License 2.0. See LICENSE.