Your knowledge,
wired as a graph.

01Overview#

GraphFinder is a cross-platform desktop application (Tauri v2 + Rust + React 19) and command-line tool that indexes Markdown knowledge vaults and source-code repositories into a single, semantically searchable graph.

Traditional RAG pipelines split documents into arbitrary fixed windows or push entire files into an LLM context, wasting thousands of tokens. Note-taking tools, in turn, rarely offer local vector search or an API agents can use. GraphFinder addresses both sides:

• For humans — a distraction-free, local-first environment to write pure Markdown with [[wikilinks]], explore connections in an interactive 2D graph and keep full ownership of your files.
• For AI agents — an embedded Model Context Protocol (MCP) server that returns sub-section level results ([[Note#Section]]) and individual code symbols, typically around 50 tokens per hit.

Key concepts

02Installation#

Option A — Pre-built installers (recommended)

Every tagged release is built by GitHub Actions for all three desktop platforms. Grab the latest from the Releases page:

After installing, enable the terminal command so graphfinder works from any shell:

# Windows: adds the install folder to your User PATH + creates graphfinder.cmd shims
# macOS/Linux: creates a symlink in ~/.local/bin/graphfinder
graphfinder install-cli

Option B — Build from source

Prerequisites

• Node.js 20+ and npm
• Rust 1.75+ via rustup
• Windows: Visual Studio C++ Build Tools · Linux: libwebkit2gtk-4.1-dev, build-essential, libssl-dev, libayatana-appindicator3-dev, librsvg2-dev

git clone https://github.com/GabrielTBeserra/GraphFinder.git
cd GraphFinder
npm install

# Run the desktop app in development mode (Vite on :1420 + Tauri)
npm run app

# Produce installers in src-tauri/target/release/bundle/
npm run tauri build

03Quick start#

1. Open the appLaunch GraphFinder (or run graphfinder with no arguments). A default vault is created and the graph appears.
2. Create or open a projectUse the project switcher in the top bar → New project, give it a name and optionally pick an existing folder (a notes folder or a code repository).
3. Write a noteCreate a note, start with # Title, a short summary, then ## sections. Link concepts with [[Other Note]] and finish with tags like #architecture. Save with Ctrl+S.
4. SearchPress Ctrl/⌘+K for Omnisearch — hybrid semantic search across notes and code symbols.
5. Connect your AI editorRun graphfinder config --install or copy a snippet from the in-app MCP modal. Your agent now has 24 GraphFinder tools.

Prefer the terminal? The same flow headless:

cd ~/code/my-project
graphfinder sync            # registers the folder as a project and indexes it
graphfinder status          # notes, code files, edges, database size
graphfinder search "rate limiting middleware"
graphfinder report          # architecture audit + graph artifacts

04Desktop app#

The interface is organised around a sidebar, the central graph canvas and contextual panels.

Keyboard shortcuts

05Writing notes#

GraphFinder works with any Markdown, but retrieval is most precise when notes follow this structure:

1. One H1 title (# Note Title) followed by a 2–3 line executive summary.
2. Self-contained ##/### sections of roughly 40–150 tokens, with descriptive headings (## 2. SQLite WAL Configuration rather than ## Config). Each heading becomes its own embedding and deep-link target.
3. Wikilinks — [[Note]] or [[Note#Section]]. Aim for 1–3 links per note to avoid orphans.
4. Lowercase hashtags — #architecture #sqlite #mcp at the end of sections or the note. They drive the coloured clusters in the graph.

# Auth JWT

How the API issues and validates JSON Web Tokens. Covers signing keys,
expiry policy and refresh rotation.

## 1. Token Signing
Tokens are signed with RS256. Keys rotate every 30 days and are loaded
from the secrets store at boot. See [[System Architecture#2. Secrets]].

## 2. Refresh Rotation
Each refresh invalidates the previous token family to stop replay attacks.

#auth #security #architecture

How notes are parsed

• Parsing uses a real CommonMark AST (pulldown-cmark). Content inside fenced code blocks is isolated, so a # in code is never treated as a heading or tag.
• Sections longer than 320 tokens are windowed with a 40-token overlap so no context is lost at boundaries.
• Renaming a note (UI or rename_note) rewrites every incoming [[Old Title]] across the vault.
• Notes edited outside GraphFinder (VS Code, Cursor, Neovim…) are picked up by the file watcher (500 ms debounce).

06Search engine#

Every query runs two retrievers in parallel and merges them:

Storage is a single SQLite database per project running in WAL mode for concurrent indexing and querying. Re-indexing is incremental: files are compared by timestamp and SHA-256 hash, and only changed files are re-parsed and re-embedded.

07Code indexing#

Point GraphFinder at a repository and it builds a symbol index and dependency graph without needing a compiler or language server.

Supported file types

What gets extracted

• Symbols — top-level functions, classes, structs, interfaces, enums, with line ranges and token estimates. Each symbol is a searchable chunk.
• Local imports — resolved to project files and stored as bidirectional edges (code_links): imports and dependents.
• External packages — third-party modules (e.g. rusqlite, react) listed per file.

What gets skipped

Anything in .gitignore, plus node_modules, target, dist, .git, binary files and files larger than 1 MB.

08Graph analytics#

A pure-Rust analytics engine treats notes and code files as one unified graph and answers architectural questions.

Exported artifacts

graphfinder report, graphfinder export, sync --export or the export_graph tool write to ./graphfinder-out/:

• graph.json — nodes (community, degree, centrality, god-node flag) and edges (source, target, label, weight). Ideal for agents and scripts.
• GRAPH_REPORT.md — executive summary, metrics, God Nodes table, subsystem list, coupling surprises and cycles.
• graph.html — zero-dependency offline visualiser with search, community colours and hub halos. Open it in any browser.

09CLI reference#

The same binary is both the desktop app and the CLI. Running it without arguments opens the GUI; with a command it runs in the terminal.

graphfinder [COMMAND] [OPTIONS]

Examples

# Machine-readable sync for CI or scripts
graphfinder sync ./services/api --json

# How does the UI reach the database layer?
graphfinder path "GraphView.tsx" "db.rs"

# Why does this file matter?
graphfinder explain "src-tauri/src/engine/db.rs"

# Audit into a custom folder
graphfinder report --out-dir ./docs/architecture

# Search only 3 results in a specific project path
graphfinder search "file watcher debounce" --path ./GraphFinder --limit 3

From a source checkout, npm scripts wrap the CLI: npm run sync, npm run status, npm run search, npm run projects, npm run mcp.

10MCP server setup#

GraphFinder implements the Model Context Protocol with the official Rust SDK (rmcp) in two modes:

The fastest path is automatic registration:

graphfinder config --install   # Cursor, Claude Desktop, Windsurf, Cline, Roo Code…
graphfinder config --json      # just print the JSON snippet

Or configure manually:

{
  "mcpServers": {
    "graphfinder": {
      "url": "http://127.0.0.1:45123/sse"
    }
  }
}

{
  "mcpServers": {
    "graphfinder": {
      "command": "C:\\Program Files\\GraphFinder\\GraphFinder.exe",
      "args": ["--mcp"]
    }
  }
}

{
  "mcpServers": {
    "graphfinder": {
      "type": "sse",
      "url": "http://127.0.0.1:45123/sse"
    }
  }
}

{
  "mcpServers": {
    "graphfinder": {
      "url": "http://127.0.0.1:45123/sse"
    }
  }
}

{
  "mcpServers": {
    "graphfinder": {
      "command": "graphfinder",
      "args": ["--mcp"]
    }
  }
}

11MCP tools (24)#

Every tool accepts an optional project parameter to target a specific vault without cross-contamination. Dashed parameters are optional.

Knowledge retrieval

Authoring & linking

Graph & architecture

Codebase

Projects & sync

Run graphfinder tools to export the JSON schemas of all tools for use with any agent framework.

12AI agents & skills#

GraphFinder ships three layers that work together: the agent (Cursor, Claude, Antigravity…) reasons and plans, the skill enforces token economy and note quality, and the MCP server executes retrieval and writes.

Bundled skills & rules

• AGENTS.md — repository rules for agents (token economy, note schema, decision pipelines). Antigravity loads it automatically; in Cursor add it to Project Rules; in Claude paste it into the project prompt.
• .agents/skills/graphfinder-curator — authoring and curation workflow (summaries, atomic sections, suggest_links before store_context, tags).
• .agents/skills/graphfinder — architecture auditing workflow (reports, paths, explain, exports).

Recommended workflows

Answering a question

search_semantic("sqlite wal mode")        → top 5 chunks (~50 tokens each)
  └─ need the outline?  get_compressed_context("System Architecture")
  └─ need one section?  read_section("System Architecture", "1. Local Storage")

Saving knowledge

draft note (# Title + summary + ## sections)
  → suggest_links(draft)                   → e.g. "System Architecture: 85%"
  → insert [[System Architecture]] into draft
  → store_context(title, content, tags)    → file written, indexed, graph updated

Inspecting code

search_code("hybrid_search", language="rust")
  → get_file_context("src-tauri/src/engine/db.rs")       # symbol map, <80 tokens
  → read_code_chunk("src-tauri/src/engine/db.rs", "hybrid_search")
  → get_code_dependencies("src-tauri/src/engine/db.rs")  # impact analysis

Auditing architecture

get_community_report()      → subsystems, God Nodes, surprises, cycles
  → explain_node("db.rs")   → why it matters
  → find_path("App.tsx", "db.rs")

Prompt examples

13Projects & vaults#

Each project is an isolated workspace with its own Markdown directory and its own SQLite vector database, so searches never leak between projects.

• Default vault — <data dir>/vault with index <data dir>/index.db.
• Managed vaults — <data dir>/vaults/<project_id>/, created from the UI or create_project.
• External folders — any path on disk (e.g. a code repo) registered via the UI, graphfinder sync <path> or create_project(name, path).
• Registry — vaults/projects.json stores the active project, custom names and custom paths.

{
  "active_project": "default",
  "custom_names": { "my-api": "My API" },
  "custom_paths": { "my-api": "C:/Repos/MyAPI" }
}

Where is the data directory?

1. GRAPHFINDER_DATA_DIR, if set.
2. The current directory, if it contains package.json (source checkout / dev mode).
3. Otherwise the OS data folder: %APPDATA%\GraphFinder (Windows), ~/Library/Application Support/GraphFinder (macOS), ~/.local/share/GraphFinder (Linux).

14Configuration#

GraphFinder is configured through environment variables — no config file required.

# Portuguese / multilingual vault on a custom port
export GRAPHFINDER_MODEL=multilingual
export GRAPHFINDER_MCP_PORT=47000
graphfinder

15Architecture#

Repository layout

GraphFinder/
├── src/                      # React 19 + TypeScript frontend
│   ├── components/           # GraphView, NoteEditor, CodeInspector, Sidebar,
│   │                         # OmnisearchModal, McpModal, ArchitecturalReportModal…
│   ├── services/             # Tauri IPC bindings
│   └── types.ts
├── src-tauri/                # Rust backend
│   ├── src/main.rs           # CLI entry point (GUI when no args)
│   ├── src/lib.rs            # Tauri setup, IPC commands, embedded MCP HTTP server
│   ├── src/engine/
│   │   ├── parser.rs         # CommonMark AST, chunking, wikilinks, tags
│   │   ├── embeddings.rs     # FastEmbed model loading & inference
│   │   ├── db.rs             # SQLite schema, FTS5, hybrid RRF search
│   │   ├── vault.rs          # Engine: sync, watcher, note lifecycle
│   │   ├── code.rs           # Language detection, symbols, imports
│   │   ├── graph_analytics.rs# Communities, centrality, paths, exports
│   │   └── project.rs        # Multi-vault manager & registry
│   └── src/mcp/              # MCP tool definitions (mod.rs) & transports (server.rs)
├── .agents/skills/           # graphfinder & graphfinder-curator skills
├── mcp-tools/                # Exported tool schemas
├── docs/                     # This website (GitHub Pages)
└── AGENTS.md · MCP_TOOLS.md · CHANGELOG.md

Tech stack

16Security#

• Loopback only — the MCP HTTP server binds to 127.0.0.1.
• DNS-rebinding defense — the Host header is validated on every request.
• Origin validation — strict middleware instead of permissive CORS.
• Content Security Policy — enforced in tauri.conf.json.
• XSS protection — Markdown previews are sanitised with DOMPurify.
• Path traversal protection — project ids are sanitised before touching the filesystem.

Report vulnerabilities privately as described in SECURITY.md.

17Development#

Releases

Pushing a tag matching v* (or running the Release workflow manually) triggers .github/workflows/release.yml: scripts/sync-version.js stamps the tag version into package.json, Cargo.toml and tauri.conf.json, then tauri-action builds and publishes installers for Windows, macOS and Linux.

git tag v0.11.0
git push origin v0.11.0

Contributing

Bug reports, features, docs and PRs are welcome. Read CONTRIBUTING.md and the Code of Conduct.

18Troubleshooting & FAQ#

My agent can't connect to 127.0.0.1:45123.

The HTTP/SSE endpoint only exists while the desktop app is running. Open the app, or switch your client to stdio mode ("command": "graphfinder", "args": ["--mcp"]). If you changed GRAPHFINDER_MCP_PORT, update the URL.

graphfinder is not recognised in the terminal.

Run GraphFinder.exe install-cli (or graphfinder config --install) and open a new terminal so the updated PATH is loaded.

Search results are poor for Portuguese / other languages.

Set GRAPHFINDER_MODEL=multilingual and re-index.

The first start is slow.

The embedding model is downloaded once. Subsequent starts load it from .fastembed_cache; point GRAPHFINDER_MODELS to a local copy for air-gapped machines.

Some files are missing from the code graph.

Check whether they are ignored by .gitignore, are binary, exceed 1 MB, or have an unsupported extension. Run graphfinder sync to force an incremental update.

Does any data leave my machine?

No. Embeddings, search and analytics run locally. The only network access is the one-time model download (and this website checking the latest release on GitHub).

19Changelog#

Full history in CHANGELOG.md and on the Releases page.