# AIGX Brain

> AIGX Brain is a plug-and-play external memory genome for AI agents, built with the same AIGX principles:
> scarce, addressed, lean context. It compiles bounded context packs by task
> scope, uses typed update/forget policies, and integrates through MCP in minutes.

## Core

- [Brain page (HTML)](https://aigx.dev/brain)
- [Brain protocol source](https://github.com/Lolner95/AIGX/blob/main/docs/brain-protocol.md)
- [AIGX spec](https://aigx.dev/aigx-spec.md)

## Default structure (all files are `.aigx`)

```text
brain/
├── soul.aigx
├── brain.index.aigx
├── profile.aigx
├── preferences.aigx
├── people.aigx
├── work.aigx
├── personal.aigx
├── episodes.aigx
├── procedures.aigx
├── rules.aigx
└── manifest.aigx
```

## Why this works

1. **Addressed retrieval:** the compiler resolves scope through `brain.index.aigx`, then ranks inside that
   scope. No memory dump.
2. **Typed policies:** `fact`, `preference`, `project`, `person`, `episode`, `procedure`, and `rule` have
   different write/confirm/forget behavior.
3. **Portable ownership:** users can inspect, diff, export, and move their brain.
4. **Safety gates:** sensitive memory is never auto-written and never auto-injected.

## MCP integration

The MCP surface is intentionally minimal:

- `aigx_recall(task, budget_tokens?)` -> returns `{ context_pack, ids, gaps }`
- `aigx_remember(observation)` -> returns `{ status: written|proposed, id?, reason? }`

Connect flow:

1. User logs in to dashboard.
2. User creates a connect code for an agent connection.
3. Agent connector exchanges code for a scoped key.
4. Agent calls `aigx_recall` before personal answers and `aigx_remember` for durable observations.

## API surface

- `POST /v1/brains`
- `POST /v1/brains/{id}/connections`
- `POST /v1/recall`
- `POST /v1/remember`
- `POST /v1/forget`
- `GET /v1/export.aigx`
- `GET /v1/audit`

Default scope profile: `context.read + memory.propose`.

## Agent protocol

1. Recall before personal answers.
2. Respect precedence: `rule > fact > preference > inferred`.
3. If `gaps` says unknown, ask the user.
4. Remember sparingly and only durable facts.
5. Never overwrite on conflict - propose and queue for approval.

## Standard

AIGX Brain and AIGX codebase genomes are one method applied to two organisms:

- `files.aigx` maps constraints to edited files.
- `brain.index.aigx` maps memories to task scopes.
- Both follow the same AIGX principles and parity discipline.