Add agent memory with Brains

Before you start

You need a Ringside API key with the api:write scope. Every call below uses your Bearer key. Replace brn_abc with the id returned from step 1.

1. 1
   1. Create a brain

   Pick an encryption mode now. Use standard or strict for regulated data. Pick the embedding model deliberately — it governs every vector — though you can change it later with POST /v1/brains/{id}/reindex.

   bash

   Copy

   curl https://api.fightclub.pro/v1/brains \
     -H "Authorization: Bearer $RINGSIDE_KEY" \
     -d '{ "name": "Support assistant", "encryption": "none" }'
   # -> { "id": "brn_abc", ... }

2. 2
   2. Load reference knowledge

   Reference entries are chunked and embedded. Scope them so a tenant only ever sees its own.

   bash

   Copy

   curl -X PUT https://api.fightclub.pro/v1/brains/brn_abc/entries \
     -H "Authorization: Bearer $RINGSIDE_KEY" \
     -d '{ "scope": "/acme", "class": "reference",
           "title": "Refund policy",
           "body": "Refunds are issued within 14 days for unused credit ..." }'

3. 3
   3. Recall

   Recall at a scope sees that scope and its ancestors. Add explain to see why each hit ranked.

   bash

   Copy

   curl https://api.fightclub.pro/v1/brains/brn_abc/recall \
     -H "Authorization: Bearer $RINGSIDE_KEY" \
     -d '{ "scope": "/acme", "query": "can I get a refund?", "explain": true }'

4. 4
   4. Let it learn

   Send a finished turn. The brain keeps only durable facts and ignores chatter. Use wait=true to see the result inline.

   bash

   Copy

   curl "https://api.fightclub.pro/v1/brains/brn_abc/observe?wait=true" \
     -H "Authorization: Bearer $RINGSIDE_KEY" \
     -d '{ "scope": "/acme",
           "transcript": "user: our account manager is Dana Lee\nassistant: noted" }'
   # -> { "changed": 1, "proposed": 0, "conflicts": 0, "used": 0 }

5. 5
   5. Make it ambient

   Attach two headers to a normal completion. Ringside recalls before the call and learns after. No recall or observe code on your side.

   bash

   Copy

   curl https://api.fightclub.pro/v1/chat/completions \
     -H "Authorization: Bearer $RINGSIDE_KEY" \
     -H "Brain: brn_abc" \
     -H "Brain-Scope: /acme" \
     -d '{ "model": "match:anthropic/sonnet",
           "messages": [{ "role": "user", "content": "who is our account manager?" }] }'

Tuning what it remembers

The defaults are sensible, but the memory_policy is yours to shape. Two common changes:

• ·Stop it learning small talk or off-task content with an ignore block (a rubric, regex patterns, or require_task_relevance).
• ·Change how fast a fact fades with a per-type decay curve — a short half-life for incident, a slow power curve for preference. Prefer tuning decay per type over flipping the brain-wide decay_anchor: it is already last_used by default, and setting it globally also stops short-lived incident/state facts from ever expiring (their recency clock keeps resetting every time they are used).

curl -X PATCH https://api.fightclub.pro/v1/brains/brn_abc \
  -H "Authorization: Bearer $RINGSIDE_KEY" \
  -d '{ "memory_policy": {
          "type_taxonomy": [
            { "type": "incident", "tier": "D",
              "decay": { "fn": "exponential", "half_life_days": 4 } }
          ],
          "ignore": { "require_task_relevance": true }
        } }'

Gating sensitive writes

For regulated workflows, set learn_mode: "review" (or a per-tier review threshold) so load-bearing changes wait in a queue. Approve them with the proposals endpoint. Facts learned from external content are low trust and are routed to review automatically when they would land in a protected tier.