Public/openbrain-mcp
1
0
Fork 0
mirror of https://gitea.ingwaz.work/Ingwaz/openbrain-mcp.git synced 2026-03-31 14:49:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add Agent Identity & Source Tagging section to README

Browse Source 
- 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
This commit is contained in:
admin
2026-03-28 02:36:05 +00:00
parent cb28b99343
commit 98baa27c90
1 changed files with 81 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
README.md
View File

@@ -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 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 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