Aegis Retirement Planner Documentation

Aegis Retirement Planner turns a conversation about the retirement you want into a budget, a bucket strategy and Monte Carlo odds that the money lasts. Everything runs on your computer: the language model runs locally through Ollama, and your plans are stored in a local SQLite file.

Installation & Setup

Aegis Retirement Planner 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 aegisretirementplanner

To open statements, plans and reports on USB drives, connect this interface once:

sudo snap connect aegisretirementplanner:removable-media

With the Snap, your plans live under ~/snap/aegisretirementplanner/current/.aegisretirementplanner/.

Debian / Ubuntu (.deb)

Download the package, then install it with apt so its dependencies are pulled in:

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

The app appears in your applications menu under Office → Finance, and as aegisretirementplanner on the command line. The package bundles its own Python environment under /opt/aegisretirementplanner/.

Local AI (Ollama)

The interview, the Ask Aegis assistant and statement import use a local model through Ollama, installed separately — see our Ollama setup guide. Then pull the default model:

ollama pull qwen2.5:7b

It runs on an 8 GB laptop without a GPU. The app checks for Ollama on first start, and Settings → Check Ollama shows anything that is missing.

The Pages

The Ask Aegis panel on the right answers questions about your plan and proposes changes, which you accept or reject. Press F1 at any time for the built-in guide.

The Interview

Aegis works through these topics, following your lead: household and ages; retirement age; where to live; housing; health and insurance; travel; hobbies; entertainment and dining; family support; giving and legacy; work in retirement; risk comfort; and savings, pensions and Social Security.

After every answer, a second, careful pass turns what you said into profile fields. Each field remembers whether you stated it, it was inferred, or it is a default, along with the words it came from. Inferred values are read back once for you to confirm.

Tips

• Ranges are fine: "three or four trips a year" works.
• Skip this topic uses typical values you can change later.
• Reopen a topic when plans change ("we decided to move to Portugal"). Only the affected budget lines update; lines you edited yourself are kept.
• If something was recorded wrongly, correct it in chat ("no, we rent") or on the Profile page — both write the same record.
• Start over clears the conversation and answers; a snapshot is saved first.
• Skip to forms if you'd rather type than talk.

When the topics are done, press Build my budget.

Importing Statements

Instead of typing balances, import the statements you already have: 401(k), 403(b), 457, TSP, traditional, Roth, SEP and rollover IRAs, brokerage and HSA statements, pension benefit estimates, and your Social Security statement (from ssa.gov/myaccount).

1. On the Profile page choose Import statements… (or File → Import retirement-plan statements).
2. Pick one or more files. PDF is best; PNG, JPG, TXT and CSV also work.
3. Aegis reads each one on your computer with your local model and lists what it found.
4. Check the list. Change the owner, account type or amount, or untick a row, then press Apply selected.

What gets checked

• Every amount is looked up in the statement's own text. If it isn't there, the row is marked ⚠ Check and starts unticked — models sometimes misread numbers.
• A statement for an account you imported before (same last four digits and type) updates it; a new one is added.
• The first statement of each type replaces the interview's rough estimate.
• Pre-tax and Roth balances in one 401(k) become two accounts, because they are taxed differently.

Scanned statements

A scanned PDF has no text to read. Choose a vision model in Configure (for example qwen3-vl or minicpm-v) and Aegis will read the page image instead. Check those amounts carefully. Our guide to finding a vision model can help.

Budget

Each line is a yearly amount in today's dollars with its own inflation class (general, healthcare, food or fixed), the ages it applies to, and a multiplier for each phase of retirement: the go-go, slow-go and no-go years. Travel might run at 100%, 50% and 10%; healthcare at 100%, 130% and 180%.

Hover a line to see why it has its number: how it was worked out, the words from the interview, and the cost-table entry behind it. Lines you edit are marked user and survive a re-interview.

Use Add one-off goal for a dated expense such as a new roof or a wedding.

Comparing with actual spending

