🧠 MACCHA — Multi-Agent Continuous Context Harness

Turn Antigravity, OpenCode, Claude Code, or any other AI coding assistant into a fully contextualized, highly secure, self-improving Real-World Digital Assistant.

MACCHA is a lightweight file architecture, a set of intelligent markdown templates, and a suite of maintenance scripts that live in your home directory. It acts as a universal, persistent "brain" that any local AI agent can plug into.

⚡ What is MACCHA?

It solves the biggest limitation of modern AI coding agents: transient memory and repetitive context-setting.

When you open a new workspace or start a terminal session, standard AI assistants start from absolute zero. They forget who you are, your technical preferences, your system constraints, and the hard-earned lessons from yesterday. You have to explain your project rules over and over again.

MACCHA solves this permanently. By establishing a structured memory hierarchy and automated maintenance loops, any AI agent reading your system instantly inherits a persistent, self-improving, and highly protected professional profile.

Because this memory lives directly in your file system—not in a proprietary cloud silo—MACCHA creates a shared, evolving intelligence across different platforms. You can switch seamlessly between Antigravity, OpenCode, and Claude Code. They will all read from and write to the same MACCHA brain, sharing a single, unified digital identity.

Imagine this:

• Monday: You tell Antigravity that you strictly use pnpm and prefer dark-mode CSS without Tailwind. The agent writes this rule to your MACCHA memory.
• Wednesday: You open Claude Code in a completely different project. It instantly reads MACCHA, knows your pnpm and CSS preferences, checks your todo.md to see what you're working on, and starts coding exactly the way you like.
• Friday: You shut everything down. No background servers are running. Your entire agentic identity rests safely in a few kilobytes of text files, ready to be instantly rehydrated next week.

🆚 The MACCHA Philosophy (vs. Always-On Agents)

While projects like Hermes Agent and OpenClaw provide incredibly powerful autonomous assistants, they are typically designed as "always-on" daemons. They require heavy local computing power, continuous background processing, and constant API polling. For many users, running a heavy 24/7 node simply isn't feasible.

MACCHA is built for people who cannot or do not want to run heavy, 24/7 background agents, but still want the compounding benefits of a sophisticated, self-improving autonomous system.

• Lightweight Hardware: Runs flawlessly on constrained hardware (like Chromebooks, older laptops, or free-tier cloud environments). The agent only consumes compute when you actively invoke it.
• Cross-Agent Synergy: You are never locked into one tool. Antigravity can start a complex coding task today, and OpenCode can continue it tomorrow.
• Human-in-the-Loop (HITL) by Default: Perfect for sensitive operations, financial tasks, or personal data. You remain the conductor. The agent acts on-demand and proposes changes; you approve them. There are no runaway background processes.
• True Continuity: Despite not running 24/7, MACCHA's architecture gives you the same continuous context, tool integration, and long-term memory as an always-on agent.

If you want the persistent memory and deep context of a sophisticated digital assistant, but need it to be highly resource-efficient and fully under your control—MACCHA is your bridge.

🗂️ How It Works: The 7-Tier Architecture

To make this possible, MACCHA organizes your system context into seven distinct, isolated tiers. This prevents memory bloat, avoids context-drift, and enforces a strict priority structure so the AI always knows exactly what is most important.

             ┌─────────────────────────────────────────────────────────┐
             │                      USER REQUEST                       │
             └────────────────────────────┬────────────────────────────┘
                                          │
                                          ▼
                      ┌───────────────────────────────────────┐
                      │    TIER 0: ~/AGENTS.md (Bootstrap)    │
                      └───────────────────┬───────────────────┘
                                          │
                                          ▼
                      ┌───────────────────────────────────────┐
                      │  TIER 1: ~/BRAIN/AGENTS.md (Mandates) │
                      └───────────────────┬───────────────────┘
                                          │
                                          ▼
                      ┌───────────────────────────────────────┐
                      │  TIER 2: ~/.gemini/GEMINI.md (Global) │
                      └───────────────────┬───────────────────┘
                                          │
                                          ▼
        ┌─────────────────────────────────┴─────────────────────────────────┐
        ▼                                 ▼                                 ▼
