diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..624eceb
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,93 @@
+# Matrix Hermes — Agent Guide
+
+Matrix authentication, client, and bridge integration for Hermes Agent. Provides login/token management, async client wrapper, room management, messaging, sync engine, and Kanban board monitoring over Matrix.
+
+## Stack
+
+- **Python** ≥3.10, **mautrix** (Matrix client SDK), **aiohttp**
+- **python-dotenv** — config loading
+- Optional: `mautrix[encryption]` for E2EE
+- **pytest**, **pytest-asyncio**, **ruff** — dev tooling
+
+## Project Structure
+
+```
+src/matrix_hermes/
+  __init__.py
+  auth.py       # Login/logout, access token management, device ID
+  client.py     # Async MatrixClient wrapper (mautrix-based)
+  config.py     # MatrixConfig dataclass, .env-based loading
+  cli.py        # CLI entry point — `matrix-hermes` command
+  rooms.py      # Room CRUD operations
+  messaging.py  # Send/edit/reaction/typing indicators
+  sync.py       # Incremental sync engine
+  kanban.py     # Kanban DB monitoring over Matrix
+
+tests/
+  __init__.py
+  conftest.py
+  test_auth.py
+  test_cli.py
+  test_config.py
+  test_kanban.py
+  test_messaging.py
+  test_rooms.py
+  test_sync.py
+
+pyproject.toml   # Build config, dependencies
+.env.example     # Config template
+README.md
+```
+
+## How to Run
+
+```bash
+# Install
+pip install -e ".[dev]"
+
+# Login
+matrix-hermes login
+
+# Check status
+matrix-hermes whoami
+
+# Show config
+matrix-hermes show-config
+
+# Logout
+matrix-hermes logout
+
+# Check connection
+matrix-hermes check
+
+# Monitor Kanban
+matrix-hermes kanban
+```
+
+## Key Architecture
+
+- **Package-based** — installable via `pip install -e .`
+- CLI entry: `matrix-hermes` (click-based)
+- Sessions persist to `~/.hermes/matrix_sessions/`
+- Config via `.env` file (template in `.env.example`)
+- Async core built on `mautrix` — all network calls are async
+
+## Production
+
+- **CLI tool / library** — no server, no systemd
+- Used as a library by Hermes Agent gateway for Matrix platform support
+
+## Environment Variables
+
+| Var | Description |
+|-----|-------------|
+| MATRIX_HOMESERVER | Matrix server URL (e.g. `https://matrix.ourpad.casa`) |
+| MATRIX_ACCESS_TOKEN | Persistent access token (after login) |
+| MATRIX_USER_ID | User MXID (after login) |
+| MATRIX_DEVICE_ID | Device identifier (after login) |
+
+## Pitfalls
+
+- **E2EE is optional** — requires `mautrix[encryption]` install extra
+- Session tokens stored at `~/.hermes/matrix_sessions/` — keep secure
+- All matrix network operations are async — synchronous wrappers may need event loop management