braindb-agent

BrainDB Memory Agent

BrainDB has its own internal agent (LiteLLM with pluggable provider via LLM_PROFILE; defaults to deepinfra/google/gemma-4-31B-it) that handles all memory operations. You don't call individual endpoints — you ask the agent in plain English via one endpoint: POST http://localhost:8000/api/v1/agent/query.

Health check:

!curl -sf http://localhost:8000/health > /dev/null 2>&1 && echo "OK" || echo "BRAINDB_DOWN"

If the output contains BRAINDB_DOWN, the memory database is not running. Do this:

1. Ask the user: "BrainDB isn't running. Do you want me to start it for you?"
2. Find the braindb repo — look for a directory that has ALL of these:
   • docker-compose.yml at the root
   • braindb/main.py
   • pyproject.toml with name = "braindb" Search in: current dir, parent dirs (up to 3 levels), common locations like ~/source/repos/**/braindb/.
3. Start it: cd <braindb-path> && docker compose up -d
4. Cache the path: echo "<braindb-path>" > ~/.claude/skills/braindb-agent/.repo_path
5. Wait for it: poll curl -sf http://localhost:8000/health for up to 30 seconds.
6. If healthy, proceed. If the user declines or start fails, proceed WITHOUT memory.

---

TOOL PRIORITY (read this first)

The agent has a clear order of tools it should reach for. When you phrase a request, lean into the sophisticated tools — don't ask it to "run SQL" for anything to do with recall or understanding.

1. Query-driven recall — "what do we know about X?" → the agent calls /memory/context (keyword-mediated fuzzy + embedding + graph + ranking, with diversity quotas). The default for ALL discovery and understanding.
2. Entity-driven neighbourhood — the agent's view_tree returns a nested JSON tree (root keyed by entity_type, children arrays per node, 1-N hops out, keyword + retired-wiki noise filtered by default, _truncated marker if more remain). Especially useful when an entity ID is already in hand — often sharper than another query about the same entity. On hub entities pass max_depth=3 for narrative chains.
3. Multi-step investigation — "investigate / disambiguate / resolve X" → the agent delegates to a subagent. Keeps the main context clean.
4. Direct lookups — view_entity_relations, get_entity, list_entities for narrow questions.
5. search_sql ⚠ exception only — for explicit aggregates (counts, GROUP BY, activity-log joins). Never for finding / understanding / "what's related to" — those are jobs for the tools above.