matha

MATHA

The persistent cognitive layer for AI-assisted development.

---

You gave the AI your entire codebase. You explained the business logic for two hours. You did a Q&A, walked through every edge case, corrected every misunderstanding.

Then you closed the session.

The next day you opened a new one. And it remembered nothing.

Not the HWM calculation that took three sessions to get right. Not the rule about deposit events not triggering profit cycles. Not the assumption that broke everything in V1 and cost you twelve days to fix. Gone. Cold start. Again.

This is not an AI intelligence problem. Every tool — Cursor, Copilot, Claude Code, Windsurf — is stateless by design. They are powerful and amnesiac in equal measure. The larger your project, the more painful that amnesia becomes.

MATHA fixes this.

---

What MATHA Does

MATHA is a local MCP server that runs alongside your project and gives any AI agent the context that currently only exists inside a senior engineer's head.

It captures three things that no markdown file can hold:

Intent — why the project exists, what the non-negotiable rules are, what it explicitly does not do. Not features. The reasoning behind them.

Decisions — every assumption that broke, every correction that was made, every "no that's wrong" moment that cost you days. Recorded by the agent itself over MCP as a by-product of the work (with a CLI fallback), not by humans writing docs after the fact.

Behaviour contracts — assertions that must remain true for a component. Stored with the component, surfaced whenever an agent is about to touch it, with violation history escalating the warning.

Every session writes back what it learned. Every session starts warmer than the last. The brain stays on.

---

How It Works

MCP is the primary surface: the agent calls matha_brief before touching code and matha_record when it learns something. The CLI is for setup, diagnostics, and agents without MCP support:

# Once per project — seeds the brain from your project's intent and git history
matha init

# Print the project brief for a scope (copy-paste fallback for non-MCP agents)
matha before --scope src/payments/ --intent "change retry logic"

# Record what a session learned (fallback for non-MCP agents)
matha after

# Diagnose the setup: which brain, schema status, record counts, staleness
matha doctor

# Upgrade .matha/ after a matha version bump
matha migrate

The write-back means a correction never has to be made twice.

Keeping the brain trustworthy

A memory that silently rots is worse than no memory. matha treats staleness and drift as first-class:

# Triage queue: confirm, retire, or skip unconfirmed and possibly-stale records
matha review

# Commits since the last recorded knowledge that no record covers (backfill list)
matha catchup

# Match a git diff against the brain — advisory in CI, --strict to fail on criticals
matha check --diff origin/main

# Declare an admin boundary: pinned, confirmed, always CRITICAL on a path match
matha boundary add --paths db/schema/ --rule "Schema changes require DBA sign-off"

# Human-readable, PR-diffable brain summary / self-contained HTML report
matha export --md --out BRAIN.md
matha ui

# Seed an existing codebase: agent proposes records from your docs, you confirm
matha onboard

# Wire the Claude Code SessionStart hook that injects the brief automatically
matha hooks --install

Records whose code changed after they were written are flagged possiblyStale and rank-penalized — surfaced, never silently wrong. Agent writes land as probable; only a human (matha after, matha review) can mark knowledge confirmed. The codemap refreshes itself incrementally on read (a persisted commit cursor means even a huge history is analysed once, then only new commits).

---

Installation

npm install -g @10kdevs/matha

Zero-install first run:

npx @10kdevs/matha init

Requires Node.js 20+. No API key. No cloud dependency. All data stays in your repository.

---

Connecting To Your IDE

After matha init, connect MATHA to your IDE via MCP.

The init command writes .matha/mcp-config.json with the exact config for your machine. Add it to your IDE's MCP configuration.

Claude Code:

# .matha/mcp-config.json contains the correct config
# Add to your Claude Code MCP settings

Cursor:

{
  "mcpServers": {
    "matha": {
      "command": "npx",
      "args": ["-y", "@10kdevs/matha", "serve", "--project", "/path/to/your/project"]
    }
  }
}

Once connected, your AI agent can call matha_brief() as its first action in any session — receiving the full project context before writing a line. The server resolves the right .matha/ from --project, the IDE's workspace roots, or the file paths in each tool call — and if none resolves, it says so explicitly rather than serving an empty brain. Run matha doctor any time to see exactly which brain is being served.

---

The Brain

MATHA's knowledge lives in .matha/ in your repository. Committed to version control. Owned by your team. Never sent anywhere.

.matha/
├── hippocampus/        intent, rules, decisions, danger zones
├── cerebellum/         behaviour contracts, violation log
└── cortex/             stability map, co-change graph, boundaries

The codemap (cortex) builds itself from git history. Files that change together are linked. Files with low churn and high connectivity are classified frozen — AI agents are warned before touching them.

Retrieval is hierarchical: a danger zone recorded against src/payments/ fires for src/payments/retry.ts. Records written by an agent carry probable confidence until a human confirms them; garbage inputs (empty components, one-letter "corrections") are rejected at write time.

---

MCP Tools

AI agents connected via MCP have access to a deliberately small surface:

matha_brief(scope?, intent?, filepaths?)   Token-budgeted project context + scored matches
matha_match(scope?, intent, filepaths?)    What does the brain know about this change?
                                             (scope omitted → keyword search over intent alone)
matha_record(type, ...)                    The one write tool:
                                             decision | danger | contract   (new knowledge)
                                             violation | supersede | retire (lifecycle)
matha_refresh()                            Rebuild the codemap from git history

Agents can create knowledge and maintain it — log a contract violation, supersede a decision that proved wrong, retire one that no longer applies. What they cannot do is self-promote: everything an agent writes is at most probable, and declared boundaries are CLI-only.

