{"id":45840808,"url":"https://github.com/agentic-research/mache","last_synced_at":"2026-04-02T15:39:12.367Z","repository":{"id":338257118,"uuid":"1154039896","full_name":"agentic-research/mache","owner":"agentic-research","description":"🗂️ The Universal Graph-Native Overlay Engine","archived":false,"fork":false,"pushed_at":"2026-03-26T23:10:16.000Z","size":7464,"stargazers_count":30,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T23:56:30.817Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://rosary.bot/about","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agentic-research.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-10T00:20:46.000Z","updated_at":"2026-03-26T23:10:21.000Z","dependencies_parsed_at":"2026-03-12T06:04:00.700Z","dependency_job_id":null,"html_url":"https://github.com/agentic-research/mache","commit_stats":null,"previous_names":["agentic-research/mache"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/agentic-research/mache","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentic-research%2Fmache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentic-research%2Fmache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentic-research%2Fmache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentic-research%2Fmache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentic-research","download_url":"https://codeload.github.com/agentic-research/mache/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentic-research%2Fmache/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31309156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-27T00:05:58.985Z","updated_at":"2026-04-02T15:39:12.356Z","avatar_url":"https://github.com/agentic-research.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mache\n\n[![CI](https://github.com/agentic-research/mache/actions/workflows/ci.yml/badge.svg)](https://github.com/agentic-research/mache/actions/workflows/ci.yml)\n[![Integration](https://github.com/agentic-research/mache/actions/workflows/integration.yml/badge.svg)](https://github.com/agentic-research/mache/actions/workflows/integration.yml)\n\nAn agent-computer interface for code and structured data.\n\nAgents operate in environments without topology. They see flat files, grep for strings, and rebuild context every turn. Mache gives them the structure that's missing — a graph of functions, types, cross-references, and call chains, exposed over MCP or as a mounted filesystem. Agents navigate structure instead of searching for it. Outputs stay human-discernible; it's just directories and SQL.\n\n\u003e *Mache* (/mɑʃe/ *mah-shay*): from *papier-mâché* — raw material, crushed and remolded into shape.\n\n![Mache Demo](demo.gif)\n\n## Install\n\n```bash\nbrew install agentic-research/tap/mache\n```\n\n## Use with Claude Code\n\nAdd to your project's `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"mache\": {\n      \"command\": \"mache\",\n      \"args\": [\"serve\", \"--stdio\", \".\"]\n    }\n  }\n}\n```\n\nThat's it. Mache auto-infers the schema from your codebase. No config files, no mount, no daemon.\n\nYour agent gets 15 tools:\n\n| Tool               | What it does                                               |\n| ------------------ | ---------------------------------------------------------- |\n| `get_overview`     | Top-level structure, node counts, entry points             |\n| `list_directory`   | Browse the graph by path                                   |\n| `read_file`        | Read source content (supports batch reads)                 |\n| `find_definition`  | Jump to where a symbol is defined                          |\n| `find_callers`     | Who calls this?                                            |\n| `find_callees`     | What does this call?                                       |\n| `search`           | Pattern match across symbols                               |\n| `semantic_search`  | Natural-language search via embeddings                     |\n| `get_communities`  | Find clusters of tightly-coupled code                      |\n| `get_type_info`    | LSP type info and hover data                               |\n| `get_diagnostics`  | LSP errors and warnings                                    |\n| `get_impact`       | Blast radius of changing a symbol                          |\n| `get_architecture` | Entry points, abstractions, dependency layers              |\n| `get_diagram`      | Mermaid diagram of system structure                        |\n| `write_file`       | Edit through the splice pipeline: validate, format, splice |\n\n## Why this exists\n\nAgents 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.\n\nMache does. Point it at data, it figures out the shape. Source code gets parsed by tree-sitter. JSON and YAML get walked. Schema inference (via Formal Concept Analysis) discovers the natural groupings — `functions/`, `types/`, `classes/` — without you writing config. The agent can then explore the topology directly: follow call chains, find definitions, read context, write back.\n\nThe workflow: **point your agent at data → mache discovers the shape → agent explores structure instead of searching for it.**\n\nThis is built for agents first. The design choices — stable node paths across edits, POSIX as the universal interface, 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.\n\n## Mount as a filesystem\n\nMache can also mount your data as a real directory tree. This works with any tool — `cat`, `ls`, `cd`, shell scripts, other agents.\n\n```bash\n# Mount source code (zero-config, writable)\nmache --infer -d ./src --writable /tmp/mache-src\n\n# Mount with agent mode (generates PROMPT.txt for LLMs)\nmache --agent -d ~/my-project\n\n# Mount a SQLite database (zero-copy)\nmache --schema examples/nvd-schema.json --data results.db /tmp/nvd\n```\n\nWhat the mount looks like:\n\n```\n/tmp/mache-src/\n  functions/\n    HandleRequest/\n      source        # the function body\n      context       # imports, types visible to this scope\n      callers/      # who calls this function\n      callees/      # what this function calls\n    ValidateToken/\n      source\n  types/\n    Config/\n      source        # type Config struct { ... }\n  _project_files/\n    README.md\n    go.mod\n```\n\nNavigate by function name, not file path. `callers/` and `callees/` are virtual directories that appear only when references exist.\n\n### Write-back\n\nWith `--writable`, edits to `source` files go through a pipeline before touching your actual source:\n\n1. **Validate** — tree-sitter checks syntax\n1. **Format** — gofumpt (Go), hclwrite (HCL)\n1. **Splice** — atomic byte-range replacement in the source file\n1. **Update** — node content updated in-place, no re-ingest\n\nIf the syntax is wrong, the write is saved as a draft. The node path stays stable. Errors show up in `_diagnostics/`. The agent can read what it broke and try again without losing its place.\n\n## MCP server options\n\n```bash\n# stdio — Claude Code spawns mache as a subprocess (recommended)\nmache serve --stdio .\n\n# HTTP — runs independently, multiple clients\nmache serve .\nmache serve --http :9000 -s examples/nvd-schema.json results.db\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eClaude Code setup (detailed)\u003c/summary\u003e\n\n**Per-project (stdio)** — `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"mache\": {\n      \"command\": \"mache\",\n      \"args\": [\"serve\", \"--stdio\", \".\"]\n    }\n  }\n}\n```\n\n**Global** — `~/.claude/settings.json` with same format.\n\n**HTTP (always-on)**:\n\n```bash\nmache serve /path/to/data \u0026\nclaude mcp add --transport http mache http://localhost:7532/mcp\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eClaude Desktop setup\u003c/summary\u003e\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"mache\": {\n      \"command\": \"/path/to/mache\",\n      \"args\": [\"serve\", \"--stdio\", \"/path/to/code\"]\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n## How it works\n\n- **Tree-sitter** parses source into AST nodes (28 languages including Go, Python, JS, TS, Rust, Java, C, Ruby, SQL, HCL, YAML)\n- **Schema inference** (Formal Concept Analysis) groups nodes into containers — `functions/`, `types/`, `classes/`\n- **Cross-reference extraction** builds a call graph from identifiers and imports\n- **SQL projection** maps the graph into a navigable tree\n\nThree backends: MCP server (JSON-RPC), NFS mount (macOS default), FUSE mount (Linux default).\n\n\u003cdetails\u003e\n\u003csummary\u003eThe graph isomorphism argument\u003c/summary\u003e\n\nBoth 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.\n\nOperating systems never formalized this mapping. Mache does:\n\n- SQL is the graph operator — queries define projections from one topology to another\n- Schema defines topology — the formal specification of how source nodes map to filesystem nodes\n- The filesystem exposes traversal primitives: `cd` traverses an edge, `ls` enumerates children, `cat` reads node data\n\n```mermaid\ngraph TD\n    DH[\"\u003cb\u003eData Graph\u003c/b\u003e\u003cbr/\u003e(JSON / Code / YAML)\"]\n\n    root[\"Root Object\"]\n    root --\u003e key1[\"{key}\"]\n    root --\u003e key2[\"{key}\"]\n    root --\u003e arr[\"[Array]\"]\n    key1 --\u003e val[\"'value'\"]\n    key2 --\u003e obj[\"{object}\"]\n    arr --\u003e item[\"{item}\"]\n\n    bridge[\"\u003cb\u003eMache Bridge: SQL Projection\u003c/b\u003e\u003cbr/\u003eGraph → Tree\"]\n\n    OSH[\"\u003cb\u003eOS Graph\u003c/b\u003e\u003cbr/\u003e(Filesystem)\"]\n\n    mount[\"/  (mount)\"]\n    mount --\u003e dir1[\"/key/\"]\n    mount --\u003e dir2[\"/key/\"]\n    mount --\u003e dirArr[\"/Arr/\"]\n    dir1 --\u003e file[\"file\"]\n    dir2 --\u003e subdir[\"dir/\"]\n    dirArr --\u003e itemdir[\"dir/\"]\n\n    DH --\u003e root\n    val --\u003e bridge\n    obj --\u003e bridge\n    item --\u003e bridge\n    bridge --\u003e mount\n    mount --\u003e OSH\n\n    style DH fill:#e1f5ff,stroke:#333,stroke-width:2px\n    style bridge fill:#fff4e1,stroke:#333,stroke-width:2px\n    style OSH fill:#ffe1f5,stroke:#333,stroke-width:2px\n    style root fill:#b3e5fc\n    style mount fill:#f8bbd0\n\n```\n\nSee [Architecture](docs/ARCHITECTURE.md) for the full picture.\n\n\u003c/details\u003e\n\n## What's stable, what's not\n\n| Capability                              | Status |\n| --------------------------------------- | ------ |\n| Tree-sitter parsing (28 langs)          | Stable |\n| NFS/FUSE mount                          | Stable |\n| Write-back (validate, format, splice)   | Stable |\n| Cross-references (callers/callees)      | Stable |\n| Context files (imports, types, globals) | Stable |\n| MCP server (15 tools, stdio + HTTP)     | Stable |\n| Schema inference (FCA)                  | Beta   |\n| Community detection (Louvain)           | Beta   |\n| LSP enrichment (type info, diagnostics) | Beta   |\n\n## Landscape\n\nSee [Prior Art](docs/PRIOR_ART.md) for detailed comparisons with related tools.\n\n\u003cdetails\u003e\n\u003csummary\u003eBuild from source\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/agentic-research/mache.git\ncd mache\ntask build            # requires: go-task, Go 1.23+\ntask install          # copies to ~/.local/bin\n```\n\n- **macOS:** `brew install go-task`\n- **macOS (FUSE):** `brew install --cask fuse-t` (only if using `--backend fuse`)\n- **Linux:** `apt-get install libfuse-dev` and [install Task](https://taskfile.dev/installation/)\n\n\u003c/details\u003e\n\n## Docs\n\n- [Architecture](docs/ARCHITECTURE.md)\n- [Prior Art](docs/PRIOR_ART.md)\n- [Roadmap](docs/ROADMAP.md)\n- [Example Schemas](examples/README.md)\n- [ADRs](docs/adr/)\n- [Contributing](CONTRIBUTING.md)\n\n## License\n\nApache 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentic-research%2Fmache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentic-research%2Fmache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentic-research%2Fmache/lists"}