Show HN: Maccha – Cross Agent Brain for Antigravity, Claude Code, OpenCode etc.

Notifications You must be signed in to change notification settings

Fork 1

Star 2

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

2 Commits

2 Commits

brain

brain

cli-tools

cli-tools

infrastructure

infrastructure

learned-lessons

learned-lessons

system-brain

system-brain

.gitignore

.gitignore

LICENSE

LICENSE

README.md

README.md

publish.sh

publish.sh

setup.sh

setup.sh

uninstall.sh

uninstall.sh

Repository files navigation

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 │ └─────────────────────────────────────────────────────────┘

Tier File / Location Purpose Priority

TIER 0 ~/AGENTS.md Master Bootstrap: The absolute first file any agent must read. Activates the engine. 🔴 Highest

TIER 1 ~/BRAIN/AGENTS.md Project Mandates: Session rules, meso memory rules, and local development standards. 🟠 High

TIER 2 ~/.gemini/GEMINI.md Machine Mandates: Cross-project preferences, machine hardware profile, global security. 🟡 Medium

TIER 3 ~/INFO/over-owner/SITUATIE_OVERZICHT.md Owner Situation: Central reference for personal context, legal/medical history, and targets. 🟢 Reference

TIER 4 ~/BRAIN/tms/ + ~/BRAIN/policies/ Live State: TMS task flow (todo / in-progress / done) and the machine-enforced guardrails. 🟢 State

TIER 5 ~/IMPROVEMENT.md Long-Term Auto-Improvement: Feedback loop tracking what the agent learned during the session. 🟢 Feedback

TIER 6 ~/BRAIN/learned-lessons/ Technical Lessons: A highly curated directory of reusable coding/configuration patterns. 🟢 Lessons

Important

The Routing Rule: A piece of information MUST live in exactly one tier. If a conflict or duplicate arises, priority is determined from top to bottom (Global/Machine Rules supersede project templates, which supersede situational references).

Note

The Zone Model: ~/BRAIN/ is exclusively the technical capsule (mandates, memory, TMS, hooks, policies) — it stays PII-free and portable. Personal content lives in dedicated root zones: ~/INFO/ (dossiers & knowledge base), ~/PLAN/ (plans) and ~/INBOX/ (the owner → agent drop-off channel: drop any PDF, letter or note there; the session-startup script reports the item count, and the agent processes every item to its owner location and empties the folder). Convenience access to single files from the root happens only via symlinks.

🛠️ 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/-Q.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 [email protected]:KarelTestSpecial/real-agent-setup.git cd real-agent-setup bash setup.sh

Note

Safe Installation: setup.sh is completely non-destructive. It carefully copies templates to your home folder without overwriting any of your existing files or configurations.

What the setup scri

[truncated for AI cost control]