Aegis MoneyScope Documentation

Aegis MoneyScope is a private, local-first personal finance analyzer. It reads your bank and credit-card statements, organizes every transaction into spending categories, and shows you where your money goes, how your cash flows month to month, how your spending compares with similar households, and what a change in habits would be worth. A built-in AI advisor answers questions about your finances in plain English.

Statements, transactions and analysis live in a database on your own computer. All AI features run on a local model through Ollama. There is no telemetry and no account to create.

Installation & Setup

Aegis MoneyScope is available for Linux as a Snap or as a Debian/Ubuntu .deb package from the download page.

Snap

Install from the Snap Store, or in a terminal:

sudo snap install aegismoneyscope --candidate

To open statement files on USB drives, connect this interface once:

sudo snap connect aegismoneyscope:removable-media

With the Snap, your data live under ~/snap/aegismoneyscope/current/.aegismoneyscope/.

Debian / Ubuntu (.deb)

cd ~/Downloads
sudo apt install ./aegismoneyscope_*_amd64.deb

The app appears in your applications menu under Office → Finance, and as aegismoneyscope on the command line. On first start it asks whether you prefer a Dark or Light appearance; you can change it later under Configure → Appearance.

Local AI (Ollama)

MoneyScope uses Ollama to run AI models on your own computer. See our Ollama setup guide, or on Linux:

curl -fsSL https://ollama.com/install.sh | sh

The app uses two models, which can be the same one:

• Statement extraction model — reads PDF statements whose layout isn't recognized automatically, and categorizes merchants the built-in rules don't know.
• AI advisor chat model — answers your questions and writes summaries. It must support tool calling.

The default for both is qwen2.5:14b (about 9 GB):

ollama pull qwen2.5:14b

On a computer with less memory, use qwen2.5:7b (about 4.7 GB) and select it under Configure → LLM Settings. As a rule of thumb, a 7B model needs about 8 GB of RAM and a 14B model about 16 GB. A GPU makes answers much faster but isn't required.

The Window

Pick a page from the list on the left. The AI Advisor chat is docked on the right on every page (it can be moved to the left or floated).

Press F1 at any time for the built-in user guide.

Importing Statements

Ways to import

• Drag and drop files onto the Accounts panel's drop zone.
• Click + in the Accounts panel, or choose Tools → Import Statement.
• From a terminal: aegismoneyscope --import statement1.pdf export.ofx activity.csv. If the app is already open, the files are handed to the running window.

Imports run in a separate background process, so the window stays responsive. A progress card for each file shows its stage, and the status bar reports the result, such as "84 transactions imported (3 duplicates skipped)".

What happens during an import

• The institution and account are identified. An account imported before — even in a different format — is matched by institution and last four digits.
• Signs are normalized: money out is negative, money in is positive. Card exports that list charges as positive amounts (common with American Express, Discover and Citi) are detected and flipped.
• Duplicates are skipped, so overlapping statements and re-downloads are safe.
• Card payments are flagged as transfers, and transfers between your accounts are linked.
• Categorization runs (see Categories).
• A copy of the file is archived in ~/.aegismoneyscope/statements/.

CSV details

Recognized columns include Date / Transaction Date / Posting Date, Description / Payee / Merchant, Amount, separate Debit and Credit (or Withdrawal and Deposit) columns, a DR/CR type column, Status, Category and Card Number. Summary lines above the header, comma / semicolon / tab delimiters, month-first or day-first dates, and amounts such as $1,234.56, (12.34), 12.34- and decimal commas are all handled. Pending rows are skipped. A bank-supplied Category column is used as a hint.

Re-importing

Dropping a file that was already imported re-processes it: the old copy of that statement is removed and the file is read again — useful after improving category rules or updating the app.

Accounts & Transactions

The Accounts panel is a tree of Institution → Account → Statement. Click an account for all its transactions, or a statement for just that statement's. Right-click for Details or Delete, or press Delete / Backspace; deleting removes everything underneath, after confirmation.

The Transactions panel lists Date, Description, Category and Amount (money out in red, money in in green). Search filters as you type, a category filter narrows the list, and the footer totals count, income, expense and net.

Correcting a transaction

Right-click a transaction:

• Set Category… — choose a category and the scope: all transactions with the same vendor (the rule is remembered for future imports) or this transaction only.
• Toggle Transfer — mark or unmark money moving between your own accounts. Transfers are excluded from spending everywhere.
• Delete Transaction — after confirmation.

Every change refreshes Analytics, Cross Accounts and Scenarios immediately.

Categories

