Braindb

BrainDB — Persistent Memory System

You have access to a persistent memory database at http://localhost:8000. Use it to remember things about the user across sessions.

Health check and always-on rules:

!curl -sf http://localhost:8000/health > /dev/null 2>&1 && curl -s http://localhost:8000/api/v1/memory/rules || echo "BRAINDB_DOWN"

Skill version sync:

!REPO=$(cat ~/.claude/skills/braindb/.repo_path 2>/dev/null); if [ -n "$REPO" ] && [ -f "$REPO/skills/braindb/SKILL.md" ] && ! diff -q ~/.claude/skills/braindb/SKILL.md "$REPO/skills/braindb/SKILL.md" > /dev/null 2>&1; then echo "SKILL_UPDATE_AVAILABLE: $REPO/skills/braindb/SKILL.md"; fi

If the output above contains SKILL_UPDATE_AVAILABLE, a newer version of this skill exists in the local braindb repo (updated via git pull). Update it now:

cp <path shown in the output>/skills/braindb/SKILL.md ~/.claude/skills/braindb/SKILL.md

Tell the user: "I've updated the braindb skill to the latest version from the repo. The update will take effect on the next skill invocation." Then continue with the current task normally.

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

Step 1 — Ask the user

BrainDB isn't running. Do you want me to start it for you?

Step 2 — Find the braindb repo

A braindb repo is identified by having ALL of these:

• A docker-compose.yml at the root
• A braindb/ Python package directory (contains main.py)
• A pyproject.toml whose name = "braindb"

Search in this order:

1. The current working directory: does ./docker-compose.yml exist AND ./braindb/main.py exist?
2. Parent directories up to 3 levels
3. Common locations (use the Glob tool):
   • ~/source/repos/**/braindb/docker-compose.yml
   • ~/repos/**/braindb/docker-compose.yml
   • ~/projects/**/braindb/docker-compose.yml
4. If still not found, ask the user for the absolute path.

Step 3 — Start it and cache the repo path

From the braindb repo root:

cd <braindb-repo-path> && docker compose up -d

This builds if needed and starts the braindb_api container. The container runs alembic upgrade head on startup, then uvicorn braindb.main:app --host 0.0.0.0 --port 8000.

Also save the repo path so future skill invocations can check for updates:

echo "<braindb-repo-path>" > ~/.claude/skills/braindb/.repo_path

Note: the first start (build) can take 1-2 minutes. Subsequent starts take ~5 seconds.

Step 4 — Wait and verify

# Wait up to 30 seconds for it to come up
for i in 1 2 3 4 5 6; do
  sleep 5
  curl -sf http://localhost:8000/health > /dev/null 2>&1 && break
done
curl -s http://localhost:8000/health

If the final curl returns {"status":"ok"}, you're live.

Step 5 — Proceed or fall back

• If healthy: continue with the recall workflow below.
• If user declined or the start failed: proceed with the task WITHOUT memory. Don't keep retrying. Don't block the conversation.

Troubleshooting if startup fails

• docker compose up -d fails with "network not found" → the compose file references an external network. Check docker network ls for local-network, create if missing: docker network create local-network.
• alembic upgrade head fails → the database connection from .env isn't reachable. Tell the user to check .env and that their PostgreSQL is running.
• Health check never responds → check logs: docker logs braindb_api --tail 30

TOOL PRIORITY (read this first)

BrainDB's power is the graph + embeddings + ranking. Use it; do not fall back to flat SQL.

1. POST /api/v1/memory/context (multi-query) — the default for ALL query-driven recall, discovery, and understanding ("what do we know about X?"). BOTH the fuzzy and embedding pathways are keyword-mediated (the query matches against keyword entities, entities surface via tagged_with). A two-level diversity quota (per-search-term + per-keyword halving) keeps results balanced. Then graph traversal + decay
   • ranking.
2. GET /api/v1/memory/tree/<id>?max_depth=N — reveals an entity's neighbourhood as 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 as a last child if more remain. Especially useful when you have an entity ID (from a previous recall) and want its graph context — often a sharper choice than another /memory/context call about the same entity. On hub entities (wikis with many connections) pass max_depth=3 to see narrative chains.
3. POST /api/v1/agent/query with "delegate to a subagent…" — for multi-step investigation/disambiguation; the agent researches and returns a summary.
4. GET /api/v1/entities…, GET /api/v1/entities/<id>/relations — direct lookups (list-by-filter, single-hop relations).
5. Wikis — first-class entity type, curated topic pages assembled by an internal maintainer + writer pipeline from facts/thoughts tagged with the same keyword. To browse: GET /api/v1/entities?entity_type=wiki. Full body: GET /api/v1/entities/<id>. Wikis also surface naturally in /memory/context. Write paths are documented in the WIKIS section below.
6. POST /api/v1/memory/sql ⚠ exception only — aggregates only. A flat SELECT has no embeddings/graph/ranking. Use it solely for a specific structured/aggregate question (counts, GROUP BY, activity-log joins) the above cannot express. Never for recall, discovery, similarity, or understanding. Never for "what's around this entity" — that's /memory/tree.

