diff --git a/README.md b/README.md
index 839d3fa..784b7b6 100644
--- a/README.md
+++ b/README.md
@@ -137,6 +137,8 @@ The template includes a working agent integration and docker-compose setup. See
 - Stores decisions, configurations, learnings
 - Retrieved via `/memory?project=...`
 
+**Project scoping**: Use a stable identifier for the `project` parameter (e.g., git remote URL like `https://github.com/username/repo`). This ensures your project's conventions and memories follow you across machines, even if file paths differ. The template agent auto-detects the git remote.
+
 ## MCP Server Integration
 
 If you use Claude Desktop, add to your config:
diff --git a/SETUP.md b/SETUP.md
index 32dcfcc..11153fe 100644
--- a/SETUP.md
+++ b/SETUP.md
@@ -191,9 +191,13 @@ Edit `.env` if needed:
 ```env
 API_URL=http://helm:8675
 API_KEY=  # Only if auth enabled
-PROJECT=/path/to/your/project  # Optional, for context scoping
+# PROJECT=  # Optional. If not set, agent auto-detects git remote origin (recommended)
 ```
 
+**Project scoping**: The `PROJECT` variable determines how conventions and memories are scoped. We recommend using the git remote origin URL (e.g., `https://github.com/username/repo.git`) as a stable identifier that follows you across machines, even if file paths differ. If `PROJECT` is not set, the agent automatically detects the git remote origin (if the working directory is a git repository). This ensures your project's knowledge base is consistent regardless of where you clone the repo.
+
+For non-git directories, set `PROJECT` to any unique string that identifies the project across machines.
+
 #### 3. Run Your Agent
 
 ```bash
diff --git a/USAGE.md b/USAGE.md
index e903312..0cf72c9 100644
--- a/USAGE.md
+++ b/USAGE.md
@@ -251,11 +251,20 @@ decisions = resp.json()["entries"]
 
 ### Starting a New Session
 
-1. **Define your project identifier** - a path or unique string:
+1. **Define your project identifier** - we recommend using git remote origin for consistency across machines:
    ```python
-   PROJECT = "/home/user/myapp"  # or "my-discord-bot", "workspace-123"
+   # Option A: Auto-detect (recommended) - agent template does this automatically
+   project = get_project_identifier()  # returns git remote origin if available, else env var, else dir name
+   
+   # Option B: Explicit project identifier (stable across machines)
+   PROJECT = "git@github.com:username/repo.git"  # or "https://github.com/username/repo"
+   
+   # Option C: Use environment variable
+   # export PROJECT="git@github.com:username/repo.git"
    ```
 
+   **Why git remote?** If you work on the same repository from multiple machines (different file paths), using the git remote as the project identifier ensures your conventions and memories follow you. The same repo gets the same context regardless of where you clone it.
+
 2. **Load past memories** (optional but helpful):
    ```python
    memories = httpx.get("http://helm:8675/memory", params={"project": PROJECT}).json()["entries"]
@@ -284,7 +293,7 @@ If your agent works across multiple projects:
 
 ```python
 # Switch project context mid-conversation
-PROJECT = "/home/user/project1"  # current active project
+PROJECT = "git@github.com:company/project-a.git"  # stable identifier
 
 # Each project has its own conventions and memories
 context = await get_context(query, project=PROJECT)