diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..4cadfbdc1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,132 @@
+## Repository Guidelines
+
+This document summarizes how to work with the cognee repository: how it’s organized, how to build, test, lint, and contribute. It mirrors our actual tooling and CI while providing quick commands for local development.
+
+## Project Structure & Module Organization
+
+- `cognee/`: Core Python library and API.
+  - `api/`: FastAPI application and versioned routers (add, cognify, memify, search, delete, users, datasets, responses, visualize, settings, sync, update, checks).
+  - `cli/`: CLI entry points and subcommands invoked via `cognee` / `cognee-cli`.
+  - `infrastructure/`: Databases, LLM providers, embeddings, loaders, and storage adapters.
+  - `modules/`: Domain logic (graph, retrieval, ontology, users, processing, observability, etc.).
+  - `tasks/`: Reusable tasks (e.g., code graph, web scraping, storage). Extend with new tasks here.
+  - `eval_framework/`: Evaluation utilities and adapters.
+  - `shared/`: Cross-cutting helpers (logging, settings, utils).
+  - `tests/`: Unit, integration, CLI, and end-to-end tests organized by feature.
+  - `__main__.py`: Entrypoint to route to CLI.
+- `cognee-mcp/`: Model Context Protocol server exposing cognee as MCP tools (SSE/HTTP/stdio). Contains its own README and Dockerfile.
+- `cognee-frontend/`: Next.js UI for local development and demos.
+- `distributed/`: Utilities for distributed execution (Modal, workers, queues).
+- `examples/`: Example scripts demonstrating the public APIs and features (graph, code graph, multimodal, permissions, etc.).
+- `notebooks/`: Jupyter notebooks for demos and tutorials.
+- `alembic/`: Database migrations for relational backends.
+
+Notes:
+- Co-locate feature-specific helpers under their respective package (`modules/`, `infrastructure/`, or `tasks/`).
+- Extend the system by adding new tasks, loaders, or retrievers rather than modifying core pipeline mechanisms.
+
+## Build, Test, and Development Commands
+
+Python (root) – requires Python >= 3.10 and < 3.14. We recommend `uv` for speed and reproducibility.
+
+- Create/refresh env and install dev deps:
+```bash
+uv sync --dev --all-extras --reinstall
+```
+
+- Run the CLI (examples):
+```bash
+uv run cognee-cli add "Cognee turns documents into AI memory."
+uv run cognee-cli cognify
+uv run cognee-cli search "What does cognee do?"
+uv run cognee-cli -ui   # Launches UI, backend API, and MCP server together
+```
+
+- Start the FastAPI server directly:
+```bash
+uv run python -m cognee.api.client
+```
+
+- Run tests (CI mirrors these commands):
+```bash
+uv run pytest cognee/tests/unit/ -v
+uv run pytest cognee/tests/integration/ -v
+```
+
+- Lint and format (ruff):
+```bash
+uv run ruff check .
+uv run ruff format .
+```
+
+- Optional static type checks (mypy):
+```bash
+uv run mypy cognee/
+```
+
+MCP Server (`cognee-mcp/`):
+
+- Install and run locally:
+```bash
+cd cognee-mcp
+uv sync --dev --all-extras --reinstall
+uv run python src/server.py               # stdio (default)
+uv run python src/server.py --transport sse
+uv run python src/server.py --transport http --host 127.0.0.1 --port 8000 --path /mcp
+```
+
+- API Mode (connect to a running Cognee API):
+```bash
+uv run python src/server.py --transport sse --api-url http://localhost:8000 --api-token YOUR_TOKEN
+```
+
+- Docker quickstart (examples): see `cognee-mcp/README.md` for full details
+```bash
+docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main
+```
+
+Frontend (`cognee-frontend/`):
+```bash
+cd cognee-frontend
+npm install
+npm run dev     # Next.js dev server
+npm run lint    # ESLint
+npm run build && npm start
+```
+
+## Coding Style & Naming Conventions
+
+Python:
+- 4-space indentation, modules and functions in `snake_case`, classes in `PascalCase`.
+- Public APIs should be type-annotated where practical.
+- Use `ruff format` before committing; `ruff check` enforces import hygiene and style (line-length 100 configured in `pyproject.toml`).
+- Prefer explicit, structured error handling. Use shared logging utilities in `cognee.shared.logging_utils`.
+
+MCP server and Frontend:
+- Follow the local `README.md` and ESLint/TypeScript configuration in `cognee-frontend/`.
+
+## Testing Guidelines
+
+- Place Python tests under `cognee/tests/`.
+  - Unit tests: `cognee/tests/unit/`
+  - Integration tests: `cognee/tests/integration/`
+  - CLI tests: `cognee/tests/cli_tests/`
+- Name test files `test_*.py`. Use `pytest.mark.asyncio` for async tests.
+- Avoid external state; rely on test fixtures and the CI-provided env vars when LLM/embedding providers are required. See CI workflows under `.github/workflows/` for expected environment variables.
+- When adding public APIs, provide/update targeted examples under `examples/python/`.
+
+## Commit & Pull Request Guidelines
+
+- Use clear, imperative subjects (≤ 72 chars) and conventional commit styling in PR titles. Our CI validates semantic PR titles (see `.github/workflows/pr_lint`). Examples:
+  - `feat(graph): add temporal edge weighting`
+  - `fix(api): handle missing auth cookie`
+  - `docs: update installation instructions`
+- Reference related issues/discussions in the PR body and provide brief context.
+- PRs should describe scope, list local test commands run, and mention any impacts on MCP server or UI if applicable.
+- Sign commits and affirm the DCO (see `CONTRIBUTING.md`).
+
+## CI Mirrors Local Commands
+
+Our GitHub Actions run the same ruff checks and pytest suites shown above (`.github/workflows/basic_tests.yml` and related workflows). Use the commands in this document locally to minimize CI surprises.
+
+