The auditable multi-agent CFO. Every board-ready claim traces to the agent that produced it, the reasoning step, the grounding source, and the adversarial review that tested it.
A single CFO task — "build the FY plan", "fund the enterprise tier", "approve the board ask" — fragments across three failure modes:
- Context fragmentation across departments
- Reasoning opacity in the final output — nobody can trace why a number landed where it did
- Soft consensus that looks unanimous because assumptions were never adversarially reviewed
MeshCFO solves all three. The result is a board-ready document with complete provenance — suitable for audit committees, board presentations, and regulatory compliance.
Three specialist agents collaborate on a shared context engine through visible expansion/compression reasoning cycles. Every session is wrapped in the Consensus Hardening Protocol (CHP) — foundation disclosure, adversarial assumption attacks, R0 gate checks, and explicit lock progression.
brief → DecisionCase + CHP foundation disclosure + attack
→ seed shared ContextEngine
→ EnterpriseOrchestrator (Finance → Strategy → Compliance)
→ synthesize CFO artifact + AuditTrail
→ third-party validation → LOCKED
| Agent | Produces | Consumes |
|---|---|---|
| Finance | Budget envelope, ROI model | Raw brief |
| Strategy | Market positioning, go-to-market | Budget envelope |
| Compliance | Risk register, mitigations | Both |
- Per-claim provenance: Every line in the final artifact traces back to the agent, expansion step, grounding source, and CHP finding
- CHP governance: Foundation disclosure → adversarial attack → R0 gate → lock progression (EXPLORING → PROVISIONAL_LOCK → LOCKED)
- SpacetimeDB: Real-time shared context, live audit trail subscriptions, zero DevOps
- Self-improving playbooks: Each agent owns a playbook with delta-only updates (ADD, INCREMENT, MERGE, PRUNE)
| Task | Output | Use Case |
|---|---|---|
| Forecast | Driver-based operating plan with stress views | FY planning, budget cycles |
| Investment Case | Capital allocation memo with milestone-gated release | Fund requests, board approvals |
| Board Output | Decision packet with ranked options and dissent surface | Board meetings, committee reviews |
git clone https://github.com/Cubiczan/meshcfo.git
cd meshcfo
pip install -e .
# Run an investment case
cfo-os cfo-os --task investment_case \
--title "Fund enterprise tier Q3" \
--company "Acme" \
--problem "Should we fund a dedicated enterprise tier this quarter?" \
--amount 4000000 \
--payback-months 14 \
--current-runway 18 \
--upside "Higher ACV" --upside "Lower strategic-account churn" \
--risk "Adoption lag" --risk "Implementation complexity"
# Run a forecast
cfo-os cfo-os --task forecast \
--title "FY26 driver-based plan" \
--company "Acme" \
--problem "Build the FY26 driver-based operating plan with stress views." \
--base-revenue 42000000 --base-opex 33000000 \
--growth-pct 0.28 --churn-pct 0.09from cme.cfo_os import CFOOperatingSystem, InvestmentBrief
from demo import FinanceAgent, StrategyAgent, ComplianceAgent
cfo = CFOOperatingSystem(
agents=[FinanceAgent(), StrategyAgent(), ComplianceAgent()]
)
report = cfo.run(InvestmentBrief(
title="Fund enterprise tier Q3",
company="Acme",
problem="Should we fund a dedicated enterprise tier this quarter?",
investment_amount_usd=4_000_000,
expected_payback_months=14,
current_runway_months=18,
expected_upside=["Higher ACV"],
key_risks=["Adoption lag"],
), confirmed_by="finance-lead")
print(report.case.status.value) # PROVISIONAL_LOCK
print(report.hardening) # CHP gate summary (R0, parity, lock state)
print(report.artifact.render()) # board-ready memo
print(report.audit.render()) # per-claim provenance
# Advance to LOCKED via third-party validation
cfo.lock(
report.case.decision_id,
validator="fresh_instance",
item="Investment spec v1",
rationale="Spec coheres; flip criteria explicit.",
)| Before (CockroachDB) | After (SpacetimeDB) |
|---|---|
| SQLAlchemy ORM + connection pooling + query latency between agent turns | Agents connect directly as clients; state propagates instantly |
| Audit trail written to DB, visible only on query | Audit trail is a subscription stream — dashboards see findings appear in real-time |
| Migration scripts, schema management | Single binary, zero DevOps |
| Single-user CLI | Multi-user collaboration for free (identity system built-in) |
┌──────────────────────────────┐
┌── shared ─────> │ ContextEngine │ <───── shared ──────┐
│ │ (entities / events / tasks │ │
│ │ + short / long memory) │ │
│ └──────────────────────────────┘ │
v v
┌────────────────────┐ ┌────────────────────┐ ┌────────────────────────┐
│ Finance Agent │ │ Strategy Agent │ │ Compliance Agent │
│ ├─ Playbook (ACE) │ │ ├─ Playbook (ACE) │ │ ├─ Playbook (ACE) │
│ └─ Protocol (CMP) │ │ └─ Protocol (CMP) │ │ └─ Protocol (CMP) │
└─────────────────────┘ └────────────────────┘ └────────────────────────┘
│ │ │
v v v
budget_envelope market_positioning risk_register
│ │ │
└──────────────┬───────────┴──────────────┬──────────┘
v v
┌──────────────────────────────────────────┐
│ CFOOperatingSystem │
│ 1. CHP DecisionCase + Foundation │
│ 2. EnterpriseOrchestrator (Mesh) │
│ 3. Lock progression (EXPLORING > LOCK) │
│ 4. CFOArtifact + AuditTrail │
└──────────────────────────────────────────┘
| Feature | What It Does |
|---|---|
| Cognitive Mesh Protocol | Visible expand/compress reasoning cycles with verified/inferred/pattern-match tagging |
| Consensus Hardening Protocol | Foundation disclosure → adversarial attack → R0 gate → lock progression |
| Self-Improving Playbooks | Delta-only updates after every turn (ADD, INCREMENT, MERGE, PRUNE) |
| Per-Claim Audit Trail | Every line traces to agent + grounding + CHP finding |
| Context Engine | Entity/event/task graph with cosine dedup and combined scoring (semantic 50%, recency 20%, importance 20%, frequency 10%) |
| Signed Audit Ledger | HMAC-SHA256, append-only, signature-chained JSONL trail of every recommendation and board narrative |
| SpacetimeDB | Real-time subscriptions, live audit streams, zero DevOps |
Every recommendation and board narrative MeshCFO emits is written to a
tamper-evident, append-only JSONL ledger (.meshcfo/audit.jsonl by default),
so the reasoning trail is defensible to an audit committee, external auditor, or
regulator (PCAOB AS 1215 / AICPA AU-C 230 style provenance).
Scheme (extracted from the signed-ledger family — cleanmandate, swarmfi-executor, glacier-edge-arm, compliance-as-code-agent — and strengthened with per-record signature chaining):
- One JSON record per line, append-only, never rewritten.
- Each record is signed as
HMAC-SHA256(key, canonical_json(record) + prev_sig), wherecanonical_jsonis the deterministic (sorted-key) encoding of every field exceptsig, andprev_sigis the signature of the previous line. - Because each line folds in the prior signature, any edit, deletion, or reordering breaks the chain from the first tampered record onward.
Record shape: {ts, event, actor, inputs, sources, confidence?, rationale?, prev_sig, sig}
Key: read from AUDIT_LEDGER_KEY (a well-known test default is used when
unset so the offline demo/tests run without configuration — set a real secret in
production).
from cme.audit import AuditLedger
ledger = AuditLedger("audit.jsonl") # key from AUDIT_LEDGER_KEY
sig = ledger.append(
event="recommendation", actor="finance",
inputs={"problem": "invest?"}, sources=["actuals"],
confidence="high", rationale="Do X",
)
intact, first_tampered_index = ledger.verify() # (True, None) when cleanThe ledger is wired into EnterpriseOrchestrator and CFOOperatingSystem — no
extra code is required; running a session signs every turn automatically.
On top of the signed audit ledger, every CFO OS session runs through the
Consensus Hardening Protocol (consensus-hardening-protocol package,
wired in src/cme/hardening.py) before its board-ready claim can be issued:
- R0 — before the engine. The brief is checked for solvability, scope,
validity, and worth (
Solvable/Scoped/Valid/Worth_it, failures reportFATAL). A refused brief never reaches the agents: nothing runs, nothing persists. - Deterministic adversary — after the artifact. The rendered board-ready
artifact is scored by a deterministic pass, not an LLM:
guardrails 40 (no overclaims, grounded claims, specificity) +
bounded result 30 (a comparable headline number exists) +
golden parity 30 (the number matches
evals/golden_qa.json, the pinned QA baseline for canonical briefs). - Domain floors. Board-ready financial claims gate at the finance floor:
finance/capital_allocation/board_decisionsessions need ≥ 100 — i.e. full guardrails + bounded result + golden parity. A floor breach is fatal; a named confirmer cannot cure it, and a parity mismatch is fatal even with one. - Human lock. Sessions open
EXPLORINGand transition explicitly toPROVISIONAL_LOCK;LOCKEDrequires a named human confirmer (confirmed_by) applied via third-party validation. WhileMESH_CFO_CHP_REQUIRE_HUMAN_LOCKis on (default), an unconfirmed session is refused outright. - Decision ledger. Each gated session is sealed as a CHP payload
envelope into an append-only JSONL ledger. CHP's envelope validation is
structure-only, so the ledger also stores a SHA-256
body_sha256of the record body and re-validates both on every read — a tampered body reads back withintegrity_valid: false.
Read the ledger back with cfo-os decisions [--decision-id ID] or the MCP
server's decisions tool.
Environment controls (see .env.example):
MESH_CFO_CHP_REQUIRE_HUMAN_LOCK— default1(fail-closed). Set0only to let unconfirmed sessions hold atPROVISIONAL_LOCK.MESH_CFO_CHP_DECISIONS_PATH— decision-ledger location (default.meshcfo/chp_decisions.jsonl).MESH_CFO_CHP_GOLDEN_PATH— golden QA baseline (defaultevals/golden_qa.json). If a canonical brief's headline number disagrees with this file, the session is refused — regenerate the baseline deliberately, never silently.
meshcfo/
├── src/
│ ├── cme/
│ │ ├── cli.py # CLI entry point
│ │ ├── agent.py # MeshAgent base class
│ │ ├── protocol.py # Cognitive Mesh Protocol
│ │ ├── context.py # ContextEngine
│ │ ├── playbook.py # Playbook + Reflector + Curator
│ │ ├── audit/ # Signed, append-only HMAC-SHA256 audit ledger
│ │ ├── chp/ # Consensus Hardening Protocol
│ │ ├── cfo_os/ # CFOOperatingSystem capstone
│ │ └── db/ # SpacetimeDB persistence
│ └── demo/ # Finance, Strategy, Compliance agents
├── spacetime/ # SpacetimeDB Rust module + Python client
├── tests/ # pytest suite
└── examples/ # CLI invocations
pip install pytest
PYTHONPATH=src pytest tests/ -vMeshCFO is part of a growing ecosystem of multi-agent systems. These complementary projects are worth exploring:
- TauricResearch/TradingAgents (86K stars) – Multi-agent financial trading framework.
- openai/openai-agents-python (27K stars) – OpenAI's official agent framework.
- crewAIInc/crewAI (53K stars) – Role-based AI agent orchestration.
- AgentOps-AI/agentops (5.6K stars) – Agent observability and analytics.
- raga-ai-hub/RagaAI-Catalyst (16K stars) – Agent tracing and evaluation platform.
| Finance | Strata · Metabocommand · meshcfo · working-capital-optimizer · cash-flow-optimizer · finance-cockpit | | Governance | consensus-hardening-protocol · agent-conductor · compliance-as-code-agent · cleanmandate |
MeshCFO wraps every CFO session in CHP — pair with Strata for maturity roadmaps and Metabocommand for operational approval queues.
MIT. See LICENSE.
Decisions from the portfolio propagation matrix (SecOps/Gov wave C), recorded per the adopt-or-reverse contract. Revisit triggers are binding.
meshcfo already locks provenance in the audit ledger and hardening modules (src/cme/audit/ledger.py, src/cme/cfo_os/audit.py, src/cme/hardening.py); a rubric chain would be a strictly weaker duplicate of an enforced mechanism.
Revisit trigger: a genuinely subjective quality dimension appears in this repo's output that no deterministic gate can decide (e.g. prose quality in user-facing deliverables). Then author the rubric against the canonical chain shape rather than a local one.