If you track spending with AegisMoneyScope, load the aegis-spending-summary.json it exports to see last year's actual spending next to each category. Only totals are read, never transactions. Large gaps are flagged so you can ask Aegis about them.

Buckets

The classic strategy holds two years of net spending in cash, eight years in an income bucket of bonds, and the rest in a growth bucket. Net spending is spending minus pensions, Social Security and work income.

• Bridge covers the years between retiring and claiming Social Security (useful before 65).
• Legacy / LTC reserve is left alone unless everything else runs out.

Refill rules

The same rules run inside every simulated lifetime. Accounts decide taxes: withdrawals come from RMDs first, then cash, taxable, tax-deferred and Roth, in that order.

Simulate

Each run simulates 10,000 lifetimes (adjustable from 1,000 to 100,000). Every simulated year draws returns and inflation, adds income, computes spending, applies the withdrawal rule, RMDs and Roth conversions, works out federal tax bracket by bracket, withdraws from the buckets and refills them.

Return models

• Lognormal / normal: you set the mean, volatility and correlation per asset class.
• Historical bootstrap: blocks of consecutive US years since 1928, keeping real crashes and inflation spells.
• Deterministic: fixed returns, as a sanity check.

Reading the results

• Success rate: how often the money lasted to the planning age (or for life, with the mortality model).
• Fan chart: the 10th to 90th percentile of your portfolio by age, in today's dollars.
• Sustainable spending: the highest spending that keeps success at your target.
• Sweeps: success by retirement age, savings or spending; a heatmap of age × spending; and a tornado chart of what matters most.

Every scenario uses the same random paths for the same seed, so differences come from the plan, not noise. Each result is stored with a hash of its inputs: change anything and it is marked out of date and re-run.

Taxes

The simulation models federal ordinary income brackets and the standard deduction (with the age-65 and 2025–2028 senior deductions), 0/15/20% capital gains, taxable Social Security, RMDs, Roth conversions, Medicare IRMAA, and a flat state rate.

Scenarios & Export

A scenario bundles a profile, budget, buckets and assumptions. Every edit autosaves.

• Duplicate and change creates a child scenario that remembers its parent, so Compare can show what changed.
• Snapshot saves a named revision ("Before Portugal").
• History lists revisions; restore any of them.
• Export plan writes a single .aegisplan file, optionally password-protected.
• Export PDF report writes a summary.

Nothing is uploaded anywhere.

Your Data & Privacy

• No telemetry, no accounts, no cloud sync.
• Plans are stored in ~/.aegisretirementplanner/profiles/, one SQLite file per profile, and are kept when the package is removed or updated.
• The model is reached only on your computer; a remote Ollama host is refused unless you allow it in Settings.
• Every prompt and reply is logged to logs/llm.jsonl in the data folder for debugging. Set AEGIS_LLM_LOG=0 to turn it off.
• Settings has Delete chat history and Wipe all data.

Reference Data

All bundled figures were entered by hand and carry their source and as-of date. Check them before relying on them.

Beta & Licensing

Aegis Retirement Planner is in Beta and free to use. There is no license charge during the Beta: every feature is available without paying anything.

The app is complete enough to plan with, and we are still improving it. Updating the app keeps your plans. You may find rough edges — please tell us about them.

In the future we may limit some features unless a one-time license is purchased. One-time means you pay once; it is not a subscription.

Troubleshooting

Aegis doesn't answer

Check that Ollama is running (ollama serve) and the model is pulled (ollama pull qwen2.5:7b). Settings → Check Ollama shows what's missing.

The interview is slow

Pick a smaller model (qwen2.5:3b) in Settings, or use the forms. On a machine with a GPU, a larger model such as qwen2.5:14b follows the interview more reliably.

The interview recorded something wrong

Correct it in chat ("no, we rent") or on the Profile page; both write the same record.

A statement amount looks wrong

Rows marked ⚠ Check could not be found in the statement's text; fix the amount or untick the row before applying. Scanned PDFs need a vision model — see Importing Statements.

Reporting a problem

Email support@yourprivacysw.com. Please don't include account numbers or other personal details we don't need.

Contact Support