GitHub - Zabaca/lattice: Human-initiated, AI-powered knowledge graph for markdown documentation

@zabaca/lattice

Build a knowledge base with Claude Code — using your existing subscription

Lattice turns your markdown documentation into a searchable knowledge graph. Unlike other GraphRAG tools that require separate LLM APIs, Lattice uses Claude Code for entity extraction — so you're already paying for it.

The Workflow

/research "knowledge graphs"   # Find existing docs or create new research
/graph-sync                    # Extract entities & sync (automatic)
lattice search "your query"    # Semantic search your knowledge base

That's it. Two commands to build a knowledge base.

Why Lattice?

Quick Start (2 Minutes)

What You Need

• Claude Code (you probably already have it)
• Voyage AI API key (get one here - embeddings only, ~$0.01/1M tokens)

1. Install

bun add -g @zabaca/lattice          # Install CLI
export VOYAGE_API_KEY=your-key-here  # Set API key
lattice init --global                # Install Claude Code commands

That's it. No Docker. No containers. DuckDB is embedded.

2. Start Researching

claude                        # Launch Claude Code
/research "your topic"        # Find or create documentation
/graph-sync                   # Build knowledge graph (automatic)
lattice search "your query"   # Semantic search

That's It!

The /research command will:

• Search your existing docs for related content
• Ask if you need new research
• Create organized documentation with AI assistance

The /graph-sync command will:

• Detect all new/changed documents
• Extract entities using Claude Code (your subscription)
• Sync to DuckDB for semantic search

Using /research

The /research command provides an AI-assisted research workflow.

Searching Existing Research

/research "semantic search"

Claude will:

1. Search your docs using semantic similarity
2. Read and summarize relevant findings
3. Ask if existing research answers your question

Creating New Research

/research "new topic to explore"

If no existing docs match, Claude will:

1. Perform web research
2. Create a new topic directory (docs/new-topic/)
3. Generate README.md index and research document
4. Remind you to run /graph-sync

Batch Syncing

/graph-sync doesn't need to run after each research session. It identifies all documents needing sync:

# After multiple research sessions
/graph-sync

# Shows: "4 documents need syncing"
# Extracts entities and syncs all at once

CLI Reference

The Lattice CLI runs behind the scenes. You typically won't use it directly — the Claude Code slash commands handle everything.

lattice init              # Install to .claude/commands/ (current project)
lattice init --global     # Install to ~/.claude/commands/ (all projects)

lattice sync [paths...]         # Sync specified paths or current directory
lattice sync --force            # Force re-sync (rebuilds entire graph)
lattice sync --dry-run          # Preview changes without applying

lattice status                  # Show new/changed documents

lattice search "query"          # Search all entity types
lattice search "query" -l Tool  # Filter by label

lattice sql "SELECT * FROM nodes LIMIT 10"
lattice sql "SELECT label, COUNT(*) FROM nodes GROUP BY label"

lattice rels "TypeScript"       # Show all relationships for an entity

lattice ontology                # Show entity types and relationship types

Configuration

Environment Variables

Database Location

Lattice stores its knowledge graph in a single .lattice.duckdb file in your docs directory. This file contains:

• All extracted entities (nodes)
• Relationships between entities
• Vector embeddings for semantic search

You can back up, copy, or version control this file like any other.

-- Nodes (entities)
CREATE TABLE nodes (
    label VARCHAR NOT NULL,      -- Entity type: Document, Technology, etc.
    name VARCHAR NOT NULL,       -- Unique identifier
    properties JSON,             -- Additional metadata
    embedding FLOAT[512],        -- Vector for semantic search
    PRIMARY KEY(label, name)
);

-- Relationships
CREATE TABLE relationships (
    source_label VARCHAR NOT NULL,
    source_name VARCHAR NOT NULL,
    relation_type VARCHAR NOT NULL,
    target_label VARCHAR NOT NULL,
    target_name VARCHAR NOT NULL,
    properties JSON,
    PRIMARY KEY(source_label, source_name, relation_type, target_label, target_name)
);

Contributing

git clone https://github.com/Zabaca/lattice.git
cd lattice
bun install
cp .env.example .env

bun run dev              # Development mode
bun test                 # Run tests
bun run build            # Build for production

import { NestFactory } from '@nestjs/core';
import { AppModule } from '@zabaca/lattice';

async function main() {
  const app = await NestFactory.createApplicationContext(AppModule);
  const syncService = app.get(SyncService);

  const result = await syncService.sync({
    paths: ['./docs'],
    force: false
  });

  console.log(`Synced ${result.added} new documents`);

  await app.close();
}

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Built with DuckDB, Voyage AI, and Claude Code