┌──────────────┐                  ┌──────────────┐                  ┌──────────────┐
│    TIER 3    │                  │    TIER 4    │                  │    TIER 5    │
│    SITUATION │                  │  LIVE STATE  │                  │ AUTO-IMPROVE │
│    ~/INFO    │                  │ ~/BRAIN/tms  │                  │~/IMPROVEMENT │
└──────────────┘                  └──────────────┘                  └──────────────┘
        │                                 │                                 │
        └─────────────────────────────────┼─────────────────────────────────┘
                                          │
                                          ▼
                      ┌───────────────────────────────────────┐
                      │  TIER 6: ~/BRAIN/learned-lessons/     │
                      └───────────────────┬───────────────────┘
                                          │
                                          ▼
             ┌─────────────────────────────────────────────────────────┐
             │              FULLY CONTEXTUALIZED AI AGENT              │
             └─────────────────────────────────────────────────────────┘

🛠️ Deep Feature Breakdown

🧠 1. Memanto Working Memory Engine (brain/lib/)

A sophisticated, 13-category temporal memory bank (Instruction, Fact, Decision, Goal, Preference, etc.) that features:

• Exponential Confidence Decay: Automatically reduces the confidence scores of transient situational facts over time while preserving stable, core facts.
• AI-Powered Semantic Conflict Detection: Scans proposed memory inserts against existing ones to catch and supersede contradictions automatically (compatible with Gemini 3.0 Thought Signatures).
• Hybrid Search Recaller: Batched cosine-similarity vector embeddings combined with Jaccard keyword overlap fallbacks.

📊 2. MACCHA Storage Manager (infrastructure/storage-manager.js)

An advanced diagnostics utility specifically engineered to maintain system health on resource-limited systems (such as Chromebooks running Crostini):

• Terminology Alignment: Categorizes project directory state as either 💧 HYDRATED (dependencies present) or 🌵 DORMANT (dependencies pruned to free space).
• Interactive Cleanup: Clears cache stores (pnpm, npm), optimizes bloated .git databases via git gc --prune=now, and identifies massive unused files to reclaim space instantly.

🛡️ 3. Absolute Supply Chain & Safety Guards

MACCHA turns your workspace into an ironclad security zone, protecting users who aren't cybersecurity experts:

• Supply Chain Cooldown: Enforces a minimum-release-age=7d for all packages to safeguard against zero-day malware.
• HITL (Human-in-the-Loop) Mandate: Under no circumstances can an agent execute actions modifying real-world capital or sending emails without explicit manual confirmation.
• Auto-Guard Scans: Performs pre-install pnpm audit checks and prints immediate Safety Report: GREEN/RED flags.
• Secrets Scan: Detects leaked API keys, RSA private keys, or service JSONs before committing.

📌 4. Task Management System (TMS) Hygiene

Automatic, script-driven maintenance keeps your daily workspace organized without mental overhead:

• TMS Integrity Hook: Validates that all files modified in the workspace or committed via git are logged correctly under the TMS files (todo.md, in-progress.md, done.md).
• Pruning Rotator: Completed items flow through done.md and are archived quarterly into ~/BRAIN/archive/tms/<year>-Q<x>.md, preventing context windows from bloating.
• Rule Guard at Startup: session-startup flags leftover [x] items, broken TMS symlinks and an overgrown in-progress.md (max ±10 active items), and triggers a throttled weekly sweep.

🗄️ 5. Encrypted Weekly Backup (cli-tools/maccha-backup)

Set-and-forget disaster recovery for the entire knowledge base:

• AES-256 encrypted tar of your personal zones (INFO/ PLAN/ BRAIN/ …) written to a mounted cloud drive, with a 4-backup rotation and an automatic decrypt-and-list integrity check.
• Key stays local: generated once into ~/.config/maccha/backup.key (keep an off-device copy); plain restore instructions are written next to the backups — without the key.
• Zero overhead: triggered automatically (throttled, once per 7 days) by session-startup.

📂 Repository Directory Map

