lat.md: Building a Knowledge Graph for Your Codebase Using Markdown

The Problem with AGENTS.md

As AI-powered coding agents become ubiquitous, developers increasingly rely on files like AGENTS.md or CLAUDE.md to provide context about their codebase. But there's a fundamental scalability problem: a single flat file simply cannot capture the complexity of a growing project.

Key design decisions get buried in walls of text. Business logic goes undocumented. And worst of all, AI agents hallucinate context they should be able to look up.

Enter lat.md: Agent Lattice

Created by 1st1 (a CPython core developer), lat.md proposes a novel solution: compress your codebase knowledge into a graph of interconnected Markdown files living in a lat.md/ directory at your project root.

How It Works

1. Initialize: Run lat init to scaffold the lat.md/ directory
2. Write: Create Markdown files describing architecture, business logic, test specs
3. Link: Use [[wiki links]] syntax (e.g., [[auth#OAuth Flow]]) to connect concepts
4. Annotate: Add // @lat: [[section-id]] comments in source code to tie implementation back to documentation
5. Validate: Run lat check to ensure nothing drifts out of sync

Key Features

• Scales: Split knowledge across as many files and sections as needed
• Cross-references: Wiki links create a navigable graph of concepts
• Stays in sync: Validates all links and code references
• Searchable: Exact, fuzzy, and semantic (vector) search across all sections
• Works for humans and machines: Readable in any editor, queryable by agents via CLI

Installation

npm install -g lat.md
lat init  # scaffold lat.md/ directory
lat check # validate all wiki links and code refs
lat search "how do we auth?"  # semantic search

Semantic search requires an OpenAI or Vercel AI Gateway API key.

Why This Matters

As AI agents become more deeply integrated into development workflows, the way we structure codebase knowledge matters more than ever. lat.md bridges the gap between human-readable documentation and machine-queryable context — a critical piece of infrastructure for the agent-native development era.

The project is open source, requires Node.js 22+, and is available on GitHub.