Vaults

A vault is a balance you hold: petty cash, a bank account, a card, a wallet, a float or a deposit. Every change to it is a movement, so the balance is always explained by its history. Vaults also show your money across all of them, month by month (module vaults).

In the sidebar under Money → Vaults. Handles money: when an agent tries to change anything here, a person is asked to approve it first (Agents and approvals).

What you see

The page has two tabs.

Vaults

• A list of vaults with their name, kind and balance in the vault's own currency. Archived vaults are marked.
• Counters for how many vaults there are and how much is held in each currency.
• Open shows one vault. Recalculate opens it and checks its balance at once. Transfer appears once there are two vaults.

Inside a vault you see its balance, how many movements it has, and every movement in order: its kind, amount, the other end (another vault, a cost, or outside), the reason and the date. Each movement has History, and people who may change vaults also see Edit and Remove, or Restore on a removed one. Show removed lists removed movements too; they are off the balance either way.

Overview

Your money across every live vault, converted into one currency you choose, over a number of months you choose:

• Net worth now, the change in a month and since the start, money in and out this month (transfers between your own vaults left out), and the savings rate.
• Net worth: each vault at each month's end, with money owed shown below the line.
• Money in and out: per month, from and to outside your vaults, with the net and how much was kept.
• Where it sits: what is held now, split by kind of vault and by currency.
• Vaults: each vault's month ends, its balance, its last movement and whether its movements add up to its balance.
• What to look at: suggestions, most urgent first.

A vault with no exchange rate into the chosen currency is listed apart and left out of every total. Rates come from Accounts.

What you can do

Make a vault

1. Choose New vault.
2. Give it a name, such as "Cash USD", a kind and a currency.
3. Save. It starts empty. Money arrives by a deposit or a transfer, never by typing a balance in.

Record money in or out

1. Open the vault and choose Deposit for money arriving from outside, or Withdraw for money leaving.
2. Enter the amount, the date and a reason.
3. Save. The balance moves and the books are told.

Move money between vaults

1. Choose Transfer.
2. Pick the vault it leaves (From) and the one it reaches (To), and the Amount out.
3. When the two vaults hold different currencies, fill in Arrives as with what reached the other side. That records an exchange.
4. Add a reason and a date, and save. Both balances change.

Correct or take back a movement

1. In the vault, choose Edit on the movement to correct its amount, the amount that arrived on an exchange, its reason or its date. The balances move by the difference, and what it said before is kept.
2. To take a movement back, choose Remove and say why. Its amounts come off both balances and out of the books. It is marked removed, not deleted.
3. Restore puts a removed movement back.
4. History shows every state a movement has been in, who changed it, when, why, and what the books did each time.

Which vaults a movement touched cannot change. Remove it and record the right one.

Check that a balance adds up

1. Open the vault and choose Recalculate balance.
2. The page shows what the movements add up to beside the stored balance, and whether they agree.
3. If they differ and the movements are complete, choose Set balance to … to take their total. If the account really holds something else, a movement is missing: record it first, then recalculate again.

An agent can also book the difference as an adjustment movement instead, which keeps the balance and explains it in the history.

Rename, archive or delete a vault

1. Choose Edit on a vault's row to rename it or change its kind. Its currency can change only while it has never held or moved anything.
2. Delete removes a vault that never moved anything. One with history is refused.
3. Retire a vault with history by archiving it. Archiving has no button on this page: it is done through the API or by an agent with vaults.update.

Tie statement numbers to a vault

A card ending or an account number printed on statements can be tied to a vault, so a statement read by Extraction lands in the right vault without asking. One number names one vault. This is done through the API and agent tools.

Keep credentials with a vault

A vault can hold credentials, such as a banking sign-in: a label, a username and a secret, encrypted when stored. Lists show the label, username and vault, never the secret. Credentials are managed through the API, and agents can list and delete them.

Who can do what

Permission	Label	Lets you
vaults:read	View vaults	Open Vaults and the Overview, see balances, movements, history, aliases and credential labels. Agents need it for every read tool.
vaults:write	Manage vaults	Make, edit, archive and delete vaults; deposit, withdraw and transfer; correct, remove and restore movements; recalculate balances; manage aliases and credentials. Agents need it for every change tool.

Roles and how permissions are granted are explained in People, roles and permissions.

What runs on its own

Job	When	What it does
ledger-catch-up	Every hour at minute 23 (23 * * * *)	Puts into the books every movement that is not there yet, for example because no rate existed for the day or a month was locked when it was recorded. A movement that has not changed writes nothing; a changed one writes a new revision; one a person reversed stays reversed. A movement that is gone has its entry reversed. Where the books disagree with a movement, the difference is recorded as a finding.

How vaults reach the books

• Each movement is booked in Books as its own entry. A transfer between vaults kept in different entities becomes two entries, one in each.
• A cost paid from a vault is booked by Costs, not here, so the money is not counted twice.
• A deposit with no recorded source is booked against a suspense account and flagged for a person to review. Mapping that vault's deposits to an account in the books teaches it where later ones belong.
• Costs records its own movement in the vault it was paid from, through a link this module offers.

For agents

An agent can read balances, movements and the overview, record and correct movements, and tidy vaults, aliases and credentials.

This module handles money. When an agent calls a tool here that changes something, the call goes to a person for approval first, whatever the agent's policy says, and no per-tool rule can set it to allow. Reads follow the agent's policy as usual. A person working in the app, or an API key somebody set up, is not held by this rule: their permissions decide. Several tools here are marked as spending money (vaults.move, vaults.transfer, vaults.updateMovement, vaults.restoreMovement, vaults.recompute), and no rule can ever allow spending without asking.

Read

• vaults.list: vaults and their balances.
• vaults.movements: recent movements in and out of a vault.
• vaults.reconcile: the stored balance beside what the movements add up to, and the drift. It changes nothing.
• vaults.overview: money across every live vault by month: net worth, money in and out, savings rate, splits by kind and currency, and suggestions.
• vaults.movementHistory: every state a movement has been in, with who, when, why and what the books did.
• vaults.credentials: the credentials kept with the vaults, label and username only.
• vaults.aliases: the card endings and account numbers tied to vaults.

Record and correct movements

• vaults.move: money arriving from outside a vault, or leaving it. Spends.
• vaults.transfer: money between two vaults, with the arriving amount for an exchange. Spends.
• vaults.updateMovement: correct a movement's amount, arriving amount, reason or date. Spends.
• vaults.removeMovement: take a movement back; it can be restored. Destructive.
• vaults.restoreMovement: put a removed movement back. Spends.

Fix a balance

• vaults.recompute: book an adjustment movement for exactly the drift, so the history explains the balance. Spends.
• vaults.adoptLedger: set the balance to what the movements add up to, writing no movement. Destructive.

Vaults, aliases and credentials

• vaults.create: make an empty vault.
• vaults.update: rename, change kind, archive or bring back.
• vaults.remove: delete a vault that never moved anything. Destructive.
• vaults.addAlias: tie a card's last 4 digits or an account number to a vault.
• vaults.removeAlias: untie a number from its vault. Destructive.
• vaults.removeCredential: delete a credential for good. Destructive.

Over MCP the same tools are named vaults__list and so on (API keys and MCP access).

Related

• Money
• Costs: costs paid from a vault move its balance.
• Books
• Accounts: exchange rates for the overview and the books.
• Extraction: reads statements into vaults.