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.

If you're tempted to phrase a request as "run a SQL query that finds…" for finding or understanding something, stop — that's the recall or tree path's job. Ask in plain English.

Wikis are first-class memory entities curated by an internal maintainer + writer pipeline. The agent surfaces them through recall automatically when relevant — you don't have to ask for them explicitly, and you don't have to trigger anything to make new ones. Saving facts with the right keywords is enough; the scheduler runs maintain → write on its 60s tick and the wikis materialise on their own.

Internally the agent now researches from short previews and reads a full body only by id (paging large ones, or delegating big documents to a subagent), so its context stays clean — just ask in natural language ("read and summarise datasource X"); it handles the chunking itself.

RECALL — at conversation start, and whenever you need context

Ask the agent in natural language. It handles keyword formulation, multi-query search, graph traversal, and summarization.

Encoding note: When constructing the curl JSON body, use ASCII characters only — plain hyphens (-), straight quotes (", '), no em-dashes (—) or smart quotes. On Windows shells these get mangled in the JSON body and the server returns 400 Bad Request.

curl -s -X POST http://localhost:8000/api/v1/agent/query \
  -H "Content-Type: application/json" \
  -d '{"query":"Tell me who the user is - role, expertise, preferences, recent projects."}'

For topic-specific recall:

curl -s -X POST http://localhost:8000/api/v1/agent/query \
  -H "Content-Type: application/json" \
  -d '{"query":"What do you know about the user React frontend experience?"}'

Read the answer field from the response. Use the summary to inform your response. Never paste raw JSON into the conversation.

SAVE — after learning something new

Describe what you learned in natural language. The agent decides the entity type, picks keywords, generates embeddings, creates relations.

curl -s -X POST http://localhost:8000/api/v1/agent/query \
  -H "Content-Type: application/json" \
  -d '{"query":"Save: the user just told me they prefer simple code over abstractions. Source: user-stated. Connect to existing preference entities."}'

Proactive save — but ASK the user first

The pattern is RECALL → ASK → SAVE:

1. When the user shares something that might be worth remembering (a name, role, project, preference, decision, your own inference about them), RECALL first via the agent to check if it's already known.

2. If it's net-new, ASK the user:

   "I haven't seen this before — should I save it to BrainDB? I'd file it as a [fact / thought / rule] tagged with [keywords]."

3. Only on a 'yes', issue the save request to the agent.

Don't pre-save without confirmation. The user has the final say on what becomes long-term memory. User-confirmed memory is higher-signal and lets the user catch judgement-call mistakes early.

Exception: when the user explicitly framed it as a rule ("from now on, always X"; "never do Y"), save it without an extra confirmation — they already said it — but surface the action: "Saving that as a rule."

What's worth flagging to the user

• Identity / role / company (one-time setup info)
• Strong preferences or working-style rules
• Project / topic context the user just disclosed
• Decisions the user explicitly made
• Useful URLs or references the user shared
• Your own inferences about the user (tag as thought, source=agent-inference) — ASK before persisting these too; an inference is still memory.

The goal is to capture what the user gives you in conversation that isn't already in BrainDB — not to scrape every utterance. Information already in recall doesn't need saving again; ephemeral task details ("currently debugging X") don't need saving at all.

Example queries

Recall (no confirmation needed — these are reads)