From 98baa27c90766394703819b4b71223fd346bb21d Mon Sep 17 00:00:00 2001 From: admin Date: Sat, 28 Mar 2026 02:36:05 +0000 Subject: [PATCH] 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 | 100 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 81 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 0298bb9..08f3312 100644 --- a/README.md +++ b/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": ""` 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 │ -│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ -│ │ store │ │ query │ │ purge │ │ -│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ -│ │ │ │ │ -│ ┌──────▼────────────────▼────────────────▼──────┐ │ -│ │ Embedding Engine (ONNX) │ │ -│ │ all-MiniLM-L6-v2 (384d) │ │ -│ └──────────────────────┬────────────────────────┘ │ -│ │ │ -│ ┌──────────────────────▼────────────────────────┐ │ -│ │ PostgreSQL + pgvector │ │ -│ │ HNSW Index for fast search │ │ -│ └────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────┘ +┌─────────────────────┴───────────────────────────────────────┐ +│ OpenBrain MCP Server │ +│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ +│ │ store │ │ query │ │ purge │ │ +│ └──────┬──────────┘ └──────┬──────────┘ └──────┬──────────┘ │ +│ │ │ │ │ +│ ┌──────▼────────────────────▼────────────────────▼──────────┐ │ +│ │ Embedding Engine (ONNX) │ │ +│ │ all-MiniLM-L6-v2 (384d) │ │ +│ └──────────────────────┬────────────────────────────────────┘ │ +│ │ │ +│ ┌──────────────────────▼────────────────────────────────────┐ │ +│ │ PostgreSQL + pgvector │ │ +│ │ HNSW Index for fast search │ │ +│ └───────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────┘ ``` ## Environment Variables