If you're about to use /memory/sql to find or understand something, stop — that's a /memory/context or /memory/tree (or delegated /agent/query) job.

Previews vs full body

/memory/context (and /memory/search, GET /entities) return short previews per item (~1K); a clipped item ends with --truncated (N more) -- full body: get_entity("<id>"). That's intended — decide from previews, then read only what you need:

• Full single entity: GET /api/v1/entities/{id}.
• Large body: page it — GET /api/v1/entities/{id}?offset=0&limit=8000, then follow content_meta.next_offset until it is null. For big documents, prefer POST /api/v1/agent/query with "delegate to a subagent to read and distil entity <id>" so the heavy content never enters this conversation.
• Fact notes may include a byte range like (bytes 245760-252960) — pass directly as GET /api/v1/entities/{id}?offset=245760&limit=7200 to read the exact source slice the fact was extracted from.

RECALL — Before Responding

Step 1: Formulate targeted queries

Analyze the user's message. Extract the core topics that need memory context. Create multiple targeted queries — do NOT paste the raw user message.

Query strategy — BrainDB's retrieval is keyword-mediated, so:

• Prefer multiple narrow queries (single keywords / bare names) over one long sentence. Keywords are short, so a short query matches them cleanly; a long phrase dilutes pg_trgm similarity against the keyword.
• The per-search-term quota reserves slots for EACH query you pass, so adding a bare keyword as one of your queries guarantees it surfaces (it doesn't compete with the broader phrases).
• Use terms that match how entities are STORED. Common keyword conventions: user-profile, expertise, project-decision, user-preference.

Examples (narrow + one broader angle, mixed):

Always include a "user-profile" query on the first message of a conversation — you need to know who you're talking to.

Step 2: Call the multi-query context endpoint

curl -s -X POST http://localhost:8000/api/v1/memory/context \
  -H "Content-Type: application/json" \
  -d '{"queries": ["narrow1", "narrow2", "one broader phrase"], "max_depth": 3}'

max_results defaults to 30 — leave it unless you specifically want fewer.

Step 3: Evaluate results and retry if weak

If you got 0 results, your query terms didn't match stored content. Reformulate with more specific terms that would actually appear in entity content or keywords.

If results are weak — Retry 1: Reformulate queries with different terms.

• "machine learning" missed? Try "ML artificial intelligence data science"
• Too specific? Broaden: "user-profile technical background" instead of "user-profile Python metaprogramming"
• Too broad? Narrow: "React hooks state management" instead of "frontend development"

If still weak — Retry 2: Final broad sweep:

{"queries": ["user-profile expertise", "project-decision", "user-preference"], "max_results": 15}

After 2 retries, accept what you have and proceed.

Step 4: Use results naturally

NEVER paste raw JSON API responses into the conversation. Parse results silently and use the content to inform your response. When you need to show the user what's in memory, format it as clean bullet points or a markdown table — not JSON.

Let recalled facts inform your response. Do NOT announce "I found in memory that..." unless sharing the memory is directly relevant. If you know the user is senior in ML, calibrate your explanations accordingly — don't narrate that you remembered it.

SAVE — After Responding

After each interaction, evaluate what you learned. The policy is RECALL → ASK → SAVE.

Saving philosophy — always ASK the user first

Always recall first. If what the user shared is net-new (not already in /memory/context), ASK the user before saving:

"I haven't seen this before — should I save it as a fact / thought / rule? (I'd tag it with keywords X, Y; importance Z.)"

Only persist after the user confirms. The user has the final say on what becomes long-term memory. Auto-saves without confirmation dilute signal and accumulate junk; user-confirmed memory is higher-signal and traceable.

Exception — behavioural rules the user explicitly stated as rules ("from now on, always X"; "never do Y") can be saved without an extra confirmation — they already said it. Just surface the action: "Saving that as a rule."

Once the user agrees:

• Create RELATIONS for every new entity. Connect it to existing entities found during recall. Multiple relations per entity is ideal — the graph's value comes from density.
• Thoughts (your own inferences about the user) — ASK before persisting, same as facts. A thought is still memory; the user should agree it belongs there.

What to save as