setup-open-index

Set up Open Index for a domain agent

Open Index gives a domain-specialized agent structured context it can search, traverse, and maintain. It is read/write by default; use --read-only only when the agent must never update domain knowledge.

1. Install

From a local checkout:

python -m venv .venv
. .venv/bin/activate
pip install -e '.[mcp]'

If Open Index is published as a package, install the equivalent open-index[mcp] release instead. Never invent or hardcode credentials during setup.

2. Initialize the domain brain

Choose a short directory name and describe the actual domain in brain.yaml:

open-index init <brain-name>
cd <brain-name>
open-index validate
open-index index

Replace the example note schema with concepts meaningful to the domain. For example, a legal agent might model matters, clauses, obligations, and precedents; a support agent might model products, issues, customer segments, and resolutions.

3. Connect the MCP server

Configure the agent runtime to launch this command from the brain directory:

open-index mcp --brain /absolute/path/to/<brain-name>

Generic MCP configuration shape:

{
  "mcpServers": {
    "open-index": {
      "command": "open-index",
      "args": ["mcp", "--brain", "/absolute/path/to/<brain-name>"]
    }
  }
}

Adapt the location of this configuration to the selected client. Claude Code's optional adapter is .mcp.json; OpenClaw and Hermes may install this SKILL.md in their own skills directory while their MCP connection is configured according to that runtime's current documentation.

For retrieval-only access, append --read-only. Do not add it by default.

4. Verify the agent connection

Confirm the connected server exposes these default tools:

• navigation_guidelines
• search_brain
• get_entity
• put_entity
• create_doc_type

The MCP host should inject the server's dynamic domain-context instructions into the agent prompt. navigation_guidelines() is a refresh/fallback for hosts that do not support server instructions or after the schema/index changes.