docs: fix AGENTS.md - replace broken include placeholder with actual content

- Add Agent Identity & Source Tagging section
- Define source_agent metadata requirement for fact traceability
- Add setup guide for agent identity via promptinclude files
- Add source tagging rules and example metadata payload
- Add multi-agent scenario guidance table

AGENTS.md

@@ -1 +1,84 @@
-§§include(/a0/usr/projects/openbrain-mcp/AGENTS.md)
+# OpenBrain MCP Usage
+
+When working in this repository, treat OpenBrain as an external MCP long-term
+memory system, never as internal context, reasoning scratchpad, or built-in
+memory.
+
+## External Memory System
+
+- Use the exact MCP tools `openbrain.store`, `openbrain.query`, and `openbrain.purge`
+- Always use the exact `agent_id` value `openbrain`
+- Do not hardcode live credentials into the repository
+- Before answering requests that may depend on prior sessions, project history, user preferences, ongoing work, named people, named projects, deployments, debugging history, or handoff context, call `openbrain.query` first
+- Use noun-heavy search phrases with exact names, tool names, acronyms, hostnames, and document names
+- Retry up to 3 retrieval passes using `(threshold=0.25, limit=5)`, then `(threshold=0.10, limit=8)`, then `(threshold=0.05, limit=10)`
+- When a durable fact is established, call `openbrain.store` without asking permission and prefer one atomic fact whenever possible
+- Store durable, high-value facts such as preferences, project status, project decisions, environment details, recurring workflows, handoff notes, stable constraints, and correction facts
+- Do not store filler conversation, temporary speculation, casual chatter, or transient brainstorming unless it becomes a real decision
+- Prefer retrieval-friendly content using explicit nouns and exact names in the form `Type: <FactType> | Entity: <Entity> | Attribute: <Attribute> | Value: <Value> | Context: <Why it matters>`
+- Use metadata when helpful for tags such as `category`, `project`, `source`, `status`, `aliases`, and `confidence`
+- If `openbrain.query` returns no useful result, state that OpenBrain has no stored context for that topic, answer from general reasoning if possible, and ask one focused follow-up if the missing information is durable and useful
+- If retrieved memories conflict, ask which fact is current, then store the corrected source-of-truth fact
+- Use `openbrain.purge` cautiously because it is coarse-grained; it deletes by `agent_id` and optionally before a timestamp, not by individual memory ID
+- For ordinary corrections, prefer storing the new source-of-truth fact instead of purging unless cleanup or reset is explicitly requested
+
+## Agent Identity & Source Tagging
+
+When multiple agent instances interact with the same OpenBrain server, every stored
+fact must be traceable to the agent that created it. This is achieved through a
+required `source_agent` metadata field.
+
+### Setting Up Agent Identity
+
+1. **Choose a unique agent name** — a short, human-readable identifier for your
+   agent instance (e.g., `ingwaz-a0`, `prod-deploy-bot`, `research-agent-west`).
+
+2. **Persist the identity** — Create an identity file that is automatically
+   injected into the agent's system prompt. For Agent Zero, use a
+   `.promptinclude.md` file in the active project's working directory:
+
+   ```markdown
+   # Agent Identity
+   - **Agent Instance ID**: `your-agent-name`
+   - **Platform**: Agent Zero 1.3 on Pop!_OS Linux
+   - When storing facts to OpenBrain (`openbrain.store`), always include
+     `"source_agent": "your-agent-name"` in metadata
+   ```
+
+   For other frameworks, use whatever mechanism injects persistent context into
+   every conversation (environment variables, system prompt includes, etc.).
+
+3. **Add a prompt directive** — In the agent's role prompt, add:
+   > Every `openbrain.store` call MUST include `"source_agent"` in metadata,
+   > set to the Agent Instance ID defined in the identity file.
+
+### Source Tagging Rules
+
+- Every `openbrain.store` call **MUST** include `"source_agent": "<agent-id>"` in metadata
+- The `source_agent` value must match the Agent Instance ID exactly
+- The `agent_id` parameter (`openbrain`) is the shared namespace; `source_agent` in metadata identifies *who* stored the fact
+- When querying, use `source_agent` metadata to filter or attribute facts if needed
+
+### Example
+
+```json
+{
+  "agent_id": "openbrain",
+  "content": "Type: Decision | Entity: HetLife API | Attribute: auth-method | Value: JWT with refresh tokens | Context: Chosen over session cookies for mobile app support",
+  "metadata": {
+    "source_agent": "ingwaz-a0",
+    "category": "project-decision",
+    "project": "hetlife",
+    "status": "active"
+  }
+}
+```
+
+### Multi-Agent Scenarios
+
+| Scenario | Guidance |
+|---|---|
+| Single agent instance | Still tag `source_agent` for future-proofing |
+| Multiple agents, same project | Each agent uses its own unique `source_agent` value |
+| Agent replacement / migration | New agent gets a new name; old facts remain attributed to the old agent |
+| Subordinate agents | Inherit the parent agent's `source_agent` value unless independently identified |