Extending the System

this ain’t some closed-source black hole. brainz is built to be ripped apart, modded, and pushed way past what we ship by default. every piece—memory, agents, inference, analytics—is plug-and-play. you want custom logic? drop it in. you want to fork it? go wild.

---

build your own agent

agents are autonomous workers that watch, score, rewrite, or retrain the model—basically, your own little ops crew running 24/7.

how to drop one in:

# backend/agents/my_custom_agent.py
class MyCustomAgent:
    def run(self, prompt: str, response: str) -> dict:
        # do whatever – scoring, rewriting, tagging
        return {
            "log": "custom logic executed",
            "action": "flagged",
            "status": "ok"
        }

• register it in core/registry.py

• trigger via:

  • cli → python cli/agent_runner.py

  • api → /api/agent/trigger

  • other agents (chain ‘em up, if you’re crazy enough)

agents get full access to: ✅ memory (vectors + tags) ✅ logs ✅ full prompt lifecycle + outputs

---

swap or extend your model

quick swap:

# .env
MODEL_NAME=tiiuae/falcon-rw-1b

wanna go harder? patch models/adapter.py → wrap it with quantization, lora, or even hybrid inference setups. restart the container → new brain, same runtime.

---

add new api routes

fastapi makes adding endpoints stupid easy:

# backend/api/routes/agent_control.py
from fastapi import APIRouter
router = APIRouter()

@router.post("/agent/trigger")
def trigger_agent(agent_id: str):
    return {"status": "launched"}

include it in api/server.py, done.

---

custom memory logic

want smarter vector recall or different scoring?

• change data/vectorizer.py → swap cosine for dot, euclidean, hybrid ann

• inject tag filters or session context before lookup

• need scale? dump postgres → faiss, weaviate, or whatever ann flavor you like

• log it → track whether hits actually improve inference quality

---

cli tooling – plug & extend

every script under cli/ has full runtime access. drop your own tool in, no permission needed:

# backend/cli/summarize.py
from backend.core.registry import registry

def main():
    model = registry.get("model")
    print(model("summarize today’s crypto news"))

if __name__ == "__main__":
    main()

✅ model ✅ logger ✅ memory vectors ✅ agents ✅ config

hook it up to cronjobs, bash loops, or external apis for self-training loops on autopilot.

---

first hacks to try

• daily twitter scraper agent that feeds memory + trains overnight

• memory cleaner that purges old vectors by score

• cli visualizer for prompt clusters

• ui toggle to swap models mid-session

---

contributing or forking

brainz is open-source under mit. no bs, no locks. workflow:

git clone https://github.com/brainz/OS
git checkout -b feat/my-agent
git commit -m "add my agent"

push a pr with: ✅ tests under /tests/ ✅ updated flags in docs ✅ a short “what it does”

we merge anything that doesn’t break the brain.