The Open-Source Operational Hub for Creators, Busy Operators, Freelancers, and Technical Builders.
ACI transforms any AI Agent (Claude Code, Gemini, Antigravity, Cursor) into a persistent, context-aware operational team.
Instead of re-explaining your background, brand voice, target clients, and workflows in every new chat, ACI provides a central Brain (brain/) and dedicated Operational Engines that adapt to your exact daily work.
This README covers four things: why the architecture works, the empirical research backing the design, the proof it produces calibrated output, and how to actually run it.
| Archetype | How ACI Empowers You | Primary Engines |
|---|---|---|
| π¨ Creators & Solopreneurs | Turn raw voice dumps into high-performing newsletters, LinkedIn posts, and viral video scripts in your authentic voice. | content-engine/video-engine/ |
| β‘ Busy Executives & Operators | Get 30-second meeting cheat sheets, instant email drafts, and competitor teardowns without AI fluff. | research-vault/email-engine/ |
| πΌ Freelancers & Agencies | Auto-generate winning 1-page proposals, Scopes of Work (SOW), and client kickoff agendas directly from call notes. | client-ops/research-vault/ |
| π Founders & Technical Builders | Write technical PRDs, run cold outbound campaigns, scrape leads, and connect APIs/MCPs with zero token waste. | product-engine/automations/ |
These 8 engines are curated starting presets, not a fixed ceiling. They cover the most common workflows, but the folder structure isn't special-cased in code β it's just a convention your AI assistant follows. If your work needs something these don't cover, ask it to spawn a new module (a
podcast-engine/, asponsorships/tracker, afinance-ops/folder β whatever your actual workflow is) and it will build one on the same 3-tier structure below. See the Dynamic Module Spawning Protocol inCLAUDE.md/AGENTS.md.
Operating AI systems generally follows one of three architectural approaches: single-session chat windows, autonomous agent frameworks, or file-based contextualized infrastructure.
| Dimension | Standard Chatbot (Web UI) | Autonomous Agent Frameworks (CrewAI, LangChain, AutoGPT) | ACI (Contextualized Infrastructure) |
|---|---|---|---|
| Context Persistence | Stateless. Manual re-prompting required every session. | In-memory session state or external vector database. | Git-tracked markdown files in brain/. Transparent and persistent. |
| Execution Reliability | High manual burden. User supervises each prompt turn. | Low to moderate. Autonomous loops can enter recursive retries or hallucinate tools. | High. Deterministic Python handles mechanical tasks; LLM handles synthesis. |
| Token Efficiency | Poor. Resends growing chat histories with each prompt turn. | Poor. Autonomous thought loops and heavy tool call traces burn tokens rapidly. | Optimal. Zero-token Python utilities offload data tasks; prompt caching lowers costs up to 90%. |
| Observability & State | Visible in chat window, lost on refresh. | Opaque. State is hidden inside framework abstractions and graph objects. | Completely transparent. Every asset, status, and learning lives as plain text on disk. |
| Infrastructure Overhead | Zero setup. | High. Requires vector DBs, Python orchestration libraries, and complex schema configs. | Zero external dependencies. Standard markdown files and vanilla Python scripts. |
Instead of pasting business background, style boundaries, and ICP details into prompts, the model references brain/ on demand. Because core identity and rule files stay stable, LLM providers cache these tokens, reducing input costs by up to 90% on subsequent turns.
Mechanical operations do not require LLM inference:
- Data ingestion, web scraping, email syntax cleaning, and workspace indexing run as native Python scripts in
automations/scripts/. - Local script execution consumes 0 API tokens and executes in milliseconds on local CPU.
Autonomous agents frequently fail by loading dozens of raw files into context, causing retrieval noise and context saturation:
- ACI separates discovery from execution.
- The Map (
brain/workspace_index.md) provides a 1-line index of every asset and active learning. - The Territory (
<engine>/examples/and<engine>/SOP.md) is read strictly when an agent performs a task in that specific domain.
- Failure Prevention: When a script breaks or output requires correction, the failure mode is logged to
brain/memory.mdunder## π« Corrected Mistakes. Subsequent sessions check this ledger before generating work. - Quality Anchoring: When a deliverable meets production quality, it is stored in that module's
examples/directory. Future prompts use these proven assets as few-shot references.
| Operation | Standard Chatbot | Autonomous Agent Framework | ACI Architecture | Token & Cost Impact |
|---|---|---|---|---|
| Workspace Orientation | Re-type background (~1,500 tokens/session) | Loads system prompts + schema overhead (~3,000 tokens) | Cached brain/ context |
~75% to 90% savings |
| Workspace Cataloging | Manual file discovery | Multi-step agent tool calling loop (~50,000+ tokens) | Native Python scan (index_workspace.py) |
100% free (0 tokens, $0.00) |
| Raw Data Cleaning | Paste raw CSV/HTML dumps (~25,000 tokens) | LLM-based JSON extraction loops (~20,000 tokens) | Python regex scripts clean data before model sees it | ~95% savings |
| Error Corrections | Multi-turn chat corrections resending full context | Recursive self-retry loops often fail or loop indefinitely | Single write to memory.md prevents repeat errors |
~80% savings |
On these numbers: the prompt-caching figure (up to 90%) matches Anthropic's published prompt-caching discount for cached input tokens. The rest are order-of-magnitude illustrations based on typical workflow shapes, not measured benchmarks β actual savings depend on your prompt sizes and how much of a task is deterministic Python vs. LLM-driven.
ACI's core architectural choices are grounded in published research across computational linguistics, LLM systems, and agent architecture:
| Architectural Choice in ACI | Published Research & Benchmarks | Core Finding & Validation |
|---|---|---|
Lazy Loading & Map/Territory (brain/workspace_index.md) |
"Lost in the Middle: How Language Models Use Long Contexts" (Liu et al., Stanford / UC Berkeley, TACL 2024) | Attention degrades when relevant context is placed in the middle of long prompts. Isolating active context to brief maps prevents context saturation. |
Deterministic Python Offloading (automations/scripts/) |
"Program-Aided Language Models (PAL)" (Gao et al., CMU, ICML 2023) / "Program of Thoughts (PoT)" (Chen et al., TMLR 2023) | Decoupling reasoning from execution by delegating data processing to a runtime interpreter eliminates arithmetic and syntax hallucinations at zero token cost. |
Golden In-Context Examples (<engine>/examples/) |
"Rethinking the Role of Demonstrations: What Makes In-Context Learning Work?" (Min et al., Meta AI / UW, EMNLP 2022) | Concrete demonstrations anchor format, output boundaries, and label distribution far more reliably than abstract system prompt instructions. |
Single-Agent File Staging vs. Swarms (drafts/ to published/) |
"From Spark to Fire: Modeling and Mitigating Error Cascades in LLM-Based Multi-Agent Collaboration" (2026) / "Towards Long-Horizon Agents: A Survey" (2026) | Autonomous multi-agent pipelines suffer from compounding error cascades ("compound interest in reverse") and autonomy drift. File-based staging creates verifiable checkpoints. |
Static Markdown Prefixes (brain/identity.md, rules.md) |
Anthropic & Google Prompt Caching Technical Specifications (2024-2026) | Stable prompt prefixes enable KV-cache reuse, reducing input token costs by up to 90% and cutting latency by up to 80%. |
- Paper: "Lost in the Middle: How Language Models Use Long Contexts" (Liu et al., Stanford / UC Berkeley, TACL 2024)
- Key Finding:
"Performance is highest when relevant information occurs at the very beginning or end of the context, and significantly degrades when models must access relevant information in the middle of long contexts... performance drops even in models explicitly designed for extended context windows."
- How ACI Applies It:
ACI prevents context saturation by separating discovery from execution ("Map and Territory"). Instead of stuffing an entire repository or chat history into context,
brain/workspace_index.mdacts as a compact 1-line index. Full domain rules (SOP.md) and benchmark examples (examples/) are lazy-loaded on demand only when working within that specific operational engine.
- Papers: "Program-Aided Language Models (PAL)" (Gao et al., Carnegie Mellon University, ICML 2023) & "Program of Thoughts (PoT)" (Chen et al., TMLR 2023)
- Key Finding:
"Disentangling computation from reasoning by having the LLM generate programmatic steps, rather than performing calculations directly in natural language... delegating execution to a runtime interpreter bypasses the inherent computational and arithmetic weaknesses of LLMs."
- How ACI Applies It:
Mechanical, parsing, and data validation routines (such as lead email syntax validation, web scraping, and workspace indexing) are offloaded to native Python scripts in
automations/scripts/. This ensures 100% deterministic accuracy at zero token cost, reserving LLM inference exclusively for synthesis and drafting.
- Paper: "Rethinking the Role of Demonstrations: What Makes In-Context Learning Work?" (Min et al., Meta AI / University of Washington, EMNLP 2022)
- Key Finding:
"Demonstrations serve primarily to locate or activate intrinsic abilities that the LLM has already acquired during pre-training... the model relies heavily on the overall format, label space, and distribution of the input text rather than learning a task function from scratch."
- How ACI Applies It:
Every engine under ACI includes an
examples/directory containing concrete golden benchmarks (e.g.,content-engine/examples/linkedin_golden.md). Rather than relying on multi-paragraph instructional rules, ACI supplies pre-calibrated few-shot examples that instantly anchor output format, tone, and structure.
- Papers: "From Spark to Fire: Modeling and Mitigating Error Cascades in LLM-Based Multi-Agent Collaboration" (2026) & "Towards Long-Horizon Agents: A Survey" (2026)
- Key Finding:
"Unconstrained multi-agent loops are vulnerable to compounding error cascades, where early inaccuracies propagate across downstream agents and solidify into systemic failure... autonomous agents chaining long trajectories suffer from autonomy drift without stable, deterministic verification checkpoints."
- How ACI Applies It:
ACI avoids opaque in-memory multi-agent swarms (such as complex CrewAI or AutoGPT loops) in favor of a single-agent, file-based staging workflow. Artifacts move deliberately across observable filesystem checkpoints (
drafts/tooutputs/topublished/), with key decisions and corrections logged transparently inbrain/memory.mdand Git diffs.
- Reference: Anthropic & Google Prompt Caching Technical Specifications (2024-2026)
- Key Finding:
"By caching the KV-cache of stable prompt prefixes that do not change across turns, systems achieve up to a 90% reduction in input token costs and up to an 80% reduction in time-to-first-token latency."
- How ACI Applies It:
ACI isolates static persona, brand boundaries, and operating constraints into permanent files (
brain/identity.md,brain/voice-and-tone.md,brain/rules.md). Because these files remain stable across sessions, LLM providers cache the prefix across turns, cutting operating token overhead.
Architecture claims are cheap. Here's an actual before/after β not a hypothetical.
Without a brain/ folder (a fresh chat, generic prompt: "write me a LinkedIn post about AI infrastructure"):
"In today's fast-paced digital world, AI is a game-changer for businesses looking to unlock new levels of productivity. By leveraging the power of AI, teams can revolutionize how they work and stay ahead of the competition."
Vague, no numbers, and it hits several of the exact phrases brain/voice-and-tone.md explicitly bans.
With ACI's brain/ context β this is the real, unedited golden benchmark stored at content-engine/examples/linkedin_golden.md:
"Most founders use AI like an expensive Google search bar.
The top 1% use AI as an autonomous operational department.
Here is the exact 4-tier infrastructure we built to handle 80% of our daily operations..."
Specific framework, concrete claim, zero banned words β because the model read voice-and-tone.md and the golden examples before writing a single line, per the execution protocol in content-engine/CLAUDE.md.
Verify it yourself: every example referenced in this README is a real file in this repo, not copy staged for marketing. Open content-engine/examples/, email-engine/examples/, client-ops/examples/, research-vault/examples/, product-engine/examples/, or video-engine/examples/ and check.
- One of: Claude Code, Gemini CLI, Antigravity, or Cursor (any AI coding assistant that can read local files and run shell commands).
- Python 3.9+ β only needed if you plan to run the scripts in
automations/andemail-engine/scripts/(lead cleaning, web scraping, workspace indexing). Not required just to draft content. - Git, to clone the repo.
git clone https://github.com/your-username/ACI.git
cd ACIOnly needed if you'll run the automation scripts:
pip install -r requirements.txtOpen your AI assistant in this directory (claude, gemini, cursor, etc.) and paste the following prompt:
Run the ACI Deep Setup Interview. Read `brain/rules.md` and `CLAUDE.md`, then interview me step-by-step to customize this workspace.
Follow this protocol:
1. Ask 1-2 focused questions at a time across the 5 phases:
- Phase 1: Archetype & Background (Creator, Busy Operator, Freelancer, or Founder + Core Mission).
- Phase 2: Audience & Offer (Target persona, 3 daily headaches, core services/products, credibility proof).
- Phase 3: Voice Calibration & Anti-Sludge (Paste 1-2 writing samples, list pet peeves and banned words).
- Phase 4: Workflow Mapping & Engine Selection (Select active engines, detect custom channels needed).
- Phase 5: Auto-Synthesis & Workspace Calibration (Populate brain/, calibrate engine examples/, log initial state to memory.md, deliver 3 starter commands).
2. Accept rough voice-note transcripts, messy bullets, or brief answers.
3. Automatically populate `brain/identity.md`, `brain/voice-and-tone.md`, and `brain/icp-and-offers.md`.
4. Calibrate the `examples/` across active engines so they feature my real offers, audience, and voice.
5. If my workflow requires custom modules (e.g., `podcast-engine/`, `sponsorships/`), autonomously spawn them using the 3-Tier Blueprint.
6. Conclude with 3 tailored, ready-to-run commands for my specific daily workflow.
Begin with Phase 1: Archetype & Background.Two checks that setup actually landed:
- Open
brain/identity.mdβ it should describe your business, not still say[Your Name / Brand Name]. - Run the workspace sweep to confirm the indexer picks up your new context:
This regenerates
python automations/cron/scheduled_tasks.py
brain/workspace_index.mdand reports what's pending in each engine's staging folder. Zero errors means the workspace is wired correctly.
Every folder contains its own CONTEXT.md, CLAUDE.md, or SOP.md defining what the folder does, step-by-step instructions for the AI to follow, and golden benchmark examples:
ACI/
βββ README.md # Main project hub & kickoff setup prompt
βββ CLAUDE.md / AGENTS.md # Global AI operating guidelines & navigation
β
βββ brain/ # π§ The Core Context Layer (Source of Truth)
β βββ CONTEXT.md # Guided overview of the Brain layer
β βββ memory.md # Persistent AI memory (learnings, corrections, session log)
β βββ workspace_index.md # Generated high-level asset map & watchlist
β βββ workspace_index.json # Machine-readable structured asset catalog
β βββ identity.md # Bio, mission, archetype, positioning, 90-day targets
β βββ voice-and-tone.md # Writing rules, vocabulary, banned clichΓ©s, formatting
β βββ icp-and-offers.md # Target audience, pain points, core offers, pricing
β βββ rules.md # Universal AI guardrails & operating constraints
β βββ knowledge/ # Meeting frameworks, case studies, playbooks
β βββ CONTEXT.md # Guide to long-form knowledge assets
β
βββ content-engine/ # βοΈ Content Creation & Repurposing System
β βββ CONTEXT.md # Guided overview & quick prompts for Content Engine
β βββ CLAUDE.md / SOP.md # Step-by-step SOP for drafting posts & newsletters
β βββ examples/ # Golden standards ("What Good Looks Like")
β βββ templates/ # Voice-dump repurposer, hook library, post frameworks
β βββ drafts/ & published/ # Content staging pipeline
β
βββ email-engine/ # βοΈ Inbound & Outbound Email Operations
β βββ CONTEXT.md # Guided overview & quick prompts for Email Engine
β βββ CLAUDE.md / SOP.md # Cold outreach & sequence generation SOPs
β βββ examples/ # Golden cold emails, follow-ups, objection handlers
β βββ sequences/ # Multi-touch drip templates
β βββ scripts/validate_leads.py # Python lead syntax cleaner & deduplicator
β
βββ video-engine/ # π¬ Video Production & Retention System
β βββ CONTEXT.md # Guided overview & quick prompts for Video Engine
β βββ CLAUDE.md / SOP.md # Hook-to-retention framework & visual cue SOPs
β βββ examples/ # Golden 8-min YouTube script & 45s viral Short
β βββ templates/ # 10-min YouTube framework, title & thumbnail matrix
β βββ scripts/ # Staging directory for generated video scripts
β
βββ client-ops/ # πΌ Proposals, Scopes of Work & Client Onboarding
β βββ CONTEXT.md # Guided overview & quick prompts for Client Ops
β βββ CLAUDE.md / SOP.md # Proposal generation SOP & pricing defense rules
β βββ examples/ # Golden winning 1-page proposal
β βββ templates/ # 1-page proposal, Scope of Work (SOW), kickoff agenda
β βββ proposals/ # Staging directory for client deliverables
β
βββ research-vault/ # π Market & Competitor Intelligence
β βββ CONTEXT.md # Guided overview & quick prompts for Research Vault
β βββ CLAUDE.md / SOP.md # Research teardown SOP & evidence citation rules
β βββ examples/ # Golden strategic competitor teardown
β βββ templates/ # Competitor audit & executive dossier templates
β βββ briefs/ # Staging directory for saved research reports
β
βββ product-engine/ # π Product Specs, Launches & Changelogs
β βββ CONTEXT.md # Guided overview & quick prompts for Product Engine
β βββ CLAUDE.md / SOP.md # PRD authoring & launch day sequencing
β βββ examples/ # Golden technical feature PRD
β βββ templates/ # Product launch checklist & weekly changelog format
β βββ specs/ # Staging directory for feature specifications
β
βββ automations/ # β‘ Python Scripts & Workflow Utilities
β βββ CONTEXT.md # Guided overview & tool execution guide
β βββ CLAUDE.md # Guidelines for writing & running automations
β βββ scripts/ # Scrapers, lead enrichers, workspace indexer
β βββ cron/ # Scheduled tasks & maintenance utilities
β
βββ tools-and-mcp/ # π Tooling Hub & Protocol Configurations
βββ CONTEXT.md # Guided overview & MCP setup instructions
βββ CLAUDE.md # Tool discovery & execution guidelines
βββ mcp-configs/ # Ready-to-use MCP server configs (Stripe, Supabase, Brave Search)
Every engine folder β including the 8 presets and any custom module you spawn β adheres to the same 3-tier structure:
CLAUDE.md/SOP.md(The Mind): Explicit role, phase-by-phase workflow, input/output specifications.examples/(The Golden Standard): Few-shot examples of what exceptional output looks like.templates/&scripts/(The Hands): Reusable frameworks and deterministic code to execute the work cleanly.
Building your own module: this isn't a hardcoded plugin system β it's a folder convention. To add a domain the presets don't cover, just tell your AI assistant what you need (e.g. "I run a podcast, spawn a podcast-engine/ module"). It will create the folder, write a CLAUDE.md/SOP.md for that domain, and stage examples/, templates/, and a staging directory β the exact same shape as content-engine/ or client-ops/. Once it exists, it's a first-class engine: reference it from brain/memory.md, extend its examples/ over time, and it behaves identically to a preset.
Every time your AI assistant does a task in this workspace, it follows the same three-step order β this is the actual logic defined in CLAUDE.md/AGENTS.md, not a black box:
- Ground in Core Context: Before writing anything, it reads
brain/memory.md(active projects, past corrections),brain/identity.md,brain/voice-and-tone.md,brain/icp-and-offers.md, andbrain/rules.md. - Follow the Folder's SOP: It reads that engine's
CLAUDE.md/SOP.mdand studiesexamples/to match the quality bar, before drafting anything new. - Execute Deterministically First: If a script in
automations/scripts/or<engine>/scripts/can do the task mechanically (cleaning, scraping, parsing), it runs the script instead of burning LLM tokens on it.
This is why the kickoff interview matters: skip it, and step 1 has nothing real to ground on β every engine will fall back to generic output because brain/ is still template placeholders.
Once the kickoff interview is complete, you simply converse with your AI naturally:
-
Turn a brain dump into content:
"Take these rough call notes and turn them into 1 newsletter and 2 LinkedIn posts using content-engine templates."
-
Prepare for an upcoming meeting:
"Research Acme Corp and generate a 1-page executive brief in research-vault/ using our meeting prep framework."
-
Create a client proposal:
"Draft a 1-page proposal in client-ops/ for a $3,500 automation pipeline based on my notes."
-
Clean a list of leads:
"Run validate_leads.py on leads.csv to clean invalid emails and deduplicate the list."
-
Teach the AI a new rule:
"Remember: never use emojis in cold emails, and keep all subject lines under 4 words."
$\rightarrow$ The AI updatesbrain/memory.mdimmediately.
MIT License. Open source and free for individuals, creators, and teams.