β οΈ DISCLAIMER β MATHIR has NOT undergone formal security testing. Use at your own risk in production. License: MIT.
The first cognitive memory layer for LLMs that actually thinks β promotes, forgets, consolidates, and links.
π v8.9.1 β GUARDRAIL TIER β 6th tier, push-based always-active rules. Critical corrections auto-injected into every context response. God Mode Β· Client Bridge Β· CHANGELOG
git clone https://github.com/sil3d/MATHIR.git
cd MATHIR/mathir_mcp
pip install -e .
mathir-server &
# Add mathir to your MCP config β 27 tools available (including 2 for god-mode orchestration).Full install: mathir_mcp/README.md Β· Cross-platform installer: python mathir_mcp/INSTALL_FOR_DEV/install_smart.py (see π οΈ Install Scripts below)
Multi-agent orchestration via shared memory. One orchestrator. N workers. Zero configuration.
Terminal 1: mathir_god_agent() β "I am MiMo. I'm fast at code generation..."
Terminal 2: mathir_god_agent() β "I am Codex. I excel at bulk testing..."
Terminal 3: mathir_god_agent() β "I am OpenCode. I'm good at docs..."
Terminal 4: mathir_god_orchestre(directive="Refactor auth + tests + docs")
β Sees all profiles. Assigns tasks by strength. Monitors. Verifies.
What it solves: You have 4 AI agents open. You copy-paste context between them. You decide who does what. You check each result manually. You are the bottleneck.
mindmap
root((π± GOD MODE))
π§ Orchestrator
Decomposes directive
Reads worker profiles
Assigns by strength
Monitors & verifies
Dispatches dependents
π· Workers
Self-identify
Name & capabilities
Strengths & weaknesses
Tool access
Poll for tasks
Execute & report
Loop until shutdown
π‘ Shared Memory
MATHIR Daemon :7338:
Label Protocol
god:reg β registration
god:task β dispatch
god:result β completion
god:shutdown β stop
No broker needed
Cross-process
βοΈ Core Engine
TaskGraph β DAG
Dependency resolution
Cycle detection DFS
WorkerRegistry
Capability matching
Status tracking
GodProtocol
Label encode/decode
Task ID generation
WorktreeManager
Git isolation
Branch per task
π‘οΈ Safety
LIKE injection prevention
Cycle detection
No premature completion
Honest self-assessment
How it works:
- Workers call
mathir_god_agent()with no arguments β they self-identify (name, strengths, weaknesses) - Orchestrator calls
mathir_god_orchestre(directive="...")β sees all worker profiles β decomposes β assigns by strength β dispatches - Workers poll, execute, report. Orchestrator verifies and dispatches next tasks.
- All communication goes through MATHIR shared memory. No new infrastructure.
Built-in intelligence:
- Agents self-identify honestly β the orchestrator doesn't guess who's installed
- Tasks matched to worker strengths β deep reasoning β Claude, bulk work β fast model
- Dependency-aware β tasks dispatched only when prerequisites complete
- Cycle detection β circular dependencies caught at creation time
Full guide: docs/GOD_MODE.md
26 MCP tools. 22 algorithms. INT8 quantization. Cross-encoder reranking. Multi-agent benchmark.
INT8 quantization β embedding storage reduced 4x (float32 β int8), zero recall loss. 410 DBs migrated: 1.9 GB β 825 MB.
Cross-encoder reranking β ms-marco-MiniLM-L-6-v2 second-pass scoring: +20pp hit@10 on natural-language queries.
Multi-agent benchmark β free-tier models (mimo, nemotron, north) score 0% without memory β 53% average with MATHIR.
e5-small validated β e5-small + rerank (52.9%) beats e5-large alone (51.0%) at 47x less cost.
Full diff: mathir_mcp/CHANGELOG.md Β· Full report: benchmarks/06_results/current/README.md
MATHIR has 2 long-running processes + 1 cross-tool instruction file:
βββββββββββββββββββββββββββββββββββββββββββββββ
β DAEMON (port 7338) β mathir-server β
β Flask + Waitress Β· sqlite-vec Β· embedder β
β Holds the model in RAM/VRAM, exposes HTTP β
βββββββββββββββββββββββββββββββββββββββββββββββ
β² HTTP
β
ββββββββββββββββββΌβββββββββββββββββ
β β β
βββββββββββββββββββ ββββββββββββββββββββ ββββββββββββββββββββ
β MCP BRIDGE β β MCP BRIDGE β β MCP BRIDGE β
β opencode β β mimocode β β any OpenAI-comp. β
β (stdio β HTTP) β β (stdio β HTTP) β β Claude / Cline / β
βββββββββββββββββββ ββββββββββββββββββββ β Cursor / etc. β
ββββββββββββββββββββ
β²
β baseUrl
ββββββββββββββββββββ
β PROXY (port 7339) β
β mathir-proxy β
β Universal OpenAI- β
β compatible injec- β
β tion (works for β
β ANY agent that β
β redirects baseUrl)β
ββββββββββββββββββββ
3 coverage tiers (honest disclosure):
| Tier | Mechanism | Agents | Coverage |
|---|---|---|---|
| A β Plugin auto-inject | mathir-auto-inject.ts hooks session.started + experimental.chat.system.transform β no agent cooperation needed |
opencode, mimocode | TRUE auto-inject |
| B β Instructions + MCP | MCP server registered + GLOBAL_INSTRUCTIONS.md injected. Agent must follow the advisory instruction to call memory_session_start |
claude-code, cursor, cline, zcode, codex, etc. (14 agents) | SOFT β agent must comply |
| C β MCP only | MCP server registered, no behavioral prompt | windsurf, gemini-cli, kilo, qwen, kiro-ide, warp, trae, crush, etc. (34 agents) | NONE β set OPENAI_BASE_URL=http://127.0.0.1:7339/v1 |
Universal escape hatches (escape from tier C β true auto-inject):
-
mathir-proxyon port 7339 β OpenAI-compatible LLM proxy. Intercepts every/v1/chat/completions, queries daemon/api/context, prepends<mathir-auto-injection>block to system prompt. Works for ANY agent that redirects its baseUrl.export OPENAI_BASE_URL=http://127.0.0.1:7339/v1 -
AGENTS.mdat repo root β read automatically by 26+ agents (Aider, Amp, Claude Code, Codex, Cursor, Devin, Factory, Goose, JetBrains Junie, Jules, OpenCode, VS Code Copilot, Warp, Zed, etc. β see agents.md). Instructs the agent to callmemory_session_starton first turn +memory_contextbefore each task.cp mathir_mcp/opencode_templates/AGENTS.md /path/to/your/project/AGENTS.md
Per-project DB routing β each project gets its own .mathir/mathir.db:
- Mycerise_V2_Taur β
Mycerise_V2_Taur/.mathir/mathir.db - mathir_mcp (installer) β
~/.config/MATHIR/mathir_mcp/.mathir/mathir.db - Future projects β
<project>/.mathir/mathir.db(auto-created on first save)
Routing is fixed in v8.5.1: mathir_mcp_server.py injects project + cwd into every request; mathir_server.py uses them to pick the right DB.
This is the story behind MATHIR. It's also my end-of-study project.
Can modern cars navigate an unknown environment?
Not a highway with lane markings. Not a pre-mapped city. A place they've never seen, where the rules change every meter.
A car following pre-programmed rules in a perfect simulation isn't intelligent β it's scripted. True autonomy requires the ability to learn, remember, and adapt across situations it's never seen before.
That's where MATHIR started. An AI can't be intelligent if it can't remember β every session starts from zero, that's amnesia, not intelligence.
Next step: MATHIR has been validated in software (26 MCP tools, 6-tier architecture, plug-and-play MCP). The next step is to build a 3D-printed RC car and test MATHIR as its actual memory layer in a real autonomous-driving scenario.
| Problem | MATHIR solution | |
|---|---|---|
| 1 | Medical AI β "We've never seen this disease before" | Rare case stored as episodic memory β next patient gets instant recall. The model learns from experience. |
| 2 | Chat sessions β "Sorry, who are you?" | Context persists across sessions, tools, time. Switch Claude β Gemini β Llama β memory stays. |
| 3 | Autonomous driving β "The sensor just died" | Car doesn't just see β it remembers. "Last time I was here, speed bump at this GPS." Memory fills sensor gaps. |
| 4 | Fine-tuning β "My data is a mess" | MATHIR auto-classifies, dedupes, links. Data ready for fine-tuning as you add it. |
| 5 | Knowledge drift β "Is this still accurate?" | Memories decay when unused. Old memory fades when API changes. Self-maintaining. |
A plug-and-play 6-tier cognitive memory layer for any LLM:
| Tier | Role | Example |
|---|---|---|
| π©· Working | Scratchpad (current session) | "Right now" |
| π©΅ Episodic | Events | "Last time you asked, the API was at /v2" |
| π© Semantic | Stable facts | "Water boils at 100Β°C" |
| π¨ Procedural | How-to / recipes | "How to deploy: pytest β docker build β aws ecs" |
| π₯ Immunological | Anomaly detection | "Prompt injection detected" |
| π‘οΈ Guardrail | Always-active rules (immune to decay) | "NEVER call _get_project_db() from agent code" |
Memories decay when unused (Ebbinghaus), promote when recalled, consolidate with duplicates, link to related concepts. Guardrails are push-based: auto-injected into every memory_context response, immune to decay, min priority 8, max 50 per project. Same memory works across Claude / GPT / Gemini / Ollama / any LLM.
Why? See the doctoral research paper (6 theorems) and the vs Alternatives doc.
Monday morning. You open Claude. You tell it: "My name is Thomas, I'm building a RAG with Python, FastAPI + Postgres." Claude says: "Got it, I'll remember that."
3 months later. You switch to Cursor + Llama 3.1. Llama: "Hi! Who are you?" Everything Claude "remembered"? Gone. Vendor-locked.
6 months of memory. Wiped in 3 seconds. Because your memory doesn't belong to you.
And the autonomous vehicle:
2:32 PM. The Tesla learns that a yellow pedestrian marker at a crosswalk = slow down. Pattern stored. 2:33 PM. OTA restart. Memory is wiped. Next time, it won't slow down. 2:35 PM. 80 km/h. Zero detection. Zero alerts. Zero memory.
A car that doesn't remember = a car that doesn't understand.
What MATHIR changes:
β
Memory that follows you everywhere β SQLite local, MIT, zero vendor lock-in.
β
Memory that improves β +37.8% online learning, not static facts.
β
Anomaly detected in <1ms β immunological tier, AUC = 1.0.
β
Runs on edge β 240 MB VRAM, Jetson Orin β
, Raspberry Pi
Add MATHIR to your AI agent (OpenCode, Claude Code, Cursor, MiMo, etc.):
That's it. 26 tools (memory_save, memory_recall, mathir_god_orchestre, mathir_god_agent, etc.) β all your agents.
Full MCP config: mathir_mcp/INSTALL_FOR_AGENT/AGENT.md (50+ agents).
| Command | What it does |
|---|---|
mathir-mcp |
MCP stdio server (26 tools, 2 prompts) |
mathir-server |
HTTP unified server (port 7338) |
mathir-client |
CLI client: mathir-client recall "my query" |
mathir-dashboard |
Stats dashboard (port 7420) |
mathir-migrate |
One-shot legacyβnew schema migration |
mathir-brain |
Orchestrator (server + watchdog + proxy) |
Install: pip install -e ./mathir_mcp
| Doc | Purpose |
|---|---|
| mathir_mcp/README.md | Install, MCP setup, all 26 tools |
| mathir_mcp/INSTALL_FOR_AGENT/AGENT.md | Per-agent MCP config (50+ agents) |
| mathir_mcp/docs/DAEMON.md | Daemon HTTP API + JSON-RPC protocol |
| mathir_mcp/docs/DIMENSIONS.md | Embedding model selection |
| mathir_mcp/docs/DASHBOARD_GUIDE.md | Stats dashboard setup |
| docs/GOD_MODE.md | God Mode β multi-agent orchestration guide |
| mathir_mcp/docs/GPU_SETUP.md | GPU/ONNX acceleration |
| docs/01_MASTER_RESEARCH_PAPER.md | Doctoral research paper (6 theorems) |
| docs/03_MASTER_QA_GUIDE.md | 63 Q&A for defense / evaluation |
| docs/07_MATHIR_VS_VECTORDB_USE_CASES.md | MATHIR vs FAISS / vector DBs |
| CHANGELOG.md | Full version history |
| mathir_mcp/GLOBAL_INSTRUCTIONS.md | Universal AI agent instructions |
Cross-platform: python mathir_mcp/INSTALL_FOR_DEV/install_smart.py --autostart-only (Windows / macOS / Linux).
Manual: see INSTALL_FOR_AGENT/INSTALL_WINDOWS.md Β· INSTALL_FOR_AGENT/INSTALL_LINUX.md Β· INSTALL_FOR_AGENT/INSTALL_MACOS.md.
| Product | OSS? | LLM-agnostic? | Edge? | Anomaly detection | Cost |
|---|---|---|---|---|---|
| π§ MATHIR | β MIT | β Any | β ~500MB GPU | β MCP server: live Mahalanobis detector, AUC-ROC=0.8533 | Free |
| Mem0 | β | β | β | Free β $249/mo | |
| Letta | β Apache 2.0 | β | β | Free | |
| Zep | β | β | β | $1,250/yr | |
| Cognee | β Apache 2.0 | β | β | $35/mo | |
| LangMem | β MIT | β | β | Free | |
| GraphRAG | β MIT | β | β | Free | |
| ChatGPT Memory | β | β OpenAI | β | β | $20/mo+ |
| Claude Projects | β | β Anthropic | β | β | $20/mo+ |
Anomaly detection status: the MCP server/daemon (
mathir_lib/, what coding agents connect to) now wires itsimmunologicaltier to a real, live Mahalanobis-distance detector:/api/memory/savescores every incoming embedding against a running per-project baseline and can writetier='immunological'when it flags an outlier. On a realistic prompt-injection corpus (mathir_mcp/tests/data/anomaly_eval/), the honest result is AUC-ROC=0.8533 for normal-vs-injection separation β good, not perfect. There is no clean separation between "malicious" and "merely unusual" using distance alone: benign-but-unusual text can also score above the threshold and get flagged. Because of this, flagged content is not auto-blocked or silently deleted β it lands in theimmunologicaltier for review viamemory_audit_immunological. A separate, simpler (non-Mahalanobis) detector also exists inmathir_dropin/(the standalone embeddable library for non-MCP apps, see docs/05_SHIPPING_GUIDE.md) β it is a different implementation and its numbers are not the ones quoted above.Retrieval quality vs FAISS: real BEIR benchmarks (SciFact/ArguAna/NFCorpus, see benchmarks/06_results/current/) currently show plain FAISS dense retrieval outperforming MATHIR's hybrid BM25+dense+cross-encoder pipeline. Any "+14pp vs FAISS" figure you may see elsewhere comes from a 50-query/200-chunk internal evaluation on a single textbook and is not comparable to a standard IR benchmark β see docs/SOTA_RESEARCH_2024_2026.md for the full self-audit.
LoCoMo results (2026-07-03): MATHIR now has LoCoMo numbers β 51.2% on Groq (Llama 3.3 70B, 41/233 judged due to TPM limits), 38.8% on OpenCode Zen free models (67/152 judged). Temporal retrieval is strong (65-73%), multi-hop is weak (8-17%). Full results: benchmarks/06_results/current/README.md.
Full comparison: docs/07_MATHIR_VS_VECTORDB_USE_CASES.md
98/98 tests pass (mathir_mcp/tests/). Run yourself:
pytest mathir_mcp/tests/ -v| Benchmark | Result |
|---|---|
| Multi-agent + MATHIR | 0% β 53% avg (free models + shared memory) |
| INT8 quantization | 410 DBs, 1.9 GB β 825 MB, 0% recall loss |
| Cross-encoder rerank | +20pp hit@10 on NL queries (50% β 70%) |
| LoCoMo (Groq 70B) | 51.2% overall, 73% temporal |
| e5-small + rerank | 52.9% > e5-large 51.0% at 47x less cost |
| Micro (500 memories) | 360 mem/s store, 425 ops/s recall, p50=2.29ms |
| decay_all | 599/599 decayed (100% coverage) |
| consolidate | 99 duplicates merged |
Full report: benchmarks/06_results/current/README.md
ββββββββββββββββββββββββββββββββββββ
β Any LLM (Claude, GPT, Gemini) β
ββββββββββββββββ¬ββββββββββββββββββββ
β embeddings 384d
βΌ
ββββββββββββββββββββββββββββββββββββ
β MATHIR Daemon (port 7338) β
β Flask+Waitress Β· FastMCP 3.4.2 β
β HybridSearch + CrossEncoder rerankβ
β 6 tiers Β· INT8 Β· Ebbinghaus β
β β
β GOD MODE (v8.8.0) + GUARDRAIL β
β /api/god/poll Β· /api/god/agents β
β Cross-process multi-agent β
β orchestration via shared memory β
ββββββββββββββββ¬ββββββββββββββββββββ
β
βΌ
SQLite + sqlite-vec
(per-project DB)
Full architecture: docs/BRAIN_ARCHITECTURE.md
MATHIR/
βββ mathir_mcp/ β Install this (v8.9.0, 26 MCP tools, God Mode + Guardrails)
βββ benchmarks/ β Reproducible benchmarks
βββ docs/ β Doctoral paper, QA, architecture
βββ examples/ β Usage examples
βββ stress_test/ β Stress test web UI
βββ vision_testing/ β Vision/audio testing
βββ raspberry_jetson/ β Edge deployment
βββ _deprecated/ β v1-v7 history (do not use)
βββ README.md (you are here)
β V1βV5 Core architecture + KL router β V6 LLM-agnostic plugin API β V7 8 algorithms + 6 theorems + 9.3Γ compression β V7.5 BEIR benchmarks (0.7441 SOTA on SciFact) β V7.6 Universal Bridge (UNIBRI) β V7.7 Vision & audio testing β V7.7.1 SimpleMemory (FTS5) + UI overhaul β V7.8 GPU embeddings + daemon architecture β V8.0 Cascade architecture β V8.5.0 FastMCP rewrite + auto-injection (20 tools) β V8.5.1 New tools (23 total) + project-aware DB β V8.6.0 INT8 quantization + cross-encoder rerank + multi-agent benchmark β V8.7.0 3-layer auto-cache (L1 embedding, L2 recall, L3 session) β V8.8.0 God Mode β cross-process multi-agent orchestration β V8.9.0 Guardrail tier β push-based always-active rules (6th tier)
graph LR
V91["V9.1<br/>VISION<br/>Model testing<br/>(laptop, T+0)"] --> V92["V9.2<br/>RASPBERRY PI<br/>CPU edge deploy<br/>(Pi 5, T+2 weeks)"]
V92 --> V93["V9.3<br/>JETSON<br/>GPU edge deploy<br/>(Orin, T+1 month)"]
V93 --> V94["V9.4<br/>RC CAR<br/>Physical world<br/>(3D-printed, T+2m)"]
V91 --- |"OpenRouter<br/>26 free models<br/>Vision + audio"| A1
V92 --- |"MiniLM-L12<br/>CPU + ONNX INT8<br/><500 MB RAM"| A2
V93 --- |"bge-large-en-v1.5<br/>CUDA fp16 500MB<br/><30 ms recall"| A3
V94 --- |"Real sensors<br/>camera + LIDAR<br/>no internet"| A4
classDef done fill:#22c55e,color:#fff
classDef next fill:#3b82f6,color:#fff
classDef pending fill:#6b7280,color:#fff
class V91 next
class V92 pending
class V93 pending
class V94 pending
| Stage | Hardware | Embedding | Goal |
|---|---|---|---|
| V9.1 Vision (now) | Laptop | OpenRouter free LLM | Verify across LLMs |
| V9.2 Raspberry Pi | Pi 5 (8GB) | MiniLM CPU + ONNX INT8 | CPU edge robustness |
| V9.3 Jetson | Orin Nano (8GB) | bge-large CUDA fp16 | GPU edge acceleration |
| V9.4 RC Car | 3D-printed + Pi/Orin | Same as Jetson | Real-world autonomous |
π V10 Open-source release (HuggingFace Β· PyPI)
- V9.1 Vision (now): Cheap, fast, validates the memory layer across many LLMs. No hardware risk.
- V9.2 Raspberry Pi: Real edge constraints (CPU only, 4GB RAM). If it works here, it works anywhere.
- V9.3 Jetson: GPU acceleration, but still bounded power. The "production edge" sweet spot.
- V9.4 RC Car: No internet, no reboot, no excuses. Real sensors, real noise, real failures. This is the validation that can't be faked.
We welcome PRs and security reports. Open an issue or pull request.
@software{mathir2026,
title = {MATHIR: Memory-Augmented Tensor Hybrid with Intelligent Routing},
author = {Mbama Kombila, Prince Gildas},
year = {2026},
url = {https://github.com/sil3d/MATHIR}
}Full paper: docs/MATHIR_Research_Paper.tex
MIT β free for commercial and research use.




{ "mcpServers": { "mathir": { "command": "mathir-mcp" } } }