> For the complete documentation index, see [llms.txt](https://docs.brain.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.brain.fi/concepts/memory.md).

# Memory

Brain holds, per tenant, a continuously updated record of every financial fact it has seen: transactions, balances, accounts, counterparties, obligations, invoices, contracts, on-chain transfers. You can query it as structured data or in natural language.

### Two Ways to Read It

```typescript
// Structured.
const txns = await brain.transactions.list("acme", { from: "2025-09-01" });

// Natural language.
const answer = await brain.ask("acme", "What did we spend on AWS last month?");
```

Both reach the same underlying record. Structured queries are precise and predictable. Natural-language questions are forgiving and discoverable. Use structured for code paths you'll hit often; use natural language for the questions you wouldn't have thought to filter for.

### What Goes In

Brain ingests from any source the tenant authorizes:

| Category                 | Examples                                                         |
| ------------------------ | ---------------------------------------------------------------- |
| **Banks and processors** | Plaid, direct bank APIs, Stripe, Adyen                           |
| **On-chain**             | Wallets via Alchemy, contract event streams                      |
| **ERPs**                 | NetSuite, SAP, Dynamics                                          |
| **Accounting**           | QuickBooks, Xero                                                 |
| **Payroll**              | Gusto, Rippling, ADP                                             |
| **Documents**            | Email-attached invoices, CSV/PDF uploads                         |
| **Agent contributions**  | Transcripts, signed contracts, observations from external agents |

You connect a source once. Brain handles the rest: pulling, parsing, normalizing, indexing, keeping it current.

### Citations on Every Claim

Every answer Brain gives carries citations back to source evidence.

```typescript
const answer = await brain.ask("acme", "Which vendor did we pay the most last quarter?");

answer.text;
// "Amazon Web Services, $182,431 across 14 invoices."

answer.citations;
// [
//   { type: "transaction", id: "tx_4127" },
//   { type: "transaction", id: "tx_4128" },
//   { type: "invoice",     id: "inv_8231" },
//   ...
// ]
```

You can render those citations in your UI as clickable proof. Open one and Brain returns the underlying transaction, invoice, or document.

### What "Continuously Updated" Means

| Trigger                         | Brain's response                                          |
| ------------------------------- | --------------------------------------------------------- |
| New transaction lands at a bank | Webhook arrives; record updates within seconds            |
| Invoice paid                    | Obligation closes; counterparty's payment history updates |
| Counterparty merged             | Duplicate entities resolve; relationships rewrite         |
| New month begins                | Rolling summaries regenerate                              |

There's no batch job you wait for. The memory is current.

### What "Tenant-Isolated" Means

Each tenant has its own logical record. Cross-tenant access is impossible by construction:

| Boundary          | How                                                                                                                                           |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Storage**       | Per-tenant database partitions and Azure Blob prefixes                                                                                        |
| **Encryption**    | Source credentials use a single AES-256-GCM key loaded from Azure Key Vault in production or `BRAIN_SOURCE_CREDENTIAL_KEY` outside production |
| **Authorization** | Every API call carries a tenant; cross-tenant reads return 404                                                                                |

You'll never accidentally surface one customer's data in another customer's response.

### Memory Compounds

The longer Brain runs for a tenant, the better it gets:

| Time horizon     | What improves                                                 |
| ---------------- | ------------------------------------------------------------- |
| **First days**   | Counterparty profiles emerge; basic narrative anchors form    |
| **First months** | Rolling baselines mature; anomaly detection becomes possible  |
| **First year**   | Year-over-year comparisons unlock; vendor history is deep     |
| **Multi-year**   | Cross-period narratives are durable; switching costs are real |

### Where This Lives in the Protocol

If you want to look under the hood, memory is built from three of Brain's six layers:

| Layer      | Job                                              |
| ---------- | ------------------------------------------------ |
| **Raw**    | Lossless ingestion of the original evidence      |
| **Ledger** | Deterministic structuring into immutable records |
| **Wiki**   | Continuously regenerated human-readable memory   |

[**→ Protocol: Raw and Ledger**](/protocol/raw-and-ledger.md)

### Related

| Concept                                | Page   |
| -------------------------------------- | ------ |
| The rules that govern action on memory | Policy |
| Who can read memory                    | Agents |
| Proving Brain's claims                 | Proof  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.brain.fi/concepts/memory.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.