Lat.md: A Markdown-Based Knowledge Graph for Codebases

Lat.md is a tool that builds a knowledge graph for your codebase using markdown files. It solves the problem of AGENTS.md not scaling well—as projects grow, maintaining a single flat file becomes impractical, leading to buried design decisions, undocumented business logic, and AI agents hallucinating context.

How It Works

You compress domain knowledge into a graph of interconnected markdown files stored in a lat.md/ directory at your project root. Sections link to each other with [[wiki links]] like [[file#Section#Subsection]], markdown files link to code with [[src/auth.ts#validateToken]], and source files link back using comments such as // @lat: [[section-id]] in TypeScript or # @lat: [[section-id]] in Python. The lat check command ensures referential consistency.

Key Features

• Faster coding for agents: Instead of grepping through code, agents search the knowledge graph to discover design decisions, constraints, and domain context consistently.
• Faster workflow for humans: Agents maintain lat files; when reviewing diffs, start with semantic changes in lat.md/ to understand what changed and why, making code review secondary.
• Knowledge retention: Agents capture context and reasoning from prompts into the graph as they work, so future sessions begin with full context instead of rediscovering it.
• Test specs with enforcement: Test cases can be described in lat.md/ sections marked with require-code-mention: true. Each spec must be referenced by a // @lat: comment in test code, and lat check flags any spec without a backlink.

CLI Commands

• lat init: Sets up popular coding agents with hooks and instructions to keep lat updated and correct.
• lat check: Enforces referential consistency; agents call it automatically before finishing work.
• lat search and lat section: Agents use these to understand prompts and navigate the graph instead of endless grep calls.
• lat locate: Finds sections by name (exact or fuzzy).
• lat refs: Finds what references a section.
• lat expand: Expands [[refs]] in a prompt for agents.
• lat mcp: Starts MCP server for editor integration.

Installation and Setup

Install with npm install -g lat.md, then run lat init in your repository to scaffold a lat.md/ directory. Write markdown files describing architecture, business logic, or test specs, and link them as needed.

For semantic search (lat search), an OpenAI (sk-...) or Vercel AI Gateway (vck_...) API key is required. The key is resolved in this order: LAT_LLM_KEY env var (direct value), LAT_LLM_KEY_FILE env var (path to a file containing the key), LAT_LLM_KEY_HELPER env var (shell command that prints the key with a 10s timeout), or a config file saved by lat.