real-agent-setup/
├── system-brain/                  # MACCHA templates (PII-free, ready to customize)
│   ├── AGENTS.md                  #   Root bootstrap — fill with your own context
│   ├── IMPROVEMENT.md             #   LTAIS auto-improvement loop
│   ├── ALIASES.md                 #   Your aliases and shortcuts
│   ├── todo.md                    #   Task tracker
│   ├── in-progress.md             #   Current work
│   └── done.md                    #   Accomplishments
├── brain/                         # Memory engine
│   ├── lib/memanto_engine.py      #   13-category working memory (Memanto)
│   └── README.md
├── cli-tools/                     # Shared CLI utilities (AI models, storage, cleanup)
├── infrastructure/                # Shared bridges and session maintenance scripts
├── learned-lessons/               # Runtime directory (populated locally, never pushed)
│   └── README.md
├── setup.sh                       # Install script for new machines
└── publish.sh                     # Publish local improvements back to repo

(Note: Directories like cli-tools and infrastructure contain numerous specialized scripts for system maintenance, AI integrations, and daily workflows.)

🚀 Quick Start Guide

Prerequisites

• A Unix-like environment (Linux, MacOS, WSL, or ChromeOS Crostini).
• git and bash installed.
• An AI coding assistant capable of reading local files (Antigravity, OpenCode, Claude Code, Cursor, etc.).

1. Installation

To set up a new machine with the complete MACCHA scaffolding harness:

git clone --depth 1 git@github.com:KarelTestSpecial/real-agent-setup.git
cd real-agent-setup
bash setup.sh

What the setup script accomplishes:

1. Installs all standard CLI utilities in ~/bin/ — including the session-startup and session-closeout lifecycle scripts.
2. Configures Infrastructure Bridges (storage manager, cloud-drive access, deep-research runner) in ~/INFRA/.
3. Copies MACCHA PII-free templates (AGENTS.md, IMPROVEMENT.md, etc.) to your home folder ~/.
4. Offers an optional interactive prompt to download, compile, and configure the local Himalaya CLI email client in ~/.local/bin/.

2. Post-Installation Configuration

1. Populate Your Context: Open the generated ~/AGENTS.md and define your personal constraints, rules, and technical preferences.
2. Add CLI Tools to PATH: In your ~/.bash_aliases (or ~/.zshrc), ensure ~/bin is included in your PATH:

   export PATH="$HOME/bin:$PATH"

3. Boot Your Agent: Launch Antigravity, OpenCode, or your preferred agent. The agent will read ~/AGENTS.md automatically at startup and immediately assume its professional persona.

🧹 Uninstalling

Changed your mind, or just testing on a throwaway machine? uninstall.sh reverses setup.sh — safely. It removes a file only if it is still byte-for-byte identical to the repo copy (i.e. you never touched it). Anything you edited, and every personal data directory, is left completely alone.

cd ~/real-agent-setup
bash uninstall.sh            # DRY-RUN — lists what would be removed, deletes nothing
bash uninstall.sh --force    # asks y/N before deleting each pristine file
bash uninstall.sh --force --yes   # delete pristine files without prompting

🛡️ Maintainer Publishing Guide

To push local improvements, bug fixes, or performance refinements to the shared utilities back to the public repository:

cd ~/real-agent-setup
bash publish.sh           # Interactively copies, commits, and pushes
bash publish.sh --dry-run # Review changes before committing

🔒 Local-only sanitization config (gitignored)

publish.sh copies your working scripts verbatim, so a few personal details can ride along (a home-folder name, a one-off local tool). To keep those out of the public repo without ever writing them into the committed publish.sh itself, the publish step is driven by three optional, gitignored config files in the repo root. They live only on your machine; if a file is absent, that step is simply skipped.

In addition, you can wrap any personal, non-generic block inside an otherwise-shared script with markers — publish.sh strips everything between them on sync:

# >>> LOCAL-ONLY
...personal block kept locally, never published...
# <<< LOCAL-ONLY

MACCHA v2.0 | Multi-Agent Continuous Context Harness
"Continuity is the absolute key to agentic performance."