Stories · How it works · Quickstart · Architecture · API · Roadmap

Emma approved the migration to microservices. It sounded right in the exec summary. What she didn't know — because it was compressed through four layers of management — was that the team had already evaluated and rejected microservices six months earlier. The reasoning was in a Slack thread. Nobody escalated it. The migration cost $2M and eighteen months. The original rejection had three paragraphs explaining exactly why.

The information existed. It just couldn't travel.

Mike joined as a senior engineer. Week one, he asked "why is the auth service built this way?" Five people gave him five different partial answers. He spent his evenings reading old PRs, piecing together archaeology from git blame. The person who made the original decision? She left a year ago. It took Mike three months to become productive. Not because he was slow — because the context wasn't accessible.

The knowledge walked out the door.

Sarah was the only person who truly understood the payment system. She'd built it from scratch, navigated two PCI audits, and survived three Black Friday incidents. When she gave her two weeks, leadership panicked. They scheduled "knowledge transfer" sessions. Four hours of frantic meetings. It wasn't enough. The team spent the next four months reverse-engineering what Sarah carried in her head.

No one person should be a single point of knowledge failure.

Tuesday at 2pm. Alex gets pulled into a conference room. Seven people. The question: "Why did we pick Postgres over Mongo?" Alex made this decision three months ago. He wrote the reasoning in the PR description. He wrote it in the RFC. He explained it in the architecture review. Nobody read any of it. He spends 45 minutes re-explaining what's already documented in three places.

The answer existed in writing. Three times. Nobody could find it.

At 10 people, coordination is free. Everyone just knows.

At 50, you start scheduling meetings to "align."

At 200, you have entire teams whose job is to make sure other teams know what's going on.

At 1,000+, 60% of your payroll goes to coordination — people whose job isn't to produce, but to make sure producers are producing the right things.

The hierarchy is a compression algorithm. Each layer compresses reality into a 30-minute summary for the layer above. Five layers up, the CEO is making decisions based on a lossy JPEG of what's actually happening.

You feed it your documents. It builds a living knowledge graph. You ask it questions. It answers with traced sources.

That's a decision trace — not just what was decided, but why. The observation that triggered it. The reasoning that was considered. The action that was taken. The outcome that followed. With sources you can click.

This is what hierarchy loses. A CEO never sees the observation, the benchmark, or the tradeoff analysis. They just hear "we switched databases."

meshgraph keeps the full chain. Forever. For everyone.

git clone https://github.com/meshgraph/meshgraph
cd meshgraph
docker compose up

git clone https://github.com/meshgraph/meshgraph
cd meshgraph
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python main.py

Open http://localhost:8000 — the setup wizard walks you through the rest.

First run asks three things:

That's it. You're running.

graph TB
    subgraph INPUT["What goes in"]
        M["Manual Paste<br/>docs, notes, specs"]
        GH["GitHub<br/>PRs, issues, commits"]
        SL["Slack<br/>threads, decisions"]
    end

    subgraph ENGINE["meshgraph engine"]
        EX["LLM Extraction<br/>entities + decisions"]
        GRAPH[("Graph DB<br/>SQLite")]
        VEC[("Vector Store<br/>ChromaDB")]
        DEC[("Decision Traces")]
        QE["Query Engine<br/>search + traverse + answer"]
    end

    subgraph OUTPUT["What comes out"]
        VIZ["Graph Visualization"]
        CHAT["Chat Answers<br/>with source traces"]
        API_OUT["REST API"]
    end

    M --> EX
    GH -.-> EX
    SL -.-> EX
    EX --> GRAPH
    EX --> VEC
    EX --> DEC
    GRAPH --> QE
    VEC --> QE
    DEC --> QE
    GRAPH --> VIZ
    QE --> CHAT
    GRAPH --> API_OUT

graph LR
    O["Observation<br/><i>what was seen</i>"] --> R["Reasoning<br/><i>what was considered</i>"]
    R --> A["Action<br/><i>what was decided</i>"]
    A --> OUT["Outcome<br/><i>what happened</i>"]

    style O fill:#fef3c7,color:#92400e
    style R fill:#dbeafe,color:#1e40af
    style A fill:#dcfce7,color:#166534
    style OUT fill:#f3e8ff,color:#6b21a8

graph LR
    subgraph Nodes
        P["Person"]
        PR["Project"]
        D["Decision"]
        DOC["Document"]
        T["Task"]
    end

    P -->|works_on| PR
    P -->|decided| D
    P -->|created| DOC
    D -->|informed_by| DOC
    T -->|blocked_by| T
    PR -->|depends_on| PR
    D -->|supersedes| D

    style P fill:#6366f1,color:#fff
    style PR fill:#22c55e,color:#fff
    style D fill:#f59e0b,color:#fff
    style DOC fill:#3b82f6,color:#fff
    style T fill:#06b6d4,color:#fff

Full architecture docs: docs/architecture.md

Everything meshgraph does, you can do via API:

GET    /api/status             Setup check + version
POST   /api/setup              First-run wizard
POST   /api/login              JWT authentication
POST   /api/ingest/text        Ingest a document
GET    /api/nodes              List/filter nodes
GET    /api/nodes/:id          Node detail + edges + decision trace
POST   /api/nodes              Create a node manually
DELETE /api/nodes/:id          Delete a node
GET    /api/edges              List/filter edges
POST   /api/edges              Create an edge
DELETE /api/edges/:id          Delete an edge
GET    /api/graph              Full graph for visualization
GET    /api/graph/neighbors/:id  Connected nodes within N hops
POST   /api/query              Ask a question in natural language
GET    /api/search?q=          Semantic search across all content
GET    /api/decisions          List all decision traces
GET    /api/decisions/:id      Full decision trace detail
POST   /api/decisions          Log a decision manually
GET    /api/stats              Node/edge/decision/vector counts
GET    /api/export             Export full graph as JSON

• Manual document ingestion with AI extraction
• Graph storage + interactive visualization (Cytoscape.js)
• Dark/light theme with persistence
• AI-powered chat with animated thinking, suggestion pills, source citations
• Decision traces (observation → reasoning → action → outcome)
• Semantic search (ChromaDB)
• Docker one-command deploy
• LLM-agnostic (Claude, GPT, Ollama — tested with Ollama locally)
• Full REST API (15 endpoints) + JSON export
• GitHub connector — auto-ingest PRs, issues, contributors
• Slack connector — detect decisions in threads
• Timeline view — chronological decision history
• Team permissions — who sees what
• Conflict detection — flag contradictory decisions across teams
• Org health metrics — decision velocity, knowledge concentration

We'd love your help. See CONTRIBUTING.md.