Skip to content

sil3d/MATHIR

Repository files navigation

⚠️ DISCLAIMER β€” MATHIR has NOT undergone formal security testing. Use at your own risk in production. License: MIT.


MATHIR Logo

🧠 MATHIR

Memory-Augmented Tensor Hybrid with Intelligent Routing

The first cognitive memory layer for LLMs that actually thinks β€” promotes, forgets, consolidates, and links.


πŸ†• v8.9.4 β€” Self-healing daemon + universal LLM injection proxy. One proxy (port 7339) in front of Anthropic's API or any OpenAI-compatible provider (~30 allowlisted, incl. local models) injects live memory into every request β€” no per-tool config edits. Daemon + proxy now self-heal on all 3 OSes. God Mode Β· Client Bridge Β· CHANGELOG


Python 3.10+ PyTorch 2.0+ MIT v8.9.4 98 tests


🧠 What is MATHIR, in one paragraph?

MATHIR is not another API you call when you feel like it β€” it's an architectural layer that inserts itself between the model and the provider, in the request path itself. The idea mimics how a human actually thinks: before acting, you unconsciously recall relevant past experience β€” including a mistake you made a year ago β€” so you don't repeat it. LLMs don't do that by default: every request is amnesiac, so they repeat the same errors, forget what "don't do X" they were told last week, and relearn the same lessons from scratch. MATHIR's job is to be that recall step β€” automatically, on every single request, whether the agent asks for it or not. Two ways it does this: passively (MCP tools the agent can call to read/write memory) and, as of v8.9.4, structurally (a proxy that sits between any tool and its LLM API β€” Anthropic or OpenAI-compatible β€” and rewrites the request to inject relevant memory, past mistakes, and standing rules before the provider ever sees it). It runs as one local process (Flask daemon + SQLite/sqlite-vec, no external database, no cloud), with memories that decay, promote, consolidate, and link themselves (Ebbinghaus-style, not a flat similarity store) β€” and it can be shared live across multiple agents on the same machine.

MATHIR vs. the managed alternatives (Mem0, Zep, Letta)

MATHIR Mem0 / Zep / Letta (typical)
Where it runs 100% local β€” one Python process Self-host or managed cloud API
Infrastructure Single daemon + SQLite (sqlite-vec) β€” zero external services Orchestrates external services (e.g. Mem0 self-hosted = Qdrant + Postgres + Mem0 itself)
Cost Free, no tier β€” there is no cloud version to pay for Free self-hosted; cloud plans from free (10K memories) β†’ $19–249+/mo β†’ custom Enterprise
Data residency Always on your disk Yours if self-hosted; on their servers if you use the cloud API
Multi-agent sharing Native (God Mode β€” same local daemon, any agent) Not a core feature
License MIT Apache-2.0 (Mem0)
Retrieval benchmarks None published externally yet (internal only, see Positioning) Published LongMemEval / LoCoMo numbers, funded, wider adoption

Read this as: MATHIR trades external validation and managed convenience for zero infrastructure, zero cost, and full local control. If you want a battle-tested hosted memory API today, Mem0/Zep are reasonable choices β€” see full honest comparison.

MATHIR Architecture


⚑ Quick Start

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)


πŸ”± Introducing: MATHIR GOD MODE

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
Loading

How it works:

  1. Workers call mathir_god_agent() with no arguments β†’ they self-identify (name, strengths, weaknesses)
  2. Orchestrator calls mathir_god_orchestre(directive="...") β†’ sees all worker profiles β†’ decomposes β†’ assigns by strength β†’ dispatches
  3. Workers poll, execute, report. Orchestrator verifies and dispatches next tasks.
  4. 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


πŸ†• Recent Highlights (v8.6.0 β†’ v8.9.4)

27 MCP tools. 22 algorithms. INT8 quantization. Cross-encoder reranking. Multi-agent benchmark. Self-healing daemon + universal injection proxy (see banner above for the latest, v8.9.4).

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


πŸ—οΈ Universal Architecture β€” How MATHIR runs everywhere

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.     β”‚
                                          β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                                    β–²
                                                    β”‚ ANTHROPIC_BASE_URL or
                                                    β”‚ OPENAI_BASE_URL
                                          β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                                          β”‚ PROXY (port 7339) β”‚
                                          β”‚ mathir-proxy      β”‚
                                          β”‚ Universal injectionβ”‚
                                          β”‚ β€” Anthropic native β”‚
                                          β”‚ /v1/messages AND   β”‚
                                          β”‚ OpenAI-compatible  β”‚
                                          β”‚ /v1/chat/completionsβ”‚
                                          β”‚ (~30 providers,    β”‚
                                          β”‚ multi-upstream)     β”‚
                                          β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

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 β€” or upgrade to the proxy below for a hard guarantee (v8.9.4+) claude-code, cursor, cline, zcode, codex, etc. (14 agents) SOFT β€” agent must comply, unless proxied
C β€” Universal proxy Point ANTHROPIC_BASE_URL or OPENAI_BASE_URL at the proxy (port 7339) β€” no MCP, no agent cooperation, works identically for every tool pointed at it Any tool with a custom-base-URL setting: windsurf, gemini-cli, kilo, qwen, kiro-ide, warp, trae, crush, claude-code, codex, local models (Ollama/llama.cpp), etc. HARD β€” set ANTHROPIC_BASE_URL=http://127.0.0.1:7339 for Anthropic-native tools (no /v1 β€” matches the Anthropic SDK's own base-URL convention), or OPENAI_BASE_URL=http://127.0.0.1:7339/v1 for OpenAI-compatible tools (/v1 required β€” matches the OpenAI SDK's default)

