Skip to content

Repository files navigation

🧠 AI Contextualized Infrastructure (ACI)

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.


🎯 Built For Practical Everyday Work

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/, a sponsorships/ tracker, a finance-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 in CLAUDE.md / AGENTS.md.


🧬 Why This Architecture Works: System & Token Economics

Operating AI systems generally follows one of three architectural approaches: single-session chat windows, autonomous agent frameworks, or file-based contextualized infrastructure.

Architectural Comparison: Chat vs. Autonomous Agents vs. ACI

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.

Core Mechanics of the ACI Approach

1. Persistent Context Layer (brain/)

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.

2. Deterministic Offloading (Zero-Token Execution)

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.

3. Map and Territory Retrieval (Lazy Loading)

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.

4. Closed-Loop Failure Recovery and Benchmark Promotion

  • Failure Prevention: When a script breaks or output requires correction, the failure mode is logged to brain/memory.md under ## 🚫 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.

Token & Operational Cost Breakdown

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.


πŸ“š Empirical Research & Theoretical Foundations

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%.

Key Findings & Practical Application

1. Context Saturation and the U-Shaped Attention Curve

  • 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.md acts 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.

2. Deterministic Code Execution vs. Token-Based Arithmetic

  • 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.

3. In-Context Demonstrations over Abstract Prompting

  • 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.

4. Mitigating Cascading Errors and Autonomy Drift

  • 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/ to outputs/ to published/), with key decisions and corrections logged transparently in brain/memory.md and Git diffs.

5. KV-Cache Prefix Reuse Economics

  • 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.

πŸ”¬ The Proof

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.


⚑ Setup

Prerequisites

  • 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/ and email-engine/scripts/ (lead cleaning, web scraping, workspace indexing). Not required just to draft content.
  • Git, to clone the repo.

1. Clone the repository

git clone https://github.com/your-username/ACI.git
cd ACI

2. (Optional) Install Python dependencies

Only needed if you'll run the automation scripts:

pip install -r requirements.txt

3. Copy & Paste the Kickoff Prompt

Open 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.

4. Verify it worked

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:
    python automations/cron/scheduled_tasks.py
    This regenerates brain/workspace_index.md and reports what's pending in each engine's staging folder. Zero errors means the workspace is wired correctly.

πŸ—οΈ Folder Hierarchy & Navigation

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)

πŸ“‹ The Standard 3-Tier Blueprint

Every engine folder β€” including the 8 presets and any custom module you spawn β€” adheres to the same 3-tier structure:

  1. CLAUDE.md / SOP.md (The Mind): Explicit role, phase-by-phase workflow, input/output specifications.
  2. examples/ (The Golden Standard): Few-shot examples of what exceptional output looks like.
  3. 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.


🧭 How ACI Actually Works (Execution Hierarchy)

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:

  1. 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, and brain/rules.md.
  2. Follow the Folder's SOP: It reads that engine's CLAUDE.md/SOP.md and studies examples/ to match the quality bar, before drafting anything new.
  3. 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.


πŸ’‘ How to Work With ACI Day-to-Day

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 updates brain/memory.md immediately.


πŸ“„ License

MIT License. Open source and free for individuals, creators, and teams.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages