<img src="docs/preview.jpg" alt="The Luia graph: team knowledge at the centre, project work fanning out around it, with one node selected to show its connections" width="100%">

Luia

A knowledge graph for design teams.

Design teams accumulate knowledge faster than they can organise it. A spacing rule agreed in March, a carousel pattern that tested badly, the reason a component was built one way and not another. It ends up scattered across docs, threads, and people's memory, and by the time someone needs it nobody can find it.

Luia has two halves:

• An MCP server that plugs into Claude. Designers and developers install it once, and from then on Claude reads the team's conventions before answering and writes new decisions back as they are made.
• A graph viewer that renders the same knowledge spatially, so you can see how decisions connect instead of scrolling a folder tree.

Both read the same plain Markdown folder. There is no database, no backend, and no service to sign up for — which means a team shares its knowledge by putting that folder in git.

Install the MCP server

Requires Node.js 20.19+ or 22.12+.

git clone https://github.com/gustavocambareri/Luia_MCP.git
cd Luia_MCP
npm install

Point Claude at it. LUIA_KNOWLEDGE_DIR is the folder your team's Markdown lives in — anywhere you like:

claude mcp add luia --scope user \
  --env LUIA_KNOWLEDGE_DIR="$HOME/luia-knowledge" \
  -- node "$PWD/server/index.mjs"

Verify it connected:

claude mcp list        # luia: … - ✔ Connected

For Claude Desktop, add the same thing to claude_desktop_config.json:

{
  "mcpServers": {
    "luia": {
      "command": "node",
      "args": ["/absolute/path/to/luia/server/index.mjs"],
      "env": { "LUIA_KNOWLEDGE_DIR": "/absolute/path/to/your-knowledge" }
    }
  }
}

That's the whole setup. Ask Claude "what's our spacing rule?" and it searches the store before answering.

What Claude can do with it

Tool	When Claude reaches for it
search_knowledge	Before answering anything about how your team designs or builds — so the answer matches decisions you already made
get_document	When a search excerpt looks relevant and it needs the full rule
record_decision	The moment you settle a convention, so it survives the session
list_documents	To see everything the team has written down

The two that matter are search and record. Search is described so Claude calls it unprompted at the start of design work — nobody remembers to ask for their own conventions. Record is a single call with no ceremony, because a capture step with friction is a capture step that doesn't happen.

Using it with your team

The knowledge store is a folder of Markdown files, so sharing it is just git:

cd ~/luia-knowledge
git init && git add . && git commit -m "Team knowledge"
git remote add origin git@github.com:your-team/design-knowledge.git
git push -u origin main

Teammates clone that repo and point their own LUIA_KNOWLEDGE_DIR at it. Pull to get everyone's decisions; push to share yours. Decisions arrive as readable diffs you can review like any other change.

Each document is plain Markdown with frontmatter — editable by hand, no tool required:

---
title: Spacing System
project: atlas          # optional; omit for team-wide knowledge
author: your-name       # or 'team' for collectively-owned decisions
tags: [spacing, layout]
created: 2026-03-09
---

8px base unit, with a 4px step for tight UI.

**Why:** the ratio between gaps carries more meaning than absolute values.

[!TIP] Always write the why. A decision without its rationale is one the team relitigates in six weeks — and the rationale is what makes Claude apply the rule correctly to a case you didn't anticipate.

The graph viewer

• Spatial navigation — a 3D force-directed graph you can pan, zoom, and explore, with hand-composed positions so the layout reads deliberately rather than like a hairball.
• Four ways to filter — by scope, project, author, or free-text search across titles, tags, descriptions, and section headings.
• The author lens — dim everything except one person's contributions to see who holds which knowledge, and where a single point of failure is forming.
• Typed relationships — foundation, reference, and sibling edges are drawn differently, so how two documents relate is legible at a glance.
• Readable content — every node carries full Markdown, a description, and a section outline; click any node to read it without leaving the graph.

Running the viewer

npm run dev

