Tax-alpha co-pilot
About this agent
A tax-loss and LTCG-harvesting co-pilot for MFDs and RIAs, built to catch what usually only gets done reactively at financial year-end: unused Section 112A exemption headroom and offsettable capital losses sitting across a client's own SIP tranches. Every tranche — one per SIP installment or lump sum — is tracked independently and ordered FIFO, with its holding period measured against the asset-class-specific threshold (12 months for equity, 24 or 36 for hybrid or specified debt) to classify each gain as short- or long-term. Two deterministic strategies then run over that bucketed list: sell just enough long-term, in-the-money units to use up whatever's left of the client's ₹1.25 lakh annual LTCG exemption without a rupee over it, and separately sell underperforming tranches to realise losses that offset a stated amount of taxable STCG or LTCG. Every sale is paired with a same-category reinvestment recommendation rather than a straight buy-back into the same scheme, to preserve the target allocation without courting wash-sale-style scrutiny. None of this arithmetic is left to the model — Decimal, not float, is used throughout — the LLM's only job is to narrate the already-computed plan and flag anything unusual from recalled memory. A scan only ever writes to session-scoped memory; nothing touches the client's multi-year tranche and loss-carryforward ledger in project memory until an advisor explicitly approves and the harvest is committed.
What changed with Zenmem?
The same agent, built twice against the same contract — once on Zenmem, once on MongoDB + LangChain/LangGraph.
Before → after
Before With Zenmem
What the team gained
- A scan lives entirely in session scope, so simulating a harvest never touches the client's permanent tax ledger — the simulate-then-commit split is a property of the scopes, not a flag to remember.
- Multi-year FIFO tranche history, LTCG-exemption utilisation and unabsorbed losses share one client scope, so a computation spanning financial years reads one place.
- A loss carried up to eight assessment years stays addressable without an archive table or a retention job.
- Nothing is written until an advisor approves and the commit runs, so an abandoned scan leaves no trace.
- FIFO and exemption arithmetic stay deterministic; memory holds the ledger and the narrative, not the maths.
How memory is scoped
Two scopes with a hard rule about which is which. Session memory holds one scan: the harvest simulation and the LLM's narrative of it, and nothing more — a scan never touches a client's permanent record. Project memory, keyed to projectId="CLIENT_TAX_LEDGER", holds the facts that have to survive across financial years and advisor sessions: multi-year FIFO tranche history, each year's LTCG-exemption utilisation, and every unabsorbed loss with the assessment year it expires after (up to eight). Nothing is written there until an advisor explicitly approves a harvest and commit_harvest() runs — matching the simulate-then-execute flow, and meaning next year's scan reads exactly what was actually executed, not what was merely proposed.
How it works
Bucket, harvest, narrate, commit — nothing written until approval.
Bucket tranches FIFO
Every tranche is ordered oldest-first and classified short- or long-term against its asset class's holding-period threshold, using live NAVs.
Harvest the LTCG exemption
Sells just enough long-term, in-the-money units to use up what's left of the annual Section 112A exemption, without going a rupee over it.
Harvest losses to offset gains
Sells underperforming tranches to realise short- or long-term losses that offset a stated amount of already-booked taxable gain.
Narrate the plan
The computed plan, never the arithmetic, is handed to zenmem's callLLM to produce an advisor-facing explanation and flag anything unusual in recalled memory.
Commit only on approval
An approved harvest is written atomically to project memory — the executed trade, updated exemption usage, and any new carryforward-loss entries — then the session ends.
Commands
A CLI over the scan-then-commit workflow, also usable as a library.
Commands
- tax-alpha ping — liveness check against the configured zenmem deployment.
- tax-alpha scan --csv <tranches.csv> --pan ... --client-name ... --used-ltcg ... --stcg-to-offset ... [--ltcg-to-offset ...] — runs a harvesting scan and prints the plan, execution schedule, reinvestment plan and client report.
- Agent4TaxAlphaCoPilot.scan_portfolio() — the Python API for a scan: FIFO bucketing, harvesting, and an LLM narrative, session-scoped only.
- Agent4TaxAlphaCoPilot.commit_harvest() — atomically commits an approved harvest to project memory and closes the session.
- LossCarryforwardLedger.record_loss() / available_as_of() — records and queries unabsorbed losses against the 8-assessment-year carryforward window.
- execution_schedule() / reinvestment_plan() / client_facing_report() — the three output artifacts, rendered as plain Markdown.