diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..e12b4e9
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,80 @@
+# AGENTS.md
+
+Guidance for AI coding agents (Cursor, Claude Code, Copilot, Codex, and similar) working in this repository.
+
+## EchoVault (required)
+
+This project uses the **EchoVault** MCP server (`user-echovault`) as persistent memory across sessions.
+Use it aggressively. Skipping it means the next agent starts from zero.
+
+### When to call what
+
+| Tool | When |
+| --- | --- |
+| `memory_context` | **Session start** and after a major topic change. Loads recent decisions for this project. |
+| `memory_search` | Before work on a familiar/unclear topic, and whenever the user’s request may relate to prior decisions or bugs. |
+| `memory_save` | **Before ending** any session where you made decisions, fixed bugs, discovered non-obvious patterns, or changed architecture/infra. Not optional. |
+
+Prefer `project: "the-living-world"` when the tool accepts a project filter.
+
+### What to save
+
+Save when you:
+
+- Chose an approach (X over Y) or fixed a non-obvious bug
+- Learned something about this codebase that is not obvious from reading the code
+- Set up tooling/config the next agent will need
+- Were corrected or given a durable requirement by the user
+
+Do **not** save: typos, pure formatting, facts already clear from the code, or duplicates of existing memories.
+
+### How to write a good memory
+
+- `title` — short (≤60 chars)
+- `what` — 1–2 sentences the next agent needs
+- `why` / `impact` — reasoning and what changed
+- `category` — one of: `decision`, `bug`, `pattern`, `learning`, `context`
+- `tags` / `related_files` — so search can find it
+- `details` — write for an agent with **zero** context. Prefer:
+
+  ```
+  Context
+  Options considered
+  Decision
+  Tradeoffs
+  Follow-up
+  ```
+
+### Session checklist
+
+1. Call `memory_context` (and `memory_search` if the task is specific).
+2. Do the work.
+3. Call `memory_save` for every meaningful decision or fix before you stop.
+
+## Project snapshot
+
+The Living World is a web game whose map is a real place: the API imports OpenStreetMap via Overpass into an Arch ECS world and serves chunked geometry; a PixiJS client renders it.
+
+| Area | Path / stack |
+| --- | --- |
+| API | `src/TheLivingWorld.Api` — .NET 10, minimal APIs |
+| Core / ECS | `src/TheLivingWorld.Core` — Arch, geo, export |
+| OSM import | `src/TheLivingWorld.Osm` — Overpass + import pipeline |
+| Web client | `src/TheLivingWorld.Web` — TypeScript, Vite, PixiJS 8 |
+| Aspire host | `src/TheLivingWorld.AppHost` |
+| Tests | `tests/TheLivingWorld.Tests` (xUnit), Vitest under the web project |
+
+Worlds are stored as files under `data/` (not committed). Cap: `WorldStorage:MaxConcurrentWorlds`. UI: main menu (list + create) → map screen.
+
+Keep wire DTOs in sync: `TheLivingWorld.Core.Contracts` and `src/TheLivingWorld.Web/src/api/types.ts`.
+
+## Working conventions
+
+- Prefer small, focused diffs. Do not rewrite unrelated code or add docs the user did not ask for.
+- Match existing naming, comments, and file layout.
+- Backend tests: `dotnet test tests/TheLivingWorld.Tests/TheLivingWorld.Tests.csproj`
+- Frontend checks: `npm --prefix src/TheLivingWorld.Web test` and `npm --prefix src/TheLivingWorld.Web run typecheck`
+- Full stack: `run.cmd` or `dotnet run --project src/TheLivingWorld.AppHost`
+- Do not commit unless the user asks. Do not invent secrets or commit `data/`.
+
+Details of the import pipeline, API surface, and renderer live in [README.md](README.md) — read that before large map/API changes.