Open the address Vite prints (usually http://localhost:5173) and the demo graph loads immediately.

npm run build     # production build to dist/
npm run preview   # serve that build locally
npm run lint      # eslint

[!NOTE] The bundled graph is entirely fictional. Meridian, Lumen, Atlas, Cadence, Harbor, and Verso are invented engagements, and every person credited in them is made up. Nothing here is real client work.

Viewer data format

The viewer reads src/data/graph-data.json. Replace it with your own and the app is yours.

A node looks like this:

{
  "id": "projects/atlas/block-library",
  "name": "Atlas — Block Library",
  "slug": "block-library",
  "scope": "project",
  "project": "atlas",
  "author": "your-name",
  "tags": ["atlas", "blocks", "templates"],
  "created": "Mon Mar 16 2026 01:00:00 GM",
  "fileSize": 8200,
  "description": "Reusable blocks and page templates for the Atlas redesign.",
  "body": "# Atlas — Block Library\n\n## Navigation\n\nSticky header that…",
  "sections": ["Atlas — Block Library", "Navigation"],
  "connections": ["_team/design-system-patterns"]
}

And an edge connects two of them:

{
  "source": "_team/design-system-patterns",
  "target": "projects/atlas/block-library",
  "type": "reference",
  "label": "informs",
  "description": "Team patterns applied in the Atlas block library."
}

The full shape is defined in src/lib/types.ts.

Fields worth understanding

Field	What it does
scope	team for shared knowledge, project for engagement work. Drives colour and grouping.
project	Required when scope is project. Becomes a filter chip automatically.
author	Powers the author lens. Use team for collectively-owned documents.
fileSize	Controls node radius. Scale your values into roughly 2600–19500 so sizes stay differentiated.
body	Markdown, rendered in the detail panel.
sections	Heading list, included in search.
type	Edge weight and curvature: foundation arcs through the centre, sibling hugs the perimeter.

Adding a project

1. Add your nodes to graph-data.json with a new project value.
2. Add a colour for it in src/lib/colors.ts → PROJECT_COLORS. Without one it falls back to the default ink, and becomes indistinguishable from team nodes.
3. Optionally place its nodes in MANUAL_POSITIONS in src/components/graph3d/useForceLayout.ts. Nodes without coordinates are positioned automatically, but hand-placing them keeps clusters legible.

The filter chips read the project list straight from your data, so step 1 is enough to make it appear in the UI.

[!TIP] Keep id values path-like (projects/<project>/<slug>). Nothing enforces it, but it keeps the file browsable and makes connections easy to write by hand.

Design decisions

A few choices are deliberate and worth knowing before you extend it:

• Positions are authored, not simulated. A pure force layout drifts on every reload and buries the structure. Coordinates live in useForceLayout.ts so the composition is stable and intentional.
• Colour is a system, not decoration. Every hue in colors.ts is derived from a five-colour palette and tuned to a narrow contrast band, so no project reads as visually heavier than another.
• Uppercase titles, explicit weights. Type rules are applied consistently across the canvas and panel; if you add UI, set fontWeight explicitly rather than inheriting it.

Project structure

server/                       # the MCP server
├── index.mjs                 # tool definitions + stdio transport
└── knowledge.mjs             # Markdown store: read, write, search

src/                          # the graph viewer
├── data/graph-data.json      # demo content — replace this with yours
├── lib/
│   ├── types.ts              # GraphNode, GraphEdge, GraphData
│   └── colors.ts             # palette, scope/project/author colour maps
├── hooks/useGraphData.ts     # filtering, search, selection state
└── components/
    ├── FilterBar.tsx         # scope/project/author filters, search
    ├── DecisionLog.tsx       # per-node detail panel
    └── graph3d/              # the 3D scene
        ├── useForceLayout.ts # hand-placed node coordinates
        ├── GraphNode3D.tsx   # node + label rendering
        └── GraphEdge3D.tsx   # typed, curved edges

Built with

React 19 · TypeScript · Vite · Three.js via React Three Fiber · Tailwind CSS