AGENTS.md
+200 −169
https://raw.githubusercontent.com/inite-ai/inite-brain-service/HEAD/AGENTS.md
− # AGENTS.md — using Brain as your memory over MCP− This guide is for AI agents (Claude Code, Cursor, openclaw, custom MCP− clients) consuming **INITE Brain** — a bitemporal, per-tenant knowledge-graph− memory service on SurrealDB. Humans: start at− [docs/getting-started.md](docs/getting-started.md) instead.− ## Connect− Brain speaks MCP over **Streamable HTTP**, one endpoint per tenant:− POST https://brain.inite.ai/mcp # tenant from the credential− POST https://brain.inite.ai/mcp/<companyId> # explicit; must match the credential− Authorization: Bearer brain_<api-key>− ```− Reach for the tenant-less form when all you have is a URL — an− OAuth-discovered connector learns its tenant from the token's `org`− claim, not from the path. `GET /mcp/health` answers unauthenticated.− Harnesses with native remote-MCP support connect by URL + header. Harnesses− that can only spawn stdio servers use the first-party shim− [`@inite/brain-mcp`](clients/brain-mcp/README.md):− ```json− { "command": "npx", "args": ["-y", "@inite/brain-mcp"],− "env": { "BRAIN_API_KEY": "brain_…", "BRAIN_COMPANY_ID": "…" } }− ```− Self-hosted: add `BRAIN_BASE_URL` (or `BRAIN_MCP_URL`). The shim (v0.2) is a− transparent passthrough for tools AND resources (`resources/list`,− `resources/templates/list`, `resources/read`), and bridges sampling in− reverse — brain's `sampling/createMessage` reaches YOUR model, falling back− to a server-side template when your harness doesn't advertise sampling.− Auth, tenancy, scopes, and PII fencing are enforced server-side from the− key. Key scopes decide what `tools/list` returns: `brain:read` → read− surface; `brain:write` adds mutations; `brain:admin` adds GDPR forget.− Two further scopes exist but are hosting-operator-only (granted via env-key− config, never mintable through tokens): `brain:read_media` (media/biometric− evidence — stricter than `brain:read_pii`, not implied by it) and− `brain:platform_admin` (cross-tenant operator authority).− ## Tool surface− Read (with `brain:read`):− | Tool | One-line semantics |− |---|---|− | `search_knowledge` | Semantic search over the graph; entities + top facts; `asOf` for "what was TRUE on X" (valid time — a fact learned later still shows) |− | `search_multi_hop` | Planner-LLM decomposes into ≤5 anchored hops; returns an auditable evidence chain (`finalEntityIds` + `supportingFactIds`); `synthesize=true` for a grounded answer |− | `graph_retrieve` | Graph-first retrieval around named entities (1-hop neighbourhood); use when you already know WHICH entities |+ # AGENTS.md — contributing to INITE Brain+ > Using Brain as your agent's memory? See [docs/agents-using-brain.md](docs/agents-using-brain.md).+ This file is for AI coding agents (Claude Code, Cursor, Codex, Copilot, Gemini+ CLI, Windsurf…) and the humans working with them on **this repository**. It is+ the source of truth for commands, zones and the idea → PR loop.+ [CONTRIBUTING.md](CONTRIBUTING.md) is the human-facing companion; where the two+ disagree, this file wins (and please fix the other one).+ ## What this is+ INITE Brain is a bitemporal, per-tenant knowledge-graph memory service for AI+ agents, served over MCP (Streamable HTTP) and REST, on SurrealDB. NestJS 11 ++ TypeScript, pnpm, Node 22. Also in the repo: the landing/admin app+ (`brain-landing/`, Next.js), npm clients (`clients/*`), the agent skills+ (`skills/`) and the Claude Code plugin (`plugins/inite-brain/`).+ **Place in the INITE Triad:** Auth (inite-auth-service) issues tokens;+ Billing and Brain verify them. The token contract (issuer, audience, claims)+ is [inite-triad/docs/compatibility.md](https://github.com/inite-ai/inite-triad/blob/main/docs/compatibility.md);+ Brain's side of it is `src/auth/token-audience.ts`, pinned by+ `test/triad-token-contract.socket-spec.ts`.+ ## Ground rules (non-negotiable)+ 1. **Never edit a shipped migration.** Schema changes are a NEW file+ `src/db/migrations/NNNN_description.surql` (next free number, idempotent,+ `IF NOT EXISTS`). The migrator records applied ids per tenant and silently+ skips edited files, so an edit is invisible in production.+ 2. **Never weaken tenancy or per-user scope.** Every tenant is its own+ database (`NS=brain`, `DB=co_<companyId>`, reached only through+ `SurrealService.withCompany`). Omitting `userId` must keep returning+ tenant-global facts only — personal memory is never mixed in. No new code+ path may skip the scope fences (`src/auth/user-scope.ts`,+ `src/auth/tenant-scope.ts`, `src/search/internals/where-builder.ts`).+ 3. **Never change the token contract** (accepted `iss`/`aud`, claim shapes,+ scope names `brain:read|write|admin|read_pii|read_media|platform_admin`)+ without a Triad-level change agreed first.+ 4. **GDPR forget stays complete and synchronous.** `forget_entity` / user+ forget must keep cascading every derived row and leaving only tombstones.+ A new table holding user content must be wired into the cascade.+ 5. **No eval forks behind flags.** A flag whose purpose is to let one+ measurement see a different code path is a fork; forks live on git+ branches. Per-tenant behaviour is configuration (`RetrievalProfile`,+ extraction profile), not a flag. New engine-behaviour boolean flags fail+ `test/flag-budget.unit-spec.ts` until a maintainer approves the golden
Showing the first 40 of each.
