docs: add Agent Identity & Source Tagging section to README

- Add source_agent directive to developer prompt code block
- Add full Agent Identity & Source Tagging section with setup guide
- Add source tagging rules, example payload, and multi-agent scenarios

README.md

@@ -179,8 +179,70 @@ Recommended target file in A0:
 - **Conflict Handling**: If retrieved memories conflict, ask which fact is current, then store the corrected source-of-truth fact
 - **Purge Constraint**: Use `openbrain.purge` cautiously because it is coarse-grained; it deletes by `agent_id` and optionally before a timestamp, not by individual memory ID
 - **Correction Policy**: For ordinary corrections, prefer storing the new source-of-truth fact instead of purging unless the user explicitly asks for cleanup or reset
+- **Source Tagging**: Every `openbrain.store` call MUST include `"source_agent"` in metadata, set to the Agent Instance ID defined in the active project's identity file (e.g., `"source_agent": "ingwaz-a0"`). This enables tracing facts back to the originating agent instance.
 ```
 
+## 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 |
+
 ## MCP Integration
 
 OpenBrain exposes both MCP HTTP transports:
@@ -298,26 +360,26 @@ client runtime supports streamable HTTP. Codex should use `/mcp`.
 ## Architecture
 
 ```
-┌─────────────────────────────────────────────────────────┐
+┌─────────────────────────────────────────────────────────────┐
-│                    AI Agent                              │
+│                       AI Agent                              │
-└─────────────────────┬───────────────────────────────────┘
+└─────────────────────┬───────────────────────────────────────┘
                       │ MCP Protocol (Streamable HTTP / Legacy SSE)
-┌─────────────────────▼───────────────────────────────────┐
+┌─────────────────────┴───────────────────────────────────────┐
-│              OpenBrain MCP Server                        │
+│              OpenBrain MCP Server                            │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐      │
-│  │   store     │  │   query     │  │   purge     │      │
+│  │   store         │  │   query         │  │   purge         │      │
-│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘      │
+│  └──────┬──────────┘  └──────┬──────────┘  └──────┬──────────┘      │
-│         │                │                │              │
+│         │                    │                    │              │
-│  ┌──────▼────────────────▼────────────────▼──────┐      │
+│  ┌──────▼────────────────────▼────────────────────▼──────────┐      │
-│  │           Embedding Engine (ONNX)              │      │
+│  │          Embedding Engine (ONNX)                          │      │
-│  │           all-MiniLM-L6-v2 (384d)              │      │
+│  │          all-MiniLM-L6-v2 (384d)                          │      │
-│  └──────────────────────┬────────────────────────┘      │
+│  └──────────────────────┬────────────────────────────────────┘      │
-│                         │                                │
+│                         │                                        │
-│  ┌──────────────────────▼────────────────────────┐      │
+│  ┌──────────────────────▼────────────────────────────────────┐      │
-│  │         PostgreSQL + pgvector                  │      │
+│  │         PostgreSQL + pgvector                             │      │
-│  │         HNSW Index for fast search             │      │
+│  │         HNSW Index for fast search                        │      │
-│  └────────────────────────────────────────────────┘      │
+│  └───────────────────────────────────────────────────────────┘      │
-└─────────────────────────────────────────────────────────┘
+└─────────────────────────────────────────────────────────────────────┘
 ```
 
 ## Environment Variables