Additional escape hatch β€” AGENTS.md at your project 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. β€” real open standard, agents.md, 60,000+ projects as of Dec 2025). Instructs the agent to call memory_session_start on first turn + memory_context before each task β€” a soft guarantee like tier B, but works even for agents not in the tier table above.

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:

  • your-project/ β†’ your-project/.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.


🧭 Project origin & the problem it solves β€” click to expand (optional read, 2-min story)

Project Origin β€” 2 years, 1 question

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 (27 MCP tools, 6-tier architecture, plug-and-play MCP). The autonomous-driving research direction β€” testing whether place-based episodic memory can complement (not replace) sensor-fusion robustness when sensors degrade β€” is being developed as its own track: docs/MATHIR_FOR_ROBOTICS.md.

The story that hurts

MATHIR Story

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:

MATHIR Story 2 β€” The Solution

βœ… 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 ⚠️, zero cloud.


πŸ”₯ 5 real-world problems MATHIR solves

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.

🍰 The 6 Memory Tiers

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.

MATHIR Brain Architecture

Why? See the research paper (6 theorems) and the architecture rationale doc.


The story that hurts

MATHIR Story

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:

MATHIR Story 2 β€” The Solution

βœ… 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 ⚠️, zero cloud.


πŸ”Œ MCP Plug & Play

Add MATHIR to your AI agent (OpenCode, Claude Code, Cursor, MiMo, etc.):

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

That's it. 27 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).

Console Scripts (universal, IDE-agnostic)

Command What it does
mathir-mcp MCP stdio server (27 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


πŸ“š Documentation Index

Doc Purpose
mathir_mcp/README.md Install, MCP setup, all 27 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 Master's research paper (6 theorems)
docs/03_MASTER_QA_GUIDE.md 63 Q&A for defense / evaluation
docs/07_MATHIR_VS_VECTORDB_USE_CASES.md Where MATHIR vs. a plain vector index each fit (chat use case, cascade architecture)
docs/MATHIR_FOR_ROBOTICS.md Autonomous-driving research track: place-memory hypothesis, honest positioning vs. sensor-fusion-robustness literature
CHANGELOG.md Full version history
mathir_mcp/GLOBAL_INSTRUCTIONS.md Universal AI agent instructions

πŸ› οΈ Install Scripts

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.


πŸ“ Positioning (2026)

By mid-2026 the "LLM has no memory" gap is being closed from two directions at once: model vendors ship native memory (Claude, ChatGPT, Gemini all added cross-session recall in 2026), and a funded agent-memory ecosystem exists (Mem0, Zep/Graphiti, Letta, Cognee, LangMem β€” hybrid retrieval, temporal graphs, published LongMemEval/LoCoMo numbers). MATHIR doesn't try to out-benchmark that ecosystem on retrieval quality β€” that's a well-covered, well-funded problem now. What MATHIR set out to test, and what the experiments in this repo actually validate, is narrower and different:

  • Structured tiering that self-maintains β€” 6 memory tiers (working/episodic/semantic/procedural/immunological/guardrail) with decay, promotion, and consolidation running automatically, not just a flat store with a similarity search.
  • Cross-process, cross-provider, fully local β€” the same memory is shared by multiple agents (Claude, Codex, OpenCode, MiMo, ...) running in separate processes on one machine, coordinating through shared memory with no cloud dependency and no vendor lock-in. This multi-agent "god mode" orchestration is tested and working (see below) β€” it's not a common feature in the products above.
  • Runs on modest hardware β€” validated on consumer laptops/CPUs, not a managed cloud service; the edge-deployment path (Pi, Jetson) is an explicit next step, not a marketing claim.

Honest gaps: MATHIR has no external benchmark citations, no peer review, and no third-party adoption yet β€” the numbers below are internal and should be read as such. If you need a battle-tested, funded, widely-adopted memory backend today, Mem0/Zep/Letta are reasonable choices. MATHIR is a research project testing a specific architectural bet (structured, self-maintaining, local-first, multi-agent memory), documented openly including where it falls short.

Anomaly detection status: the MCP server/daemon (mathir_lib/, what coding agents connect to) now wires its immunological tier to a real, live Mahalanobis-distance detector: /api/memory/save scores every incoming embedding against a running per-project baseline and can write tier='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 the immunological tier for review via memory_audit_immunological. A separate, simpler (non-Mahalanobis) detector also exists in mathir_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


πŸ“Š Tests & Benchmarks

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


πŸ—οΈ Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  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


πŸ› οΈ Project Structure

MATHIR/
β”œβ”€β”€ mathir_mcp/         ← Install this (v8.9.4, 27 MCP tools, God Mode + Guardrails + universal proxy)
β”œβ”€β”€ benchmarks/         ← Reproducible benchmarks
β”œβ”€β”€ docs/                ← Research 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)

πŸ—ΊοΈ Roadmap

βœ… Done (V1–V8.5.1)

βœ… 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)

πŸ”œ Next: 4 validation stages

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/>&lt;500 MB RAM"| A2
    V93 --- |"bge-large-en-v1.5<br/>CUDA fp16 500MB<br/>&lt;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
Loading
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

πŸ“‹ Future

πŸ“‹ V10 Open-source release (HuggingFace Β· PyPI)

Why this order?

  1. V9.1 Vision (now): Cheap, fast, validates the memory layer across many LLMs. No hardware risk.
  2. V9.2 Raspberry Pi: Real edge constraints (CPU only, 4GB RAM). If it works here, it works anywhere.
  3. V9.3 Jetson: GPU acceleration, but still bounded power. The "production edge" sweet spot.
  4. 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.

🀝 Contributing

We welcome PRs and security reports. Open an issue or pull request.


πŸ“„ Citation

@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


πŸ“œ License

MIT β€” free for commercial and research use.