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`
- Memory visibility is determined by the API token in the MCP client config, not by `agent_id`
- On `openbrain.store`, use `agent_id` only as a provenance label for the storing agent when that label is useful
- On `openbrain.query`, do not send `agent_id` for normal retrieval; use `source_agent_id` only when you intentionally want to filter by source agent
- 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 memories visible to the current API token and can optionally narrow by `source_agent_id` and `before`, 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: Some API | Attribute: auth-method | Value: JWT with refresh tokens | Context: Chosen over session cookies for mobile app support",
  "metadata": {
    "source_agent": "some-a0",
    "category": "project-decision",
    "project": "someproject",
    "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 |