There is also an MCP prompt, matha_context, which injects the brief plus the standing "record what you learn" instruction — IDEs that support MCP prompts can pull it at session start with zero configuration.

Retrieval is scored (structural path match × lexical relevance × confidence × recency) and the brief stays under a ~1,500-token budget — criticals are ranked first, so they are never the part that gets truncated. Every response includes diagnostics.brainDir — you always know which brain answered.

Two things worth knowing about brief.truncated and recentDecisions: truncated means something didn't fit the budget (an oversized record, or the section budget itself), not that the whole response was cut short — check matchResults.length and tokenEstimate for the real picture. recentDecisions is intentionally global (most-recent-first across the whole brain), not scope-filtered — it's the "what's been learned lately" section; scope-relevant knowledge surfaces separately in matchResults.

The sub-10ms warm p95 figure (from the eval harness) describes in-process retrieval inside a long-lived MCP server session with a warm cache — a matha before CLI invocation pays Node's process-startup cost on top of that (typically 150–250ms) and isn't the number that claim describes.

Tuning for large, high-file-count repos

On a repo with a large fraction of files classified frozen, matha check --strict can flag an unusually large share of an ordinary diff as CRITICAL. Set frozenFileSeverity: "warning" in .matha/config.json to keep the signal without the block:

{ "schema_version": "1.1.0", "frozenFileSeverity": "warning" }

The classifier itself also guards against the most common cause: a file touched within the last 60 days never classifies frozen, regardless of its long-run churn average — a bounded/incremental analysis window can otherwise make a historically active, business-critical file look "settled" just because few of its changes fall inside the analysed window.

---

Benchmarks

npm run eval:report

Runs matha's own golden-set retrieval eval (the CI gate in tests/eval/golden.test.ts) standalone, against a naive substring-match baseline (matha's own pre-scoring behaviour), and writes BENCHMARKS.md. Deterministic — the fixture clock is fixed, so recall/precision are exactly reproducible on any machine.

This is an in-house fixture, not a public academic benchmark — there is no published dataset for "retrieve the right decision for a given file + intent," which is a narrower, more structural task than conversational long-memory QA. The numbers are honest about that scope, not a leaderboard claim.

---

Initialising From An Existing Document

If your project already has a BRD, spec, or requirements document:

Setting Up Your Project Brain

Before running matha init, generate a requirements.md file that captures your project's intent, rules, and boundaries in a format MATHA understands deeply.

Paste this prompt into any AI assistant:

I am setting up MATHA — a persistent cognitive layer for AI-assisted 
development. I need you to generate a requirements.md file for my 
project that MATHA will parse during initialisation.

My project: [describe your project in 2-3 sentences]

Generate a requirements.md with exactly these sections:

## Overview
A concise paragraph explaining what problem this project solves 
and why it exists. Focus on the WHY, not the features.

## Business Rules
A bullet list of non-negotiable rules that must always be true.
These are constraints the codebase must never violate.
Examples: calculation logic, data integrity rules, 
financial constraints, domain-specific invariants.

## Out of Scope
A bullet list of things this project explicitly does NOT do.
These are boundaries that protect the system from scope creep.

## Owner
The name or team responsible for this project.

Be specific and precise. Vague rules are useless. 
Each rule should be concrete enough that a developer 
who has never seen the codebase understands exactly 
what it means.

Then run:

matha init --from requirements.md

MATHA will parse the document, show you what it found, and let you confirm or override before writing anything.

MATHA parses business rules, boundaries, and intent from the document and pre-fills the init prompts. You review and confirm. Nothing is written without your sign-off.

---

What MATHA Is Not

MATHA does not generate code.

MATHA does not replace your IDE, your AI model, or your version control.

MATHA does not require a specific model, a specific IDE, or a specific language. If your tool supports MCP, it connects to MATHA on day one.

MATHA does not send your data anywhere. The brain lives in your repository.

---

The Real Problem It Solves

There is a moment every developer who uses AI tools eventually hits.

The project is large enough that you cannot hold all of it in your head. The AI cannot hold all of it in its context window. You find yourself explaining the same decision three times across three sessions. You find a bug and you are not confident which part of the codebase is responsible. You realise you have forgotten the core logic you wrote four weeks ago.

At that moment, the AI is not the problem. The absence of accumulated understanding is the problem.

MATHA is the accumulated understanding.

It is what the senior engineer carries in their head after three years on a project — the why behind every decision, the scars from every production incident, the rules that cannot be broken and the code that cannot be touched without knowing why it works the way it does.

That knowledge survives sessions. It survives team changes. It survives the moment you come back to a project six months after you last touched it.

The code gets better. The context never resets. The brain stays on.

---

Auto-Wiring MATHA (Set Once, Works Forever)

After connecting MATHA as an MCP server, add this rule to your IDE's AI settings. It eliminates the manual before/after step entirely.

Cursor → Settings → Rules for AI
Windsurf → Settings → AI Rules
Claude Code → CLAUDE.md in project root

Paste this rule:

At the start of every conversation, call matha_brief() before writing any code. Review all rules, danger zones, and prior decisions. Flag any hasCritical:true results before proceeding. After completing work, call matha_record() for any assumption that changed during the session.

One rule. Every session starts warm.

---

Case Study

How MATHA would have saved 12 days on a real PAMM trading platform →

---

Contributing

CONTRIBUTING.md

---

License

MIT — owned by nobody, usable by everyone.

---

Built because the problem was real.