Design Philosophy

Minara Agent is purpose-built for finance. This page explains the decisions that follow from that: why each rule exists and what breaks if it's relaxed.

1. Finance is not a playground: every unsafe call is gated

A fund-moving agent's worst case is somebody's rent. Every gate lives in code, not in policy.

• 4 permission tiers. Every tool carries a level from 1 (read-only) to 4 (manual-only), checked at every call against the turn source and the session risk ceiling. See Sandbox & Permissions.
• Stage-locked risk ceilings. Each conversation stage — discover, evaluate, decide, manage — sets a risk ceiling for the turn. A price query cannot escalate to a trade.
• 2-step confirmation for fund moves. Turn 1 returns a structured preview; turn 2 executes only when you say yes. The only automation bypass is scoped to backtests and CI, never active in production.
• Physically sandboxed filesystem. File tools are incapable of escaping the sandbox directory. Path traversal is blocked at the OS layer, not in application code.
• 2-layer subprocess guard. Shell tools pass through a policy filter, then a kernel-level sandbox. Internal calls use validated argument lists only, never string interpolation.

2. The agent compounds: scenarios, roles, and self-learning

An AI wealth butler accumulates understanding across turns, sessions, and months. 3 mechanisms make this structural.

• Intent classification before tool selection. A pre-AI classifier routes each turn into 1 of 41 playbooks — 25 standalone intents and 16 composable sub-contexts. Each playbook injects a numbered investigation plan and output checklist, so "should I buy SOL?" runs a different path than "how's the macro this week?". Keyword matching first, AI fallback second. When self-learning is on, proposed playbooks from classification misses go through operator review before going live. See Scenarios.
• Domain-scoped memory. Every skill declares the memory domains it writes to — trader, analyst, investor, and others. Each domain owns its own indexed memory slice. When a playbook fires, it surfaces relevant past lessons from the right domain. A token-analysis turn reads analyst-domain history, not a pile of everything.
• 10 behavioral dimensions. Risk appetite (conservative / balanced / aggressive), markets traded, finance knowledge, decision style, patience, and more. Re-inferred from your chat history every 10 minutes, with a 30-day rebuild cooldown. What you set explicitly always takes precedence over inference.
• Rules that graduate through real use. An analytical-rule database stores market insights per asset class: "long-term holder profit dominance above 1 signals an uptrend"; "RSI above 70 alone is not a short signal." New rules are quarantined until they clear a statistical confidence threshold (95% lower bound ≥ 0.55) across enough real uses. A 30-day half-life prevents stale rules from coasting on past wins. Promoted rules surface into playbooks, tool outputs, and direct lookups, all behind a single operator off switch. The database is shared fleet-wide.

3. Skills are lazy-loaded prompt fragments

Most agents use a single massive system prompt or an ever-growing tool list. The Minara skill registry does neither.

• Pre-filter before the AI runs. The router scores every skill by keyword, stage, asset class, and required tools before the model is called. Skills with missing dependencies drop out of the catalog entirely.
• Explicit activation. Skills are inert until the model requests them. 2 to 4 domain skills per turn beats a 20,000-token monolith on both cost and quality.
• Declarative composition. Skills are bundles: a prompt fragment, a tool allowlist, and routing metadata. Combining 2 skills is a one-line catalog entry.
• External packages load through the same registry. No separate code path. A third-party knowledge pack and a built-in skill are treated equally.

4. SQLite everywhere, Redis never required

Most production agents need a Postgres, a Redis, and a vector database. Minara runs on 1.

• Single container. docker run minara is the full infrastructure. Local dev and production are identical.
• Full-text search scales far enough. SQLite's built-in full-text search handles thousands of stored insights and tens of thousands of audit rows without a vector database.
• The distributed lock library stays dormant. Available for optional horizontal scaling, never a boot-time dependency.

5. Fail closed at boot

• Missing provider credential: skill unregistered, tool set removed from the catalog. The AI never sees a tool it can't call.
• Missing required credential: the process refuses to start with a clear error.
• Conditional activation runs at startup so the catalog is coherent before the first AI turn.

6. Every secret goes through the environment

No credential is passed as an AI-visible argument or hard-coded. Every provider reads its key from the environment at startup. Every new credential ships a detailed template entry — purpose, consumer, default behavior — plus the matching row in the env-vars inventory.

7. TypeScript-native document generation

Word, PDF, and PowerPoint output uses 3 MIT-licensed, pure-JavaScript libraries. Python never enters the document path: Anthropic's official document skills carry a proprietary license that forbids vendoring into an open-source repo, and a second runtime adds supply-chain complexity without adding value.

8. What we actively don't do

• No abstractions for 3 or fewer call sites. 3 similar lines beat a premature helper.
• No error handling for conditions that can't happen. System boundaries get validated; internal code is trusted.
• No narration comments. Comments exist only for non-obvious why, never to describe what the code does.
• No amending published commits or skipping hooks without explicit user authorization. See Conventions §9.