Income, Housing & Utilities, Utilities, Groceries, Dining & Entertainment, Transportation, Health & Wellness, Personal & Lifestyle, Recreation & Travel, Charity, Financial & Transfers, Streaming Services, Education and Home Improvement. Add your own under Tools → Manage Categories. Each category is also tagged essential or discretionary, and fixed or variable.

How a transaction gets its category

The cheapest, most reliable signal wins, in this order:

1. Your learned rules — every "all transactions from this vendor" correction. These always win.
2. Your personal rules file, if you have one (below).
3. The built-in U.S. rules: about 2,700 patterns covering national and large regional chains — grocers, fuel, restaurants, pharmacies, utilities, telecoms, insurers, lenders, airlines, hotels, streaming — plus general keywords. They recognize the abbreviations banks print, such as AMZN MKTP, WHOLEFDS or TST*.
4. The local AI model for whatever is left, in batches of 40 merchants with your own corrections as examples. An answer below 50% confidence is left Uncategorized rather than guessed.

Ambiguous charges — checks, generic "insurance", person-to-person payments, Square or PayPal charges with no merchant name — are deliberately not guessed.

Tools → Auto-Categorize Uncategorized (Local AI) re-runs the rules and the AI over everything still uncategorized, without changing transactions that already have a category.

Writing your own rules

Create ~/.aegismoneyscope/categories.local.yml. It is read before the built-in rules and never overwritten by updates:

- category: Groceries
  match: [CORNER MARKET, VILLAGE FARM STAND]
- category: Education
  match: SCHOOL FIELDSTUDIES
  necessity: essential
  variability: fixed
- category: Transportation
  word: true          # whole-word match, for short codes
  match: [JR]

• Matching ignores case and looks anywhere in the merchant name or description; word: true requires a whole word; a pattern starting with ^ is a regular expression.
• The first matching rule wins, so put specific rules before general ones.
• Use category: Uncategorized to stop a merchant from being guessed.

A report of merchants that matched no rule, sorted by spend, is written to ~/.aegismoneyscope/reports/unmatched-merchants.csv — the best place to start.

Cross Accounts

Paying a card from checking, or moving money to savings, shows up twice — once leaving one account and once arriving in another. Counting both would double-count every card purchase, so these are treated as transfers.

Matched transfers have both sides found (an equal and opposite amount within four days). Unmatched ones were recognized from their description, but the other side hasn't been imported yet. Use Toggle Transfer in the Transactions panel to mark or unmark one by hand.

Analytics

Analytics works from a cleaned copy of your transactions: transfers and duplicates are removed, refunds are netted against their purchases, and year mix-ups on statements spanning New Year are corrected. It rebuilds automatically whenever transactions change.

The date range bar applies to every view. The data-quality strip beneath it shows the share of spending still uncategorized (amber above 5%), transfers excluded, the date range covered and the latest statement date. Most charts are clickable and open the transactions behind them.

Cash Flow

Analytics → Cash Flow answers when, and how reliably, money comes and goes.

• Headline figures: average income, spending and net per month; savings rate; and how much of your income recurring charges claim.
• What stands out: deficit months, your main income source and pay cadence, income concentration, the payday effect, your heaviest spending weekday and time of month, volatility, and a 30-day projection.
• Income streams: each source with its cadence (weekly, biweekly, semi-monthly, monthly, quarterly, annual or irregular), typical deposit and next expected deposit.
• Next 30 days: expected paydays, upcoming recurring charges and average day-to-day spending, adding up to a projected net.

Explain with local AI has the local model describe these patterns and suggest one or two realistic actions. Only the computed figures are sent to the model — never individual transactions.

Benchmarks

Vs. similar households

Your spending mix compared with average U.S. households, using approximate figures from the U.S. Bureau of Labor Statistics Consumer Expenditure Survey. Compare with picks an income bracket automatically from your statements, or choose All households, Under $50k, $50k–$100k or Over $100k.

Comparisons use shares of spending, not raw dollars: statements don't show payroll deductions and may not include every account, so shares are fairer. Transfers, income, fees, taxes and uncategorized spending are not benchmarked. The figures are rounded approximations meant for perspective, not precise targets.

Vs. your own history

Your latest complete month against your average over the previous six months. A category is flagged Higher or Lower when it moves by at least 25% and at least $25.

Scenarios

The Scenarios page asks: what would change if I spent less on this?

• Create, duplicate, rename and delete named scenarios; they're saved automatically.
• Choose a baseline: Latest Month, Last 3 Months, Last 12 Months or All Time, averaged per month.
• Set a 0–100% cut per category, or Remove it entirely. Each row shows baseline and scenario monthly spend and what the change is worth per year.
• Headline cards show the monthly and annual saving, and net cash flow against your income.

