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:

   # 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

{
  "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