![\"lat.md\"](\"templates/logo-dark.svg\"){kind=logo}
\n\n \n
\n ![\"CI\"](\"https://github.com/1st1/lat.md/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"npm\"](\"https://img.shields.io/npm/v/lat.md\")
A knowledge graph for your codebase, written in markdown.
\n\n## The problem\n\n`AGENTS.md` doesn't scale. A single flat file can describe a small project, but as a codebase grows, maintaining one monolithic document becomes impractical. Key design decisions get buried, business logic goes undocumented, and agents hallucinate context they should be able to look up.\n\n## The idea\n\nCompress the knowledge about your program domain into a **graph** — a set of interconnected markdown files that live in a `lat.md/` directory at the root of your project. Sections link to each other with `[[wiki links]]`, markdown files link into the codebase (`[[src/auth.ts#validateToken]]`), source files link back with `// @lat: [[section-id]]` comments, and `lat check` ensures nothing drifts out of sync.\n\n- **Faster coding for agents** — instead of grepping through your codebase, agents search the knowledge graph to discover key design decisions, constraints, and domain context fast and consistently.\n\n- **Faster workflow for humans** — your agents maintain lat files for you. When you review a diff, start with the semantic changes in `lat.md/` to understand *what* changed and *why*. Reviewing code becomes the secondary task.\n\n- **Knowledge retention** — the context and reasoning behind your prompts is usually lost after a session ends. With lat, agents capture that knowledge into the graph as they work, so future sessions start with full context instead of rediscovering it from scratch.\n\n- **Test specs with enforcement** — test cases can be described as sections in `lat.md/` and marked with `require-code-mention: true`. Each spec then must be referenced by a `// @lat:` comment in test code. `lat check` flags any spec without a backlink, so you can review and maintain test coverage from the knowledge graph.\n\nThe `lat` CLI gives agents and humans a system to navigate and maintain the graph:\n\n- **`lat init`** — sets up popular coding agents with hooks and instructions to keep lat updated and correct\n- **`lat check`** — enforces referential consistency; agents call it automatically before finishing work\n- **`lat search`** and **`lat section`** — agents use these to understand your prompts and navigate the graph instead of endless `grep` calls\n\n`lat` is a workflow that comes with tools — build pre-commit hooks and GitHub bots, run CI tasks that improve the knowledge graph in the background.\n\n## Install\n\n```bash\nnpm install -g lat.md\n```\n\nThen run `lat init` in the repo you want to use lat in.\n\n## How it works\n\nRun `lat init` to scaffold a `lat.md/` directory, then write markdown files describing your architecture, business logic, test specs — whatever matters. Link between sections using `[[file#Section#Subsection]]` syntax. Link to source code symbols with `[[src/auth.ts#validateToken]]`. Annotate source code with `// @lat: [[section-id]]` (or `# @lat: [[section-id]]` in Python) comments to tie implementation back to concepts.\n\n```\nmy-project/\n├── lat.md/\n│ ├── architecture.md # system design, key decisions\n│ ├── auth.md # authentication & authorization logic\n│ └── tests.md # test specs (require-code-mention: true)\n├── src/\n│ ├── auth.ts # // @lat: [[auth#OAuth Flow]]\n│ └── server.ts # // @lat: [[architecture#Request Pipeline]]\n└── ...\n```\n\n## CLI\n\n```bash\nlat init # scaffold a lat.md/ directory\nlat check # validate all wiki links and code refs\nlat locate \"OAuth Flow\" # find sections by name (exact, fuzzy)\nlat section \"auth#OAuth Flow\" # show a section with its links and refs\nlat refs \"auth#OAuth Flow\" # find what references a section\nlat search \"how do we auth?\" # semantic search via embeddings\nlat expand \"fix [[OAuth Flow]]\" # expand [[refs]] in a prompt for agents\nlat mcp # start MCP server for editor integration\n```\n\n## Configuration\n\nSemantic search (`lat search`) works **offline by default** — no API key required. It uses a bundled local embedding model (all-MiniLM-L6-v2, compiled to WebAssembly; no native binaries, no network).\n\nTo use higher-quality hosted embeddings instead, provide an OpenAI (`sk-...`) or Vercel AI Gateway (`vck_...`) API key, resolved in order:\n\n1. `LAT_LLM_KEY` env var — direct value\n2. `LAT_LLM_KEY_FILE` env var — path to a file containing the key\n3. `LAT_LLM_KEY_HELPER` env var — shell command that prints the key (10s timeout)\n4. Config file — saved by `lat init`. Run `lat config` to see its location.\n\nSwitch backends any time with `lat reindex` (`--local` to force the offline model, `--remote` to use your key).\n\n## Development\n\nRequires Node.js 22+ and pnpm.\n\n```bash\npnpm install\npnpm build\npnpm test\n```\n","readmeFilename":"README.md"}