Scenarios never change your data — they're what-ifs.

AI Advisor

The chat panel answers questions using the local AI model. It looks up your actual data with built-in tools — spending by category, monthly overviews, transaction search, largest expenses, cash-flow analysis, benchmarks, account lists and read-only database queries — rather than guessing.

• How much did I spend on dining in March?
• What are my biggest recurring charges?
• When do I usually get paid, and will I have enough for rent next month?
• Show me a chart of my grocery spending over the last year.

The advisor knows which account or date range you're looking at. Larger chat models give better answers.

Agent Outputs

When an answer is clearer as a picture, the advisor draws a bar, line or pie chart or a table on the Agent Outputs page. Charts are checked against the data the advisor actually retrieved, so it can't display invented numbers.

Memory

Short summaries of past conversations are written periodically and when you close the app (you'll see "updating memory" for a few seconds). Memory is stored separately from your financial data.

External AI Tools (MCP)

MoneyScope can make its data and tools available to applications that support the Model Context Protocol, such as Claude Desktop or Cursor. Point your application's MCP configuration at:

aegismoneyscope --mcp-server

The main app must be running: the MCP server talks to it through a local bridge on 127.0.0.1:8002 that only accepts connections from your own computer. Tools include importing statements, listing and searching transactions, categorizing, spending summaries, monthly trends, savings analysis, benchmarks, cash flow and read-only queries.

Configure & Tools

LLM Settings

• Ollama Host — blank for the default (http://localhost:11434), or the address of Ollama on another computer on your network.
• Statement extraction model and AI advisor chat model. The chat model must support tool calling (Qwen 2.5, Llama 3.1+, Mistral and similar).
• Refresh model list re-checks the connection. Changes take effect without restarting.

Other settings and tools

• Appearance — Dark or Light theme, with a live preview.
• Storage — database and archive locations, database size, Clear Temp Files.
• Tools → Clear All Data — after confirmation, deletes every institution, account, statement, transaction and learned vendor rule. Categories are kept. This cannot be undone.
• View — show or hide the Accounts panel, Transactions panel and AI Advisor. Layout is remembered.

Data, Privacy & Backup

• No cloud services, no accounts, no telemetry.
• All AI runs locally through Ollama. If you point Ollama Host at another computer, your data goes to that computer — use one you control.
• The diagnostic AI log stays on your computer; start the app with AEGIS_LLM_LOG=0 to turn it off.
• Feedback (Help → Provide Feedback) opens your own email client, so you see exactly what is sent.

Backing up

Close the app and copy the ~/.aegismoneyscope folder. To restore, put it back. The folder holds your complete financial history — store backups somewhere secure, ideally encrypted.

Beta & Licensing

Aegis MoneyScope is in Beta. It is still being refined: you may run into rough edges, and features and screens may change between versions. Reports from Beta users directly shape what gets fixed next.

There is no license charge during the Beta. Every feature is available, and no license key, account or sign-up is needed. In the future we may limit some features unless a one-time license is purchased — a single purchase, not a subscription. Help → About shows the version you are running.

Troubleshooting

"Ollama not found" at startup

Install and start Ollama, then check that http://localhost:11434 says "Ollama is running". On Linux, systemctl status ollama shows whether the service is running and sudo systemctl start ollama starts it.

"Model not installed"

Run ollama pull <model> for the model named in the message, or choose an installed model under Configure → LLM Settings. ollama list shows what's installed.

The AI is slow

Use a smaller model such as qwen2.5:7b, close memory-hungry applications, or run Ollama on a computer with a GPU and enter its address as the Ollama Host. OFX/QFX/CSV imports don't use the AI at all.

"No transactions found" in a PDF

The PDF may be a scanned image with no text. Download the statement as OFX/QFX or CSV instead.

Many transactions are Uncategorized

Run Tools → Auto-Categorize Uncategorized with Ollama running. For merchants you see often, right-click one and choose Set Category → all transactions with the same vendor. Check unmatched-merchants.csv for the merchants worth teaching first.

Spending looks doubled

A card payment or transfer wasn't recognized. Right-click it and choose Toggle Transfer. Importing both sides (the card and the bank account) lets the app match transfers automatically.

A month looks much higher than usual

Switch Trend to Amortized to spread annual charges, or check Top Merchants for a large one-off purchase.

Charts are empty

Check the date range bar and the data-quality strip's date range. Try All Time.

Reporting a problem

Use Help → Provide Feedback in the app, or email support@yourprivacysw.com. Please don't include account numbers or other financial details.

Contact Support