Show HN: Local-first semantic knowledge graph with magnetic-pull retrieval

Watch your codebase become a constellation — and give your AI agent a map of it.

▶ Watch the full demo with audio

Rig builds a local-first semantic knowledge graph of your project, renders it as an interactive map you can fly through, and exposes it to coding agents (Claude Code, Cursor, Codex, …) over MCP. Your agent stops grepping blindly and starts navigating — by structure, by meaning, and by what it's touched before.

Everything runs on your machine. No API key, no upload, nothing leaves your laptop.

In any project directory:

npx rig-constellation

(Have Bun? bunx rig-constellation

works too.) That's the whole thing. One command:

  ⬡ Rig — mapping my-project
  http://localhost:7491

  ✓ initialized  ./.rig
  ✓ map live    http://localhost:7491
  → 1/6 extract      ██████████████████ 212/212
  → 5/6 hubness      ████████████████░░
  ✓ indexed     1,204 nodes · 3,891 edges · 212 files · 36 skills
  ✓ wired       claude

  press Ctrl-C to stop the map.

It initializes .rig/

, opens the live map first, then indexes your code so the graph assembles in the already-open browser tab in real time, and wires up whichever agent it detects. The map title and port are derived per project, so two checkouts can run side by side on stable, distinct ports. Re-run any time, or use the explicit subcommands below.

The command is

rig

(alias:rig-constellation

). Prefer a global install?npm i -g rig-constellation

(orbun install -g rig-constellation

), thenrig start

. Installed locally withnpm i rig-constellation

? The binary lives innode_modules/.bin

— run it withnpx rig start

(or install with-g

to getrig

on yourPATH

).

A map of your codebase. Files, symbols, calls, imports, and dependencies as a navigable graph — not a file tree.Magnetic pull. Ask "what's related to X" and get a ranked answer that blends graph distance, semantic similarity, and what's been active recently.Hubs. The structurally important anchors surface first, so a 5k-node graph stays legible.Dependency intelligence."What version of X do I have?" and "what's declared but never imported?" become one-hop graph queries.** Waypoints.**Your agent drops durable markers at decisions and constraints that survive context-window compaction — so a new session picks up oriented.An MCP tool surface your agent calls directly: search, pull, callers/callees, impact, hubs, deps, and more.

Without a map, an agent answers "what breaks if I change parseConfig?" by grepping the string and reading whatever files match — blind, lossy, and token-expensive.

With Rig it's one call:

rig_impact parseConfig
→ 7 transitive callers, ranked:
   loadSettings          calls · depth 1
   bootstrap             calls · depth 2
   __tests__/config…     tests · depth 1
   …

And "what else should I look at?" isn't a guess — rig_pull

returns related anchors scored by graph distance, on-device embedding similarity, and recent activity, with the three components broken out so the ranking is explainable, not a black box:

rig_pull parseConfig
→ { node: "validateSchema", score: 0.81,
    components: { structural: 0.4, semantic: 0.9, recency: 0.7 } }

That ranked, self-explaining retrieval — not a flat grep dump — is the difference.

• Embeddings run locally via a small on-device model ( bge-small

).No API key required. - The graph lives in .rig/rig.db

in your project.rig

auto-adds.rig/

to your.gitignore

. - Nothing is uploaded. The map UI is served on loopback only.

bunx rig-constellation

auto-detects and wires the agents you have installed. To wire one explicitly:

rig install claude      # also: cursor · codex · opencode · openrouter

This merges Rig's MCP server into the agent's config; the agent spawns rig serve --mcp

on demand.

Command	What it does
rig start
One-shot: init + index + wire agent + open the live map
rig index
Extract + write nodes (--include / --exclude <glob> )
rig sync
Incremental update
rig query
CLI search
rig serve --all
Start MCP and/or the web map (--mcp / --web / --auth )
rig status
Index health
rig doctor
Diagnose environment, db, model cache, agent configs
rig export-docs
Render waypoints into a markdown doc tree

Run rig --help

for the full list.

.contracts/

is the declarative source of truth (tools, anchors, migrations, events); bun run gen

emits the matching code into generated/

. The graph is plain SQLite. Retrieval is a single magnetic-pull scoring function over structural edges, on-device embeddings, and recency. The map UI is a force-graph over WebSocket.

packages/core

— theRig

class: DB, extraction, graph, embeddings, magnetic pullpackages/mcp

— MCP stdio server + tool dispatchpackages/web

— Fastify + WebSocket + React map UIpackages/cli

— therig

binarypackages/contracts

—defineToolContract

& friends

See docs/contracts.md to add a tool,

for the architecture, and

docs/integration.md

for the stability promise.

COMPATIBILITY.md

Bun≥ 1.1 (primary), or Node ≥ 20 (fallback).- Works on macOS, Linux, and Windows.

Adding a tool means touching one file in .contracts/

and one implementation — the generator wires the rest. Start with docs/contracts.md, then

for where new ideas plug in. Stable tools are protected by a compatibility gate (

docs/integration.md

bun run check:compat

); see .

COMPATIBILITY.md

Apache-2.0. Rig's extraction layer is derived from CodeGraph (MIT, © Colby Mchenry); those portions remain under their original MIT terms — see LICENSE-CODEGRAPH.txt and

. With thanks.

NOTICE

source & further reading

github.com — original article