# AGENTS.md — how agents operate this brain
This file is the **schema** for LLM agents (Claude Code, Cursor, Grok, Codex, etc.) that maintain or query the Stacc Brain.
**Philosophy (Karpathy):** Obsidian is the IDE. The agent is the programmer. The wiki is the codebase.
**Scale twist:** at Telegram-scale, **markdown is not the source of truth for the compiled brain**. The hologram + exact side store are. Markdown is raw + projection + human browse.
---
## Product surfaces
| Surface | Path / URL | Agent use |
|---|---|---|
| Vault A (md SoT / pitch) | `/Users/stacc/brain-ab/vault-a` | Classic Karpathy browse; redteam wiki |
| Vault B (hologram SoT) | `/Users/stacc/brain-ab/vault-b` | Projection + plugin; query via API |
| Shared raw | `/Users/stacc/brain-ab/shared-raw/telegram` | Immutable participated export |
| Local brain | `python3 code/brain_b.py` / `store/brain_b.json` | Ingest / lint offline |
| Hosted API | `https://brain.stacc.bio` | Query / multi-tenant (when up) |
| Telethon | `~/.holo/tg.session` + `code/tg_pull_active.py` | Live + recent active chats |
---
## Layers (do not violate)
### 1. Raw (immutable)
- Desktop HTML exports, Telethon pulls, `live__*.md`
- **Never rewrite history.** Append new sources; dedupe by `(chat, message_id)`.
- Full **conversation turns** (you + counterparties) when a chat is kept.
### 2. Wiki / compiled
- **Arm A:** extractive + redteam wiki under `vault-a/wiki/` (chats, people, traps, promises).
- **Arm B:** holographic index + optional projection under `vault-b/wiki/`.
- Agent may update wiki after ingest; do not hand-edit thousands of raw files.
### 3. Schema
- This file + `vault-*/schema/CLAUDE.md` + `MONETIZATION.md`.
- Co-evolve only with explicit human OK for breaking convention changes.
---
## Identity
- Owner: **stacc overflow** / **notStacc** / stacc.
- Participated filter: chat kept if owner sent ≥1 text message in the window.
- Redteam lens: counterparties = **users**, commitments = **promises**, social-eng / wallet urgency = **traps** (lexical heuristics, not verdicts).
---
## Operations
### Ingest (raw → brain)
1. Prefer Telethon for recent/active:
`python3 code/tg_pull_active.py --dialogs 150 --per-chat 500`
Live: `python3 code/tg_pull_active.py --live`
2. Desktop exports: `python3 code/tg_to_md.py` / multi-export convert into `shared-raw/`.
3. Rebuild hologram:
`python3 code/brain_b.py --md shared-raw/telegram --store store/brain_b.json --wiki vault-b/wiki`
4. Redteam wiki compile: extractive compiler / prior `compile` pipeline into **both** vaults when corpus changes.
5. Hosted: rsync data + `systemctl restart brain` on the VPS (see deploy scripts).
### Query
1. **Prefer** `POST /v1/{tenant}/query` on hosted or local BrainB — not re-reading all of `raw/`.
2. Cite raw paths / chat titles for provenance.
3. For **exact string / seed / trap tokens**, use keyword/grep over raw (hybrid). Geometry is approximate.
4. File durable answers as findings / wiki pages when they compound.
### Lint
1. BrainB `lint()` — tensions, hubs, matrix size.
2. Redteam ledgers: `wiki/traps/ledger.md`, `wiki/promises/ledger.md`.
3. Orphans / missing entity pages in Arm A wiki.
4. Never claim “safe” from trap heuristics alone.
---
## Multi-tenant / hosted (layer 3)
| Tenant type | Auth | Use |
|---|---|---|
| `demo-telegram` | public | Marketing demo (corpus previously publicly leaked) |
| `group-*` | `X-Brain-Key` | Private group brains |
| Admin load | `X-Admin-Key` | `POST /admin/load` |
Agents serving **end users** must never mix tenants. One principal → one tenant namespace.
---
## Realtime TG for app users (product)
Human connects **their** Telegram user session (Telethon-style):
1. App provides `api_id` / `api_hash` from **https://my.telegram.org/apps** (or platform-managed app).
2. Login: phone → code → optional 2FA (same pattern as `holo/memory/tg_login.py`).
3. Session stored **encrypted per user**, never in git.
4. Worker: active dialogs with **conv turns** + `--live` forward stream → their tenant raw + hologram rebuild/increment.
5. User can deny-list chats via filter JSON.
Agents must not request seed phrases, 2FA codes in logs, or session files in chat.
---
## A/B discipline
When changing retrieval:
- Run `python3 code/ab_scale.py` (and `ab_scale_v2.py` when present).
- Report **p50/p95 latency**, scale curve, storage, planted-needle R@1 if available.
- Do not claim quality wins without a defined metric.
Known measured (v1, ~321k msgs): B ~**5000×** faster p50 than full md scan; B matrix ~1 MB vs ~25 MB raw.
---
## Safety
- No force-push of secrets. `~/.holo/creds.json` and `*.session` stay local chmod 600.
- Demo corpus is public-by-prior-leak; private tenants are not.
- Trap/promise tags are **signals for review**, not accusations.
---
## Quick commands
```bash
# query hosted (when healthy)
curl -s -X POST https://brain.stacc.bio/v1/demo-telegram/query \
-H 'content-type: application/json' -d '{"q":"solana rpc","k":5}'
# local hologram rebuild
cd /Users/stacc/brain-ab/code && python3 brain_b.py --md ../shared-raw/telegram
# scale A/B
python3 ab_scale.py --raw ../shared-raw/telegram
# open vaults
./scripts/open_vaults.sh
```
---
## Definition of done for an agent task
- [ ] Raw untouched except append/dedupe
- [ ] Wiki/hologram updated if ingest happened
- [ ] Query path uses brain API when corpus is large
- [ ] Metrics or explicit “not measured” on perf claims
- [ ] No secrets written into the vault or this repo