时地方
This commit is contained in:
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: "10 Math Books That Sharpen Your Thinking (But Most People Never Finish)"
|
||||
source: "https://x.com/SJosephBurns/status/2047640569451602052"
|
||||
author:
|
||||
- "[[@SJosephBurns]]"
|
||||
published: 2026-04-24
|
||||
created: 2026-04-24
|
||||
description: "Mathematics is one of the few disciplines that can genuinely rewire how you think. Not just about numbers, but about logic, patterns, uncert..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
Mathematics is one of the few disciplines that can genuinely rewire how you think. Not just about numbers, but about logic, patterns, uncertainty, and the hidden structure underneath everyday life.
|
||||
|
||||
The books on this list are not traditional textbooks. They are intellectual workouts that demand active participation. Most people buy them with the best intentions and never get past the first few chapters. If you can read them and understand what they teach, they will sharpen your thinking across multiple areas of life.
|
||||
|
||||
## 1\. Gödel, Escher, Bach: An Eternal Golden Braid by Douglas Hofstadter
|
||||
|
||||
This book is a 700-page journey through mathematics, art, music, and the foundations of artificial intelligence. Hofstadter uses the works of mathematician Kurt Gödel, artist M.C. Escher, and composer Johann Sebastian Bach to explore how complex systems emerge from simple rules.
|
||||
|
||||
The reason it sharpens your thinking is that it trains you to see self-reference and recursion everywhere. The reason most people quit is that the book is playfully dense, and by the midpoint, the logic puzzles become genuinely difficult to untangle.
|
||||
|
||||
## 2\. How to Solve It by George Pólya
|
||||
|
||||
Pólya's classic is widely considered the foundational text on mathematical problem-solving. Rather than teaching formulas, it teaches heuristics, which means it teaches you how to approach a problem you have never seen before.
|
||||
|
||||
The four-step framework in the opening chapter feels straightforward, but the deeper tactical nuances come much later. Most readers assume they've grasped the whole book after the first section, which is exactly where they go wrong.
|
||||
|
||||
## 3\. Calculus by Michael Spivak
|
||||
|
||||
Spivak's Calculus is not what most students encounter in high school. It is a rigorous introduction to mathematical analysis, and it demands that you prove nearly everything from first principles.
|
||||
|
||||
You don't just apply the Chain Rule. You understand why it exists and why it works. The starred problems (marked with asterisks) are intentionally brutal, designed to force hours of deep thinking. Most readers hit those problems and quietly set the book on a shelf where it looks impressive.
|
||||
|
||||
## 4\. How Not to Be Wrong by Jordan Ellenberg
|
||||
|
||||
Ellenberg describes mathematics as a prosthesis for common sense, and this book delivers on that idea with clarity and wit. It applies high-level mathematical thinking to real-world situations, including politics, health, and statistics.
|
||||
|
||||
The opening chapters are accessible and engaging. The middle sections, however, require a level of statistical engagement that surprises many readers who expected a light pop-science read throughout. It rewards those who push through.
|
||||
|
||||
## 5\. Proofs and Refutations by Imre Lakatos
|
||||
|
||||
This book is written as a dialogue between a teacher and students, and it challenges the assumption that mathematics is a clean, finished product. Lakatos shows how mathematical truth is built through a process of trial and error and gradual refinement.
|
||||
|
||||
The dialogue format is intellectually rich but can feel exhausting over time. The detailed historical discussion of Euler's formula for polyhedra is more granular than casual readers expect, and many lose momentum before reaching the book's deeper insights.
|
||||
|
||||
## 6\. Introduction to Mathematical Philosophy by Bertrand Russell
|
||||
|
||||
Russell attempts something ambitious: building mathematics from the ground up using nothing but logic. The result is a book that forces you to question what numbers actually are and what it means for something to exist in a mathematical sense.
|
||||
|
||||
The prose is elegant, but the relentless logical precision requires careful, repeated reading. It's a book you experience in slow motion. Many readers find it deeply rewarding in short doses and overwhelming at length.
|
||||
|
||||
## 7\. The Princeton Companion to Mathematics, edited by Timothy Gowers
|
||||
|
||||
This encyclopedia-style volume maps the entire landscape of modern mathematics. It connects fields like topology, number theory, and logic in ways that reveal how unified the discipline actually is beneath its many branches.
|
||||
|
||||
At over a thousand pages, most readers treat it as a reference rather than a cover-to-cover read. Those who do attempt it systematically tend to develop what mathematicians call mathematical maturity, a broader perspective on how ideas fit together across the field.
|
||||
|
||||
## 8\. Problem-Solving Strategies by Arthur Engel
|
||||
|
||||
Engel's book is the training manual for serious competitors in mathematics competitions. It teaches you to look for invariants, symmetry, and structural patterns in problems that appear completely chaotic on the surface.
|
||||
|
||||
The difficulty curve is steep from the beginning. It's entirely possible to spend several days on a single problem and discover that the official solution is only a few lines long. That gap between effort and elegance is both humbling and instructive.
|
||||
|
||||
## 9\. Thinking Mathematically by John Mason
|
||||
|
||||
This book takes a psychological approach to mathematics. It focuses on what it actually feels like to be stuck on a hard problem and provides practical tools for working through mental blocks rather than around them.
|
||||
|
||||
The book asks readers to engage in regular reflection and written exercises. Most people looking for answers find this process uncomfortable. The irony is that the discomfort is precisely the point, and the readers who engage with it most honestly tend to benefit the most.
|
||||
|
||||
## 10\. Information Theory, Inference, and Learning Algorithms by David J.C. MacKay
|
||||
|
||||
MacKay's book bridges mathematics, physics, and computer science in a way that few texts manage. It explains how information can be quantified and how that framework underlies everything from data compression to machine learning.
|
||||
|
||||
The pace is fast and assumes a strong foundation in probability. Readers who arrive underprepared often fall behind before reaching the chapters on Bayesian inference. Those who arrive ready find it one of the most intellectually satisfying books in the field.
|
||||
|
||||
## Conclusion
|
||||
|
||||
What these ten books share is a refusal to make things easier than they are. They respect the reader enough to present difficulty honestly, and that honesty is exactly what makes them so valuable for anyone serious about sharpening their thinking.
|
||||
|
||||
You don't have to finish all of them to benefit from them. Starting one and pushing past the point where most readers quit is itself a form of intellectual training. The habit of sitting with hard problems, rather than abandoning them, is the real skill these books are teaching.
|
||||
@@ -0,0 +1,216 @@
|
||||
---
|
||||
title: "28 tools under the hood of bot that made $1M on Polymarket"
|
||||
source: "https://x.com/antpalkin/status/2046654122892403188"
|
||||
author:
|
||||
- "[[@antpalkin]]"
|
||||
published: 2026-04-22
|
||||
created: 2026-04-26
|
||||
description: "28 repositories. Six layers. One stack. No gaps. How it works, why it works, and how to make your first $1,000 on Polymarket with same alg..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
28 repositories. Six layers. **One stack. No gaps.** How it works, why it works, and how to make your first **$1,000** on Polymarket with same algo - it’s all in here. Everything you need to build a profitable trading bot on Polymarket - from the brain to the backtest to the production execution layer. **Our patient:**
|
||||
|
||||

|
||||
|
||||
Wallet link: [polymarket.com/@coinman2?r=antopotoshka#RLOep5t](https://polymarket.com/@coinman2?r=antopotoshka#RLOep5t)
|
||||
|
||||
This article is not the story of one wallet. It is a map of the stack. Each tool below closes a specific failure mode that bleeds capital from most prediction-market operators: missing data, missing validation, missing discipline, missing speed.
|
||||
|
||||
## Before you read:
|
||||
|
||||
**→ Bookmark this. You'll need it when you actually start building.** **→ If you want these exact strategies working for you tonight just copy coinman2 trades with this TG bot:** [kreo.app/@cvxv666](https://kreo.app/@cvxv666)
|
||||
|
||||
**→ follow me for more alpha** [@antpalkin](https://x.com/@antpalkin) **→ You'll definitely need a Polymarket account:** [polymarket.com](https://polymarket.com/?r=antopotoshka)
|
||||
|
||||
# Coinman2 - main hero.
|
||||
|
||||
**$1,003,450 PnL. 3,062 predictions. One wallet.**
|
||||
|
||||
The wallet is ["0x55be7aa03ecfbe37aa5460db791205f7ac9ddca3"](https://polymarket.com/@coinman2?r=antopotoshka#RLOep5t) public handle [@coinman2](https://polymarket.com/@coinman2?r=antopotoshka#RLOep5t) on Polymarket. Joined November 2024. Biggest single win on record: $113.8K.
|
||||
|
||||
When traders first saw the growth trajectory on-chain, the initial reaction from crypto Twitter was simple: fake. A seven-figure cumulative PnL from a retail-profile wallet belongs in a Telegram scam group, not in a verifiable on-chain dashboard.
|
||||
|
||||
But the blockchain doesn't lie. Every trade is public. Every settlement is verifiable.
|
||||
|
||||
Developers reverse-engineered the approach within weeks. Then they asked Claude to rebuild it from scratch.
|
||||
|
||||
This piece is about the full tool stack that makes this possible - and what each layer actually does.
|
||||
|
||||
# What Polymarket is and where the edge lives.
|
||||
|
||||
Polymarket is a prediction market. Users trade on outcomes: will Bitcoin be higher in 15 minutes? Will the Fed raise rates? Each contract resolves at $1.00 (correct) or $0.00 (wrong). A contract priced at $0.73 means the market believes there's a 73% chance the "Yes" outcome happens.
|
||||
|
||||
The platform's weekly volume exceeded **$2 billion** in early 2026.
|
||||
|
||||
The key category for automated trading is short-duration crypto contracts - 5-minute and 15-minute BTC and ETH up/down questions. They resolve fast, provide immediate feedback, and have a structural vulnerability.
|
||||
|
||||
Polymarket updates its prices **slower** than the underlying asset moves on Binance. In 2024, that lag averaged **12 seconds**. By Q1 2026, competition had compressed it to **2.7 seconds**.
|
||||
|
||||
**2.7 seconds is an eternity for a machine.**
|
||||
|
||||
That gap - between what Binance knows and what Polymarket still shows is where every strategy in this article lives.
|
||||
|
||||
# The mechanism, step by step.
|
||||
|
||||
A 15-minute BTC contract opens at 50/50. Ten minutes in, Bitcoin drops 0.6% on Binance in 30 seconds. The "real" probability that BTC will be lower at expiry just shifted to roughly 78%. Polymarket still shows 54/46.
|
||||
|
||||
**That's a 24-point edge on a binary contract.** It's not a prediction. The outcome, in a probabilistic sense, has already happened.
|
||||
|
||||
A bot monitoring Binance's WebSocket feed with under 50ms latency sees this immediately. It calculates the discrepancy, sizes a position using **Kelly Criterion**, and executes via **Polymarket's CLOB API**. Two seconds later, the market corrects. The position closes profitable.
|
||||
|
||||
**Repeat 200–500 times per day.**
|
||||
|
||||
That's the coinman2 result. Not magic. Industrial-scale exploitation of a gap that still exists today.
|
||||
|
||||
# Why the gap exists at all.
|
||||
|
||||
Polymarket is a decentralized prediction market. Prices only update when traders actively post orders - there's no dedicated market-making desk refreshing quotes in real time. In the seconds after a Binance move, the "smart" side of the contract has few sellers willing to trade at stale odds.
|
||||
|
||||
The gap has narrowed from 12 seconds to 2.7 seconds as more bots entered. It will continue to narrow. But it hasn't closed. And closing it entirely would require the kind of real-time automated market makers that are, themselves, already the arbitrage bots. **It's an arms race with no obvious end state.**
|
||||
|
||||
# Polymarket API infrastructure.
|
||||
|
||||
Before any AI, you need the raw infrastructure. Polymarket exposes four surfaces:
|
||||
|
||||

|
||||
|
||||
The official Python client, "py-clob-client" (pip install py-clob-client), wraps all of this. Three lines to fetch an order book. Five to place a signed limit order on Polygon (chain ID 137, USDC settlement).
|
||||
|
||||
**Key repos to start with:**
|
||||
|
||||
\- **Polymarket/agents (**[https://github.com/Polymarket/agents](https://github.com/Polymarket/agents)) - Official AI agent framework. Gamma API, CLOB API, and LangChain already wired together. Built-in Chroma vector database for ingesting news sources.
|
||||
|
||||
\- **polyterm** ([github.com/NYTEMODEONLY/polyterm](https://github.com/NYTEMODEONLY/polyterm)) - Terminal dashboard: whale tracker, arbitrage scanner, insider detection, cross-platform comparison vs Kalshi, market risk grading A–F.
|
||||
|
||||
# The stack - layer by layer.
|
||||
|
||||
## LAYER 1 - BRAIN
|
||||
|
||||
**AI reasoning.** The coinman2 bot ran on Anthropic's Claude. In March 2026, a controlled experiment ran Claude against the OpenClaw framework - same starting capital ($1,000), same market conditions, 48 hours.
|
||||
|
||||
**Claude: +1,322% return. OpenClaw: fully liquidated.**
|
||||
|
||||

|
||||
|
||||
Claude reasoning trace - from market context to Kelly-sized order, every decision auditable after the fact.
|
||||
|
||||
Researchers traced the gap to one thing: risk management quality. Claude's generated code included more conservative default parameters, more defensive edge cases, and cleaner error handling. OpenClaw overlevered into a losing sequence and couldn't stop. **Claude** (Anthropic) - Primary strategist. Reasons about market questions, estimates probability vs current price, identifies edge size.
|
||||
|
||||
**Qwen3-Coder** ([github.com/QwenLM/Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder)) - Open source coding LLM. Watches live performance, detects crowded strategies, rewrites modules autonomously.
|
||||
|
||||
**G0DM0D3** ([github.com/elder-plinius/G0DM0D3](https://github.com/elder-plinius/G0DM0D3)) - Uncensored AI interface. Engages with uncomfortable market theses without refusals.
|
||||
|
||||
**Claude Squad** ([github.com/smtg-ai/claude-squad](https://github.com/smtg-ai/claude-squad)) - Runs multiple Claude instances in parallel. One watches politics, one crypto, one sports - all feeding the same engine.
|
||||
|
||||
## LAYER 2 - ORCHESTRATION
|
||||
|
||||
**Making agents do things.** A reasoning engine with no execution layer is just an opinion generator.
|
||||
|
||||

|
||||
|
||||
Bull vs Bear debate resolved by Risk Manager veto - the framework that keeps confident-but-wrong from becoming confident-and-bankrupt.
|
||||
|
||||
**Agency Agents** ([github.com/msitarzewski/agency-agents](https://github.com/msitarzewski/agency-agents)) - Role-based debate: Bull Agent vs Bear Agent vs Risk Manager veto. Consensus determines trade and size.
|
||||
|
||||
**ClaudeAgent OneClick** ([github.com/cvxv666/ClaudeAgentOneClick](https://github.com/cvxv666/ClaudeAgentOneClick)) - One click Claude agent deploy. Persistent 24/7 market watcher in minutes.
|
||||
|
||||
**MiroThinker** ([github.com/MiroMindAI/MiroThinker](https://github.com/MiroMindAI/MiroThinker)) - Mandatory chain-of-thought layer. Bot must justify every position before entry.
|
||||
|
||||
**Superpowers** ([github.com/obra/superpowers](https://github.com/obra/superpowers)) - Extends agents with web access, file ops, arbitrary API calls. Fresh data every decision cycle.
|
||||
|
||||
**TradingAgents** ([github.com/TauricResearch/TradingAgents](https://github.com/TauricResearch/TradingAgents)) - Multi-agent framework: fundamental analyst + technical analyst + sentiment analyst → aggregated signal.
|
||||
|
||||
## LAYER 3 - DATA & MARKET SIGNALS
|
||||
|
||||
**The eyes.** The bot is only as good as what it can see. This layer used to be four tools. Adding macro data, indicator math, and a real-time charting engine brings it closer to a Bloomberg terminal than a script.
|
||||
|
||||

|
||||
|
||||
The edge visualized: Binance-implied probability (blue) vs Polymarket shown (red). The gap between lines is the entire business.
|
||||
|
||||
**OpenBB** ([github.com/OpenBB-finance/OpenBB](https://github.com/OpenBB-finance/OpenBB)) - Open source Bloomberg. 100+ data sources unified: stocks, macro, crypto, options flow, news. The backbone.
|
||||
|
||||
**Dexter** ([github.com/virattt/dexter](https://github.com/virattt/dexter)) - Autonomous deep research. SEC filings, earnings transcripts, analyst reports - two hours of analyst work in seconds.
|
||||
|
||||
**MCP Server** ([github.com/financial-datasets/mcp-server](https://github.com/financial-datasets/mcp-server)) - Financial datasets via MCP protocol. Typed, validated data straight into Claude's context window.
|
||||
|
||||
**Crucix** ([github.com/calesthio/Crucix](https://github.com/calesthio/Crucix)) - On-chain aggregator. Whale wallet movements on Polygon can front-run the visible order book by minutes.
|
||||
|
||||
**fredapi** ([github.com/mortada/fredapi](https://github.com/mortada/fredapi)) - Every macroeconomic dataset the Federal Reserve publishes, free, behind one Python wrapper. CPI, unemployment, yield curves - pipe directly into Claude's context to anchor any macro-related market.
|
||||
|
||||
**Binance Collector** ([github.com/txbabaxyz/mlmodelpoly](https://github.com/txbabaxyz/mlmodelpoly)) - Predicts market direction and computes fair value for short-duration BTC/ETH contracts. The price-discovery half of every latency-arbitrage trade.
|
||||
|
||||
**Polymarket Assistant Tool** ([github.com/FiatFiorino/polymarket-assistant-tool](https://github.com/FiatFiorino/polymarket-assistant-tool)) - Indicator engine that surfaces directional bias on live markets. Translates raw orderbook + price action into a usable signal.
|
||||
|
||||
**lightweight-charts** ([github.com/tradingview/lightweight-charts](https://github.com/tradingview/lightweight-charts)) - TradingView's own charting library. 14k stars, 45KB, free. The fastest path to a production-grade dashboard for monitoring positions and signals in real time.
|
||||
|
||||
## LAYER 4 - MARKET INTELLIGENCE
|
||||
|
||||
**What others have already built.** You don't have to build everything from scratch. An entire ecosystem of Polymarket-specific intelligence and pre-built bots already exists.
|
||||
|
||||

|
||||
|
||||
Whale alerts, leaderboards, signal confluence - the institutional-grade view retail never used to have.
|
||||
|
||||
**Polyscope** ([thepolyscope.com](https://thepolyscope.com/)) - Scans 2,000+ markets. Whale alerts ($5k/$10k/$20k), probability shifts, volume spikes - all to Telegram in real time.
|
||||
|
||||
**Polywhaler** ([polywhaler.com](https://polywhaler.com/)) - [$10k](https://x.com/search?q=%2410k&src=cashtag_click)\+ whale trade tracker. Real-time alerts, insider detection, AI-generated signals.
|
||||
|
||||
**WHALES tracker** (Apify) - Cross-references Gamma + Data + CLOB. Outputs Smart Money Consensus, Health Score, Conviction Score as structured JSON.
|
||||
|
||||
**HyperBuildX bot** ([github.com/HyperBuildX/Polymarket-Trading-Bot](https://github.com/HyperBuildX/Polymarket-Trading-Bot)) - Rust-based, sub-100ms latency. AI ranks copy-trade signals when multiple whales pile into the same market.
|
||||
|
||||
[polymarketanalytics.com](https://polymarketanalytics.com/) **-** Open trader analytics. Top wallet P&L, biggest wins, Kalshi cross-comparison.
|
||||
|
||||
**polyrec** ([github.com/txbabaxyz/polyrec](https://github.com/txbabaxyz/polyrec)) - Real-time terminal dashboard combining Chainlink oracle, Binance feed, and full orderbook depth. 70+ indicators, automatic CSV logging, built-in strategy backtester. The closest thing to an institutional cockpit you can get free.
|
||||
|
||||
**Polymarket-Trading-Bot** ([github.com/dylanpersonguy/Polymarket-Trading-Bot](https://github.com/dylanpersonguy/Polymarket-Trading-Bot)) | 53k lines of TypeScript. Seven prebuilt strategies: arbitrage, momentum, market making, AI forecast, whale copy-trade, convergence, and more. A complete framework - pick a strategy, plug in keys, run. |
|
||||
|
||||
## LAYER 5 - BACKTEST & SIMULATION
|
||||
|
||||
**Prove it before you run it.** This is the layer most retail bots skip - and the reason most retail bots blow up.
|
||||
|
||||
Reasoning models can sound convincing about strategies that have never made money. Whales can be followed into trades that already moved. A signal that worked last month may have been arbitraged out by yesterday. The only defense is running every idea against historical data and simulated execution before a single dollar of real capital touches the CLOB.
|
||||
|
||||

|
||||
|
||||
Every strategy earns its way to production by surviving this report first: 17 months of live record, fees and slippage included, drawdowns visible.
|
||||
|
||||
**prediction-market-backtesting** ([github.com/evan-kolberg/prediction-market-backtesting](https://github.com/evan-kolberg/prediction-market-backtesting)) - Backtests trading strategies against real historical Polymarket and Kalshi data. The first sanity check on any new idea before it sees production.
|
||||
|
||||
**polybot** ([github.com/ent0n29/polybot](https://github.com/ent0n29/polybot)) - Full execution and market-data infrastructure with paper trading. Kafka, ClickHouse, Grafana - the analytics pipeline an institutional desk would build. Reverse-engineered from production strategies.
|
||||
|
||||
## The complete signal flow.
|
||||
|
||||

|
||||
|
||||
World event to execution: under 10 seconds in the ideal world.
|
||||
|
||||
# Human traders vs bots - the data.
|
||||
|
||||
The performance gap between human traders and automated bots using comparable latency arbitrage approaches is documented. Bots generated approximately $206,000 during a tracked period. Humans using the same logic generated roughly $100,000.
|
||||
|
||||
**2× gap. Same market. Same strategy. Same time window.**
|
||||
|
||||
The gap isn't better forecasting. It's execution. Humans make four systematic errors that bots don't:
|
||||
|
||||
\- **Late entries.** By the time a human identifies the Polymarket lag, confirms the Binance move, and places the order manually, the window has often already closed.
|
||||
|
||||
\- **Inconsistent sizing.** Humans oversize when confident, undersize when uncertain — exactly the inverse of Kelly math. Emotional sizing destroys expected value across thousands of trades.
|
||||
|
||||
\- **Fatigue.** A human monitoring 15-minute BTC contracts through an 8-hour session degrades. A bot running for 72 hours makes the same decision at hour 72 that it made at hour 1.
|
||||
|
||||
\- **Drawdown psychology.** After a losing sequence, humans either abandon a working strategy or double down. Both destroy capital. A bot with a hard kill switch does neither.
|
||||
|
||||
# Why now.
|
||||
|
||||
The bots already running have a compounding advantage. The edge exists today. The window is narrowing. The best time to understand this stack was six months ago.
|
||||
|
||||
**The second best time is right now.**
|
||||
|
||||
**If you read this far:**
|
||||
|
||||
\-> **SAVE THIS POST** or you’ll lose every important link. -> **coinman2 bot profile on Polymarket**: [wallet link](https://polymarket.com/@coinman2?r=antopotoshka#RLOep5t) -> If it seems too complicated, **copying the trades of similar bots is also a profitable strategy**. That’s exactly what I do through a TG bot: [kreo.app/@cvxv666](https://kreo.app/@cvxv666) -> **remember:** competition is way weaker than it looks. **99.9%** of people will scream **"too hard"** and call it cap. Only the **0.01%** actually try… **and eat.**
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: "4 minute rule on polymarket: holy grail or trap?"
|
||||
source: "https://x.com/0xbobaaa/status/2036073103281803412"
|
||||
author:
|
||||
- "[[@0xbobaaa]]"
|
||||
published: 2026-03-23
|
||||
created: 2026-04-26
|
||||
description: "imagine this: you analyze 12,000 trades and find a strategy with a 96.83% winrate. sounds like total insanity? - NO these are real data fr..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
imagine this: you analyze 12,000 trades and find a strategy with a 96.83% winrate. sounds like total insanity? - NO these are real data from polymarket prediction markets, and now we’re gonna break down why this is both the coolest and the most useless finding for a regular trader.
|
||||
|
||||
## what’s the strategy?
|
||||
|
||||

|
||||
|
||||
bitcoin on 5 minute candles behaves like a heavy train. once it gets moving, it doesn’t stop right away. that’s called momentum, and that’s exactly what the “4 minute rule” is built on.
|
||||
|
||||
the logic is simple: - you watch the first 4 minutes of the candle - the price kept going up the whole time? you bet up on the 5th minute - the price kept going down the whole time? you bet down and this is where the number magic starts.
|
||||
|
||||
## the numbers that melt your brain
|
||||
|
||||

|
||||
|
||||
based on the analysis of 12,000 trading periods:
|
||||
|
||||
\- 96.83% wins if the price went up for all 4 minutes in a row and you bet up - 95.97% wins symmetrically on the downside - 88.58% if the move exceeded $100 in the first 2 minutes - 92.76% if the move exceeded $200 but these perfect impulse moves do not show up on every candle, so the overall win rate of the full strategy is 78.46%. and the breakeven threshold on polymarket, even with fees included, is only 51.02%. the maximum losing streak across all 12,000 trades was 6 in a row. the maximum drawdown was 0.5%. that is not a typo.
|
||||
|
||||
on paper, this looks almost like a holy grail.
|
||||
|
||||
## when does it work best?
|
||||
|
||||

|
||||
|
||||
the best results come on weekdays. institutional volume makes the moves cleaner and more predictable. the golden hours are 23:00 utc and 09:00 utc. that’s the open and close of major markets.
|
||||
|
||||
## now for the cold shower
|
||||
|
||||

|
||||
|
||||
everything above is true. the stats are honest. but there’s one detail that kills the whole idea for a manual trader.
|
||||
|
||||
95% of that profit has already been taken by bots.
|
||||
|
||||
while you’re looking at the chart and thinking: “oh, it’s been going up for 4 minutes, i should enter” the algorithm already placed the trade in 200 milliseconds.
|
||||
|
||||
that’s the real catch
|
||||
|
||||
bots use latency arbitrage. they see the price move on binance before the chainlink oracle updates the data on polymarket. that’s not cheating. that’s a technological edge bought for millions of dollars.
|
||||
|
||||
now add slippage. try entering with real size and the liquidity will disappear right in front of you. the mathematical edge will burn up together with your deposit.
|
||||
|
||||
and don’t forget the entry window. you have exactly 60 seconds during the 4th minute.
|
||||
|
||||
you vs. hundreds of bots good luck.
|
||||
|
||||
## verdict
|
||||
|
||||

|
||||
|
||||
the “4 minute rule” is a real market anomaly. the numbers do not lie. but without a high frequency bot, it’s just pretty statistics, not a working tool.
|
||||
@@ -0,0 +1,176 @@
|
||||
---
|
||||
title: "5 levels of AI marketing (and how to master each one)"
|
||||
source: "https://x.com/shannholmberg/status/2033596949601865786"
|
||||
author:
|
||||
- "[[@shannholmberg]]"
|
||||
published: 2026-03-15
|
||||
created: 2026-04-26
|
||||
description: "karpathy scored 342 US jobs AI exposure. marketing scored a 9 out of 10.That means everyone in marketing are cooked, but only IF they don´t ..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
karpathy scored 342 US jobs AI exposure. marketing scored a 9 out of 10.
|
||||
|
||||
That means everyone in marketing are cooked, but only IF they don´t take action now.
|
||||
|
||||
and yet, most people using AI for marketing are still copy-pasting ChatGPT outputs that sound like your average washed up LinkedIn influencer.
|
||||
|
||||
```text
|
||||
LEVEL WHAT IT IS
|
||||
─────────────────────────────────────────
|
||||
1 custom prompts
|
||||
2 manual skills
|
||||
3 skills + brand foundation
|
||||
4 agents with skills
|
||||
5 autonomous agent teams
|
||||
─────────────────────────────────────────
|
||||
```
|
||||
|
||||
I built a multi-agent content system over the past few months. not as a side project, as the actual production workflow for my agency. during that process I realized there are five distinct levels to how people use AI for marketing, and almost everyone is stuck at level 1 or 2.
|
||||
|
||||
I will walk you through each level because understanding where you are right now is the fastest way to figure out what to do next.
|
||||
|
||||
## level 1: custom prompts
|
||||
|
||||

|
||||
|
||||
this is where 90% of people start and where most of them stay forever.
|
||||
|
||||
you open ChatGPT. you type "write me an email for my product launch." you get something back that sounds vaguely professional but could have been written for literally any product on earth.
|
||||
|
||||
every session starts from zero, with no memory of your brand, no context about your audience and no knowledge of what worked last time. you are starting a new relationship with a stranger every time you sit down to write.
|
||||
|
||||
**the output at this level is generic because the input is generic.** one line of instruction produces one dimension of output.
|
||||
|
||||
if this is you right now, thats fine. everyone starts here. but staying here is expensive in ways you dont realize yet.
|
||||
|
||||
## level 2: manual skills
|
||||
|
||||

|
||||
|
||||
level 2 is where most "AI-savvy" marketers land. instead of one-line prompts, you build detailed prompt templates packed with frameworks.
|
||||
|
||||
think Schwartz awareness levels baked into your email sequences. proof stacking patterns for landing pages. specific CTA structures tested across hundreds of campaigns.
|
||||
|
||||
a skill at this level is 1,200+ lines of structured framework. Compare that to a simple prompt, the difference in output quality is night and day.
|
||||
|
||||
but you are still running everything manually. every time you want to create something, you open the skill, paste your inputs, run it, and review the output. it´s better than level 1 by a mile, but it still requires you to be the engine.
|
||||
|
||||
**the ceiling here is your time.** you can produce great individual pieces, but you can´t scale because every piece still needs your hands on the keyboard.
|
||||
|
||||
## level 3: skills plus a brand foundation
|
||||
|
||||

|
||||
|
||||
truth is, this is where most people should be spending their time right now. almost nobody is.
|
||||
|
||||
you create a brand foundation file with your voice, your tone, the words you always use. the words you never use. your audience's pain points. your positioning against competitors. the phrases that sound like you versus the phrases that sound like AI slop.
|
||||
|
||||
then your skills reference this foundation automatically. every output passes through your brand filter before it reaches you.
|
||||
|
||||
at level 2, you might produce a great email but it doesnt sound like you. at level 3, everything sounds like you because the system knows who "you" is.
|
||||
|
||||
**one foundation feeds all your skills.** email skill, social media skill, landing page skill, ad copy skill. they all pull from the same source of truth. consistency across every channel without you manually enforcing it.
|
||||
|
||||
this is where your AI content starts scaring your competitors. because it doesnt read as AI anymore. it reads as you, moving at 10x speed.
|
||||
|
||||
## level 4: agents with skills
|
||||
|
||||

|
||||
|
||||
most marketers have never touched this level, and honestly, six months ago neither had I.
|
||||
|
||||
an agent reads your goal, plans the steps, selects the right skills, and executes. one command triggers a full workflow.
|
||||
|
||||
at my agency, I can say "research the top 20 tweets about AI marketing this week, generate 5 content ideas based on what performed, and draft the best one" and the system does it. research agent pulls the data. idea agent structures the concepts. writer agent produces the draft. critic agent scores it before I ever see it.
|
||||
|
||||
the key concept at this level is subagents. these are isolated specialists that run in parallel. the parent agent delegates a task, the subagent executes in isolation, and returns only the distilled results.
|
||||
|
||||
> 3月15日
|
||||
|
||||
as [@akshay\_pachaar](https://x.com/@akshay_pachaar) put it in his article: "subagents are for decomposition." they break a big task into smaller independent pieces. research, writing, editing as separate isolated tasks, fire-and-forget parallelism.
|
||||
|
||||
**one person doing the work of a small team.** the coordination cost drops to zero because you dont need to brief anyone, wait for deliverables, or manage handoffs. the agents just run.
|
||||
|
||||
## level 5: autonomous agent teams
|
||||
|
||||

|
||||
|
||||
very few people are here yet. this is the endgame.
|
||||
|
||||
the difference between level 4 and level 5 is coordination. at level 4, subagents work in isolation. at level 5, agents share context, build on each others outputs, and compound their knowledge over time.
|
||||
|
||||
**agent teams are for coordination.** a team orchestrator reads a shared briefing, distributes tasks, and agents build on each others work. the research agent's findings feed directly into the writer's context. the critic's feedback loops back into the next draft cycle.
|
||||
|
||||
and then there is memory.
|
||||
|
||||
run 1 of your system produces a brand voice document and a first draft. run 5 adds performance data and tighter headlines based on what actually got clicks. run 20 has audience feedback baked in, personalized patterns for different segments, and a track record of what converted versus what bounced.
|
||||
|
||||
the system gets better every time it runs. it learns from engagement data. it adapts to what your audience actually responds to instead of what you think they respond to.
|
||||
|
||||
I know of an 8-person team running 38 agents across 8 departments right now. content, SEO, paid ads, email, social, analytics, CRM, reporting. each department has its own agent cluster, and they all share context through a central knowledge base.
|
||||
|
||||
at this level, AI marketing is infrastructure. Not a tool you open its more like an OS you run.
|
||||
|
||||
but there is a catch.
|
||||
|
||||
## why most people wont do this
|
||||
|
||||
AI-generated ads show a 19% improvement in clickthrough rates. but purchase likelihood drops 33% when consumers know AI created the content.
|
||||
|
||||
"AI slop" mentions went from 461K to 2.4M in a single year, thats a 5x increase in people calling out bad AI content.
|
||||
|
||||
the gap between levels 1-2 and levels 3-5 is taste, judgement & technical skills. the people at levels 1-2 are producing volume. the people at levels 3-5 are producing volume that doesn´t read as AI because they baked their judgment into the system.
|
||||
|
||||
Rick Rubin doesnt play instruments on most of the albums he produces. but every album sounds intentional because his taste shapes every decision. thats the model. you are not the one writing anymore. you are the one deciding what stays, what gets cut, and what gets refined.
|
||||
|
||||
**the moat is taste.** anyone can set up agents, the hard part is having judgment worth adding to them.
|
||||
|
||||
karpathy scored 342 US jobs on a 0-10 AI exposure scale. market researchers scored a 9. writers and editors scored a 9. graphic designers scored a 9. marketing is one of the most exposed professions on the entire list.
|
||||
|
||||
The jobs growing are the ones that require judgment at levels 3-5.
|
||||
|
||||
## your first moves at each level
|
||||
|
||||
**level 1 to level 2:** write three detailed prompt templates for your most common marketing tasks. email sequences, social posts, ad copy. include your frameworks, your constraints, examples of good output. go from a 1-line prompt to a 50-line skill document.
|
||||
|
||||
**level 2 to level 3:** spend two hours writing your brand foundation. voice, tone, audience, positioning, words you never say. then make every skill reference it. this single file will improve every piece of content your AI produces.
|
||||
|
||||
**level 3 to level 4:** pick one workflow you do repeatedly and automate it end-to-end. for me it was the research-to-draft pipeline. identify the steps, build a skill for each one, then connect them through an agent that orchestrates the sequence.
|
||||
|
||||
**level 4 to level 5:** add memory. start logging what performs and what doesnt. feed that data back into your agents. build a shared context layer that all your agents can read from.
|
||||
|
||||
## the cost
|
||||
|
||||
```text
|
||||
TRANSITION TIME EFFORT
|
||||
─────────────────────────────────────────────────
|
||||
1 → 2 an afternoon write 3 detailed prompt templates
|
||||
2 → 3 a weekend build your brand foundation doc
|
||||
3 → 4 1-2 weeks automate one full workflow
|
||||
4 → 5 ongoing compounds every month
|
||||
─────────────────────────────────────────────────
|
||||
ROI: exponential. levels 3-5 pay back daily.
|
||||
```
|
||||
|
||||
level 1 to 2 takes an afternoon. maybe 3-4 hours of writing detailed prompts.
|
||||
|
||||
level 2 to 3 takes a weekend. the brand foundation document is the hard part because it forces you to articulate things about your voice that you have never written down.
|
||||
|
||||
level 3 to 4 takes 1-2 weeks of building and testing, depending on how complex your workflow is.
|
||||
|
||||
level 4 to 5 is ongoing. the system compounds over months. this is not a project you finish, its an infrastructure you maintain.
|
||||
|
||||
**the ROI curve is exponential though**. the time you invest at levels 3-5 pays back every day after that. your system runs while you sleep, and it compounds what it learned from last week into this weeks output.
|
||||
|
||||
## the window
|
||||
|
||||
right now, operating at level 3 or above puts you in a tiny minority. most agencies and most marketers are still at level 1, maybe level 2. the ones who build their systems now will have compounding advantages that late adopters cant catch up to.
|
||||
|
||||
because the advantage isn´t just speed, but accumulated taste, judgment, and months of memory that a competitor starting from scratch doesn´t have.
|
||||
|
||||
every week you wait is a week of compounding you don´t get back.
|
||||
|
||||
I´ve been documenting exactly how I built my systems from level 1 through level 5. if this was useful, save this, drop a like and follow along. im breaking down each level in detail over the coming weeks.
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: "A Framework for Frontier AI and the Dawning of a New Age"
|
||||
source: "https://x.com/demishassabis/status/2076957440109625718"
|
||||
author:
|
||||
- "[[@demishassabis]]"
|
||||
published: 2026-07-14
|
||||
created: 2026-07-16
|
||||
description: "This is a pivotal moment in human history. Artificial General Intelligence (AGI), a system that exhibits all the cognitive capabilities the ..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
This is a pivotal moment in human history. Artificial General Intelligence (AGI), a system that exhibits all the cognitive capabilities the brain has, is probably only a few short years away. When we look back on this time in the decades to come, I think we will realise we were standing in the foothills of the singularity - nothing less than the dawning of a new age for humanity.
|
||||
|
||||
I’ve spent my whole life working on AGI because I’ve always had a deep conviction that, if built and deployed responsibly, it would prove to be one of the most beneficial and transformative technologies ever invented. AGI cannot be compared to standard technological breakthroughs, not even ones as consequential as the internet or mobile - it is much more akin to the discovery of electricity or fire. If you stop to think about it, we’ve essentially found a way to make sand think. It’s miraculous.
|
||||
|
||||
The magnitude of this technology’s impact will be unprecedented, perhaps 10x of the Industrial Revolution at 10x the speed. It will help us solve some of the biggest problems society faces from accelerating drug discovery to developing new clean energy sources to creating novel advanced materials. We could even reach a point where resources are no longer the limiting factor for human progress, leading to an amazing new era of abundance.
|
||||
|
||||
## The Challenges of the Frontier
|
||||
|
||||
AI is already starting to deliver real-world benefits but to realise its immense promise, we have to navigate this critical period of development thoughtfully and carefully. Urgent action is needed to address risks that might arise as we get closer to AGI. We’ve already seen the challenges frontier models pose for cybersecurity, and other threats including nuclear and bio risks may soon emerge as capabilities continue to advance. On the horizon, we will need robust safeguards to maintain control of increasingly agentic, recursively self-improving systems - and tackle unknown issues that will only become clearer over time.
|
||||
|
||||
I’ve always believed in the power of human ingenuity and creativity to solve any problem. I’m confident that mitigating the technical risks related to AI is a challenge we can collectively address, but only if we give ourselves the time and space to get this next crucial step right. Currently, as a field and as a wider society, we aren’t doing that.
|
||||
|
||||
At the moment, we are locked in an extremely intense, multilayered commercial and geopolitical race. While these competitive dynamics fuel rapid progress and accelerate the incredible upsides, advances on the frontier are outpacing our understanding of the technology. Nobody in the world knows for sure what is going to happen from here, and even the experts disagree. When there is a large degree of uncertainty and the stakes are this high, proceeding with cautious optimism is the sensible and correct strategy. That calls for public policy that promotes innovation while also incentivising responsibility and security, fosters international collaboration on key safety issues, and encourages careful consideration of how AI is deployed for the benefit of society.
|
||||
|
||||
## A Framework for a Frontier AI Standards Body
|
||||
|
||||
The rapid progress we’re seeing in AI requires a new approach to testing frontier AI model capabilities that is dynamic, adaptable, and rigorous. The US is well positioned, given its economic and technical standing, to take the first step in developing such a framework. It could establish a new Standards Body modelled on a federally overseen public-private partnership or self-regulatory organisation, much like the Financial Industry Regulatory Authority (FINRA), with a board that includes independent leading technical experts and open-source representatives. Funding would need to be substantial and likely mostly come from industry, in order to attract world-class technical talent and provide the necessary compute resources for large-scale testing.
|
||||
|
||||
The Standards Body would be responsible for developing assessment protocols and working with appropriate federal agencies and the US National Labs to conduct testing in areas relevant to national security. A model would qualify as ‘Frontier-class’ if it meets certain thresholds on a set of benchmarks determined by the Standards Body and regularly updated to keep pace with evolving AI capabilities. Organisations with ‘Frontier Models’ as defined by those benchmarks would be deemed ‘Frontier Labs’, and be encouraged to adopt best practices, such as publishing model cards with technical details, maintaining strong internal cybersecurity, vetting key personnel, and providing sufficient resourcing for safety and security research, and more.
|
||||
|
||||
Initially, Frontier Labs would voluntarily share models with the Standards Body for review up to 30 days before release. Once the assessment protocol is shown to be effective and robust, formalisation could quickly follow, meaning that Frontier Models would be required to pass it to be deployed in the US market. Labs would also work with the Standards Body to address any critical post-release vulnerabilities.
|
||||
|
||||
Model assessments should include rigorous scientific evaluations of capabilities in cybersecurity, biological threats and other high-risk domains. Specific agentic AI tests could look for attempts to bypass safety guardrails or signs of deception, and ensure best practices, such as digitally watermarking AI-generated images and generating human-readable output tokens to understand model reasoning.
|
||||
|
||||
These evaluations would be regularly updated, perhaps quarterly to start, with outdated or saturated benchmarks being deprecated and replaced. Initially, they would be developed in consultation with Frontier Labs, but eventually the Standards Body should build up the technical capacity to create its own held-out tests independent of the Labs to prevent overfitting. Working with the US government, it could promote an ecosystem of third-party auditors to help with the assessments and development of new benchmarks and evaluations.
|
||||
|
||||
The strength of this approach is it would be technically focused, while at the same time supporting innovation and incentivising responsible behaviour. It is designed to keep up with the field’s acceleration and adapt to the biggest risks as they are identified, and could be ratcheted up if the seriousness of the situation demands, including coordinating a slowdown in development among the Frontier Labs if deemed necessary. Being designated a Frontier Lab would carry significant prestige and be open to any organisation by building models that meet the benchmark criteria. The framework could apply to Frontier-class models no matter their country of origin or whether they are open or closed, but any non-frontier models, say from startups or academia, would be exempt from this process.
|
||||
|
||||
This US-initiated effort would provide a strong starting point for creating shared international standards on Frontier AI. Since this technology is going to affect the entire planet, ideally this framework would spur the international community to reach a consensus on how to manage the most serious risks while ensuring everyone has access to and can benefit from the opportunities that AI brings.
|
||||
|
||||
## The Future Is Not Yet Written
|
||||
|
||||
AGI has the potential to be the ultimate tool for advancing science and medicine, and to drive enormous productivity gains and economic growth. But in order to achieve this, we need to get the technical foundations right by coordinating around a shared global framework, using the most rigorous scientific methods, and bringing the best minds together to work on the challenges we face.
|
||||
|
||||
Even if we solve these hard technical challenges, there will be further complex economic and philosophical questions to tackle: what sorts of new economic models will be needed to help everyone thrive in a post-scarcity world? What values do we want to live by, what will meaning and purpose be, and how might even the human condition itself change? Resolving these questions obviously cannot and should not be left to technologists alone. It requires every part of society to come together to help define this new chapter.
|
||||
|
||||
There is both huge excitement and uncertainty around AI, and both are warranted. But the future is not yet written, we must use this precious window before AGI arrives to shape this technology for the benefit of all humanity. What we collectively do now will determine how the next phase of civilisation unfolds. By safely stewarding AGI into the world, we can enter a new golden age of scientific discovery and progress, and usher in a bright future of incredible human flourishing.
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
title: "A Practical Guide to Paying Down Tech Debt with Agents"
|
||||
source: "https://x.com/dabit3/status/2047355555895763205"
|
||||
author:
|
||||
- "[[@dabit3]]"
|
||||
published: 2026-04-24
|
||||
created: 2026-04-24
|
||||
description: "Most engineering teams carry a backlog of technical debt they plan to pay down. It tends to grow rather than shrink because paying it down c..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
Most engineering teams carry a backlog of technical debt they plan to pay down. It tends to grow rather than shrink because paying it down competes with feature work for the same engineering hours, and features usually take priority.
|
||||
|
||||
At [@cognition](https://x.com/@cognition), we're seeing teams use [@DevinAI](https://x.com/@DevinAI) to run implementation-heavy debt work alongside the roadmap while reducing the amount of engineer time required for scoping, coding, and review. The rest of this post covers what this looks like in practice and how to put these workflows to into action on your own backlog.
|
||||
|
||||
## Why Debt Accumulates
|
||||
|
||||
Debt items are almost always the first to get cut when priorities exceed capacity, because addressing each one means a human engineer has to stop working on something more urgent.
|
||||
|
||||
Tools like linters, SonarQube, and Dependabot reduce the cost of identifying debt, but fixing it still falls back on a human. Engineers spend less than 20% of their time writing code to begin with, which keeps the pool of hours available for debt work small and contested.
|
||||
|
||||
# How Cloud Agents Add Capacity
|
||||
|
||||
By cloud agent, I mean an autonomous coding agent that can check out a repo, inspect code, make changes, run tests, and open PRs from its own cloud environment.
|
||||
|
||||
A cloud agent adds to the team's total capacity from outside the existing pool. It runs in its own isolated environment on its own schedule, triggered by an API call or webhook, a Linear or Jira ticket, a cron job, or a Slack message. It can run overnight, in parallel across many sessions, or on a recurring schedule without anyone initiating each run.
|
||||
|
||||
## Four capabilities matter most for debt work.
|
||||
|
||||
**Autonomy** lets the agent run in its own cloud environment without anyone at the keyboard. Teams start sessions and come back to completed PRs, regardless of whether anyone is online.
|
||||
|
||||
**Parallelism** lets a team run many agent sessions at once.
|
||||
|
||||
**Scheduling** lets debt work run on its own cadence, whether that's daily triage, weekly maintenance, or one-time cleanups tied to specific events.
|
||||
|
||||
**Long horizons** let the agent work across dozens of sessions on the same project, maintaining state and adapting to what each session reveals. Modernization work that requires a coherent multi-week effort becomes tractable because the agent doesn't get pulled onto other work midway.
|
||||
|
||||
## Patterns
|
||||
|
||||
The patterns below describe debt work that teams are now running through cloud agents.
|
||||
|
||||
**Run large-scale migrations**. Give the agent a single prompt that asks it to scope the surface area, propose conflict-free work packages, and launch one parallel session per package, all following a shared playbook to keep output consistent. PRs merge over the following days. Works for migrations like JavaScript to TypeScript, REST to GraphQL, MongoDB to Postgres, or Angular 16 to 18.
|
||||
|
||||
**Keep dependencies current.** Set up a weekly scheduled session that runs every Monday. Patch and minor bumps get batched into a single PR with test results attached. Each major-version bump opens as its own PR with breaking-change notes from the changelog and the required compatibility edits already applied. Engineers only engage with the cases that need judgment.
|
||||
|
||||
**Retire feature flags on schedule.** On the day a flag ships, schedule a one-time session for 30 days later. When the date arrives, the session traces every usage of the flag, keeps the enabled path, deletes the disabled path, updates the tests, and opens a PR with a summary of what was removed.
|
||||
|
||||
**Fill test coverage in batches.** Prompt the agent to find the lowest-coverage modules and dispatch one parallel session per module, each writing tests until the module crosses an 80% line-coverage threshold. Eight sessions run overnight and take a codebase from 44% to 68% coverage in one cycle.
|
||||
|
||||
**Triage production errors daily.** Set up a daily scheduled session with an integration to Sentry. It pulls the top unresolved errors, fetches stack traces and breadcrumbs, locates the relevant files in the repo, identifies the root cause, and opens a targeted fix PR with a regression test for each. Long-tail errors that wouldn't otherwise clear the bar for a sprint ticket get addressed as part of the same pass.
|
||||
|
||||
**Catch design system drift.** Run a daily scheduled session that scans merged PRs, flags hardcoded hex values, missing spacing tokens, and one-off components that duplicate the shared library, and opens auto-fix PRs against each one.
|
||||
|
||||
**Split up monolithic files.** Kick off an ad-hoc session from Slack, an IDE, or the agent's web UI with a prompt describing the target structure. A 2,000-line Express router gets broken into per-domain route files, shared middleware gets extracted into its own module, the original URL paths stay identical, and the existing test suite verifies the refactor. The work lands as one PR over the weekend.
|
||||
|
||||
**Sync docs with code.** Run a daily scheduled session that diffs yesterday's merged PRs against the docs repo and opens corrective PRs for renamed endpoints, deprecated options, and features that now behave differently than they used to.
|
||||
|
||||
**Investigate bug reports automatically.** Apply a label to a Linear, Jira, or GitHub issue to trigger an agent session that attempts to reproduce the issue in a browser, attaches a screen recording and steps-to-reproduce, and posts the reproduction back on the ticket.
|
||||
|
||||
## Prevention
|
||||
|
||||
These patterns clear existing debt and also prevent new debt from forming. Agent-run PR review pushes this upstream. Bugs, standards violations, and missing tests get caught and fixed in the PR itself.
|
||||
|
||||
Once these cadences are in place, debt maintenance runs as a standing process rather than periodic cleanup.
|
||||
|
||||
## Economics
|
||||
|
||||
Work that never cleared the priority bar clears it now because it no longer competes for engineer-hours, and deciding what to address becomes a scoping question: which debt has clear enough success criteria to hand off to an agent, and which still needs human attention.
|
||||
|
||||
## Try it
|
||||
|
||||
Most teams start with weekly dependency updates or daily Sentry triage. Both land fast and build trust. Try Devin at [devin.ai](https://devin.ai/).
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,408 @@
|
||||
---
|
||||
title: "AI Knowledge Layer (and why your agents are useless without it)"
|
||||
source: "https://x.com/shannholmberg/status/2044111115878326444"
|
||||
author:
|
||||
- "[[@shannholmberg]]"
|
||||
published: 2026-04-03
|
||||
created: 2026-04-26
|
||||
description: "this article gives you a two-layer system that makes every AI agent you run smarter. 20 minute setup, gets better every day, fully open sour..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
this article gives you a two-layer system that makes every AI agent you run smarter. 20 minute setup, gets better every day, fully open source.
|
||||
|
||||
karpathy recently talked about shifting most of his token spend from code to knowledge management.
|
||||
|
||||
the post resonated because it named a problem everyone feels: your agents don't know you. every conversation starts from zero. you re-explain your business, your voice, your goals, your context, and the output is generic because the input has no memory.
|
||||
|
||||
I took his pattern, tested multiple approaches over two weeks, simplified it down to the one that works, and loaded it with my own data. notes, ideas, tweets, articles, bookmarks. the agent compiled 230+ structured wiki pages from that, cross-linked with concepts, entities, and sources I can query anytime.
|
||||
|
||||

|
||||
|
||||
this article covers what the knowledge layer is, how to build one for content creation, for a company, and for your personal life. the framework is open source and the setup takes 20 minutes.
|
||||
|
||||
> 4月3日
|
||||
>
|
||||
> LLM Knowledge Bases Something I'm finding very useful recently: using LLMs to build personal knowledge bases for various topics of research interest. In this way, a large fraction of my recent token throughput is going less into manipulating code, and more into manipulating
|
||||
|
||||
## what is the AI knowledge layer
|
||||
|
||||
the AI knowledge layer is the infrastructure that sits between you and your agents. it's what they read before they do anything. without it, they guess. with it, they know.
|
||||
|
||||
it has two parts:
|
||||
|
||||
1. **the knowledge base layer (KBL)** is dynamic. you dump raw sources into a folder: tweets, articles, bookmarks, PDFs, notes, voice memos. an AI agent reads all of it, classifies each source by type, builds structured wiki pages with cross-references, and maintains a master index with one-line summaries for fast scanning. every question you ask gets filed back as a new page. the wiki gets richer over time.
|
||||
2. **the brand foundation (BF)** is static. this is the layer only you edit. your voice rules, your visual style, your positioning, your audience definition, the words you never use. agents read it before producing anything, but they never rewrite it. it's the anchor that keeps everything sounding like you even when agents do the work.
|
||||
|
||||
here's how the two layers sit in the system:
|
||||
|
||||
```text
|
||||
+-------------------------------------------------------+
|
||||
| YOUR AGENTS |
|
||||
| (writer, researcher, strategist, analyst) |
|
||||
+---------------------------+---------------------------+
|
||||
| reads from | reads from
|
||||
v v
|
||||
+------------------+ +-------------------+
|
||||
| KNOWLEDGE BASE | | BRAND FOUNDATION |
|
||||
| LAYER (KBL) | | (BF) |
|
||||
| | | |
|
||||
| dynamic | | static |
|
||||
| agent-maintained| | human-edited |
|
||||
| grows over time | | your voice, your |
|
||||
| wiki pages, | | rules, your |
|
||||
| sources, index | | positioning |
|
||||
+--------+---------+ +-------------------+
|
||||
|
|
||||
compiles from
|
||||
|
|
||||
+--------+---------+
|
||||
| raw/ inbox |
|
||||
| tweets, articles |
|
||||
| bookmarks, PDFs |
|
||||
| notes, ideas |
|
||||
+-------------------+
|
||||
```
|
||||
|
||||
**why not RAG?** RAG re-derives answers at query time by chunking documents and searching. the knowledge layer compiles once, cross-references, and keeps current. at around 100 articles, karpathy found the compiled approach outperforms RAG for Q&A. graphify measured **71.5x fewer tokens per query compared to searching raw files.**
|
||||
|
||||
the evolution went in three phases:
|
||||
|
||||
1. one-shot RAG (2020-2023)
|
||||
2. agentic RAG with multi-hop retrieval (2023-2024)
|
||||
3. and now context engineering where the agent builds its own context from multiple sources (2025+). the knowledge layer is the infrastructure for that third phase.
|
||||
|
||||

|
||||
|
||||
## why most people won't build one
|
||||
|
||||
the same reason most people won't meal prep on Sunday. it takes an hour of upfront work to save ten hours over the week. most people would rather complain about bad AI output than spend 20 minutes setting up the system that fixes it.
|
||||
|
||||
90% of people using AI are doing the same thing right now: prompting, accepting, shipping. with no judgment and no taste.
|
||||
|
||||
the knowledge layer is how you leave that 90%. it encodes your taste, your data, your patterns so agents produce output that sounds like you wrote it instead of something that could be on any AI slop.
|
||||
|
||||

|
||||
|
||||
the friction is real though, you need to curate what goes in. if something doesn't feel 80%+ relevant to what you're working on, skip it.
|
||||
|
||||
high-signal inputs make the output better. fill it with noise and you get noise back.
|
||||
|
||||
## for content creators and personal brands
|
||||
|
||||
this is where I started. I run an AI marketing content account and an agency, and I needed my agents to know what I've written, what performed, and what my voice sounds like.
|
||||
|
||||
I built a framework called LLM Wikid and open sourced it (learn how to implement it further down). here's what happened when I loaded my own data:
|
||||
|
||||
- I started by sitting down and writing out everything on my mind: notes on projects I'm running, half-formed product ideas, observations about what's working in my niche, thoughts on where AI marketing is headed. raw thinking, no focus on structure.
|
||||
- then I dumped my X archive (87 tweets from 6 weeks), three published articles, and all my bookmarks. the agent processed everything and turned it into 15 themed source pages, 14 concept pages, 11 entity pages, with 100+ cross-links between them.
|
||||
- I then pulled 197 bookmarks via the X API, the agent downloaded 81 images and transcribed 49 videos from those bookmarks, analyzed the visual content, and wove it all into the wiki. my notes, my ideas, my tweets, my bookmarks, my articles, all connected and searchable.
|
||||
|
||||

|
||||
|
||||
image of my Obsidian graph
|
||||
|
||||
## the two layers in practice
|
||||
|
||||
**the KBL (knowledge base layer) holds everything that grows:** sources classified by type (transcript, article, tweet, paper), cross-referenced with wikilinks, indexed with TLDRs.
|
||||
|
||||
when I need to write about a topic, I run /wiki-query and get a cited answer from my own data. that answer gets filed back as a new page, so the next query is richer.
|
||||
|
||||
the folder structure looks like this:
|
||||
|
||||
```markdown
|
||||
my-wiki/
|
||||
raw/
|
||||
clippings/ # obsidian web clipper drops here
|
||||
ideas/ # notes, brainstorms, half-formed thoughts
|
||||
bookmarks/ # saved tweets, threads, tools
|
||||
articles/ # your own published content
|
||||
papers/ # PDFs, research
|
||||
x-archive/ # your X/Twitter export
|
||||
assets/images/ # downloaded media from sources
|
||||
wiki/
|
||||
index.md # master index with TLDRs
|
||||
log.md # append-only changelog
|
||||
concepts/ # ideas, frameworks, topics
|
||||
ai-marketing.md
|
||||
distribution-moat.md
|
||||
entities/ # people, companies, tools
|
||||
karpathy.md
|
||||
claude-superpowers.md
|
||||
sources/ # one summary per raw source
|
||||
graphify-2026.md
|
||||
outputs/ # filed answers to queries
|
||||
sops/ # repeatable processes
|
||||
syntheses/ # cross-cutting analysis
|
||||
templates/ # page type starters
|
||||
CLAUDE.md # the schema that controls everything
|
||||
```
|
||||
|
||||
notice the clippings/ folder at the top of raw/. that's where Obsidian Web Clipper drops everything.
|
||||
|
||||
you install the browser extension, and whenever you're browsing X, reading an article, checking a GitHub repo, or scrolling Reddit, you clip it with one click. it saves to raw/clippings/ with the source URL in the frontmatter.
|
||||
|
||||
<video preload="auto" tabindex="-1" playsinline="" aria-label="嵌入式视频" poster="https://pbs.twimg.com/tweet_video_thumb/HF4LUKKasAUwCeh.jpg" src="https://video.twimg.com/tweet_video/HF4LUKKasAUwCeh.mp4" type="video/mp4" style="width: 100%; height: 100%; position: absolute; background-color: black; top: 0%; left: 0%; transform: rotate(0deg) scale(1.005);"></video>
|
||||
|
||||

|
||||
|
||||
GIF
|
||||
|
||||
next time you run /wiki-ingest, the agent reads the URL, detects what type of source it is (tweet, article, PDF, video), sorts it to the right subfolder, fetches the full content, downloads any images, and compiles it into the wiki.
|
||||
|
||||
you clip during the day, ingest processes it overnight, you wake up to a richer knowledge base.
|
||||
|
||||
**the BF (brand foundation) holds what stays constant:** my AI tells document (a list of every banned word, phrase, and structure that flags as AI), my visual content style guide (terminal screenshots over beautiful backgrounds, color-coded flowcharts), and my voice profile. every agent reads these before producing anything.
|
||||
|
||||
## how agents plug into this
|
||||
|
||||
a writer agent reads the brand foundation for voice, queries the wiki for topic research, and checks content performance data to pick the right format.
|
||||
|
||||

|
||||
|
||||
a researcher agent monitors X, Reddit, YouTube for signals, feeds new sources into the raw folder, and expands wiki topics. a content strategist cross-references what's performing in the niche against existing coverage and identifies gaps.
|
||||
|
||||

|
||||
|
||||
**each agent is only as good as the knowledge layer it reads from.**
|
||||
|
||||
the same agent with a thin knowledge base produces slop. the same agent reading 200+ structured wiki pages with your voice, your data, and your performance history produces work that sounds like you.
|
||||
|
||||
I tested this directly. Helena, an AI marketing tool, can analyze a brand from a URL alone and produces accurate brand voice profiles. but the content it generates from that analysis was, in my experience, "a whole month of marketing slop in a minute." brand analysis alone isn't enough. you need the knowledge layer on top of it.
|
||||
|
||||
> 3月31日
|
||||
>
|
||||
> honest first impression of Helena, the "autonomous AI marketer" you start by giving it your website URL and it fetches your brand, analyzes competitors, and generates a full brand knowledge base. the brand read was accurate it generates all of this from your URL alone: > brand
|
||||
|
||||
## how this maps to the 5 levels of ai
|
||||
|
||||
this connects to the 5 levels of AI marketing I wrote about earlier:
|
||||
|
||||
- level 1: custom prompts (no knowledge layer)
|
||||
- level 2: manual skills (thin knowledge layer)
|
||||
- level 3: skills + brand foundation (BF layer added)
|
||||
- level 4: agents with skills reading from compiled knowledge (KBL + BF working together)
|
||||
- level 5: autonomous agent teams with full compounding knowledge layer
|
||||
|
||||
most people sit at level 1 or 2. the knowledge layer is what gets you to 4 and 5.
|
||||
|
||||
> 3月17日
|
||||
|
||||
## the distribution angle
|
||||
|
||||
vibe coding solved building. everyone can ship an app in 48 hours. distribution is still hard.
|
||||
|
||||
the knowledge layer is how you compound distribution intelligence. every content insight you capture, every bookmark you analyze, every performance metric you track makes the next piece of content better-targeted.
|
||||
|
||||
a scheduled trigger runs ingest every morning on whatever you clipped the day before. your distribution gets smarter while you sleep.
|
||||
|
||||
there's also a service angle. setting up someone's knowledge layer is a $1,500-3,000 service with a $300-500 monthly retainer.
|
||||
|
||||
ten clients is $56,800 in year one. if you're a content creator or agency owner, this is a productizable skill.
|
||||
|
||||
## for companies and projects
|
||||
|
||||
the same architecture works at company scale.
|
||||
|
||||
the difference is that multiple people's agents read from and write to the same knowledge layer, and the layer holds operational knowledge, not just content knowledge.
|
||||
|
||||

|
||||
|
||||
we run this at [@EspressioAI](https://x.com/@EspressioAI) and at [@LunarStrategy](https://x.com/@LunarStrategy). at Espressio, the knowledge base holds client delivery patterns, agent architecture templates, and internal SOPs.
|
||||
|
||||
at Lunar Strategy, it holds campaign playbooks, client research, and content frameworks. new team members point their agent at the knowledge base and they're productive from day one instead of spending weeks learning the undocumented way things work.
|
||||
|
||||
Eric Osiu rolled out something similar across his entire company. every employee has a role-tuned AI agent connected to a shared central brain. his framing:
|
||||
|
||||
> "a personal assistant has a ceiling. the unlock is role-tuned agents sharing context through a central brain."
|
||||
|
||||
when sales closes a deal, the account manager's agent already has the handoff. when content performs, the sales agent adjusts outreach angles automatically.
|
||||
|
||||

|
||||
|
||||
screenshot from Erics article, credits to him.
|
||||
|
||||
no information falls through cracks because the knowledge layer catches everything.
|
||||
|
||||
> 4月9日
|
||||
|
||||
## how it scales
|
||||
|
||||
one person (personal wiki) to small team (5-10 people sharing one knowledge base) to organization (50+ people with role-tuned agents reading from compiled intelligence). the pattern is the same at every level:
|
||||
|
||||
1. raw sources go in
|
||||
2. agents compile structured pages
|
||||
3. cross-references build automatically
|
||||
4. humans validate through exploration gates (every page starts as unreviewed, only a human marks it as confirmed)
|
||||
5. git syncs everything so the knowledge is version-controlled and reversible
|
||||
|
||||
Cody Schneider built a 10-capability GTM agent swarm for local service businesses.
|
||||
|
||||
> 4月11日
|
||||
>
|
||||
> AI agents for marketing are here and it's gonna totally change how you're gonna grow your business and I'm going to show you how to build your first marketing agent with Hermes in the next 10 minutes These basically fully functioning employees that you can delegate work to
|
||||
|
||||
the foundation of his system is a data warehouse holding all business data. his words:
|
||||
|
||||
> "without it, agents can't make good decisions."
|
||||
|
||||
he calls it a data warehouse.
|
||||
|
||||
Eric Osiu calls it a shared brain. karpathy calls it an LLM wiki.
|
||||
|
||||
**the name doesn't matter. agents need compiled, structured knowledge to do useful work.**
|
||||
|
||||
the extreme version of this is what Greg Isenberg calls "ambient businesses," companies that run primarily on agents where the owner checks in every few days.
|
||||
|
||||

|
||||
|
||||
Medvi is the proof: $1.8 billion revenue run rate, 2 employees, zero VC. AI handles code, creative, voice, customer service. the knowledge layer is the prerequisite. without it, agents need constant human direction. with it, they operate from compiled organizational intelligence.
|
||||
|
||||
> 4月3日
|
||||
>
|
||||
> The NYT just profiled a $1.8B revenue company with 2 employees. Medvi is a telehealth GLP-1 provider built by Matthew Gallagher, 41, from his house in LA. He launched in September 2024 with $20,000. Here are the numbers: Month 1: 300 customers Month 2: 1,300 customers 2025 full
|
||||
|
||||
## for your personal life
|
||||
|
||||
the most underrated use. the same system that tracks your content performance can track your thinking.
|
||||
|
||||
journal entries, book notes, podcast highlights, health metrics, goal reviews, random ideas at 2am.
|
||||
|
||||
all of it goes into raw/. the agent compiles it into structured pages.
|
||||
|
||||
when you ask "what patterns do I see in my energy levels" or "what did I learn about productivity last quarter," you get a cited answer from your own data. that answer gets filed back, so the next question is smarter.
|
||||
|
||||
**the compound loop:** every question you ask makes the system richer. every source you add creates new connections. your curiosity feeds back into the quality of answers you get.
|
||||
|
||||
quality controls matter here more than anywhere because this is where blind trust in AI is most dangerous:
|
||||
|
||||
bias checks force counter-arguments and data gaps on every page. if you dump in 10 articles that all say the same thing, the wiki will note it but also flag what's missing from the picture.
|
||||
|
||||
the validation gate means every AI-generated page starts with explored: false. only you can mark something as reviewed. you always know what's been human-verified and what hasn't.
|
||||
|
||||
confidence levels tag every page as high, medium, low, or uncertain. the agent has to be honest about how well-supported its knowledge is.
|
||||
|
||||
**the 80/20 rule from my three moats article applies directly here:** let AI do 80% of the organization, compilation, and cross-referencing. apply your taste to the last 20%, the curation, the validation, the connections only you can see. the knowledge layer is how you encode your taste so the 80% gets better over time.
|
||||
|
||||

|
||||
|
||||
## the 20-minute setup guide
|
||||
|
||||
this is not theoretical. the framework is open source and the setup is fast.
|
||||
|
||||
**step 1: clone the repo (2 minutes)**
|
||||
|
||||
```markdown
|
||||
git clone https://github.com/shannhk/llm-wikid.git my-wiki
|
||||
cd my-wiki
|
||||
```
|
||||
|
||||
open the folder as an Obsidian vault.
|
||||
|
||||
**step 2: run your agent (3 minutes)**
|
||||
|
||||
open Claude Code (or any agent that reads markdown and runs bash) in the folder. it reads CLAUDE.md, which is the schema that controls everything:
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md (simplified)
|
||||
## Directory Structure
|
||||
- raw/ → messy inbox, dump anything here
|
||||
- wiki/ → compiled pages, flat structure
|
||||
- wiki/index.md → master index with TLDRs
|
||||
## Operations
|
||||
- /wiki-ingest → process raw/ into wiki pages
|
||||
- /wiki-query → ask questions, get cited answers
|
||||
- /wiki-explore → browse and validate pages
|
||||
- /wiki-lint → catch contradictions, stale content
|
||||
```
|
||||
|
||||
the agent reads this file, understands the full schema, and scaffolds the wiki structure automatically.
|
||||
|
||||
**step 3: fill it up (10 minutes)**
|
||||
|
||||
- request your X archive from settings.
|
||||
- grab the Obsidian Web Clipper extension and start clipping tweets, articles, threads worth keeping.
|
||||
- sit down and write out everything on your mind for 10 minutes. dump your bookmarks in. anything that feels 80%+ relevant goes into raw/.
|
||||
|
||||
**step 4: run ingest (5 minutes)**
|
||||
|
||||
```markdown
|
||||
> /wiki-ingest
|
||||
```
|
||||
|
||||
the agent sorts your clippings, fetches full content from URLs, downloads and analyzes images, classifies each source by type, builds wiki pages with cross-references, adds counter-arguments and data gaps on every page, and updates the master index.
|
||||
|
||||
here's what a /wiki-query looks like in practice:
|
||||
|
||||
```markdown
|
||||
> /wiki-query what content formats get the most bookmarks?
|
||||
|
||||
Reading wiki/index.md... scanning 47 TLDRs
|
||||
Reading wiki/content-performance.md
|
||||
Reading wiki/bookmark-analysis-march.md
|
||||
Reading wiki/thread-vs-single-tweet.md
|
||||
|
||||
Answer:
|
||||
Threads with numbered lists get 3.2x more bookmarks than
|
||||
single tweets in your data. visual breakdowns (terminal
|
||||
screenshots, flowcharts) averaged 847 bookmarks vs 312 for
|
||||
text-only. the top 5 bookmarked posts were all either
|
||||
step-by-step guides or tool comparisons.
|
||||
|
||||
Sources: [[content-performance]], [[bookmark-analysis-march]],
|
||||
[[thread-vs-single-tweet]]
|
||||
|
||||
→ Filed as wiki/bookmark-formats-query.md
|
||||
```
|
||||
|
||||
every answer gets filed back. the next query about content performance will also pull from this one.
|
||||
|
||||
**step 5: open the graph**
|
||||
|
||||
open Obsidian's graph view. your ideas, the people you follow, the tools you use, and the concepts you care about are now linked together in a visual network. start querying with /wiki-query.
|
||||
|
||||

|
||||
|
||||
once the initial ingest is done, try these:
|
||||
|
||||
> "what content topics have I bookmarked the most in the last month?" shows your signal patterns.
|
||||
|
||||
> "what are the counter-arguments to \[my main thesis\]?" forces you to stress-test your thinking against what the wiki has compiled.
|
||||
|
||||
> "summarize everything I know about \[competitor/tool/topic\]" pulls from every source that mentions it and synthesizes a briefing.
|
||||
|
||||
> "what concepts in my wiki have the fewest sources?" shows where your knowledge is thin and where to research next.
|
||||
|
||||
each answer gets filed back. the wiki grows.
|
||||
|
||||
## what to do now?
|
||||
|
||||
set up a scheduled trigger (Claude Dispatch or cron) that runs /wiki-ingest every morning.
|
||||
|
||||
you clip things during the day, they get processed overnight, you wake up to a richer knowledge base.
|
||||
|
||||
run /wiki-lint every week or two to catch contradictions between pages, stale content, orphan pages nobody links to, and duplicate concepts under different names.
|
||||
|
||||
the agent fixes what it can and flags what needs your judgment.
|
||||
|
||||
when you hit 300+ pages, install qmd (by Tobi Lutke) for local hybrid search with BM25 + vector retrieval and LLM re-ranking. it has an MCP server so your agent can search the wiki as a native tool.
|
||||
|
||||
start connecting the knowledge layer to other agents. a writer agent that reads from it. a researcher that feeds into it. a content strategist that queries it. the knowledge layer is the shared brain that makes all of them useful.
|
||||
|
||||
## the window
|
||||
|
||||
karpathy's post hit 99,000+ bookmarks. graphify shipped in 48 hours and got 27,000+ more. multiple implementations went viral the same week. the demand is obvious.
|
||||
|
||||
most people will bookmark this, think "that's cool," and never set it up.
|
||||
|
||||
the ones who spend 20 minutes today will have a compounding knowledge base by next month that no search engine and no generic AI prompt can replicate. it will know your voice, your data, your patterns, and your taste.
|
||||
|
||||
every week you wait is a week of compounding you don't get back.
|
||||
|
||||
repo: [github.com/shannhk/llm-wikid](https://github.com/shannhk/llm-wikid)
|
||||
|
||||
> 4月13日
|
||||
>
|
||||
> how marketing AI knowledge layer works every marketing team has data scattered across 15-30 tools and none of it talks to each other your CRM doesnt know what your SEO agent found yesterday. your ad platform doesnt know what your sales team heard on calls this week. your
|
||||
@@ -0,0 +1,310 @@
|
||||
---
|
||||
title: "Agents 201: The Unit Shrank"
|
||||
source: "https://x.com/ghumare64/status/2047401813364683007"
|
||||
author:
|
||||
- "[[@ghumare64]]"
|
||||
published: 2026-04-24
|
||||
created: 2026-04-24
|
||||
description: "Three months ago, I wrote an article that went viral: Agents 201 about orchestrating multiple agents without burning your token budget or tu..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
**Three months ago**, **I wrot**e **an** **article that went viral:** [Agents 201](https://x.com/ghumare64/status/2012136491133145364) about orchestrating multiple agents without burning your token budget or turning coordination into chaos.
|
||||
|
||||
That's still true. What I missed is that the unit itself was about to change.
|
||||
|
||||
## What changed since January
|
||||
|
||||
Then, the agent was the atomic unit. Supervisor pattern. Swarm pattern. Hierarchical pattern. Every node in every diagram was "an agent."
|
||||
|
||||
[r/claude, April 19, 866 upvotes](https://www.reddit.com/r/claude/comments/1spef7j/my_full_claude_code_setup_after_months_of_daily/): "Try Haiku 4.5 agents. Just as good as Sonnet if Opus is orchestrating."
|
||||
|
||||

|
||||
|
||||
- [r/ClaudeCode, April 4](https://www.reddit.com/r/ClaudeCode/comments/1sc6ic3/im_on_a_100month_claude_max_plan_my_last_30_days/): 138 sessions. 61.8M tokens. $11.55 per session. **15x the Max plan cost.**
|
||||
|
||||

|
||||
|
||||
Nobody is shipping a better agent. They're shipping parts of one. Tier model allocation. Dependent handoffs. Blackboards. Verifier gates. Observability dashboards.
|
||||
|
||||
The agent got disassembled.
|
||||
|
||||
## Why monolithic agents are failing
|
||||
|
||||
A monolithic agent is a generalist. It plans, retrieves, reasons, writes, verifies, and answers in one context window. All on one model. All billed per token.
|
||||
|
||||
Three things break at production.
|
||||
|
||||
**Token economics.** One agent coordinating four sub-agents on the most expensive model turns a 15K-token task into 60K. The [$1,593-a-month Claude Code story](https://www.reddit.com/r/ClaudeCode/comments/1sc6ic3/im_on_a_100month_claude_max_plan_my_last_30_days/) is what "one smart agent doing everything" actually costs.
|
||||
|
||||
**Specialization loss.** When one model plays router, coder, reviewer, summarizer, and verifier, it's good at none of them. We keep [relearning this](https://x.com/doppenhe/status/2046997971812884640). It's the ML lesson at a new layer.
|
||||
|
||||
**Debugging by vibes.** When a supervisor holds the plan and four workers write to shared state and something is wrong at the end, you don't debug. You re-run and hope. Exactly the problem [tailclaude](https://github.com/rohitg00/tailclaude) is trying to fix with a Kubernetes-style dashboard.
|
||||
|
||||
## The unit is a worker
|
||||
|
||||

|
||||
|
||||
A worker does one thing. Clear identity. Defined input. Defined output. One job it gets good at.
|
||||
|
||||
A retriever worker retrieves. One model. One prompt. One schema. Benchmarkable. Swappable.
|
||||
|
||||
A verifier worker verifies. Runs after other workers. Fails loud. Has a test.
|
||||
|
||||
A summarizer worker summarizes. That's it. Boring. Boring is the feature.
|
||||
|
||||
An agent is a composition of workers. Not the other way around.
|
||||
|
||||
This is the shift. In January I was writing about how to orchestrate agents. The question was wrong. The question is how to compose workers into something that looks like an agent from the outside.
|
||||
|
||||
## Three primitives
|
||||
|
||||
iii ships three primitives. **Worker, Function, Trigger.** That's the vocabulary.
|
||||
|
||||

|
||||
|
||||
A **Worker** is any process that connects. Rust daemon, TypeScript service, Python script, browser tab, microVM, or an LLM itself. Long-lived WebSocket client on websockets.
|
||||
|
||||
A **Function** is a named unit of work a Worker registers. **memory::recall. retrieve::web. verify::code**. Called by ID plus a JSON payload.
|
||||
|
||||
A **Trigger** is what causes a Function to run. HTTP. Cron. Queue. State change. Stream event. User-defined.
|
||||
|
||||
That's it. No separate mental model for agents, queues, workflows, or observability.
|
||||
|
||||
**React** shipped with four concepts. **Unix** shipped with three. **SQL** shipped with three. Every paradigm that compounded over decades did it on a vocabulary small enough to hold in one head.
|
||||
|
||||
The smallness is the bet.
|
||||
|
||||
**The smallest real worker**
|
||||
|
||||
```typescript
|
||||
import { registerWorker } from 'iii-sdk'
|
||||
|
||||
const iii = await registerWorker('ws://127.0.0.1:49134', {
|
||||
workerName: 'retriever',
|
||||
})
|
||||
|
||||
await iii.registerFunction(
|
||||
'retrieve::web',
|
||||
async ({ query }: { query: string }) => {
|
||||
const hits = await fetchSearch(query)
|
||||
return { hits }
|
||||
},
|
||||
{
|
||||
description: 'Retrieve web results for a query',
|
||||
request_format: {
|
||||
type: 'object',
|
||||
properties: { query: { type: 'string' } },
|
||||
required: ['query'],
|
||||
},
|
||||
},
|
||||
)
|
||||
|
||||
await iii.registerTrigger({
|
||||
type: 'http',
|
||||
function_id: 'retrieve::web',
|
||||
config: { api_path: 'retrieve', http_method: 'POST' },
|
||||
metadata: {},
|
||||
})
|
||||
```
|
||||
|
||||
That's a complete worker. One function. One trigger. Any other worker on the engine can now call retrieve::web. Any HTTP client can POST /retrieve.
|
||||
|
||||
## Orchestration patterns are triggers, not architectures
|
||||
|
||||
Three months ago I drew supervisor, swarm, and hierarchical as three distinct architectures. They're not. They're patterns that reduce to the same primitives.
|
||||
|
||||
**Supervisor as workers**
|
||||
|
||||

|
||||
|
||||
```typescript
|
||||
await iii.registerFunction('plan::decompose', async ({ task }) => {
|
||||
const [retrieved, coded, reviewed] = await Promise.all([
|
||||
iii.trigger({ function_id: 'retrieve::web', payload: { query: task } }),
|
||||
iii.trigger({ function_id: 'code::write', payload: { task } }),
|
||||
iii.trigger({ function_id: 'review::lint', payload: { task } }),
|
||||
])
|
||||
|
||||
return iii.trigger({
|
||||
function_id: 'synth::merge',
|
||||
payload: { retrieved, coded, reviewed },
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
Supervisor + specialized sub-agents (retriever, coder, analyst, summarizer) + shared memory bus. In [iii](https://iii.dev/) the bus is the engine.
|
||||
|
||||
**Swarm via state triggers**
|
||||
|
||||
No supervisor. Workers subscribe to shared state. Each reacts to changes others wrote.
|
||||
|
||||

|
||||
|
||||
```typescript
|
||||
await iii.registerFunction('hotel::search', async ({ scope, key, value }) => {
|
||||
const dest = value?.destination
|
||||
if (!dest) return { skipped: true }
|
||||
const hotels = await searchHotels(dest)
|
||||
await iii.trigger({
|
||||
function_id: 'state::set',
|
||||
payload: { scope, key: 'hotels', value: hotels },
|
||||
})
|
||||
return { count: hotels.length }
|
||||
})
|
||||
|
||||
await iii.registerTrigger({
|
||||
type: 'state',
|
||||
function_id: 'hotel::search',
|
||||
config: { scope: 'trip-42', key: 'destination' },
|
||||
metadata: {},
|
||||
})
|
||||
```
|
||||
|
||||
Swarm is not an architecture. It's a state trigger. When destination changes, flights react. When flights resolve, hotels react. No central coordinator. No framework.
|
||||
|
||||
**Hierarchical is supervisor, recursive**
|
||||
|
||||

|
||||
|
||||
Each mid-level is itself a function that triggers leaf functions. Same primitive. Different shape. You're not picking an architecture. You're picking which Functions subscribe to which Triggers.
|
||||
|
||||
**Narrow-worker decomposition**
|
||||
|
||||
A domain with multiple concerns is not one worker. It's several.
|
||||
|
||||
Memory is the canonical example. Not one memory worker. Five of them:
|
||||
|
||||

|
||||
|
||||
Each is iii worker add-able. Minimal app installs memory. Research assistant installs four. Same pattern for auth, routing, observability, anything with multiple concerns.
|
||||
|
||||
That's the rule. One scope per worker. No cross-scope reads. Split on complexity, not on speculation.
|
||||
|
||||
## What you actually build
|
||||
|
||||
Start with one worker. One function. Measure it.
|
||||
|
||||
Find the bottleneck. Usually specialization or token cost.
|
||||
|
||||
Extract one concern. Make it a second worker with its own function.
|
||||
|
||||
Wire them with iii.trigger(). The call site doesn't change when the callee moves to another machine, another language, another process.
|
||||
|
||||
```typescript
|
||||
// Before: one function does two things
|
||||
await iii.registerFunction('memory::store', async ({ text }) => {
|
||||
const summary = await summarize(text) // expensive model
|
||||
return persist({ text, summary })
|
||||
})
|
||||
|
||||
// After: two workers, narrow scope each
|
||||
// memory-compress:
|
||||
await iii.registerFunction('memory::compress', async ({ text }) => ({
|
||||
summary: await summarize(text),
|
||||
}))
|
||||
|
||||
// memory (calls compress via trigger):
|
||||
await iii.registerFunction('memory::store', async ({ text }) => {
|
||||
const { summary } = await iii.trigger({
|
||||
function_id: 'memory::compress',
|
||||
payload: { text },
|
||||
})
|
||||
return persist({ text, summary })
|
||||
})
|
||||
```
|
||||
|
||||
Now memory::compress is swappable. Benchmarkable. You can downgrade its model independent of the store path. You can install a community version. The call site didn't change.
|
||||
|
||||
## The categories that collapse
|
||||
|
||||
A partial list of things you stop buying once workers are the unit:
|
||||
|
||||

|
||||
|
||||
Not because iii has equivalents. Because once work is triggered Functions on Workers, the conditions that made these separate categories are gone.
|
||||
|
||||
## Where it gets interesting
|
||||
|
||||
**A worker can create workers.** An agent hits a task outside its current capabilities, installs a sandbox worker from the registry, runs the task, tears it down. The agent extended itself at runtime. No human in the loop for the capability. No fixed tool set prepared in advance.
|
||||
|
||||
**A browser tab is a worker.** Cron on the backend calls a function on your open tab. Long-running workflows pause, invoke a human-in-the-loop function in an admin's browser, wait for the return. One trace across backend, agent, browser.
|
||||
|
||||
## Sandbox is a worker
|
||||
|
||||
Running untrusted code is the hard part of autonomy. Agent writes code. Agent wants to run it. You don't want it touching your filesystem, your network, your process tree, or your production DB.
|
||||
|
||||
Every agent framework today wires this separately. Docker container here. Firecracker there. A custom RPC shim on top. Two different RBAC models. Two different logging paths.
|
||||
|
||||
In iii, a sandbox is a worker. Same shape as everything else.
|
||||
|
||||

|
||||
|
||||
A sandbox worker registers three functions. sandbox::create opens a hardware-isolated microVM. sandbox::exec runs a command in it. sandbox::destroy tears it down. The worker implementation is Firecracker or Docker or Wasm or anything else. The contract is the same.
|
||||
|
||||
```typescript
|
||||
await iii.registerFunction('agent::run_untrusted', async ({ code }) => {
|
||||
const { box_id } = await iii.trigger({
|
||||
function_id: 'sandbox::create',
|
||||
payload: { image: 'python:3.12-slim', cpu: 1, mem_mb: 512 },
|
||||
})
|
||||
|
||||
try {
|
||||
const { stdout, exit_code } = await iii.trigger({
|
||||
function_id: 'sandbox::exec',
|
||||
payload: { box_id, cmd: ['python', '-c', code], timeout_ms: 10000 },
|
||||
})
|
||||
return { stdout, exit_code }
|
||||
} finally {
|
||||
await iii.trigger({
|
||||
function_id: 'sandbox::destroy',
|
||||
payload: { box_id },
|
||||
action: { type: 'void' },
|
||||
})
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
The agent doesn't know what's under sandbox::create. It could be sandbox-firecracker, sandbox-docker, sandbox-wasm, or a fake one in tests. Swap by iii worker add-ing a different sandbox worker. No agent code changes.
|
||||
|
||||
Three things fall out of this shape.
|
||||
|
||||
**CLI and agent are peers.** When you run iii worker add <name>, the CLI calls sandbox::create to install in isolation. When an agent runs generated Python, it calls the same sandbox::create. Same function. Same engine. Same auth path.
|
||||
|
||||
**RBAC is just a function.** An allow::check function (its own worker) sits in front of sandbox::create via a condition trigger. Same gate governs the CLI and the agent. You don't maintain two policy systems.
|
||||
|
||||
**The spawned microVM is itself a worker.** It connects to the engine as an ephemeral peer, runs its task, disconnects. While alive it can register its own functions and be invoked like any other worker. The recursion is the point: a worker that creates workers that register functions that other workers can trigger.
|
||||
|
||||
**sandbox-docker or sandbox-firecracker** can be written in Rust and can be used anytime, anywhere. Swap at will.
|
||||
|
||||
Isolation stopped being platform infrastructure. It's a function on the same engine as your queue.
|
||||
|
||||
## The quadratic problem
|
||||
|
||||

|
||||
|
||||
New capability is n+1, not n². Every worker joins by connecting. No consumer services to update. No gateway config. No registry entries. No restarts. The coordination cost of shipping a capability goes to zero.
|
||||
|
||||
For a multi-agent system this is the difference between a tree you hand-maintain and a graph that self-assembles.
|
||||
|
||||
## Bottom line
|
||||
|
||||
Stop building agents. Start building workers.
|
||||
|
||||
One worker at a time. Narrow scope. Clear identity. Defined tools. Let the composition emerge from Triggers and Functions.
|
||||
|
||||
An agent isn't a thing you build. It's what you call the composition when it's working.
|
||||
|
||||
Pick the smallest real task your current agent struggles with. Extract it into a worker. Give it one function. Measure it. Ship.
|
||||
|
||||
That's how you move.
|
||||
|
||||
Don't forget to check out [iii.dev](https://iii.dev/), It's open-source.
|
||||
|
||||
[https://github.com/iii-hq/iii](https://github.com/iii-hq/iii) (⭐️)
|
||||
|
||||
Follow [@ghumare64](https://x.com/@ghumare64) for more lessons on AI Agentic Engineering.
|
||||
|
||||

|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: "Atomic agent blueprints on Google Cloud’s Agent Garden"
|
||||
source: "https://x.com/GoogleCloudTech/status/2048066787233943773"
|
||||
author:
|
||||
- "[[@GoogleCloudTech]]"
|
||||
published: 2026-04-25
|
||||
created: 2026-04-26
|
||||
description: "Building multi-agent systems from scratch presents complex design challenges, including; finding the optimized design pattern for your use-c..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
Building multi-agent systems from scratch presents complex design challenges, including; finding the optimized design pattern for your use-case, orchestration failures and evaluation loops. You can spend weeks reinventing the wheel, trying to get your agents to be ready for production—or you can start with architectures that already work, with our new Atomic Agents in Agent Garden.
|
||||
|
||||
Authored by [Anant Nawalgaria](https://www.linkedin.com/in/anant-nawalgaria/%20a) and [Naz Bayrak](https://www.linkedin.com/in/naz-levent/)
|
||||
|
||||
At Google Cloud Next '26, we’re releasing a dozen core agent blueprints on Agent Garden that reduce friction for enterprise teams. These agents include Brand-Aligned Research & Presentations, On-Brand GenMedia, Cyber Guardian, YouBuddy, High-Volume Document Analyzer, Invoice Processing, Small Business Loans, Nurse Handover, Economic Research, Task Planner Agent, SDLC Technical Agent & User Story Refiner.
|
||||
|
||||
These Atomic Agents are production-ready templates and blueprints that offer proven approaches to standard design and implementation challenges. They are the exact production-grade patterns our customers are using today to accomplish specific tasks. Instead of starting from scratch, you follow a proven path to production using Agent Garden:
|
||||
|
||||

|
||||
|
||||
## Blueprint 1: The SDLC Suite
|
||||
|
||||
Product backlogs are often stalled by ambiguous, unstructured feature requests. Breaking down a massive technical design into manageable Jira tickets or Git merge requests is an administrative chore that drains engineering momentum.
|
||||
|
||||

|
||||
|
||||
The SDLC Suite in Agent Garden is a chained architectural pattern composed of three atomic agents that take a feature from a vague idea to a structured execution plan:
|
||||
|
||||
1. **User Story Refiner:** An interactive product assistant. It interviews stakeholders to clarify raw requirements and automatically generates standardized Markdown user stories complete with strict Behavior-Driven Development (BDD) acceptance criteria.
|
||||
2. **Technical Designer:** A planning co-pilot that converts those refined stories into Request for Comments (RFC) documents and Architecture Decision Records (ADRs). By leveraging Google Cloud Spanner via spanner\_query\_tools, it actively queries your project's Code Knowledge Graph to generate accurate Mermaid architecture diagrams that don't clash with existing infrastructure.
|
||||
3. **Task Planner:** An embedded technical lead that tears through the generated documentation to map out a fully sequenced Execution Plan. It breaks broad features down into atomic tasks and intelligently charts out optimal Git branch strategies (e.g., parallel vs. sequential dependencies) before coding begins.
|
||||
|
||||
## Blueprint 2: On-Brand GenMedia
|
||||
|
||||
Marketing teams often struggle to scale asset production without compromising their corporate visual identity.
|
||||
|
||||

|
||||
|
||||
The **On-Brand GenMedia** agent resolves this tension by deploying a sequential, self-correcting creative engine. Beyond generating images; it actively evaluates and refines them using an LLM-as-a-judge framework to ensure strict brand alignment.
|
||||
|
||||
- **RAG for Brand Governance:** It dynamically searches and injects existing brand asset metadata and policy rules (get\_policy, search\_asset\_bank) before hitting the generation model.
|
||||
- **The Self-Correction Loop:** It manages a distinct toolset distributed across sub-agents. Crucially, it implements an automated loop governed by a check\_condition\_and\_escalate\_tool. A dedicated Checker Agent iteratively scores generated artifacts against a strict compliance rubric, regenerating any media that fails to meet the quantitative visual standards.
|
||||
|
||||
## Blueprint 3: Invoice Processing
|
||||
|
||||
Document extraction is notoriously brittle. When invoice formats change, parsing rules break, requiring developers to manually update the codebase.
|
||||
|
||||

|
||||
|
||||
The **Invoice Processing** agent establishes a continuous improvement loop by isolating agent development from agent improvement. Powered by Gemini 2.5 (Flash + Pro), it processes invoices through a 9-stage pipeline, allowing domain experts to update extraction rules conversationally without altering the core codebase.
|
||||
|
||||
- **Adaptive Learning Framework (ALF):** Equipped with 24 deterministic condition operators and scope-based mutual exclusion, it allows finance analysts to teach the agent new rules via natural language.
|
||||
- **Risk-Free Rule Updates:** It registers 18 specialized function tools on a single LlmAgent (divided into inference and learning tools). When a human expert proposes a new rule, an impact assessment protocol evaluates the rule against a random sample of existing ground-truth cases to prevent collateral damage before committing the changes to production.
|
||||
|
||||
## Querying Your Deployed Agent
|
||||
|
||||
Once you've selected and configured a blueprint, deploying it to Agent Engine allows you to seamlessly integrate it into your existing programmatic workflows.
|
||||
|
||||
## Get Started
|
||||
|
||||
You don't need to build from scratch. Head to [Agent Garden](https://console.cloud.google.com/vertex-ai/agents/agent-garden) within the Gemini Enterprise Agent Platform to explore these templates, view their architecture diagrams, and deploy them directly to your environment.
|
||||
@@ -0,0 +1,388 @@
|
||||
---
|
||||
title: "Build Agents that never forget"
|
||||
source: "https://x.com/akshay_pachaar/status/2043745099792953508"
|
||||
author:
|
||||
- "[[@akshay_pachaar]]"
|
||||
published: 2026-04-14
|
||||
created: 2026-05-04
|
||||
description: "A first-principles walk through agent memory: from Python lists to markdown files to vector search to graph-vector hybrids, and finally, a c..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
A first-principles walk through agent memory: from Python lists to markdown files to vector search to graph-vector hybrids, and finally, a clean, open-source solution for all of this.
|
||||
|
||||

|
||||
|
||||
An LLM is stateless by design. Every API call starts fresh. The "memory" you feel when chatting with ChatGPT is an illusion created by re-sending the entire conversation history with every request.
|
||||
|
||||
That trick works for casual chat. It falls apart the moment you try to build a real agent.
|
||||
|
||||
**Here are 7 failure modes show up the instant you skip memory:**
|
||||
|
||||
1. **Context amnesia:** the agent asks for information you already gave it
|
||||
2. **Zero personalization:** every interaction feels generic
|
||||
3. **Multi-step task failure:** intermediate state silently drops mid-task
|
||||
4. **Repeated mistakes:** no episodic recall means the same errors, forever
|
||||
5. **No knowledge accumulation:** every session starts from scratch
|
||||
6. **Hallucination from gaps:** when context overflows, the model invents
|
||||
7. **Identity collapse:** no continuity, no trust
|
||||
|
||||
The obvious response is "throw more context at it." That's why 128K and 200K token windows feel like they should solve everything.
|
||||
|
||||
They don't.
|
||||
|
||||
**Accuracy drops over 30% when relevant information sits in the middle of a long context.** This is the well-documented "lost in the middle" effect.
|
||||
|
||||
Context is a shared budget: system prompts, retrieved docs, conversation history, and output all fight for the same tokens.
|
||||
|
||||
Even at 100K tokens, the absence of persistence, prioritization, and salience makes raw context length insufficient.
|
||||
|
||||

|
||||
|
||||
Memory isn't about cramming more text into the prompt. **It's about structuring what the agent remembers so it can find what matters.**
|
||||
|
||||
## The cognitive science frame that actually helps
|
||||
|
||||
Lilian Weng's 2023 formulation has become the default framework:
|
||||
|
||||
**Agent = LLM + Memory + Planning + Tool Use.**
|
||||
|
||||
The four co-equal pillars.
|
||||
|
||||
Her taxonomy borrows from cognitive science, where human memory splits into three systems:
|
||||
|
||||
- **Sensory memory** captures raw perceptual input and holds it for a fraction of a second. Only the portions you pay attention to get passed forward.
|
||||
- **Working memory** is where active thinking happens. It holds roughly 7±2 items at a time ([Miller's 1956 finding](https://pmc.ncbi.nlm.nih.gov/articles/PMC4486516/)). Lose focus, and the contents disappear.
|
||||
- **Long-term memory** is durable storage with no practical capacity limit. Retrieval is the bottleneck: you can store millions of things and still fail to recall the one you need.
|
||||
|
||||
Each maps directly to a component in modern agent architectures:
|
||||
|
||||

|
||||
|
||||
**Long-term memory itself splits further:**
|
||||
|
||||
- **Episodic:** specific past events ("on Tuesday, the PostgreSQL cluster went down")
|
||||
- **Semantic:** facts and concepts ("PostgreSQL is a relational database")
|
||||
- **Procedural:** skills and workflows ("when a user asks for a refund, first check the purchase date")
|
||||
|
||||
The bridge between episodic and semantic is **memory consolidation**: repeated specific events distilling into general knowledge. An agent that notices "users consistently prefer executive summaries" across dozens of interactions should turn that into a reusable rule. Without consolidation, your agent replays individual events rather than learning from them.
|
||||
|
||||

|
||||
|
||||
## The minimal agent, and what breaks first
|
||||
|
||||
Strip away the frameworks and an agent is a loop: perceive, think, act.
|
||||
|
||||
```python
|
||||
class Agent:
|
||||
"""Minimal AI agent: perceive, think, act"""
|
||||
def __init__(self):
|
||||
self.client = anthropic.Anthropic()
|
||||
self.model = "claude-sonnet-4-20250514"
|
||||
|
||||
def run(self, user_input: str) -> str:
|
||||
response = self.client.messages.create(
|
||||
model=self.model,
|
||||
max_tokens=1024,
|
||||
messages=[{"role": "user", "content": user_input}],
|
||||
)
|
||||
return response.content[0].text
|
||||
```
|
||||
|
||||
Tell it "I have 4 apples," then ask "I ate one, how many left?" and it has no idea what apples you're talking about. Each call exists in isolation.
|
||||
|
||||
## Layer 1: The Python list
|
||||
|
||||
The first fix everyone reaches for:
|
||||
|
||||
```python
|
||||
class Agent:
|
||||
def __init__(self):
|
||||
self.client = anthropic.Anthropic()
|
||||
self.messages = [] # The entire "memory" is a list
|
||||
|
||||
def chat(self, user_input: str) -> str:
|
||||
self.messages.append({"role": "user", "content": user_input})
|
||||
response = self.client.messages.create(
|
||||
model="claude-sonnet-4-20250514",
|
||||
max_tokens=1024,
|
||||
messages=self.messages, # Full history sent every time
|
||||
)
|
||||
reply = response.content[0].text
|
||||
self.messages.append({"role": "assistant", "content": reply})
|
||||
return reply
|
||||
```
|
||||
|
||||
Multi-turn works now. The apples question gets answered correctly because the full conversation re-ships with every call.
|
||||
|
||||
Two problems show up fast:
|
||||
|
||||
- **The list grows unbounded.** Around turn 200, you hit the context ceiling and the oldest messages silently drop. The user's name from turn 1 disappears long before yesterday's throwaway joke. No prioritization, just strict chronological order.
|
||||
- **Everything lives in RAM.** The moment the Python process ends, your agent has no idea who you are.
|
||||
|
||||
## Layer 2: Markdown files for persistence
|
||||
|
||||
The next move is writing memory to disk. Markdown is a natural fit: human-readable, Git-friendly, and the agent can read it back as plain text. Claude Code uses exactly this pattern with **CLAUDE.md** and **MEMORY.md** files.
|
||||
|
||||
```python
|
||||
class MarkdownMemoryAgent:
|
||||
def __init__(self):
|
||||
self.client = anthropic.Anthropic()
|
||||
self.history_file = Path("memory/conversation_history.md")
|
||||
self.facts_file = Path("memory/known_facts.md")
|
||||
|
||||
def save_to_disk(self, role: str, content: str) -> None:
|
||||
with open(self.history_file, "a") as f:
|
||||
f.write(f"### {role} at {datetime.now().isoformat()}\n{content}\n\n")
|
||||
|
||||
def load_history(self) -> str:
|
||||
if self.history_file.exists():
|
||||
return self.history_file.read_text()
|
||||
return ""
|
||||
|
||||
def chat(self, user_input: str) -> str:
|
||||
self.save_to_disk("user", user_input)
|
||||
history = self.load_history()
|
||||
response = self.client.messages.create(
|
||||
model="claude-sonnet-4-20250514",
|
||||
max_tokens=1024,
|
||||
system=f"Previous conversation:\n{history}",
|
||||
messages=[{"role": "user", "content": user_input}],
|
||||
)
|
||||
reply = response.content[0].text
|
||||
self.save_to_disk("assistant", reply)
|
||||
return reply
|
||||
```
|
||||
|
||||
Persistence is solved. Restart the script, and the conversation is still on disk. You could also maintain a separate facts file that the agent extracts over time:
|
||||
|
||||
```plaintext
|
||||
- User's name is Sarah
|
||||
- Sarah manages the backend team at Acme Corp
|
||||
- Acme Corp is a B2B SaaS company
|
||||
- Currently migrating production database to a new AWS region
|
||||
```
|
||||
|
||||
You can open the file in any editor, see exactly what the agent knows, and fix it by hand. Genuinely useful for prototyping.
|
||||
|
||||
With 4 facts, this works perfectly. Load the entire file into context and the LLM handles any question about Sarah, her company, or her industry.
|
||||
|
||||
Now fast-forward three months. Your agent has 2,000 extracted facts and 200 conversation logs. That's 500K+ tokens of markdown on disk, and your context window is 128K.
|
||||
|
||||
**You can no longer load everything.** You need to selectively retrieve only the facts relevant to the current query. With flat files, your only option is keyword search:
|
||||
|
||||
```python
|
||||
# User asks: "What's the status of our cloud migration?"
|
||||
grep("cloud migration", facts_file)
|
||||
# Returns: []
|
||||
# The fact on disk says "migrating production database to a new AWS region."
|
||||
# The words "cloud migration" appear nowhere.
|
||||
|
||||
# User asks: "Which team is handling the database work?"
|
||||
grep("database team", facts_file)
|
||||
# Returns: []
|
||||
# One fact says Sarah "manages the backend team." Another says the team
|
||||
# is "migrating production database." But no single line contains
|
||||
# both "database" and "team" together.
|
||||
```
|
||||
|
||||
**At small scale, markdown files work. At real scale, they force keyword retrieval, and keywords can't handle synonyms, paraphrases, or connections across facts.**
|
||||
|
||||
The information is on disk. But you can't load all of it, and keyword search is too brittle to find the right pieces.
|
||||
|
||||
If you've used **OpenClaw**, you've seen this play out. It stores memory as markdown checkpoint files, and over weeks of daily use, earlier facts quietly slip away as context accumulates and gets compacted. The storage is there. The retrieval isn't.
|
||||
|
||||
Storage without intelligent retrieval is a library with no catalog.
|
||||
|
||||
## Layer 3: Vector search and the wall it hits
|
||||
|
||||
Bolt on embeddings. Chunk your markdown, embed the chunks, search by cosine similarity. Now "database" matches "PostgreSQL" because their vectors live close together in embedding space. The synonym problem dissolves.
|
||||
|
||||
Then you hit a new wall. Consider these three facts in your vector DB:
|
||||
|
||||
```plaintext
|
||||
- "Alice is the tech lead on Project Atlas"
|
||||
- "Project Atlas uses PostgreSQL for its primary datastore"
|
||||
- "The PostgreSQL cluster experienced an outage on Tuesday"
|
||||
```
|
||||
|
||||
**User asks:** "Was Alice's project affected by Tuesday's outage?"
|
||||
|
||||
The query mentions Alice and Tuesday's outage, so vector search ranks the first and third facts high. But the critical bridge, "Project Atlas uses PostgreSQL," mentions neither Alice nor Tuesday. It's the connecting piece, and it's the one that won't surface.
|
||||
|
||||
Each fact is an isolated point in embedding space. **The connective tissue linking them is invisible to vectors.**
|
||||
|
||||

|
||||
|
||||
This isn't an edge case. It's the normal shape of real-world questions. Business knowledge is inherently relational: people belong to teams, teams own projects, projects depend on systems, systems have incidents. Any question that crosses two or more hops exceeds what flat vector retrieval can answer.
|
||||
|
||||
## The capability matrix
|
||||
|
||||
Each layer fixes the previous pain but reveals a deeper one:
|
||||
|
||||

|
||||
|
||||
**You need persistence, semantic understanding, and relational reasoning in a single memory layer.**
|
||||
|
||||
Building this yourself means gluing together a vector database, a graph database, a relational store, an entity extractor, a deduplication pipeline, and an edge-weighting system. That's weeks of infrastructure work before you write a single line of agent logic.
|
||||
|
||||
I've been using a solution that fills this gap cleanly. It's fully open-source, handles all three storage paradigms under one roof, and you can get it running in minutes. Let's talk about Cognee.
|
||||
|
||||
# Cognee: three stores, one engine, four calls
|
||||
|
||||
[Cognee](https://github.com/topoteretes/cognee) is an open-source knowledge engine built for agent memory. It combines vector search with knowledge graphs and a relational provenance layer into a single system.
|
||||
|
||||
The entire API surface is four async calls:
|
||||
|
||||
```python
|
||||
import cognee
|
||||
|
||||
await cognee.add("Your document here") # Ingest anything
|
||||
await cognee.cognify() # Build knowledge graph + embeddings
|
||||
await cognee.memify() # Self-improve the memory
|
||||
await cognee.search("Your query") # Retrieve with reasoning
|
||||
```
|
||||
|
||||
Behind those four calls sits a three-store architecture.
|
||||
|
||||

|
||||
|
||||
**Why three stores and not one ?**
|
||||
|
||||
Each store captures a dimension of knowledge the others can't:
|
||||
|
||||
- **Relational store** → provenance: where data came from, when it was ingested, who has access
|
||||
- **Vector store** → semantics: what content means, what it's similar to
|
||||
- **Graph store** → relationships: how entities connect, what causes what, who reports to whom
|
||||
|
||||
Flatten any of these and you lose information that matters for retrieval accuracy.
|
||||
|
||||
The default stack is **SQLite + LanceDB + Kuzu**, entirely embedded and file-based. pip install cognee plus an LLM API key and you're running.
|
||||
|
||||
No Docker, no external services.
|
||||
|
||||
For production, swap SQLite for Postgres, LanceDB for Qdrant/Pinecone/pgvector, and Kuzu for Neo4j/FalkorDB/Neptune.
|
||||
|
||||
Same four-call API either way.
|
||||
|
||||
## What cognify actually does?
|
||||
|
||||
cognee.cognify() runs a multi-stage pipeline that converts raw text into structured, interconnected knowledge:
|
||||
|
||||
1. **Document classification** by type and domain
|
||||
2. **Permission checking** for multi-tenant access control
|
||||
3. **Chunk extraction** that respects paragraph structure (not fixed-size cuts)
|
||||
4. **Entity and relationship extraction** via LLM, with automatic deduplication through content hashing
|
||||
5. **Summary generation** for efficient retrieval
|
||||
6. **Dual indexing** into the vector store (embeddings) and graph store (edges)
|
||||
|
||||
The deduplication step matters more than it sounds. If the same entity shows up across 50 documents, Cognee merges it into a single graph node with 50 inbound edges. Your agent no longer sees "Alice" as 50 different strangers. And the pipeline is incremental by default: only new or updated files get reprocessed.
|
||||
|
||||

|
||||
|
||||
**Every graph node has a corresponding embedding.** This dual representation is the core trick: enter through vectors (find semantically similar content) and exit through the graph (follow relationships to connected entities), or the reverse. That's what makes multi-hop queries work without sacrificing semantic search.
|
||||
|
||||
## Memify: memory that learns
|
||||
|
||||
memify() is what separates Cognee from every "ingest and search" tool. It runs an RL-inspired optimization pass over the graph:
|
||||
|
||||
- **Strengthening** useful paths that led to good retrieval
|
||||
- **Pruning** stale nodes that haven't been touched
|
||||
- **Auto-tuning** edge weights based on real usage
|
||||
- **Adding derived facts** by identifying implicit relationships
|
||||
|
||||
A customer support agent's graph naturally strengthens paths through product docs and refund policies while letting rarely-queried HR edges decay. **The graph develops its own sense of relevance over time.**
|
||||
|
||||

|
||||
|
||||
## Fourteen retrieval modes
|
||||
|
||||
Cognee ships 14 search modes. The ones you'll actually reach for:
|
||||
|
||||

|
||||
|
||||
# Building a real agent with Cognee memory
|
||||
|
||||
Here's the complete pattern wiring Cognee into the perceive-think-act loop:
|
||||
|
||||
```python
|
||||
import cognee
|
||||
from cognee import SearchType
|
||||
|
||||
class CogneeMemoryAgent:
|
||||
"""Agent with graph-vector hybrid persistent memory."""
|
||||
|
||||
def __init__(self, session_id: str = "default"):
|
||||
self.llm_client = OpenAI()
|
||||
self.session_id = session_id
|
||||
|
||||
async def ingest(self, text: str, dataset: str = "main"):
|
||||
await cognee.add(text, dataset)
|
||||
await cognee.cognify([dataset])
|
||||
|
||||
async def recall(self, query: str) -> str:
|
||||
results = await cognee.search(
|
||||
query_text=query,
|
||||
query_type=SearchType.GRAPH_COMPLETION,
|
||||
session_id=self.session_id,
|
||||
)
|
||||
return results[0] if results else ""
|
||||
|
||||
async def chat(self, user_input: str) -> str:
|
||||
context = await self.recall(user_input)
|
||||
messages = [
|
||||
{"role": "system", "content": "You are helpful. Use memory context."},
|
||||
{"role": "system", "content": f"Memory context:\n{context}"},
|
||||
{"role": "user", "content": user_input},
|
||||
]
|
||||
response = self.llm_client.chat.completions.create(
|
||||
model="gpt-4o-mini", messages=messages
|
||||
)
|
||||
reply = response.choices[0].message.content
|
||||
await cognee.add(
|
||||
f"User: {user_input}\nAssistant: {reply}",
|
||||
"conversations"
|
||||
)
|
||||
await cognee.cognify(["conversations"])
|
||||
return reply
|
||||
```
|
||||
|
||||
The memory cycle: ingest, extract, store, retrieve, respond, store again. Each turn enriches the knowledge graph, and incremental processing means you only pay to index new content.
|
||||
|
||||
Session memory handles pronoun resolution automatically:
|
||||
|
||||
```python
|
||||
await cognee.search(query_text="Where does Alice live?", session_id="conv_1")
|
||||
await cognee.search(query_text="What does she do for work?", session_id="conv_1")
|
||||
# "she" resolves to Alice from session context
|
||||
```
|
||||
|
||||
Multi-tenancy is built in at the graph level with per-dataset permissions (read, write, delete, share). Not namespace separation, actual graph-level isolation.
|
||||
|
||||
## The practical path forward
|
||||
|
||||
If you're building an agent today, the real starting question is: **"what does my agent need to remember, and what kind of questions will it answer?"**
|
||||
|
||||
If your queries only need similarity search ("find conversations like this one"), vector-only memory works. The moment queries cross entity boundaries ("Was Alice's project affected by Tuesday's outage?"), you need graph traversal.
|
||||
|
||||
You can wire together separate vector, graph, and relational stores yourself. Teams that go this route typically burn weeks on infrastructure for a memory layer that still doesn't learn from its own usage.
|
||||
|
||||
[Cognee collapses that into four API calls](https://github.com/topoteretes/cognee). Embedded defaults get you running in minutes. Swappable backends (Postgres, Qdrant, Neo4j) take you to production without changing your agent code.
|
||||
|
||||
**Intelligence requires structure, not just storage.** The three storage paradigms (relational, vector, graph) aren't competing options. They're complementary layers of the same memory system. Treating them that way is what turns a stateless LLM wrapper into something that actually learns.
|
||||
|
||||
What's the next thing you'd want your agent to remember tomorrow that it forgot today? Start there.
|
||||
|
||||
**👉** [Check out Cognee on GitHub →](https://github.com/topoteretes/cognee), give it a star, and try wiring it into your next agent.
|
||||
|
||||
Four async calls, a pip install, and you're running.
|
||||
|
||||
That's a wrap!
|
||||
|
||||
If you enjoyed reading this:
|
||||
|
||||
Find me →[@akshay\_pachaar](https://x.com/@akshay_pachaar) ✔️
|
||||
|
||||
Every day, I share tutorials and insights on AI, Machine Learning, and vibe coding best practices.
|
||||
+687
@@ -0,0 +1,687 @@
|
||||
---
|
||||
title: "Building a Prediction Market Trading Bot with Python: From Idea to Deployment"
|
||||
source: "https://x.com/sopersone/status/2045488274915901765"
|
||||
author:
|
||||
- "[[@sopersone]]"
|
||||
published: 2026-04-18
|
||||
created: 2026-04-26
|
||||
description: "Part 6 of 12 Event-Driven Backtesting and Parameter OptimizationIn the previous article, we built a vectorized backtest and compared three ..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
# Part 6 of 12 Event-Driven Backtesting and Parameter Optimization
|
||||
|
||||
In the previous article, we built a vectorized backtest and compared three strategies on real BTC data. Fast, clean, and useful. But this approach has limitations: it does not handle commissions properly, does not model slippage, and does not support complex position management rules.
|
||||
|
||||
In this article, we move to the next level: event-driven backtesting. We will process data bar by bar - the way it actually happens in live trading. We will add commissions and slippage, walk through parameter optimization with grid search, learn to fight overfitting with walk-forward analysis, and get acquainted with the Kelly Criterion for position sizing.
|
||||
|
||||
# Event-Driven vs Vectorized Backtesting
|
||||
|
||||
In a vectorized backtest, we apply operations to the entire data array at once. It is fast, but it means there is no concept of "state" - we simply multiply two arrays and get returns.
|
||||
|
||||
In an event-driven backtest, we step through the data one bar at a time, as if we are inside that moment in time. At each bar:
|
||||
|
||||
1\. We observe new data 2. We check strategy conditions 3. We make a decision: buy, sell, or do nothing 4. We update portfolio state: cash balance, position, trade history
|
||||
|
||||
It is slower, but it lets us model reality accurately: commissions are deducted on every trade, slippage eats into profits, and position sizing shapes the equity curve.
|
||||
|
||||

|
||||
|
||||
# Building the Event-Driven Backtest
|
||||
|
||||
Let us start with a simple but complete implementation. We need three components:
|
||||
|
||||
\- \*\*Portfolio\*\* -- an object that tracks state: cash on hand, current position, trade history
|
||||
|
||||
\- \*\*execute\_trade()\*\* -- a function that simulates order execution accounting for commission and slippage
|
||||
|
||||
\- \*\*run\_backtest()\*\* -- the main loop that steps through bars and calls the strategy
|
||||
|
||||
**The Portfolio Class**
|
||||
|
||||
```text
|
||||
python
|
||||
class Portfolio:
|
||||
"""
|
||||
Tracks the state of a trading account.
|
||||
"""
|
||||
|
||||
def __init__(self, initial_cash=10_000.0, commission=0.001, slippage=0.0005):
|
||||
"""
|
||||
Parameters:
|
||||
initial_cash -- starting capital in USDT
|
||||
commission -- commission per trade (0.001 = 0.1%)
|
||||
slippage -- slippage (0.0005 = 0.05%)
|
||||
"""
|
||||
self.initial_cash = initial_cash
|
||||
self.cash = initial_cash
|
||||
self.position = 0.0 # BTC held in position
|
||||
self.commission = commission
|
||||
self.slippage = slippage
|
||||
self.trades = [] # trade history
|
||||
self.equity_curve = [] # equity curve
|
||||
|
||||
def buy(self, price, date):
|
||||
"""Open a long position using all available cash."""
|
||||
if self.position > 0:
|
||||
return # already in position
|
||||
|
||||
# Slippage: we buy slightly above the price
|
||||
exec_price = price * (1 + self.slippage)
|
||||
|
||||
# Deduct commission
|
||||
commission_cost = self.cash * self.commission
|
||||
btc_amount = (self.cash - commission_cost) / exec_price
|
||||
|
||||
self.position = btc_amount
|
||||
self.cash = 0.0
|
||||
|
||||
self.trades.append({
|
||||
"date": date,
|
||||
"action": "BUY",
|
||||
"price": exec_price,
|
||||
"amount": btc_amount,
|
||||
"cost": commission_cost,
|
||||
})
|
||||
|
||||
def sell(self, price, date):
|
||||
"""Close the position."""
|
||||
if self.position == 0:
|
||||
return # no position to close
|
||||
|
||||
# Slippage: we sell slightly below the price
|
||||
exec_price = price * (1 - self.slippage)
|
||||
|
||||
proceeds = self.position * exec_price
|
||||
commission_cost = proceeds * self.commission
|
||||
self.cash = proceeds - commission_cost
|
||||
self.position = 0.0
|
||||
|
||||
self.trades.append({
|
||||
"date": date,
|
||||
"action": "SELL",
|
||||
"price": exec_price,
|
||||
"amount": 0,
|
||||
"cost": commission_cost,
|
||||
})
|
||||
|
||||
def total_equity(self, current_price):
|
||||
"""Current portfolio value: cash + position at current price."""
|
||||
return self.cash + self.position * current_price
|
||||
|
||||
def record(self, date, current_price):
|
||||
"""Record the current state to the equity curve."""
|
||||
self.equity_curve.append({
|
||||
"date": date,
|
||||
"equity": self.total_equity(current_price),
|
||||
})
|
||||
```
|
||||
|
||||
**The Main Backtest Loop**
|
||||
|
||||
```text
|
||||
python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
from data_loader import fetch_btc_data, add_returns
|
||||
from strategies import sma_crossover_strategy, momentum_strategy, mean_reversion_strategy
|
||||
|
||||
def run_backtest(df_strategy, initial_cash=10_000.0, commission=0.001, slippage=0.0005):
|
||||
"""
|
||||
Event-driven backtest of a strategy.
|
||||
|
||||
Parameters:
|
||||
df_strategy -- DataFrame with a 'position' column (already computed by strategy)
|
||||
initial_cash -- starting capital
|
||||
commission -- commission per trade
|
||||
slippage -- slippage
|
||||
|
||||
Returns:
|
||||
portfolio -- Portfolio object with results
|
||||
equity_df -- DataFrame with the equity curve
|
||||
"""
|
||||
portfolio = Portfolio(initial_cash, commission, slippage)
|
||||
data = df_strategy.dropna(subset=["position"]).copy()
|
||||
|
||||
for date, row in data.iterrows():
|
||||
price = row["close"]
|
||||
position = row["position"]
|
||||
|
||||
if position == 1:
|
||||
portfolio.buy(price, date)
|
||||
elif position == 0:
|
||||
portfolio.sell(price, date)
|
||||
|
||||
portfolio.record(date, price)
|
||||
|
||||
equity_df = pd.DataFrame(portfolio.equity_curve).set_index("date")
|
||||
return portfolio, equity_df
|
||||
```
|
||||
|
||||
**Let us run it:**
|
||||
|
||||
```text
|
||||
python
|
||||
df = fetch_btc_data(interval="1d", lookback="2 years ago UTC")
|
||||
df = add_returns(df)
|
||||
|
||||
df_sma = sma_crossover_strategy(df, fast=20, slow=50)
|
||||
|
||||
portfolio, equity_df = run_backtest(df_sma, initial_cash=10_000)
|
||||
|
||||
print(f"Starting capital: ${portfolio.initial_cash:,.0f}")
|
||||
print(f"Final capital: ${equity_df['equity'].iloc[-1]:,.0f}")
|
||||
print(f"Number of trades: {len(portfolio.trades)}")
|
||||
print(f"Total commissions: ${sum(t['cost'] for t in portfolio.trades):,.2f}")
|
||||
```
|
||||
|
||||
# Commissions and Slippage: How Much Do They Matter
|
||||
|
||||
Let us put some numbers to this and see how costs change the outcome. We run the same backtest with different settings:
|
||||
|
||||
```text
|
||||
python
|
||||
configs = [
|
||||
{"commission": 0.0, "slippage": 0.0, "label": "No costs"},
|
||||
{"commission": 0.001, "slippage": 0.0, "label": "Commission only (0.1%)"},
|
||||
{"commission": 0.001, "slippage": 0.0005, "label": "Commission + slippage"},
|
||||
{"commission": 0.002, "slippage": 0.001, "label": "High costs"},
|
||||
]
|
||||
|
||||
results = {}
|
||||
for cfg in configs:
|
||||
_, eq = run_backtest(df_sma,
|
||||
commission=cfg["commission"],
|
||||
slippage=cfg["slippage"])
|
||||
results[cfg["label"]] = eq
|
||||
|
||||
fig, ax = plt.subplots(figsize=(12, 5))
|
||||
for label, eq in results.items():
|
||||
ax.plot(eq.index, eq["equity"], label=label, linewidth=1.2)
|
||||
|
||||
ax.set_title("Impact of Commissions and Slippage on Returns (SMA 20/50)")
|
||||
ax.set_ylabel("Capital (USDT)")
|
||||
ax.legend()
|
||||
ax.grid(True, alpha=0.3)
|
||||
plt.tight_layout()
|
||||
plt.show()
|
||||
```
|
||||
|
||||

|
||||
|
||||
For SMA Crossover with 8-12 trades per year the difference is small - a 0.1% commission per trade does not add up to much. But for strategies with dozens of trades per month, it is significant. Always account for transaction costs. They can turn a profitable strategy into a losing one.
|
||||
|
||||
# Parameter Optimization: Grid Search
|
||||
|
||||
Every strategy has parameters. For SMA Crossover those are the fast and slow periods. The question is: which values produce the best results?
|
||||
|
||||
One way to answer that is to try every combination and pick the best. This is called a grid search.
|
||||
|
||||
```text
|
||||
python
|
||||
def grid_search_sma(df, fast_range, slow_range, commission=0.001):
|
||||
"""
|
||||
Iterate over all SMA Crossover parameter combinations.
|
||||
Returns a DataFrame with results for each pair.
|
||||
"""
|
||||
results = []
|
||||
|
||||
for fast in fast_range:
|
||||
for slow in slow_range:
|
||||
if fast >= slow:
|
||||
continue # fast SMA must be shorter than slow SMA
|
||||
|
||||
df_strat = sma_crossover_strategy(df, fast=fast, slow=slow)
|
||||
portfolio, equity_df = run_backtest(df_strat, commission=commission)
|
||||
|
||||
final_equity = equity_df["equity"].iloc[-1]
|
||||
total_return = (final_equity / portfolio.initial_cash) - 1
|
||||
|
||||
# Sharpe ratio
|
||||
daily_returns = equity_df["equity"].pct_change().dropna()
|
||||
sharpe = (daily_returns.mean() / daily_returns.std()) * np.sqrt(252) \
|
||||
if daily_returns.std() > 0 else 0
|
||||
|
||||
# Maximum drawdown
|
||||
rolling_max = equity_df["equity"].cummax()
|
||||
max_drawdown = ((equity_df["equity"] - rolling_max) / rolling_max).min()
|
||||
|
||||
results.append({
|
||||
"fast": fast,
|
||||
"slow": slow,
|
||||
"total_return": total_return,
|
||||
"sharpe": sharpe,
|
||||
"max_drawdown": max_drawdown,
|
||||
"trades": len(portfolio.trades),
|
||||
})
|
||||
|
||||
return pd.DataFrame(results)
|
||||
|
||||
# Run the search
|
||||
fast_range = range(5, 51, 5) # 5, 10, 15, ... 50
|
||||
slow_range = range(10, 201, 10) # 10, 20, 30, ... 200
|
||||
|
||||
grid_results = grid_search_sma(df, fast_range, slow_range)
|
||||
|
||||
# Top 10 by Sharpe ratio
|
||||
print(grid_results.sort_values("sharpe", ascending=False).head(10).to_string())
|
||||
```
|
||||
|
||||
**Heatmap of Result**
|
||||
|
||||
Let us visualize how the Sharpe ratio changes across the parameter space:
|
||||
|
||||
```text
|
||||
python
|
||||
import seaborn as sns
|
||||
|
||||
pivot = grid_results.pivot(index="slow", columns="fast", values="sharpe")
|
||||
|
||||
fig, ax = plt.subplots(figsize=(12, 8))
|
||||
sns.heatmap(pivot, annot=False, fmt=".2f", cmap="RdYlGn",
|
||||
center=0, ax=ax, cbar_kws={"label": "Sharpe ratio"})
|
||||
ax.set_title("Sharpe Ratio: SMA Crossover (fast vs slow)")
|
||||
ax.set_xlabel("Fast SMA (days)")
|
||||
ax.set_ylabel("Slow SMA (days)")
|
||||
plt.tight_layout()
|
||||
plt.show()
|
||||
```
|
||||
|
||||

|
||||
|
||||
The heatmap shows that there is no single "best" parameter pair - there are entire regions where the strategy performs well. That is a good sign. If good results were concentrated in just one narrow spot, that would be a clear signal of overfitting.
|
||||
|
||||
# The Overfitting Problem and Walk-Forward Analysis
|
||||
|
||||
Here is the trap with grid search: if you tune parameters on the same data you use to evaluate the result, you end up with a strategy perfectly fitted to the past. On a live market, it will fail.
|
||||
|
||||
This is called \*\*overfitting\*\*.
|
||||
|
||||
The classic solution is to split the data into three parts:
|
||||
|
||||

|
||||
|
||||
\- \*\*Train set\*\* - optimize parameters here (grid search) - \*\*Validation set\*\* - check whether you have overfit - \*\*Test set\*\* - the final evaluation on data you never touched during development
|
||||
|
||||
With financial data there is a key constraint: it is sequential. You cannot shuffle future data in with the past. The split must be strictly chronological.
|
||||
|
||||
**Walk-Forward Analysis**
|
||||
|
||||
Walk-forward is a more realistic version of the same principle. We slide a window across the data:
|
||||
|
||||
1\. Take a training window (for example, 1 year) 2. Optimize parameters on it 3. Test on the next window (for example, 3 months) - this is out-of-sample 4. Shift both windows forward by 3 months 5. Repeat
|
||||
|
||||
The result is a series of out-of-sample tests that together give an honest picture of how the strategy would have performed in real time.
|
||||
|
||||
```text
|
||||
python
|
||||
def walk_forward_analysis(df, fast_range, slow_range,
|
||||
train_months=12, test_months=3,
|
||||
commission=0.001):
|
||||
"""
|
||||
Walk-forward analysis for SMA Crossover.
|
||||
|
||||
At each step:
|
||||
1. Optimize parameters on the train window
|
||||
2. Record the out-of-sample result on the test window
|
||||
"""
|
||||
results_oos = []
|
||||
|
||||
start = df.index[0]
|
||||
end = df.index[-1]
|
||||
|
||||
window_start = start
|
||||
while True:
|
||||
train_end = window_start + pd.DateOffset(months=train_months)
|
||||
test_end = train_end + pd.DateOffset(months=test_months)
|
||||
|
||||
if test_end > end:
|
||||
break
|
||||
|
||||
df_train = df[window_start:train_end]
|
||||
df_test = df[train_end:test_end]
|
||||
|
||||
if len(df_train) < 60 or len(df_test) < 10:
|
||||
window_start += pd.DateOffset(months=test_months)
|
||||
continue
|
||||
|
||||
# --- Optimize on train ---
|
||||
best_sharpe = -np.inf
|
||||
best_fast, best_slow = 20, 50
|
||||
|
||||
for fast in fast_range:
|
||||
for slow in slow_range:
|
||||
if fast >= slow:
|
||||
continue
|
||||
df_s = sma_crossover_strategy(df_train, fast=fast, slow=slow)
|
||||
_, eq = run_backtest(df_s, commission=commission)
|
||||
if len(eq) < 5:
|
||||
continue
|
||||
dr = eq["equity"].pct_change().dropna()
|
||||
sharpe = (dr.mean() / dr.std()) * np.sqrt(252) \
|
||||
if dr.std() > 0 else 0
|
||||
if sharpe > best_sharpe:
|
||||
best_sharpe = sharpe
|
||||
best_fast, best_slow = fast, slow
|
||||
|
||||
# --- Out-of-sample test ---
|
||||
df_s_test = sma_crossover_strategy(df_test, fast=best_fast, slow=best_slow)
|
||||
_, eq_test = run_backtest(df_s_test, commission=commission)
|
||||
|
||||
if len(eq_test) > 0:
|
||||
oos_return = (eq_test["equity"].iloc[-1] / eq_test["equity"].iloc[0]) - 1
|
||||
results_oos.append({
|
||||
"period_start": train_end.date(),
|
||||
"period_end": test_end.date(),
|
||||
"best_fast": best_fast,
|
||||
"best_slow": best_slow,
|
||||
"oos_return": oos_return,
|
||||
})
|
||||
|
||||
window_start += pd.DateOffset(months=test_months)
|
||||
|
||||
return pd.DataFrame(results_oos)
|
||||
|
||||
# Run walk-forward
|
||||
fast_range_wf = range(10, 41, 10)
|
||||
slow_range_wf = range(20, 101, 20)
|
||||
|
||||
wf_results = walk_forward_analysis(df, fast_range_wf, slow_range_wf,
|
||||
train_months=12, test_months=3)
|
||||
print(wf_results.to_string())
|
||||
print(f"\nAverage OOS return per quarter: {wf_results['oos_return'].mean():.2%}")
|
||||
print(f"Percentage of profitable quarters: {(wf_results['oos_return'] > 0).mean():.1%}")
|
||||
```
|
||||
|
||||
Walk-forward takes longer - we run the grid search multiple times. But the results are honest: every out-of-sample period was tested on data that was genuinely "the future" at the time of optimization.
|
||||
|
||||
# The Kelly Criterion: Position Sizing
|
||||
|
||||
Until now our strategy invested the entire available capital in every trade. This is called full Kelly - the most aggressive approach possible. In practice, nobody trades this way.
|
||||
|
||||
The \*\*Kelly Criterion\*\* answers a specific question: what fraction of capital should you risk on each trade to maximize long-term capital growth?
|
||||
|
||||
The Kelly formula for binary outcomes:
|
||||
|
||||
## f = (p \* b - (1 - p)) / b
|
||||
|
||||
where:
|
||||
|
||||
\- \`f\` - fraction of capital to invest - \`p\` - win probability (win rate) - \`b\` - ratio of average win to average loss (win/loss ratio)
|
||||
|
||||
```text
|
||||
python
|
||||
def kelly_fraction(trades_df):
|
||||
"""
|
||||
Computes the Kelly fraction from trade history.
|
||||
|
||||
Parameters:
|
||||
trades_df -- DataFrame with trades (needs a 'pnl' column)
|
||||
|
||||
Returns:
|
||||
kelly_f -- recommended fraction of capital (between 0 and 1)
|
||||
"""
|
||||
wins = trades_df[trades_df["pnl"] > 0]["pnl"]
|
||||
losses = trades_df[trades_df["pnl"] < 0]["pnl"].abs()
|
||||
|
||||
if len(wins) == 0 or len(losses) == 0:
|
||||
return 0.0
|
||||
|
||||
p = len(wins) / len(trades_df) # win rate
|
||||
avg_win = wins.mean()
|
||||
avg_loss = losses.mean()
|
||||
b = avg_win / avg_loss # win/loss ratio
|
||||
|
||||
kelly_f = (p * b - (1 - p)) / b
|
||||
return max(0.0, min(kelly_f, 1.0)) # clip to [0, 1]
|
||||
```
|
||||
|
||||
In practice, traders use \*\*half Kelly\*\*. This delivers roughly 75% of the maximum capital growth but with half the volatility and drawdowns. A sensible trade-off.
|
||||
|
||||
```text
|
||||
python
|
||||
def run_backtest_kelly(df_strategy, initial_cash=10_000.0,
|
||||
commission=0.001, kelly_multiplier=0.5):
|
||||
"""
|
||||
Event-driven backtest with Kelly-based position sizing.
|
||||
"""
|
||||
portfolio = Portfolio(initial_cash, commission)
|
||||
data = df_strategy.dropna(subset=["position"]).copy()
|
||||
|
||||
# First run a standard backtest to estimate Kelly parameters
|
||||
_, eq_base = run_backtest(df_strategy, initial_cash, commission)
|
||||
|
||||
strategy_returns = eq_base["equity"].pct_change().dropna()
|
||||
in_position = df_strategy["position"].reindex(eq_base.index).fillna(0)
|
||||
trade_returns = strategy_returns[in_position == 1]
|
||||
|
||||
if len(trade_returns) > 10:
|
||||
wins = trade_returns[trade_returns > 0]
|
||||
losses = trade_returns[trade_returns < 0].abs()
|
||||
p = len(wins) / len(trade_returns)
|
||||
b = wins.mean() / losses.mean() if len(losses) > 0 else 1.0
|
||||
kelly_f = max(0.0, min((p * b - (1 - p)) / b, 1.0))
|
||||
else:
|
||||
kelly_f = 0.5 # default fallback
|
||||
|
||||
fraction = kelly_f * kelly_multiplier
|
||||
print(f"Kelly fraction: {kelly_f:.2%}, using: {fraction:.2%} of capital")
|
||||
|
||||
# Run the backtest with this fraction
|
||||
cash = initial_cash
|
||||
position = 0.0
|
||||
equity_curve = []
|
||||
|
||||
for date, row in data.iterrows():
|
||||
price = row["close"]
|
||||
signal = row["position"]
|
||||
|
||||
if signal == 1 and position == 0:
|
||||
invest = cash * fraction
|
||||
cost = invest * commission
|
||||
position = (invest - cost) / price
|
||||
cash -= invest
|
||||
|
||||
elif signal == 0 and position > 0:
|
||||
proceeds = position * price
|
||||
cost = proceeds * commission
|
||||
cash += proceeds - cost
|
||||
position = 0.0
|
||||
|
||||
equity_curve.append({
|
||||
"date": date,
|
||||
"equity": cash + position * price,
|
||||
})
|
||||
|
||||
equity_df = pd.DataFrame(equity_curve).set_index("date")
|
||||
return equity_df, kelly_f
|
||||
```
|
||||
|
||||
**Comparison: Full Position vs Half Kelly vs Fixed Fraction**
|
||||
|
||||
```text
|
||||
python
|
||||
fig, ax = plt.subplots(figsize=(12, 5))
|
||||
|
||||
# Full position (as before)
|
||||
_, eq_full = run_backtest(df_sma)
|
||||
ax.plot(eq_full.index, eq_full["equity"],
|
||||
label="Full position (100%)", linewidth=1.2, color="steelblue")
|
||||
|
||||
# Half Kelly
|
||||
eq_hk, kf = run_backtest_kelly(df_sma, kelly_multiplier=0.5)
|
||||
ax.plot(eq_hk.index, eq_hk["equity"],
|
||||
label=f"Half Kelly ({kf*0.5:.0%} of capital)", linewidth=1.2, color="darkorange")
|
||||
|
||||
# Fixed 25%
|
||||
eq_25, _ = run_backtest_kelly(df_sma, kelly_multiplier=0.25)
|
||||
ax.plot(eq_25.index, eq_25["equity"],
|
||||
label="Fixed 25%", linewidth=1.2, color="forestgreen")
|
||||
|
||||
ax.set_title("Position Sizing: Comparing Approaches")
|
||||
ax.set_ylabel("Capital (USDT)")
|
||||
ax.legend()
|
||||
ax.grid(True, alpha=0.3)
|
||||
plt.tight_layout()
|
||||
plt.show()
|
||||
```
|
||||
|
||||

|
||||
|
||||
The comparison makes it clear: the aggressive approach produces higher absolute returns, but with significantly larger drawdowns. Moderate position sizing reduces volatility - and makes the strategy much easier to stick with psychologically.
|
||||
|
||||
# Final Script: Putting It All Together
|
||||
|
||||
Everything goes into \`backtest\_event.py\`:
|
||||
|
||||
```text
|
||||
python
|
||||
"""
|
||||
backtest_event.py -- event-driven backtest with commissions, grid search, and Kelly
|
||||
"""
|
||||
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
from data_loader import fetch_btc_data, add_returns
|
||||
from strategies import sma_crossover_strategy, momentum_strategy, mean_reversion_strategy
|
||||
|
||||
class Portfolio:
|
||||
def __init__(self, initial_cash=10_000.0, commission=0.001, slippage=0.0005):
|
||||
self.initial_cash = initial_cash
|
||||
self.cash = initial_cash
|
||||
self.position = 0.0
|
||||
self.commission = commission
|
||||
self.slippage = slippage
|
||||
self.trades = []
|
||||
self.equity_curve = []
|
||||
|
||||
def buy(self, price, date):
|
||||
if self.position > 0:
|
||||
return
|
||||
exec_price = price * (1 + self.slippage)
|
||||
commission_cost = self.cash * self.commission
|
||||
self.position = (self.cash - commission_cost) / exec_price
|
||||
self.cash = 0.0
|
||||
self.trades.append({"date": date, "action": "BUY",
|
||||
"price": exec_price, "cost": commission_cost})
|
||||
|
||||
def sell(self, price, date):
|
||||
if self.position == 0:
|
||||
return
|
||||
exec_price = price * (1 - self.slippage)
|
||||
proceeds = self.position * exec_price
|
||||
commission_cost = proceeds * self.commission
|
||||
self.cash = proceeds - commission_cost
|
||||
self.position = 0.0
|
||||
self.trades.append({"date": date, "action": "SELL",
|
||||
"price": exec_price, "cost": commission_cost})
|
||||
|
||||
def total_equity(self, price):
|
||||
return self.cash + self.position * price
|
||||
|
||||
def record(self, date, price):
|
||||
self.equity_curve.append({"date": date, "equity": self.total_equity(price)})
|
||||
|
||||
def run_backtest(df_strategy, initial_cash=10_000.0, commission=0.001, slippage=0.0005):
|
||||
portfolio = Portfolio(initial_cash, commission, slippage)
|
||||
data = df_strategy.dropna(subset=["position"]).copy()
|
||||
for date, row in data.iterrows():
|
||||
if row["position"] == 1:
|
||||
portfolio.buy(row["close"], date)
|
||||
elif row["position"] == 0:
|
||||
portfolio.sell(row["close"], date)
|
||||
portfolio.record(date, row["close"])
|
||||
equity_df = pd.DataFrame(portfolio.equity_curve).set_index("date")
|
||||
return portfolio, equity_df
|
||||
|
||||
def grid_search_sma(df, fast_range, slow_range, commission=0.001):
|
||||
results = []
|
||||
for fast in fast_range:
|
||||
for slow in slow_range:
|
||||
if fast >= slow:
|
||||
continue
|
||||
df_s = sma_crossover_strategy(df, fast=fast, slow=slow)
|
||||
_, eq = run_backtest(df_s, commission=commission)
|
||||
if len(eq) < 5:
|
||||
continue
|
||||
dr = eq["equity"].pct_change().dropna()
|
||||
sharpe = (dr.mean() / dr.std()) * np.sqrt(252) if dr.std() > 0 else 0
|
||||
rm = eq["equity"].cummax()
|
||||
mdd = ((eq["equity"] - rm) / rm).min()
|
||||
ret = (eq["equity"].iloc[-1] / 10_000) - 1
|
||||
results.append({"fast": fast, "slow": slow,
|
||||
"sharpe": sharpe, "total_return": ret,
|
||||
"max_drawdown": mdd})
|
||||
return pd.DataFrame(results)
|
||||
|
||||
if __name__ == "__main__":
|
||||
df = fetch_btc_data(interval="1d", lookback="2 years ago UTC")
|
||||
df = add_returns(df)
|
||||
|
||||
# Event-driven backtest for SMA Crossover
|
||||
df_sma = sma_crossover_strategy(df, fast=20, slow=50)
|
||||
portfolio, equity_df = run_backtest(df_sma)
|
||||
|
||||
final = equity_df["equity"].iloc[-1]
|
||||
ret = (final / 10_000) - 1
|
||||
print(f"Final capital: ${final:,.0f}")
|
||||
print(f"Return: {ret:.1%}")
|
||||
print(f"Trades: {len(portfolio.trades)}")
|
||||
|
||||
# Grid search
|
||||
print("\nRunning grid search...")
|
||||
grid = grid_search_sma(df,
|
||||
fast_range=range(5, 51, 5),
|
||||
slow_range=range(10, 201, 10))
|
||||
print("\nTop 5 by Sharpe ratio:")
|
||||
print(grid.sort_values("sharpe", ascending=False).head(5).to_string())
|
||||
```
|
||||
|
||||
Updated project structure:
|
||||
|
||||
```text
|
||||
algobot/
|
||||
data/
|
||||
btc_daily.csv
|
||||
btc_daily.h5
|
||||
data_loader.py
|
||||
strategies.py
|
||||
backtest_vectorized.py
|
||||
backtest_event.py <- new file
|
||||
```
|
||||
|
||||
# Practice Exercise
|
||||
|
||||
Try these on your own:
|
||||
|
||||
1\. Run the event-driven backtest for the momentum strategy (window=20). How does the result compare to the vectorized backtest? How large a role did commissions play?
|
||||
|
||||
2\. Run a grid search for the momentum strategy: sweep the window from 5 to 60 days in steps of 5. Which window gives the best Sharpe ratio?
|
||||
|
||||
3\. Implement a simple train/test split: first 70% of the data is train, last 30% is test. Optimize the SMA on train, then run the best parameters on test. Do the results hold up?
|
||||
|
||||
4\. Compute the Kelly fraction for SMA Crossover from your backtest results. Compare the equity curve under full position vs half Kelly. How much did the maximum drawdown change?
|
||||
|
||||
# Summary
|
||||
|
||||
In this article, we moved from the simplified vectorized backtest to a full event-driven one:
|
||||
|
||||
\- Built a \`Portfolio\` class that simulates a real trading account with commissions and slippage - Implemented an event-driven loop that processes data bar by bar - Saw how transaction costs affect returns in concrete numbers - Wrote a grid search for parameter tuning and learned to read the heatmap - Worked through walk-forward analysis as a tool for fighting overfitting - Got acquainted with the Kelly Criterion and position sizing
|
||||
|
||||
We now have a solid, realistic tool for evaluating strategies. The next step is to teach the bot to predict the market rather than just react to it.
|
||||
|
||||
# Important Disclaimer
|
||||
|
||||
Algorithmic trading involves real financial risk. This series is educational material. It will teach you how to build trading bots, but it does not guarantee profit. Good backtest results do not mean good results on a live market. If you decide to trade with real money, do so with capital you can afford to lose.
|
||||
|
||||
# What Is Next
|
||||
|
||||
In Article 7, we add machine learning. We will take historical BTC data, build features from technical indicators, train logistic regression and random forest models, and find out whether it is possible to predict price direction better than random chance. Spoiler: it is - but with caveats.
|
||||
|
||||
**If you want to try it yourself →** [https://polymarket.com/?r=copy](https://polymarket.com/?r=copy)
|
||||
|
||||
See you in Part 7!
|
||||
+134
@@ -0,0 +1,134 @@
|
||||
---
|
||||
title: "Built in 1.5 Weeks, Saved 1,000+ Hours. Meet Nexus — Deel's Internal App Store."
|
||||
source: "https://x.com/Bouazizalex/status/2048046352022593624"
|
||||
author:
|
||||
- "[[@Bouazizalex]]"
|
||||
published: 2026-04-25
|
||||
created: 2026-04-26
|
||||
description: "We gave everyone at Deel the ability to ship software.Not \"submit a request\" or \"wait for bandwidth.\" Actually ship - in under 5 minutes.Ne..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
We gave everyone at Deel the ability to ship software.
|
||||
|
||||
Not "submit a request" or "wait for bandwidth." Actually ship - in under 5 minutes. Nexus is our internal app store. It was built in 1.5 weeks using Claude Code without a single line of handwritten code. 48 apps are live. One engineer maintains the whole platform.
|
||||
|
||||
## What People Built
|
||||
|
||||
The clearest way to explain Nexus is to show what gets built on it.
|
||||
|
||||
Every new Deel hire submits the same information before day 1 - address, tax details, bank info, emergency contact. For years, this ran on Typeform. HR sent a link, the hire filled it out, and someone downloaded the export, cleaned it up, and manually pushed the data into the systems that needed it. A few minutes per hire - longer when a field meant something different in Brazil than in Germany. At 125 new hires a month across 100+ countries, that's 25 hours of manual data-entry work every month.
|
||||
|
||||
Someone on HR built a Nexus app and eliminated the problem entirely. The form knows which country you're in and asks only what's relevant. Data lands directly where it belongs. The cleanup step is gone.
|
||||
|
||||
When a Deel AE gets off a call with a prospect, someone used to listen back to the recording, write down the requirements, cross-reference SKUs, check availability per country, and put together a scoped proposal by hand. Three to four hours per deal.
|
||||
|
||||
Someone built the AI SE Copilot on Nexus. It reads the call transcript, extracts the hardware requirements, and produces the proposal. Review takes 15 minutes. Proposals that took 3 days now go out the same day.
|
||||
|
||||
Below are some of the tools saving 100+ hours per department, every month.
|
||||
|
||||

|
||||
|
||||

|
||||
|
||||
## From Idea to Production in 5 Minutes
|
||||
|
||||
Deploying an internal app used to take a DevOps engineer 1-3 days. Now it happens while you're getting coffee.
|
||||
|
||||
You open Nexus in your browser, sign in with your Deel account, and point it at a GitHub repo. No second form. No infrastructure menu. No dropdown asking you to pick a database tier.
|
||||
|
||||
Nexus reads your code and figures out what it needs. Database packages in your dependencies? It provisions a database. Storage libraries? File storage appears. The platform infers everything.
|
||||
|
||||
Then three buttons:
|
||||
|
||||
- **Scan** - checks your project against Deel's standards
|
||||
- **Test** - builds it in a clean environment
|
||||
- **Deploy** - ships it
|
||||
|
||||
Your app is live at its own URL, secured, and ready for your team to use.
|
||||
|
||||

|
||||
|
||||
## The Engineering Behind Nexus
|
||||
|
||||
**Step 1: Scan** It verifies whether the repo matches Deel's tech policies.
|
||||
|
||||
1. Fetch all repo files from both default and dev branches in parallel.
|
||||
2. Run seven static checks: package.json, Node v22+, lock file, package manager, next.config, AWS S3 SDK, and database packages.
|
||||
3. Send the file snapshot to Gemini 2.5 Flash at temperature 0.1 to verify the stack.
|
||||
4. Static checks catch about 80% of cases on their own. Static evidence can override a false-positive Gemini rejection, so if next.config exists on disk, the platform approves regardless of what the model says.
|
||||
5. Auto-patch values.yaml on both branches when the scan detects pg or sequelize (enables the database) or [@aws](https://x.com/@aws)\-sdk/client-s3 (enables file storage).
|
||||
|
||||
**Step 2: Test** Builds a production container and verifies it is safe to ship.
|
||||
|
||||
1. Generate a multi-stage Alpine Node Dockerfile targeting next build --standalone.
|
||||
2. Commit the Dockerfile to the dev branch.
|
||||
3. Dispatch a GitHub Actions workflow that runs npm ci && npm run build.
|
||||
4. Poll until the workflow completes.
|
||||
5. On failure, Gemini 2.5 Flash diagnoses the logs and returns a root cause with a concise fix.
|
||||
|
||||
**Step 3: Deploy** Twelve sequential sub-steps provision every piece of production infrastructure.
|
||||
|
||||
1. Commit the Dockerfile and patch next.config for standalone output.
|
||||
2. Create an AWS ECR repo with a lifecycle policy that keeps three images.
|
||||
3. Generate the ArgoCD Application manifest and commit it to argocd/{name}.yaml.
|
||||
4. Push all env vars to AWS Secrets Manager as JSON, so secrets never touch Git.
|
||||
5. Generate values.yaml with image URI, resource limits, ingress, and optional DB or S3 config.
|
||||
6. Write .github/workflows/ci.yml using OIDC federation, so no long-lived AWS keys sit anywhere.
|
||||
7. Assign the project an https://{name}.dp.com URL.
|
||||
8. Create and merge the setup PR into dev, then delete the setup branch.
|
||||
9. Merge dev into main and register the ArgoCD app.
|
||||
10. Create a filtered merge that includes only user code, excluding helm/, .github/, and the Dockerfile, so user PRs can never overwrite platform infrastructure.
|
||||
11. ArgoCD watches main/helm/ and auto-syncs to Kubernetes with CreateNamespace=true, auto-prune, and self-heal.
|
||||
12. Pod is live in <5 mins end-to-end.
|
||||
|
||||
**Failure diagnosis** It uses two AI paths, both using Gemini 2.5 Flash with structured JSON output.
|
||||
|
||||
- **Build failures.** Nexus sends the GitHub Actions logs with a prompt asking for root cause and a concise fix, at temperature 0.2.
|
||||
- **ArgoCD deploy failures.** Nexus sends the ArgoCD condition type, the message, and three files (values.yaml, Dockerfile, ci.yml) through the same path, at temperature 0.1. Near-deterministic by design.
|
||||
|
||||
**Security** There is layered security, applied by default which cannot be skipped.
|
||||
|
||||
- **Auth.** Google OAuth with [@deel](https://x.com/@deel).com domain enforcement at login.
|
||||
- **Sessions.** JWT with 8-hour TTL. Admin status refreshed every five minutes.
|
||||
- **Tenancy.** Every API route calls findProjectForUser(). No cross-tenant access.
|
||||
- **Secrets.** Env vars live in AWS Secrets Manager, synced into Kubernetes through the ExternalSecret operator. Never in Git.
|
||||
- **Isolation.** Every project gets its own namespace with resource limits. CPU 100m to 500m, memory 256Mi to 512Mi.
|
||||
- **CI/CD.** GitHub Actions uses OIDC federation via aws-actions/configure-aws-credentials@v4. No long-lived keys are stored anywhere.
|
||||
- **Network.** VPN enforcement at the network level. All \*.dp.com endpoints are internal-only by design.
|
||||
|
||||
**Supported stack today**
|
||||
|
||||
- Next.js App Router
|
||||
- TypeScript or JavaScript
|
||||
- Node v22+
|
||||
- npm or pnpm (auto-detected)
|
||||
- Optional Postgres via Sequelize
|
||||
- Optional AWS S3
|
||||
- Auto-generated Alpine Dockerfile
|
||||
- GitHub Actions for CI/CD
|
||||
- Kubernetes through ArgoCD and Helm
|
||||
|
||||
The three steps today are a safety measure, because steps 1 and 2 are what make step 3 succeed 99% of the time. The whole “deploy” runs in two to five minutes. A single click will replace the three steps in the near future.
|
||||
|
||||
## What It's Actually Worth
|
||||
|
||||
Every tool on Nexus started as a problem someone was living with - one that never got fixed because the cost of building the solution was higher than the cost of tolerating it.
|
||||
|
||||
That calculation hits harder at a remote-first company operating across 100+ countries, where every handoff crosses a timezone. Nexus removes the handoff. Someone in São Paulo ships at 2pm without waiting for San Francisco to wake up.
|
||||
|
||||

|
||||
|
||||
## The New Moat
|
||||
|
||||
48 apps is the surface count. What they actually represent is 48 pieces of institutional knowledge that used to live inside someone's head and now live inside production software. Years of tribal knowledge, encoded. Anyone can use them in a single click.
|
||||
|
||||
You can't buy this from a vendor. No off-the-shelf platform ships with workflows tuned to how Deel actually operates. The tools are valuable precisely because they're specific to us.
|
||||
|
||||
Most companies die by a thousand cuts - hundreds of tiny frictions, each one too small to justify fixing, collectively draining enormous amounts of time and energy. This is the default state of a scaling company.
|
||||
|
||||
Nexus made the cost of fixing them nearly zero.
|
||||
|
||||
So they're getting fixed. Every new app raises the baseline for the team using it. And every week there are more of them.
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
title: "Chief Product Officer in a Box: Introducing The AI PM OS"
|
||||
source: "https://x.com/nurijanian/status/2033111195121865207"
|
||||
author:
|
||||
- "[[@nurijanian]]"
|
||||
published: 2026-03-15
|
||||
created: 2026-04-26
|
||||
description: "I’ve been tracking Cursor use for PM work across Reddit, X, and a few video sources. The same handful of patterns keep showing up.Dennis Yan..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
## I’ve been tracking Cursor use for PM work across Reddit, X, and a few video sources. The same handful of patterns keep showing up.
|
||||
|
||||
**Dennis Yang’s workflow at Chime:** PRDs written in markdown inside Cursor, published to Confluence via an MCP server connection, with Jira epics auto-generated from the spec. Weekly status reports drafted in a few minutes from the same source files. He described it as reducing his documentation overhead significantly, which is believable: if your spec is already in the same environment as your AI, you stop copy-pasting between tabs.
|
||||
|
||||
[https://youtu.be/rwmR7m5rvqw](https://youtu.be/rwmR7m5rvqw)
|
||||
|
||||
**Zevi Arnovitz at Meta:** No technical background. He runs Claude for planning, Gemini for UI generation, and then has both models review each other’s output before shipping. His engineers now ask him to teach them his process. He built the peer review loop from scratch through trial and error, and the output is good enough that his team follows his lead.
|
||||
|
||||
[https://www.youtube.com/watch?v=1em64iUFt3U](https://www.youtube.com/watch?v=1em64iUFt3U)
|
||||
|
||||
[Alan Wright](https://alaniswright.com/blog/using-cursor-and-mcp-as-a-product-manager/)**:** He queried PostHog directly inside Cursor, had the AI diagnose what the data showed, produce a markdown summary of the finding, push it to Notion, and open a Linear ticket from it. Something that used to take hours now takes a few minutes. He wrote it up on his site. Most PMs reading his post probably thought: “I’d love to do that, but I don’t know where to start.”
|
||||
|
||||
**The scale of what’s happening:** This spring, [Y Combinator named “Cursor for Product Management” as a Request for Startups category](https://www.ycombinator.com/rfs), meaning they’re actively looking to fund companies building in this space.
|
||||
|
||||
## The part that none of the videos mention
|
||||
|
||||
None of these write-ups mention what it actually takes to get there.
|
||||
|
||||
Yang, Arnovitz, and Wright all built their setups from scratch, through trial and error, over weeks.
|
||||
|
||||
Each spent real time on the plumbing before they could do any of the interesting work.
|
||||
|
||||
Watching a 45-minute podcast episode and then going off to build what Dennis built takes days, weeks — if you know what you’re doing.
|
||||
|
||||
Cursor opens with an empty file and no direction for PM work; you have to know what context to load, which workflow to follow, and what prompts to use at each step.
|
||||
|
||||
What many forward-thinking PMs are still missing is not even where to start with Cursor or Claude Code — it is how to get to a working system fast enough.
|
||||
|
||||
## AI PM OS: the system, already built
|
||||
|
||||
[AI PM OS](https://www.prodmgmt.world/products/pm-os?utm_source=x&utm_medium=social&utm_campaign=cursor_pm_os_150326utm_content=title) started as my own attempt to solve this.
|
||||
|
||||

|
||||
|
||||
It’s a pre-configured operating system for PM work inside Cursor, mapping directly to what Yang, Arnovitz, and Wright each had to build by hand, enriched by all the good PM juice that I had inside my Notion-based Complete PM Bundle.
|
||||
|
||||

|
||||
|
||||
The setup takes about five minutes:
|
||||
|
||||
**Run** /start**.** The AI asks you questions about your company, product, team, goals, and constraints and fills in five context files as you answer. Every response after that draws on those files. This is what Dennis Yang was describing when he talked about the AI that “knows your product.” In PM OS, that knowledge lives in COMPANY.md, PRODUCTS.md, GOALS.md, TEAM.md, and CONSTRAINTS.md. You fill them once, and every workflow uses them automatically.
|
||||
|
||||
**190+ skills auto-trigger.** You don’t have to remember to prompt or even bring your own prompt library. The skills activate based on what you’re doing. This is the prompt library that I know others maintain as individual files, already pre-installed and wired up.
|
||||
|
||||

|
||||
|
||||
**7 structured workflows.** These cover the PM work that actually repeats: strategy, research, decisions, stakeholder communication, opportunity framing, assumption testing, and meeting prep. Each one walks you through the work in the right sequence, rather than leaving you to design the process from scratch.
|
||||
|
||||

|
||||
|
||||
**The** [Lenny Podcast MCP](https://github.com/akshayvkt/lenny-mcp) **& my favourite external skills are pre-installed.** The knowledge source most PMs reference is already connected. You can query specific episodes, pull frameworks, and reference content without leaving your workflow.
|
||||
|
||||
You also have the [Shaping skills](https://github.com/rjs/shaping-skills) and the [Frontend-Slides skills](https://github.com/zarazhangrui/frontend-slides) pre-installed ready to use. I love them, and I can’t live without them now!
|
||||
|
||||

|
||||
|
||||
The difference between PM OS and what others have built is that you can have it today - you don’t need months to experiment, you don’t need to populate it with frameworks, techniques, skills, examples and all that good stuff I’ve been sharing for years.
|
||||
|
||||
You just open Cursor, run /start, and you’re in.
|
||||
|
||||
# → Get PM OS
|
||||
@@ -0,0 +1,322 @@
|
||||
---
|
||||
title: "DESIGN.md | The One File AI Needs to Match Your UI"
|
||||
source: "https://x.com/nurijanian/status/2048327986777350425"
|
||||
author:
|
||||
- "[[@nurijanian]]"
|
||||
published: 2026-04-26
|
||||
created: 2026-04-26
|
||||
description: "A year ago, PMs worried they could not get from idea to screen. Now they can get ten screens in ten minutes, and the problem is whether any ..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
A year ago, PMs worried they could not get from idea to screen. Now they can get ten screens in ten minutes, and the problem is whether any of them look like the same product.
|
||||
|
||||
Ask an agent for a settings screen, an onboarding modal, a dashboard, and a pricing page. Each one may look fine in isolation. Put them together and you get four different products wearing the same logo.
|
||||
|
||||
Designers solved this years ago with design systems.
|
||||
|
||||

|
||||
|
||||
Agents need something similar, but Figma is mostly invisible to them and brand PDFs are worse. DESIGN.md puts the rules where agents actually look: in text, inside the repo.
|
||||
|
||||
Google’s Stitch team describes it as a plain-text design system document for AI agents. It sits in your project and tells the agent how the product should look and feel: colors, type, spacing, component rules, layout principles, and the do’s and don’ts that keep screens from wandering off.
|
||||
|
||||

|
||||
|
||||
**AGENTS.md is the closest comparison.**
|
||||
|
||||
- README.md tells humans what the project is.
|
||||
- AGENTS.md tells coding agents how to work inside the repo.
|
||||
|
||||
**DESIGN.md tells design and coding agents what the product should look like.**
|
||||
|
||||
## What DESIGN.md contains
|
||||
|
||||
A DESIGN.md file has two layers.
|
||||
|
||||
1. The first is machine-readable YAML: colors, type, radius, spacing, component references, and exact component properties.
|
||||
2. The second is human-readable markdown: what the interface should feel like, which colors do which jobs, how layout behaves, which component patterns are allowed, and which ones should never appear.
|
||||
|
||||

|
||||
|
||||
Agents need values and reasons.
|
||||
|
||||
Pure prose gives the agent mood words: “clean,” “premium,” “friendly,” “modern.” Most of those words are useless until you attach them to decisions.
|
||||
|
||||
Pure tokens give the agent values without judgment. A hex code does not tell the agent whether that color should appear on every button, only on the primary action, or never on a background.
|
||||
|
||||
With both, the agent gets exact values, humans get the reasons, and the PM, designer, engineer, and agent have one thing to argue over.
|
||||
|
||||
You do not have to pretend to be the designer. You just have to write down enough product judgment that the agent stops freelancing.
|
||||
|
||||
## The PM version of the problem
|
||||
|
||||
Most PMs already know the pain this solves.
|
||||
|
||||

|
||||
|
||||
You ask for a prototype and the output looks “pretty good.” Then a designer looks at it and sees the problems:
|
||||
|
||||
- Wrong radius
|
||||
- Wrong font weight
|
||||
- Wrong CTA hierarchy
|
||||
- Too much accent color
|
||||
- New card style invented for no reason
|
||||
- Form fields that do not match the product
|
||||
- Mobile layout that breaks like a spreadsheet
|
||||
- Empty state that sounds like a SaaS brochure
|
||||
|
||||
None of these are catastrophic alone.
|
||||
|
||||
Together, they make the product feel fake.
|
||||
|
||||
The agent did what you asked with incomplete context.
|
||||
|
||||
I think this is the part PMs need to get used to. When AI makes UI cheap, the hard part moves from generating the screen to knowing whether the screen belongs in the product.
|
||||
|
||||
Once AI does more of the making, PM judgment matters more.
|
||||
|
||||
Also, many UI leaves are exactly the kind of work an agent can draft if everyone knows what “good” is supposed to look like. (There’s a skill in my PM OS for identifying these leaves, by the way. Scroll to the bottom when done reading.)
|
||||
|
||||
## How to apply it
|
||||
|
||||
Create a DESIGN.md before you ask the agent to build UI.
|
||||
|
||||
In practice, I would do it this way.
|
||||
|
||||
1\. Start from a real source
|
||||
|
||||
Begin somewhere more specific than “make it beautiful.”
|
||||
|
||||
Use one concrete source:
|
||||
|
||||
- Your existing app
|
||||
- A public marketing site
|
||||
- A Figma file
|
||||
- A screenshot of a screen you like
|
||||
- A reference DESIGN.md from a collection like awesome-design-md or getdesign.md
|
||||
|
||||
If the product already exists, ask the agent to infer the first draft from the current UI. If the product is new, pick a reference direction first.
|
||||
|
||||
2\. Capture decisions, not vibes
|
||||
|
||||

|
||||
|
||||
A weak DESIGN.md says:
|
||||
|
||||
- Minimal
|
||||
- Premium
|
||||
- Clean
|
||||
- Friendly
|
||||
|
||||
A stronger DESIGN.md says:
|
||||
|
||||
- Use one accent color per screen, reserved for the main action.
|
||||
- Body text should stay at 15-16px with line height above 1.4.
|
||||
- Cards use border and surface contrast instead of heavy shadows.
|
||||
- Primary buttons are filled. Secondary actions are text or outline.
|
||||
- Empty states should be direct and functional, with restraint around playfulness.
|
||||
- Tables should prioritize scan speed over decorative spacing.
|
||||
- Mobile screens should collapse secondary metadata before primary actions.
|
||||
|
||||
PMs can help here because even without the final shadow token, they can still name the product judgment: dense or spacious, playful or sober, action-heavy or review-heavy, consumer-feeling or enterprise-feeling, expressive or quiet.
|
||||
|
||||
3\. Fill the sections agents use
|
||||
|
||||
Google’s basic shape:
|
||||
|
||||
- Overview, colors, typography, layout
|
||||
- Elevation, shapes, components
|
||||
- Do’s and don’ts
|
||||
|
||||
The spec allows unknown sections, which is useful because products have weird constraints.
|
||||
|
||||
For example, a B2B workflow product might need:
|
||||
|
||||
- Data density rules
|
||||
- Table behavior
|
||||
- Error-state tone
|
||||
- AI confidence display rules
|
||||
|
||||
A consumer app might need:
|
||||
|
||||
- Image treatment
|
||||
- Motion rules
|
||||
- Empty-state personality
|
||||
|
||||
Bad output is easier to spot when the rule is written down.
|
||||
|
||||
4\. Make the agent cite the file back to you
|
||||
|
||||
The underused move is making the agent cite the file back to you.
|
||||
|
||||
Attaching DESIGN.md and hoping is too passive.
|
||||
|
||||
After the agent generates a screen, ask it to review its own output against the file.
|
||||
|
||||
Use prompts like:
|
||||
|
||||
- List the DESIGN.md rules this screen follows.
|
||||
- List any places where this screen invented a new pattern.
|
||||
- Compare the button, card, input, typography, spacing, and mobile behavior against DESIGN.md.
|
||||
- Before changing the UI, state which section of DESIGN.md justifies the change.
|
||||
- If DESIGN.md is silent, say so and ask whether to extend the file.
|
||||
|
||||
The last prompt is where the file becomes alive. When a new product decision appears, you can either treat it as a one-off or add it back into the system.
|
||||
|
||||
5\. Pair it with human review
|
||||
|
||||
Think of DESIGN.md as writing down the decisions you do not want the agent to keep remaking.
|
||||
|
||||
It cannot tell you whether the product should feel more like Linear, Notion, Ramp, Workday, or something else entirely. It cannot decide what the screen should make the user feel.
|
||||
|
||||
The file does a narrower job. It stops the agent from making every screen feel like a new product.
|
||||
|
||||
Expecting the file to replace designers is the wrong read. The better use is letting designers and PMs encode decisions once so agents stop re-litigating them screen by screen.
|
||||
|
||||
## The PM checklist for DESIGN.md
|
||||
|
||||
If I were adding DESIGN.md to a PM workflow, I would use this checklist.
|
||||
|
||||
Use it for four kinds of work: prototypes, UI leaves in a codebase, new agent sessions, and PM-designer alignment.
|
||||
|
||||
It also makes design QA less personal. Instead of saying “this feels off,” reviewers can point to the file: CTA hierarchy violates the color rule, the card invented a new elevation pattern, the mobile layout dropped the wrong metadata, the empty-state copy broke the tone rule.
|
||||
|
||||
Before creating it
|
||||
|
||||
Answer the setup questions first:
|
||||
|
||||
- What product surface will this govern?
|
||||
- Which existing screen is the best taste anchor?
|
||||
- Which screen is the warning example?
|
||||
- Is this for exploration, production code, or review only?
|
||||
- Does the team already have Figma tokens, Tailwind config, brand rules, or component docs?
|
||||
|
||||
A DESIGN.md for exploration can be loose. A DESIGN.md for production UI should be stricter, especially around accessibility, component states, and responsive behavior.
|
||||
|
||||
What the file must include
|
||||
|
||||

|
||||
|
||||
At minimum:
|
||||
|
||||
- Overview: what the product should feel like, in plain language
|
||||
- Color roles: hex values plus jobs for each color
|
||||
- Typography and spacing: sizes, weights, line heights, density, rhythm
|
||||
- Components and states: buttons, inputs, cards, navigation, tables, empty, loading, error, disabled
|
||||
- Layout and responsive behavior: grids, max widths, gutters, what collapses, what stays visible
|
||||
- Accessibility: contrast, keyboard navigation, focus styles, motion limits
|
||||
- Do’s and don’ts: the fastest way to stop every generated screen from feeling new
|
||||
|
||||
The do’s and don’ts are probably the most PM-friendly section.
|
||||
|
||||
They let you encode judgment in normal language:
|
||||
|
||||
- Do keep one obvious primary action per screen.
|
||||
- Do preserve scan speed on operational pages.
|
||||
- Do use empty states to help the user take the next action.
|
||||
- Don’t create a new button style without updating this file.
|
||||
- Don’t use accent color for decoration.
|
||||
- Don’t hide approval, review, or destructive actions inside low-contrast menus.
|
||||
- Don’t make dense B2B workflows feel like a consumer landing page.
|
||||
|
||||
A PM should be willing to write a sentence that specific.
|
||||
|
||||
How to use it in prompts
|
||||
|
||||
Put DESIGN.md in the prompt and make the agent prove it followed the file:
|
||||
|
||||
- For generation: Read DESIGN.md first. If the request conflicts with the file, explain the conflict before generating.
|
||||
- For implementation: Use existing components where possible. If a new pattern is needed, explain why DESIGN.md does not cover it.
|
||||
- For review: Return only mismatches, missing states, accessibility risks, responsive issues, and places where the design invented a new pattern.
|
||||
|
||||
This makes the agent show its work instead of returning a screen that is somehow “cleaner” but still wrong. PMs can work with that.
|
||||
|
||||
When to update it
|
||||
|
||||
Update DESIGN.md when:
|
||||
|
||||
- A new component pattern appears twice
|
||||
- A designer changes the visual direction
|
||||
- A PM notices repeated agent mistakes
|
||||
- A review comment keeps coming back
|
||||
- A feature area needs different density rules
|
||||
- A mobile pattern diverges from desktop
|
||||
- The team decides a one-off pattern should become standard
|
||||
|
||||
Avoid updating it for every preference fight.
|
||||
|
||||
One person disliking a card radius is feedback. Three screens inventing three different card radii is a system problem.
|
||||
|
||||
The failure modes
|
||||
|
||||

|
||||
|
||||
Most bad DESIGN.md files fail in predictable ways:
|
||||
|
||||
- Too vague: “modern and clean,” “beautiful enterprise UI,” “simple and intuitive”
|
||||
- Too visual without being operational: colors with no roles, typography with no usage rules, components with no states
|
||||
- Too rigid: every section over-specified, no room for product-specific exceptions, no rule for what happens when the file is silent
|
||||
- Disconnected from real screens: written from brand theory, never tested against agent output, no bad examples documented
|
||||
|
||||
Boring is a feature here. Common design decisions should repeat, and genuinely hard product decisions still belong with humans.
|
||||
|
||||
## The PM takeaway
|
||||
|
||||
I think the point is simple: PMs are going to give agents more UI work, and the good teams will stop treating taste like something everyone can remember.
|
||||
|
||||
DESIGN.md is one way to write it down without turning every prompt into a 900-word reminder.
|
||||
|
||||
One file in the repo means humans can read it, agents can use it, and the product can change without everyone relying on memory.
|
||||
|
||||
Pick one product surface you own and ask an agent to draft a DESIGN.md from the existing UI. Then review it with your designer or engineering partner and fix the parts that are too vague.
|
||||
|
||||
After that, use it on one small UI task.
|
||||
|
||||
If the output improves, keep going. If it does not, good, now you can see exactly what your design system never spelled out.
|
||||
|
||||
[Here is a great resource with some example DESIGN.md files](https://getdesign.md/).
|
||||
|
||||
If the next question is “how do I make this repeatable?”, PM OS gives you the setup: 200+ skills, 10 workflows, and the Cursor/Claude Code scaffolding to run agent workflows without rebuilding the process every time.
|
||||
|
||||

|
||||
|
||||
## AI PM OS v1.8.0 — Project-Based Organization
|
||||
|
||||
PM OS now organizes work around projects, not document types.
|
||||
|
||||
Before v1.8, strategy docs, research, PRDs, decisions, and measurements could end up scattered across separate folders. Now, each project gets one home in 📂 Context/Work/{project-slug}/, so every artifact for an initiative stays together.
|
||||
|
||||
**What’s New**
|
||||
|
||||
- Create and manage project folders with /project: create, list, switch, view the current project, or archive completed work.
|
||||
- Keep workflow outputs together automatically. Strategy, research, assumptions, decisions, meetings, measurements, and reviews now save into the active project folder.
|
||||
- Start new work faster. When you describe a new initiative, PM OS can notice that no project exists yet and offer to create one before the workflow starts.
|
||||
- Pick up where you left off. Project-scoped workflows now do a lightweight prior-work scan, so the agent can reference recent artifacts in the current project before asking what you want to do next.
|
||||
- Tune the AI’s voice with the new optional 📂 Context/MY\_STYLE.md file. Set preferred format, depth, tone, writing notes, decision lens, and time horizon without changing the core PM OS rules.
|
||||
- **New: 3 standalone skills for messy work**PM OS now includes 212 skills, including three new standalone tools for problems that do not need a full workflow. **Corporate Misalignment Finder** helps you diagnose why teams are stuck: unclear goals, missing facts, broken decision process, fuzzy authority, or decisions that never get captured. Based on [Robert’s Rules of Order Newly Revised: 12th Edition](https://books.google.co.nz/books/about/Robert_s_Rules_of_Order_Newly_Revised_De.html?id=2Uc9ygEACAAJ&source=kp_book_description&redir_esc=y) **Vibe Code Leaf Finder** helps you see where AI can safely edit a codebase, where it needs guardrails, and where an engineer should stay in control. Based on this [Anthropic talk.](https://youtu.be/fHWFF_pnqDk?si=Ol89gef0twxCvtLt) **Workflow Trellis** helps you turn messy interviews, customer research, or operational notes into a map of the real workflow: obligations, fragments, handoffs, automation opportunities, and exception queues. Useful especially for B2B SaaS PMs.Use them directly with /skill, or describe the situation in plain language and PM OS will route to the right one.
|
||||
|
||||
**Improved**
|
||||
|
||||
- /tidy is now project-aware. It detects artifacts sitting at Work/ root or in legacy folders like PRDs/, Research/, Strategy/, and offers to route them into the right project folder.
|
||||
- /tidy reminders are more reliable. The hook now works even before the first tidy run, checks for orphaned files, and uses a 12-hour freshness window.
|
||||
- /start now offers optional setup for communication style and first project creation.
|
||||
- /migrate now works as a proper slash command in both Cursor and Claude Code.
|
||||
- Migration no longer silently creates legacy type-based Work folders. It preserves existing files, warns when legacy folders contain content, and lets /tidy handle routing safely.
|
||||
- Migration now removes empty iCloud “ 2” duplicate folders created by sync conflicts, while preserving any non-empty user data.
|
||||
|
||||
**Fixed**
|
||||
|
||||
- Fixed Claude Code not recognizing /migrate as a slash command.
|
||||
- Fixed /tidy reminder behavior when no tidy state file existed yet.
|
||||
- Fixed migration cleanup for empty iCloud conflict folders after emoji-folder upgrades.
|
||||
|
||||
**Upgrade Notes**
|
||||
|
||||
Run /migrate from an existing v1.7.x project. Your 📂 Context/ files are preserved. Existing legacy Work folders stay in place until you move them manually or run /tidy.
|
||||
|
||||
# This release updates PM OS to 1.8.0.
|
||||
|
||||
# Upgrade your PM setup with PM OS 1.8
|
||||
@@ -0,0 +1,344 @@
|
||||
---
|
||||
title: "Decoding DeepSeek-V4"
|
||||
source: "https://x.com/amitiitbhu/status/2047570591021146510"
|
||||
author:
|
||||
- "[[@amitiitbhu]]"
|
||||
published: 2026-04-24
|
||||
created: 2026-04-24
|
||||
description: "In this blog, we will learn about DeepSeek-V4, the new family of open Mixture-of-Experts language models that natively supports a one-millio..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
In this blog, we will learn about DeepSeek-V4, the new family of open Mixture-of-Experts language models that natively supports a one-million-token context with dramatically lower inference cost.
|
||||
|
||||
DeepSeek-V4 makes one-million-token context roughly a tenth as expensive as it was in DeepSeek-V3.2. It introduces a new attention design, a new way of doing residual connections, a new optimizer, and a new post-training pipeline. We will decode each of these one by one.
|
||||
|
||||
We will cover the following:
|
||||
|
||||
- The Big Picture
|
||||
- Two Models: DeepSeek-V4-Pro and DeepSeek-V4-Flash
|
||||
- Hybrid Attention with CSA and HCA
|
||||
- Manifold-Constrained Hyper-Connections (mHC)
|
||||
- Muon Optimizer
|
||||
- FP4 Quantization-Aware Training
|
||||
- Pre-Training
|
||||
- Post-Training: Specialist Training and On-Policy Distillation
|
||||
- Reasoning Modes
|
||||
- Putting It All Together
|
||||
- Quick Summary
|
||||
|
||||
I’m **Amit Shekhar** from [Outcome School](https://outcomeschool.com/), where I teach [AI and Machine Learning](https://outcomeschool.com/program/ai-and-machine-learning).
|
||||
|
||||
Let's get started.
|
||||
|
||||
## The Big Picture
|
||||
|
||||
Before we go into the details, let's understand the big picture.
|
||||
|
||||
DeepSeek-V4 is built to solve one core problem: **make ultra-long context cheap**. Modern reasoning models and AI Agents need to handle very long inputs - long documents, long tool histories, long agent trajectories. The standard attention mechanism in a Transformer becomes very expensive as the input gets longer. DeepSeek-V4 redesigns attention so that even a one-million-token input remains practical.
|
||||
|
||||
In simple words:
|
||||
|
||||
**DeepSeek-V4 = DeepSeek-V3 + Hybrid Compressed Attention + Better Residual Connections + Muon Optimizer + On-Policy Distillation.**
|
||||
|
||||
Let's put this into perspective with real numbers. At a one-million-token context:
|
||||
|
||||
- DeepSeek-V4-Pro uses only **27%** of the per-token compute of DeepSeek-V3.2.
|
||||
- DeepSeek-V4-Pro uses only **10%** of the KV cache size of DeepSeek-V3.2.
|
||||
- DeepSeek-V4-Flash uses only **10%** of the per-token compute and **7%** of the KV cache size of DeepSeek-V3.2.
|
||||
|
||||
This is a massive efficiency gain. Now, let's decode each piece.
|
||||
|
||||
## Two Models: DeepSeek-V4-Pro and DeepSeek-V4-Flash
|
||||
|
||||
DeepSeek-V4 ships as two models. Both are [Mixture-of-Experts (MoE)](https://outcomeschool.com/blog/mixture-of-experts) models. In an MoE model, the feed-forward layer is split into many small expert networks, and a router picks only a few experts per token. This is how the total parameter count can be huge while the per-token compute stays small.
|
||||
|
||||
Let me tabulate the differences between the two models for your better understanding so that you can decide which one to use based on your use case.
|
||||
|
||||

|
||||
|
||||
Here, "activated" means the parameters that actually run for each input token. In an MoE model, only a small fraction of the experts are active per token, so activated parameters are much smaller than total parameters.
|
||||
|
||||
Both models support a context of **one million tokens** natively. Both are trained on more than 32 trillion tokens.
|
||||
|
||||
DeepSeek-V4-Pro is the larger, more capable model. DeepSeek-V4-Flash is the smaller, faster, more cost-efficient model.
|
||||
|
||||
## Hybrid Attention with CSA and HCA
|
||||
|
||||
This is the most important change in DeepSeek-V4. Let's understand the problem first.
|
||||
|
||||
**The Problem.** Standard attention compares every query token with every other token. Suppose we have N tokens in the input. The cost grows like N x N. At one million tokens, this becomes one trillion comparisons across the full sequence. The KV cache, which is the memory of past keys and values, also grows linearly with N. Both of these become a serious bottleneck for long context.
|
||||
|
||||
We have a detailed blog on [KV Cache in LLMs](https://outcomeschool.com/blog/kv-cache-in-llms) that explains what KV cache is and why it matters.
|
||||
|
||||
**The Solution.** Here comes the hybrid attention design to the rescue. DeepSeek-V4 introduces two new attention types and uses both of them in an interleaved manner across layers:
|
||||
|
||||
- **CSA (Compressed Sparse Attention)** - lighter compression, but uses sparse selection.
|
||||
- **HCA (Heavily Compressed Attention)** - heavier compression, but keeps attention dense.
|
||||
|
||||
Let's decode the names first.
|
||||
|
||||
**CSA = Compressed + Sparse + Attention.**
|
||||
|
||||
**HCA = Heavily + Compressed + Attention.**
|
||||
|
||||
The best way to learn this is by taking an example. Let's say we are reading a huge library of one million pages and we want to answer a question. Standard attention is like reading every single page from start to end before answering. It works, but it is painfully slow.
|
||||
|
||||
CSA and HCA both fix this, but in different ways. We will use this library example throughout to understand both. Let's decode each one.
|
||||
|
||||
CSA: Compressed Sparse Attention
|
||||
|
||||
CSA does two things to make attention cheap.
|
||||
|
||||
**Step 1: Compress.** Instead of keeping the KV cache for every single token, CSA combines every **m** consecutive tokens into one compressed entry using learned softmax weights. Just for the sake of understanding, let's say **m = 4**. So every 4 tokens get combined into 1 entry in the KV cache. The KV cache shrinks by a factor of **m**.
|
||||
|
||||
In our library example, this is like grouping every 4 pages into one summary card. Instead of reading 1 million pages, we now have only 250K summary cards to look at.
|
||||
|
||||
**Step 2: Select.** After compression, CSA still does not look at every summary card. It uses a small **Lightning Indexer** to score each compressed entry against the current query, and then picks only the top-k most relevant ones. The Lightning Indexer runs in FP4 precision to keep this scoring step cheap.
|
||||
|
||||
In our library example, this is like a quick scanner who flips through the 250K summary cards, scores each one for relevance, and hands us only the top few cards. We then read only those few cards in detail. Most of the library is skipped completely.
|
||||
|
||||
For a deeper background on Q, K, V in attention, we have a detailed blog on [Math Behind Attention: Q, K, V](https://outcomeschool.com/blog/math-behind-attention-qkv).
|
||||
|
||||
Here is a simple ASCII picture:
|
||||
|
||||
```markdown
|
||||
All tokens: [t1][t2][t3][t4][t5][t6][t7][t8] ...
|
||||
|__________| |__________|
|
||||
group 1 group 2
|
||||
| |
|
||||
Compressed: [C1] [C2] [C3] ...
|
||||
| | |
|
||||
Lightning Indexer scores each one against current query
|
||||
| | |
|
||||
score=0.9 score=0.2 score=0.8
|
||||
| | |
|
||||
Top-k selection: [ C1 ] ( C2 ) [ C3 ]
|
||||
picked skipped picked
|
||||
| |
|
||||
+-------------+-------------+
|
||||
|
|
||||
v
|
||||
Attention runs only on [C1] and [C3]
|
||||
(the picked compressed entries)
|
||||
```
|
||||
|
||||
So CSA first compresses many tokens into one, and then picks only the few compressed entries that look most relevant. This is how CSA brings the cost down. Both compute and memory are saved.
|
||||
|
||||
HCA: Heavily Compressed Attention
|
||||
|
||||
This was all about CSA. Now, let's move to HCA.
|
||||
|
||||
HCA makes a different trade-off. It compresses much more aggressively, and because the compressed sequence is already tiny, dense attention on it is cheap. No need for sparse selection.
|
||||
|
||||
HCA uses a much larger group size **m'**, much bigger than **m** in CSA. For DeepSeek-V4, **m'** is set to 128. So instead of combining 4 tokens into one entry, HCA combines 128 tokens into one entry. The KV cache shrinks even more dramatically.
|
||||
|
||||
In our library example, this is like grouping every 128 pages into one summary card. Now we have only about 7,800 summary cards in total. Since the number of cards is already very small, we just read all of them, every time. There is no need to pick the top few.
|
||||
|
||||
So CSA and HCA are two different design points with the same goal - cheap long-context attention. CSA does mild compression plus sparse top-k selection. HCA does aggressive compression plus dense attention. The result for both: very low compute and very low memory.
|
||||
|
||||
This was all about HCA. Now, let's see how the actual model uses both.
|
||||
|
||||
In DeepSeek-V4, the layers are interleaved. For DeepSeek-V4-Flash, the first two layers use pure sliding window attention, and the rest alternate between CSA and HCA. For DeepSeek-V4-Pro, the first two layers use HCA, and the rest alternate between CSA and HCA. This way, different layers handle long context in slightly different ways, and together they cover both fine-grained selection (CSA) and broad coverage (HCA).
|
||||
|
||||
Sliding Window Branch
|
||||
|
||||
Now, a natural question arises - what if compression blurs out important details from very recent tokens?
|
||||
|
||||
The answer is the **sliding window branch**. Both CSA and HCA also keep a small extra set of recent uncompressed KV entries. For DeepSeek-V4, this window size is 128 tokens.
|
||||
|
||||
In our library example, this is like always keeping the last 128 pages we just read on our desk in full. Compression is used for the older pages, but the most recent pages are right there in front of us, uncompressed and ready to read. This makes sure that local fine-grained dependencies are not lost.
|
||||
|
||||
Attention Sink
|
||||
|
||||
One more small but clever trick. In the core attention of both CSA and HCA, DeepSeek-V4 adds a small set of learnable **sink logits** to the denominator of the softmax. This allows each attention head to have attention scores that sum to less than 1.
|
||||
|
||||
Why does this help? In standard attention, the scores are forced to sum to exactly 1. This means every query token must distribute all of its attention somewhere, even when nothing in the context is actually relevant. Attention sinks let the model say "none of these are important right now" and spend less attention overall.
|
||||
|
||||
DeepSeek-V4 also applies RMSNorm on the queries and compressed KV entries just before the core attention step. This is what keeps attention logits stable and prevents them from exploding.
|
||||
|
||||
**Note:** Put together, CSA, HCA, Sliding Window, and Attention Sink make one trade-off possible: **less memory, less compute, with no major loss in quality**. That is what makes one-million-token context practical.
|
||||
|
||||
## Manifold-Constrained Hyper-Connections (mHC)
|
||||
|
||||
This was all about attention. Now, let's move to the residual connections inside the Transformer.
|
||||
|
||||
Let's decode the name first.
|
||||
|
||||
**mHC = Manifold + Constrained + Hyper + Connections.**
|
||||
|
||||
In a normal Transformer, every layer adds its output to a "residual stream" - a single shared signal that flows from the bottom of the model to the top. Hyper-Connections (HC) widen this residual stream by a factor of **n\_hc** (set to 4 in DeepSeek-V4), turning the single stream into multiple parallel streams. Three learned matrices (A, B, C) mix these streams at every layer, giving the model more flexibility in how information flows.
|
||||
|
||||
The issue with plain HC is that it becomes numerically unstable when we stack many layers. The signal can blow up or collapse. Training breaks down.
|
||||
|
||||
So, here comes mHC to the rescue. mHC fixes the problem by **constraining** the residual mapping matrix to lie on a special manifold called the Birkhoff polytope - the set of doubly stochastic matrices. A doubly stochastic matrix is a matrix whose every row sums to 1 and every column sums to 1. This simple constraint bounds the largest stretch factor (the spectral norm) of the matrix at 1, so the signal cannot blow up as it passes through dozens of layers.
|
||||
|
||||
The result is that deeper stacks train stably, and the model expressivity is preserved. It works perfectly.
|
||||
|
||||
## Muon Optimizer
|
||||
|
||||
This was all about mHC. Now, let's move to the optimizer.
|
||||
|
||||
DeepSeek-V4 swaps the optimizer for most of its parameters from AdamW to **Muon**.
|
||||
|
||||
**Muon = An optimizer that uses the full gradient matrix and orthogonalizes the update direction.**
|
||||
|
||||
Why does this matter? Most optimizers like AdamW treat each weight independently. Muon, on the other hand, looks at the full gradient matrix and applies an orthogonalization step before doing the weight update. This orthogonalization is done using Newton-Schulz iterations. It normalizes all the singular values of the update matrix to be close to 1, so no single direction in the update dominates. The result is faster convergence and more stable training.
|
||||
|
||||
A few important points:
|
||||
|
||||
- AdamW is still used for the embedding module, the prediction head, all RMSNorm modules, and the static parts of mHC.
|
||||
- Muon is used for everything else.
|
||||
- The DeepSeek team uses a hybrid Newton-Schulz iteration with carefully chosen coefficients for stable orthogonalization.
|
||||
|
||||
This gives us the best of both worlds. Muon brings faster convergence where it matters, and AdamW stays where it is already proven to work well.
|
||||
|
||||
## FP4 Quantization-Aware Training
|
||||
|
||||
Now, let's move to how DeepSeek-V4 makes inference faster and cheaper. The answer is **FP4 Quantization-Aware Training**.
|
||||
|
||||
Let's decode this.
|
||||
|
||||
- **FP4** stands for floating point with only 4 bits per number. Compared to FP8 or BF16, FP4 uses much less memory and bandwidth. It makes our life easier on the hardware side.
|
||||
- **Quantization-Aware Training (QAT)** means the model is trained while simulating the lower-precision number format, so the weights adapt to the precision loss during training itself. Without QAT, we would squeeze the weights down only at deployment time, and the model would lose quality. With QAT, the model learns to live with low precision.
|
||||
|
||||
DeepSeek-V4 applies FP4 to two key places:
|
||||
|
||||
- **MoE expert weights**, which take up most of the GPU memory.
|
||||
- The **Query-Key (QK) path of the CSA indexer**, where the lightning indexer computes scores in FP4.
|
||||
|
||||
There is one more clever detail here. FP8 (E4M3) has 2 more exponent bits than FP4 (E2M1), which gives it a much wider dynamic range. Because of this, the FP4 block scale factors can be fully absorbed into the FP8 format during dequantization. This means the FP4-to-FP8 dequantization is **lossless**, and the entire existing FP8 training pipeline can be reused without any modification.
|
||||
|
||||
The end result is a 2x speedup on the top-k selector while preserving a 99.7% recall of KV entries. There is no major quality loss.
|
||||
|
||||
## Pre-Training
|
||||
|
||||
Now that we have learned about the architecture and optimizer, it's time to learn about pre-training.
|
||||
|
||||
**Data.** The pre-training corpus has more than **32 trillion tokens**. It includes mathematical content, code, web pages, long documents, scientific papers, and multilingual data. The team puts a special emphasis on long-document curation since the model is built for long context.
|
||||
|
||||
**Sequence length scheduling.** Training does not start at one-million tokens directly. First, the model trains at a sequence length of 4K. Then, the length is extended to 16K. After that, to 64K. Finally, to 1M. Sparse attention is also turned on gradually. The model first warms up with dense attention for the first 1T tokens, and sparse attention is introduced at 64K and kept on for the rest of the training.
|
||||
|
||||
**Mitigating Training Instability.** Training trillion-parameter MoE models is hard. Loss spikes happen. But here is the catch - simple rollbacks do not prevent the next spike from happening. The DeepSeek team found two practical tricks that fix this:
|
||||
|
||||
- **Anticipatory Routing.** The MoE routing network at step **t** is computed using slightly older parameters **θ\_{t-Δt}**, while the rest of the backbone uses the current parameters **θ\_t**. This asymmetry breaks the feedback loop where bad routing causes outliers, which then cause worse routing.
|
||||
- **SwiGLU Clamping.** The output of the SwiGLU activation is clamped to a fixed range. This prevents extreme values from appearing and destabilizing training.
|
||||
|
||||
With these two tricks in place, training stays stable all the way through.
|
||||
|
||||
## Post-Training: Specialist Training and On-Policy Distillation
|
||||
|
||||
Till now, we have learned about pre-training. Now, it's time to learn about post-training.
|
||||
|
||||
Post-training is where DeepSeek-V4 takes a different path from many other models. The pipeline has two stages. Let's decode each one.
|
||||
|
||||
Stage 1: Specialist Training
|
||||
|
||||
For each target domain like mathematics, coding, agent use, instruction following, and etc., the DeepSeek team trains a separate **expert model**. Each expert model is built in two steps.
|
||||
|
||||
First, the base model goes through Supervised Fine-Tuning (SFT) on high-quality, domain-specific data. This establishes the foundational capability for that domain. Then, Reinforcement Learning is applied using **GRPO (Group Relative Policy Optimization)**, guided by domain-specific reward signals. This sharpens the model for the specific success criteria of that domain.
|
||||
|
||||
After this stage, the team has multiple specialist expert models - one per domain, each trained for varying reasoning efforts - each excelling in its own field.
|
||||
|
||||
This was all about Stage 1. Now, let's move to Stage 2.
|
||||
|
||||
Stage 2: On-Policy Distillation (OPD)
|
||||
|
||||
Now, a natural question arises - how do we combine all these expert models into one final unified model?
|
||||
|
||||
The answer is **On-Policy Distillation (OPD)**.
|
||||
|
||||
In simple words:
|
||||
|
||||
**On-Policy Distillation = The student model generates its own outputs, and learns to match the probability distribution of the right teacher expert for each task.**
|
||||
|
||||
Let's understand what makes OPD different from regular distillation.
|
||||
|
||||
In regular distillation, the student learns from data that the teacher produced. But there is one catch - the student never sees the kind of outputs it actually produces at inference time. This creates a gap between training and real behavior.
|
||||
|
||||
In OPD, the student samples its own trajectories. This is the "on-policy" part. The student writes its own drafts, and the teacher corrects each token by providing the full vocabulary distribution it would have used. The student is pulled towards the teacher's distribution using **reverse KL loss**. Reverse KL is mode-seeking - it pushes the student to concentrate probability mass where the teacher's mass is concentrated, rather than smearing out across all teacher modes. This gives sharper, more decisive outputs.
|
||||
|
||||
Also, different teachers are weighted based on the task. For a math task, the math expert teaches more. For a coding task, the coding expert teaches more. This way, all the specialist knowledge gets merged into one single unified student.
|
||||
|
||||
This step replaces the traditional mixed RL stage that DeepSeek-V3.2 used. The team found that OPD gives more stable and faithful knowledge transfer than weight merging or mixed RL, which is why it became the core consolidation step in the DeepSeek-V4 post-training pipeline.
|
||||
|
||||
## Reasoning Modes
|
||||
|
||||
This was all about post-training. Now, let's move to how DeepSeek-V4 actually serves users at inference time.
|
||||
|
||||
DeepSeek-V4 supports three reasoning modes that the user can pick depending on how hard the task is. Let me tabulate the differences between them for your better understanding so that you can decide which one to use based on your use case.
|
||||
|
||||

|
||||
|
||||
For **Think Max** mode, the injected system prompt essentially tells the model: Reasoning effort is set to absolute maximum with no shortcuts permitted. Be very thorough, decompose the problem to its root cause, rigorously stress-test your logic against all edge cases and adversarial scenarios, and write out every intermediate step, considered alternative, and rejected hypothesis explicitly. This instruction stretches the reasoning as far as it can go.
|
||||
|
||||
This way, the model can be cheap when the question is easy, and slow but powerful when the question is hard. We get to control the trade-off based on our use case.
|
||||
|
||||
## Putting It All Together
|
||||
|
||||
Now, let's put everything together to see how DeepSeek-V4 runs end to end.
|
||||
|
||||
In one sentence: a token enters the embedding layer, flows through many Transformer blocks (each one alternating CSA/HCA attention with a DeepSeekMoE feed-forward layer, both wrapped by mHC residual connections), and exits through the prediction head and MTP modules.
|
||||
|
||||
Here is the high-level architecture of one Transformer block in DeepSeek-V4:
|
||||
|
||||
```markdown
|
||||
Input Tokens
|
||||
|
|
||||
Embedding
|
||||
|
|
||||
+----------------|----------------+
|
||||
| Pre-Block Mixing |
|
||||
| | |
|
||||
| CSA / HCA | <- Hybrid Attention
|
||||
| | |
|
||||
| Post-Block Mixing |
|
||||
| | |
|
||||
| Residual Mixing | <- mHC residuals
|
||||
| | |
|
||||
| Pre-Block Mixing |
|
||||
| | |
|
||||
| DeepSeekMoE | <- Mixture of Experts FFN
|
||||
| | |
|
||||
| Post-Block Mixing |
|
||||
| | |
|
||||
| Residual Mixing | <- mHC residuals
|
||||
+----------------|----------------+
|
||||
(repeat for L layers)
|
||||
|
|
||||
Prediction Head
|
||||
|
|
||||
MTP Modules <- Multi-Token Prediction
|
||||
|
|
||||
Output
|
||||
```
|
||||
|
||||
At the top of the stack, a prediction head and **MTP (Multi-Token Prediction)** modules produce the output. MTP allows the model to predict more than one token at a time during training, which improves data efficiency.
|
||||
|
||||
This is how DeepSeek-V4 runs end to end - combining strong capability with one-million-token efficiency.
|
||||
|
||||
## Quick Summary
|
||||
|
||||
Let's recap what we have decoded:
|
||||
|
||||
- **DeepSeek-V4** is a family of open MoE language models built for ultra-long context. Two variants: **V4-Pro (1.6T total, 49B active)** and **V4-Flash (284B total, 13B active)**, both natively supporting **1M tokens**.
|
||||
- **Hybrid Attention** combines **CSA (Compressed Sparse Attention)** and **HCA (Heavily Compressed Attention)** in an interleaved manner. CSA compresses tokens into groups and then picks top-k. HCA compresses even more but keeps attention dense. A small sliding window keeps recent tokens uncompressed, and learnable attention sinks keep attention logits stable.
|
||||
- **mHC (Manifold-Constrained Hyper-Connections)** widens the residual stream by **n\_hc=4** and constrains the mixing matrix to the Birkhoff polytope (doubly stochastic matrices, rows and columns summing to 1), which bounds the spectral norm at 1 for stable deep training.
|
||||
- **Muon Optimizer** orthogonalizes the gradient update matrix using Newton-Schulz iterations, normalizing all singular values close to 1 for balanced, faster convergence. AdamW is still used for embeddings and a few other modules.
|
||||
- **FP4 Quantization-Aware Training** is applied to MoE expert weights and the CSA indexer, with a lossless FP4-to-FP8 dequantization that reuses the existing FP8 pipeline unchanged.
|
||||
- **Pre-training** uses 32T+ tokens with a sequence length schedule that grows from 4K to 1M, plus **Anticipatory Routing** and **SwiGLU Clamping** to fix loss spikes.
|
||||
- **Post-training** has two stages: **Specialist Training** (SFT + GRPO per domain) followed by **On-Policy Distillation (OPD)** that merges all specialists into one unified student model.
|
||||
- **Three reasoning modes** - Non-think, Think High, Think Max - let the user trade off cost and depth.
|
||||
- **Net result:** at 1M-token context, DeepSeek-V4-Pro uses only 27% of the FLOPs and 10% of the KV cache of DeepSeek-V3.2. DeepSeek-V4-Flash pushes this further to 10% FLOPs and 7% KV cache.
|
||||
|
||||
This is how the DeepSeek-V4 series ushers in a new era of million-length contexts for open large language models.
|
||||
|
||||
Read my LLM Internals Series: [LLM Internals](https://github.com/amitshekhariitbhu/llm-internals)
|
||||
|
||||
That's it for now.
|
||||
|
||||
Thanks
|
||||
|
||||
**Amit Shekhar** Founder @ [Outcome School](https://outcomeschool.com/)
|
||||
@@ -0,0 +1,190 @@
|
||||
---
|
||||
title: "DeepSeek's 10 trillion USD grand strategy"
|
||||
source: "https://x.com/bookwormengr/status/2057909493250539891"
|
||||
author:
|
||||
- "[[@bookwormengr]]"
|
||||
published: 2026-05-23
|
||||
created: 2026-05-25
|
||||
description: "Have you ever wondered, how DeepSeek may make money, and lot of it? They didn't come up with competitive coding plans like GLM, MoonShot and..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
**Have you ever wondered, how DeepSeek may make money, and lot of it?**
|
||||
|
||||
They didn't come up with competitive coding plans like GLM, MoonShot and MiniMax. They don't have multimodal, audio, video models. Till date they don't have a harness (they have begun hiring recently for building a harness)? DeepSeek is also committed to open source in the long term and is too happy to share their secret sauce. Is this madness? Is this sheer waste of money? Are investors who are about to invest 10B USD in them throwing money into a drain? No - quite the contrary, imho!!! Here I present observations about what they have done till date, and a strategy they seem to be following . [Liang Wenfeng](https://en.wikipedia.org/wiki/Liang_Wenfeng)'s (DeepSeek CEO) eyes seem to be on much bigger prize and they could achieve 1T USD valuation, while helping create a 10T USD industry!
|
||||
|
||||

|
||||
|
||||
TechInAsia news about DeepSeek's latest funding round
|
||||
|
||||
## Revisiting DeepSeek's Hero's Journey
|
||||
|
||||
DeepSeek has always gone against the wind of building incrementally better models and trying to sell immediate applications - e.g. coding plans. I wrote this viral tweet on 27th Jan 2025 about what I saw as [DeepSeek's Hero's Journey.](https://x.com/bookwormengr/status/1883712073814954379?s=20) The story is getting only more interesting.
|
||||
|
||||
- When people were trying building dense models, DeepSeek went after Mixture of Expert models (MoE) that were hard to train.
|
||||
- They worked from 'first principal' approach and invented new algorithm GRPO to replace dominant PPO algorithm for Reinforcement Learning (RL) that was more expensive to implement.
|
||||
- They figured out Reinforcement Learning from Verified Rewards (RLVR) as a key strategy to improve reasoning ability of models.
|
||||
- They came up with a simple strategy for Speculative Decoding through "Multi Token Prediction" that also densified the training signal.
|
||||
- They perfected "ZERO bubble" pipelines to improve use of limited GPU resources.
|
||||
- They published Expert Load balancer to make it easy for everyone deploy Mixture of Expert models. Particularly with "Wide Expert Parallel" strategy models can be served much more economically as one can have large batches.
|
||||
- They invented MLA, DSA, CSA, HCA to reduce KV Cache need and keep computation demand against growing context near constant.
|
||||
- They invented Engram to trade memory for compute.
|
||||
- They invented mHC to achieve stable training as model size grows. And th list continues....
|
||||
|
||||
In Hero's Journey story structure (the most universal), hero never decides what his journey is going to be. He learns along the way and figures out a great mission for himself and completes it against all the odds. He meets many detractors, but he ignores them. He meets many bad faith actors. He has great flaw or shortcoming - but he overcomes them to accomplish his mission. He confronts challenges that seem unsurmountable, but figures out how to make alliances and how to use precious resources wisely. This is what gets the audience to root for the hero. This is what earns DeepSeek their fan following and global respect and also detractors.
|
||||
|
||||
As I will show you in detail, DeepSeek is on this journey for long enough now and have discovered the ultimate destiny: **it is not selling coding plans, but to enable a 10T USD Chinese AI hardware ecosystem and achieve 1T USD valuation for itself.** In doing to so they will enable many new entrants in the western hardware ecosystem as well. Comments and criticism welcome: [@naval](https://x.com/@naval) [@teortaxesTex](https://x.com/@teortaxesTex) [@jukan05](https://x.com/@jukan05) [@bubbleboi](https://x.com/@bubbleboi) [@poezhao0605](https://x.com/poezhao0605) [@hsu\_steve](https://x.com/@hsu_steve) [@tphuang](https://x.com/@tphuang)
|
||||
|
||||

|
||||
|
||||
## Starting with some fun with KV Cache calculations:
|
||||
|
||||
Read this timely tweet from [@SemiAnalysis\_](https://x.com/@SemiAnalysis_) :
|
||||
|
||||

|
||||
|
||||
DeepSeek has already solved this problem better than anyone else!
|
||||
|
||||
Let us do some fun KV cache math first. Don't worry if you don't like Math. We will use recently release KV Cache calculator to see KV Cache saving made possible by DeepSeek V4 Pro and compare it with latest GLM and Qwen models.
|
||||
|
||||
I compute for 1M context. I assume 8 bit KV precision and 16 bit indexer precision. You can play with the calculator.
|
||||
|
||||
[https://kvcache.ai/tools/kv-cache-calculator/](https://kvcache.ai/tools/kv-cache-calculator/)
|
||||
|
||||

|
||||
|
||||
Play with the calculator yourself!
|
||||
|
||||
**For 1M context**
|
||||
|
||||
1. DeepSeek V4 needs only 5.48GB HBM
|
||||
2. GML5 needs 60GB HBM
|
||||
3. Qwen3-235B-A22B needs whopping 89B
|
||||
|
||||
**Mind you**
|
||||
|
||||
1. DeepSeek is 1.6T parameter model,
|
||||
2. GLM5 is around 700B parameter, it already uses DeepSeek's MLA and DSA; though not latest compressed attention
|
||||
3. Qwen3-235B-A22B is around 235B and uses GQA attention
|
||||
|
||||
DeepSeek has made foundational contribution to ease pressure on memory. **If widely adopted this innovation can make long horizon agents highly economical and unlock next set of use cases**.
|
||||
|
||||

|
||||
|
||||
Comparison of KV Cache footprint for 1M tokens and model size
|
||||
|
||||
## Method behind the madness:
|
||||
|
||||
This small size of KV cache - **without compromising on quality** - is the reason they can offer long held cache at such a ridiculously low price - less than 3% price of Cache hits for Sonnet 4.6 - and they hold it for multiple hours.
|
||||
|
||||
Small amount of cache for long horizon task enables **offloading to SSDs and reloading very cost effective**. This reduces requirement of HBM that is in short supply and hardest to make memory from Chinese AI hardware industry perspective. DeepSeek have also developed techniques to load KV cache faster from SSD as described [in the Dual Path paper.](https://arxiv.org/pdf/2602.21548)
|
||||
|
||||

|
||||
|
||||
Their new DeepSeek V4 compresses KV cache so much, this may not even be needed.
|
||||
|
||||
## Who is the immediate beneficiary of KV Cache compression?:
|
||||
|
||||
Who supplies SSD in large quantity? Remember **YMCT is emerging as 3D NAND giant.** NAND allows DeepSeek to avoid re-computation of KVs. In turn, DeepSeek creates a large market for NAND & SSD - not just of YMTC's but everyone else's as well.
|
||||
|
||||

|
||||
|
||||
## It is not only about NAND & SSD, however:
|
||||
|
||||
**LPDDR** memory has great potential to be a place where you hold weights and stream them into HBM as needed, reducing the pressure on HBM demand. [SGLang team has published great blog about it.](https://www.lmsys.org/blog/2025-09-25-gb200-part-2/) I present below diagram to explain how the scheme works.
|
||||
|
||||
While DeepSeek did not do anything specifically for this - their MoE architecture with large number of experts and 4 bit weights make it easy to implement this scheme.
|
||||
|
||||

|
||||
|
||||
Schematic showing how memory could be used and weights could be streamed to HBM from LPDDR. Highly recommend to read the SGLang blog.
|
||||
|
||||
This innovation combined with super compact KV Cache (lossless) reduce HBM demand significantly.
|
||||
|
||||
Who in China makes LPDDR? **CXMT.** They are only 0.5 Gen behind on speed for LPDDR and 1 generation behind on density**. Not very far!** In addition abundant NAND, Chinese ecosystem will have abundant LPDDR in near future. **Can this relieve pressure on compute? YES.** Follow on..
|
||||
|
||||

|
||||
|
||||
## Smart use of memory also reduces pressure of GPUs/ASICS as well
|
||||
|
||||
It is quite clear to understand use of NAND for KV cache allows holding KV cache for longer, reduce pressure of HBM and helps avoid re-computation of KV cache that relieves compute pressure on GPUs & ASICs. Can LPDDR also help in similar manner, in addition being a place from where weights can be streamed in "just in time fashion"? **The answer is YES.**
|
||||
|
||||
LPDDR supports holding large amount of what is known as "Engram". In their [Engram paper](https://arxiv.org/pdf/2601.07372) DeepSeek showed that while MoE scales capacity via conditional computation, Transformers lack a native primitive for knowledge lookup. They're forced to inefficiently simulate retrieval through computation. They introduce Engram, a module that modernizes classic N-gram embedding into an O(1) hash-based lookup, creating a complementary sparsity axis they call conditional memory. This saves computation, but needs memory to host the embeddings table which can be large in size. It is a classic **memory-compute substitution**, but with the insight that the "memory" side is dramatically cheaper per bit retrieved (**a LPDDR lookup vs. a full forward pass through transformer layers**), making it a very favorable trade at scale. **This is how they save on compute by trading memory!!!**
|
||||
|
||||

|
||||
|
||||
**Trade-offs worth having:** Chinese GPUs & ASICS are forever going to lag in raw FLOPs compared to western GPUs due to not having same transistor density per chiplet (no EUV). They are quite behind in packaging as well. So such trade-offs are well worth it, particularly if you can make abundant NAND and LPDDR memory.
|
||||
|
||||
## DeepSeek's long game recounted:
|
||||
|
||||
From all these innovations, DeepSeek's game doesn't seem to be immediate profits of few hundred millions given all the choices they have made (no multimodality yet, no voice models, video - what is that?) - but **they are playing a patient 10T USD game to enable alternative hardware ecosystem.**
|
||||
|
||||
It is not only about making Chinese memory players key players on Chinese and global AI hardware arena, but also reducing the resource demand itself, to be able to train and serve AI models cost effectively - this will enable many GPU/ASIC makers as well as networking chip makers as they will become viable options. **All these innovations will also help Western open source ecosystem as well as new hardware makers.**
|
||||
|
||||
All the signs are there. Just let us recount in detail all the innovations they came up with:
|
||||
|
||||
1\. **Mixture of Expert** (MoE) and **MLA** introduced in DeepSeek V2. MoE is made it possible to train **very intelligent models at 40 to 50% less compute.** MLA made it possible to reduce KV cache by 90%. This made offloading KV cache to SSD quite efficient. This ideas were introduced in their May 2024 paper [DeepSeek V2](https://arxiv.org/pdf/2405.04434). It later unlocked training DeepSeek V3 which was near closed source at the time with only 2048 H800 nerfed GPUs.
|
||||
|
||||

|
||||
|
||||
2\. **DSA** (introduced in [DeepSeek V3.2 Exp)](https://arxiv.org/pdf/2512.02556) to reduce compute for long context scenarios and also relieve pressure on HBM bandwidth. It ensures computation doesn't grow with growing context. Please see charts below - processing time for DeepSeek-v3.2 stays flat with context.
|
||||
|
||||

|
||||
|
||||
3\. **mHC** introduced in Dec 2025 in paper [mHC: Manifold-Constrained Hyper-Connections](https://arxiv.org/pdf/2512.24880). mHC is a macro-architecture innovation from DeepSeek that reinvents how information flows between transformer layers. Instead of the standard residual connection (x + F(x)) used since ResNet, mHC expands the residual stream into multiple parallel information highways and allows learned mixing between them — but crucially constrains the mixing matrices to be doubly stochastic (via Sinkhorn-Knopp projection onto the Birkhoff polytope), which mathematically guarantees that signal magnitude is preserved across arbitrary depth.
|
||||
|
||||
- **This solves the catastrophic instability** that plagued unconstrained Hyper-Connections (initially invented at ByteDance), where signal amplification exploded to 3000× at 27B scale, collapsing training entirely.
|
||||
- **The compute cost is minimal:** mHC adds only 6.7% wall-clock training overhead since it doesn't change the FLOPs of attention or FFN layers, only how their outputs are routed between layers.
|
||||
- **The performance gains, however, are substantial:** at 27B parameters, mHC delivers +7.2 points on BIG-Bench Hard reasoning, +3.2 on DROP, +2.8 on GSM8K math, and +1.4 on MMLU general knowledge, all at the same model size and nearly identical compute budget.
|
||||
|
||||
In essence, mHC achieves meaningfully higher intelligence per parameter by giving the network a richer, more expressive topology for routing information across layers, while paying almost nothing in additional FLOPs.
|
||||
|
||||

|
||||
|
||||
mHC is a complex architecture; but it offers great stability of training and higher per parameter intelligence
|
||||
|
||||
4\. **CSA, HSA** (introduced in [DeepSeek V4](https://huggingface.co/deepseek-ai/DeepSeek-V4-Pro/blob/main/DeepSeek_V4.pdf) in April 2026) to reduce KV need by another 90% by compressing KV tokens and reduces FLOPs needed by large margin relieving pressure on both HBM and GPU/ASIC.
|
||||
|
||||

|
||||
|
||||
5\. [Engram](https://arxiv.org/pdf/2601.07372) introduced in Q1 2026 where they trade memory (**LPDDR memory**) for compute (in a way). As the following detailed chart show performance gain due to Engram at same overall parameters budget.
|
||||
|
||||

|
||||
|
||||
6\. Extreme focus on **Compute** and **Communication** overlap, and innovations like **Dual Path** can be explained as work around to resource constraint. But DeepSeek goes further to advise hardware vendors on their ASIC design to make sure they **don't waste precious silicon resources.** This is from [DeepSeek V4 paper](https://huggingface.co/deepseek-ai/DeepSeek-V4-Pro/blob/main/DeepSeek_V4.pdf).
|
||||
|
||||

|
||||
|
||||
This is advice they shared in DeepSeek V4 paper. Pretty sure, they share far more feedback in person.
|
||||
|
||||
7\. Investment in **TileLang** point in the consistent direction that they are not just dealing with their own compute crunch but making Chinese hardware ecosystem competitive with western ecosystem. With Tilelang it is possible to develop kernel (code for computation) once and have it run successfully on multiple hardware platforms for which TileLang backend is available. I expect all other China based labs to join in - helping Chinese hardware makers deal indirectly with the "CUDA moat". This also unlocks more western hardware like AMD. Note: many AI platforms in China either provide CUDA compatibility or CUDA translation layer: Moore Threads, MetaX, Biren, and Iluvatar CoreX are the most CUDA-compatible Chinese chips via translation layers. They do not need TileLang (in theory).
|
||||
|
||||

|
||||
|
||||
## Large scale RL and RSI:
|
||||
|
||||
With access to more compute (due to more potential hardware options) and reduction in compute demand, DeepSeek can take on much more ambitious training projects; particularly RL post training. RL involves generating large number of trajectories - generating trillions of tokens. It can get expensive real fast. Furthermore to train 1M context models, you need to generate trajectories that long. Training models for such long trajectories enables long horizon tasks. Furthermore, availability of more hardware at DeepSeek due to increased options will enable automated research (RSI). RSI involves AI itself designing and carrying out experiments. The approach has large number of trials and errors and can get costly very quickly. **However, RSI is important to explore the entire design space.** DeepSeek will need to be RSI capable before they hit AGI followed by ASI.
|
||||
|
||||
## What DeepSeek does today, rest of the industry does tomorrow:
|
||||
|
||||
DeepSeek's innovations around Mixture of Expert, MLA, DSA have been picked up by rest of the AI labs from around the world and from China. For example, ZAI - makers of GLM family of models - use MLA and DSA. Kimi (Moonshot) has adopted MLA and have no hesitation in saying their architecture is based on DeepSeek's architecture. In return DeepSeek uses Muon optimiser that was first used my Kimi (Moonshot) for large scale training. (NOTE: - MoE was invented at [Google in 2027 with Naom Shazeer](https://arxiv.org/pdf/1701.06538) as the key author. DeepSeek applied it at massive scale and invented their own tricks. - The Muon (MomentUm Orthogonalized by Newton-Schulz) optimizer was created by machine learning researcher **Keller Jordan** in late 2024. Kimi (Moonshot) team were the first one to use it at massive scale.)
|
||||
|
||||
## What about making $$$?:
|
||||
|
||||
Let us study interesting example of OpenAI. OpenAI received warrant/options to buy stocks of AMD and Cerebras at a low price, based on consumption mile stones. It is a great deal for AMD and Cerebras. OpenAI being committed to them, makes they likely to succeed in the long run.
|
||||
|
||||
[Quote from AMD announcement](https://www.amd.com/en/newsroom/press-releases/2025-10-6-amd-and-openai-announce-strategic-partnership-to-d.html): "As part of the agreement, to further align strategic interests, AMD has issued OpenAI a warrant for up to 160 million shares of AMD common stock, structured to vest as specific milestones are achieved. The first tranche vests with the initial 1 gigawatt deployment, with additional tranches vesting as purchases scale up to 6 gigawatts. Vesting is further tied to AMD achieving certain share-price targets and to OpenAI achieving the technical and commercial milestones required to enable AMD deployments at scale."
|
||||
|
||||

|
||||
|
||||
I forecast DeepSeek to enter in such agreements with multiple Chinese memory, ASIC, CPU and networking stack makers and work closely with them to make their hardware stacks viable for leading AI workloads.
|
||||
|
||||
Given combined valuation of all Western (including East Asian allies) AI stocks far exceeds 10T USD. This - **collaboration that awards equity -** approach allows DeepSeek to help create equally big industry in China and claim their piece of the pie while achieving **1T USD valuation for themselves**. This will allow them to make far more $$$ while also achieving their goal in their words of **"AGI for everyone". Liang Wenfeng - a big fan of Jim Simmon - is too smart a capitalist to miss this!** This is the only thing that makes sense, if you look at everything DeepSeek have done so far...
|
||||
|
||||

|
||||
|
||||
These are key AI stocks. Not shown are Hyper-scalars and many others.
|
||||
|
||||
Detailed blog on these innovation coming out this weekend, follow my substack [https://polymath707.substack.com/](https://polymath707.substack.com/) if interested...
|
||||
@@ -0,0 +1,128 @@
|
||||
---
|
||||
title: "Designing for Agents"
|
||||
source: "https://x.com/teddy_riker/status/2047312986696454584"
|
||||
author:
|
||||
- "[[@teddy_riker]]"
|
||||
published: 2026-04-23
|
||||
created: 2026-04-24
|
||||
description: "If you spend time in the same corner of X as I do, scrolling past the \"How I built a second brain with Obsidian\" and \"Anthropic just KILLED ..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
If you spend time in the same corner of X as I do, scrolling past the "How I built a second brain with Obsidian" and "Anthropic just KILLED \[insert industry\] FOREVER" posts, you've probably also seen the take that **UI is dead.** And unless a product can be used by agents via an MCP, API, CLI, or something in between, it won't survive.
|
||||
|
||||
The trend is real at Ramp. Over the past three months, weekly active users on our MCP have grown 10x as more customers reach into the product through Claude, ChatGPT, and other agents.
|
||||
|
||||
Last week, Salesforce became one of the first incumbents to lean into this thesis.
|
||||
|
||||
From [VentureBeat](https://venturebeat.com/ai/salesforce-launches-headless-360-to-turn-its-entire-platform-into-infrastructure-for-ai-agents):
|
||||
|
||||
> [Salesforce](https://www.salesforce.com/) on Wednesday unveiled the most ambitious architectural transformation in its 27-year history, introducing "[Headless 360](https://www.salesforce.com/news/stories/salesforce-headless-360-announcement/)" — a sweeping initiative that exposes every capability in its platform as an API, MCP tool, or CLI command so AI agents can operate the entire system without ever opening a browser.
|
||||
|
||||
> The announcement, made at the company's annual [TDX developer conference](https://www.salesforce.com/tdx/) in San Francisco, ships more than 100 new tools and skills immediately available to developers. It marks a decisive response to the existential question hanging over enterprise software: In a world where AI agents can reason, plan, and execute, does a company still need a CRM with a graphical interface?
|
||||
|
||||
> Salesforce's answer: No — and that's exactly the point.
|
||||
|
||||
This is a smart move by Salesforce, and one that I can't imagine was easy to make. Ask most salespeople, and they'll tell you how much they dislike using Salesforce. But the product is pervasive because of the familiarity of its UX. Sales leaders aren't interested in ramping up their teams on new technology, and consistency frequently trumps functionality.
|
||||
|
||||
Benioff and team are accepting that this moat is eroding and leaning into the reality that a majority of usage will be driven through agents like Claude, ChatGPT, and other background processes that users never see.
|
||||
|
||||
I don't think UI is dying. Humans still want to point and click, see their configurations, and verify completed work. But the 80/20 has flipped: the new 80% of interaction with software will be through agents. That changes not only what you need to build, but how you build it.
|
||||
|
||||
## The new interaction pattern
|
||||
|
||||
For the past twenty years, the primary way people have interacted with software has been:
|
||||
|
||||
User → Interface → Database
|
||||
|
||||
You open a product, click around, get things done. The interface is how you experience the software. For most people, the interface is the product.
|
||||
|
||||
As agents take on more of the work, a new layer has emerged:
|
||||
|
||||
User → **User's Agent (e.g. Claude)** → Database
|
||||
|
||||
The agent acts on the user's behalf. It reads, writes, and navigates the product so they don't have to. And suddenly the interface is gone. The agent is talking directly to the system underneath.
|
||||
|
||||
But even this is rapidly changing. Software companies are (and should be) designing their own agents and capabilities. So the new pattern looks more like this:
|
||||
|
||||
User → User's Agent → **Software's Agent** → Database
|
||||
|
||||
In this model, the software's agent handles complexity on behalf of the user's agent: applying business logic, enforcing rules, pulling in context the latter doesn't have. Two LLMs working together to drive toward an outcome.
|
||||
|
||||
## Teach agents how to succeed
|
||||
|
||||
I do a majority of my brainstorming, writing, and ideating with LLMs. When a draft is ready to share, I push it to Notion through their MCP server. I was a Google Docs loyalist for years; Notion's MCP flipped me.
|
||||
|
||||
One thing I appreciate as a Notion MCP user is how every time I ask an agent to write something, it nails it. Tables, bullets, italics, lists, you name it — the agent never fails.
|
||||
|
||||
This is by design.
|
||||
|
||||
The notion-create-pages tool's description opens with: "For the complete Markdown specification, always first fetch the MCP resource at notion://docs/enhanced-markdown-spec. Do NOT guess or hallucinate Markdown syntax." When I ask my agent to write to a page, that's the first thing it does. It fetches the spec, then writes. Every Notion-specific assumption gets explicitly called out against the general model's defaults.
|
||||
|
||||
In an old world, that spec would've lived in API docs, and a developer integrating with Notion would read it, internalize it, and write a transformation layer. Now Notion hands the spec directly to the agent, at the moment it's needed.
|
||||
|
||||
If you've ever used the Slack MCP, you've probably experienced the inverse of this. Your agent assumes standard markdown and doesn't adhere to Slack's specific formatting. You end up spending more time editing the formatting than you would have writing the message:
|
||||
|
||||

|
||||
|
||||
Sure, the formatting guidelines are online and you could save them somewhere and teach your agent how to use them. But that's annoying, and it shouldn't be necessary.
|
||||
|
||||
Think about what your agent's callers need to know to succeed, and give it to them proactively. Don't make them figure it out.
|
||||
|
||||
## Build feedback loops
|
||||
|
||||
When we first launched our MCP at Ramp, observability was our largest problem. We could see tool call volume, but we couldn't see the surrounding chat context that produced those calls. Volume alone didn't tell us what was working, what was breaking, or what people were actually trying to accomplish.
|
||||
|
||||
We've addressed this in a few ways:
|
||||
|
||||
1. **Require a 'rationale' on every tool call.** Every MCP or CLI tool call requires the agent to include a rationale parameter explaining why it's making the request. We can't see the chat, but the rationale reconstructs intent. Patterns in the rationales tell us what people are actually trying to do.
|
||||
2. **A feedback tool.** We shipped a standalone tool the agent can call when it gets blocked or runs into a pattern that isn't working. The agent submits what it was trying to do, what it tried, and where it got stuck.
|
||||
3. **Tool-specific seeds.** We add purpose-built parameters to individual tools to capture context we'd want later: things the agent has access to that we'd otherwise have to infer.
|
||||
|
||||
Imagine you're building a customer support platform, and you offer tools for customers to fetch tickets. Over time, you start noticing the same phrase in rationale logs: "building an incident report," "drafting incident summary," "gathering tickets for an outage postmortem."
|
||||
|
||||
That's a new product feature! A build-incident-report tool could identify related tickets, score severity, pull the affected customer segment, and draft a summary in a strongly opinionated format.
|
||||
|
||||
Once that's live, you might start receiving feedback on the tool: "the report pulled in tickets from three days ago that weren't part of this incident" or "it keeps including tickets from free-tier users who don't belong in postmortems." All of a sudden you've got agents telling your agents exactly what to build. Agents hallucinate, sure. But they're also more specific and more consistent in their feedback than most humans you'd ever ship to.
|
||||
|
||||
If the report pulls irrelevant tickets, you add a date range parameter. If it shouldn't include free-tier customers, you add a segment filter. Each feedback loop becomes a new way for the product to improve.
|
||||
|
||||
## Mind the context gap
|
||||
|
||||
In any agent interaction, your system has context the calling agent doesn't have, and the calling agent has context your system doesn't have. When designing these interactions, you should have an opinion about where each has a leg up.
|
||||
|
||||
Let's say Diego goes on a business trip. Diego's AI chief of staff picks up a Slack nudge from the expense management system's agent: he has incomplete expenses from his recent trip. Two agents are now pointed at the same outcome: submit these expenses correctly.
|
||||
|
||||
These two agents bring their own context.
|
||||
|
||||
**What Diego's chief of staff brings:**
|
||||
|
||||
- Diego's calendar: knows which meetings happened, when, and with whom
|
||||
- Diego's email: has the hotel and flight confirmation as attachments
|
||||
- Diego's Slack: can correlate the Kokkari dinner to a thread where he invited the Acme team
|
||||
- Diego's receipts (pulled from email attachments and photo library)
|
||||
|
||||
**What the expense management system brings:**
|
||||
|
||||
- The raw transaction data (e.g., merchant, time of transaction)
|
||||
- The company's policies around submission
|
||||
- The company's GL accounts
|
||||
- The company's historical coding patterns
|
||||
|
||||
A traditional API would dump the problem back on the user. "Here is a transaction that needs a GL code. Use this endpoint to fetch the 150 GL code options, and pick one."
|
||||
|
||||
A well-designed agent interaction flips this — it doesn't ask for a GL code. It asks for context: was this a client meal, a team meal, or personal travel? The chief of staff agent pulls the answer from a calendar entry or a Slack thread. The EM system applies the correct code based on the context it was missing.
|
||||
|
||||
Diego and his agent never need to know what the GL codes are, and the finance team gets accurate categorization. Each side contributes what it knows, and delivers an outcome that is better for Diego — and his accountant.
|
||||
|
||||
As you design these agent-to-agent interactions, be mindful of the context gap. It's ok to admit where your agent falls short — you're both serving the same user.
|
||||
|
||||
The interface used to sit between Diego and his expense system. Now it sits between his agent and yours.
|
||||
|
||||
That shift reframes the product team's job. You used to design for a human who wanted to move fast, avoid mistakes, and see their work. Now you're designing for that same person through an intermediary whose instincts, context, and limitations are different from theirs. Teaching agents how to succeed, building feedback loops, and minding the context gap all ask the same underlying question: what does your agent's caller need to do its job well, and are you giving it to them?
|
||||
|
||||
Most companies will ship an MCP, check the box, and move on. Their usage will grow for a few quarters, then stall. Over time, customers will route toward products that sweated the details and around the ones that didn't.
|
||||
|
||||
Build for the agent with the same care you spent on the human. Before you know it, it'll be the one writing the check.
|
||||
@@ -0,0 +1,150 @@
|
||||
---
|
||||
title: "Every AI trend you need to know in 2026"
|
||||
source: "https://x.com/rohit4verse/status/2046990550273065277"
|
||||
author:
|
||||
- "[[@rohit4verse]]"
|
||||
published: 2026-04-23
|
||||
created: 2026-04-24
|
||||
description: "Something broke in how I used AI this year.I stopped writing prompts and started building workspaces.Memory that survived sessions. Knowledg..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
Something broke in how I used AI this year.
|
||||
|
||||
I stopped writing prompts and started building workspaces.
|
||||
|
||||
Memory that survived sessions. Knowledge bases that got smarter on their own. By month three I could not remember the last time I typed a question into a chat box and waited for an answer.
|
||||
|
||||
That is the shift nobody is summarizing properly, and it is the only thing about 2026 you need to understand.
|
||||
|
||||
Every trend you are about to read is part of the same thing. Agentic coding. Open-source agent frameworks. Karpathy's LLM wiki. GraphRAG. "Ragless" systems. Grok sitting inside every X thread you scroll past. They sound like five different stories because they shipped on five different weeks. They are one story.
|
||||
|
||||
AI stopped being a thing you talk to. It became a thing you build around.
|
||||
|
||||
Once you see it that way, the rest of 2026 makes sense in a way it did not a year ago.
|
||||
|
||||
## The year prompts stopped mattering
|
||||
|
||||
Two years ago the winning skill in AI was prompt engineering. You learned the right phrasing, the right persona, the right chain of thought, and you got better outputs than the person next to you. That skill had a half-life of maybe eighteen months.
|
||||
|
||||
What killed it was not a better model. It was the realization that prompts are the thinnest, most volatile layer of the stack.
|
||||
|
||||
Context is the thickest. Context is what the model sees before it starts generating. Your project files. Your past conversations. Your tools. Your style guide. Your codebase. Your domain knowledge. Everything you would whisper in a new hire's ear on day one.
|
||||
|
||||
The teams winning in 2026 figured out that whoever owns the context layer owns the output quality. Prompt engineers became context engineers. And context, unlike a clever prompt, is an asset that compounds.
|
||||
|
||||
Everything else in this article is what "owning the context layer" actually looks like once you start building it.
|
||||
|
||||
## The shift to agentic coding
|
||||
|
||||
Claude Code was the canary.
|
||||
|
||||
When it first landed as a CLI tool, most people treated it like a fancy autocomplete. Paste some code, ask for a fix, move on. That framing missed the point by two orders of magnitude.
|
||||
|
||||
The real shift was that Claude Code did not try to be a typing assistant. It tried to be a coworker. A project file that remembered the codebase. A permission system that asked before touching production. MCP integrations that let it read from databases, run tests, spin up parallel instances against the same branch. The pattern reads less like GitHub Copilot and more like hiring a junior engineer who already knows your stack.
|
||||
|
||||
I ran parallel Claude Code sessions on my own backend for the first time in January. One session fixed a bug in the retrieval layer. Another worked on a new pattern detection pipeline. A third wrote the integration tests for both. I reviewed diffs, not keystrokes.
|
||||
|
||||
That day ended with three merged branches and a realization. My job stopped being "write the code." It became "describe the goal, set the guardrails, review the work."
|
||||
|
||||
That is the delegation layer the industry spent two years pretending did not exist. In 2026 it stopped being a demo and started being a workflow.
|
||||
|
||||
The reason Claude Code became the reference point is that it surfaced every hard problem nobody wanted to solve. How do you manage context over a four-hour session without the agent forgetting what it was doing? How do you let it touch real systems without nuking production? How do you compact history without losing the thread of a long refactor? Every serious agentic coding tool that shipped after it is a different answer to the same four questions.
|
||||
|
||||
Cursor, Copilot Workspace, the newer Devin releases, the SWE-agent academic line. Different answers, same questions. That is how you know a category has matured.
|
||||
|
||||
## Open-source agents grew up
|
||||
|
||||
The open-source side of this story is the part most people undersell.
|
||||
|
||||
OpenClaw is the cleanest example. When it first launched, the framing was "an agent that plugs into your chat apps." Cute demo, nothing more. By mid-2026 the release notes read like infrastructure engineering. HSTS headers. SSRF policy changes. External secrets management. Cron reliability patches. Multilingual memory embeddings. Multi-model routing. Thread-bound agents so conversations in Signal do not cross-contaminate with conversations in Telegram.
|
||||
|
||||
That list is not exciting. That list is exactly what you need to run an agent in production without it becoming a security incident.
|
||||
|
||||
The maturation pattern here matters more than the specific features. Open-source agent projects stopped chasing the next benchmark and started shipping the boring infrastructure that makes an agent survive a real user base. The demo era was 2024. The demo-to-prod era was 2025. 2026 was the year open-source agents had to answer the same compliance questions a B2B SaaS product answers in its second round of funding.
|
||||
|
||||
Hermes 3 sits at the model end of the same trend. Nous Research positioned it as a frontier open model with long-term context retention, multi-turn conversation, internal-monologue capabilities, and agentic function calling, trained primarily on synthetic data fine-tuned over Llama 3.1 sizes. You do not train a model that way unless you assume it is going to get wrapped in an agent loop and left running.
|
||||
|
||||
Read the two together. OpenClaw is building the harness. Hermes is training the model that expects to live inside one. They are different parts of the same bet: that the next wave of open-source AI will be agents, not chatbots, and the teams winning will have invested in the plumbing long before anyone else thought it mattered.
|
||||
|
||||
If you are an engineer choosing what to learn next, this is the unglamorous answer. Spend a weekend reading the OpenClaw release notes end to end. You will learn more about what production AI actually looks like than from any paper you read this year.
|
||||
|
||||
## Knowledge bases that compound
|
||||
|
||||
Andrej Karpathy did something quietly radical in March.
|
||||
|
||||
He posted a thread describing his personal knowledge system. Raw source material goes in. An LLM compiles it into an interlinked markdown wiki. Every time something new comes in, the wiki gets updated, cross-referenced, compressed, pruned. Secondary writeups say one of his research wikis hit around 100 articles and roughly 400,000 words. A book's worth of knowledge, maintained by the AI itself, queryable at the speed of thought.
|
||||
|
||||
That post broke the brain of every prompt engineer on X for a week.
|
||||
|
||||
The reason it mattered is not the specific setup. It is the mental model. Karpathy reframed AI from a transient assistant into a compounding research partner. The reusable asset stopped being the prompt and started being the maintained knowledge layer around the model.
|
||||
|
||||
This matches what I have been building for my own work. A memory layer with decay, deduplication, contradiction handling, pattern detection. A content corpus that gets richer every time I add a new source. A style guide the model learns from by reading my past outputs. None of that is prompt engineering. All of it is context engineering. And all of it compounds, which means every week I put into it makes every future session better without any additional work from me.
|
||||
|
||||
The deepest implication of the Karpathy thread is that durable context is starting to look more valuable than clever prompting. A prompt is good for one response. A well-maintained knowledge base is good for every response you will ever generate from that point forward. That is not a small difference. That is the difference between writing a letter and building a library.
|
||||
|
||||
If you have not started your own version of this, start now. A shared folder. A note-taking app with good tagging. A weekly ritual where you drop everything interesting you read into one place and let an AI sort it. Six months from now you will be the person your team quotes.
|
||||
|
||||
## Beyond naive RAG
|
||||
|
||||
The retrieval trend is the one most commonly miscommunicated on X.
|
||||
|
||||
"RAG is dead" is a bad read. Naive RAG lost credibility. There is a difference.
|
||||
|
||||
Naive RAG is the pipeline you built in 2023. Chunk your documents, embed them, drop them in a vector database, retrieve the top-k matches, stuff them into the prompt. It worked well enough for demos. It fell apart the moment anyone tried to use it on a serious knowledge base with contradictory sources, temporal changes, or queries that required reasoning across multiple documents.
|
||||
|
||||
In 2026 the conversation split into three camps.
|
||||
|
||||
The first camp kept RAG and got serious about it. Better chunking strategies that preserve semantic boundaries. Rerankers that understand query intent instead of keyword overlap. Hybrid search that combines BM25 with vector similarity because neither is enough on its own. This is the camp doing the unglamorous engineering work, and it is where most production teams ended up.
|
||||
|
||||
The second camp went structural. GraphRAG was the flagship idea. Instead of treating your knowledge as an unordered bag of chunks, you extract entities and relationships, build a graph, and let the model reason over the structure. It solves problems naive RAG cannot touch, like "what connects these two papers that never cite each other?" The tradeoff is complexity. Graphs are expensive to build and maintain, and most teams discover halfway through that their knowledge does not need graph reasoning in the first place.
|
||||
|
||||
The third camp went ragless. Not in the sense that retrieval disappeared. In the sense that you pre-compile and maintain a structured knowledge layer the model reasons over directly, instead of doing live retrieval every time. Karpathy's wiki is the canonical example. The model does not chunk-and-retrieve when you ask a question. It reads a maintained document that was designed to be read. The retrieval happened at write time, not at query time.
|
||||
|
||||
All three camps are right about different things. Improved RAG is right for most production teams with structured corpora and clear query patterns. GraphRAG is right for research and analysis where relationships matter more than documents. Ragless is right for personal knowledge and high-leverage domains where you can afford to maintain the corpus manually and reap compound returns.
|
||||
|
||||
The wrong answer is picking one and declaring the others dead. The builders who ship in 2026 are the ones who understand that retrieval architecture is a design choice, not a religion.
|
||||
|
||||
## The convergence nobody is naming
|
||||
|
||||
Here is the thing most of the takes on X are missing.
|
||||
|
||||
Agentic coding. Open-source agent frameworks. Karpathy-style knowledge bases. Beyond-naive RAG. Grok sitting inside every X thread you scroll past. These all look like separate trends. They are the same trend from five different angles.
|
||||
|
||||
The unifying shape is this: AI became workflow-native, persistent, and tool-using.
|
||||
|
||||
Workflow-native means the AI lives inside the actual work, not in a separate chat window. Claude Code inside the terminal. OpenClaw inside Signal. Grok inside the X search bar and every reply you post. You stop context-switching to talk to the AI. The AI shows up where you already are.
|
||||
|
||||
The X product surface is underrated as a signal here. Grok did not win by being the smartest model. It won by being the model that was already in the app you were scrolling. Summaries appear next to trending topics. Replies get AI-assisted drafts. Search gained a reasoning layer. Platform behavior itself became the distribution channel for AI. That is a template every consumer product is now copying, and it is why the "where does the AI live" question is starting to matter more than the "which model is best" question.
|
||||
|
||||
Persistent means memory survives across sessions. Not in the shallow "ChatGPT remembers your name" sense. In the deeper sense where the model knows what you were working on last week and picks up where you left off. Hermes 3's long-term context retention. Claude Code's project files. Your knowledge wiki. The retrieval layer you maintain. All of these are different ways of answering the same question: how does the AI remember anything?
|
||||
|
||||
Tool-using means the AI can do things instead of just saying them. MCP integrations. Permission pipelines. API calls. File edits. Database queries. The model is no longer the bottleneck. The harness around it is.
|
||||
|
||||
Stack those three together and you stop having chatbots and start having coworkers.
|
||||
|
||||
This is why every serious AI team in 2026 is obsessing over the same set of problems. Context management. State persistence. Tool reliability. Error recovery. Permission systems. Observability. None of these sit inside the model. All of them sit in the layer around it.
|
||||
|
||||
If you are an engineer, this is the most important thing to internalize. The model is commodity. The harness around it is not. The team that ships in 2026 is the team that figures out how to build that harness before their competitors do.
|
||||
|
||||
## What this means for you
|
||||
|
||||
You have been reading this thinking one of two things.
|
||||
|
||||
Either "I need to pick one of these trends and go deep." Or "this feels like too much, I will wait until the dust settles."
|
||||
|
||||
Both are wrong.
|
||||
|
||||
You do not need to pick one. You need to pick a workflow you actually do every week and wrap every one of these trends around it, one at a time. If you write code, start with agentic coding. Then add a knowledge base for your stack. Then build a retrieval layer for your past PRs. You will find that each trend makes the next one easier, because they are all pieces of the same machine.
|
||||
|
||||
And you cannot wait for the dust to settle. The dust is not going to settle. The teams building now are going to have a year of compounding context advantage by the time anyone feels ready to start. That is not a prediction. That is what compounding does. You already know this, you just have not applied it to AI yet.
|
||||
|
||||
Start small. Pick one workflow this weekend. Give the AI a project file and a memory layer. One tool it can touch. Run it for a week and see what happens.
|
||||
|
||||
A month from now you will be looking at the person still typing prompts into a chat window and wondering how you ever did it that way.
|
||||
|
||||
That is what 2026 is. Not a better model year. Not a benchmark year. A year where the people who stopped talking to AI and started building around it ran away with the next decade of leverage.
|
||||
|
||||
The rest of this year is about whether you join them now or catch up later.
|
||||
+110
@@ -0,0 +1,110 @@
|
||||
---
|
||||
title: "Everybody Talks About It, Nobody Knows What It Is — Harness Engineering 到底是什么"
|
||||
source: "https://yage.ai/share/harness-demand-side-analysis-20260420.html"
|
||||
author:
|
||||
- "[[鸭哥]]"
|
||||
published: 2026-04-20
|
||||
created: 2026-04-24
|
||||
description: "Harness engineering 火了三个月,没人能定义清楚。这篇从需求侧解释:agent 能力跑在了 infrastructure 前面,管理学早有答案,harness engineering 给了这些旧原则一个精准的新名字。"
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||
## 一个没人定义得了的词,凭什么火三个月
|
||||
|
||||
Dan Ariely 说大数据像 teenage sex:everybody talks about it, nobody really knows how to do it, everyone thinks everyone else is doing it, so everyone claims they’re doing it. Harness engineering 现在就是这个状态。
|
||||
|
||||
AI 领域每隔几周就有一个新概念被推上风口,热闹一阵,然后被下一个概念取代。RAG 是这样,LangChain 是这样,Context Engineering 也是这样。
|
||||
|
||||
Harness Engineering 不太一样。从 2026 年 2 月 [Mitchell Hashimoto 首次提出](https://mitchellh.com/writing/my-ai-adoption-journey) ,到 [OpenAI 正式采用](https://openai.com/index/harness-engineering/) ,到 Garry Tan 的 [Thin Harness Fat Skills](https://x.com/garrytan/status/2042925773300908103) 拿下 140 万阅读,这个概念已经持续了近三个月,热度没有明显衰减。而这三个月里,几乎没有人能给出一个让大家都满意的定义。
|
||||
|
||||
OpenAI 写了一篇好文章,Garry Tan 有影响力,三大公司同时发文形成共振。这些可以解释第一周的热度,但解释不了第三个月的热度。三个月的持续需要需求侧的真实共鸣:一群人在自己的实践中撞上了同一组问题,然后发现 harness 这个词恰好描述了它。
|
||||
|
||||
这组问题是什么?2025 年底到 2026 年初,GPT-5.4、Claude Opus 4.6、Gemini 3 Pro 先后发布,agent 从概念验证进入了生产部署。大量团队在这个过程中同时撞上了五面墙。
|
||||
|
||||
## Agent 撞了哪些墙
|
||||
|
||||
**第一面墙:错误的组合爆炸。** 单个 agent 的错误模式是可管理的,你可以给它加 guard。但两个 agent 串联起来,失败模式不是两个的叠加,而是两个的组合。一个 [医疗场景的案例](https://dev.to/diven_rastdus_c5af27d68f3/the-3-production-failures-that-kill-ai-agents-and-how-we-fixed-each-one-3p59) 能说明这种组合爆炸:三个 agent 各自准确率 95%,Agent A 生成了一个不存在的药物名称,Agent B 基于它检测出虚构的药物相互作用,Agent C 据此向医生发出了紧急警报。每个 agent 的 guard 都通过了(各自的输出格式正确、逻辑自洽),但组合在一起产出了一份完全虚构的高置信度医疗告警。根源在于:传统的逐组件防错机制建立在错误模式可穷举的假设上,agent 的概率性输出让这个假设不再成立。
|
||||
|
||||
**第二面墙:自然语言产出无法度量。** 传统的 observability 度量的是结构化数据:HTTP status code、latency、error rate。你可以对数值设阈值、配告警。但 agent 的核心产出是自然语言。一封催款邮件写得是否精准、细节是否充分、语气是否得当,没有现成的度量手段。一个金融领域的案例:agent 初期生成的催款邮件非常精准,随着处理的边界情况增多,输出逐渐退化为泛泛的模板。模型对 prompt 的理解发生了漂移,而团队完全没有手段在漂移发生时捕捉到它。 [Mezmo 的 AURA 项目负责人](https://tfir.io/ai-agents-production-reliability-mezmo-aura/) 一句话说到了点上:“agents fail silently. They hallucinate, loop, and make confident but incorrect decisions based on incomplete context. Traditional observability stacks offer no visibility into these failures.” 根源在于:传统的观测体系建立在被观测对象是结构化数据的假设上,agent 的自然语言产出让这个假设不再成立。
|
||||
|
||||
**第三面墙:被管理的对象会感知环境并改变行为。** 传统软件的状态由程序员定义,边界清晰。Agent 的 context 完全不同:动态、非结构化、有容量限制,而且 agent 对这个限制有感知,并会据此改变行为。Cognition(Devin 团队)在 [重建产品](https://cognition.ai/blog/devin-sonnet-4-5-lessons-and-challenges) 时发现了 context anxiety:agent 提前感知到 context window 的限制,开始走捷径、提前收尾任务。他们的解决方案完全是环境层面的:开启 1M token context,实际限制使用量在 200K,让模型认为自己还有大量余量。模型没变,环境变了,问题消失了。根源在于:传统的状态管理建立在被管理的对象不会感知资源约束的假设上,agent 对 context 的主动感知让这个假设不再成立。
|
||||
|
||||
**第四面墙:输出不可复现,传统测试失效。** 传统的测试手段(单元测试、集成测试、回归测试)建立在一个前提上:同样的输入产生同样的输出。跑一次 pass 了,就代表以后也会 pass。Agent 的输出每次都不一样,今天 pass 的 case 明天可能 fail。传统的 pass/fail 判定方式不够用,需要的是基于评判标准的持续评估:定义什么样的输出算合格,然后用统计方法判断整体质量是否在可接受范围内。根源在于:传统的验证体系建立在行为可复现的假设上,agent 的概率性输出让这个假设不再成立。
|
||||
|
||||
**第五面墙:治理框架管不住概率性行为。** [McKinsey 的数据](https://www.mckinsey.com/capabilities/quantumblack/our-insights/the-state-of-ai) 显示超过 70% 的企业在试点 AI,但只有不到 20% 成功规模化。 [IDC 的调研](https://thelettertwo.com/2025/11/23/aws-idc-study-ai-agent-adoption-enterprise-2027-scaling-challenges/) 更尖锐:只有 2.9% 的组织在跨部门规模化 agent 应用。具体症状包括 agent 跨系统重复处理数据、API 变更导致 agent 静默失败、管理不善的 agent 产生的 support ticket 比带来的生产力提升更多。企业原有的 IT governance 体系(权限管理、变更控制、审计追踪)假设一个系统被授权做某件事,它就只做那件事,每次都以同样的方式做。Agent 的概率性行为让这个假设不再成立:同样的权限、同样的输入,agent 可能做出授权范围之外的操作。根源在于:传统的治理框架建立在系统行为确定的假设上。
|
||||
|
||||
回过头来看这五面墙,它们有一个统一的模式。每一面墙对应的都是传统软件可靠性保障链条上的一个环节:防错、观测、状态管理、验证、治理。这五个环节合在一起,覆盖了一个软件从运行到交付的完整生命周期。而每个环节失效的原因也是同一个:它的底层假设建立在确定性系统上,agent 的概率性行为打破了这个假设。
|
||||
|
||||
换句话说,agent 不是在某一个点上出了问题,而是让整条可靠性保障链条同时失效了。这些问题不属于模型能力的范畴(你不能等下一代模型来修复它们),也不属于 prompt 或 context engineering 的范畴(后两者关注的是模型的输入质量)。它们是 infrastructure 的问题:agent 的能力跑在了 infrastructure 前面。
|
||||
|
||||
但这些 infrastructure 缺口真的是全新的吗?
|
||||
|
||||
## 太阳下面没有新鲜事
|
||||
|
||||
把上面五面墙放到管理学的语境下看,每一面都有现成的对应物。我们在 [《管理 AI》系列](https://yage.ai/tag/ai-management.html) 中用大量案例论证过这一点:AI 落地中遇到的大多数障碍,在管理人类团队时早就出现过,也早就有成熟的解法。
|
||||
|
||||
错误的组合爆炸,对应的是跨部门协作中的组合性风险。每个部门自己的质量管理可能都过关了,但部门之间的交接点会产生谁都没预见到的新问题。组织管理中的应对是端到端的流程审计、跨部门的 independent review、在关键交接点设置 checkpoint。单独检查每个部门永远不够,你必须检查它们组合在一起的效果。
|
||||
|
||||
自然语言产出无法度量,对应的是考核指标失效。当团队的产出从可量化的(代码行数、工单数、达标率)变成难以量化的(方案质量、沟通效果、判断力),原来的 KPI 体系就不够用了。管理学中的应对是引入定性评估:同行评审、案例复盘、基于 rubric 的多维评分。核心挑战是同一个:你需要为非结构化的产出建立新的度量体系。
|
||||
|
||||
Context anxiety,对应的是员工感知到资源压力后降低标准。人类员工在觉得时间不够或者任务超出能力边界的时候,也会提前收尾、走捷径。管理者的应对方式是合理分配工作量、明确优先级、让员工对资源约束有正确的预期,而不是等到产出质量下降了才去追究。
|
||||
|
||||
测试失效,对应的是产出波动大的团队成员。有些下属的表现时好时差,你不能只看一次交付就下结论,需要持续跟踪多次产出来判断整体水准。管理学中的做法是建立持续的绩效追踪机制,用多次采样来替代单次考核。
|
||||
|
||||
治理框架失效,对应的是组织扩张中的管控失灵。当组织从一个团队扩展到十个团队,原来有效的管理方式开始失效,需要引入层级结构、标准化流程、跨团队协调机制。而且当团队成员的行为不完全可预测时(比如新人、外包团队),你需要更强的审计和权限管理。
|
||||
|
||||
每一面墙在管理学中都有对应的问题和成熟的解法。
|
||||
|
||||
## 既然是管理学,为什么之前没火
|
||||
|
||||
用 AI 就是在做管理,这个观察并不新鲜。
|
||||
|
||||
2023 年, [Karpathy 提出 Software 3.0](https://x.com/karpathy/status/1674873002314563584) ,说开发者的角色从写代码变成了用自然语言指挥和验证 AI 的产出。2024 年, [Ethan Mollick 在 *Co-Intelligence*](https://www.insightpartners.com/ideas/ethan-mollick-on-ai/) 中明确写道 “great AI management, not great models, creates competitive advantage”,并给出了完整的委派-监督-评估框架。同年 [Simon Willison](https://simonwillison.net/2024/Dec/31/llms-in-2024/) 把 agent 定义为 “an LLM that runs tools in a loop”,开发者的角色是提供约束和验证。2025 年 Karpathy 的 [vibe coding](https://thenewstack.io/vibe-coding-is-passe/) 走红之后,他自己也承认实际工作需要 “more oversight and scrutiny”。我们自己从 2025 年初开始写 [《管理 AI》系列](https://yage.ai/tag/ai-management.html) ,核心论点也是同一个:AI 落地中遇到的障碍,在管理人类团队时早就出现过。
|
||||
|
||||
这些观点都对,传播也不差,但没有一个形成持续的热度。为什么?
|
||||
|
||||
因为「管理 AI」这个说法有两个问题。
|
||||
|
||||
第一,它唤起的联想是错的。一说管理学,技术社区的第一反应是:供应链管理、财务管理、人力资源管理,跟我写代码有什么关系?更具体地说,人类管理学里大量精力花在了解你的下属、知道怎么 motivate 他、处理人际关系和政治上。这些对 AI 完全不适用,AI 天生就是被训练成 helpful assistant 的,你不需要花精力去激励它或者处理它的情绪。所以 AI 的管理和人类的管理虽然原则相通,但侧重点完全不同:人类管理的难点在意愿(willingness),AI 管理的难点在可靠性(reliability)。叫管理学,大家想到的是意愿那一半,而 agent 真正需要解决的是可靠性那一半。
|
||||
|
||||
第二,它听起来是软技能。Yuzheng 在 [「名词 vs 动词」](https://www.superlinear.academy/c/share-your-insights/verb) 里点明了这个问题的根源:市场只给名词定价,不给动词定价。Debug 一个 multi-agent 系统的级联错误是动词,设计验证循环是动词,管理 agent 的 context 生命周期是动词。这些动词没有 GitHub 仓库,不能 pip install,不能写进简历的技能栏。叫管理学,它就留在软性认知的货架上。
|
||||
|
||||
Harness engineering 解决了这两个问题。
|
||||
|
||||
## 一个起得好的名字
|
||||
|
||||
Harness 的原始含义是马具。马是有自主能动性的生物,它能自己判断路况、绕开障碍、在骑手醉酒的时候不撞墙。但骑手需要控制方向,需要用 5% 的力气决定 95% 的行进路线。这个隐喻精确地映射了 agent 的特性:有能动性、有判断力,但需要 high-leverage 的引导。
|
||||
|
||||
这和汽车的隐喻完全不同。汽车没有能动性,方向盘往左它就往左,踩刹车它就停。驾驶汽车的心理模型是过程确定性:你控制每一步操作。骑马的心理模型是结果确定性:你给出方向和意图,马自己决定具体怎么走。我们在 [《从过程确定性到结果确定性》](https://yage.ai/result-certainty.html) 和 [《管理 AI:你职业生涯中最重要的一次晋升》](https://yage.ai/ai-management-2.html) 中都用过类似的类比:过去用 API 调用 AI 就像开汽车,你控制每一步操作;现在用 agent 就像骑马,你管方向,它管执行。从 micromanage 到 management 的转变,从过程确定性到结果确定性的转变,说的是同一件事。
|
||||
|
||||
Harness 这个词天然锁定在「引导有自主能力的智能体」这个特定场景上,比管理学的范围窄得多,心理锚点也准确得多。当然,这里面也有 hype 的成分。Harness engineering 听起来比 AI 管理学新、比 AI 管理学酷,这种新鲜感本身就是传播力的一部分。AI 管理学一听就是几十年的老东西,即使内容完全一样,也很难让技术社区兴奋起来。但 hype 只能解释短期传播,三个月的持续热度说明名字之下确实有实质。而这个实质就是:harness engineering 比 agent management 多了一个关键信号:engineering。它宣称这是一个工程学科,有可编码、可传授、可度量的工程实践。当你把一组动词打包成 harness engineering 这个名词,它就从软性认知的货架搬到了硬核技术的货架上,可以被讨论、被学习、被定价了。
|
||||
|
||||
但好名字只解决了认知分类的问题,没有解决内容的问题。名字之下,harness engineering 到底在做什么?
|
||||
|
||||
它在做的事情是:把管理学的旧原则在 agent runtime 这个新环境中重新实现。原则是同一套,工程实践是两套。
|
||||
|
||||
一个更精确的类比是 DevOps。运维的原则几十年没变:监控、告警、容量规划、故障恢复。传统数据中心时代,这些原则的实现工具是 Nagios 做监控、手动 SSH 上服务器查日志、运维团队 oncall 轮值处理故障。Cloud-native 时代,同样的原则有了完全不同的实现:Prometheus + Grafana 做监控、Kubernetes 自动编排容器、Terraform 把基础设施写成代码、GitHub Actions 做 CI/CD 自动化部署。原则没变,但 cloud-native 环境(实例随时创建销毁、状态分布在多个节点、基础设施本身需要版本管理)要求一套全新的工具和实践。DevOps 不是发明了新的运维原则,而是在新的执行环境中重新实现了旧原则。
|
||||
|
||||
Harness engineering 和管理学的关系也是如此。管理人你用 1-on-1、绩效考核、文化建设。管理 agent 你用 checkpoint 设计、验证循环、context 生命周期策略、可观测性 stack。Agent runtime 有自己特有的约束(概率性输出、context window 限制、工具调用的不确定性、多 agent 状态同步),这些约束要求一套新的工程实践来实现管理学中那些老原则。
|
||||
|
||||
2026 年 Q1 的三篇奠基文章,从这个角度看就清晰了。它们各自解决的是管理学原则在 agent runtime 不同维度上的工程实现。OpenAI 的 [harness engineering](https://openai.com/index/harness-engineering/) 解决的是交互维度:人如何用最少的介入来 steer 大量 agent 工作,对应管理学中的 span of control 和 delegation。Cursor 的 [self-driving codebases](https://cursor.com/blog/self-driving-codebases) 解决的是空间维度:几百个 agent 并行如何不踩脚,对应跨团队协调。Anthropic 的 [harness design for long-running apps](https://www.anthropic.com/engineering/harness-design-long-running-apps) 解决的是时间维度:一个 agent 连续跑几小时如何不走偏,对应长周期项目的 milestone management。
|
||||
|
||||
三篇文章的读者群高度重叠,用的术语高度一致,但各自回答的工程问题截然不同。这也是为什么大家对 harness 的定义始终无法收敛:每个人都在往这个词里装自己正在解决的那个特定维度的管理问题。
|
||||
|
||||
## Harness engineering 为什么火
|
||||
|
||||
回到一开始的问题。三大公司同时发文形成共振,这解释了第一周的热度。但三个月的持续需要需求侧的支撑。
|
||||
|
||||
需求侧发生了什么:agent 进入生产环境之后,整条软件可靠性保障链条同时失效了。防错、观测、状态管理、验证、治理,五个环节的底层假设全部建立在确定性系统上,agent 的概率性行为把这些假设逐一打破。实践者在日常工作中撞上了这些问题,然后发现解法并不陌生:管理学里早就有对应的原则和工具。
|
||||
|
||||
原则是旧的,但之前的几次命名尝试都没能让它流行起来。管理 AI 这个说法让人想到意愿和政治,而 agent 的核心挑战在可靠性。Harness engineering 解决了这个命名问题:harness 锁定了「引导有自主能力的智能体」这个特定场景,engineering 声明了这是可编码、可传授的工程学科,两个词合在一起把一组散落的动词打包成了一个可以被讨论和定价的名词。
|
||||
|
||||
所以 harness engineering 的持续热度来自两件事的叠加:一个真实存在的 infrastructure 缺口,和一个终于对上了这个缺口的名字。
|
||||
|
||||
对于实践者来说,这意味着一个好消息和一个坏消息。
|
||||
|
||||
好消息是你不需要从零学一门全新的学科。管过人、管过项目、管过团队,你已经具备了 harness engineering 的原则基础。
|
||||
|
||||
坏消息是原则相通不等于可以直接搬。Agent runtime 有自己特有的约束和机会,需要专门学习的新实践。举几个例子。管理人的时候,团队有 tribal knowledge,很多事情不用写下来大家也知道。Agent 没有 tribal knowledge,所有上下文必须显式写成文档,document first 不是锦上添花而是基本前提。管理人的时候,你不需要担心下属在任务进行到 80% 的时候突然开始偷工减料。Agent 会:当 context window 接近容量上限时,它会感知到压力并开始走捷径(前面讲的 context anxiety)。你需要主动管理 context 的生命周期,在它接近阈值之前做 divide and conquer。管理人的时候,让十个人同时做同一件事然后赛马,成本高、伦理上也说不通。管理 agent 的时候,你可以让十个 agent 并行跑同一个任务,取最优结果,这在统计学里叫 bootstrapping,成本几乎为零,效果显著。
|
||||
|
||||
这些实践在管理人的语境下要么不可能,要么不经济,但在 agent runtime 中是基本操作。Harness engineering 的原则来自管理学,但它的工程实践必须针对 agent 的特性重新设计。这也是为什么它值得有自己的名字。
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: "Experience is now a tax."
|
||||
source: "https://x.com/JayaGup10/status/2047508230813917600"
|
||||
author:
|
||||
- "[[@JayaGup10]]"
|
||||
published: 2026-04-24
|
||||
created: 2026-04-24
|
||||
description: "There is a CIO at a large firm somewhere right now who has never opened Claude, cannot explain what a Claude skill is, and still asks his re..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||
There is a CIO at a large firm somewhere right now who has never opened Claude, cannot explain what a Claude skill is, and still asks his reports to print documents and leave them on his desk. And he is the person making the decision about the firm's AI ROI. Across companies around the world including the Fortune 500, the people with authority over how organizations adopt AI are the people with the least firsthand experience of what these tools can actually do. Meanwhile, a 22 year-old is writing production code in an afternoon, turning a napkin sketch into a working prototype by lunch, and moving between visual and written abstractions with a fluency that took their bosses twenty years to build.
|
||||
|
||||
The two groups are having different experiences of the same technology, and it's making the cultural conversation strange. The senior cohort has settled on two words to explain why they still belong at the top of the stack: judgment and taste. These are things AI cannot replicate. These are things that take decades to develop. These are, conveniently, the exact things the person making the argument has spent a career accumulating. The younger cohort feels that they learn more from an AI in an afternoon than they used to learn from a mentor in a month. They can delete old assumptions and start over with a clean model of a problem in a way someone carrying thirty years of priors physically cannot. And when they bring what they've figured out into a meeting, they watch it get filtered through "well, in my experience" and "that's not how we do things" and "you don't have the context yet."
|
||||
|
||||
**So which is it. Are judgment and taste real, durable skills that AI cannot replicate? Or are they the last ideological defense of a generation that has run out of other advantages?**
|
||||
|
||||
The way humans make decisions is being rewired right now, in real time, at a speed the culture has not caught up to. The algorithms your brain runs when it's trying to figure something out, the ones that have been stable for the entire history of knowledge work, are operating in a different medium for the first time ever. The brains of people who work with AI every day are already wiring differently than the brains of people who don't, and the gap is widening by the month.
|
||||
|
||||
To see it, you have to look at what the mind is actually doing when it's trying to make a decision. For a long time, neuroscientists and computer scientists have pointed out that the brain runs a small set of algorithms that look a lot like the ones computers run. Three of them matter most here: whether to try something new or stick with what's working, what to hold in your head and what to offload, and when to commit versus when to reverse. Each used to be constrained by cost, which AI collapses extremely quickly.
|
||||
|
||||
**Try something new, or stick with what's working**
|
||||
|
||||
Every organization runs this algorithm constantly. Stick with the current strategy, or try a new one? Keep the vendor, or run a new RFP? Hire the same profile that has worked before, or try something different? Historically, trying something new was expensive, someone had to build the case, run the analysis, defend it in a room, and wear the consequences if it failed. So most organizations defaulted to sticking.
|
||||
|
||||
Trying something new is now radically cheaper. A product manager who used to take three weeks to build a competitive positioning memo can now generate five versions by end of day, each benchmarked against real competitor data. A portfolio manager who used to take a quarter to evaluate whether to rotate out of a sector can model six alternative allocations over a weekend.
|
||||
|
||||
Which exposes the real reason most organizations didn't explore before. It was never JUST the cost. It was that the people with the authority to greenlight something new had more to lose from a failed experiment than to gain from a successful one. Senior people have spent careers accumulating credibility, and credibility is expensive to risk. Young people have less of it, and less of it to lose. The bias toward sticking used to have a structural excuse. Now it's become rather personal.
|
||||
|
||||
**What you carry in your head, and what you offload**
|
||||
|
||||
For a long time, being smart in a professional setting meant having the right analogy to reach for. The senior lawyer who remembers that a clause structured this way fell apart in a Delaware case from 2011. The doctor who recognizes a pattern of symptoms because she saw it twice in residency. What looked like intelligence was often retrieval, the person who had spent the longest carrying the most analogies had the fastest access to the right one in the moment.
|
||||
|
||||
AI does not fully replicate that, but it closes the gap dramatically. A second-year lawyer can surface every historical case that resembles the one in front of her, ranked by relevance, in minutes with a synthesis of the "so what". A junior doctor can walk into a diagnostic puzzle with the full pattern library of her field one prompt away. While the experienced person still has better instincts about which analogy is actually the right one, the raw retrieval & synthesis advantage is compressing extremely fast.
|
||||
|
||||
What replaces carrying as the scarce skill is structuring the knowledge. Knowing what to externalize, how to organize it, when to pull it back, which analogy actually fits. That has almost nothing to do with years of experience and everything to do with how fluently someone works with these tools. For the first time in a long time, the person with twenty years of analogies does not automatically beat the person with twenty months of them by simply reciting history as a reason it won't work.
|
||||
|
||||
**When to commit, and when to reverse**
|
||||
|
||||
The third algorithm is the inverse of the first. If trying new things was once expensive, so was committing to the new thing once you chose it. Picking a vendor locked you in for a year. Launching a product meant a quarter of engineering before you could tell if it worked. Choosing a strategy meant defending it for twelve months before you earned the right to change direction. The cost of commitment was high because the cost of reversal was high.
|
||||
|
||||
That is no longer true for a growing class of decisions. You can change your product in an afternoon and change it back the next morning. You can launch a landing page, kill it, launch another before lunch. Commitment used to be a one-way door, but for more and more decisions, it is now a revolving one, which changes the algorithm entirely.
|
||||
|
||||
The old version was: search long enough to be sure, then commit. The new version is: commit quickly, see what happens, reverse if wrong, commit again. The skill is no longer weighing every option before choosing. It is choosing fast, learning fast, and not attaching your identity to the last version of yourself who made the previous choice.
|
||||
|
||||
This is where seniority quietly hurts the most. Senior operators have spent careers learning that reversing is a small admission the last decision was wrong, and they have built reputations that make public wrongness expensive. So they reverse slowly, or not at all. Young people haven't yet learned to attach identity to their decisions. Reversal feels like iteration to them, not failure. Which is, for an increasing share of the decisions that matter, exactly what it is. You can see younger people's priors changing extremely rapidly, hour by hour.
|
||||
|
||||
**So now what?**
|
||||
|
||||
Experience is no longer a moat. frankly, in a lot of cases, it's starting to look like a tax.
|
||||
|
||||
The "judgment" we admire in senior operators is a mix of three things: pattern recognition earned over years, accumulated preferences that are harder to distinguish from facts the longer they live in someone's head, and a growing aversion to being wrong in public. When a senior person says "that won't work," sometimes they are seeing something a younger person can't. Sometimes they are protecting an old decision. Sometimes they genuinely can't afford to be wrong — reputation, politics, sunk cost, the version of the story already told to the board. Real judgment and all of that arrive in the same package. Even the person carrying them can't always tell which is which.
|
||||
|
||||
**However, age is also just a proxy.** What actually matters is how much you have to protect, how much you have to lose, the environment you are in, and your ability to take risks. If you are a product manager, investment banker, a consultant, or someone who picked an ambitious-but-safe career where your next promotion rides on not being wrong in front of important people, where every idea has to survive a wall of constraints before it gets acted on, you don't just sit out the risks you would otherwise take. You become a person whose default mode is "well, think about the risks." A "what if this, what if that" person. Rewriting how you make decisions requires the capacity to act on what you see, not hedge against it. Your capacity for that is partly genetic, partly environmental. Mostly environmental.
|
||||
|
||||
**For the young people reading**
|
||||
|
||||
If you can still think about a problem without first running every thought through "yes but what would my boss or the world say," use that ability now. Use it while you have it. The window narrows faster than you think. It narrows partly through accumulation: reputation, ego, fear, dependents, the decisions you have tied your identity to. But mostly through environment. If you are in a place that punishes the clarity you currently have, where every honest insight has to survive a hundred layers of "we don't do it that way" before it can become action, that environment is training you. It is teaching you to run the filter yourself, so other people don't have to. Eventually you will run it automatically. You will have thoughts and discard them before they finish forming, because your nervous system has learned they are not worth having. That is the version of aging that is actually dangerous.
|
||||
|
||||
If you are in that kind of environment, leave. The comparative advantage of being young is not that you are smarter or more talented, but that you can still think clearly, without a filter, because no one has taught you not to yet.
|
||||
|
||||
That is your asset!
|
||||
@@ -0,0 +1,299 @@
|
||||
---
|
||||
title: "From Skills to Systems: 5 Multi-Agent Orchestration Patterns in ADK 2.0"
|
||||
source: "https://x.com/GoogleCloudTech/status/2047367046070161674"
|
||||
author:
|
||||
- "[[@GoogleCloudTech]]"
|
||||
published: 2026-04-24
|
||||
created: 2026-04-24
|
||||
description: "A few weeks ago, our article on 5 Agent Skill design patterns went viral. The patterns (Tool Wrapper, Generator, Reviewer, Inversion, Pipeli..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
A few weeks ago, our article on [5 Agent Skill design patterns](https://x.com/GoogleCloudTech/status/2033953579824758855?s=20) went viral. The patterns (Tool Wrapper, Generator, Reviewer, Inversion, Pipeline) gave developers a structural vocabulary for designing agent skills. But a single skill, no matter how well-designed, only solves part of the problem.
|
||||
|
||||
The harder question is: how do you orchestrate multiple skills across multiple agents in a production system? How do you ensure that Agent A's output is the right format for Agent B's input? How do you enforce that certain steps always happen in a certain order while still allowing AI flexibility within each step? How do you coordinate agents written in different languages by different teams?
|
||||
|
||||
**At Google Cloud Next 26, we launched Agent Development Kit (ADK) 2.0** that answers these questions with three core additions: graph-based workflows, collaborative agents, and a formalized Skills framework. Here are five orchestration patterns that will take you to the next level of agent architecture.
|
||||
|
||||
**By** [@addyosmani](https://x.com/@addyosmani) **and** [@Saboo\_Shubham\_](https://x.com/@Saboo_Shubham_)
|
||||
|
||||
## Pattern 1: The Hybrid Graph
|
||||
|
||||
The most common production failure in agent systems is an orchestration failure. The agent reasons correctly about each individual step but executes them in the wrong order, skips a mandatory step, or takes a path that no human reviewer anticipated.
|
||||
|
||||
This happens because most agent architectures encode workflow logic inside system prompts. The LLM follows the instructions faithfully for the first few turns. By turn seven, it starts taking shortcuts. By turn twelve, it's skipping steps entirely. This is a fundamental limitation of using natural language instructions to define procedural workflows. LLMs are optimizers. They're trained to produce helpful outputs efficiently. When the model looks at a five-step workflow, it often decides it can produce a more helpful response by combining steps or reordering them.
|
||||
|
||||
ADK 2.0's graph-based workflows solve this structurally. You define agent logic as a directed graph where nodes are actions and edges are transitions with conditional logic. The critical innovation is that you can mix deterministic nodes (hard-coded business rules) with AI-driven nodes (LLM reasoning) in the same graph.
|
||||
|
||||

|
||||
|
||||
Here's a concrete example: a loan application processing agent. Some steps must be deterministic (regulatory compliance checks, credit score thresholds, documentation requirements). Other steps benefit from AI flexibility (assessing document quality, summarizing financial profiles, generating recommendations).
|
||||
|
||||
```python
|
||||
from google.adk import Agent, Graph, Node, Edge
|
||||
|
||||
loan_processor = Graph(name="loan-processor")
|
||||
|
||||
# Deterministic node: validate required documents
|
||||
@loan_processor.node("validate_docs")
|
||||
def validate_documents(application):
|
||||
required = ["id_proof", "income_proof", "address_proof", "bank_statements"]
|
||||
missing = [doc for doc in required if doc not in application.documents]
|
||||
if missing:
|
||||
return {"status": "incomplete", "missing": missing}
|
||||
return {"status": "complete"}
|
||||
|
||||
# AI-driven node: assess document quality
|
||||
@loan_processor.node("assess_quality")
|
||||
async def assess_document_quality(application, llm):
|
||||
return await llm.analyze(
|
||||
prompt="Evaluate the quality and authenticity of these documents. "
|
||||
"Flag any concerns about readability, completeness, or "
|
||||
"potential inconsistencies.",
|
||||
documents=application.documents
|
||||
)
|
||||
|
||||
# Deterministic node: credit score check
|
||||
@loan_processor.node("credit_check")
|
||||
def check_credit_score(application):
|
||||
score = application.credit_score
|
||||
if score >= 750:
|
||||
return {"tier": "prime", "auto_approve": True}
|
||||
elif score >= 650:
|
||||
return {"tier": "standard", "auto_approve": False}
|
||||
else:
|
||||
return {"tier": "subprime", "auto_approve": False, "flag": True}
|
||||
|
||||
# AI-driven node: generate recommendation
|
||||
@loan_processor.node("recommendation")
|
||||
async def generate_recommendation(application, assessment, credit, llm):
|
||||
return await llm.analyze(
|
||||
prompt="Based on the document assessment and credit check, "
|
||||
"generate a loan recommendation with risk factors "
|
||||
"and suggested terms.",
|
||||
context={"assessment": assessment, "credit": credit}
|
||||
)
|
||||
|
||||
# Deterministic node: compliance check
|
||||
@loan_processor.node("compliance")
|
||||
def compliance_check(recommendation):
|
||||
# Hard-coded regulatory rules that cannot be AI-driven
|
||||
violations = []
|
||||
if recommendation.apr > MAX_LEGAL_APR:
|
||||
violations.append("APR exceeds regulatory maximum")
|
||||
if recommendation.term_months > MAX_TERM:
|
||||
violations.append("Term exceeds maximum allowed")
|
||||
return {"compliant": len(violations) == 0, "violations": violations}
|
||||
|
||||
# Define the graph edges with conditions
|
||||
loan_processor.add_edge("validate_docs", "assess_quality",
|
||||
condition=lambda r: r["status"] == "complete")
|
||||
loan_processor.add_edge("validate_docs", "request_missing_docs",
|
||||
condition=lambda r: r["status"] == "incomplete")
|
||||
loan_processor.add_edge("assess_quality", "credit_check")
|
||||
loan_processor.add_edge("credit_check", "recommendation")
|
||||
loan_processor.add_edge("recommendation", "compliance")
|
||||
loan_processor.add_edge("compliance", "human_review",
|
||||
condition=lambda r: not r["compliant"])
|
||||
loan_processor.add_edge("compliance", "auto_approve",
|
||||
condition=lambda r: r["compliant"])
|
||||
```
|
||||
|
||||
The key difference from prompt-based orchestration: the mandatory structure is enforced by the framework. The LLM has flexibility within each node but cannot skip nodes or reorder the graph. The deterministic nodes are unit-testable with standard testing frameworks. The AI-driven nodes can be evaluated separately using Agent Simulation. And the graph structure itself is inspectable, so a compliance officer can review the workflow and verify that every required step is included and properly ordered without reading any LLM prompts.
|
||||
|
||||
## Pattern 2: The Coordinator-Specialist
|
||||
|
||||
The "God agent" is the most common anti-pattern in production agent systems. One agent tries to do everything: customer support, data analysis, document generation, API integration. Its system prompt is thousands of tokens long, its tool set is enormous, and its behavior is unpredictable because the LLM is constantly deciding between dozens of possible actions.
|
||||
|
||||
The problem gets worse as you add capabilities. Around the fifth major addition, the system becomes unreliable. The agent uses the wrong tool for the task. It applies the customer support tone when doing data analysis. It follows financial compliance rules when answering a simple question about project timelines. The instructions compete for the model's attention, and the model starts making tradeoffs you didn't anticipate.
|
||||
|
||||
ADK 2.0's collaborative agents provide native support for the coordinator-specialist pattern. A coordinator agent handles task routing and workflow management. Specialist agents handle domain-specific work with focused context and tools.
|
||||
|
||||
```python
|
||||
from google.adk import Agent, CoordinatorAgent, TransferProtocol
|
||||
|
||||
# Specialist agents with focused responsibilities
|
||||
data_analyst = Agent(
|
||||
name="data-analyst",
|
||||
instructions="""You are a data analysis specialist. You have access
|
||||
to BigQuery and can run SQL queries, generate visualizations, and
|
||||
produce statistical summaries. Focus exclusively on data tasks.
|
||||
If asked about anything outside data analysis, transfer back
|
||||
to the coordinator.""",
|
||||
tools=[bigquery_tool, visualization_tool, statistics_tool]
|
||||
)
|
||||
|
||||
document_writer = Agent(
|
||||
name="document-writer",
|
||||
instructions="""You are a technical document specialist. You produce
|
||||
reports, summaries, and documentation in structured formats.
|
||||
You do not access databases or run queries. If the user needs
|
||||
data analysis, transfer to the coordinator for routing.""",
|
||||
tools=[markdown_tool, template_tool, format_tool],
|
||||
skills=["report-generator", "executive-summary"] # ADK Skills
|
||||
)
|
||||
|
||||
customer_expert = Agent(
|
||||
name="customer-expert",
|
||||
instructions="""You are a customer context specialist. You have
|
||||
access to CRM data, support ticket history, and customer
|
||||
communication logs. Provide customer insights but do not
|
||||
generate reports - transfer to the coordinator for that.""",
|
||||
tools=[salesforce_tool, zendesk_tool, email_search_tool]
|
||||
)
|
||||
|
||||
# Coordinator agent that routes tasks
|
||||
coordinator = CoordinatorAgent(
|
||||
name="project-coordinator",
|
||||
specialists=[data_analyst, document_writer, customer_expert],
|
||||
transfer_protocol=TransferProtocol.CONTEXTUAL,
|
||||
instructions="""You are a project coordinator. When a user makes
|
||||
a request, determine which specialist(s) need to be involved.
|
||||
For complex requests that span multiple domains, orchestrate
|
||||
the specialists in sequence: gather data first, then generate
|
||||
the report.
|
||||
|
||||
Example routing:
|
||||
- "Analyze Q3 sales data" → data-analyst
|
||||
- "Write the quarterly report" → document-writer
|
||||
- "What's the history with Acme Corp?" → customer-expert
|
||||
- "Create a report on Acme Corp's Q3 performance" →
|
||||
customer-expert (context) → data-analyst (numbers) →
|
||||
document-writer (final report)"""
|
||||
)
|
||||
```
|
||||
|
||||
The transfer protocol defines how context flows between agents during handoffs. 𝚃𝚛𝚊𝚗𝚜𝚏𝚎𝚛𝙿𝚛𝚘𝚝𝚘𝚌𝚘𝚕.𝙲𝙾𝙽𝚃𝙴𝚇𝚃𝚄𝙰𝙻 means the coordinator includes relevant context from the previous specialist's output when transferring to the next specialist. The document writer does not need to re-query the database - it receives the data analyst's output as context.
|
||||
|
||||
Each specialist has its own identity (via **Agent Identity**), its own tool permissions (governed by **Agent Gateway**), and its own memory context. The data analyst cannot access CRM data. The customer expert cannot run SQL queries. The blast radius of any single agent's malfunction is contained to its domain.
|
||||
|
||||
This pattern also simplifies testing and iteration. When the data analyst's output quality degrades, you evaluate and fix that one specialist. You don’t need to retrain or re-prompt a monolithic agent. When you add a new capability (say, a competitive intelligence specialist), you register it with the coordinator and it is available immediately.
|
||||
|
||||
## Pattern 3: Skill Composition
|
||||
|
||||
In our previous article, we covered five skill design patterns: Tool Wrapper, Generator, Reviewer, Inversion, and Pipeline. ADK 2.0 formalizes these with a declarative Skills framework that makes skills first-class citizens in multi-agent workflows.
|
||||
|
||||
The key addition is 𝚂𝚔𝚒𝚕𝚕𝚃𝚘𝚘𝚕𝚜𝚎𝚝, which lets agents load and use skills as tools. An agent does not need to know the internal implementation of a skill. It knows the skill's name, its description, and its interface. This enables composition - chaining skills together across agents in ways the original skill authors did not anticipate.
|
||||
|
||||

|
||||
|
||||
Here’s how this works in practice. Imagine you have three existing skills built by three different teams:
|
||||
|
||||
```text
|
||||
skills/
|
||||
├── data-extractor/
|
||||
│ └── SKILL.md # Pattern: Tool Wrapper (extracts data from APIs)
|
||||
├── trend-analyzer/
|
||||
│ └── SKILL.md # Pattern: Pipeline (multi-step trend analysis)
|
||||
└── executive-summary/
|
||||
└── SKILL.md # Pattern: Generator (produces formatted summaries)
|
||||
```
|
||||
|
||||
A coordinator agent can compose these skills into a workflow that none of them was individually designed for:
|
||||
|
||||
```python
|
||||
from google.adk import Agent, SkillToolset
|
||||
|
||||
market_intelligence = Agent(
|
||||
name="market-intelligence",
|
||||
skills=SkillToolset([
|
||||
"data-extractor", # Pulls data from market APIs
|
||||
"trend-analyzer", # Runs statistical trend analysis
|
||||
"executive-summary" # Generates formatted reports
|
||||
]),
|
||||
instructions="""You are a market intelligence agent. When asked
|
||||
for a market analysis:
|
||||
1. Use data-extractor to pull relevant market data
|
||||
2. Pass the data to trend-analyzer for pattern identification
|
||||
3. Use executive-summary to format findings for leadership
|
||||
|
||||
Each skill handles its own domain. Your job is orchestration
|
||||
- ensuring the output of each skill is properly formatted
|
||||
as input for the next skill in the chain."""
|
||||
)
|
||||
```
|
||||
|
||||
Thanks to progressive disclosure, the agent only loads a skill's full context when it actually invokes that skill. If a user asks a simple question that does not require trend analysis, the trend-analyzer skill's instructions, references, and assets are never loaded into the context window. This keeps context token usage efficient even when an agent has access to dozens of skills.
|
||||
|
||||
This is the same insight that made npm, pip, and Maven successful: small, focused, composable packages with clear interfaces are more valuable than large, monolithic libraries. Individual teams build skills for their domain (data engineering builds extraction skills, analytics builds analysis skills, communications builds formatting skills). A coordinator agent assembled by the platform team can compose these into workflows that cross organizational boundaries without any of those teams needing to coordinate directly.
|
||||
|
||||
## Pattern 4: The Cross-Language Pipeline
|
||||
|
||||
ADK is now available in four different languages: Python, TypeScript, Go, and Java. Each SDK has native support for the A2A (Agent-to-Agent) protocol. This means an agent written in Python can seamlessly delegate to an agent written in Go, which can delegate to an agent written in Java.
|
||||
|
||||
This matters in organizations where different teams use different languages. The ML team writes Python. The platform team writes Go. The enterprise integration team writes Java. The frontend team writes TypeScript. Previously, building a multi-agent workflow across these teams required custom API integrations, protocol negotiation, and data format translation. A2A standardizes all of that.
|
||||
|
||||
Here's what a cross-language pipeline looks like in practice:
|
||||
|
||||

|
||||
|
||||
Each agent publishes its capabilities via an Agent Card at /.𝚠𝚎𝚕𝚕-𝚔𝚗𝚘𝚠𝚗/𝚊𝚐𝚎𝚗𝚝-𝚌𝚊𝚛𝚍.𝚓𝚜𝚘𝚗. Other agents discover these capabilities automatically. The A2A protocol handles task management, status updates, and result streaming. From each agent's perspective, delegating to a remote agent in a different language feels like calling a local function.
|
||||
|
||||
Each SDK also brings language-specific strengths to the pipeline. ADK Go 1.0 added OpenTelemetry integration for distributed tracing across multi-agent pipelines, self-healing logic via plugins, and YAML-based agent definitions that let you manage agents declaratively (the same way you manage Kubernetes manifests or Terraform resources). The Java SDK adds event compaction for managing long conversation histories and ToolConfirmation for human-approval workflows that are critical for enterprise governance.
|
||||
|
||||
## Pattern 5: The Sandboxed Executor
|
||||
|
||||
The final pattern addresses a common requirement: agents that need to execute code as part of their workflow. A data analysis agent needs to run pandas operations. A code review agent needs to execute tests. A document processing agent needs to run transformation scripts.
|
||||
|
||||
Running arbitrary code inside an agent is a security risk if the execution environment isn't isolated. ADK 2.0 provides secure workspaces: hardened, sandboxed environments where agents can run bash commands, manage files, and execute code, all isolated from your core systems.
|
||||
|
||||

|
||||
|
||||
Here’s the code implementation in Python:
|
||||
|
||||
```python
|
||||
from google.adk import Agent, SecureWorkspace
|
||||
|
||||
code_analyst = Agent(
|
||||
name="code-analyst",
|
||||
workspace=SecureWorkspace(
|
||||
allowed_commands=["python", "pip", "pytest", "git"],
|
||||
filesystem_access="read-write", # Within sandbox only
|
||||
network_access="restricted", # Allowlisted domains only
|
||||
max_execution_time=300, # 5-minute timeout per command
|
||||
resource_limits={"memory": "2G", "cpu": "2"}
|
||||
),
|
||||
instructions="""You are a code analysis specialist. When reviewing
|
||||
code, you can:
|
||||
1. Clone the repository into your workspace
|
||||
2. Install dependencies
|
||||
3. Run the test suite
|
||||
4. Execute static analysis tools
|
||||
5. Report findings with evidence from actual test results
|
||||
|
||||
Your workspace is sandboxed. You cannot access systems outside
|
||||
your allowed network domains. All file operations are confined
|
||||
to your workspace directory."""
|
||||
)
|
||||
```
|
||||
|
||||
The sandbox boundary is the critical security property. The agent can run arbitrary Python code within its workspace, but that code cannot access the host filesystem, cannot make network connections to unapproved domains, and cannot escalate privileges. If the agent's code execution goes haywire - an infinite loop, excessive memory allocation, an attempt to access restricted resources - the sandbox enforces hard limits.
|
||||
|
||||
This pattern is particularly powerful combined with the Pipeline skill pattern from our previous article. A documentation pipeline skill that needs to parse source code, generate docstrings, and assemble a final document can execute each step in the sandbox, using actual code execution rather than LLM reasoning for the parsing step. The result is more reliable - parsing Python ASTs with actual Python is more accurate than asking an LLM to reason about code structure.
|
||||
|
||||
## Choosing the right orchestration pattern
|
||||
|
||||
These patterns compose, just like the skill patterns from our previous article:
|
||||
|
||||
- A **Hybrid Graph** can use **Coordinator-Specialist** at individual nodes - the graph defines the overall workflow, and specialist agents handle domain-specific nodes
|
||||
- A **Coordinator-Specialist** setup can use **Skill Composition** within each specialist - each specialist loads only the skills relevant to its domain
|
||||
- A **Cross-Language Pipeline** can use **Sandboxed Executors** at any stage - the Python agent runs ML models in a sandbox, the Go agent runs compliance checks with sandboxed test data
|
||||
- Any pattern can incorporate the five skill patterns (Tool Wrapper, Generator, Reviewer, Inversion, Pipeline) from our previous article at the individual skill level
|
||||
|
||||

|
||||
|
||||
## Getting Started
|
||||
|
||||
ADK 2.0 is available now. Install with pip install google-adk --pre (Python 3.11+). Your existing ADK 1.x agents are backward compatible, though advanced implementations may need migration testing.
|
||||
|
||||
The ADK samples repository ([github.com/google/adk-samples](https://github.com/google/adk-samples)) includes 30+ sample agents across Python, TypeScript, Go, and Java, covering patterns from simple tool wrappers to complex multi-agent workflows.
|
||||
|
||||
Documentation: [adk.dev](https://adk.dev/) GitHub Repos: [ADK Python](https://github.com/google/adk-python) | [ADK Java](https://github.com/google/adk-java) | [ADK Go](https://github.com/google/adk-go) | [ADK TypeScript](https://github.com/google/adk-js)
|
||||
|
||||
## 🚢 From Agent Skills to Systems: Google for Startups AI Agents Challenge
|
||||
|
||||
Move beyond the demos by joining our 6-week global challenge for startups to build, optimize, or refactor autonomous agents on the Gemini Enterprise Agent Platform.
|
||||
|
||||
You'll get **$500 in cloud credits**, full platform access, and a shot at the **$90,000 prize pool**. Put these ADK 2.0 orchestration patterns into practice and build production-ready agent systems. [Sign up today to start building](https://devpost.team/hackathon_guest_invites/4fb181b4-2722-415d-a442-285a57dcaba5?utm_source=twitter&utm_medium=social&utm_campaign=google-for-startups-ai-agents-challenge&utm_content=twitter-post)!
|
||||
@@ -0,0 +1,123 @@
|
||||
---
|
||||
title: "Garry Tan 的 Thin Harness, Fat Skills:五个概念拆解,以及怎么落地"
|
||||
source: "https://yage.ai/share/thin-harness-fat-skills-20260414.html"
|
||||
author:
|
||||
- "[[鸭哥]]"
|
||||
published: 2026-04-14
|
||||
created: 2026-04-24
|
||||
description: "Garry Tan 提出 AI 系统的五层架构。这五个概念和我们过去一年独立推导出的体系几乎一一对应。逐个映射对应关系,标注各自走得更深的地方,讨论独立收敛说明了什么。"
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||
> **日期**: 2026-04-14 **来源**: [Garry Tan, X Article](https://x.com/garrytan/status/2042925773300908103) (2026-04-11, ~1M views) **类型**: 概念解读 + 实践映射
|
||||
|
||||
上周 Garry Tan 在 X 上发了一篇长文 [Thin Harness, Fat Skills](https://x.com/garrytan/status/2042925773300908103) ,百万阅读,几千收藏。Steve Yegge 说用 AI coding agent 的人比用 Cursor 聊天的人效率高 10x-100x。Garry 的解释是:差距来自架构,具体来说是五个概念的组合。
|
||||
|
||||
这五个概念每一个都指向了一个实际的工程问题。这篇文章逐个拆解它们,同时给出我们过去一年在实践中找到的对应实现。我们在今年早些时候把这套实践体系 [开源](https://github.com/grapeot/context-infrastructure) 了。下面每个概念后面,我会直接链到对应的文件或目录,有兴趣的读者可以直接看代码。
|
||||
|
||||
## 概念一:Skill Files
|
||||
|
||||
Garry 定义 skill file 为用 markdown 写成的可复用程序。它描述的是判断过程,而非固定答案。同一个 /investigate skill,传入安全科学家和 250 万封邮件就变成医学调查,传入竞选资金数据就变成政治献金追踪。他说这不是 prompt engineering,是 software design,只不过用 markdown 当编程语言。
|
||||
|
||||
他提到一个多数人忽略的洞察:skill file 像方法调用一样接受参数。同一个流程,不同参数,完全不同的能力。
|
||||
|
||||
在我们的系统里,这对应 [Skills 体系](https://github.com/grapeot/context-infrastructure/tree/main/rules/skills) 。当前有 40 多个 skill 文件,每个都有触发词、参数、依赖声明和执行流程。比如 [深度调研工作流](https://github.com/grapeot/context-infrastructure/blob/main/rules/skills/workflow_deep_research_survey.md) 定义了从初步扫描到多 Agent 并行到交叉验证的完整流程, [并行 Subagent 工作流](https://github.com/grapeot/context-infrastructure/blob/main/rules/skills/workflow_parallel_subagents.md) 定义了什么时候该拆任务、怎么控制并行度、overlap 怎么设。这些 skill 在使用中被修正和扩展,积累的知识不随会话结束消失。
|
||||
|
||||
Garry 说”every skill you write is a permanent upgrade to your system”。这正是我们观察到的:每个 skill 是系统的永久升级,模型更新时 skill 自动受益,确定性步骤保持稳定。 [Skills 索引](https://github.com/grapeot/context-infrastructure/blob/main/rules/skills/INDEX.md) 是完整列表。
|
||||
|
||||
## 概念二:Thin Harness
|
||||
|
||||
Garry 的核心主张是 harness(运行模型的那层程序)只做四件事:循环调用模型、读写文件、管理上下文、执行安全策略。他反对 fat harness:40 多个工具定义占掉半个上下文窗口,God-tools 每次 MCP 调用 2-5 秒。他用 Playwright CLI vs Chrome MCP 的 75 倍性能差距来量化这个问题。
|
||||
|
||||
设计原则是方向性的:把智能向上推到 skills,把执行向下推到确定性工具,中间保持最薄。
|
||||
|
||||
我们在实践中得到了相同结论,并且在 [《从过程确定性到结果确定性》](https://yage.ai/result-certainty.html) 中做了更细的分析。我们提出 AI 集成有四层:Model、Protocol、Runtime、Contract。多数人把注意力放在 Protocol 层(怎么调 API),但 Runtime 层消耗最多时间。好消息是 Runtime 层正在成为公共产品:Claude Code、Codex、Cursor Agent 都在收敛为可复用的 Agentic Runtime。模型提供商为了兼容这些工具,主动适配自己的故障模式,意味着长尾问题从你一个团队的负担变成了整个生态的共同投入。
|
||||
|
||||
所以 Garry 说 harness 要薄,我们更进一步:harness 应该直接外包给现有的 agentic runtime,你只需要在上面叠 skills 和确定性工具。我们的系统就是这么做的: [AGENTS.md](https://github.com/grapeot/context-infrastructure/blob/main/AGENTS.md) 是整个系统的入口,它在 Claude Code 或 OpenCode 的 agentic loop 上面运行,harness 本身不是我们写的,我们只写上面的 skills 和下面的 tools。
|
||||
|
||||
## 概念三:Resolvers
|
||||
|
||||
Garry 的 resolver 是上下文的路由表。当任务类型 X 出现,先加载文档 Y。他举了一个例子:开发者改 prompt 文件,resolver 自动加载 eval 文档,开发者甚至不知道 eval suite 存在。他还提到自己的 CLAUDE.md 从 20,000 行砍到 200 行指针文档,因为模型注意力在大量上下文中退化。
|
||||
|
||||
在我们的系统里,这对应一个三级缓存结构,灵感来自 CPU 内存层级。
|
||||
|
||||
**L1 cache** (每次都加载): [AGENTS.md](https://github.com/grapeot/context-infrastructure/blob/main/AGENTS.md) 。200 行左右,只有指针和最核心的行为定义。Garry 砍 CLAUDE.md 到 200 行的经验,我们也经历过,最终的解法一样。
|
||||
|
||||
**L2 cache** (按需查索引): [Skills INDEX.md](https://github.com/grapeot/context-infrastructure/blob/main/rules/skills/INDEX.md) 和 [Axioms INDEX.md](https://github.com/grapeot/context-infrastructure/blob/main/rules/axioms/INDEX.md) 。模型知道有哪些能力和原则可用,但不加载具体内容。
|
||||
|
||||
**L3 cache** (匹配后加载):具体的 [skill 文件](https://github.com/grapeot/context-infrastructure/tree/main/rules/skills) 和 [axiom 文件](https://github.com/grapeot/context-infrastructure/tree/main/rules/axioms) 。只有当模型匹配到用户意图后才加载。每个文件都有 description 和触发词,路由是自动的。
|
||||
|
||||
Garry 的 resolver 路由到 skill 和文档。我们多做了一层:除了路由到 skill(改变模型怎么做事),还路由到 axiom(改变模型用什么判断框架做事)。这层差异后面会展开。
|
||||
|
||||
我们把这套分层方案的设计思路写在了 [《为什么 AI 只会说正确的废话》](https://yage.ai/context-infrastructure.html) 里。
|
||||
|
||||
## 概念四:Latent vs. Deterministic
|
||||
|
||||
Garry 说系统中每一步要么属于 latent space(模型做判断),要么属于 deterministic space(程序做执行)。模型可以考虑 8 个人的社交动态来安排座位,但让它安排 800 个人的座位就会输出看似合理、完全错误的方案。他在 YC 系统里的正确做法是:模型发明主题(latent),确定性算法执行分配(deterministic)。
|
||||
|
||||
这条分界线在我们的体系里对应公理 [T02:结果确定性优于过程确定性](https://github.com/grapeot/context-infrastructure/blob/main/rules/axioms/t02_results_certainty.md) 。Garry 关注怎么划界。我们在划完界之后多走了一步:对 latent 一侧的输出,怎么建立信任?
|
||||
|
||||
答案是把验收标准写成可执行的检查。在翻译场景中,我们发现翻译失败的根本原因是模型不知道什么叫”完成”。一旦把标准写成脚本(格式是否正确、有没有中文泄漏、术语是否一致),模型就能自己跑检查、自己修正、循环到达标为止。我们把这个过程的完整案例写在了 [《从过程确定性到结果确定性》](https://yage.ai/result-certainty.html) 里。
|
||||
|
||||
另外,我们在 2025 年 11 月提出的 [Generative Kernel](https://yage.ai/ai-software-engineering.html) 里有一个组件叫 Leverage Toolkit,专门处理 latent 和 deterministic 的交界地带:对于模型概念上理解但执行容易出错的任务,提供确定性工具让模型调用。这和 Garry 说的 deterministic foundation 是同一个位置。
|
||||
|
||||
## 概念五:Diarization
|
||||
|
||||
Garry 的 diarization 是让模型读取关于某个主体的所有材料,输出一页结构化画像。他举了一个具体例子:一个 founder 说自己做”Datadog for AI agents”,但 80% 的 commit 在 billing 模块。模型需要同时读 GitHub 提交历史、申请表和 advisor transcript,三者交叉才能发现”说的和做的不一致”。他明确说 no SQL query produces this, no RAG pipeline produces this。
|
||||
|
||||
这个判断我们完全认同。我们的对应实现是一套三层蒸馏机制,不过维度不同。Garry 的 diarization 是横向的(多源交叉,per-entity),我们的 Layered Distillation 是纵向的(时间蒸馏,per-person)。
|
||||
|
||||
L1 Observer 每天扫描文件变化和对话记录,提取有意义的观察。L2 Reflector 每周合并去重、识别跨项目的重复模式。L3 Axiom 把经过时间检验的稳定模式提炼为决策原则。筛选标准是稳定性:只有在不同情境和不同时间跨度中反复出现的判断,才进入公理层。
|
||||
|
||||
一年积累下来,我们的系统蒸馏出了 [43 条 axiom](https://github.com/grapeot/context-infrastructure/blob/main/rules/axioms/INDEX.md) ,覆盖 AI 协作、技术决策、管理哲学和信任验证四个领域。每条 axiom 都有具体的来源场景、应用判定和边界条件。比如 [A04:可靠性是管理问题](https://github.com/grapeot/context-infrastructure/blob/main/rules/axioms/a04_reliability_management.md) 说的是 AI 不可靠的根源通常是你把它当工具而非团队成员, [V02:可验证性是信任的地基](https://github.com/grapeot/context-infrastructure/blob/main/rules/axioms/v02_verifiability.md) 说的是要设计可检测错误的架构而非期望零错误。
|
||||
|
||||
Garry 和我们的共同判断是:这一步只有模型能做,关键词搜索和向量检索都做不到。分歧在于蒸馏的方向:横向(多源交叉发现矛盾)还是纵向(时间过滤出稳定模式)。两者解决不同的问题,可以组合。
|
||||
|
||||
## Garry 跳过的一步:怎么让人愿意放下键盘
|
||||
|
||||
Garry 整篇文章有一个隐含前提:读者已经接受了设计系统让模型执行、自己不亲自写代码的工作方式。但在实际观察中,这一步恰恰是多数技术人员卡住的地方。
|
||||
|
||||
技术能力越强的人越容易掉进这个陷阱:看到模型犯了一个你能三秒修复的错误,本能反应就是自己上手。表面上你比模型快,但如果你管理的是多个并行 AI 会话,每次都抢键盘的话效率会迅速崩塌。
|
||||
|
||||
我们在 [《AI 管理三大陷阱》](https://yage.ai/ai-management.html) 中分析了这个问题,并在公理 [A03:从 IC 到经理的心智转变](https://github.com/grapeot/context-infrastructure/blob/main/rules/axioms/a03_ic_to_manager.md) 中把管理者的五个职能映射到了 AI 协作场景。选人对应模型选择,委派对应任务分解加上下文准备,培训对应持久化的知识库(也就是 Garry 说的 skill files),指导对应教方法而非给答案,验收对应可观测的标准(也就是结果确定性)。
|
||||
|
||||
换个角度看,Garry 描述的整套架构其实就是 AI 管理学的工程实现。Skill files 是培训材料,resolvers 是工作分配系统,latent vs. deterministic 是任务委派的边界判断,thin harness 是管理者不应该做的事。只不过他跳过了起点:怎么让一个技术专家完成从执行者到管理者的转变。
|
||||
|
||||
## 再多走一步:Consensus Ceiling
|
||||
|
||||
Garry 的框架让模型高效执行。但还有一个问题他没有触及:模型输出的认知深度。
|
||||
|
||||
我们用一个 [对照实验](https://yage.ai/context-infrastructure.html) 展示了这个问题。两个配置几乎相同的 AI 系统(相当的模型、相同的 skill、相同的工具、相同的 prompt),唯一区别是背后的认知上下文。一个有一年积累的判断框架,另一个没有。两个系统分析同一个话题,产出的报告在性质上完全不同。一个给出行动清单:建 AGENTS.md、写规则进 repo、CI 检查文档。另一个给出判断:完美主义是吞吐量的敌人,两家公司都接受了纠错比等待便宜这个权衡。
|
||||
|
||||
LLM 的训练机制决定了默认输出是共识。Next token prediction 输出最高概率 token,RLHF 进一步惩罚争议性输出。两层叠加,默认行为就是回归均值。这就是 consensus ceiling。
|
||||
|
||||
打破这个 ceiling,需要的不只是更好的 skill,而是密度足够高的个人认知上下文去覆盖训练时植入的共识先验。这就是为什么前面提到我们的 resolver 多了一层 axiom 路由。Skill 改变模型怎么做事(执行效率),axiom 改变模型用什么框架做判断(认知深度)。两者是正交维度。
|
||||
|
||||
Garry 的读者在应用他的框架后,会得到一个高效、准确、可扩展的 AI 系统。加上 [axiom 层](https://github.com/grapeot/context-infrastructure/tree/main/rules/axioms) 之后,这个系统还能产出超越共识的判断。
|
||||
|
||||
## 概念映射总表
|
||||
|
||||
| Garry Tan 的概念 | 我们的对应实现 | 代码 / 文档 |
|
||||
| --- | --- | --- |
|
||||
| Skill Files | Skills 体系 | [rules/skills/](https://github.com/grapeot/context-infrastructure/tree/main/rules/skills) |
|
||||
| Thin Harness | Agentic Runtime 外包 | [AGENTS.md](https://github.com/grapeot/context-infrastructure/blob/main/AGENTS.md) (在 Claude Code 上运行) |
|
||||
| Resolvers | 三级缓存 On-Demand Loading | [Skills INDEX](https://github.com/grapeot/context-infrastructure/blob/main/rules/skills/INDEX.md) + [Axioms INDEX](https://github.com/grapeot/context-infrastructure/blob/main/rules/axioms/INDEX.md) |
|
||||
| Latent vs. Deterministic | T02 结果确定性 | [axioms/t02](https://github.com/grapeot/context-infrastructure/blob/main/rules/axioms/t02_results_certainty.md) |
|
||||
| Diarization | Layered Distillation → 43 条 Axiom | [rules/axioms/](https://github.com/grapeot/context-infrastructure/tree/main/rules/axioms) |
|
||||
| Self-rewriting skills | 知识飞轮 | [workflow\_knowledge\_flywheel.md](https://github.com/grapeot/context-infrastructure/blob/main/rules/skills/workflow_knowledge_flywheel.md) |
|
||||
| (未涉及) | IC → Manager 心智转变 | [axioms/a03](https://github.com/grapeot/context-infrastructure/blob/main/rules/axioms/a03_ic_to_manager.md) |
|
||||
| (未涉及) | Consensus Ceiling 的突破 | [上下文基础设施全文](https://yage.ai/context-infrastructure.html) |
|
||||
|
||||
完整的开源仓库在 [github.com/grapeot/context-infrastructure](https://github.com/grapeot/context-infrastructure) 。
|
||||
|
||||
---
|
||||
|
||||
## 参考来源
|
||||
|
||||
- Garry Tan, [Thin Harness, Fat Skills](https://x.com/garrytan/status/2042925773300908103), X Article, 2026-04-11
|
||||
- 我们的相关文章(按时间顺序):
|
||||
- [当 AI 变成你的下属:技术人必须跨越的三道管理陷阱](https://yage.ai/ai-management.html), 2025-02
|
||||
- [Beyond DRY: Thoughts on AI-Native Software Engineering](https://yage.ai/ai-software-engineering.html), 2025-11
|
||||
- [从过程确定性到结果确定性](https://yage.ai/result-certainty.html), 2026-01
|
||||
- [OpenClaw Deep Dive](https://yage.ai/openclaw.html), 2026-02
|
||||
- [为什么 AI 只会说正确的废话](https://yage.ai/context-infrastructure.html), 2026-03
|
||||
@@ -0,0 +1,376 @@
|
||||
---
|
||||
title: "Hermes Has a Browser Escape Hatch Most Agents Don’t"
|
||||
source: "https://x.com/NeoAIForecast/status/2047521653954089113"
|
||||
author:
|
||||
- "[[@NeoAIForecast]]"
|
||||
published: 2026-04-24
|
||||
created: 2026-04-24
|
||||
description: "Most AI browser agents break when the page gets weird.A button hides inside an iframe. A native dialog blocks execution. A cookie issue ruin..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
Most AI browser agents break when the page gets weird.
|
||||
|
||||
A button hides inside an iframe. A native dialog blocks execution. A cookie issue ruins the session. A JS-heavy app does not show the state you need.
|
||||
|
||||
Hermes has a technical answer for this: **browser\_cdp.**
|
||||
|
||||
It is not the normal browser tool. It is the escape hatch underneath it.
|
||||
|
||||
Most browser agents are built around high-level actions:
|
||||
|
||||
- navigate to a page
|
||||
- click a button
|
||||
- type into a field
|
||||
- scroll
|
||||
- read the page
|
||||
- take a screenshot
|
||||
|
||||
That works until it doesn’t.
|
||||
|
||||
Modern websites are messy. They have shadow DOMs, iframes, native dialogs, hidden state, client-side routing, weird auth flows, cookie problems, dynamic rendering, and JavaScript errors that never appear in the visible page.
|
||||
|
||||
Hermes Agent handles normal browser work with high-level tools like:
|
||||
|
||||
```plaintext
|
||||
browser_navigate
|
||||
browser_snapshot
|
||||
browser_click
|
||||
browser_type
|
||||
browser_console
|
||||
browser_vision
|
||||
```
|
||||
|
||||
But when those are not enough, Hermes exposes something much lower level:
|
||||
|
||||
```plaintext
|
||||
browser_cdp
|
||||
```
|
||||
|
||||
That stands for:
|
||||
|
||||
**Chrome DevTools Protocol.**
|
||||
|
||||
It lets Hermes send raw CDP commands directly to a connected Chrome instance.
|
||||
|
||||
In plain English:
|
||||
|
||||
Hermes can drop below “AI browser control” and talk to the browser like DevTools does. That is a serious power-user feature.
|
||||
|
||||
## Why high-level browser tools are not enough
|
||||
|
||||
High-level browser tools are great for most agent workflows.
|
||||
|
||||
They give the model a clean accessibility-tree view of the page. Hermes can see interactive elements, assign refs like [@e1](https://x.com/@e1) or [@e2](https://x.com/@e2), click buttons, fill forms, scroll, and inspect page text.
|
||||
|
||||
That is exactly what you want for normal browsing. But the abstraction can hide important details.
|
||||
|
||||
For example:
|
||||
|
||||
- the accessibility tree may not expose the element you need
|
||||
- an iframe may require target-specific inspection
|
||||
- a native JavaScript dialog may block the page
|
||||
- a frontend error may only appear in the console
|
||||
- a site may store critical state in cookies or local storage
|
||||
- a SPA may render data after network calls complete
|
||||
- visual state may differ from text state
|
||||
|
||||
Most agents either fail here or hallucinate around it.
|
||||
|
||||
Hermes gives the agent a lower-level path.
|
||||
|
||||
Takeaway: High-level browser tools are the default. **browser\_cdp** is what you use when the default abstraction leaks.
|
||||
|
||||
## What browser\_cdp actually does
|
||||
|
||||
browser\_cdp is a raw Chrome DevTools Protocol passthrough.
|
||||
|
||||
That means Hermes can call CDP methods such as:
|
||||
|
||||
```plaintext
|
||||
Target.getTargets
|
||||
Runtime.evaluate
|
||||
Page.handleJavaScriptDialog
|
||||
Network.getAllCookies
|
||||
DOM.*
|
||||
Emulation.*
|
||||
Storage.*
|
||||
Browser.*
|
||||
```
|
||||
|
||||
The official Hermes docs describe it as an escape hatch for browser operations not covered by normal browser tools.
|
||||
|
||||
Common uses include:
|
||||
|
||||
- native dialog handling
|
||||
- iframe-scoped evaluation
|
||||
- cookie inspection
|
||||
- network control
|
||||
- direct JavaScript evaluation
|
||||
- browser/tab target inspection
|
||||
- low-level DOM operations
|
||||
- debugging page state
|
||||
|
||||
Example:
|
||||
|
||||
```plaintext
|
||||
browser_cdp(method="Target.getTargets")
|
||||
```
|
||||
|
||||
That lists available browser targets/tabs.
|
||||
|
||||
Then a page-level command can target a specific tab:
|
||||
|
||||
```plaintext
|
||||
browser_cdp(
|
||||
method="Runtime.evaluate",
|
||||
params={
|
||||
"expression": "document.title",
|
||||
"returnByValue": true
|
||||
},
|
||||
target_id="<tabId>"
|
||||
)
|
||||
```
|
||||
|
||||
This is not “click the button.”
|
||||
|
||||
This is “ask Chrome directly what the page is doing.”
|
||||
|
||||
Takeaway: browser\_cdp turns Hermes from a browser user into a browser debugger.
|
||||
|
||||
## The setup is intentionally explicit
|
||||
|
||||
browser\_cdp is not always available.
|
||||
|
||||
Hermes only exposes it when a reachable CDP endpoint exists at session start.
|
||||
|
||||
The clean path is local Chrome via:
|
||||
|
||||
```plaintext
|
||||
/browser connect
|
||||
```
|
||||
|
||||
Inside the Hermes CLI, you can run:
|
||||
|
||||
```plaintext
|
||||
/browser connect
|
||||
/browser status
|
||||
/browser disconnect
|
||||
```
|
||||
|
||||
By default, Hermes connects to:
|
||||
|
||||
```plaintext
|
||||
ws://localhost:9222
|
||||
```
|
||||
|
||||
You can also provide a specific CDP endpoint:
|
||||
|
||||
```plaintext
|
||||
/browser connect ws://host:port
|
||||
```
|
||||
|
||||
If Chrome is not already running with remote debugging, Hermes can attempt to launch it.
|
||||
|
||||
The manual Linux path looks like this:
|
||||
|
||||
```bash
|
||||
google-chrome \
|
||||
--remote-debugging-port=9222 \
|
||||
--user-data-dir=$HOME/.hermes/chrome-debug \
|
||||
--no-first-run \
|
||||
--no-default-browser-check &
|
||||
```
|
||||
|
||||
Then launch Hermes from the terminal and run:
|
||||
|
||||
```plaintext
|
||||
/browser connect
|
||||
```
|
||||
|
||||
Important detail:
|
||||
|
||||
**/browser connect** is an interactive CLI slash command.
|
||||
|
||||
It is not dispatched by Telegram, Discord, WebUI, or other gateway chats. If you type it into a gateway chat, it will be treated like normal text instead of executing the slash command.
|
||||
|
||||
Takeaway: browser\_cdp is a CLI/operator feature. Start Hermes locally when you want raw browser control.
|
||||
|
||||
## The mental model: two browser layers
|
||||
|
||||
Hermes browser automation has two layers.
|
||||
|
||||
**Layer 1: Agent-friendly browser tools**
|
||||
|
||||
Use these for normal workflows:
|
||||
|
||||
```plaintext
|
||||
browser_navigate
|
||||
browser_snapshot
|
||||
browser_click
|
||||
browser_type
|
||||
browser_scroll
|
||||
browser_press
|
||||
browser_console
|
||||
browser_vision
|
||||
```
|
||||
|
||||
This layer is optimized for LLMs.
|
||||
|
||||
Hermes converts the page into a text-based accessibility tree. The agent sees refs like [@e3](https://x.com/@e3), clicks them, types into fields, and verifies results.
|
||||
|
||||
This is the default path.
|
||||
|
||||
**Layer 2: Raw CDP passthrough**
|
||||
|
||||
Use this when the first layer cannot see or control what you need:
|
||||
|
||||
**browser\_cdp**
|
||||
|
||||
This layer is optimized for power users. It exposes the Chrome DevTools Protocol directly.
|
||||
|
||||
The agent can inspect targets, evaluate JavaScript, read cookies, handle dialogs, and interact with browser internals.
|
||||
|
||||
Takeaway: Hermes does not force every browser task through one abstraction. It gives you a clean path and a low-level fallback.
|
||||
|
||||

|
||||
|
||||
## When I would use browser\_cdp
|
||||
|
||||
**Good use cases**
|
||||
|
||||
1\. Native JavaScript dialogs
|
||||
|
||||
If a site opens a blocking alert, confirm, or prompt, the normal click/type loop may get stuck.
|
||||
|
||||
CDP can handle it directly:
|
||||
|
||||
```plaintext
|
||||
Page.handleJavaScriptDialog
|
||||
```
|
||||
|
||||
2\. Debugging frontend state
|
||||
|
||||
If the page looks wrong, ask the browser directly:
|
||||
|
||||
```plaintext
|
||||
Runtime.evaluate
|
||||
```
|
||||
|
||||
Example expression:
|
||||
|
||||
```plaintext
|
||||
document.title
|
||||
```
|
||||
|
||||
Or:
|
||||
|
||||
```plaintext
|
||||
window.location.href
|
||||
```
|
||||
|
||||
Or app-specific state if exposed globally.
|
||||
|
||||
3\. Cookie/session inspection
|
||||
|
||||
For auth issues, CDP can inspect cookies:
|
||||
|
||||
```plaintext
|
||||
Network.getAllCookies
|
||||
```
|
||||
|
||||
That is much more precise than guessing whether a login “worked.”
|
||||
|
||||
4\. Iframe problems
|
||||
|
||||
Some pages hide the useful interaction inside nested frames.
|
||||
|
||||
CDP gives the agent a way to inspect targets and work closer to the browser’s real structure.
|
||||
|
||||
5\. Frontend QA
|
||||
|
||||
For local web-app testing, Hermes can combine:
|
||||
|
||||
```plaintext
|
||||
browser_console
|
||||
browser_snapshot
|
||||
browser_cdp
|
||||
```
|
||||
|
||||
That means it can see the page, check the console, and query browser internals.
|
||||
|
||||
Takeaway: Use browser\_cdp when the browser state matters more than the visible page text.
|
||||
|
||||
## The workflow I’d teach operators
|
||||
|
||||
Here is the practical Hermes browser-debug workflow.
|
||||
|
||||
Step 1: Start Chrome with CDP
|
||||
|
||||
```bash
|
||||
google-chrome \
|
||||
--remote-debugging-port=9222 \
|
||||
--user-data-dir=$HOME/.hermes/chrome-debug \
|
||||
--no-first-run \
|
||||
--no-default-browser-check &
|
||||
```
|
||||
|
||||
Step 2: Open Hermes locally
|
||||
|
||||
```plaintext
|
||||
hermes
|
||||
```
|
||||
|
||||
Step 3: Connect the browser
|
||||
|
||||
```plaintext
|
||||
/browser connect
|
||||
```
|
||||
|
||||
Step 4: Verify the connection
|
||||
|
||||
```plaintext
|
||||
/browser status
|
||||
```
|
||||
|
||||
Step 5: Use normal browser tools first
|
||||
|
||||
Ask Hermes to navigate, inspect, click, type, and read the page normally.
|
||||
|
||||
Example:
|
||||
|
||||
```plaintext
|
||||
Open my local app at http://localhost:3000, inspect the login flow, and check for JS errors.
|
||||
```
|
||||
|
||||
Step 6: Drop to CDP only when needed
|
||||
|
||||
If the normal browser tools cannot reach the right state, ask Hermes to use browser\_cdp.
|
||||
|
||||
Example:
|
||||
|
||||
```plaintext
|
||||
Use browser_cdp to list targets, identify the active tab, and evaluate document.title on that tab.
|
||||
```
|
||||
|
||||
Step 7: Disconnect when done
|
||||
|
||||
```plaintext
|
||||
/browser disconnect
|
||||
```
|
||||
|
||||
Takeaway: Treat CDP as the escalation path, not the first move.
|
||||
|
||||
## Final takeaway
|
||||
|
||||
Most browser agents give you a steering wheel. Hermes also gives you access to the diagnostic port.
|
||||
|
||||
That is the difference.
|
||||
|
||||
For normal tasks, use the clean high-level browser tools. But when the page gets weird, Hermes can drop into Chrome DevTools Protocol and debug the browser directly.
|
||||
|
||||
That is why browser\_cdp is one of the most technical and underrated Hermes features.
|
||||
|
||||
It is not flashy, It is better than flashy, It is the escape hatch you want when real web automation breaks.
|
||||
+115
@@ -0,0 +1,115 @@
|
||||
---
|
||||
title: "How A2A and MCP work together: five integration patterns for building multi-agent systems"
|
||||
source: "https://x.com/GoogleCloudTech/status/2047567704807346675"
|
||||
author:
|
||||
- "[[@GoogleCloudTech]]"
|
||||
published: 2026-04-24
|
||||
created: 2026-04-24
|
||||
description: "No organization will build every agent it needs from scratch. The real value comes from discovering agents built by different teams, in dif..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
No organization will build every agent it needs from scratch. The real value comes from discovering agents built by different teams, in different languages, across different organizations. That's what A2A and MCP enable: A2A for agent-to-agent communication. MCP for agent-to-tool communication.
|
||||
|
||||
**By** [@addyosmani](https://x.com/@addyosmani) **and** [@Saboo\_Shubham\_](https://x.com/@Saboo_Shubham_)
|
||||
|
||||
At **Cloud Next 26**, we shipped the infrastructure that makes this integration practical at enterprise scale. Here are five integration patterns for building multi-agent systems with both protocols.
|
||||
|
||||
## Pattern 1: Agent Card Discovery
|
||||
|
||||
Before your agent can delegate to another agent, it needs to know that agent exists, what it can do, and how to communicate with it.
|
||||
|
||||
A2A solves this with Agent Cards. Every A2A-compatible agent publishes a JSON document at a well-known URL that describes its capabilities, authentication requirements, and rate limits. Think of it as an OpenAPI spec, but designed for agent-to-agent interaction rather than client-server communication.
|
||||
|
||||
In **Agent Development Kit (ADK)**, exposing your agent as an A2A server is a single configuration. It automatically generates the Agent Card from your agent's definition. Consuming a remote agent is equally straightforward through the RemoteA2aAgent component, which handles authentication, data serialization, error handling, and result streaming. From the coordinator's perspective, a remote agent built by another team in another language feels like a local one.
|
||||
|
||||
**Agent Registry** amplifies this. When you register agents in the central registry, other agents across your organization can discover them without knowing specific URLs. The registry becomes the service mesh for your agent ecosystem: a single place to find what capabilities are available, who maintains them, and how to access them.
|
||||
|
||||

|
||||
|
||||
## Pattern 2: Delegated Specialization
|
||||
|
||||
The most common integration pattern is delegation: your agent encounters a task outside its expertise and hands it to a specialist.
|
||||
|
||||
This pattern builds on the [Coordinator-Dispatcher architecture](https://developers.googleblog.com/developers-guide-to-multi-agent-patterns-in-adk/), but extends it across team and framework boundaries. The specialist doesn't need to be built with ADK. It doesn't need to be written in the same language. It doesn't need to be maintained by the same team. It just needs to speak A2A.
|
||||
|
||||
Consider a customer onboarding workflow that spans five teams and four languages. The coordinator (your team, Python) delegates identity verification to the security team's Go agent, credit assessment to the risk team's Java agent, account provisioning to the platform team's Go agent, compliance documentation to the legal team's Python agent, and welcome communication to the marketing team's TypeScript agent.
|
||||
|
||||

|
||||
|
||||
Each specialist is owned by a different team, maintained independently, and deployed on its own schedule. The coordinator doesn't know or care about internal implementations. It only knows their Agent Card capabilities and the A2A protocol.
|
||||
|
||||
When the security team updates their verification agent to support new document types, no changes are needed in the coordinator. When the risk team improves their credit models, the coordinator automatically gets better assessments. Each team iterates independently, and the overall system improves. This is the same principle that made microservices successful: independent deployment, independent scaling, independent evolution. A2A provides the service contract that makes it work for agents.
|
||||
|
||||
## Pattern 3: Tool Bridge (Model Context Protocol)
|
||||
|
||||
While A2A connects agents to agents, MCP connects agents to tools and data. The Tool Bridge pattern uses MCP to give your agents secure access to data sources, APIs, and enterprise systems without building custom connectors for each one.
|
||||
|
||||
Without MCP, every data connection requires its own custom integration code. Your agent needs a Python connector for one REST API, a different connector for another database, yet another for a legacy system. Three data sources means three connectors to build, test, and maintain. MCP eliminates this by providing a single protocol that any tool can implement.
|
||||
|
||||
The [ADK integrations ecosystem](https://developers.googleblog.com/supercharge-your-ai-agents-adk-integrations-ecosystem/) provides more than 60 ready-to-use tools and integrations, such as GitHub, Notion, Hugging Face, AgentOps, and Stripe. These allow your agent to connect instantly through simple configuration, bypassing the need for lengthy custom development.
|
||||
|
||||
For database connectivity specifically, [MCP Toolbox for Databases](https://adk.dev/integrations/mcp-toolbox-for-databases/) connects over 30 different data sources to your agents through a single MCP interface. And Apigee API Hub takes this further: if you have existing REST APIs documented in Apigee, you can turn them into agent-accessible tools automatically. Your agents access data through the same governance layer that manages your existing API traffic. Rate limiting, authentication, logging, and access control are handled by infrastructure you already manage.
|
||||
|
||||

|
||||
|
||||
ADK supports MCP natively. When you add an MCP tool to your agent, the agent discovers the tool's capabilities, invokes it with structured parameters, and receives structured responses. From the agent's perspective, an MCP tool through Stripe looks the same as an MCP tool through BigQuery. The protocol is the interface. The backend is interchangeable.
|
||||
|
||||
## Pattern 4: Cross-Organization Federation
|
||||
|
||||
The most ambitious pattern involves agents from different organizations collaborating on shared tasks. This is where A2A's open protocol design becomes essential, because you can't assume the other organization uses the same framework, language, or cloud provider.
|
||||
|
||||
Agent Gallery in Gemini Enterprise makes this practical. Over 100 validated partner agents from Adobe, ServiceNow, Workday, Salesforce, and others are available directly within the platform. Every partner agent has been validated by Google Cloud for security and interoperability.
|
||||
|
||||
The critical property is that each organization maintains its own governance. Your Agent Gateway policies control what data your agents can share with the partner agent, what actions they can take based on the partner's responses, and what information they can request. The partner agent operates under its own security model, validated by Google Cloud's integration requirements.
|
||||
|
||||
Consider a multi-agent payment workflow where your agent needs to coordinate with external merchant agents and financial service agents. Each party maintains its own governance while collaborating on shared transactions through A2A. Your agent doesn't need to understand how the merchant's system works internally. It communicates through the A2A protocol, and each side enforces its own security boundaries independently.
|
||||
|
||||

|
||||
|
||||
The same principle applies to any cross-organization integration. Your agent doesn't need to understand Salesforce's data model or ServiceNow's internal architecture. It delegates to the partner agent in Agent Gallery, which is maintained by the partner's team, validated by Google Cloud, and governed by your Agent Gateway policies. When the partner updates their platform, their agent is updated. Your system benefits without any changes on your end.
|
||||
|
||||
## Pattern 5: Ambient Event Mesh
|
||||
|
||||
The final pattern combines A2A with event-driven architecture to create a mesh of ambient agents that react to events continuously in the background, without waiting for user requests.
|
||||
|
||||
Batch and Event-Driven Agents in Gemini Enterprise Agent Platform connect directly to BigQuery tables and Pub/Sub streams. When you combine this with A2A, you create a network of agents that listen for events, process them, and delegate to specialist agents as needed - all running continuously in the background.
|
||||
|
||||
Each agent in the mesh runs independently. When an event arrives, the receiving agent processes it and decides whether to handle it locally, delegate to a specialist via A2A, or escalate to a human via Mission Control. The mesh is self-organizing - adding a new specialist agent (say, a fraud detection specialist) requires only registering it in Agent Registry and updating the routing logic in the relevant ambient agents.
|
||||
|
||||

|
||||
|
||||
This pattern is particularly powerful for organizations with high event volumes. A content platform processing millions of uploads per day, a financial institution processing millions of transactions, an e-commerce platform processing millions of customer interactions - all can use ambient agent meshes to handle the long tail of events that require intelligent processing.
|
||||
|
||||
The governance story is critical here. Every agent in the mesh has its own identity via **Agent Identity**. Every tool access is governed by **Agent Gateway**. Every interaction is traced through **Agent Observability**. The mesh is not a black box - it is a fully observable, governed network of specialized agents.
|
||||
|
||||
## Choosing the Right Pattern
|
||||
|
||||
When building multi-agent systems, choose your integration pattern based on the relationship between agents:
|
||||
|
||||

|
||||
|
||||
**Get started today**
|
||||
|
||||
The interoperability stack is available now:
|
||||
|
||||
- A2A protocol: Supported in ADK across Python, TypeScript, Go, and Java
|
||||
- MCP: Native support in ADK, managed support for GCP databases
|
||||
- Agent Gallery: 100+ validated partner agents in Gemini Enterprise
|
||||
- Native Ecosystem Integrations: Plug-and-play connectors for enterprise systems
|
||||
|
||||
The A2A + MCP codelab walks through building a multi-agent system with cross-language collaboration: [codelabs.developers.google.com/instavibe-adk-multi-agents](https://codelabs.developers.google.com/instavibe-adk-multi-agents)
|
||||
|
||||
ADK samples including multi-agent patterns: [github.com/google/adk-samples](http://github.com/google/adk-samples)
|
||||
|
||||
The companies building isolated agents will be refactoring in twelve months. The companies building interoperable agent ecosystems will be compounding their advantage every day.
|
||||
|
||||
Start building: [adk.dev](https://adk.dev/) | [https://cloud.google.com/products/gemini-enterprise-agent-platform](https://cloud.google.com/products/gemini-enterprise-agent-platform)
|
||||
|
||||
**Build Interoperable Agents: Google for Startups AI Agents Challenge**
|
||||
|
||||
Isolated agents are a dead end. Join our **6-week global challenge** for startups to build, optimize or refactor AI Agents on the Gemini Enterprise Agent Platform. You'll get **$500 in cloud credits**, full platform access and a shot at the **$90,000 prize pool**.
|
||||
|
||||
[Sign up today to start building](https://devpost.team/hackathon_guest_invites/4fb181b4-2722-415d-a442-285a57dcaba5?utm_source=twitter&utm_medium=social&utm_campaign=google-for-startups-ai-agents-challenge&utm_content=twitter-post)!
|
||||
@@ -0,0 +1,131 @@
|
||||
---
|
||||
title: "How I Build Apps with the Codex App and GPT-5.5"
|
||||
source: "https://x.com/PaulSolt/status/2048226299290828936"
|
||||
author:
|
||||
- "[[@PaulSolt]]"
|
||||
published: 2026-04-26
|
||||
created: 2026-04-26
|
||||
description: "My workflow with GPT-5.5 is completely different from my workflow with GPT-5.4 — and this literally changed this week. The GPT-5.5 model is ..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
My workflow with GPT-5.5 is completely different from my workflow with GPT-5.4 — and this literally changed this week. The GPT-5.5 model is smarter, the Codex app is faster, and it finally feels like I have the perfect coding partner. Not just for code — for everything around the app. I'm shipping app updates and doing app research in less time than before.
|
||||
|
||||
## GPT 5.5 + Codex app
|
||||
|
||||
**Medium reasoning is fast**. Surprisingly fast. It feels like I get working code in seconds for small tasks, which means faster iteration loops and more progress.
|
||||
|
||||
The [Codex app](https://developers.openai.com/codex/app) is my go to right now. Codex CLI is still great when I want speed in switching conversations, but the app gives me image previews, diff tools, and a better workspace for bigger problems. Performance keeps getting better week over week.
|
||||
|
||||
I just used Codex to revive my [9-year-old Super Easy Timer app](https://apps.apple.com/us/app/super-easy-timer/id1353137878?mt=12), which is pretty much dead. It went from 0.5% conversion rate to now over 7.1% conversion rate.
|
||||
|
||||

|
||||
|
||||
Super Easy Timer (now free): [https://apps.apple.com/us/app/super-easy-timer/id1353137878?mt=12](https://apps.apple.com/us/app/super-easy-timer/id1353137878?mt=12)
|
||||
|
||||
## Just Talk to It
|
||||
|
||||
The model is smart enough now that you just describe what you want.
|
||||
|
||||
No prompt ceremony. No plan files. Tell GPT-5.5 in Codex what you want, then let it run.
|
||||
|
||||
With 5.4, if I asked for too much at once it would go off the rails. With 5.5 I'm just driving it in real time. I describe and steer it interactively with what I want. Then I test it and give it feedback for the next loop.
|
||||
|
||||
A fast interaction loop lets me drive the code quickly. GPT-5.5 is smart and fills in a lot of gaps without me asking. Try talking to it.
|
||||
|
||||
I use [Wispr Flow](https://wisprflow.ai/) for voice dictation — though Codex's new global voice dictation is almost a replacement.
|
||||
|
||||
## Agents Can Create Xcode Projects
|
||||
|
||||
Agents need to know if the code compiles and the tests pass. If you're struggling with having agents work on your apps, you need to try this skill.
|
||||
|
||||

|
||||
|
||||
AppCreator creates new Xcode projects and allows agents to see build failures.
|
||||
|
||||
I created [App Creator skill](https://super-easy-apps.kit.com/app-creator) to solve my own problems:
|
||||
|
||||
1. It's hard to spin up new iOS/macOS apps.
|
||||
2. Agents report success when things are broken.
|
||||
|
||||
Your agent should always hand back working code, which is what the App Creator skill solves. The [App Creator skill](https://super-easy-apps.kit.com/app-creator) lets you create new Xcode projects without opening Xcode. The second part is that it gives your agents the tools to make a repeatable build/test loop. It can't lie about the build being green when it isn't.
|
||||
|
||||
> Agents should always be able to verify their work before handing it back to you.
|
||||
|
||||
**Note**: OpenAI shipped the **Build iOS Apps** and **Build macOS Apps** Plugins. Those work great on top of the foundation from my App Creator skill.
|
||||
|
||||
## Real Documentation Reduces Hallucinations
|
||||
|
||||
Agents have a fuzzy understanding of code, so for critical code that works with Core ML or AVFoundation — You'll want to use the actual APIs.
|
||||
|
||||

|
||||
|
||||
DocSetQuery for fast, local Apple Documentation
|
||||
|
||||
[DocSetQuery](https://github.com/PaulSolt/DocSetQuery) pulls the local Apple DocSet into clean Markdown and lets the agent search it. Fewer hallucinated APIs and errors.
|
||||
|
||||
## Research the Market Together
|
||||
|
||||
A real partner doesn't just help you write the app. It helps you figure out which app to build.
|
||||
|
||||
Shipping an app is a multi-discipline skill.
|
||||
|
||||
It requires:
|
||||
|
||||
- Coding
|
||||
- Marketing
|
||||
- Positioning
|
||||
- Copywriting
|
||||
- Design
|
||||
|
||||
As a one-person team, it can be hard to do all of these well. So I have been leaning into Codex to help with more and more App Store research.
|
||||
|
||||
I created 3 new skills for helping me see what the competition is doing, and to help me position my ideas.
|
||||
|
||||
The three tools are:
|
||||
|
||||
**1\. App Store Icon Grid**
|
||||
|
||||
See what icons look like for any search query. I wanted this ability after using [Astro](https://tryastro.app/) to look up keywords. I love to place my concept app icons on the grid to see how they compare.
|
||||
|
||||

|
||||
|
||||
Top 16 App Store icons for "photo collages" for competitive analysis.
|
||||
|
||||
**2\. App Store Screenshots**
|
||||
|
||||
See a grid of the top screenshots. This can help you see what messaging is resonating with users. The top apps use the copy they use because it works.
|
||||
|
||||
When you think about your App Store page, consider that on search results users will see 3 screenshots on iOS and 1 screenshot on macOS.
|
||||
|
||||

|
||||
|
||||
Top 6 "Photo collage" apps on iOS.
|
||||
|
||||
**3\. App Store Reviews**
|
||||
|
||||
Now you can do more user persona research, figure out features customers love or hate, and position your app.
|
||||
|
||||
If you want to build apps, having tools like these three will enable you to build iOS and macOS apps with ease.
|
||||
|
||||

|
||||
|
||||
App Store reviews from Pic Collage.
|
||||
|
||||
Use these tools in Codex to help you research the App Store and find a competitive niche. Take an existing idea and put your own spin on it. Make sure you don't blindly copy an app, or Apple will remove your app.
|
||||
|
||||
## Download These Skills for Your Next App
|
||||
|
||||
Grab all of the tools that I use to make apps:
|
||||
|
||||
- [Download the App Store Research CLI tools](https://super-easy-apps.kit.com/app-store-tools)
|
||||
- [Download AppCreator for iOS/macOS App Development](https://super-easy-apps.kit.com/app-creator)
|
||||
- Get [fast local documentation](https://github.com/PaulSolt/DocSetQuery) for agents to reference
|
||||
|
||||
**What's your current Codex setup?** Reply below.
|
||||
|
||||
Building iOS/macOS apps with AI tools? Follow [@PaulSolt](https://x.com/@PaulSolt) for the workflows I'm actually using.
|
||||
|
||||
**P.S.** Need help with App Store Screenshots? Read my other article: [The Screenshot Mistake That's Costing You Downloads Every Day](https://x.com/PaulSolt/status/2037591726227902555)
|
||||
@@ -0,0 +1,245 @@
|
||||
---
|
||||
title: "How LLM Inference Works"
|
||||
source: "https://x.com/akshay_pachaar/status/2050941458614751327"
|
||||
author:
|
||||
- "[[@akshay_pachaar]]"
|
||||
published: 2026-05-03
|
||||
created: 2026-05-04
|
||||
description: "A first-principles tour of what happens between your prompt and the streamed response: tokenization, embeddings, attention, the prefill/deco..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
A first-principles tour of what happens between your prompt and the streamed response: tokenization, embeddings, attention, the prefill/decode split, KV caching, and quantization.
|
||||
|
||||
You type a prompt. A few hundred milliseconds later, words start streaming back at you one at a time. Feels simple. It isn't.
|
||||
|
||||
What happens between your keystroke and that first token is one of the most carefully engineered pipelines in modern computing. And the strangest part? The model does two completely different jobs to answer you, with two different bottlenecks, on the same GPU, in the same request.
|
||||
|
||||
Once you see it, you'll never look at a generate() call the same way again.
|
||||
|
||||
# The mental model
|
||||
|
||||
An LLM is a neural network that predicts the next token. Just one token. Then it takes that token, sticks it onto the end of your prompt, and predicts the next one. Then repeats it.
|
||||
|
||||
That's it. That's the whole loop.
|
||||
|
||||
The interesting question is: how does it predict that next token, and why does the **second token** come out **much faster** than the first?
|
||||
|
||||
# Step 1: Your text becomes numbers
|
||||
|
||||
Neural networks don't read English. They read vectors. So the first thing that happens to your prompt is **tokenization**, which chops your text into pieces and assigns each piece an integer ID.
|
||||
|
||||
Most modern LLMs use a scheme called Byte Pair Encoding. The idea: start with raw characters, then merge the most common adjacent pairs over and over until you have a vocabulary of ~50,000 chunks. Common words like the get one token. Rare words like unhappiness get split into pieces like un + happi + ness.
|
||||
|
||||
```python
|
||||
prompt = "How does inference work?"
|
||||
ids = tokenizer.encode(prompt)
|
||||
# ids -> [2437, 1374, 32278, 670, 30]
|
||||
```
|
||||
|
||||
This step matters more than people realize. Languages that weren't well-represented in the tokenizer's training data get chopped into more pieces, which means more tokens, which means higher cost and slower responses for the same sentence.
|
||||
|
||||
# Step 2: Each token becomes a vector
|
||||
|
||||
Each integer ID gets looked up in a giant matrix called the embedding table. If your model has a vocabulary of 50K and a hidden dimension of 4,096, the table has shape \[50000, 4096\]. Pick a row, get a vector.
|
||||
|
||||
```python
|
||||
# embedding_table has shape [vocab_size, hidden_dim]
|
||||
vectors = embedding_table[ids] # shape: [num_tokens, 4096]
|
||||
```
|
||||
|
||||
These vectors aren't random. During training, the model nudged them around so that semantically similar tokens ended up near each other in this 4,096-dimensional space. king and queen are neighbours. python and snake are neighbours along one axis, python and javascript along another.
|
||||
|
||||
The embedding layer is also where **position information** gets injected, because attention itself doesn't know which token came first. Modern models use schemes like RoPE that rotate the vectors based on their position in the sequence.
|
||||
|
||||

|
||||
|
||||
# Step 3: Layers of attention
|
||||
|
||||
Now the real work begins. Your sequence of vectors gets fed through a stack of **transformer layers**, often 32 or more, one after the other. Each layer does roughly the same thing:
|
||||
|
||||
1. Mix information across tokens using **self-attention**.
|
||||
2. Mix information within each token using a **feed-forward network**.
|
||||
|
||||
Self-attention is the part worth understanding deeply. For every token, the layer produces three new vectors by multiplying with three learned weight matrices:
|
||||
|
||||
```python
|
||||
# x is the input to this layer, shape [num_tokens, hidden_dim]
|
||||
Q = x @ Wq # queries
|
||||
K = x @ Wk # keys
|
||||
V = x @ Wv # values
|
||||
```
|
||||
|
||||

|
||||
|
||||
Now you have three views of every token. The trick: each token uses its **query** to look at every other token's **key**, and the strength of the match decides how much of that other token's **value** to mix in.
|
||||
|
||||
```python
|
||||
# scores: how much each token attends to every other token
|
||||
raw = Q @ K.T
|
||||
scaled = raw / sqrt(hidden_dim) # keeps softmax stable
|
||||
weights = softmax(scaled) # one row per token, sums to 1
|
||||
attention_output = weights @ V
|
||||
```
|
||||
|
||||
Here's a visual representaion of the above process:
|
||||
|
||||

|
||||
|
||||
That's the magic. A token decides what context it needs by looking around and pulling in whatever it finds useful. Stack 32 layers of this and you get a model that can track references across thousands of tokens.
|
||||
|
||||
After attention, each token's vector goes through a small two-layer feed-forward network that does most of the model's actual "knowing." Attention moves information around. The feed-forward network processes it.
|
||||
|
||||
# Step 4: Predict the next token
|
||||
|
||||
After the final layer, the model takes the vector for the last position, projects it back to vocabulary size, and applies softmax to get a probability over every possible next token. Sample from that distribution, and you have your first generated token.
|
||||
|
||||
Now we hit the interesting part.
|
||||
|
||||
# The two phases nobody tells you about
|
||||
|
||||
Generating a 200-token response isn't one task. It's two tasks that look nothing alike under the hood.
|
||||
|
||||

|
||||
|
||||
## Phase 1: Prefill
|
||||
|
||||
When you submit a prompt, the model has to process all of your input tokens before it can generate anything. The good news: it can do this in parallel. Every token's Q, K, and V get computed at the same time. Attention runs as a big matrix-by-matrix multiplication.
|
||||
|
||||
GPUs love this. Matrix-matrix multiplication is what they were built for. The bottleneck here is raw arithmetic throughput: the GPU is pinned at high utilization, doing math as fast as the silicon allows.
|
||||
|
||||
The metric for this phase is **Time to First Token (TTFT)**. It's the idle time before the first word shows up on your screen.
|
||||
|
||||
```python
|
||||
# Prefill: process the whole prompt in one shot
|
||||
hidden = embed(prompt_tokens) + positions
|
||||
for layer in model.layers:
|
||||
Q, K, V = project(hidden) # for ALL tokens at once
|
||||
hidden = attention(Q, K, V) + hidden
|
||||
hidden = feedforward(hidden) + hidden
|
||||
cache_kv(layer, K, V) # save for later
|
||||
first_token = sample(project_to_vocab(hidden[-1]))
|
||||
```
|
||||
|
||||
## Phase 2: Decode
|
||||
|
||||
Once the first token is out, the model switches modes. To generate token 51, it only needs to compute Q, K, and V for that one token. The previous 50 tokens? Their K and V vectors haven't changed. Recomputing them would be wasted work.
|
||||
|
||||

|
||||
|
||||
So the model loops, one token at a time:
|
||||
|
||||
```python
|
||||
# Decode: one token per iteration
|
||||
token = first_token
|
||||
steps = 0
|
||||
while token != STOP and steps < MAX_STEPS:
|
||||
x = embed(token) + position(steps)
|
||||
for layer in model.layers:
|
||||
q, k, v = project(x)
|
||||
K_all, V_all = caches[layer].append(k, v) # cached history + new
|
||||
x = layer.forward(q, K_all, V_all, x) # attention + FFN, residuals
|
||||
token = sample(project_to_vocab(x))
|
||||
steps += 1
|
||||
yield token
|
||||
```
|
||||
|
||||
Notice what changed. Instead of multiplying a matrix of queries against a matrix of keys, you're multiplying a single query vector against a matrix of keys. The arithmetic is tiny.
|
||||
|
||||
But the GPU still has to load every weight matrix from memory and every cached K and V from memory to do that tiny computation. Suddenly the bottleneck flips. The chip has plenty of compute headroom and is just sitting there waiting for memory to deliver the next chunk of data.
|
||||
|
||||
This is why **decode is memory-bound, prefill is compute-bound.** Same model, same hardware, totally different performance characteristics.
|
||||
|
||||
The metric here is **Inter-Token Latency (ITL)**: the gap between consecutive tokens streaming out. Low ITL is what makes a model feel fast.
|
||||
|
||||
# The KV cache: the optimization that makes this whole thing viable
|
||||
|
||||
That append\_to\_cache line above is doing all the heavy lifting. Without it, generating a 1,000-token response would mean recomputing attention for the entire growing sequence at every step. Quadratic complexity and it's painfully slow.
|
||||
|
||||
With it, you save the K and V matrices once and reuse them forever. Here's the rough shape of what's happening:
|
||||
|
||||
```python
|
||||
# One KVCache per transformer layer
|
||||
class KVCache:
|
||||
def __init__(self):
|
||||
self.K = None # all keys seen so far, shape [tokens, dim]
|
||||
self.V = None # all values seen so far, shape [tokens, dim]
|
||||
|
||||
def append(self, k_new, v_new):
|
||||
if self.K is None:
|
||||
self.K, self.V = k_new, v_new # first token
|
||||
else:
|
||||
self.K = concat([self.K, k_new], axis=token_axis)
|
||||
self.V = concat([self.V, v_new], axis=token_axis)
|
||||
return self.K, self.V # full history so far
|
||||
```
|
||||
|
||||
The speedup is huge. Think 5x or more for long generations. But there's a price: the cache lives in GPU memory, and it grows with every token. Every layer keeps its own K and V tensors. For a 13B model, you're looking at roughly 1 MB per token. A 4K-token context burns through 4 GB of VRAM just on the cache.
|
||||
|
||||
This is why long contexts feel slow and expensive. It's not the model running out of brainpower. It's the cache running out of room.
|
||||
|
||||
The fixes are creative: quantize the cache to INT8 or INT4, drop tokens outside a sliding window, share K and V across attention heads (grouped-query attention), or page the cache like an operating system pages memory (PagedAttention, the trick behind vLLM).
|
||||
|
||||
# Frontier research: shrinking the cache itself
|
||||
|
||||
Quantization and paging treat the cache as a fixed cost. DeepSeek's V4 series, previewed in late 2025, takes a more aggressive line: redesign attention so the cache is small from the start.
|
||||
|
||||
Their hybrid scheme combines two compressed attention variants, one sparse, one dense, both operating on a heavily compressed KV stream. At a one-million-token context, V4-Pro reports around 10% of the cache size and 27% of the per-token compute of its predecessor.
|
||||
|
||||
The takeaway isn't the specific architecture. It's that the KV cache has become the bottleneck the field is now optimizing the model around. When attention itself is being redesigned to minimize the cache, you know the constraint has shifted.
|
||||
|
||||
Worth a read if you want to see where long-context inference is heading. The full tech report is here: [DeepSeek-V4 paper](https://huggingface.co/deepseek-ai/DeepSeek-V4-Pro/blob/main/DeepSeek_V4.pdf)
|
||||
|
||||

|
||||
|
||||
# Quantization: trading bits for speed
|
||||
|
||||
Training needs precision. Inference doesn't.
|
||||
|
||||
Most production deployments run in FP16 or BF16 instead of FP32, which halves memory and roughly doubles throughput on Tensor Cores. Aggressive setups go further, quantizing weights to INT8 or even INT4.
|
||||
|
||||
The math is straightforward. A 7B-parameter model takes:
|
||||
|
||||
- 28 GB at FP32
|
||||
- 14 GB at FP16
|
||||
- 7 GB at INT8
|
||||
- 3.5 GB at INT4
|
||||
|
||||
That last number is why you can run a 7B model on a laptop GPU. Methods like GPTQ and AWQ pick per-channel scaling factors so the lossy compression hurts quality as little as possible. Done well, INT4 can land within a percentage point of the original on most benchmarks.
|
||||
|
||||
# Putting it all together
|
||||
|
||||
Here's the full journey of one prompt, end to end:
|
||||
|
||||
1. **Tokenize.** Text becomes integer IDs.
|
||||
2. **Embed.** IDs become vectors. Position information gets folded in.
|
||||
3. **Prefill.** Every layer runs over every input token in parallel. Compute-bound. The KV cache gets populated. First output token pops out.
|
||||
4. **Decode loop.** For each new token: project Q for the new token, attend over the cached K and V, run the feed-forward network, sample. Append the new K and V to the cache. Memory-bound.
|
||||
5. **Detokenize.** Token IDs get mapped back to characters and streamed to your screen.
|
||||
|
||||
Modern serving frameworks like [vLLM](https://github.com/vllm-project/vllm), [TensorRT-LLM](https://github.com/NVIDIA/TensorRT-LLM), and Text Generation Inference wrap this loop with continuous batching (tokens from multiple users get interleaved on the same GPU step), speculative decoding (a small model drafts tokens, the big model verifies), and clever memory management. That's how a single GPU serves dozens of concurrent users.
|
||||
|
||||

|
||||
|
||||
# What this should change about how you think
|
||||
|
||||
A few practical takeaways once the picture clicks:
|
||||
|
||||
- **Long prompts are expensive in TTFT, long outputs are expensive in ITL.** They stress different things. Optimize for the one your users actually feel.
|
||||
- **Context length isn't free.** Doubling it doesn't just double compute; it bloats the KV cache and starves your batch size.
|
||||
- **Quantization is the highest-leverage knob you have.** Going FP16 to INT8 often cuts latency in half with negligible quality loss.
|
||||
- **GPU utilization can be misleading.** A model that pegs the GPU during prefill might be at 30% during decode. The fix isn't more compute; it's faster memory or a smaller cache.
|
||||
|
||||
The transformer architecture gets all the attention, but inference performance lives or dies on the boring stuff. Memory layout. Cache management. Bit widths. The art is squeezing the most from the hardware you've got.
|
||||
|
||||
Now when someone tells you their model is slow, you'll know which question to ask first: is it slow to start, or slow to stream?
|
||||
|
||||
If you liked this article, let me know in the comments.
|
||||
|
||||
It gives me a signal that I should create more content like this.
|
||||
|
||||
Thanks for reading!
|
||||
|
||||
Cheers! :)
|
||||
+205
@@ -0,0 +1,205 @@
|
||||
---
|
||||
title: "How to Build AI Workflows That Run Your Entire Business on Autopilot (Full Course)"
|
||||
source: "https://x.com/eng_khairallah1/status/2047970333865746734"
|
||||
author:
|
||||
- "[[@eng_khairallah1]]"
|
||||
published: 2026-04-25
|
||||
created: 2026-04-26
|
||||
description: "Every business owner hits the same wall.Save this :)You are doing everything. Sales. Support. Marketing. Operations. Admin. You know you sho..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
Every business owner hits the same wall.
|
||||
|
||||
Save this :)
|
||||
|
||||
You are doing everything. Sales. Support. Marketing. Operations. Admin. You know you should be focusing on strategy and growth but you are stuck in execution mode because there is nobody else to do the work.
|
||||
|
||||
Hiring is expensive. Training takes months. Managing people adds complexity.
|
||||
|
||||
**But what if the work just happened?**
|
||||
|
||||
What if your leads were qualified before you saw them. Your support tickets were answered before you woke up. Your weekly reports compiled themselves. Your invoices processed automatically. Your content calendar populated itself from your ideas. Your meeting notes organized into action items without you touching them.
|
||||
|
||||
This is not a hypothetical. This is what AI workflows do when they are built correctly.
|
||||
|
||||
Not one automation. Not a single chatbot. A system of interconnected workflows that handle the operational layer of your business while you focus on the decisions that actually move the needle.
|
||||
|
||||
**This course teaches you how to build that system.** Step by step, from identifying what to automate to deploying workflows that run without you.
|
||||
|
||||
# Why Workflows, Not Tools
|
||||
|
||||
Most people approach AI automation backwards. They start with a tool. "I should use Claude for something." Then they wander around looking for a use case that fits the tool.
|
||||
|
||||
This is like buying a drill and then walking around your house looking for things to drill. Backwards.
|
||||
|
||||
**Start with the workflow.** A workflow is a sequence of steps that transforms an input into an output. Every business runs on workflows, even if nobody has written them down.
|
||||
|
||||
A sales workflow: Lead comes in → research the company → score against criteria → draft outreach → send email → track response → follow up.
|
||||
|
||||
A support workflow: Ticket arrives → classify the issue → find the solution → draft response → send to customer → update knowledge base if new issue.
|
||||
|
||||
A content workflow: Idea captured → research the topic → write first draft → edit → format for each platform → schedule posts.
|
||||
|
||||
Each of these workflows has steps that require human judgment and steps that do not. Your job is to identify which steps can be automated and connect them into a system that runs autonomously.
|
||||
|
||||
**A tool does one thing. A workflow does everything between input and output.** The value is in the workflow, not the individual tool.
|
||||
|
||||
# Phase 1: Map Your Workflows (Week 1)
|
||||
|
||||
You cannot automate what you do not understand. The first step is making every workflow in your business explicit.
|
||||
|
||||
**The process:**
|
||||
|
||||
For each area of your business - sales, marketing, support, operations, finance - write down every recurring workflow.
|
||||
|
||||
For each workflow, document every step in order. Include: what triggers the workflow, what happens at each step, what tools or data each step requires, what the output looks like, and how long each step takes.
|
||||
|
||||
**Mark each step with one of three labels:**
|
||||
|
||||
🟢 **Automate:** This step follows a predictable pattern and does not require human judgment. AI can handle it.
|
||||
|
||||
🟡 **Assist:** This step benefits from AI doing the heavy lifting but needs human review before proceeding. AI drafts, human approves.
|
||||
|
||||
🔴 **Human:** This step requires genuine creativity, relationship awareness, ethical judgment, or emotional intelligence that AI cannot replicate. Keep it human.
|
||||
|
||||
Most people discover that 60 to 70 percent of their workflow steps are green (fully automatable) or yellow (AI-assisted). The remaining 30 to 40 percent genuinely require human involvement.
|
||||
|
||||
**The goal is not to automate everything. The goal is to automate everything that does not need you.**
|
||||
|
||||
# Phase 2: Design the Automation Architecture (Week 2)
|
||||
|
||||
Now design how each workflow will work as an automated system.
|
||||
|
||||
**Every automated workflow has five components:**
|
||||
|
||||
**Trigger:** What starts the workflow? A new email arriving, a form submission, a scheduled time, a file appearing in a folder, a webhook from another system.
|
||||
|
||||
**Input Processing:** How does the raw input get prepared for AI processing? Extracting text from PDFs, parsing email contents, structuring form data, fetching additional context from your CRM or database.
|
||||
|
||||
**AI Processing:** What does Claude do with the processed input? Classify it, analyze it, generate a response, extract data, make a decision, produce a document. This is where your system prompt and tool definitions live.
|
||||
|
||||
**Output Routing:** Where does the AI output go? Into your CRM, into an email, into a folder, into a spreadsheet, into a Slack channel. The output needs to arrive at the right destination in the right format.
|
||||
|
||||
**Quality Check:** How do you verify the output is correct? Automated validation rules for structured data. Human review queues for customer-facing content. Confidence thresholds below which the workflow escalates to a human.
|
||||
|
||||
**Design each workflow on paper before building it.** Draw boxes for each component. Draw arrows for data flow. Identify where errors could occur and what happens when they do.
|
||||
|
||||
# Phase 3: Build the Core Workflows (Weeks 3 to 6)
|
||||
|
||||
Build your first three workflows. Start with the ones that save the most time and have the clearest input-output patterns.
|
||||
|
||||
**I recommend this order for most businesses:**
|
||||
|
||||
# Workflow 1: The Email Operations Center
|
||||
|
||||
This is usually the highest-impact first workflow because email touches every part of the business.
|
||||
|
||||
**Trigger:** New email arrives.
|
||||
|
||||
**Processing:** Claude reads the email and classifies it:
|
||||
|
||||
- Sales inquiry → extract company name, stated need, and urgency. Score against ICP. Draft holding response. Add to CRM with enrichment data.
|
||||
- Support request → classify by category and severity. Search knowledge base for solution. Draft response. If no solution found, escalate to human with full context.
|
||||
- Invoice or billing → extract vendor, amount, date, payment terms. Add to accounts payable tracker. Flag if amount exceeds approval threshold.
|
||||
- Internal communication → summarize key points. Extract action items. Route to relevant team member.
|
||||
- Newsletter or promotional → archive. No action needed.
|
||||
|
||||
**Output:** Each email type routes to its specific destination. Draft responses queue for human review. Financial data enters the accounting system. The daily email summary saves to a briefing document.
|
||||
|
||||
**Quality check:** All customer-facing responses queue for human approval before sending. Financial extractions are flagged for manual verification above a dollar threshold.
|
||||
|
||||
# Workflow 2: The Report Factory
|
||||
|
||||
Every report your business produces regularly - weekly status updates, monthly analytics, quarterly reviews - can be automated.
|
||||
|
||||
**Trigger:** Scheduled. Weekly on Fridays at 3 PM, monthly on the 1st, quarterly at end of quarter.
|
||||
|
||||
**Processing:** The workflow connects to your data sources - CRM, analytics platform, financial system, project management tool - pulls the relevant data, and passes it to Claude with your report template.
|
||||
|
||||
Claude processes the data: calculates key metrics, compares against targets and previous periods, identifies trends, flags anomalies, and writes the narrative sections.
|
||||
|
||||
**Output:** A formatted report saved to the shared drive and distributed to the stakeholder list via email.
|
||||
|
||||
**Quality check:** Automated validation checks that all numbers are internally consistent (do percentages add up? are totals correct?). Anomaly flags for any metric that deviates more than 20 percent from the previous period. Human review for the executive summary before distribution.
|
||||
|
||||
# Workflow 3: The Content Engine
|
||||
|
||||
For businesses that produce regular content - blog posts, social media, newsletters - the content pipeline can be largely automated while preserving your unique voice and perspective.
|
||||
|
||||
**Trigger:** Weekly on Monday morning.
|
||||
|
||||
**Processing:**
|
||||
|
||||
- Step 1: Claude scans trending topics in your industry, reviews your content calendar, and generates 10 content ideas with hooks and angles.
|
||||
- Step 2: You pick 3 ideas (2 minutes of your time).
|
||||
- Step 3: Claude researches each topic, generates a detailed outline, writes the first draft using your voice guide, and runs a self-correction pass.
|
||||
- Step 4: Claude repurposes each article into social posts, thread, newsletter section, and short-form video script.
|
||||
|
||||
**Output:** Three drafted articles, each with multi-platform repurposed versions, saved to your content folder ready for human review and scheduling.
|
||||
|
||||
**Quality check:** You review each piece for voice accuracy, factual correctness, and strategic alignment. This review takes 15 to 20 minutes for three articles - compared to 4 to 6 hours to create the same content from scratch.
|
||||
|
||||
# Phase 4: Connect the Workflows (Weeks 7 to 8)
|
||||
|
||||
Individual workflows are powerful. Connected workflows are transformational.
|
||||
|
||||
In this phase, you wire your workflows together so the output of one becomes the input of another:
|
||||
|
||||
The email center classifies a sales inquiry → the lead data feeds into the CRM → the CRM triggers the lead qualification workflow → the qualified lead generates a meeting prep brief → the meeting generates action items → the action items feed into the weekly report.
|
||||
|
||||
Each workflow handles its piece. The connections between them create a system that runs the operational layer of your business end-to-end.
|
||||
|
||||
**The connection architecture:**
|
||||
|
||||
Use a central event system. When one workflow produces an output, it emits an event. Other workflows listen for relevant events and trigger when they detect one.
|
||||
|
||||
Tools like n8n, Zapier, or Make handle this orchestration visually. For more control, you can build event routing in code using webhooks and message queues.
|
||||
|
||||
The key design principle: workflows should be loosely coupled. Each workflow should function independently even if another workflow is down. If the email center fails, the report factory should still run on its data sources. Loose coupling prevents cascading failures.
|
||||
|
||||
# Phase 5: Monitor, Measure, and Improve (Ongoing)
|
||||
|
||||
Your workflow system is running. Now keep it running well.
|
||||
|
||||
**Monitor three things per workflow:**
|
||||
|
||||
Success rate: what percentage of inputs are processed without errors?
|
||||
|
||||
Target: 95 percent or higher.
|
||||
|
||||
Processing time: how long does each workflow take from trigger to completion?
|
||||
|
||||
Track trends. Increasing times suggest a problem.
|
||||
|
||||
Quality score: sample 10 percent of outputs weekly and rate their quality. Are the email responses accurate? Are the reports correct? Is the content good enough to publish with minimal editing?
|
||||
|
||||
**Monthly improvement cycle:**
|
||||
|
||||
Review quality scores. Identify the workflow with the lowest score. Diagnose why - is it a prompt issue, a tool connection issue, or an edge case issue? Fix it. Re-score the following month.
|
||||
|
||||
Review the workflow map from Phase 1. Have any new workflows emerged that should be automated? Have any automated workflows become obsolete? Keep the system aligned with how the business actually operates.
|
||||
|
||||
**Quarterly capability assessment:**
|
||||
|
||||
What new AI capabilities have become available since you built the system? New MCP servers, new model capabilities, new tools? Evaluate whether any would improve your existing workflows or enable new ones.
|
||||
|
||||
# The Bottom Line
|
||||
|
||||
An AI autopilot for your business is not one magic tool. It is a system of interconnected workflows that handle the operational layer while you focus on strategy, relationships, and growth.
|
||||
|
||||
Map your workflows. Design the automation architecture. Build the core three. Connect them into a system. Monitor and improve continuously.
|
||||
|
||||
The businesses that build this system now will operate at a fundamentally different level than businesses that continue doing everything manually.
|
||||
|
||||
Not because AI is smarter. Because AI does not sleep, does not forget, does not get sick, and does not need to be asked twice.
|
||||
|
||||
The operational overhead that consumes 60 to 70 percent of your time is solvable.
|
||||
|
||||
The solution is not hiring more people. It is building better systems.
|
||||
|
||||
**Follow me** [@eng\_khairallah1](https://x.com/@eng_khairallah1) **for more automation architectures, workflow designs, and business AI playbooks.**
|
||||
|
||||
**hope this was useful for you, Khairallah** **❤️**
|
||||
@@ -0,0 +1,177 @@
|
||||
---
|
||||
title: "How to Build An AI Operator for Your Businesses"
|
||||
source: "https://x.com/NickSpisak_/status/2048142772352528711"
|
||||
author:
|
||||
- "[[@NickSpisak_]]"
|
||||
published: 2026-04-26
|
||||
created: 2026-04-26
|
||||
description: "You're the salesperson. The closer. The PM. The strategist. The one fixing payroll at 11pm on Thursday. That's not a service business. That'..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
You're the salesperson. The closer. The PM. The strategist. The one fixing payroll at 11pm on Thursday. That's not a service business. That's a job that pays on an unreliable schedule.
|
||||
|
||||
The thing missing isn't another tool. It's an operator. Every generic AI you've tried is a search engine in a polite voice, not the chief of staff you need.
|
||||
|
||||
In under 5 minutes you'll learn:
|
||||
|
||||
1. The 4 architecture patterns behind a working AI operator
|
||||
2. The 4-part system prompt that turns a Claude Project into a chief of staff
|
||||
3. The 6 specialist modes that run my service business week
|
||||
4. The exact bottleneck each mode unlocks (pricing, closing, ops, cash, positioning)
|
||||
5. How to build your own operator for one expert in a single afternoon
|
||||
|
||||
**PS: If you enjoy content like this, you'll love my weekly newsletter.**
|
||||
|
||||
**Every week I give you tools, prompts, and automations you can deploy the same day to turn AI into ROI in your business.**
|
||||
|
||||
[Subscribe (free) here.](https://return-my-time.kit.com/db5f932e4e)
|
||||
|
||||
## What an AI operator actually does
|
||||
|
||||
An AI operator does four things a generic AI won't:
|
||||
|
||||
- Routes to the right framework instead of averaging every expert into mush
|
||||
- Runs the cadence with you... dial counts, follow-ups, weekly cash reviews
|
||||
- Names the bottleneck you're avoiding, not the one you brought
|
||||
- Refuses to flatter weak offers, weak proposals, weak hires
|
||||
|
||||
If your AI never disagrees with you, it's not advising. It's flattering. Flattery is the most expensive feature in AI right now.
|
||||
|
||||
## The 4 architecture patterns
|
||||
|
||||
Four phases, in order:
|
||||
|
||||
**1\. Curate, don't scrape.** Every expert gets a manifest of authoritative sources, tagged by priority and category. YouTube channel, audiobooks (highest signal per byte), guest podcast appearances (where the off-script reasoning lives), long-form posts. A min-duration filter strips clips and shorts so reaction videos don't dilute the corpus.
|
||||
|
||||
A manifest row looks like this:
|
||||
|
||||
```text
|
||||
priority, category, source, min_duration
|
||||
1, channel, YouTube channel, 600
|
||||
1, books, audiobook, 10800
|
||||
2, guest-podcasts, long-form interview, 3600
|
||||
```
|
||||
|
||||
The advisor is only as sharp as the sources you give it.
|
||||
|
||||
**2\. Caption-first transcription.** Before spending a dollar on paid transcription, check how much of the corpus already has YouTube captions. Pull those. Whisper the rest. This one decision drops build cost from hundreds of dollars per expert to a few cups of coffee.
|
||||
|
||||
**3\. Distill, don't dump.** Loading 600 hours of raw transcript into a Claude Project gives you a noisy chatbot. The distill step is the work: chunk the corpus, run each chunk through a Claude pass that pulls out frameworks, voice patterns, and decision rules. Aggregate, dedupe, rank by evidence and specificity. Output is two short files that get loaded as Project knowledge.
|
||||
|
||||
A frameworks file entry looks like this:
|
||||
|
||||
```text
|
||||
## Grand Slam Offer
|
||||
An offer gets stronger when the dream outcome feels bigger,
|
||||
the buyer believes it is more likely, the time delay feels
|
||||
shorter, and the effort or sacrifice feels lower.
|
||||
```
|
||||
|
||||
A voice patterns file entry looks like this:
|
||||
|
||||
```text
|
||||
## Default rhythm
|
||||
1. Make the claim.
|
||||
2. Explain the mechanism.
|
||||
3. Give the example.
|
||||
4. Push toward action.
|
||||
```
|
||||
|
||||
**4\. Eval before you trust.** Every operator ships with a suite of test prompts. Each one has a "strong answer should" checklist of 3-4 specific things the answer must hit. Two Claude calls per prompt: one answers with the Project knowledge loaded, one judges against the checklist. Failures send you back to the distill step.
|
||||
|
||||
A test prompt looks like this:
|
||||
|
||||
```text
|
||||
## Offer diagnosis
|
||||
I help law firms sign more cases. I charge $2,500/month.
|
||||
Tell me what is weak.
|
||||
|
||||
Strong answer should:
|
||||
- identify weak specificity
|
||||
- address proof and risk reversal
|
||||
- suggest packaging or pricing changes
|
||||
```
|
||||
|
||||
That's the difference between a Project that sounds smart and one you'll trust near a real client decision.
|
||||
|
||||
## The system prompt that makes it work
|
||||
|
||||
The knowledge files are the brain. The system prompt is the personality and the refusal behavior. Without it, you get a polite chatbot. With it, something that tells you your offer is weak in the first sentence.
|
||||
|
||||
Every operator runs on a 4-part project-instructions file:
|
||||
|
||||
```text
|
||||
Response style: blunt truth first. Name the bottleneck before tactics. Push toward action over reflection.
|
||||
|
||||
Reasoning pattern: state the problem. Name the framework. Show the math. Give the example. End on the next move.
|
||||
|
||||
Conversational rules: no hedging. No preambles. No hiding behind "it depends." No flattering weak ideas.
|
||||
|
||||
Output preference: diagnosis. Why it matters. What to change. The next move.
|
||||
```
|
||||
|
||||
Copy that structure verbatim. Swap in expert-specific tone markers per advisor. Done.
|
||||
|
||||
The week below runs on this stack.
|
||||
|
||||
## 1\. Monday: pricing reset (Hormozi mode)
|
||||
|
||||
Most service businesses are 30-50% underpriced. Hormozi mode runs the Value Equation against my offer: dream outcome, perceived likelihood, time delay, effort. It tells me where the offer is generic, what risk reversal is missing, and what the price floor is given the proof.
|
||||
|
||||
A 30-minute conversation produces a packaged offer with a higher ceiling. ChatGPT gives you "consider exploring." Hormozi mode tells you which lever to move first.
|
||||
|
||||
## 2\. Tuesday: six-figure proposal prep (Voss mode)
|
||||
|
||||
You know the deals where the prospect goes quiet on price and you start pre-discounting? I run discovery notes through Voss mode for the calibrated questions I missed. It names the labels and mirrors that would have exposed the real objection, then rewrites the follow-up with tactical empathy instead of the apologetic tone that creeps in when a deal wobbles.
|
||||
|
||||
## 3\. Wednesday: pipeline cadence (Blount mode)
|
||||
|
||||
Every service business hits a sales plateau. Almost always the cause is the same: not enough top-of-funnel activity, dressed up as a strategy problem.
|
||||
|
||||
Blount mode does the math you don't want to do. Dial counts, contact rates, conversion ratios, the actual number of new conversations you need this week to hit your quarter. It calls out the LinkedIn scrolling that masquerades as prospecting.
|
||||
|
||||
## 4\. Thursday: ops fire (Herold mode)
|
||||
|
||||
The agency owner who can't take two weeks off without revenue dropping 30% has an org design problem, not a marketing problem.
|
||||
|
||||
Herold mode treats the business like a COO. It diagnoses where you're still the bottleneck, what role to hire next, and what filter so the new person isn't a project. Pairs with Dan Martell's Buyback Principle: hours bought back go into the next bottleneck.
|
||||
|
||||
## 5\. Friday: cash flow check (Michalowicz mode)
|
||||
|
||||
Service businesses go broke profitably every day of the week. Michalowicz mode runs Profit First mechanics on a service P&L: real account allocations on real numbers. It surfaces margin leaks inside operations that look healthy on paper.
|
||||
|
||||
The Friday check is fifteen minutes. The answer is either "you're fine" or "you have eight weeks of runway and didn't know it."
|
||||
|
||||
## 6\. Sunday: positioning audit (Thompson mode)
|
||||
|
||||
Once a month I drop the niche, offer, and ideal client into Thompson mode and ask whether the strategic position actually compounds. Aggregation Theory, supply economics, long-term defensibility.
|
||||
|
||||
Most service businesses run on a position that worked three years ago. The market moved. The position didn't. Thompson mode pulls me out of the week and into the year.
|
||||
|
||||
## Build your own (one expert, one afternoon)
|
||||
|
||||
You don't need a pipeline. You need one expert and four steps that mirror the architecture above:
|
||||
|
||||
- **Curate:** Pick the expert whose frameworks unlock your biggest bottleneck. Pricing? Hormozi. Closing? Voss. Cash? Michalowicz. List 8-12 of their highest-signal videos and audiobooks.
|
||||
- **Transcribe:** Pull YouTube captions where they exist. MacWhisper handles the rest for free. Most of a corpus by lunch.
|
||||
- **Distill:** Write two markdown files: frameworks (named, with the math) and voice patterns (how they push back, refuse, prioritize).
|
||||
- **Eval:** Create a Claude Project, load both files, paste the 4-part system prompt above. Write 6-10 prompts from the last 30 days of decisions, each with a "strong answer should" checklist of 3-4 bullets. If the answers miss the checklist, the distill is too thin. Sharpen and rerun.
|
||||
|
||||
That is one operator. Same four-step recipe repeats for the next twelve.
|
||||
|
||||
## The closer
|
||||
|
||||
Generic AI averages every expert into polite mush: never wrong, never useful enough to act on. A specialist mode only knows one expert's frameworks. It tells you to raise prices when ChatGPT tells you to A/B test.
|
||||
|
||||
13 specialists. 4 architecture patterns. One operator that flips between modes based on what the week brings. Boring on purpose. The bench is the moat. The operator that knows which framework to run, when to run it, and what to refuse is the asset that compounds.
|
||||
|
||||
You don't need more advice. You need an operator. Build one this afternoon.
|
||||
|
||||
**PS: If you enjoy content like this, you'll love my weekly newsletter.**
|
||||
|
||||
**Every week I give you tools, prompts, and automations you can deploy the same day to turn AI into ROI in your business.**
|
||||
|
||||
[Subscribe (free) here.](https://return-my-time.kit.com/db5f932e4e)
|
||||
@@ -0,0 +1,155 @@
|
||||
---
|
||||
title: "How to Build an OS for Your AI Workforce?"
|
||||
source: "https://x.com/akshay_pachaar/status/2036429137695613190"
|
||||
author:
|
||||
- "[[@akshay_pachaar]]"
|
||||
published: 2026-03-24
|
||||
created: 2026-05-04
|
||||
description: "A first-principles look at why managing a fleet of AI agents requires an OS layer, not a better framework, and what that layer actually need..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
A first-principles look at why managing a fleet of AI agents requires an OS layer, not a better framework, and what that layer actually needs to do.
|
||||
|
||||
We've spent two years getting really good at building AI agents.
|
||||
|
||||
We have frameworks, workflow builders, drag-and-drop canvases, Python libraries, multi-agent orchestrators. The tooling has never been more accessible. And yet, most organizations that deploy AI agents in production still treat it like a science project.
|
||||
|
||||
Something is missing, and it's not another framework.
|
||||
|
||||
# The problem isn't building agents. It's running them.
|
||||
|
||||
Think about how software development matured.
|
||||
|
||||
In the early days, developers wrote scripts. Then they wrote applications. Then systems got complex enough that you needed something to manage all those applications: an operating system. Something that handled resources, coordinated processes, and gave you a unified surface to interact with everything at once.
|
||||
|
||||
AI agents are following the exact same arc.
|
||||
|
||||

|
||||
|
||||
Right now, most teams are in the "writing scripts" phase. You build an agent. It does one thing well. You ship it. Then you build another. And another. Before long, you have a dozen agents doing a dozen different things, none of which know about each other, and no single place to manage all of them.
|
||||
|
||||
**That's not a workforce. That's a collection of scripts with nothing coordinating them.**
|
||||
|
||||
# What the current landscape actually gives you
|
||||
|
||||
Let's look at what's available today, honestly.
|
||||
|
||||
**Agent workflow builders** (tools like n8n, Dify, Flowise) are great for prototyping. You drag nodes onto a canvas, wire them together, and you have something that looks like an agent workflow. The problem is they hit a ceiling fast. Complex multi-agent coordination, dynamic task assignment, enterprise access controls, audit trails? Most of these tools weren't built for that.
|
||||
|
||||
**Code-first frameworks** (LangChain, CrewAI, AutoGen) give you power, but at a steep cost. You're writing graph definitions in Python, configuring role-based agent patterns, managing state manually. Experienced developers will tell you: the moment your [agents.py](https://agents.py/) file crosses a few hundred lines, the abstraction starts working against you. Debugging is painful and rewrites become a recurring reality.
|
||||
|
||||
**Personal AI assistants** (OpenAI's agents, Claude, Gemini in assistant mode) are remarkable at individual tasks. Ask them to research a topic, draft a document, or run a single workflow. They're designed to respond to you, one conversation at a time. But they weren't designed to coordinate a team of specialized agents working in parallel on a shared goal.
|
||||
|
||||
Here's the pattern across all of these:
|
||||
|
||||
- They help you build or interact with one agent at a time
|
||||
- They have no unified way to manage a fleet of agents
|
||||
- They can't assign new work to existing deployed agents through natural language
|
||||
- They have no shared memory, shared state, or shared governance layer
|
||||
|
||||

|
||||
|
||||
In other words, they solve the construction problem. Nobody has solved the operations problem.
|
||||
|
||||
# What an operating system for AI actually means
|
||||
|
||||
Let's go back to first principles.
|
||||
|
||||
An operating system doesn't build programs. It runs them and manages resources across programs. It gives you a single interface to see and control everything happening across your machine. It enforces permissions, logs activity, and handles failures gracefully.
|
||||
|
||||
An OS for AI agents would do the same thing, but for your workforce.
|
||||
|
||||
## It would give you one place to:
|
||||
|
||||
- Create, modify, and deploy agents without writing a single line of code
|
||||
- Direct your entire agent fleet through natural language
|
||||
- Assign tasks to specialized agents and monitor their progress
|
||||
- Connect agents to shared knowledge, shared data, and shared tools
|
||||
- Set permissions so different teams can only access relevant agents
|
||||
- See logs, audit what ran, and know exactly what each agent did
|
||||
|
||||
**The key insight is this: an AI workforce OS is not a builder. It's a command center.**
|
||||
|
||||

|
||||
|
||||
The builder is still important. Agents need to be designed well. Workflows need to be structured. But once they're running, you need a layer above them that lets you operate the whole system as a coherent unit.
|
||||
|
||||
# Why this gap exists in the first place
|
||||
|
||||
Most tooling in the AI agent space was designed from the bottom up.
|
||||
|
||||
Start with an LLM. Add tool use. Chain multiple LLM calls. Add memory. Coordinate multiple agents. Each step added complexity to an already-complex foundation.
|
||||
|
||||
Nobody stopped to ask: what does the person operating this system actually need?
|
||||
|
||||
A developer building an agent workflow doesn't think about the team lead who needs to assign new tasks to that agent next month. An ML engineer designing a multi-agent pipeline doesn't think about the compliance officer who needs to audit every action those agents took. A product manager deploying an AI research assistant doesn't think about the enterprise admin who needs to control which LLM providers each department can use.
|
||||
|
||||
The result is a massive gap between "we deployed agents" and "we have a managed AI workforce."
|
||||
|
||||
**Most organizations fall into this gap and never climb out.**
|
||||
|
||||

|
||||
|
||||
# The architecture this new layer needs
|
||||
|
||||
If you were to design an OS for your AI workforce from scratch, it would need a few things.
|
||||
|
||||
**A natural language command interface.** Not a visual canvas you drag things around on. Not a Python SDK you write against. A conversational layer where you can say "create a workflow that monitors our support inbox and escalates urgent tickets to Slack" and have it happen. This is how people actually want to interact with their AI workforce.
|
||||
|
||||
**Unified resource management.** Every agent should share access to the same knowledge bases, file stores, databases, and integration credentials. Not siloed per-agent, but managed at the workspace level. When you build a new agent, it should be able to see and use what everything else already has access to.
|
||||
|
||||
**Execution observability.** You need to see, in one place, what every agent is doing, what it has done, and why it made the decisions it did. Not buried in individual logs across different services. A single, structured audit trail.
|
||||
|
||||
**Enterprise-grade access controls.** Different teams should be able to use different agents without stepping on each other. Admins should be able to restrict which models or tools any agent can use. Sensitive data should stay gated.
|
||||
|
||||
**Self-hostability.** For any serious enterprise deployment, you can't send your data to a third-party SaaS. The OS needs to run in your own infrastructure.
|
||||
|
||||
These aren't "nice to haves." Without all of them, you don't have an operating system. You have a slightly fancier builder.
|
||||
|
||||

|
||||
|
||||
# What this changes for teams building with AI today
|
||||
|
||||
This philosophy reframes how you think about agents entirely.
|
||||
|
||||
Instead of asking "how do I build this agent," you start asking "what does my AI workforce look like six months from now, and how do I manage it?"
|
||||
|
||||
That shift matters because:
|
||||
|
||||
- **Agents become workers, not scripts.** They have roles, responsibilities, and oversight. You don't redeploy them from scratch when requirements change. You give them new instructions.
|
||||
- **Your workforce is composable.** A customer support agent, a research agent, and a data enrichment agent can share knowledge and hand off work to each other, because they're all managed by the same layer.
|
||||
- **Non-technical stakeholders can participate.** When the interface is natural language, you don't need an engineer to create a new agent or assign a new task. The product manager, the operations lead, the analyst, they can all contribute.
|
||||
- **Enterprise governance becomes tractable.** Audit trails, access controls, and compliance aren't bolted on afterward. They're built into the management layer from the start.
|
||||
|
||||
This is what makes AI agents viable at scale. Not better models. Not more integrations. A coherent management layer that treats the entire fleet as a single, operable system.
|
||||
|
||||

|
||||
|
||||
# Where things are heading
|
||||
|
||||
The bottleneck in AI adoption isn't model capability anymore. It's infrastructure maturity.
|
||||
|
||||
Organizations know what they want agents to do. They don't know how to deploy, manage, and govern them at scale. The teams that figure out the operations side first will have a structural advantage that compounds over time.
|
||||
|
||||
The companies building toward this future aren't starting with "how do we make better agents." They're starting with "what does the command center for our AI workforce look like."
|
||||
|
||||
That is the right question.
|
||||
|
||||
If you want to see this philosophy already being built, [Sim](https://www.sim.ai/) is doing exactly this. Their platform started as an open-source visual workflow builder and has evolved into what they call "the central intelligence layer for your AI workforce." The latest version ships Mothership, a natural language command center that lets you create, manage, and direct your entire agent fleet from a single interface.
|
||||
|
||||
The fact that it's **open-source** (27k+ GitHub stars, Apache 2.0) matters. You can self-host it, audit the code, and trust that you're not locked in. For builders who want to try the concept without building it from scratch, it's a solid starting point.
|
||||
|
||||
[Website →](https://www.sim.ai/)
|
||||
|
||||
[GitHub →](https://github.com/simstudioai/sim)
|
||||
|
||||
That's a wrap!
|
||||
|
||||
If you enjoyed reading this.
|
||||
|
||||
Find me →[@akshay\_pachaar](https://x.com/@akshay_pachaar) ✔️
|
||||
|
||||
Every day, I share tutorials and insights on AI, Machine Learning and vibe coding best practices.
|
||||
@@ -0,0 +1,319 @@
|
||||
---
|
||||
title: "How to build a Deep Researcher"
|
||||
source: "https://x.com/akshay_pachaar/status/2047395420935229724"
|
||||
author:
|
||||
- "[[@akshay_pachaar]]"
|
||||
published: 2026-04-24
|
||||
created: 2026-04-24
|
||||
description: "A 100% open-source, self-hostable Deep Research Stack That Beat OpenAI, Gemini, and PerplexityIf you need AI to do research for you today, y..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
A 100% open-source, self-hostable Deep Research Stack That Beat OpenAI, Gemini, and Perplexity
|
||||
|
||||
If you need AI to do research for you today, you're probably using ChatGPT Deep Research, Claude, or Perplexity. All three are genuinely capable. All three are also closed-source SaaS running in someone else's cloud.
|
||||
|
||||
Every query you send and every internal document you connect sits on their servers, not yours.
|
||||
|
||||
For most teams, that's been the trade-off: accept it, or don't use AI for serious research.
|
||||
|
||||
In this article, you'll see a third option: a fully open-source deep research stack that runs on your own infrastructure.
|
||||
|
||||
Three tools, all open source: [Onyx](https://github.com/onyx-dot-app/onyx) for retrieval, [CrewAI](https://crewai.com/) for orchestration, [Voxtral](https://huggingface.co/mistralai/Voxtral-4B-TTS-2603) for voice.
|
||||
|
||||
Here's the full system running end-to-end, from voice query to narrated research report:
|
||||
|
||||
<video preload="none" tabindex="-1" playsinline="" aria-label="嵌入式视频" poster="https://pbs.twimg.com/amplify_video_thumb/2047309825919582208/img/guEMMBsb2cyEoJ-T.jpg" style="width: 100%; height: 100%; position: absolute; background-color: black; top: 0%; left: 0%; transform: rotate(0deg) scale(1.005);"><source type="video/mp4" src="blob:https://x.com/b4933519-c904-4ce7-bbb4-873f260451be"></video>
|
||||
|
||||
0:29
|
||||
|
||||
The rest of this article breaks down how it works and walks you through building the same stack yourself. Before any of that, though, it's worth being clear about why this is worth building at all.
|
||||
|
||||
# Why self-hosting actually matters
|
||||
|
||||
Every major AI research tool is a closed cloud service. That has real consequences:
|
||||
|
||||
- **Your queries go to their servers.** The questions you ask reveal what you're working on.
|
||||
- **Your connected data gets indexed on their infrastructure.** Integration is convenient, but the index lives on their side.
|
||||
- **Retention, logging, and audit are their call, not yours.** Enterprise tiers soften this but don't eliminate it.
|
||||
- **Quotas and pricing change on their timeline.** The tool you depend on today can reprice or rate-limit tomorrow.
|
||||
|
||||
For regulated industries, teams with IP-sensitive work, or anyone working under data residency rules, that list isn't theoretical. It's the reason AI-assisted research still feels out of reach for a lot of serious work.
|
||||
|
||||
Unless you can run the whole stack yourself, with no compromise on quality.
|
||||
|
||||

|
||||
|
||||
# Why Existing Research Tools Break
|
||||
|
||||
Most research tools do one pass. They search, collect whatever comes back, and hand it to the LLM to write something up.
|
||||
|
||||
That works for shallow queries. It breaks the moment you ask something that requires synthesis across sources, contradiction detection, or reasoning across multiple hops.
|
||||
|
||||
Here's what that failure looks like in practice:
|
||||
|
||||
- The agent finds a source and a contradicting source. It picks one and moves on. The contradiction never surfaces.
|
||||
- Two sources say the same thing in different words. The report cites both as independent evidence.
|
||||
- A critical connecting fact lives in a document that wasn't retrieved, because keyword matching doesn't understand that "cloud migration" and "moving our PostgreSQL cluster to AWS" are the same thing.
|
||||
|
||||
These aren't edge cases. They're the normal shape of real research questions.
|
||||
|
||||
And they all share the same root cause: **research isn't one task.**
|
||||
|
||||

|
||||
|
||||
# What good deep research actually requires
|
||||
|
||||
Five things, regardless of tools:
|
||||
|
||||
**1\. Separation of stages.** Hard walls between gathering, analysis, and writing. Each stage gets only the clean output from the one before.
|
||||
|
||||
**2\. Retrieval that reasons.** Keyword search is brittle. Vector similarity breaks on multi-hop. You need parallel query variants, intelligent recombination, and an LLM selection step before synthesis. Skip that last step and hallucinations enter.
|
||||
|
||||
**3\. Reflection in the loop.** Static plans don't survive contact with findings. The system should pivot when something unexpected surfaces, while tracking coverage of the original plan.
|
||||
|
||||
**4\. Unified search across public and internal sources.** A research layer needs to query the open web and internal knowledge in one pipeline, with permissions enforced per-document. Whether the indexing runs on your infrastructure or a vendor's is what determines who owns the data.
|
||||
|
||||
**5\. A voice layer.** Speaking beats typing for queries. Listening beats reading for long reports. Makes a tool reachable, not just usable.
|
||||
|
||||

|
||||
|
||||
## Onyx: an open-source retrieval layer that beats the benchmarks
|
||||
|
||||
Onyx is an open-source AI platform built around these principles. It gives any model RAG, web search, code execution, deep research, and custom agents out of the box.
|
||||
|
||||
Fully self-hostable, so your data never leaves your infrastructure.
|
||||
|
||||
And it's not a compromise on capability.
|
||||
|
||||
Onyx submitted to **DeepResearch Bench**, an independent academic benchmark covering 100 PhD-level research tasks across 22 fields, evaluated on report quality and citation accuracy.
|
||||
|
||||
**It placed #1**, ahead of OpenAI Deep Research, Gemini 2.5 Pro, and Perplexity Deep Research.
|
||||
|
||||
The team recently shared their lessons from that submission. Their prompt philosophy in one line: "Prefer being thorough in research over being helpful."
|
||||
|
||||
Here's how that philosophy translates to architecture.
|
||||
|
||||
## Three phases, not one loop
|
||||
|
||||
**Phase 1: Clarification.** Up to 5 targeted questions for short or ambiguous queries. Skipped automatically for detailed ones.
|
||||
|
||||
**Phase 2: Planning.** Decomposes the query into up to 6 exploration directions. Critical choice: the planner has no tool access, so it produces a plan, not answers.
|
||||
|
||||
**Phase 3: Iterative execution.** Orchestrator and research agents alternate up to 8 cycles, each dispatching up to 3 agents in parallel.
|
||||
|
||||

|
||||
|
||||
## Two separations that matter:
|
||||
|
||||
- The orchestrator never searches directly.
|
||||
- Research agents never see the full query or plan.
|
||||
|
||||
This forces self-contained task briefs and prevents context leakage.
|
||||
|
||||
## Adaptive strategy
|
||||
|
||||
Onyx deviates from the original plan based on what it finds. Between every dispatch, a mandatory reflection step produces structured output:
|
||||
|
||||
- What's covered
|
||||
- What gaps remain
|
||||
- What new directions emerged
|
||||
- Whether more cycles will yield new info
|
||||
|
||||
Runs every time. The result behaves like a researcher, not a retrieval engine.
|
||||
|
||||
## The 6-stage retrieval pipeline
|
||||
|
||||
Each agent runs this before the LLM synthesises anything:
|
||||
|
||||
1. **Query generation.** Parallel queries: semantic rephrasing, keyword variants, broad searches. Multi-part questions split automatically.
|
||||
2. **Search and recombination.** Hybrid index (vector + BM-25), results combined via Reciprocal Rank Fusion, adjacent chunks merged.
|
||||
3. **LLM selection.** The LLM reviews all chunks and keeps only the relevant ones. Skipping this is where hallucinations enter.
|
||||
4. **Context expansion.** For each selected doc, the LLM reads surrounding chunks to decide context size. Parallel per document.
|
||||
5. **Prompt building.** Selected sections assembled with citations and chat history.
|
||||
6. **Answer synthesis.** Grounded answer with inline citations linking to sources.
|
||||
|
||||

|
||||
|
||||
## Citation integrity
|
||||
|
||||
- Agents cite inline as they write intermediate reports.
|
||||
- Citations from parallel agents get merged and renumbered into one unified set.
|
||||
- Every final claim traces back to a specific source document.
|
||||
|
||||
## Internal sources, indexed on your infrastructure
|
||||
|
||||
Onyx connects to **40+ enterprise data sources**: Slack, Confluence, Jira, GitHub, Salesforce, Google Drive, SharePoint, Notion, Zendesk, HubSpot, Gong, and more.
|
||||
|
||||

|
||||
|
||||
The difference from proprietary tools isn't whether it can connect. It's where the indexing happens. Onyx pre-indexes everything continuously on your own infrastructure, syncing content, metadata, and permissions in near real time.
|
||||
|
||||
**What that gets you:**
|
||||
|
||||
- One query spans the open web and every internal source at once.
|
||||
- Users only see results from documents they're authorised to view.
|
||||
- Permissions sync automatically from each source.
|
||||
- No internal data leaves your network to be indexed or stored by a vendor.
|
||||
|
||||

|
||||
|
||||
# CrewAI: the orchestration layer
|
||||
|
||||
Onyx handles retrieval. CrewAI handles coordination.
|
||||
|
||||
The default pattern most developers reach for is one agent with three sequential tasks sharing a growing context window:
|
||||
|
||||
- The writer starts before the analyst finishes.
|
||||
- Raw search noise bleeds into the final report.
|
||||
- Source material gets reinterpreted twice before output.
|
||||
|
||||
**CrewAI solves this with three primitives:**
|
||||
|
||||
- **Flows** wire independent Crews together, each receiving only clean output from the stage before. No accumulated context.
|
||||
- **Skills** inject domain-specific instructions into an agent's prompt at runtime via SKILL.md. Instruction at the point of action.
|
||||
- **MCP Integration** attaches MCP servers directly to an agent via the mcps field. No adapter, no context manager.
|
||||
|
||||
Onyx connects in one declaration:
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
|
||||
researcher_agent = Agent(
|
||||
role="Senior Research Analyst",
|
||||
goal="Gather information on research query with source URLs",
|
||||
backstory="You are a disciplined analyst. Record every source URL.",
|
||||
mcps=[
|
||||
f"{ONYX_MCP_URL}?token={ONYX_TOKEN}"
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
The Researcher agent gets three tools instantly:
|
||||
|
||||
- Search the knowledge base
|
||||
- Search the web
|
||||
- Fetch full page content from any URL
|
||||
|
||||
No manual tool wiring. Schemas cached, connections on-demand, graceful failure if the server is unreachable.
|
||||
|
||||
# Voxtral: the voice layer
|
||||
|
||||
Every research workflow has one friction point: the keyboard.
|
||||
|
||||
Voice in AI tools is usually a bolt-on: a Whisper wrapper for input, a basic TTS for output, different models per direction with no coherent design.
|
||||
|
||||
Voxtral is different. It's Mistral's native audio model family, built for speech understanding and generation from the ground up, with the same family handling both directions:
|
||||
|
||||
- Transcription stays accurate across accents, background noise, and domain vocabulary.
|
||||
- Narration sounds natural, not robotic.
|
||||
|
||||
**Two changes to the research experience:**
|
||||
|
||||
- **Voice input.** Speak a question instead of typing. The transcript flows straight into the pipeline.
|
||||
- **Report narration.** The full Markdown report gets read back as expressive speech. Listening beats screen-reading for long reports.
|
||||
|
||||

|
||||
|
||||
# How it all fits together
|
||||
|
||||
**The full flow:**
|
||||
|
||||
<video preload="auto" tabindex="-1" playsinline="" aria-label="嵌入式视频" poster="https://pbs.twimg.com/tweet_video_thumb/HGnGsR8bYAAa8uL.jpg" src="https://video.twimg.com/tweet_video/HGnGsR8bYAAa8uL.mp4" type="video/mp4" style="width: 100%; height: 100%; position: absolute; background-color: black; top: 0%; left: 0%; transform: rotate(0deg) scale(1.005);"></video>
|
||||
|
||||

|
||||
|
||||
GIF
|
||||
|
||||
1. Type, speak, or upload a PDF as your research query.
|
||||
2. **Researcher Agent** searches the web and your documents via Onyx MCP.
|
||||
3. **Analyst Agent** deduplicates, flags contradictions, and groups findings.
|
||||
4. **Report Writer Agent** produces a structured, citation-backed Markdown report.
|
||||
5. Click **"Play Report"** for narration via Voxtral TTS.
|
||||
|
||||
## Three mini-crews, not one
|
||||
|
||||
The natural first design is one Crew with three sequential tasks. Don't do it.
|
||||
|
||||
Shared context across stages degrades ground truth. The Onyx team calls this "deep frying":
|
||||
|
||||
- Facts get reinterpreted.
|
||||
- Contradictions smoothed over.
|
||||
- Source material unrecognisable by the time the Writer sees it.
|
||||
|
||||
This system uses a Flow: three separate Crews, each receiving only clean output from the stage before.
|
||||
|
||||

|
||||
|
||||
**Researcher Agent.** Connects to Onyx via CrewAI's MCP integration. Runs web searches, reads full URLs, searches uploaded PDFs. Every finding carries a citation.
|
||||
|
||||
**Analyst Agent.** Takes raw findings and:
|
||||
|
||||
- Deduplicates overlapping facts
|
||||
- Merges sources saying the same thing
|
||||
- Flags explicit contradictions
|
||||
- Groups into coherent themes
|
||||
|
||||
Output is a structured summary, not a pile of search results.
|
||||
|
||||
**Report Writer Agent.** Turns the summary into a polished, citation-backed Markdown report. Equipped with a CrewAI Skill (SKILL.md) injected at generation time for consistent structure.
|
||||
|
||||
```plaintext
|
||||
deep-research-report/
|
||||
├── SKILL.md # Formatting rules, evidence standards, structure
|
||||
├── scripts/ # Optional
|
||||
└── references/ # Optional
|
||||
```
|
||||
|
||||
SKILL.md uses YAML front matter and a Markdown body:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: deep-research-report
|
||||
description: >
|
||||
Guidelines for writing high-quality, publication-ready deep research reports.
|
||||
Covers structure, tone, evidence standards, and formatting rules.
|
||||
metadata:
|
||||
author: deep-research-agent
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
Instructions for the agent go here.
|
||||
This markdown is injected into the agent's prompt when the skill is activated.
|
||||
```
|
||||
|
||||
Here's a successful execution of the full flow:
|
||||
|
||||

|
||||
|
||||
# Find all the code and try it here
|
||||
|
||||
You can find all the code for the project on [@LightningAI](https://x.com/@LightningAI) Studio:
|
||||
|
||||
[Get started here →](https://lightning.ai/lightning-ai/templates/multi-agent-deep-researcher-powered-by-gemma-4?utm_campaign=akshay&utm_medium=twitter)
|
||||
|
||||
# What you get by building this
|
||||
|
||||
The story here isn't that an open-source tool has finally caught up to the big names.
|
||||
|
||||
[Onyx](https://github.com/onyx-dot-app/onyx) runs deep research on infrastructure you can inspect, self-host, and modify. Paired with CrewAI's enforced stage separation and Voxtral's native speech layer, you get a research stack with:
|
||||
|
||||
- **Capability.** Competitive or better research quality, with full citation integrity.
|
||||
- **Control.** Every byte of your queries and internal data stays on your infrastructure.
|
||||
- **Transparency.** Open-source code you can read, audit, and extend.
|
||||
|
||||

|
||||
|
||||
So here's the question worth starting with: **what would your team's research workflow look like if data sovereignty wasn't the constraint?**
|
||||
|
||||
Start there.
|
||||
|
||||
That's a wrap!
|
||||
|
||||
If you enjoyed reading this:
|
||||
|
||||
Find me →[@akshay\_pachaar](https://x.com/@akshay_pachaar) ✔️
|
||||
|
||||
Every day, I share tutorials and insights on AI, Machine Learning, and vibe coding best practices.
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
title: "How to build something small"
|
||||
source: "https://x.com/zarazhangrui/status/2050445806428438734"
|
||||
author:
|
||||
- "[[@zarazhangrui]]"
|
||||
published: 2026-05-02
|
||||
created: 2026-05-02
|
||||
description: "Most people teach you how to build something big. But I think we should learn how to build something small.Here are a few small things I've ..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
Most people teach you how to build something big. But I think we should learn how to build something small.
|
||||
|
||||
Here are a few small things I've built. All of these were built as side projects for fun:
|
||||
|
||||
1. [Frontend Slides](https://github.com/zarazhangrui/frontend-slides) (16k stars on GitHub): a skill that lets you create beautiful HTML slides with coding agents
|
||||
2. [Follow Builders](https://github.com/zarazhangrui/follow-builders) (3.6k stars on GitHub): a skill that gives you a daily newsletter consisting of tweets and podcasts from a strictly curated list of AI builders
|
||||
3. [Tab Out](https://github.com/zarazhangrui/tab-out) (1.1k stars on GitHub): a Chrome extension that turns your New Tab page into a Mission Control where you can clearly see your open tabs and easily close them
|
||||
|
||||
# Why build something small?
|
||||
|
||||
## 1\. Every big thing starts as a small thing
|
||||
|
||||
Positioning is everything. Most products fail not because they were too narrow, but because they targeted too wide.
|
||||
|
||||
If you're everything to everybody, you end up being nothing to nobody. You become a generic, bland thing that will be eaten by Claude.
|
||||
|
||||
## 2\. Build for fun, build to learn
|
||||
|
||||
Don't take software too seriously.
|
||||
|
||||
Building software used to be a serious, utilitarian pursuit. People mostly did it to make money. This made sense when software was scarce and expensive.
|
||||
|
||||
But now that software is cheap and abundant, you can actually do it for fun. Vibe coding is basically my weekend hobby now, and some of my little skills feel more like art projects. We need to overcome the scarcity mindset for software. You're totally allowed to build something useless.
|
||||
|
||||
Building something is also the best way to learn. In the traditional education system, you learned to build. In the AI era, this is now reversed: you build to learn.
|
||||
|
||||
## 3\. Build an opinionated product
|
||||
|
||||
Software is a form of self-expression. When you build a piece of software, you're embedding a little piece of your soul in it: your unique way of thinking and doing something.
|
||||
|
||||
Now that AI can build anything really quickly, what makes people want to use your software, not somebody else's?
|
||||
|
||||
Your product needs to have character. It needs to make people feel like "huh, I've never thought about it this way before, but it makes a lot of sense." People will use it because the opinion behind it resonates with them.
|
||||
|
||||
If your product is just some generic, bland productivity tool, people may as well just use Claude.
|
||||
|
||||
Case in point: there are so many AI news fetching skills out there; my [Follow Builders](https://github.com/zarazhangrui/follow-builders) skill resonated with people because they liked the underlying philosophy of "follow builders, not influencers."
|
||||
|
||||
## 4\. You can afford to
|
||||
|
||||
Before AI, you couldn't afford to build something small. Because the cost of software development was so high, you had to hire a team, convince other people, justify it to a committee.
|
||||
|
||||
Now, it's literally just you and a coding agent. A coding agent doesn't need to be convinced. It will readily build whatever crazy and weird idea you have. So go build something that would get rejected in every big tech company's product review meeting.
|
||||
|
||||
# How to find product ideas
|
||||
|
||||
## 1\. You're not that unique
|
||||
|
||||
A lot of people tell me "I have this pain point that I want to build a product for, but I'm worried it would be too niche."
|
||||
|
||||
I want to tell them: sorry that this sounds harsh, but you're not as unique as you think you are.
|
||||
|
||||
Whatever super niche pain point you have, there are at least 10k people in the world who share the same pain point. Maybe not 10 million, but definitely 10k.
|
||||
|
||||
In the old world, a product with a 10k total addressable market was not worth building. In the new world, a product with a 10k user base is a very successful side project.
|
||||
|
||||
What you think might be an extremely niche need might not be as niche as you think. You just need to find those 10k people who are as weird as you.
|
||||
|
||||
## 2\. Start with the technology
|
||||
|
||||
For most of my projects, I actually didn't start with the pain point. I started with the technology. Every day I browse X and bookmark cool new technologies and APIs that come out. Then I have a regular "playtime" where I just feed my coding agent these new technologies and we brainstorm what we can build with them. It's a lot of fun.
|
||||
|
||||
Case in point: I built [Tab Out](https://github.com/zarazhangrui/tab-out) because I first saw someone build something that reads their Chrome browsing history, and that's how I found out your browsing history is saved locally in a database. So I brainstormed with Claude what we could do with it, and after lots of discussion and iteration, we ended up with a browser extension that helps you close your tabs.
|
||||
|
||||
# How to talk to models
|
||||
|
||||
## 1\. Use the best model
|
||||
|
||||
Counterintuitively, it will often end up being cheaper than if you use a dumber model. With a dumber model, you end up not being able to do things correctly, and you spend more tokens and time fixing it.
|
||||
|
||||
## 2\. Treat it as your cofounder, not your employee
|
||||
|
||||
I seldom start by giving a detailed product spec and asking my agent to execute. I just describe my problem extensively, and ask for my agent's opinion. We bounce ideas off each other and come up with the solution together. It's a co-creation process.
|
||||
|
||||
Bring the problem, not the solution.
|
||||
|
||||
## 3\. Try everything, waste tokens
|
||||
|
||||
Have an unreasonably high standard. Keep pushing the agent to its limits. Try crazy ideas and see what it does. You can't usually get away with this when working with humans, so make the most of it.
|
||||
|
||||
## 4\. Cut features before shipping
|
||||
|
||||
LLMs are very good at adding things, but not very good at subtracting things. They often end up adding unnecessary features that look plausible at first but turn out to be useless in practice. As humans, your most important job is to subtract, simplify, and cut.
|
||||
|
||||
Build something small and elegant. Software is a medium for storytelling. Go tell a great story.
|
||||
@@ -0,0 +1,181 @@
|
||||
---
|
||||
title: "How to get your company AI pilled"
|
||||
source: "https://x.com/geoffintech/status/2042002590758572377"
|
||||
author:
|
||||
- "[[@geoffintech]]"
|
||||
published: 2026-04-09
|
||||
created: 2026-04-26
|
||||
description: "Most companies are still debating their AI strategy. They are overthinking it. Here is the playbook we followed to get everyone at the compa..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
Most companies are still debating their AI strategy. They are overthinking it. Here is the playbook we followed to get everyone at the company building using AI.
|
||||
|
||||
Ramp's AI usage is up 6,300% from last year. 99.5% of the team active on AI tools. 84% using coding agents weekly. 1,500+ apps shipped on our internal platform in six weeks, from 800+ different builders. Non-engineers now account for 12% of all human-initiated PRs on the production codebase - thousands per month - using Ramp Inspect, our home-built coding agent.
|
||||
|
||||
We did this by being obsessed over every employee embracing this new technology - akin to how computers entered the workforce. We built our own Claude Cowork called Glass that gives anyone at the company a highly configured AI agent that is fully connected with Ramp's systems and aware of how we build. We hosted the largest AI hackathon ever - 700 participants across sellers, CX, legal, marketing, finance, coached by 100 of our most capable engineering and product teammates. They shipped more in a week than we previously could in a year.
|
||||
|
||||
We modified our hiring process and talent management process. We gave everyone unlimited budget to build, learn, and explore. We created leaderboards to incentivize usage. We reorged teams around those who see the future. We celebrated wins at all hands. We relentlessly pushed every single person and leader to build. And the result is far beyond what I could ever imagine.
|
||||
|
||||
Here's how we got here. The interesting part isn't the numbers or the tools. It's that we didn't have a plan. **All we had was a culture and talent**, and we kept doubling down on the things that were working with the people and technology in front of us. And watched it compound.
|
||||
|
||||
## 1\. The second best time to start is today.
|
||||
|
||||
At Ramp, our culture is velocity. It shapes every process and team ritual. That culture turned out to be the single biggest accelerant for AI adoption.
|
||||
|
||||
At our January 2025 company kickoff, we told the whole company we would become the most productive company in the world. We believed we could do it given Ramp's culture. We had no idea how.
|
||||
|
||||
We started with the obvious:
|
||||
|
||||
1. Leadership clarity that AI usage is an expectation
|
||||
2. Dedicated AI "guild" that were responsive to any questions
|
||||
3. Slack channels where teams can share what they built
|
||||
4. Dedicated all hands time to celebrate builders
|
||||
5. Mandated AI usage and tracking for everyone
|
||||
|
||||
There was no formal change management program. No mandatory training curriculum. Instead, we built the infrastructure for people to teach themselves and each other. The reality is that teams just need to be given a chance. Everyone wants to build. And with AI, anyone can.
|
||||
|
||||
## 2\. Treat AI proficiency as a learning curve, not a light switch.
|
||||
|
||||
A year ago, most of us used AI the way everyone did. ChatGPT in a tab. AI search in Notion. Fine, but not transformational.
|
||||
|
||||
What we observed was that productive output leaps when people clear certain thresholds of comfort. Almost nobody outside of some exceptional engineers was operating at the upper levels before 2025. But in late 2025 and this year, we accelerated massively -- because we spent last year building a strong foundation first.
|
||||
|
||||
We think about AI proficiency in four levels:
|
||||
|
||||

|
||||
|
||||
- **L0:** Sometimes uses ChatGPT. Has not changed any workflows. If you're still here and not self-starting, you will most likely not be at the company.
|
||||
- **L1:** Built custom GPTs, used Notion agents, dabbled in Claude Code. Starting to see what's possible but hasn't compounded it yet.
|
||||
- **L2:** Built an app that automates part of their job. Committed code or contributed feedback to others' work. This is where things get real.
|
||||
- **L3:** Systems builders. They don't just use AI - they build the infrastructure that levels up everyone else. These people are force multipliers.
|
||||
|
||||
Our job is to get everyone up the ladder. Three things make that possible:
|
||||
|
||||
1. **Build tools that meet people where they are.** We started by shifting the whole company to Claude and Notion AI connected to all of our workplace tools - a low technical bar where everyone could participate and get meaningful benefit. That got people from L0 to L1.
|
||||
2. **Raise expectations as tools mature.** AI proficiency moved into hiring screens, onboarding, and how we talk about performance. Not as an end in itself, but as a stated expectation: getting good at these tools is essential to doing any job at Ramp well. That pushes L1s to L2.
|
||||
3. **Match the mandate to the tooling.** If you raise expectations before the tools can deliver, you burn credibility and people stop listening.
|
||||
|
||||
## 3\. Embrace creative destruction.
|
||||
|
||||
This is the part that makes Ramp exhilarating and uncomfortable in equal measure.
|
||||
|
||||
Many of the tools we shipped in January 2026 are already obsolete - replaced by better versions, often from the same builders. We've gotten comfortable with a shelf life of weeks, not months. Every LLM update, every improvement to Claude Code or Codex harnesses, every new batch of skills we release reshapes what's possible. **If your internal tools from three months ago still feel state-of-the-art, you're not moving boldly enough.**
|
||||
|
||||
Our data democratization journey tells the story well:
|
||||
|
||||
- **Phase 1:** Notion AI was the best option, so we piped important data into Notion databases to run our agent over it.
|
||||
- **Phase 2:** We launched Ramp Research, a Slack-based Snowflake research tool.
|
||||
- **Phase 3:** As coding agents matured, we encoded Snowflake research into skills those agents could use directly.
|
||||
- **Phase 4:** Now we're making data research interactive and self-improving.
|
||||
|
||||
Each generation opened doors the previous one couldn't. Each former generation was quietly sunset. The tools we're running right now? We genuinely hope they're obsolete by June.
|
||||
|
||||
From the outside, this looks chaotic. From the inside, it's the opposite. **People aren't attached to their tools. They're attached to their problems.** When a better way to solve the problem shows up, they grab it.
|
||||
|
||||
## 4\. Build from the center, drive from the spokes.
|
||||
|
||||
We got the org design wrong before we got it right.
|
||||
|
||||
The initial instinct was to centralize: one small team builds tools for the whole company. Demand outstripped capacity almost immediately. Then we swung decentralized -- every team builds their own things. Tons of redundant re-learning.
|
||||
|
||||
The answer was to do both:
|
||||
|
||||
1. **A small central team** builds the platforms, connectors, and plumbing across LLMs, data, knowledge, and workflows. They also manage training, enablement, and change management.
|
||||
2. **Functional teams** build on top of those platforms and give feedback that drives the central team's roadmap.
|
||||
|
||||
The results speak for themselves:
|
||||
|
||||
- A risk analyst automated 16 hours per month of manual financial modeling.
|
||||
- A sales ops lead replaced a spreadsheet-based comp model across three orgs in 48 hours.
|
||||
- An L&D lead built a training simulator in 15 minutes.
|
||||
- Someone in finance built a contract reviewer that saves 45 minutes per contract -- and Ramp has a lot of contracts.
|
||||
|
||||
**None of them are engineers.**
|
||||
|
||||
These people didn't file a ticket. They found their own pain, prototyped a fix, and pulled engineering in when it was time to go to production -- when that was even necessary. The spokes drove the center as much as the center drove the spokes.
|
||||
|
||||
## 5\. Give people a stage, not just a mandate.
|
||||
|
||||
Mandates decay. Culture is what remains.
|
||||
|
||||
The strategy, to the extent there was one, was to light as many small fires as possible and see which ones grew:
|
||||
|
||||
1. **A Slack channel (**[#ramp](https://x.com/search?q=%23ramp&src=hashtag_click)**\-uses-ai)** - just to see what happened. Now over 1,000 members. Spun off 40+ team-specific channels that collectively generate 20,000 messages per month.
|
||||
2. **AI office hours every Friday** - regularly 40-50+ people show up with questions.
|
||||
3. **AI onboarding for new hires** - rebuilt four times in the last year as ambition grew.
|
||||
4. **Dedicated all hands** \- we have everyone from our CEO to a first line operator demo what they have built with AI
|
||||
|
||||
The early converts mattered more than anything. On every team, there was one person - the ambitious sales ops lead, the frustrated product operator, the eager data scientist. They got curious, got sucked in, and became contagion for their teams. We made them visible: company All Hands spotlights, resources to build team-level tools, pairing them up when collaboration was warranted.
|
||||
|
||||
All this public building creates a competitive dynamic that everyone feels. Nobody wants to be the team that isn't building anything. When a CSM sees a risk analyst ship something that saves 16 hours a month, they don't think "good for Risk." They think "what can I build?"
|
||||
|
||||
That loop - build, share, inspire, build more - does more than any mandate or memo. **The biggest surprise wasn't who built the most. It was how many people had been waiting for permission to build at all**
|
||||
|
||||
## 6\. Get people to the "Aha" moment as fast as possible.
|
||||
|
||||
Training doesn't work. Office hours and workshops help. But the world's best teacher is staring right in front of you: it's AI. **You can only lead a horse to water.** The single biggest unlock is getting someone to experience a real result on day one.
|
||||
|
||||
We learned this the hard way. Despite hitting 90%+ adoption of AI tools across the company, most people were stuck on a basic chat interface. The models were good enough. The harness wasn't. Terminal windows, npm installs, MCP configurations - these were simply too hard for the majority of people to grok. And the people who did push through had wildly different setups with siloed learnings that weren't compounding.
|
||||
|
||||
So we built Glass - our own version of Claude Code's Cowork, built on Anthropic's Claude Agent SDK.
|
||||
|
||||
Glass auto-configures on install. You authenticate once via Okta SSO and 30+ tools light up - Salesforce, Snowflake, Gong, Slack, Notion, Google Workspace, Figma. No setup guide. No ticket to IT. If the user has to debug, we've already lost.
|
||||
|
||||
A team of four built it in under three months. 700 daily active users within a month of launch. The people who got the most value weren't the ones who attended training sessions. They were the ones who installed a skill on day one and immediately got a result. The product taught them faster than we ever could.
|
||||
|
||||
When you own the tool, you see exactly where people get stuck and ship a fix the same day. Every session generates signal about how non-engineers actually learn to use AI - which skills get adopted, where people break through, what separates someone who uses it once a week from someone who uses it every day.
|
||||
|
||||
We also built a skills marketplace called Dojo where anyone can package a workflow and share it. Over 350 skills shared company-wide. A sales rep figures out the best way to analyze Gong calls and draft battlecards - packages it as a skill, and now every rep has that superpower. Every skill shared raises the floor for everyone.
|
||||
|
||||

|
||||
|
||||
**The result is that anyone in 5 minutes can create anything.**
|
||||
|
||||
## 7\. Make it a competition.
|
||||
|
||||
People are competitive. At least this is true at Ramp.
|
||||
|
||||
We built an internal leaderboard that tracks AI usage across every team and individual at Ramp. Sessions run, skills used, apps shipped, tools connected. It's visible to everyone. The skeptics will tell you this is a vanity metric - that tracking usage incentivizes busywork, not productivity. We found the opposite.
|
||||
|
||||
**The top AI users at Ramp are often the highest performers.** AI proficiency is a skill like any other - the more reps you get, the better you become. The power users are developing muscle memory for when to reach for AI, how to prompt effectively, which skills to combine, and when to override. They're compounding their own leverage.
|
||||
|
||||
The leaderboard created three dynamics we didn't fully anticipate:
|
||||
|
||||
1. **Healthy peer pressure.** Nobody wants to be at the bottom. When you can see that your peer on another team is running 3x more sessions and shipping tools that save their team hours, you don't need a mandate to start building. You need your competitive instincts.
|
||||
2. **Manager accountability.** Team-level rankings made it impossible for managers to ignore AI adoption. If your team is in the bottom quartile, that's a conversation you're going to have. It shifted AI from "nice to have" to "part of how we evaluate whether teams are operating at their potential."
|
||||
3. **Discovery through emulation.** The leaderboard isn't just a scoreboard - it's a map. When you see someone at the top, you want to know what they're doing. You look at their skills, their workflows, their apps.
|
||||
|
||||
**If you're not measuring it, you're not managing it.** And if you're not making it visible, you're leaving the most powerful adoption lever on the table.
|
||||
|
||||
This extends to hiring and performance management. We now have an absolute requirement for anyone joining Ramp to be proficient with AI tools. No exceptions. For PM candidates, there's a dedicated interview session: build me a product, show me how you built it, walk me through how it works. It's a full-blown prototype, not a slide deck. If you can't demonstrate that you've internalized these tools, you don't clear the bar.
|
||||
|
||||
## 8\. Remove every constraint between your people and AI.
|
||||
|
||||
The number one way companies kill AI adoption is by treating it like a procurement decision. Budget approvals. IT reviews. Token limits. Connector requests that sit in a queue for weeks. Every one of these is a wall between your people and their "aha" moment.
|
||||
|
||||
We took the opposite approach. Three things we did early that mattered more than almost anything else:
|
||||
|
||||
1. **Treat AI usage as an infinite learning budget.** If you demand ROI on every token before people have even learned to use the tools, you'll never get adoption. We gave people room to explore with the explicit expectation that the payoff comes from the compounding, not from day one.
|
||||
2. **Kill token limits and access restrictions.** No caps on usage. No tiered access based on role. No "you're not an engineer, you don't need this." Everyone gets the same tools, the same models, the same access. The people who surprised us most were the ones we would have never given access to under a traditional approval process.
|
||||
3. **Remove every IT bottleneck on connectors.** An AI agent is only as useful as what it can access. If your people have to file a ticket and wait two weeks for IT to approve a Salesforce connection or a Snowflake integration, they'll lose momentum and never come back. We pre-connected 30+ tools - Salesforce, Snowflake, Gong, Slack, Notion, Google Workspace, Figma - so that when someone opens Glass, everything is already live. One SSO authentication and they're working.
|
||||
|
||||
Here's the cost math that should reframe the conversation for any CFO: we pay our employees a lot of money. Token consumption per employee today isn't even close to double-digit percentages of their salary. But if someone is 2x more productive with AI, you should be willing to spend their entire salary again in tokens. **If you have agents that can do 10x more work than a person, why would you not pay them twice as much as that person?**
|
||||
|
||||
## Watch it compound.
|
||||
|
||||
We didn't start with a better strategy than most companies. We might have had better starting conditions: a culture that rewards speed and initiative, people who try things without waiting for permission, a leadership team that backs bold bets because we know it's good for our customers.
|
||||
|
||||
In lieu of a master plan, we just started. We kept building tools, kept raising the bar, kept investing in data and AI infrastructure, kept creating venues for people to show off. Each track compounded separately. As they reinforced each other, the curve went vertical.
|
||||
|
||||
We are in the very early innings of AI. Your job as a leader is to give your teams superpowers and make them believe in themselves. Everything else follows.
|
||||
|
||||

|
||||
|
||||
The most important lesson is the simplest one: **just get started.**
|
||||
|
||||
We're hiring builders across all functions. If you want to work somewhere that non-engineers ship production code, internal tools have a shelf life of weeks, and nobody thinks that's weird -- come build with us at Ramp.
|
||||
|
||||
Shoutout to [@bleviathan](https://x.com/@bleviathan) for the collaboration on this piece.
|
||||
@@ -0,0 +1,156 @@
|
||||
---
|
||||
title: "How to grep video"
|
||||
source: "https://x.com/amyxst/status/2047345827128164860"
|
||||
author:
|
||||
- "[[@amyxst]]"
|
||||
published: 2026-04-24
|
||||
created: 2026-04-24
|
||||
description: "Notes on context engineering and agent harnesses for video libraries: designing the structured representations to make media legible to LLMs..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
Notes on context engineering and agent harnesses for video libraries: designing the structured representations to make media legible to LLMs. Authored with [@kdrwins](https://x.com/@kdrwins)
|
||||
|
||||
Since we started joining meetings from our computers, video has become the default way that organizations capture what happens at work. We’re at the point now where recording things has become so easy that we’ve created a new problem: we have more videos than we can ever watch.
|
||||
|
||||
Part of the reason LLMs were so transformative was because they gave us a way to synthesize text right when we were drowning in documents. Now we’re at that same point with video and audio, but the synthesis layer hasn’t arrived yet.
|
||||
|
||||
If you work with AI agents for coding, you may have noticed that the good ones are beginning to converge on the Unix design pattern. Read files → grep for patterns → edit in place → use the shell as your orchestrator. Each tool does one thing and does it well. Claude Code does this. LlamaIndex [is building on it](https://www.llamaindex.ai/blog/files-are-all-you-need).
|
||||
|
||||
The pattern is powerful because text has a useful property: text is its own searchable representation. A Python file is simultaneously the program being run and the document being searched. A markdown file is simultaneously the content and the index.
|
||||
|
||||
This property has shaped much of the current thinking around agent design: context windows, tool use, and file-based memory assume that all the material an agent needs can be read and searched in its native form.
|
||||
|
||||
To be fair, this is true for a lot of the information we work with everyday, like code, logs, config files, and documents. But it’s not true for video, images, or similar non-textual data. An MP4 is a binary container of compressed frames and audio packets. There is no grep that finds a concept inside it.
|
||||
|
||||
So if filesystem idioms don’t translate to video, what replaces them?
|
||||
|
||||
## The context window isn't the answer
|
||||
|
||||
Context windows are getting huge. Gemini now offers a 1M token context window that accepts video natively. It seems plausible that, with a big enough context window, you’d be able to work with video the same way you work with text.
|
||||
|
||||
But when you try, you bump up against some limitations pretty quickly. Gemini tokenizes video at roughly 300 tokens per second at high resolution, or about 100 at low resolution.
|
||||
|
||||
A 1M token window fits a small batch of short clips (Gemini caps requests at 10 videos) or a single meeting recording. That's useful for one-off tasks working with individual recordings. But it's not a general solution for working across a library.
|
||||
|
||||
Imagine your sales team did 120 calls last quarter, each about 35 minutes long. That's roughly 70 hours of footage, so somewhere around 25 million tokens at low-res tokenization. Twenty-five times more than fits in a single context window.
|
||||
|
||||
The query a sales leader actually wants to run looks something like:
|
||||
|
||||
“Across all 120 Q3 calls, find every moment where the prospect pushed back on pricing. For each, return the call ID, what the prospect said, the timestamp, who was on the call, and how the rep responded.”
|
||||
|
||||
You can't fit the data in to ask the question.
|
||||
|
||||
Suppose you could fit a whole video library, though. You’d still have two problems:
|
||||
|
||||
- **You can't search inside a context window.** You can only prompt over it, which is not quite the same thing. "Find every mention of pricing across these 20 recordings" is a retrieval problem. You want, targeted results over a known dataset. What you get instead is a best guess re-derived from frames on every run, with no guarantee the next run will agree with the last. That's not good enough when completeness matters.
|
||||
- **The economics are strange.** If the answer to "who was the speaker at 14:32?" lives in a 30-second segment, the structured representation that captures the speaker's name and timestamp might be 100 tokens. Without that structured representation you'd send 50,000 tokens of video context to answer the same question (500× the cost).
|
||||
|
||||
Understanding the video is still a model call (a one-time index doesn't make it deterministic) but you pay that cost up front at extraction time instead of on every query that comes in afterward. The probabilistic cost and the token cost only get paid once and stay paid.
|
||||
|
||||
Context windows will keep growing. But unless the economics radically change, you’ll need to structure and index videos ahead of time to know where to look and avoid starting from scratch every time.
|
||||
|
||||
## Every video is many videos
|
||||
|
||||
When we extract data from video today, we typically just pull the transcript, which does give us a lot to work with.
|
||||
|
||||
But when you introduce the possibility of querying all types of data within a video, a 30-minute recording turns out to be deceptively dense with information:
|
||||
|
||||
- Ask for a meeting summary and you get speaker timelines, discussion topics, action items, key decisions. Normal stuff.
|
||||
- But ask for sales coaching from the exact same recording and you get something entirely different: talk-to-listen ratios, filler word frequency, how objections were handled, energy and pace through the call.
|
||||
- Ask for customer sentiment and you’ll get new information again: an analysis of tone shifts when the conversation turned to pricing, facial expressions during the demo, and the beat of silence before an answer. The signs that actually tell you whether a deal is alive usually don't make it into the transcript.
|
||||
|
||||
Same video. Same binary blob on disk. Completely different knowledge, determined entirely by what you asked for.
|
||||
|
||||
Underneath any of these questions, the same baseline gets cached once per segment:
|
||||
|
||||
```json
|
||||
// Baseline — cached for every segment of every video
|
||||
{
|
||||
"call_id": "q3-acme-2025-09-14",
|
||||
"start_time": "00:24:15",
|
||||
"end_time": "00:24:23",
|
||||
"transcript": "Yeah, that pricing makes sense for us.",
|
||||
"speakers": ["Jamie Park"],
|
||||
"visual_description": "Prospect on right, briefly looks down, glances back at camera. Slide titled 'Enterprise pricing' visible on left.",
|
||||
"on_screen_text": ["Enterprise pricing", "$2,400/mo"],
|
||||
"entities": ["Enterprise pricing"]
|
||||
}
|
||||
```
|
||||
|
||||
Prompt-specific extractions layer on top. Earlier in the same call, here's what a coaching query adds:
|
||||
|
||||
```json
|
||||
{
|
||||
"call_id": "q3-acme-2025-09-14",
|
||||
"start_time": "00:15:24",
|
||||
"end_time": "00:16:02",
|
||||
"objection": {
|
||||
"raised_by": "Jamie Park",
|
||||
"topic": "implementation timeline",
|
||||
"rep_response_summary": "Offered a 2-week pilot",
|
||||
"outcome": "addressed"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
And here's what a sentiment query adds for the segment we started with:
|
||||
|
||||
```json
|
||||
{
|
||||
"call_id": "q3-acme-2025-09-14",
|
||||
"start_time": "00:24:15",
|
||||
"end_time": "00:24:23",
|
||||
"prosody": {"energy": "low", "pace": "slow", "pitch_contour": "rising"},
|
||||
"facial": {"expression": "tight_smile", "eye_contact": "broken"},
|
||||
"sentiment": {"direction": "negative", "confidence": 0.78}
|
||||
}
|
||||
```
|
||||
|
||||
The transcript said the prospect agreed. The prosody and facial data disagree. No single modality catches this on its own; aligned on a shared timeline, they do. The original sales-leader query becomes a trivial filter over the coaching schema, joined to the sentiment schema. No need to rewatch or re-prompt the raw video.
|
||||
|
||||
In video, there's the speech transcript, obviously, but also speaker identity, visual scene descriptions like on-screen text, slides and product walkthroughs, entity references, chapter boundaries, laughter, cross-talk, camera shot boundaries, tone shifts, and more.
|
||||
|
||||
Each of these is a different representation of the same source material. None of them is "the" representation. All of them are lossy. And all of them are useful, for different tasks and at different times.
|
||||
|
||||
The job then becomes deciding which projections to compute, how to align them temporally, and how to make the results composable and searchable.
|
||||
|
||||
This is context engineering for video libraries: designing structured intermediate representations that make opaque media legible to an LLM.
|
||||
|
||||
We studied this question [in our research on aligned video captions](https://dl.acm.org/doi/10.1145/3701716.3716890): time-aligned compact representations that combine signals across modalities (speech, visual, textual) consistently outperform both single-modality approaches and context window stuffing, across 1.8 million clips.
|
||||
|
||||
The representation layer is what gives an agent something like grep-level access to video. It does this by creating the searchable object that the original format never was.
|
||||
|
||||
## Making grep work for video
|
||||
|
||||
To create a grep-like pattern for video, you need to run the process in reverse.
|
||||
|
||||

|
||||
|
||||
For text, you search first and read second. grep finds the line and cat shows the file. For video, the searchable form doesn't exist yet. So you go the other direction: describe first, cache the result, then search.
|
||||
|
||||
This means a video agent needs three tiers of lookup:
|
||||
|
||||
- **Local keyword search over cached enrichments.** Instant and free. This is the equivalent of grep over a file you've already written. Against the Q3 collection, a query like objections.topic = "pricing" returns every relevant moment across all 120 calls, with citations.
|
||||
- **Semantic search across an indexed collection**. A question like "find moments where the prospect hesitated before answering" can't be answered by keyword matching. It needs embeddings that map a text query to the relevant spans of time across your enriched representations, matching on meaning rather than words.
|
||||
- **Full re-analysis**: Send the video back through the enrichment pipeline. Expensive, and a last resort for when existing cached representations don't contain what you need.
|
||||
|
||||
The enrichment cache is the key primitive. It needs prompt-aware keys. The same video processed with different extraction schemas produces different cache entries that coexist.
|
||||
|
||||
And it needs multiple output fidelities: a compact representation (~1–4KB per video) for routing and quick lookups, and a full structured output (50K+ tokens) for deep analysis.
|
||||
|
||||
This architecture also gets cheaper over time. Each interaction enriches the cache, which makes the next query faster and less expensive.
|
||||
|
||||
It solves the inefficiency problem of the context window approach, where every question starts from scratch, with the full cost of the raw media.
|
||||
|
||||
## The other 90% of our information
|
||||
|
||||
Translating every type of information encoded in a video into structured data LLMs can understand opens up a class of work transcripts can’t support.
|
||||
|
||||
Pulling the transcripts from a sales call helps an account executive review the topics and action items they covered with a prospect. But with video context engineering, a sales leader working with the same Q3 collection could analyze a quarter’s worth of calls and generate a coaching plan for their team. They could query for and extract talk-to-listen ratios, filler-word frequency, objections and their responses, energy levels, pricing negotiations, and phrases that progressed deals.
|
||||
|
||||
This is just one example. As with LLMs, I think we’ll discover hundreds more as we get accustomed to doing work across huge libraries of video. We’re building in this space at [Cloudglue](https://cloudglue.dev/) now. I’ll share more soon on what video context engineering makes possible.
|
||||
|
||||
**If you want to read this on the Cloudglue blog, and to follow for more technical pieces from our team:** [https://blog.cloudglue.dev/how-to-grep-video/](https://blog.cloudglue.dev/how-to-grep-video/)
|
||||
@@ -0,0 +1,290 @@
|
||||
---
|
||||
title: "I built 500+ bots and made 6 figs on it (real blueprint + my mistakes)"
|
||||
source: "https://x.com/0x_Punisher/status/2045844943160082728"
|
||||
author:
|
||||
- "[[@0x_Punisher]]"
|
||||
published: 2026-04-13
|
||||
created: 2026-04-26
|
||||
description: "Everyone who trades on Polymarket goes through the same painful loop:You build a bot -> it looks perfect in backtests -> you deploy it -> it..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
Everyone who trades on Polymarket goes through the same painful loop:
|
||||
|
||||
You build a bot -> it looks perfect in backtests -> you deploy it -> it starts bleeding
|
||||
|
||||
So you tweak parameters, add filters, maybe even rebuild the whole thing and somehow it gets worse.
|
||||
|
||||
After repeating this enough times, most people quit and assume the edge doesn’t exist.
|
||||
|
||||
That’s the wrong conclusion.
|
||||
|
||||
The truth is much simpler:
|
||||
|
||||
Most strategies already work, but they are deployed in the wrong conditions, executed incorrectly, or destroyed by things the backtest never modeled.
|
||||
|
||||
After running hundreds of bots, patterns start repeating.
|
||||
|
||||
99% of my bots are worthless.
|
||||
|
||||
But they gave me the understanding on how to create the 1% that prints for me daily.
|
||||
|
||||
My best case already made over [$8k](https://x.com/search?q=%248k&src=cashtag_click) in less than a month.
|
||||
|
||||
And unlike other KOLs, I am not hiding my wallets.
|
||||
|
||||
Both fails and winnings are public and free for everyone.
|
||||
|
||||
**Best case:** <[https://polymarket.com/@pbot-6?via=punisher](https://polymarket.com/@pbot-6?via=punisher)\>
|
||||
|
||||

|
||||
|
||||
And you can build the same one if you eliminate all the mistakes.
|
||||
|
||||
There is a recipe for it.
|
||||
|
||||
This is that recipe.
|
||||
|
||||
## Regime filtering (and why your bot isn’t broken)
|
||||
|
||||
One of the fastest ways to turn a losing system into a profitable one is not changing the logic, but changing when it runs.
|
||||
|
||||
Markets on Polymarket behave very differently depending on who is active.
|
||||
|
||||
During weekdays, you typically get more structured flow (traders, bots, people reacting fast).
|
||||
|
||||
On weekends, the behavior shifts toward slower, less disciplined participants.
|
||||
|
||||
That changes volatility, reaction speed, and how price overshoots.
|
||||
|
||||

|
||||
|
||||
If you take almost any strategy and split its results by weekday vs weekend, you’ll see a clear pattern:
|
||||
|
||||
One side makes money, the other destroys it.
|
||||
|
||||
Instead of endlessly tuning indicators, you can apply a simple filter at the execution level.
|
||||
|
||||
For example, run mean-reversion logic only on weekends where overreactions are more common.
|
||||
|
||||
And avoid it during weekdays where trends are cleaner and faster.
|
||||
|
||||
This is not optimization, but alignment.
|
||||
|
||||
You’re matching your bot to the environment where its assumptions actually hold.
|
||||
|
||||
## Time-of-day is a hidden edge most people ignore
|
||||
|
||||
Beyond days, the hour of execution matters just as much.
|
||||
|
||||
Liquidity, volatility, and behavior shift depending on which regions are active.
|
||||
|
||||
When US markets are active, reaction times are faster and inefficiencies close quickly.
|
||||
|
||||
During low-activity hours, especially when Asia dominates, markets tend to be thinner and less predictable.
|
||||
|
||||

|
||||
|
||||
Many strategies fail not because they are wrong, but because they are exposed to hours where their assumptions break.
|
||||
|
||||
A breakout system might work perfectly during high-volume periods but fail completely in slow conditions where price drifts without conviction.
|
||||
|
||||
The practical fix is to gate your bot by time.
|
||||
|
||||
Instead of letting it trade continuously, restrict it to specific windows where you have evidence it performs well.
|
||||
|
||||
This can be as simple as allowing execution only during certain UTC ranges.
|
||||
|
||||
Once you do this, you’ll notice something interesting: performance stabilizes without touching the strategy itself.
|
||||
|
||||
You didn’t fix the bot, you stopped forcing it into environments where it never had an edge.
|
||||
|
||||
## Inverting losing strategies (most people miss this completely)
|
||||
|
||||
A consistent losing strategy is not useless.
|
||||
|
||||
It is often misaligned.
|
||||
|
||||
If your bot loses randomly, it’s noise.
|
||||
|
||||
But if it loses consistently under the same conditions, that means it is systematically taking the wrong side.
|
||||
|
||||

|
||||
|
||||
For example, a mean-reversion bot that keeps buying dips and getting run over is not bad.
|
||||
|
||||
It is simply operating in a trending regime.
|
||||
|
||||
The signal itself is still meaningful, it just points in the wrong direction.
|
||||
|
||||
If your data shows a 42% win rate, the opposite side is mathematically close to 58%.
|
||||
|
||||
That’s already profitable territory in many Polymarket setups.
|
||||
|
||||
The key is to verify that the losses are structured, not random.
|
||||
|
||||
If they are, flipping the logic can turn a failing system into a working one without changing anything else.
|
||||
|
||||
This is one of the fastest ways to recover dead strategies and almost nobody uses it.
|
||||
|
||||
## Loss clustering (or why one bad period kills everything)
|
||||
|
||||
Losses in these markets are not evenly distributed over time.
|
||||
|
||||
They tend to cluster.
|
||||
|
||||
A bot might perform normally for hours, then suddenly hit a sequence of losses in a short period.
|
||||
|
||||
These clusters often happen during regime shifts, sudden volatility changes, or when the market temporarily breaks the assumptions your strategy relies on.
|
||||
|
||||
If your bot trades every window without any protection, it will fully absorb these clusters.
|
||||
|
||||
That’s what destroys most equity curves.
|
||||
|
||||
Here's an example that happened lately:
|
||||
|
||||
> 4月13日
|
||||
>
|
||||
> FOR 5/15 MINUTE BOTS DEVELOPERS: Polymarket has serious bugs right now and most traders don't know why their fills look wrong. If your bot stopped performing these last 3 days, it's not you. This is a platform wide problem affecting everyone. Here is everything that's
|
||||
|
||||
A simple but effective solution is to introduce conditional pauses.
|
||||
|
||||
For example, after two consecutive losses, the bot can skip the next few windows instead of continuing blindly.
|
||||
|
||||
This doesn’t eliminate losses entirely, but it reduces exposure during unstable conditions.
|
||||
|
||||
Over time, this dramatically improves survival.
|
||||
|
||||
You’re not trying to predict when things go wrong.
|
||||
|
||||
You’re reacting quickly when they already started going wrong.
|
||||
|
||||
## Panic sales and end-of-window behavior
|
||||
|
||||
One of the more technical edges comes from understanding how traders behave near the end of a window.
|
||||
|
||||
There is a point in every contract where the probability of reversal becomes extremely low.
|
||||
|
||||
However, participants still exit positions early.
|
||||
|
||||
Either to lock in profit, avoid perceived risk, or simply due to bad execution logic.
|
||||
|
||||
This creates moments where price temporarily deviates from its true value, especially when using FAK (fill-and-kill) orders that prioritize execution over price.
|
||||
|
||||
**Example:**
|
||||
|
||||
> 4月19日
|
||||
>
|
||||
> Locked another $900 passively today. All from sniping 99% odds markets that are resolved in fact. My wallet to track: <https://polymarket.com/@0x13f0bcec1e2e60ec9acc3bee4d2da2fe9694a50f-1774334442364?via=punisher…> Full guide attached. All info is free and public. And some people are still ignoring this edge...
|
||||
|
||||
**A well-designed bot can take advantage of this by:**
|
||||
|
||||
\> identifying when the outcome is effectively decided
|
||||
|
||||
\> monitoring aggressive sell pressure
|
||||
|
||||
\> capturing discounted entries caused by panic exits
|
||||
|
||||
This requires combining time remaining with price distance (bps) to estimate whether a reversal is realistically possible.
|
||||
|
||||
If not, any discount becomes an opportunity.
|
||||
|
||||
This is not about prediction, it’s about recognizing when the market is mispricing something that is already resolved in practice.
|
||||
|
||||
## Latency as the invisible killer of most bots
|
||||
|
||||
Almost every backtest assumes perfect execution.
|
||||
|
||||
Real markets do not.
|
||||
|
||||
If your bot experiences even small delays (entering late, missing fills, or getting worse prices), the entire expected value can disappear.
|
||||
|
||||
This is especially critical in short-duration markets like 5m or 15m crypto contracts, where timing is everything.
|
||||
|
||||

|
||||
|
||||
**Common symptoms of latency issues include:**
|
||||
|
||||
\> orders sitting in the book without fills
|
||||
|
||||
\> getting filled only after price moves
|
||||
|
||||
\> consistent slippage compared to expected entries
|
||||
|
||||
The fix is not in strategy, it’s in infrastructure.
|
||||
|
||||
You need faster RPC endpoints, optimized order submission, and minimal delay between signal and execution.
|
||||
|
||||
In many cases, improving latency alone turns an unprofitable system into a profitable one.
|
||||
|
||||
If your live results don’t match your backtest, assume execution is the problem until proven otherwise.
|
||||
|
||||
## Simplicity and deployment across markets
|
||||
|
||||
Most people overcomplicate their bots.
|
||||
|
||||
They add multiple indicators, combine strategies, introduce hedging layers, and end up with something that is hard to debug and slow to execute.
|
||||
|
||||
In reality, the best-performing bots are usually simple.
|
||||
|
||||
One or two signals, clearly defined conditions, and clean execution.
|
||||
|
||||
What actually scales is not complexity, but deployment.
|
||||
|
||||
Instead of building one perfect bot, you take a simple working idea and apply it across multiple markets:
|
||||
|
||||
BTC / ETH / SOL / XRP / DOGE / HYPE
|
||||
|
||||

|
||||
|
||||
Each behaves slightly differently.
|
||||
|
||||
Some are more volatile, some more efficient.
|
||||
|
||||
A strategy that struggles on BTC might perform well on a more chaotic asset.
|
||||
|
||||
By spreading your logic across multiple markets and timeframes, you increase your chances of finding environments where it naturally works.
|
||||
|
||||
## The real shift from strategy to system
|
||||
|
||||
Most traders on Polymarket are stuck searching for the perfect setup.
|
||||
|
||||
That’s not where the edge is.
|
||||
|
||||
**The edge comes from understanding that:**
|
||||
|
||||
\> strategies fail in specific conditions
|
||||
|
||||
\> losses are not random
|
||||
|
||||
\> execution matters as much as logic
|
||||
|
||||
Once you start thinking in those terms, everything changes.
|
||||
|
||||
You stop rebuilding from scratch every time something fails.
|
||||
|
||||
You start adjusting, filtering, and improving what already exists.
|
||||
|
||||
And eventually, instead of chasing a perfect bot, you end up with multiple systems that each work in their own conditions.
|
||||
|
||||
That’s how people go from one broken strategy to running dozens that quietly print in the background.
|
||||
|
||||
Hope this article will help you.
|
||||
|
||||
Follow me for more alpha on prediction market bots.
|
||||
|
||||
Also join my small channel where I share my every move live.
|
||||
|
||||
**Link:** [https://t.me/+zga0eT2p-10yZjBk](https://t.me/+zga0eT2p-10yZjBk)
|
||||
|
||||

|
||||
|
||||
This is the place where we connect and help each other.
|
||||
|
||||
Make sure to not miss my next guide.
|
||||
|
||||
Already preparing something huge for you.
|
||||
|
||||
Good luck!
|
||||
@@ -0,0 +1,226 @@
|
||||
---
|
||||
title: "I want to master GPT images 2.0."
|
||||
source: "https://x.com/hooeem/status/2047417677350650212"
|
||||
author:
|
||||
- "[[@hooeem]]"
|
||||
published: 2026-04-22
|
||||
created: 2026-04-24
|
||||
description: "I have combined every AI nerd, designer nerd, prompt nerd, and GPT image nerds advice into one master guide on GPT IMAGES 2.0 to take you fr..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
I have combined every AI nerd, designer nerd, prompt nerd, and GPT image nerds advice into one master guide on GPT IMAGES 2.0 to take you from a beginner to a master.
|
||||
|
||||
storyboards. character sheets. product mockups. social campaigns. ui concepts. infographics. more.
|
||||
|
||||
it is ALL possible using gpt images 2.0.
|
||||
|
||||
beginners will treat this like a better midjourney "make me a cool comic character"
|
||||
|
||||
the pros will build workflows and create reusable anchors.
|
||||
|
||||
**let me show you where gpt images 2.0 actually dominates at:**
|
||||
|
||||
**1: visual storytelling**
|
||||
|
||||
openai's own examples show manga sequences, storyboard breakdowns, comic strips with proper panel pacing.
|
||||
|
||||
**this obliterates traditional workflows:**
|
||||
|
||||
> anime storyboard pages with character continuity social content carousels that convert shot-by-shot video breakdowns comic strips with readable pacing
|
||||
|
||||
> 4月22日
|
||||
>
|
||||
> It’s getting better, faster and easier. Openai chatgpt Image 2.0 makes the storyboard: „Create a 3x3 storyboard Grid: Action Fight Scene in Gladiators Arena” ..then have the video created with Seedance 2.0: „Create the story, only music, without dialogue“
|
||||
|
||||
pros script it like directors.
|
||||
|
||||
**2: character systems**
|
||||
|
||||
the breakthrough: reusable character anchors that don't drift between generations.
|
||||
|
||||
**real applications:**
|
||||
|
||||
> youtube channel mascots product characters that scale across campaigns game character development sheets comic protagonist references
|
||||
|
||||
you can make your character (or give it one you have) and utilise it in different scenes like this:
|
||||
|
||||

|
||||
|
||||
**3: campaigns**
|
||||
|
||||
openai in their live demo showed korean hospitality brochures, editorial posters, graphic spreads with typography control.
|
||||
|
||||
> product launch campaigns brand asset libraries social campaign visuals presentation materials
|
||||
|
||||
**you could generate an entire rebrand concept in 90 minutes.** 12 poster variations, 8 social assets, 3 packaging concepts.
|
||||
|
||||
traditional cost: £8,000 gpt images 2.0 cost: NOT THAT...
|
||||
|
||||
look at this:
|
||||
|
||||
> 4月22日
|
||||
>
|
||||
> I built a GPT 2 workflow that turns one image into 20 viral ads GPT image 2 is the most powerful image model out there And you can use it to scale your ads campaign with Arcads workflow Comment Arcads to get the workflow now
|
||||
|
||||
**4: educational content that works**
|
||||
|
||||
academic posters, proof visualisations, process diagrams. the cookbook recommends treating these like instructional design briefs.
|
||||
|
||||
**output examples:**
|
||||
|
||||
> step-by-step explainers labeled process charts classroom teaching materials visual instruction guides
|
||||
|
||||
**5: product development**
|
||||
|
||||
packaging concepts, virtual try-ons, product photography, collectible designs.
|
||||
|
||||
**approach difference:**
|
||||
|
||||
amateur: "make a product photo" professional: "create premium product hero shot with luxury styling, studio lighting, white background, product positioned at 3/4 angle"
|
||||
|
||||
**ANYWAY... those were some examples, but how should you prompt gpt images 2.0?**
|
||||
|
||||
**well., let's do that.**
|
||||
|
||||
**1: universal prompt**
|
||||
|
||||
```markdown
|
||||
Goal: [specific deliverable type]
|
||||
Deliverable: [poster/storyboard/character sheet/mockup]
|
||||
Scene: [environment and context]
|
||||
Subject: [main focus elements]
|
||||
Style: [photorealistic/editorial/anime/flat design]
|
||||
Composition: [framing/layout/focal points]
|
||||
Text: [exact words in quotes]
|
||||
Constraints: [what stays fixed/what changes/what's forbidden]
|
||||
```
|
||||
|
||||
this template forces clarity.
|
||||
|
||||
**2: storyboard mastery prompt**
|
||||
|
||||
```markdown
|
||||
Goal: Create 6-panel storyboard page
|
||||
Story beats:
|
||||
Panel 1: [opening shot - wide establishing]
|
||||
Panel 2: [character reaction - medium shot]
|
||||
Panel 3: [action or discovery - dynamic angle]
|
||||
Panel 4: [emotional close-up]
|
||||
Panel 5: [turning point - dramatic moment]
|
||||
Panel 6: [resolution - final reveal]
|
||||
|
||||
Character continuity: Same face, hair, outfit, proportions throughout
|
||||
Style: Clean anime storyboard with professional panel layout
|
||||
Constraints: One clear action per panel, minimal dialogue, no background clutter
|
||||
```
|
||||
|
||||
result: storytelling that actually flows.
|
||||
|
||||
**3: character system**
|
||||
|
||||
```markdown
|
||||
Goal: Create master character reference sheet
|
||||
Character: [detailed physical description - height, build, distinctive features]
|
||||
Include: Front view, 3/4 view, side view, expression variations, key poses
|
||||
Style: [anime/realistic/cartoon - specify consistency level]
|
||||
Layout: Professional reference sheet with clear labels
|
||||
Constraints: Consistent proportions, no costume variations, clean background
|
||||
```
|
||||
|
||||
(just upload him), and for **follow-up scenes:** reference the master sheet. change only pose/setting/lighting.
|
||||
|
||||
**4: campaigns**
|
||||
|
||||
```markdown
|
||||
Goal: Create [launch poster/social asset/product mockup]
|
||||
Audience: [specific target demographic]
|
||||
Message: [core value proposition]
|
||||
Mood: [luxury/energetic/trustworthy/innovative]
|
||||
Text (EXACT): "[headline]" and "[subheading]"
|
||||
Typography: [modern sans-serif/elegant serif/bold display - specify hierarchy]
|
||||
Constraints: Brand colours only, no extra text, strong visual hierarchy
|
||||
```
|
||||
|
||||
**critical detail: put exact copy in quotes.** demand verbatim rendering.
|
||||
|
||||
**5: advanced tactics**
|
||||
|
||||
the continuity system
|
||||
|
||||
community-tested workflow for character consistency:
|
||||
|
||||
1. **create master description** - appearance only, no scene details
|
||||
2. **name your character** - "alex" or "maya" for reference
|
||||
3. **reuse core details** - repeat key appearance elements in follow-ups
|
||||
4. **separate identity from action** - change pose/setting, preserve character
|
||||
|
||||
**example master description:** "maya, 28, athletic build, shoulder-length dark hair with blue highlights, distinctive green eyes, small scar above left eyebrow, typically wears fitted black jacket"
|
||||
|
||||
**follow-up usage:** "maya \[from master description\] sitting at cafe table, laptop open, morning lighting, 3/4 view"
|
||||
|
||||
the editing protocol
|
||||
|
||||
**always specify:**
|
||||
|
||||
- change only: \[specific element\]
|
||||
- preserve: \[everything else - list explicitly\]
|
||||
- keep same: \[lighting/pose/background/colours\]
|
||||
|
||||
**example:** "change only the laptop screen to show financial charts. preserve maya's pose, facial expression, lighting, background, clothing. keep everything else identical."
|
||||
|
||||
quality scaling strategy
|
||||
|
||||
**low quality:** drafts, exploration, concept development **medium quality:** social media assets, presentations, internal use**high quality:** print materials, final deliverables, client work.
|
||||
|
||||
**NOW THEN... what about common failures? well here's there instant fixes:**
|
||||
|
||||
problem: character drifts between images
|
||||
|
||||
**fix:** character anchor system. master description. repeat core details.
|
||||
|
||||
problem: text appears but isn't exact
|
||||
|
||||
**fix:** shorten text, use quotes, specify typography, increase quality setting.
|
||||
|
||||
problem: edits change too much
|
||||
|
||||
**fix:** "change only X" protocol. list what must stay identical.
|
||||
|
||||
problem: output looks generic
|
||||
|
||||
**fix:** specific materials, lighting, framing. avoid "make it look good."
|
||||
|
||||
problem: layouts feel cluttered
|
||||
|
||||
**fix:** write like design brief. specify hierarchy, spacing, typography rules.
|
||||
|
||||
the mindset that wins
|
||||
|
||||
**beginners ask:** "what prompt should i write?"
|
||||
|
||||
**professionals ask:** "what workflow builds the deliverable i need?"
|
||||
|
||||
**the difference is systems thinking.**
|
||||
|
||||
pros use gpt images 2.0 as:
|
||||
|
||||
> storyboard production engine character development tool campaign asset generator localisation multiplier concept development accelerator
|
||||
|
||||
**they don't prompt better. they build better systems.**
|
||||
|
||||
here's what matters most
|
||||
|
||||
stop thinking "image generator."
|
||||
|
||||
start thinking "visual production system."
|
||||
|
||||
**the real power:** turning ideas into deliverable assets. storyboards that tell stories. character sheets that scale. campaigns that convert. mockups that sell. content that works.
|
||||
|
||||
**treat it like a professional collaborator with clear briefs, not a creative slot machine.**
|
||||
|
||||
**your next move:** pick one deliverable type. storyboards, character sheets, or campaign assets.
|
||||
|
||||
master that workflow first. let me know what you're going to try first!
|
||||
+194
@@ -0,0 +1,194 @@
|
||||
---
|
||||
title: "Knowing N8N Is Not the Skill. Knowing Which 20% of Your Work Actually Deserves to Be Automated Is."
|
||||
source: "https://x.com/cyrilXBT/status/2048050913428795878"
|
||||
author:
|
||||
- "[[@cyrilXBT]]"
|
||||
published: 2026-04-25
|
||||
created: 2026-04-26
|
||||
description: "I watched a founder spend an entire weekend building an N8N workflow to auto-sort his inbox.12 hours of work.Beautiful system. Custom tags. ..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
I watched a founder spend an entire weekend building an N8N workflow to auto-sort his inbox.
|
||||
|
||||
12 hours of work.
|
||||
|
||||
Beautiful system. Custom tags. Automatic labels. Priority scoring.
|
||||
|
||||
His inbox was already taking him 8 minutes a day to manage manually.
|
||||
|
||||
He built a 12-hour solution for an 8-minute problem.
|
||||
|
||||
And he felt productive the entire time he was doing it.
|
||||
|
||||
This is the automation trap. And almost every builder falls into it.
|
||||
|
||||
## The Trap Nobody Warns You About
|
||||
|
||||
Learning automation tools feels like work.
|
||||
|
||||
Building workflows feels like progress.
|
||||
|
||||
Watching your systems run feels like leverage.
|
||||
|
||||
None of that feeling is wrong. The problem is that it has nothing to do with whether the thing you automated actually matters.
|
||||
|
||||
Most people approach automation backwards.
|
||||
|
||||
They learn the tool first. Then they look for things to automate. Then they build whatever feels interesting or satisfying to build.
|
||||
|
||||
The result is a collection of workflows that run perfectly and move nothing.
|
||||
|
||||
Your email is sorted automatically. Your Notion database updates itself. Your social media posts schedule on their own.
|
||||
|
||||
And your revenue is exactly where it was 6 months ago.
|
||||
|
||||
Because none of those things were the bottleneck.
|
||||
|
||||
## The 20% That Actually Costs You Everything
|
||||
|
||||
Every week you do a set of tasks that repeat.
|
||||
|
||||
Most of them feel important because they take time.
|
||||
|
||||
Almost none of them are actually responsible for your results.
|
||||
|
||||
The 80/20 principle applied to your work looks like this:
|
||||
|
||||
20% of your manual tasks are directly responsible for 80% of your output, revenue, or growth.
|
||||
|
||||
The other 80% of your tasks create the illusion of productivity without moving the number that matters.
|
||||
|
||||
The automation trap is spending 10 hours building a workflow for a task in that 80%.
|
||||
|
||||
The automation opportunity is finding the tasks in that 20% and eliminating every second of friction from them.
|
||||
|
||||
The difference between the two is not technical skill.
|
||||
|
||||
It is the audit you do before you open any automation tool.
|
||||
|
||||
## The Audit That Changes Everything
|
||||
|
||||
Before you touch N8N, Claude, Zapier, or any workflow builder — do this first.
|
||||
|
||||
Open a blank document. Write down every task you did last week that repeated at least once.
|
||||
|
||||
Not just the tasks you planned. Every task. The ones you did automatically without thinking about them. The interruptions. The things you handled without adding to your to-do list.
|
||||
|
||||
Now label each one with one of three tags:
|
||||
|
||||
**CORE** — This task directly creates the output that generates my revenue, growth, or results. Only I can do this at the quality it needs to be done. Examples: writing content, sales conversations, product decisions, client work.
|
||||
|
||||
**SUPPORT** — This task is necessary for the business to function but does not directly create results. It could be done by someone else or something else without losing quality. Examples: scheduling, data entry, formatting, sending follow-up emails, updating records.
|
||||
|
||||
**NOISE** — This task exists because of a broken system, a bad habit, or a process that should not exist at all. Examples: re-explaining context because nothing is documented, fixing errors from a manual process that should be automated, answering the same question repeatedly.
|
||||
|
||||
The rule is simple:
|
||||
|
||||
Protect CORE work at all costs. Never automate it. Never delegate it. Guard the hours it lives in.
|
||||
|
||||
Automate SUPPORT work. This is where N8N, Claude, and every automation tool belongs.
|
||||
|
||||
Eliminate NOISE entirely. Do not automate it. Kill it.
|
||||
|
||||
Most people automate SUPPORT work that barely touches their results and protect NOISE work because it feels urgent.
|
||||
|
||||
The audit makes the distinction visible for the first time.
|
||||
|
||||
## The ROI Test Every Automation Idea Has to Pass
|
||||
|
||||
Before you build any workflow, run this calculation:
|
||||
|
||||
How many hours per month does this task currently cost me?
|
||||
|
||||
If the answer is under 2 hours per month, stop.
|
||||
|
||||
The time to build, test, debug, and maintain the automation will cost you more than the task itself over the next 12 months.
|
||||
|
||||
Not every problem that can be automated should be automated.
|
||||
|
||||
The ones worth building are the ones that cost you 5+ hours a month, repeat in a predictable pattern, and sit in the SUPPORT or NOISE category.
|
||||
|
||||
Here is the filter in Claude prompt form:
|
||||
|
||||
I want to decide whether to automate this task: \[DESCRIBE TASK\]. Tell me: 1. What category does this fall into: revenue-generating, operational support, or noise? 2. What is the realistic monthly time cost if I keep doing it manually? 3. What is the estimated build and maintenance time for an automation? 4. Does the ROI justify building it? 5. Should I automate it, delegate it, or eliminate it entirely?
|
||||
|
||||
Run every automation idea through this before you spend a single hour building.
|
||||
|
||||
## The Two Lists That Protect Your Core Work
|
||||
|
||||
The most dangerous thing about the automation era is that the best tools make it equally easy to automate things that matter and things that do not.
|
||||
|
||||
N8N does not know the difference between a workflow that saves you 10 hours of admin a month and a workflow that saves you 20 minutes while giving you the feeling of doing something important.
|
||||
|
||||
You have to know the difference.
|
||||
|
||||
The system that protects you is two lists maintained every week:
|
||||
|
||||
**List 1: Untouchable Core Work**
|
||||
|
||||
Write down the 3 to 5 tasks that are directly responsible for your results. The ones only you can do at the level they need to be done.
|
||||
|
||||
These get the best hours of your day. They never get delegated. They never get automated. They get protected.
|
||||
|
||||
**List 2: Everything Else**
|
||||
|
||||
Every other repeating task goes here. You review this list monthly and ask one question for each item: automate, delegate, or eliminate?
|
||||
|
||||
Nothing on List 2 gets your best hours. Nothing on List 2 gets protected.
|
||||
|
||||
The goal is not to have a perfectly automated business.
|
||||
|
||||
The goal is to spend as many hours as possible on List 1 and as few as possible on List 2.
|
||||
|
||||
Automation is just the fastest way to clear List 2.
|
||||
|
||||
## The Stack That Makes This Work
|
||||
|
||||
Once you have done the audit and identified what actually deserves to be automated, the stack is simple:
|
||||
|
||||
Claude for decision-making, content creation, and any task that requires judgment.
|
||||
|
||||
N8N for connecting tools and building repeating workflows that have clear triggers and clear outputs.
|
||||
|
||||
Supabase or Airtable for storing state so your automations remember what happened last time.
|
||||
|
||||
The combination of these three handles 90% of what most operators actually need to automate.
|
||||
|
||||
Here is the workflow design prompt that forces you to think about this correctly before you build:
|
||||
|
||||
I want to automate: \[DESCRIBE TASK\]. Before designing the workflow, tell me: 1. Is this CORE work, SUPPORT work, or NOISE? 2. What is the monthly time cost if I keep doing it manually? 3. What is the trigger for this workflow? 4. What is the action? 5. What is the output and how do I verify it worked? 6. What breaks this workflow and how do I handle it? 7. Should I build this now or is there something higher ROI to build first? Only design the workflow if the answers justify building it.
|
||||
|
||||
The extra step of answering these questions before touching N8N will save you more time than any individual automation you build.
|
||||
|
||||
## What Actually Separates the Operators Who Win
|
||||
|
||||
The builders who compound their results with automation are not the ones with the most complex workflows.
|
||||
|
||||
They are the ones who are ruthlessly honest about which work moves their number and which work just fills their day.
|
||||
|
||||
They do less. They automate less. But everything they do and everything they automate sits inside the 20% that actually matters.
|
||||
|
||||
The 80% of busy work runs itself or does not run at all.
|
||||
|
||||
Their calendar looks empty compared to the founders who have automated everything and are still stuck at the same revenue.
|
||||
|
||||
The automation trap convinces you that doing more, automating more, and shipping more workflows is the path forward.
|
||||
|
||||
The audit shows you that the path forward is almost always narrower than you think.
|
||||
|
||||
Find the 20%.
|
||||
|
||||
Protect it.
|
||||
|
||||
Automate everything else into silence.
|
||||
|
||||
The builders who figure this out before everyone else are the ones who will look back at 2025 and 2026 as the years they separated themselves permanently.
|
||||
|
||||
Bookmark this. Come back when you are about to spend a weekend building a workflow.
|
||||
|
||||
Run the audit first.
|
||||
|
||||
Follow [@cyrilXBT](https://x.com/@cyrilXBT) for more systems that compound over time.
|
||||
@@ -0,0 +1,138 @@
|
||||
---
|
||||
title: "Math Over Gambling: How Quants Make Millions on Sports Betting"
|
||||
source: "https://x.com/goatyishere/status/2044003377474867481"
|
||||
author:
|
||||
- "[[@goatyishere]]"
|
||||
published: 2026-04-14
|
||||
created: 2026-04-26
|
||||
description: "90% of people bet on sports like it’s a casino, and they loseThe other 10% are playing a completely different game.They don’t guess, they ca..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
90% of people bet on sports like it’s a casino, and they lose
|
||||
|
||||
The other 10% are playing a completely different game.They don’t guess, they calculate
|
||||
|
||||
Probability. Edge. Expected Value
|
||||
|
||||
That’s how millions are made
|
||||
|
||||
One of the people breaking this down is Alex Monahan (Stanford, ex-trader at Susquehanna International Group, founder of OddsJam, sold for [$160M](https://x.com/search?q=%24160M&src=cashtag_click))
|
||||
|
||||
His lecture isn’t about sports. It’s about decision-making through math
|
||||
|
||||
## The Core Idea
|
||||
|
||||
Sports betting = true probability vs implied probability
|
||||
|
||||
If you don’t understand the difference, you’re paying the market
|
||||
|
||||
## 1/ The Book Always Wins
|
||||
|
||||
Odds are never “fair”.
|
||||
|
||||
Sportsbooks bake in **vig** (their edge)
|
||||
|
||||
Example: 50/50 event → -110 / -110
|
||||
|
||||
That means:
|
||||
|
||||
- each side ≈ 52.4%
|
||||
- total >100% → the difference = bookmaker profit
|
||||
|
||||
You’re playing against a system that’s already winning
|
||||
|
||||
## 2/ Where the Money Is
|
||||
|
||||
Your job is to remove the vig (de-vig) and compare:
|
||||
|
||||
- if your probability > implied → **+EV bet**
|
||||
- if not → skip
|
||||
|
||||
Example: -150 = ~60% implied if your model says 64% → that’s edge
|
||||
|
||||
Every bet = a small mathematical advantage
|
||||
|
||||
## 3/ Arbitrage = Risk-Free Profit
|
||||
|
||||
Different books = different prices
|
||||
|
||||
You bet all outcomes → lock in profit
|
||||
|
||||
Typical ROI: 5-10% in minutes
|
||||
|
||||
But:
|
||||
|
||||
- opportunities are rare
|
||||
- they disappear fast
|
||||
- books limit winners
|
||||
|
||||
This is trading, not gambling
|
||||
|
||||
## 4/ How the Market Actually Works
|
||||
|
||||
Sportsbooks = market makers
|
||||
|
||||
- balance money on both sides
|
||||
- move lines when there’s pressure
|
||||
- react to sharp bettors
|
||||
|
||||
Sharps move the market Public pays for emotions
|
||||
|
||||
This behaves exactly like financial markets
|
||||
|
||||
## 5/ +EV Is Everything
|
||||
|
||||
You don’t need to know sports better than everyone
|
||||
|
||||
You need to:
|
||||
|
||||
- find mispriced odds
|
||||
- compare across books
|
||||
- bet only when EV is positive
|
||||
|
||||
Strategies:
|
||||
|
||||
- **Middles** (win both sides in certain outcomes)
|
||||
- slow-moving lines
|
||||
- cross-book discrepancies
|
||||
|
||||
## 6/ Why Most People Lose
|
||||
|
||||
- vig eats your bankroll
|
||||
- parlays amplify losses
|
||||
- prop bets often have 20%+ house edge
|
||||
|
||||
You can be right often and still lose money
|
||||
|
||||
## 7/ The Real Skill
|
||||
|
||||
**Decision-making under uncertainty**
|
||||
|
||||
You never know the outcome But you can make +EV decisions
|
||||
|
||||
This applies everywhere:
|
||||
|
||||
- trading
|
||||
- business
|
||||
- life
|
||||
|
||||
## 8/ Final Take
|
||||
|
||||
- 95% of bettors lose
|
||||
- not because of luck, because of no edge
|
||||
- pros play probability, not sports
|
||||
|
||||
Betting stops being gambling once you understand the math
|
||||
|
||||
## Full Lecture (Highly Recommended)
|
||||
|
||||
Massachusetts Institute of Technology lecture by Alex Monahan
|
||||
|
||||
🎓 [https://www.youtube.com/watch?v=6mTvAjmF2-A](https://www.youtube.com/watch?v=6mTvAjmF2-A)
|
||||
|
||||
Save this
|
||||
|
||||
In the long run, the winner isn’t the one who guesses right, it’s the one who has edge
|
||||
+76
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: "Mercury: The AI Agent We All Wanted - Where Control, Permissions, and Autonomy Finally Got Real"
|
||||
source: "https://x.com/Ctrl_Alt_Zaid/status/2046902326657749114"
|
||||
author:
|
||||
- "[[@Ctrl_Alt_Zaid]]"
|
||||
published: 2026-04-22
|
||||
created: 2026-04-26
|
||||
description: "The problem with AI agents right nowPersonal AI agents have a security problem, a cost problem, and an identity problem and most of them shi..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
## The problem with AI agents right now
|
||||
|
||||
Personal **AI agents** have a **security problem, a cost problem, and an identity problem** and most of them ship all three at once.
|
||||
|
||||
**On security:** agents run shell commands, touch your files, and install third-party skills, usually with permissions wide enough to drive a truck through. **Over 800 malicious skills have been found in the wild actively exfiltrating credentials.** Single-click remote code execution flaws have exposed tens of thousands of instances to total system compromise.
|
||||
|
||||
**On cost:** context windows balloon silently. Conversation histories get fed back in full on every turn. **You run the agent, you cross your fingers, and you find out what it cost at the end of the month.**
|
||||
|
||||
**On identity**: agents either scatter personality across a dozen directories or bury it inside an opaque SQLite blob you can't read, version, or edit.
|
||||
|
||||
[Mercury (by Cosmic Stack)](https://mercury.cosmicstack.org/) was built for exactly this reality.
|
||||
|
||||
A tool-first, background-native orchestrator with paranoia-level permissions, a token budget that respects your wallet, and a four-file soul system you own in plain text. Not another chat wrapper pretending to be a brain. A reliable worker that asks before it acts.
|
||||
|
||||
**OpenClaw** hit 100,000 GitHub stars in weeks and proved developers wanted a local agent that could actually execute shell commands instead of generating text in a browser tab. **Hermes** arrived from Nous Research with persistent SQLite memory and autonomous skill generation.
|
||||
|
||||
Both are brilliant feats of engineering. **Both also left the same problems above, wide open.**
|
||||
|
||||
**Here is what OpenClaw and Hermes missed, and how Mercury fixes it.**
|
||||
|
||||
# 1\. Permissions That Actually Gate Execution
|
||||
|
||||
**OpenClaw** requires uncomfortably broad access to function, relying on a naive ecosystem of unvetted third-party extensions. The result is a security nightmare. Researchers found **over 800 malicious skills** in the wild actively exfiltrating credentials. Worse, **OpenClaw’s** core architecture suffered from **CVE-2026-25253 (a CVSS 8.8 RCE flaw)**. This vulnerability exposed over 40,000 instances to total system compromise via a single clicked link, completely bypassing localhost protections.
|
||||
|
||||
[Mercury](https://mercury.cosmicstack.org/) assumes you should never blindly trust an LLM with root access. It ships with a permission-hardened architecture by default. Read and write access is explicitly scoped to specific folders. Destructive commands like **sudo** or **rm -rf /** are hard-blocked at the execution layer. They do not trigger a **"prompt for approval"** because they simply never execute. Third-party skills only receive elevated access through explicitly defined granular tools.
|
||||
|
||||
Every agent can read files and run scripts. **Mercury is the one that asks first**.
|
||||
|
||||
# 2\. Token Discipline as a First Principle
|
||||
|
||||
**OpenClaw** is notorious for context-window bloat. It attempts to feed massive JSONL conversation histories back into the model, leading to minutes of silent processing and brutal API bills. You run the agent, you cross your fingers, and you find out what it cost at the end of the month.
|
||||
|
||||
**Token efficiency** is baked directly into Mercury. It limits the context window injected per request to roughly **400 tokens of core persona**. You set a daily token limit. **Cross 70% of your daily budget**, and the **Auto-Concise** mode automatically kicks in to tighten the context and keep your API bill flat without dropping the ball on active tasks.
|
||||
|
||||
# 3\. A Layered, Version Controlled "Soul"
|
||||
|
||||
**OpenClaw** relies on disjointed skill files scattered across directories. Hermes goes the other direction, relying entirely on auto-generated learned memory stored opaquely in SQLite databases.
|
||||
|
||||
[Mercury](https://mercury.cosmicstack.org/) matches a modern developer aesthetic with a highly opinionated, four-file markdown system: **soul.md, persona.md, taste.md, and heartbeat.md**. You define exactly how the agent thinks, responds, and writes code. You can literally enforce your preference for dark themes and clean UI components right in the taste file. You own it, you write it in plain text, and you version-control it in Git. It is a clean identity system, not an unpredictable black box.
|
||||
|
||||
# 4\. An Always On, Zero Dependency Daemon
|
||||
|
||||
**Hermes** requires managing your **own infrastructure** (like Docker or VPS deployments) to keep it persistent. **OpenClaw** operates primarily as an active application you have to constantly babysit.
|
||||
|
||||
[Mercury](https://mercury.cosmicstack.org/) runs natively as a **zero-dependency background** daemon across **macOS, Linux, and Windows**. Run **mercury up**, and the daemon installs itself as a system service. It auto-starts on login, auto-restarts on crash, and handles cron scheduling automatically.
|
||||
|
||||
# The Verdict
|
||||
|
||||
**OpenClaw** proved developers want **local orchestration**. **Hermes** proved agents need **persistence**. [Mercury](https://mercury.cosmicstack.org/) represents the next logical iteration: **a streamlined, command-line native engine built on a permission-hardened foundation.**
|
||||
|
||||
With built-in tools covering **file operations, deep GitHub management, and multi-channel integration spanning from CLI streaming to Telegram,** the framework gets out of the way so the tools can do the work. It is an orchestrator built for **actual daily use**, not just a **proof of concept.**
|
||||
|
||||
# Deployment
|
||||
|
||||
[Mercury](https://mercury.cosmicstack.org/) is [open-source](https://github.com/cosmicstack-labs/mercury-agent) and can be initialized locally without additional dependencies:
|
||||
|
||||
> **npm i -g** [@cosmicstack/mercury-agent](https://x.com/@cosmicstack/mercury-agent) **&& mercury**
|
||||
|
||||
Configuration requires an API key and runs entirely on your local machine.
|
||||
|
||||
> We don't need another over-engineered application pretending to be a brain. We need a reliable, background-native worker that respects the token budget and won't blindly execute a destructive shell command.
|
||||
|
||||
**Mercury is built for that reality. You can review the architecture, read the docs, or contribute to the core loop on GitHub at :** [github.com/cosmicstack-labs/mercury-agent](https://github.com/cosmicstack-labs/mercury-agent)
|
||||
@@ -0,0 +1,105 @@
|
||||
---
|
||||
title: "Personal Agent"
|
||||
source: "https://x.com/trashpandaemoji/status/2048026069375029267"
|
||||
author:
|
||||
- "[[@trashpandaemoji]]"
|
||||
published: 2026-04-25
|
||||
created: 2026-04-26
|
||||
description: "I've been developing an agent harness I'm calling PersonalAgent (naming is still hard guys, okay?). Personal Agent is built on top of @badlo..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
I've been developing an agent harness I'm calling PersonalAgent (naming is still hard guys, okay?). Personal Agent is built on top of [@badlogicgames](https://x.com/@badlogicgames)'s excellent Pi coding agent. Its amazing what you can do with it and I've done quite a bit. PA is built on Electron and is 100% fully vibe coded. I've not looked at a single line of code.
|
||||
|
||||
The important thing is that I wanted a tool that's similar to the desktop harnesses coming from the big labs, but without big lab lock-in. With Pi, I can use any model and any harness. You need to own your own harness.
|
||||
|
||||
I'm not open sourcing it yet, because frankly this is for me, not for general consumption. However, I'd like to show you some interesting concepts I've built into Personal Agent that you can copy into your own tools.
|
||||
|
||||
# Desktop UI
|
||||
|
||||

|
||||
|
||||
First and foremost, it's a desktop application because terminal UI is way too limiting. It's great for quick prototypes, but if you're trying to do anything more advanced you quickly need to start hacking in stuff like tmux which makes the whole thing feel like a hacked together kludge.
|
||||
|
||||
So, the first feature is a desktop UI that supports multiple threads. Heavily copied from [@OpenAICodexCli](https://x.com/@OpenAICodexCli). This allows me to easily swap between running conversations, see when conversations need my attention, and is the foundation for the rest of the features.
|
||||
|
||||
# iOS Companion App
|
||||
|
||||

|
||||
|
||||
As an aside, I also have an iOS companion application. This companion app allows me to connect to a running instance of PA via my tailscale network. This is really important as it allows me to walk away from my desk and monitor agent runs on the go.
|
||||
|
||||
# Agent Lifecycle Management
|
||||
|
||||
I have a few features to improve long-running agent tasks and to put more control into the agent's hands. The goal is to give the agent tools so it can continue its own agentic loop.
|
||||
|
||||
## Scheduled Tasks
|
||||
|
||||
The automation feature is powered by a scheduling engine that the agent also has access to. The agent can schedule tasks:
|
||||
|
||||
1. On a recurring basis
|
||||
2. At a specific time in the future
|
||||
3. Queued as a followup
|
||||
4. Or as a deferred resume (retrigger the current loop in X minutes -- syntatic sugar over 2)
|
||||
|
||||
## Deferred Resume
|
||||
|
||||

|
||||
|
||||
This has been a great feature so the agent doesn't have to abuse bash sleeps. It can just trigger a deferred resume in N minutes to wake its own agent loop up.
|
||||
|
||||
## Scheduled Tasks
|
||||
|
||||

|
||||
|
||||
Scheduled tasks are exposed under the automations panel. It showcases active jobs and the threads they belong to.
|
||||
|
||||
# Auto Mode
|
||||
|
||||

|
||||
|
||||
When auto mode is enabled, it injects a continuation prompt when the agent tries to exit, telling the agent to continue working. Here's the prompts:
|
||||
|
||||
> Auto mode review for this conversation. The user enabled auto mode because they want you to keep working without waiting for user input. Call conversation\_auto\_control exactly once in this hidden review turn. - Use action "continue" if there is meaningful remaining work you can do now. - Use action "stop" only when the task is complete for the user's request, blocked on a real dependency, or needs user input. - If the user did not give an explicit validation target, infer the expected level of doneness from their request and the work so far. Do not stop just because no explicit checklist was provided. - Err toward continuing when useful work remains. - Do not do the work yourself in this hidden review turn. - Do not call other tools in this hidden review turn.
|
||||
|
||||
Continuation prompt:
|
||||
|
||||
> Auto mode continuation for this conversation. Continue working on the current user request from where you left off. Do not mention this hidden continuation prompt. Take the next concrete step that best advances the task.
|
||||
|
||||
# Embedded screenshot + excalidraw
|
||||
|
||||

|
||||
|
||||

|
||||
|
||||
I wanted the ability to draw diagrams for the agent so I embedded excalidraw. When you click the icon, it pops an excalidraw modal, then attaches the image to your prompt. Very useful! You can also paste screenshots into excalidraw and annotate them.
|
||||
|
||||
There is also a screenshot button that triggers Mac's native screenshot functionality, attaching it to the prompt for me.
|
||||
|
||||
# Dictation
|
||||
|
||||

|
||||
|
||||
This feature currently uses OpenAI's dictation endpoint with my ChatGPT subscription. If I ever swap to something else I'd probably swap this out for a local whisper model, but for now its included with my ChatGPT sub.
|
||||
|
||||
# Built in knowledge base
|
||||
|
||||

|
||||
|
||||
I really wanted a way to combine my knowledge and the agent's knowledge. To do this, our shared understanding needs to be part of the tool. [@karpathy](https://x.com/@karpathy) showed us his cool Obsidian based knowledge base, but I wanted it IN the harness. The knowledge base is simply a separate git repo, with a touchless sync engine.
|
||||
|
||||
I define "Knowledge" here as a combination of Skills + Agent.md + free-form documents/notes. I'm testing out a Karpathy style wiki in here as well, but the real workhorse has been Projects + Notes.
|
||||
|
||||
I keep a folder of folders of projects, which both myself and the agent update and keep context.
|
||||
|
||||
I also keep a folder of notes which are just markdown files where I can jot down ideas. Its great to just offload thoughts, ideas, todos.
|
||||
|
||||
The agent has full access to this folder, it has a pointer in its system prompt and can explore it. I can also use the \`@\` symbol in my inputs to tag specific files in the knowledge base. All these combined allow me to more seamlessly integrate a richer context into the application.
|
||||
|
||||
What's notably NOT in this is a RAG based knowledge base. I experimented with RAG based systems a lot both at work and with agents and frankly its not worth the effort. Its simply easier and cleaner to just maintain a folder of markdown files so both myself and the agent can interact with it.
|
||||
|
||||
# That's it for now
|
||||
|
||||
There are so many more features in PA, but these are the main ones. You should copy these ideas if they resonate. **You really should be building your own harness, owning your own agent.**
|
||||
@@ -0,0 +1,143 @@
|
||||
---
|
||||
title: "Recursive Language Models, clearly explained"
|
||||
source: "https://x.com/akshay_pachaar/status/2048757569775378858"
|
||||
author:
|
||||
- "[[@akshay_pachaar]]"
|
||||
published: 2026-04-27
|
||||
created: 2026-05-04
|
||||
description: "Researchers from MIT recently proposed a clever solution to one of the biggest limitations of modern LLMs: context rot.Here's what context r..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
Researchers from MIT recently proposed a clever solution to one of the biggest limitations of modern LLMs: context rot.
|
||||
|
||||
Here's what context rot looks like:
|
||||
|
||||
You paste a 200-page document into ChatGPT. You ask a simple question. The answer comes back wrong, even though the information is right there on page 53.
|
||||
|
||||
You didn't exceed the context window. The model just got worse at reasoning because there was too much to process at once.
|
||||
|
||||

|
||||
|
||||
The elegant fix they proposed is called Recursive Language Models. The results are striking, and the core idea is surprisingly intuitive.
|
||||
|
||||
Let's understand it step-by-step.
|
||||
|
||||
<video preload="none" tabindex="-1" playsinline="" aria-label="嵌入式视频" poster="https://pbs.twimg.com/amplify_video_thumb/2048755416683945985/img/BiZOryPMy24EJxEa.jpg" style="width: 100%; height: 100%; position: absolute; background-color: black; top: 0%; left: 0%; transform: rotate(0deg) scale(1.005);"><source type="video/mp4" src="blob:https://x.com/5f1f612a-6fc1-4141-80f1-adf27e290bf4"></video>
|
||||
|
||||
0:00 / 0:02
|
||||
|
||||
# The Problem: Context Rot Is a Reasoning Failure, Not a Window Failure
|
||||
|
||||
A model that advertises a 1M-token window can still produce garbage on a 50K-token document, and the reason has nothing to do with how much text fits.
|
||||
|
||||
Frontier models ace the **needle-in-a-haystack** benchmark. You hide one weird sentence in a pile of filler text, ask about that sentence, and the model finds it.
|
||||
|
||||
That test measures retrieval against a blob of tokens. It does not measure reasoning across those tokens.
|
||||
|
||||
Frontier models ace needle-in-a-haystack tests. But ask them to count, classify, or reason over thousands of buried entries, and performance collapses.
|
||||
|
||||
You've probably noticed this yourself:
|
||||
|
||||
- Long Claude Code sessions get sluggish
|
||||
- Extended ChatGPT conversations require more repetition
|
||||
|
||||
The model isn't hallucinating, it's just getting dumber as context grows
|
||||
|
||||

|
||||
|
||||
# The Fix: Recursive Language Models (RLMs)
|
||||
|
||||
The core idea is simple:
|
||||
|
||||
Instead of forcing the model to process everything at once, let it break context into smaller pieces and handle them recursively.
|
||||
|
||||
The key shift is **context-centric** decomposition:
|
||||
|
||||
- **Agents** decompose tasks based on human-designed steps
|
||||
- **RLMs** let the model decompose the context itself
|
||||
|
||||
The model becomes a programmer analyzing a dataset, not a student cramming for an exam.
|
||||
|
||||

|
||||
|
||||
# How RLMs Work
|
||||
|
||||
## 1\. Separate query from context
|
||||
|
||||
In a normal LLM call, the query and the full context ride together inside one prompt. Everything you want the model to see has to fit in that single prompt window before generation starts.
|
||||
|
||||
RLMs break that assumption. The context lives outside the prompt, in a runtime memory slot, while the root model sees only the question and a set of tools.
|
||||
|
||||
Think of a **Jupyter** notebook. You load a dataframe into a variable called df, and from then on every cell references df without re-uploading the CSV.
|
||||
|
||||
RLMs borrow that exact mental model. The 200-page document becomes a variable, let's call it ctx, that sits in a **REPL** environment the model can interact with through tool calls.
|
||||
|
||||

|
||||
|
||||
## 2\. The model gets tools
|
||||
|
||||
The root model cannot read ctx directly, so the whole design lives or dies on the tools it uses to probe that variable. The paper gives the model four, and together they cover every access pattern a data analyst would reach for.
|
||||
|
||||
- **Peek** at context (view first 2,000 chars to understand structure)
|
||||
- **Grep** using regex to filter relevant lines
|
||||
- **Partition** into smaller chunks
|
||||
- **Call itself recursively** on those chunks
|
||||
|
||||

|
||||
|
||||
## 3\. Strategy emerges from the task
|
||||
|
||||
Agent frameworks traditionally hardcode the decomposition. A human picks the steps, the order, and the fallback policy up front, and the model plays a part the human already scripted.
|
||||
|
||||
RLMs do the opposite. The root model decides how to break the problem down based on what it finds as it looks.
|
||||
|
||||
It might grep first, then partition. Or peek, then summarize. It figures this out on its own rather than following a human-designed workflow.
|
||||
|
||||

|
||||
|
||||
# A Concrete Example
|
||||
|
||||
Say you have 5,000 customer support tickets and you ask: "Among users 12345, 67890, and 11111, how many questions are about billing?"
|
||||
|
||||
A normal LLM receives all 5,000 tickets, tries to scan everything, and makes counting errors.
|
||||
|
||||
An RLM handles it differently:
|
||||
|
||||
1. **Peeks** at structure: "Each line has Date, User ID, Question"
|
||||
2. **Greps** for target users, reducing 5,000 lines to 50
|
||||
3. **Spawns a recursive call:** "Classify each as billing or other"
|
||||
4. **Returns:** Final Result
|
||||
|
||||
The root model's context stayed small throughout. **No rot**.
|
||||
|
||||

|
||||
|
||||
# Why It Matters
|
||||
|
||||
- **No context rot:** Accuracy holds regardless of document size
|
||||
- **Unlimited context:** 10M tokens? Just partition more
|
||||
- **Interpretable:** See exactly what the model did
|
||||
- **Cost-efficient:** Smaller calls beat one massive API call
|
||||
- **Future-proof:** As LLMs improve, RLMs improve automatically
|
||||
|
||||

|
||||
|
||||
RLMs treat context as **data to be programmatically explored**.
|
||||
|
||||
The model combines code execution and language reasoning. It's not summarization. It's not a rigid agent. It decides how to decompose the problem based on what it discovers.
|
||||
|
||||
To read more about this, I am sharing the research paper and a startup code on RLMs that you can build on top of.
|
||||
|
||||
- [Paper →](https://arxiv.org/abs/2512.24601v1)
|
||||
- [GitHub →](https://github.com/alexzhang13/rlm)
|
||||
|
||||
Thanks for reading!
|
||||
|
||||
If you found it insightful, reshare with your network.
|
||||
|
||||
Find me →[@akshay\_pachaar](https://x.com/@akshay_pachaar) ✔️
|
||||
|
||||
For more insights and tutorials on LLMs, AI Agents, and Machine Learning!
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: "Reflexive AI usage is now a baseline expectation at Shopify"
|
||||
source: "https://x.com/tobi/status/1909251946235437514"
|
||||
author:
|
||||
- "[[@tobi]]"
|
||||
published: 2025-04-07
|
||||
created: 2026-04-26
|
||||
description: "Context: This is a Shopify internal memo that I shared here because it was in the process of being leaked and (presumably) shown in bad fait..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||
> Context: This is a Shopify internal memo that I shared here because it was in the process of being leaked and (presumably) shown in bad faith
|
||||
|
||||
Team,
|
||||
|
||||
We are entering a time where more merchants and entrepreneurs could be created than any other in history. We often talk about bringing down the complexity curve to allow more people to choose this as a career. Each step along the entrepreneurial path is rife with decisions requiring skill, judgement and knowledge. Having AI alongside the journey and increasingly doing not just the consultation, but also doing the work for our merchants is a mindblowing step function change here.
|
||||
|
||||
Our task here at Shopify is to make our software unquestionably the best canvas on which to develop the best businesses of the future. We do this by keeping everyone cutting edge and bringing all the best tools to bear so our merchants can be more successful than they themselves used to imagine. For that we need to be absolutely ahead.
|
||||
|
||||
**Reflexive AI usage is now a baseline expectation at Shopify**
|
||||
|
||||
Maybe you are already there and find this memo puzzling. In that case you already use AI as a thought partner, deep researcher, critic, tutor, or pair programmer. I use it all the time, but even I feel I'm only scratching the surface. It’s the most rapid shift to how work is done that I’ve seen in my career and I’ve been pretty clear about my enthusiasm for it: you've heard me talk about AI in weekly videos, podcasts, town halls, and… Summit! Last summer I [used agents to create my talk](https://vault.shopify.io/page/Summit-2024---Unlocking-AI~RRey.md), and presented about that. I did this as a call to action and invitation for everyone to tinker with AI, to dispel any scepticism or confusion that this matters at all levels. Many of you took up the call, and all of us who did have been in absolute awe of the new capabilities and tools that AI can deliver to augment our skills, crafts, and fill in our gaps.
|
||||
|
||||
What we have learned so far is that using AI well is a skill that needs to be carefully learned by… using it a lot. It’s just too unlike everything else. The call to tinker with it was the right one, but it was too much of a suggestion. This is what I want to change here today. We also learned that, as opposed to most tools, AI acts as a multiplier. We are all lucky to work with some amazing colleagues, the kind who contribute 10X of what was previously thought possible. It’s my favorite thing about this company. And what’s even more amazing is that, for the first time, we see the tools become 10X themselves. I’ve seen many of these people approach implausible tasks, ones we wouldn’t even have chosen to tackle before, with reflexive and brilliant usage of AI to get 100X the work done.
|
||||
|
||||
In my [On Leadership](https://vault.shopify.io/page/On-Leadership---August-2020~11669.md) memo years ago, I described Shopify as a red queen race based on the Alice in Wonderland story—you have to keep running just to stay still. In a company growing 20-40% year over year, you must improve by at least that every year just to re-qualify. This goes for me as well as everyone else.
|
||||
|
||||
This sounds daunting, but given the nature of the tools, this doesn’t even sound terribly ambitious to me anymore. It’s also exactly the kind of environment that our top performers tell us they want. Learning together, surrounded by people who also are on their own journey of personal growth and working on worthwhile, meaningful, and hard problems is precisely the environment Shopify was created to provide. This represents both an opportunity and a requirement, deeply connected to our core values of Be a Constant Learner and Thrive on Change. These aren't just aspirational phrases—they're fundamental expectations that come with being a part of this world-class team. This is what we founders wanted, and this is what we built.
|
||||
|
||||
## What This Means
|
||||
|
||||
1. **Using AI effectively is now a fundamental expectation of everyone at Shopify.** It's a tool of all trades today, and will only grow in importance. Frankly, I don't think it's feasible to opt out of learning the skill of applying AI in your craft; you are welcome to try, but I want to be honest I cannot see this working out today, and definitely not tomorrow. Stagnation is almost certain, and stagnation is slow-motion failure. If you're not climbing, you're sliding.
|
||||
2. **AI must be part of your GSD Prototype phase**. The prototype phase of any GSD project should be dominated by AI exploration. Prototypes are meant for learning and creating information. AI dramatically accelerates this process. You can learn to produce something that other team mates can look at, use, and reason about in a fraction of the time it used to take.
|
||||
3. **We will add AI usage questions to our performance and peer review questionnaire**. Learning to use AI well is an unobvious skill. My sense is that a lot of people give up after writing a prompt and not getting the ideal thing back immediately. Learning to prompt and load context is important, and getting peers to provide feedback on how this is going will be valuable.
|
||||
4. **Learning is self directed, but share what you learned**. You have access to as much of the cutting edge AI tools as possible.There is [chat.shopify.io](http://chat.shopify.io/), which we had for years now. Developers have [proxy](https://proxy.shopify.ai/), Copilot, Cursor, Claude code, all pre-tooled and ready to go. We’ll learn and adapt together as a team. We’ll be sharing Ws (and Ls!) with each other as we experiment with new AI capabilities, and we’ll dedicate time to AI integration in our monthly business reviews and product development cycles. Slack and Vault have lots of places where people share prompts that they developed, like [#revenue](https://x.com/search?q=%23revenue&src=hashtag_click)\-ai-use-cases and [#ai](https://x.com/search?q=%23ai&src=hashtag_click)\-centaurs.
|
||||
5. **Before asking for more Headcount and resources**, teams must demonstrate why they cannot get what they want done using AI. What would this area look like if autonomous AI agents were already part of the team? This question can lead to really fun discussions and projects.
|
||||
6. **Everyone means everyone**. This applies to all of us—including me and the executive team.
|
||||
|
||||
## The Path Forward
|
||||
|
||||
AI will totally change Shopify, our work, and the rest of our lives. We're all in on this! I couldn't think of a better place to be part of this truly unprecedented change than being here. You don't just get a front-row seat, but are surrounded by a whole company learning and pushing things forward together.
|
||||
|
||||
Our job is to figure out what entrepreneurship looks like in a world where AI is universally available. And I intend for us to do the best possible job of that, and to do that I need everyone’s help. I already laid out a lot of the AI projects in the themes this year- our roadmap is clear, and our product will better match our mission. What we need to succeed is our collective sum total skill and ambition at applying our craft, multiplied by AI, for the benefit of our merchants.
|
||||
|
||||
\-tobi CEO Shopify
|
||||
@@ -0,0 +1,159 @@
|
||||
---
|
||||
title: "Run Excellent 1:1s"
|
||||
source: "https://x.com/dklineii/status/2048050747531518182"
|
||||
author:
|
||||
- "[[@dklineii]]"
|
||||
published: 2026-04-25
|
||||
created: 2026-04-26
|
||||
description: "This is a skills file. If it reads like the work you already do as a leader, that's because it is. The reality is you do much of this intuit..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
This is a skills file. If it reads like the work you already do as a leader, that's because it is. The reality is you do much of this intuitively. If you have time to do it at all. But since it's a skills file, you can hand it to your LLM for help. It can help you apply the skill. Prep the meeting. Track commitments. Coach your execution. The LLM will even help you refine the skills file for you over time. It's how a chatbot becomes a Chief of Staff.
|
||||
|
||||
Most managers run their 1:1s wrong. They write the agenda. They ask the questions. They take 80% of the airtime. The person sitting across from them shows up reactive, defensive, holding back things that actually matter.
|
||||
|
||||
The fix is one move.
|
||||
|
||||
Flip the ownership. The person owns the 1:1, not you. They come prepared with their wins, their metrics, their progress, their blockers, their lessons. You listen 90%. You speak 10%. You coach through questions, not solutions.
|
||||
|
||||
When you do this every week, the rhythm accelerates. Trust compounds. Coaching compounds. Problems surface early enough to fix. You stop running 1:1 meetings. You start optimizing your operating system to help your team win.
|
||||
|
||||
This file is a piece of that system. It runs weekly. Watch it grow with you.
|
||||
|
||||
## The dashboard: 8 questions that show command.
|
||||
|
||||
Establish the dashboard with the person when you set up your recurring 1:1. They own questions 2 through 7. They update their dashboard before the meeting and send it to you. You review it before you walk in.
|
||||
|
||||
By the time you're in the room, status is already covered. Your job is to coach what the answers reveal.
|
||||
|
||||
You don't go deep on all eight every week. Rotate. The structure is the scaffolding. The conversation is the work.
|
||||
|
||||
**1\. How are you? (No really, how are you?)**
|
||||
|
||||
Not a pleasantry. A genuine check on state. Are they energized or running on fumes? Do they have space to think, or are they spiraling?
|
||||
|
||||
If the answer is real, it tells you whether to follow the rest of the dashboard or abandon it entirely. Sometimes the highest-leverage 1:1 is the one where you spend all 30 minutes on a single thing.
|
||||
|
||||
**2\. What do you think we should focus on?**
|
||||
|
||||
The person sets the priority. They name what's taking up oxygen. You listen first, speak second.
|
||||
|
||||
Most managers skip this and jump to their agenda. Don't. The best performers already know what matters. You're confirming alignment, not assigning it.
|
||||
|
||||
**3\. How are you tracking against your goals?**
|
||||
|
||||
The quantitative check. On track, at risk, off track? What changed since last week?
|
||||
|
||||
If they're off track, the conversation deepens naturally. They own the diagnosis before you layer in your view.
|
||||
|
||||
**4\. Are there notable wins or losses to discuss?**
|
||||
|
||||
The stories behind the numbers. What broke? What surprised them? What worked?
|
||||
|
||||
Wins are where you see their energy spike. Lean in there. Losses are where you learn how they think about problems: do they blame the system, blame others, or own it?
|
||||
|
||||
**5\. What problems are you focused on solving right now?**
|
||||
|
||||
The evolution question. What are they trying to get better at? Where do they spend attention when they're not in execution mode?
|
||||
|
||||
This is where development hides in plain sight.
|
||||
|
||||
**6\. How are your people doing? (or: How are your key relationships?)**
|
||||
|
||||
The heatmap question. If they manage, you're checking on their team. If they don't, you're asking about peers and partners.
|
||||
|
||||
You're listening for who they need more from. Who they're protecting too long. Who they've stopped trying with.
|
||||
|
||||
**7\. How are you getting better?**
|
||||
|
||||
Growth and compounding. What did they learn last month? How are they using that insight in this month's work?
|
||||
|
||||
This is where coaching gets its highest leverage. You're not teaching them something new. You're helping them see patterns in their own growth.
|
||||
|
||||
**8\. What else can I do to help you succeed?**
|
||||
|
||||
The catch-all. The white space. Often surfaces the thing they didn't know how to bring up.
|
||||
|
||||
Leave silence after this one. Wait for the real answer.
|
||||
|
||||
## The discipline: Coach through questions, not solutions.
|
||||
|
||||
When they bring you a problem, the pressure is to solve it. Don't.
|
||||
|
||||
The person who proposes the solution owns the implementation. The person who accepts your solution executes your judgment, not theirs. Their growth stalls. Your time fills up.
|
||||
|
||||
Use these instead:
|
||||
|
||||
- "What do you think you should do?" — builds their judgment
|
||||
- "What's stopping you from doing that?" — diagnoses the real blocker
|
||||
- "If you could design the ideal approach, what would it look like?" — removes constraints first
|
||||
- "What would you do if this was your company?" — flips them into ownership
|
||||
|
||||
When they say "I don't know", push once: "Take 30 seconds. What's your gut saying? Not the perfect answer — the honest one."
|
||||
|
||||
When you have a strong opinion they're getting wrong, share it once and stop: "I see it differently. Here's my thinking: \[your view\]. What's your reaction? Anything I'm missing?" Don't defend. Let them sit with it.
|
||||
|
||||
When they bring the same problem two weeks in a row, say so: "This is the second time. What's different you need to try? What would I need to see to know you've moved it?"
|
||||
|
||||
## The prep: Review their dashboard, then run the AI.
|
||||
|
||||
Two inputs are sitting in front of you before the meeting: the dashboard the person filled out for this week, and your file of notes from prior 1:1s.
|
||||
|
||||
**Read the dashboard first.** Their answers to questions 2 through 7 are your status update. By the time you walk in, you already know how they're tracking, what they're focused on, what's surfacing with their people, what they're learning. You don't need to ask any of it. You're free to coach.
|
||||
|
||||
**Then run the AI on top of it.** The point isn't to script the meeting. The point is to surface what you'd miss reading the dashboard cold.
|
||||
|
||||
Three prompts. Run in sequence.
|
||||
|
||||
Prompt 1 — Pattern recognition
|
||||
|
||||
Two inputs: (a) the dashboard the person filled out for this week, and (b) your notes from the last 3-4 weeks of 1:1s with them. Anonymize. Paraphrase. No real names. No company info.
|
||||
|
||||
> "Role: You are an executive coach reviewing my 1:1 prep for my direct report. Here is the dashboard they filled out for this week, and my notes from the last four 1:1s. What patterns do you see? What themes are repeating? What's being said this week that connects to or contradicts what was said before? What might not be said?"
|
||||
|
||||
You'll get 3-5 patterns. One or two will stand out as real. That's your prep focus.
|
||||
|
||||
Prompt 2 — Prediction and listening cues
|
||||
|
||||
Take the pattern that hit. Add the recent context.
|
||||
|
||||
> "The pattern I'm seeing is \[pattern\]. In this week's dashboard, they wrote \[specific answer\]. Given this, what might be underneath? What should I listen for? What phrases or behaviors would tell me I'm right or wrong?"
|
||||
|
||||
You'll get hypotheses plus specific phrases to listen for. "She might be questioning the role. Listen for: 'I'm not sure I'm,' 'This isn't what I thought,' 'I see other people doing X.'"
|
||||
|
||||
This becomes your listening guide. Not what to ask. What to listen for.
|
||||
|
||||
Prompt 3 — Calibrated questions, only if you need them
|
||||
|
||||
> "Based on this pattern, here's what I want to understand: \[your ask\]. The constraint: I want them to own the diagnosis, not me to suggest answers. Give me 2-3 questions that would let them tell me what's real. Format: question / what I'm listening for / what different answers might reveal."
|
||||
|
||||
You'll get 2-3 questions designed for depth, not interrogation. These are backup. If the conversation flows naturally, you don't need them.
|
||||
|
||||
## The mistakes: common missteps that kill the 1:1
|
||||
|
||||
Watch for these. They are how managers think they're running great 1:1s while the relationship erodes silently.
|
||||
|
||||
1. **Canceling.** Nothing says what you're working on isn't important like canceling the one meeting focused on supporting you. Nothing erodes morale faster.
|
||||
2. **The manager monologue.** You take 70% of the air time. The person watches. They leave thinking the meeting was about you, not them.
|
||||
3. **Skipping question 1.** You jump straight to the dashboard and miss that someone is drowning.
|
||||
4. **Soft accountability.** You ask for commitments at the end of one meeting and never check on them at the start of the next. The team learns the meeting doesn't track. Commitments quietly become suggestions. Either confirm what they delivered AND diagnose what they didn't, or stop asking.
|
||||
5. **The interrogation.** You walk through questions 2 through 7 in the meeting because they didn't pre-fill the dashboard. The 1:1 becomes a status update again. The coaching you needed to do is now about why the prep didn't happen — start there.
|
||||
6. **Advice-giving instead of coaching.** They bring a problem. You solve it. Nothing changes because they didn't own the diagnosis.
|
||||
7. **Solving the same problem twice.** Same blocker, same advice, two weeks running. The 1:1 becomes theater.
|
||||
|
||||
## A note on the skills file
|
||||
|
||||
If you handed this to your LLM, here is what it does:
|
||||
|
||||
- It runs Prompt 1, 2, and 3 against the dashboard and notes you give it. It surfaces the patterns. It writes the listening guide. It produces backup questions.
|
||||
- During the meeting, it can sit alongside you (think: transcript) and track which questions you covered vs. skipped. It can flag when you're talking more than 10% of the time.
|
||||
- After the meeting, it can update the running file on this person with what they said, what you noticed, what they committed to do this week, and what to listen for next time.
|
||||
|
||||
Over time, as you tell it which patterns were right and which were wrong, it tailors itself to you. The moves you rely on. The signals you react to. The way each direct report responds when you ask the question that matters.
|
||||
|
||||
That is how you transform a chatbot into your Chief of Staff.
|
||||
|
||||
We're helping 50 leaders do this at scale next week in our [MGMT Second Brain workshop](https://maven.com/dave-kline/build-your-management-second-brain-the-ai-that-gets-smarter-as-you-lead). Join us for this 3-hour hands-on build session!
|
||||
@@ -0,0 +1,130 @@
|
||||
---
|
||||
title: "Some Notes on AI"
|
||||
source: "https://x.com/karrisaarinen/status/2048267794924650791"
|
||||
author:
|
||||
- "[[@karrisaarinen]]"
|
||||
published: 2026-04-26
|
||||
created: 2026-04-26
|
||||
description: "We are nearing the six-month mark from the last large jump in model coding capability. Six months is often the honeymoon period. After that..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
We are nearing the six-month mark from the last large jump in model coding capability. Six months is often the honeymoon period. After that, some of the reality starts to set in.
|
||||
|
||||
I tend to be cautiously optimistic about AI. Mostly, I try to live in the current reality. Not in some far future where AGI branches off from humanity and forms it's own TechnoCore society.
|
||||
|
||||
The capabilities are real, but so are the limits. The interesting question is less “where does this end?” and more “what is actually different now?” I find the current market narratives around AI too simplistic, and honestly a little disheartening. The conversation often leaves no room between optimism and doomerism.
|
||||
|
||||
I’m more interested in the space between: what is actually changing, what is useful, what is overhyped, what carries real risk, and what we still do not understand. --
|
||||
|
||||
## Plans are worthless, but planning is everything
|
||||
|
||||
Recently, it seems planning is going out of fashion.
|
||||
|
||||
**The way I usually think about AI’s impact is to ask whether the same decision or activity could have been made before AI.** As far as I know, there was never a hard requirement to do long planning cycles. If anything common wisdom was always to be more agile, and yet many companies ended up with annual or half-year planning cycles anyway.
|
||||
|
||||
So the question is: why? What problem were those planning cycles solving, and has AI actually solved that problem?
|
||||
|
||||
I do not have the full answer, but I often think planning is not about the output (the plans) but exercise on an alignment and commitment. It forces the organization to come together and debate what actually matters, decide priorities, create meaning and then share that direction with everyone. Sometimes is also to pre-work organizational complexities or boundaries, and the plans create shared terrain that various departments can navigate on. The plan is actually just a forcing function for all these meetings and discussions to happen.
|
||||
|
||||
So while AI may change the timelines and increase bandwidth, I do not yet quite see how it solves the other problems organizations were solving for. The need to choose still remains. In some ways, those may become more important as the cost of building goes down. If it becomes easier to make more things, it also becomes easier to make the wrong things.
|
||||
|
||||
There is still some truth to the shift. Capabilities are changing quickly. Market preferences are in flux. Very long planning cycles now carry more risk, because the market may have moved before you complete the plan.
|
||||
|
||||
There is also a clear argument for more experimentation. AI capabilities keep increasing, and our understanding of how to use them is still incomplete. Valuable use cases, tools, and workflows often have to emerge from trying things. They cannot always be planned in advance.
|
||||
|
||||
This is how we have operated at Linear from the beginning. We have plans for at least six months, which set the overall direction. But we retain the ability to change the plan or priorities any month or week. The plan is always a belief about what we seemed worthwhile. As we learn or notice changes, we adjust it. We are also encouraging more experimentation now. More room to find emergent use cases, rather than only relying on the plan.
|
||||
|
||||
But having no plans, no planning, no direction, or only a very short roadmap can also make organizations rudderless. The risk becomes building the wrong things, for the wrong customers, and for the wrong reasons.
|
||||
|
||||
Without thinking, direction, or a plan for what you actually want to achieve, you may end up doing whatever comes easily. When you don't do the planning exercise, you also never fail your thinking, commitments, plans, or timelines because you never make them. You can just build whatever and see whaat happens next, and potentially let the AI steer you toward what is easiest rather than what matters.
|
||||
|
||||
## You steer the AI, AI steers you
|
||||
|
||||
This gets to something I have written about before: [tools always steer and influence workflows](https://x.com/karrisaarinen/status/2000451411696603437). They always show you the path.
|
||||
|
||||
AI tools are different because they are thinking tools, not just mechanical tools. Their ability to steer you and your work is greater than before.
|
||||
|
||||
There is a valid workflow where you do not fight the AI. You let it pull you. This is essentially what vibe coding done well can be: following the grain of the tool, moving quickly, accepting that the model has a direction and using that momentum.
|
||||
|
||||
It can be useful while not leading you exactly where you wanted to go. Then depends on the situation if that is good or not.
|
||||
|
||||
## The expertise paradox
|
||||
|
||||
AI often feels most impressive in domains where you know the least, which I think it's largest contributor to the dissonance in the market. AI capabilities are described and understood as limitless to the casual observer.
|
||||
|
||||
In areas you understand deeply, you see the gaps. The output is close but not quite right. It misses context, invents details, chooses the obvious path, or needs heavy steering before it becomes useful.
|
||||
|
||||
In areas you know less about, the same output can feel like magic because you lack the judgment to see what is missing. This is a kind of Gell-Mann Amnesia and Dunning-Kruger effect at scale.
|
||||
|
||||
The paradox is that expertise makes AI harder to use, but also more valuable if you know how to wield in a proper way. Experts see the slop, but they also know how to steer, constrain, and evaluate the model.
|
||||
|
||||
So AI does not remove the value of expertise. It makes expertise more about direction, judgment, and knowing what good looks like.
|
||||
|
||||
## Coding
|
||||
|
||||
Talking to customers and companies in the industry, it is clear that agentic coding is now fairly standard. But there is a spectrum. Almost no one privately says their agents write 100% of the code. Also I don't hear lot of real stories from real companies running massive independent agent swarms.
|
||||
|
||||
Engineers are still very much involved in the steering the agent, and often can maybe can only run couple of agents at once, and few cloud agents in the background to do more menial fixes. Any more than that you're living in the world of Harrison Bergeron where something constantly pings you and disrupts your thinking process.
|
||||
|
||||
We see this in Linear as well. A majority of our paid workspaces now have a coding agent installed, and activity using those agents has increased more than 5x in few months. I do not know exactly how every company uses cloud agents internally, but the direction is clear: these tools are part of the normal development workflow.
|
||||
|
||||
At Linear, engineers use various agents and have also seen our pace increase. With just our own cloud coding agent, we are now fixing more than 1,000 issues per month and it's increasing fast. The biggest impact is see is increased bandwidth. We can tackle more smaller problems than before. The work that might have been too minor, too annoying, or too time-consuming now becomes easier to do.
|
||||
|
||||
But hard problems remain hard. Agentic coding does not speed those up as much as the narrative often suggests. It helps around the edges, with scaffolding, refactoring, investigation, and smaller fixes. But the difficult parts still require understanding the system, making tradeoffs, and knowing what should exist.
|
||||
|
||||
In expert coding workflows, the value is usually not “AI writes the code and you accept it.” The value is acceleration around the work. It can explore approaches, scaffold implementation, debug errors, refactor code, write tests or large migrations, and handle smaller fixes.
|
||||
|
||||
The expert still supplies the taste, constraints, and final judgment.
|
||||
|
||||
## Design
|
||||
|
||||
The new image generation and design capabilities are much better, but I still find them challenging.
|
||||
|
||||
Image generation seems to break down the more iterations you have. It is hard to make the AI change one specific thing in one specific way. It often changes many things at once. Each iteration also seems to add some kind of filter over the whole image, and you might have to start over with a new chat, new descriptions and new files to fix it.
|
||||
|
||||
I would like to see better tools for containing AI to specific areas, rather than allowing it to reinterpret the whole output every time. This also happens in writing, where asking for one change often causes the model to reshape the entire piece. I wish I would have better controls and workflows for the image generation.
|
||||
|
||||
## Design and code
|
||||
|
||||
I keep thinking about the value of having a design tool operate directly on the production codebase.
|
||||
|
||||
Many design+code tools show a React component, like a button, and then let you change it with the design tool. But when I am designing, I can imagine how the button works. Whether it is a vector shape or a React button matters very little to me at that stage.
|
||||
|
||||
A lot of the design work I do is not production design. I am not trying to implement the final version or test every edge case. Most design work is about making decisions, understanding the problem, and finding the fit. That process generates many variations and messy ideas.
|
||||
|
||||
I do not want every change to carry the speed or token cost of production code. I don't want to get in to errors because my prompt wasn't completed. I also do not want to design primarily through words or code. Design is a visual field, and for me it still works best in visual, canvas-based tools.
|
||||
|
||||
And if we put aside the debate about whether UI is needed anymore. Design is still a way to shape the problem and the solution. Most design work is about understanding how a feature fits into the existing system, how it interacts with other concepts, what its limits are, and what it is optimized for.
|
||||
|
||||
Even if a product is used through an MCP, CLI, or API, the concepts and workflows still need to make some kind of sense.
|
||||
|
||||
What I would find more useful are advanced visual tools, or semantic UI design tools, where you can define layouts and patterns more directly. Instead of drawing a rectangle, you are drawing a modal, and it can inherit some aspects of the system. AI could help fill screens, generate variations, and explore directions. The value is in the patterns, not that those patterns are backed by real production code.
|
||||
|
||||
Then, once I have something I actually want to prototype live, there should be a clear workflow for distilling the design file for an ai and translating it into code. In the AI world, design is like planning for me. It's the /gstack running, asking you questions, but it is your own brain asking those questions, finding solutions on the screen.
|
||||
|
||||
## Domain matters
|
||||
|
||||
With almost anything said about how a company uses AI, I try to ask: who are they, what is their domain, what stage are they at, what is their product, do they have customers, and who are those customers?
|
||||
|
||||
The way I have always thought about products that they each need different levels of stability, trust, security or even things like product design is that each product needs a different level and type of design.
|
||||
|
||||
A frequent, tactile tool like email needs a lot of UX polish, because users feel every paper cut. They use it constantly. Small frictions compound.
|
||||
|
||||
A backend service is different. The value may be in the backend logic. The UI can be more limited, even rougher, and the product can still be valuable.
|
||||
|
||||
I think many AI companies operate more like backend companies. The capability is the model. The harness and tools are being iterated above it, but so far they are often behind the scenes. This helps them move fast, because every feature can be another tool in the system without much visual or conceptual footprint.
|
||||
|
||||
It feels closer to classic UNIX systems, where programs are text based can be created independently and combined at runtime. The composability of the operating system is easier than compared to something like modern macOS.
|
||||
|
||||
—
|
||||
|
||||
**The last argument is always that "these are the worst as they ever be"**
|
||||
|
||||
I agree, but I try to stay close to the capabilities as they are now, because I do not know exactly what they will become. That is where my cautious optimism comes from. I do not find much value in being a doomer, but I also do not find much value in wishful thinking.
|
||||
|
||||
The more useful position is to observe carefully, try things, and keep judgment intact. AI is clearly changing things, but I don't think we can build today just by believing harder. We need to be more real and noticing what is possible now, deciding what is worth doing, and adjusting as reality changes.
|
||||
|
||||
Sort of how old nursery rhyme goes, if potential were revenue, all this CapEx would already be profit.
|
||||
+183
@@ -0,0 +1,183 @@
|
||||
---
|
||||
title: "Sub-Agents vs Agent Teams: The Architecture Decision That Changes Everything"
|
||||
source: "https://x.com/Suryanshti777/status/2047694444787577236"
|
||||
author:
|
||||
- "[[@Suryanshti777]]"
|
||||
published: 2026-04-24
|
||||
created: 2026-04-26
|
||||
description: "Most AI Systems Are Built WrongMost people reach for multi-agent systems the moment a task feels complex. That’s usually the wrong instinct...."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
Most AI Systems Are Built Wrong
|
||||
|
||||
Most people reach for multi-agent systems the moment a task feels complex. That’s usually the wrong instinct.
|
||||
|
||||
The real question isn’t “should I use multiple agents?” It’s “what kind of coordination does this task actually need?”
|
||||
|
||||
That answer determines everything about your architecture.
|
||||
|
||||
Claude-style systems give you two distinct approaches: sub-agents and agent teams. They may look similar, but they solve completely different problems.
|
||||
|
||||

|
||||
|
||||
Sub-Agents: Parallelism with Isolation
|
||||
|
||||
A sub-agent is a specialized instance that runs in its own isolated context. Think of it like delegation. You assign focused work, it returns a clean result.
|
||||
|
||||
Each sub-agent gets:
|
||||
|
||||
A system prompt defining its role
|
||||
|
||||
A limited set of tools
|
||||
|
||||
A completely isolated context
|
||||
|
||||
A single, well-scoped task
|
||||
|
||||

|
||||
|
||||
When it finishes, it returns only the final output, not reasoning or intermediate steps.
|
||||
|
||||
This matters because sub-agents are about compression, not just speed. They turn messy exploration into a clean signal.
|
||||
|
||||
There are strict constraints:
|
||||
|
||||
Sub-agents cannot talk to each other
|
||||
|
||||
Sub-agents cannot spawn new agents
|
||||
|
||||
Everything flows through the parent
|
||||
|
||||
This keeps the system predictable and clean.
|
||||
|
||||
Here’s what it looks like in practice:
|
||||
|
||||
```python
|
||||
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
|
||||
|
||||
async def main():
|
||||
async for message in query(
|
||||
prompt="Review the authentication module for issues",
|
||||
options=ClaudeAgentOptions(
|
||||
allowed_tools=["Read", "Grep", "Glob", "Agent"],
|
||||
agents={
|
||||
"security-reviewer": AgentDefinition(
|
||||
description="Find vulnerabilities and security risks",
|
||||
prompt="You are a security expert.",
|
||||
tools=["Read", "Grep", "Glob"],
|
||||
model="sonnet",
|
||||
),
|
||||
"performance-optimizer": AgentDefinition(
|
||||
description="Identify performance bottlenecks",
|
||||
prompt="You are a performance engineer.",
|
||||
tools=["Read", "Grep", "Glob"],
|
||||
model="sonnet",
|
||||
),
|
||||
},
|
||||
),
|
||||
):
|
||||
print(message)
|
||||
```
|
||||
|
||||
The key detail is the description field. It acts as a routing signal.
|
||||
|
||||
Agent Teams: Coordination Through Communication
|
||||
|
||||
Agent teams are built for collaboration. Instead of isolated workers, you have agents that maintain context, communicate, and adapt in real time.
|
||||
|
||||
They include:
|
||||
|
||||
A lead agent that assigns and synthesizes
|
||||
|
||||
Teammates that execute tasks
|
||||
|
||||
A shared task layer that tracks progress and dependencies
|
||||
|
||||

|
||||
|
||||
This allows real coordination. A frontend agent can signal backend changes and things update instantly.
|
||||
|
||||
The Core Difference
|
||||
|
||||
Sub-agents and agent teams are fundamentally different.
|
||||
|
||||
Sub-agents are execution-focused:
|
||||
|
||||
Isolated
|
||||
|
||||
Stateless
|
||||
|
||||
One-shot
|
||||
|
||||
Parent-controlled
|
||||
|
||||
Agent teams are collaboration-focused:
|
||||
|
||||
Persistent
|
||||
|
||||
Interactive
|
||||
|
||||
Context-sharing
|
||||
|
||||
Peer-to-peer
|
||||
|
||||
Use sub-agents when tasks are independent. Use teams when tasks depend on each other.
|
||||
|
||||
Where Most People Go Wrong
|
||||
|
||||
Most systems are split by roles like planner, developer, tester. This creates context loss at every handoff.
|
||||
|
||||
The implementer doesn’t know what the planner knew
|
||||
|
||||
The tester doesn’t know what the implementer decided
|
||||
|
||||
Quality drops at every boundary.
|
||||
|
||||
The better approach is context-based decomposition.
|
||||
|
||||

|
||||
|
||||
Ask: What information does this task actually need?
|
||||
|
||||
If two tasks share deep context, keep them in the same agent. Split only when context can be cleanly separated.
|
||||
|
||||
The 5 Patterns That Actually Matter
|
||||
|
||||
1\. Prompt chaining — sequential steps
|
||||
|
||||

|
||||
|
||||
2\. Routing — send tasks to the right agent
|
||||
|
||||
3\. Parallelization — run independent work together
|
||||
|
||||
4\. Orchestrator–worker — one agent delegates
|
||||
|
||||
5\. Evaluator–optimizer — generate and refine
|
||||
|
||||
When Not to Use Multi-Agent Systems
|
||||
|
||||
Sometimes a single agent is enough
|
||||
|
||||
Use multi-agent systems when:
|
||||
|
||||
You need context isolation
|
||||
|
||||
You have parallel tasks
|
||||
|
||||
You need specialization
|
||||
|
||||
Avoid them when:
|
||||
|
||||
Agents depend heavily on each other
|
||||
|
||||
Coordination overhead is too high
|
||||
|
||||
The task is simple
|
||||
|
||||
Final Principle
|
||||
|
||||
Design around context boundaries, not roles. Start simple and add complexity only when needed.
|
||||
@@ -0,0 +1,106 @@
|
||||
---
|
||||
title: "Systems Engineering: Building Agentic Software That Works"
|
||||
source: "https://x.com/ashpreetbedi/status/2041568919085854847"
|
||||
author:
|
||||
- "[[@ashpreetbedi]]"
|
||||
published: 2026-04-08
|
||||
created: 2026-04-26
|
||||
description: "In the early 1940s, Bell Labs was building the national telephone network, the most complex technical system in the world at the time. Milli..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
In the early 1940s, Bell Labs was building the national telephone network, the most complex technical system in the world at the time. Millions of switches, cables, relays, and operators had to work together. The engineers discovered something that would become an 80-year-old lesson: you can't optimize a system by optimizing individual components. The behavior of the whole (call routing, reliability, capacity, cost) emerged from how the parts interacted. They needed a discipline focused on the interactions between components.
|
||||
|
||||
They called it systems engineering.
|
||||
|
||||
The agentic software ecosystem is repeating the same mistakes that spawned that discipline. The current wave of harness engineering will ask you to use the filesystem for storage and memory, then try to get around its limitations by building a virtualized file system over a database. It'll ask you to use bash as a general-purpose tool, then force you into per-request sandboxes to handle security. These are symptoms of optimizing one part without considering the system as a whole. And we're buying into it without taking a minute to ask if it's the right approach.
|
||||
|
||||
# Software Engineering Is Systems Engineering
|
||||
|
||||
Coding agents have lowered the barrier to writing code, but they haven't lowered the requirements of production software. Software engineering is, and has always been, systems engineering and if you're building agentic software, your system needs to bridge these five layers:
|
||||
|
||||
**1\. Agent Engineering**: Your agent or multi-agent logic and execution flow.
|
||||
|
||||
Model, system instructions, tool configurations, handoffs, context management, observability. This is where you define what your agent does, how it runs and how it responds. Your agent's behavior should be deterministic where possible and observable where it isn't.
|
||||
|
||||
**2\. Data Engineering**: Your agent is only as good as the context it has access to, and context is just data under the hood. Memory, storage, knowledge: all should be managed with data engineering principles. This means well designed schemas, structured querying, databases for fast read/writes, object storage for long-term storage, and pipelines that keep your knowledge and memory up to date. The patterns are decades old. Use them.
|
||||
|
||||
**3\. Security Engineering**: Auth, RBAC, governance, data isolation, audit trails.
|
||||
|
||||
Your agent's capabilities are defined by its tools, and those tools should be scoped with JWT-backed permissions. Read-only access IS NOT a prompt instruction, it's a tool configuration. Actions should have approval tiers: reads run freely, writes need user approval, sensitive operations need admin sign-off. Most actions should be logged and queryable for the life of the product.
|
||||
|
||||
And please, isolate requests. One user's context bleeding into another's is a data breach, not a bug. It has serious consequences and there are laws protecting user data. So filesystem backed memory on a shared sandbox might not be a good idea.
|
||||
|
||||
**4\. Interface Engineering**: How users and other agents reach your agent.
|
||||
|
||||
REST API, Slack, MCP server, terminal. In the old world, you had one API and one client. Now you have multiple surfaces, each with its own identity system. A Slack user ID is not your product's user ID. An MCP client authenticating as another agent is not a human user. Interface engineering is about making sure your auth, policies, and access controls hold consistently across every surface your agent is reachable from.
|
||||
|
||||
**5\. Infrastructure Engineering**: How you run and scale your software. Containers, cloud deployment, horizontal scaling. Generally called DevOps.
|
||||
|
||||
The good news: 95% of this is identical to running any other service. Re-use existing patterns, they'll serve you well. The 5% that's different: agent requests take longer (increase your load balancer timeouts), responses stream (plan for SSE or WebSockets), and the best agents are proactive (scheduled tasks, background execution). None of this is new.
|
||||
|
||||
The key unlock for AI engineers is realizing that agentic software is just regular software, with the business logic replaced by agents, and interfaces going from request/response to streaming across multiple surfaces.
|
||||
|
||||
Systems engineering is the discipline of making these parts work together, and is the key to building agentic software that works.
|
||||
|
||||
When you look at your software from a systems perspective, the right decisions become obvious and you stop debating MCP vs CLI. You give your agent well-scoped tools, not unfettered bash access. You store sessions, memory, and knowledge in a database, not files.
|
||||
|
||||
When you design one layer in isolation, you inherit constraints that cascade through the rest of the system and you waste time and resources patching those constraints. When you design from the system's perspective, each layer reinforces the others.
|
||||
|
||||
# Systems Engineering in Practice
|
||||
|
||||
I can't make a claim this big and not give you working code.
|
||||
|
||||
[Dash is an open-source, self-learning data agent](https://github.com/agno-agi/dash). You ask it questions in plain English, it writes SQL, runs it, and tells you what the numbers mean. Simple enough to clone and adapt. Real enough to demonstrate all five layers.
|
||||
|
||||
Here's how each layer works in dash:
|
||||
|
||||
## Agent Engineering
|
||||
|
||||
Dash is a team of agents. A Leader routes requests to two specialists: an Analyst that queries data (read-only) and an Engineer that builds computed assets like views and summary tables. Each specialist gets the same tool types wired to different capabilities. The Analyst's SQL tools connect to a read-only database engine. The Engineer's SQL tools connect to a writable engine scoped to a single schema. Same interface, different permissions, determined by configuration, not prompts. Instructions are assembled at runtime from table metadata and business rules.
|
||||
|
||||
## Data Engineering
|
||||
|
||||
**Six layers of context, and tools for learning.**
|
||||
|
||||
Raw LLMs writing SQL hit a wall fast: schemas lack meaning, types are misleading, tribal knowledge is missing, there's no way to learn from mistakes. Dash solves this with six layers of grounded context:
|
||||
|
||||
- Table metadata (schema, columns, relationships)
|
||||
- Human annotations (metrics, definitions, business rules)
|
||||
- Query patterns (SQL that is known to work)
|
||||
- Institutional knowledge (docs, wikis)
|
||||
- Learnings (error patterns and discovered fixes)
|
||||
- Runtime context (live schema inspection).
|
||||
|
||||
These layers feed two systems:
|
||||
|
||||
- The first is curated knowledge: table schemas, validated queries, and business rules loaded into PostgreSQL.
|
||||
- The second is discovered learnings: error patterns and fixes that the agent saves when it hits problems and recalls on future queries.
|
||||
|
||||
The learning loop is simple: the agent runs a query, gets a type error, diagnoses the fix, saves it. Next time it sees a similar column, it gets it right the first time. And when the Engineer creates a new view, it records the schema and example queries into the knowledge base. The Analyst discovers it on the next search and starts using it. Query 100 is better than query 1, not because the model improved, but because the data layer got better.
|
||||
|
||||
## Security Engineering
|
||||
|
||||
**Enforced by the system, not the prompt.**
|
||||
|
||||
Dash in production uses RBAC with JWT verification. Every query is scoped to \`user\_id\`. An eval suite tests these boundaries directly: it prompts the agents to leak credentials, execute destructive SQL, and cross schema boundaries, then verifies they can't.
|
||||
|
||||
Security is a system property tested across layers. The Analyst's read-only access is a PostgreSQL connection parameter. The database itself rejects writes regardless of what the model generates. The Engineer can write, but only to a single schema: a query-level guard blocks any operation targeting the source data.
|
||||
|
||||
## Interface Engineering
|
||||
|
||||
Dash is available as a REST API, a Slack bot, a web UI, and a CLI. Each surface handles identity differently: Slack maps thread timestamps to sessions, the API uses JWT tokens in production. But all four hit the same agents, same tools, same knowledge.
|
||||
|
||||
Your auth and access controls need to hold across every surface, because the agent doesn't know which one it's being called from.
|
||||
|
||||
## Infrastructure Engineering
|
||||
|
||||
Minimal python container. Docker compose for local development. Deploy to your cloud of choice. Streaming via SSE through a standard ASGI server. The 95% that's identical to any other service is identical. The 5% that's different (longer timeouts, streaming, scheduled tasks) is handled with standard tools.
|
||||
|
||||
You can clone it, run \`docker compose up\`, and have the entire system.
|
||||
|
||||
One command, five layers, a working product thanks to systems engineering.
|
||||
|
||||
Here's the link for reference: [https://github.com/agno-agi/dash](https://github.com/agno-agi/dash)
|
||||
@@ -0,0 +1,530 @@
|
||||
---
|
||||
title: "THE COMPLETE GUIDE TO TRADING WEATHER MARKETS LIKE A QUANT"
|
||||
source: "https://x.com/polydao/status/2041113454023475370"
|
||||
author:
|
||||
- "[[@polydao]]"
|
||||
published: 2026-02-09
|
||||
created: 2026-04-26
|
||||
description: "One trader turned $100 into $5,000 trading the weather. Another one runs a fully automated bot that prints five figures a month. A third qui..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
One trader turned $100 into $5,000 trading the weather. Another one runs a fully automated bot that prints five figures a month. A third quit his job to do it full-time.
|
||||
|
||||
The market they use? It's been sitting right there on Polymarket - and 99% of users scroll past it every day.
|
||||
|
||||
> Weather is not vibes. It's physics, data, and public forecast models that update every 6 hours. While the crowd guesses from a phone app, a small group of quant-minded traders built systematic edges on top of NOAA and Open-Meteo APIs - and quietly farmed serious money.
|
||||
|
||||
**This piece breaks down exactly how they do it:**
|
||||
|
||||
- Who the main weather traders are and what their P&L looks like
|
||||
- How Polymarket weather markets actually work (mechanics, buckets, edge)
|
||||
- The full tool stack: forecast APIs, visual models, Polymarket data
|
||||
- Working Python code to build your own edge-detection system
|
||||
|
||||

|
||||
|
||||
# 1\. Where the money is: Polymarket weather 101
|
||||
|
||||
## 1.1 Types of weather markets
|
||||
|
||||
On Polymarket you trade outcome shares: each contract goes from 0 to 1, and resolves at 1 if the outcome happens, 0 otherwise.
|
||||
|
||||
The climate & weather vertical has three main buckets:
|
||||
|
||||
- **Daily temperature** – “Highest temperature in Shanghai on April 4?”, “Highest temperature in NYC on March 31?”, etc.
|
||||
- **Short‑term events** – “Where will it snow this December?”, specific cold waves/heatwaves.
|
||||
- **Climate milestones** – “Will 2025 be the hottest year on record?”, seasonal or yearly anomalies.
|
||||
|
||||
**In daily high markets:**
|
||||
|
||||
- You see 8-12 temperature **buckets** (for example 25°C, 26°C, 27°C, … 32°C+).
|
||||
- Each bucket trades separately; the sum of their prices roughly hovers around 1.
|
||||
- At settlement, Polymarket looks at a **specific weather station** (airport, city station) and pays 1 only on the bucket that matches the official high.
|
||||
|
||||
## 1.2 Why this niche is so clean
|
||||
|
||||
Weather has a few properties traders love:
|
||||
|
||||
- Heavy modeling by national agencies and private providers.
|
||||
- Public access to high‑quality forecasts and historical error statistics.
|
||||
- Clear resolution rules (exact station, exact time window), so you know what data matters.
|
||||
|
||||
The edge is simple:
|
||||
|
||||
> crowd trades off a single phone app, quants trade off multi‑model ensembles + scripts.
|
||||
|
||||

|
||||
|
||||
# 2\. The current weather “cartel”: who’s actually winning
|
||||
|
||||
A handful of names come up again and again in articles, leaderboards and on‑chain analytics.
|
||||
|
||||
- **neobrother** – systematic temperature ladders across global cities (Buenos Aires, Miami, Ankara, Chicago, NYC), 3 000+ daily‑high markets and 5‑figure cumulative profit Profile: [polymarket.com/@neobrother](https://polymarket.com/@neobrother?via=dao)
|
||||
|
||||

|
||||
|
||||
- **Hans323** – specializes in rare but huge tail trades; most famously Polymarket trader with 2,800+ positions Profile: [polymarket.com/@hans323](https://polymarket.com/@hans323?via=dao)
|
||||
|
||||

|
||||
|
||||
- **Handsanitizer23** – high‑precision, low‑count weather quant who flipped a sub‑4‑figure bankroll into tens of thousands with only a few dozen predictions; one viral example shows ~$600 → [$16k](https://x.com/search?q=%2416k&src=cashtag_click) on a single temperature market. Profile: [polymarket.com/@handsanitizer23](https://polymarket.com/@handsanitizer23?via=dao)
|
||||
|
||||

|
||||
|
||||
- **ColdMath** – thousands of predictions with very high long‑run win rate in temperature markets; often cited in threads as one of the most consistent weather specialists. Profile: [polymarket.com/@coldmath](https://polymarket.com/@coldmath?via=dao)
|
||||
|
||||

|
||||
|
||||
- **HondaCivic** – aggressive sizing, Top 0.01% [$1k](https://x.com/search?q=%241k&src=cashtag_click) → $ 80k; frequently referenced as part of the “weather cartel” on X. Profile: [polymarket.com/@hondacivic](https://polymarket.com/@hondacivic?via=dao) Profile 2: [polymarket.com/@hondacivic2](https://polymarket.com/@hondacivic2?via=dao)
|
||||
|
||||

|
||||
|
||||

|
||||
|
||||
- **BeefSlayer** – diversified but heavily skewed to weather, strong accuracy across dozens of cities; long‑form breakdowns show him alongside ColdMath and HondaCivic as a core weather quant. Profile: [polymarket.com/@beefslayer](https://polymarket.com/@beefslayer?via=dao)
|
||||
|
||||

|
||||
|
||||
- **Bots (e.g. automated AI trading bot)** – fully automated Clawdbot‑style systems with several thousand weather predictions and 5‑figure PnL, proving that a small statistical edge plus automation scales well. Covered in multiple exchange and community articles about weather bots.
|
||||
|
||||
# 3\. Playbook: how they actually trade weather
|
||||
|
||||
## 3.1 Temperature laddering (neobrother style)
|
||||
|
||||
Think of laddering as trading **a band** instead of a point.
|
||||
|
||||
**Typical setup described in Odaily / KuCoin pieces:**
|
||||
|
||||
- Market: “Highest temperature in Buenos Aires on March 10?”
|
||||
- Buckets: 24°C, 25°C, 26°C, 27°C, 28°C, 29°C+.
|
||||
- Model distribution says “most likely 26–28°C, long right tail”.
|
||||
|
||||
**What a ladder trader does:**
|
||||
|
||||
- Buys small size in 25°C, 26°C, 27°C, 28°C, 29°C+ at very cheap prices (often 0.7–5¢ per share).
|
||||
- Sizes a bit larger in the bucket where **probability minus price** gap is largest.
|
||||
- Accepts that 3–4 legs will expire worthless, because the winner bought at 1–5¢ pays out at 1.
|
||||
|
||||
One hit at 0.7¢ → 1.00 is a multiple of ~142× on that leg; even with several small losses the ladder as a whole is positive EV.
|
||||
|
||||
> Laddering = smoothing variance while still hunting for big multiples.
|
||||
|
||||

|
||||
|
||||
## 3.2 Bots and “Clawbot” systems
|
||||
|
||||
Community guides show a fairly standard architecture for weather bots:
|
||||
|
||||
1. **Data layer** Pull forecast data from APIs (NOAA, Open‑Meteo, ECMWF/C3S).
|
||||
2. **Model layer** Convert forecast into probabilities per bucket.
|
||||
3. **Execution layer** Watch Polymarket prices via API / WebSocket. When price << probability (by some threshold), place buy orders. Optionally sell overpriced buckets.
|
||||
|
||||
Bots like automated AI trading bot show thousands of weather predictions and 5‑figure realized profit just from repeating this logic.
|
||||
|
||||
> 2月9日
|
||||
|
||||
# 4\. The tool stack: sites, maps, APIs – and code
|
||||
|
||||
## 4.1 Forecast APIs & data sources
|
||||
|
||||
These are the workhorses behind most serious systems:
|
||||
|
||||
- **NOAA / National Weather Service API** – [https://api.weather.gov](https://api.weather.gov/) Forecasts and grid data for US locations, official government source.
|
||||
- **Open‑Meteo** – [https://open-meteo.com](https://open-meteo.com/) Free, open‑source API aggregating multiple models; includes historical and forecast data, no API key needed.
|
||||
- **ECMWF / Copernicus Climate Data Store (C3S)** – [https://cds.climate.copernicus.eu](https://cds.climate.copernicus.eu/) Access to ECMWF ensemble forecasts and seasonal products, good for distribution tails.
|
||||
- **Commercial APIs** ([Tomorrow.io](https://tomorrow.io/), Meteomatics, etc.) Paid, high‑resolution forecasts used by energy traders; relevant once size and seriousness justify the spend.
|
||||
|
||||
**Minimal Python example: pulling a forecast from Open‑Meteo.**
|
||||
|
||||
```python
|
||||
import requests
|
||||
import pandas as pd
|
||||
|
||||
LAT, LON = 40.7812, -73.9665 # Example: NYC
|
||||
|
||||
url = "https://api.open-meteo.com/v1/forecast"
|
||||
params = {
|
||||
"latitude": LAT,
|
||||
"longitude": LON,
|
||||
"hourly": "temperature_2m",
|
||||
"forecast_days": 2,
|
||||
"timezone": "UTC",
|
||||
}
|
||||
|
||||
resp = requests.get(url, params=params, timeout=10)
|
||||
resp.raise_for_status()
|
||||
data = resp.json()
|
||||
|
||||
hourly = pd.DataFrame(data["hourly"])
|
||||
hourly["time"] = pd.to_datetime(hourly["time"])
|
||||
|
||||
print(hourly.head())
|
||||
```
|
||||
|
||||
## 4.2 Visual model viewers
|
||||
|
||||
For intuition and manual checks:
|
||||
|
||||
- [Windy.com](https://windy.com/) Multi‑model viewer (ECMWF, GFS, ICON, etc.), animated global maps of temperature, wind, precipitation.
|
||||
- [Ventusky](https://www.ventusky.com/) Interactive weather map with dozens of layers; especially good for visualizing temperature and precipitation fields.
|
||||
- [Windy.app](https://windy.app/) – [https://windy.app](https://windy.app/) Focused on sports but exposes multiple forecast models and quick comparison by location.
|
||||
|
||||
**Practical workflow:**
|
||||
|
||||
- Script says “Chicago bucket 7 is cheap.”
|
||||
- Open Windy / Ventusky at that time to see if synoptic picture supports the trade.
|
||||
|
||||

|
||||
|
||||
## 4.3 Polymarket side: data & execution
|
||||
|
||||
To connect your weather insight to actual positions:
|
||||
|
||||
- Use [Polymarket docs & APIs](https://docs.polymarket.com/api-reference/introduction) for market discovery and order routing.
|
||||
- Watch live prices via WebSockets to catch moves after model updates.
|
||||
- Track leaderboards in the **Climate & Weather** category to see who is consistently profitable and how many trades they run.
|
||||
|
||||
The clean public route is to use the **Gamma API** and fetch the market by slug.
|
||||
|
||||
```python
|
||||
import requests
|
||||
import json
|
||||
|
||||
GAMMA_BASE = "https://gamma-api.polymarket.com"
|
||||
|
||||
def fetch_market_by_slug(slug: str) -> dict:
|
||||
url = f"{GAMMA_BASE}/markets"
|
||||
params = {
|
||||
"slug": slug,
|
||||
"active": "true",
|
||||
}
|
||||
resp = requests.get(url, params=params, timeout=10)
|
||||
resp.raise_for_status()
|
||||
markets = resp.json()
|
||||
|
||||
if not markets:
|
||||
raise ValueError(f"No markets found for slug: {slug}")
|
||||
|
||||
return markets[0]
|
||||
|
||||
def fetch_outcome_prices(slug: str) -> dict:
|
||||
market = fetch_market_by_slug(slug)
|
||||
|
||||
outcomes = json.loads(market["outcomes"])
|
||||
prices = json.loads(market["outcomePrices"])
|
||||
|
||||
return {
|
||||
outcome: float(price)
|
||||
for outcome, price in zip(outcomes, prices)
|
||||
}
|
||||
```
|
||||
|
||||
# 5\. Building a real edge: step‑by‑step (with code)
|
||||
|
||||
## 5.1 Pick a small universe
|
||||
|
||||
**Start narrow:**
|
||||
|
||||
- 2–3 cities you understand seasonally (for example NYC, Chicago, Dallas).
|
||||
- Only daily‑high markets for the next 1–3 days.
|
||||
|
||||
**Reasons:**
|
||||
|
||||
- Faster feedback loop.
|
||||
- You see how models behave in different regimes for the **same** geography.
|
||||
|
||||
## 5.2 Turn forecasts into bucket probabilities
|
||||
|
||||
Now that you have hourly temperatures, the simplest first approximation is:
|
||||
|
||||
- take the forecast daily max,
|
||||
- assume some forecast uncertainty,
|
||||
- simulate a distribution around that value,
|
||||
- integrate that distribution across market buckets.
|
||||
|
||||
Example: quick‑and‑dirty Monte Carlo around the day’s forecast maximum.
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
import pandas as pd
|
||||
|
||||
market_date = hourly["time"].dt.date.iloc[0]
|
||||
day = hourly[hourly["time"].dt.date == market_date]
|
||||
|
||||
point_forecast = day["temperature_2m"].max()
|
||||
sigma = 1.5 # assumed forecast error in °C
|
||||
|
||||
bucket_specs = [
|
||||
((24, 25), "24°C"),
|
||||
((25, 26), "25°C"),
|
||||
((26, 27), "26°C"),
|
||||
((27, 28), "27°C"),
|
||||
((28, 29), "28°C"),
|
||||
((29, 100), "28°C or higher"),
|
||||
]
|
||||
|
||||
def bucket_probability(lo, hi, mu, sigma, n=50000):
|
||||
samples = np.random.normal(mu, sigma, size=n)
|
||||
return ((samples >= lo) & (samples < hi)).mean()
|
||||
|
||||
rows = []
|
||||
for (lo, hi), label in bucket_specs:
|
||||
p = bucket_probability(lo, hi, point_forecast, sigma)
|
||||
rows.append({
|
||||
"outcome": label,
|
||||
"model_prob": p,
|
||||
})
|
||||
|
||||
prob_df = pd.DataFrame(rows)
|
||||
prob_df["model_prob"] = prob_df["model_prob"] / prob_df["model_prob"].sum()
|
||||
|
||||
print(prob_df)
|
||||
```
|
||||
|
||||
> **Important detail:** the labels in bucket\_specs should match the exact outcome labels in the Polymarket market you are studying. If they do not match, your map() step later will fail.
|
||||
|
||||
## 5.3 Compare probabilities with Polymarket prices
|
||||
|
||||
Once you have model probabilities and fetched market prices, the comparison is simple.
|
||||
|
||||
```python
|
||||
slug = "highest-temperature-in-nyc-on-april-2-2026"
|
||||
|
||||
pm_prices = fetch_outcome_prices(slug)
|
||||
|
||||
prob_df["market_price"] = prob_df["outcome"].map(pm_prices)
|
||||
prob_df["edge"] = prob_df["model_prob"] - prob_df["market_price"]
|
||||
|
||||
edges = prob_df.sort_values("edge", ascending=False)
|
||||
print(edges)
|
||||
```
|
||||
|
||||
That gives you the core output that matters:
|
||||
|
||||
- what your model thinks,
|
||||
- what the market implies,
|
||||
- and where the spread is biggest.
|
||||
|
||||
That spread is your potential edge.
|
||||
|
||||
## 5.4 First trades: manual laddering
|
||||
|
||||
Before automation, you want intuition.
|
||||
|
||||
**For each market:**
|
||||
|
||||
- Identify 3-6 buckets where probability minus price is positive.
|
||||
- Size them so that: Worst case: all expire at 0 → still tiny % of bankroll. Typical case: one big winner repays the rest + profit.
|
||||
|
||||
Think in **series of markets**, not one‑off hero calls.
|
||||
|
||||
## 5.5 Logging results into your own dataset
|
||||
|
||||
Even if trades are manual, logging should be automatic.
|
||||
|
||||
```python
|
||||
from pathlib import Path
|
||||
import csv
|
||||
from datetime import datetime
|
||||
|
||||
LOG_PATH = Path("weather_polymarket_log.csv")
|
||||
|
||||
def log_market(city, market_date, bucket, prob, price, edge, final_bucket=None):
|
||||
is_new = not LOG_PATH.exists()
|
||||
|
||||
with LOG_PATH.open("a", newline="") as f:
|
||||
writer = csv.writer(f)
|
||||
|
||||
if is_new:
|
||||
writer.writerow([
|
||||
"timestamp",
|
||||
"city",
|
||||
"market_date",
|
||||
"bucket",
|
||||
"model_prob",
|
||||
"market_price",
|
||||
"edge",
|
||||
"final_bucket",
|
||||
])
|
||||
|
||||
writer.writerow([
|
||||
datetime.utcnow().isoformat(),
|
||||
city,
|
||||
market_date.isoformat(),
|
||||
bucket,
|
||||
round(prob, 4),
|
||||
round(price, 4),
|
||||
round(edge, 4),
|
||||
final_bucket or "",
|
||||
])
|
||||
|
||||
best = edges.iloc[0]
|
||||
log_market(
|
||||
city="NYC",
|
||||
market_date=market_date,
|
||||
bucket=best["outcome"],
|
||||
prob=best["model_prob"],
|
||||
price=best["market_price"],
|
||||
edge=best["edge"],
|
||||
)
|
||||
```
|
||||
|
||||
## 5.6 Semi‑automatic alert loop
|
||||
|
||||
Before a full bot, build a monitor. **This version is intentionally simple:**
|
||||
|
||||
```python
|
||||
import time
|
||||
import requests
|
||||
import json
|
||||
import numpy as np
|
||||
import pandas as pd
|
||||
|
||||
GAMMA_BASE = "https://gamma-api.polymarket.com"
|
||||
|
||||
def fetch_market_by_slug(slug: str) -> dict:
|
||||
url = f"{GAMMA_BASE}/markets"
|
||||
params = {
|
||||
"slug": slug,
|
||||
"active": "true",
|
||||
}
|
||||
resp = requests.get(url, params=params, timeout=10)
|
||||
resp.raise_for_status()
|
||||
markets = resp.json()
|
||||
|
||||
if not markets:
|
||||
raise ValueError(f"No markets found for slug: {slug}")
|
||||
|
||||
return markets[0]
|
||||
|
||||
def fetch_outcome_prices(slug: str) -> dict:
|
||||
market = fetch_market_by_slug(slug)
|
||||
outcomes = json.loads(market["outcomes"])
|
||||
prices = json.loads(market["outcomePrices"])
|
||||
return {outcome: float(price) for outcome, price in zip(outcomes, prices)}
|
||||
|
||||
def fetch_hourly_forecast(lat: float, lon: float) -> pd.DataFrame:
|
||||
url = "https://api.open-meteo.com/v1/forecast"
|
||||
params = {
|
||||
"latitude": lat,
|
||||
"longitude": lon,
|
||||
"hourly": "temperature_2m",
|
||||
"forecast_days": 1,
|
||||
"timezone": "UTC",
|
||||
}
|
||||
resp = requests.get(url, params=params, timeout=10)
|
||||
resp.raise_for_status()
|
||||
data = resp.json()
|
||||
|
||||
hourly = pd.DataFrame(data["hourly"])
|
||||
hourly["time"] = pd.to_datetime(hourly["time"])
|
||||
return hourly
|
||||
|
||||
def build_probability_table(hourly: pd.DataFrame, bucket_specs, sigma=1.5) -> pd.DataFrame:
|
||||
market_date = hourly["time"].dt.date.iloc[0]
|
||||
day = hourly[hourly["time"].dt.date == market_date]
|
||||
point_forecast = day["temperature_2m"].max()
|
||||
|
||||
def bucket_probability(lo, hi, mu, sigma, n=50000):
|
||||
samples = np.random.normal(mu, sigma, size=n)
|
||||
return ((samples >= lo) & (samples < hi)).mean()
|
||||
|
||||
rows = []
|
||||
for (lo, hi), label in bucket_specs:
|
||||
p = bucket_probability(lo, hi, point_forecast, sigma)
|
||||
rows.append({
|
||||
"outcome": label,
|
||||
"model_prob": p,
|
||||
})
|
||||
|
||||
df = pd.DataFrame(rows)
|
||||
df["model_prob"] = df["model_prob"] / df["model_prob"].sum()
|
||||
return df
|
||||
|
||||
def compute_edges(slug: str, lat: float, lon: float, bucket_specs):
|
||||
hourly = fetch_hourly_forecast(lat, lon)
|
||||
prob_df = build_probability_table(hourly, bucket_specs)
|
||||
pm_prices = fetch_outcome_prices(slug)
|
||||
|
||||
prob_df["market_price"] = prob_df["outcome"].map(pm_prices)
|
||||
prob_df["edge"] = prob_df["model_prob"] - prob_df["market_price"]
|
||||
|
||||
return prob_df.sort_values("edge", ascending=False)
|
||||
|
||||
slug = "highest-temperature-in-nyc-on-april-2-2026"
|
||||
LAT, LON = 40.7812, -73.9665
|
||||
|
||||
bucket_specs = [
|
||||
((24, 25), "24°C"),
|
||||
((25, 26), "25°C"),
|
||||
((26, 27), "26°C"),
|
||||
((27, 28), "27°C"),
|
||||
((28, 29), "28°C"),
|
||||
((29, 100), "28°C or higher"),
|
||||
]
|
||||
|
||||
while True:
|
||||
edges = compute_edges(slug, LAT, LON, bucket_specs)
|
||||
print(edges[["outcome", "model_prob", "market_price", "edge"]].head())
|
||||
time.sleep(60 * 30)
|
||||
```
|
||||
|
||||
This is probably the strongest code block for the article because it demonstrates the full loop:
|
||||
|
||||
- weather forecast,
|
||||
- Polymarket prices,
|
||||
- probability model,
|
||||
- edge ranking.
|
||||
|
||||
And it does it without pretending to place orders
|
||||
|
||||
## 6\. Risks, moving edges, and why this still matters
|
||||
|
||||
**Real talk checklist:**
|
||||
|
||||
- **Model error:** fronts shift, storms pop up, micro‑climates ruin clean distributions.
|
||||
- **Liquidity:** some city markets are thin; your own orders can move the price.
|
||||
- **Platform risk:** smart‑contract, custody and regulatory risk around on‑chain markets.
|
||||
- **Crowding:** every article like this pushes more quants into the niche; edges compress over time.
|
||||
|
||||

|
||||
|
||||
**The upside:**
|
||||
|
||||
- As long as most participants use one weather app and intuition, and only a minority plug into NOAA/Open‑Meteo/ECMWF with scripts, there will be mispricings.
|
||||
- Weather is one of the rare places where you can go from “tourist” to “local pro” mostly by doing homework and building a small tool stack.
|
||||
|
||||
## 7\. TL;DR playbook
|
||||
|
||||
If you skimmed everything, here’s the compressed version:
|
||||
|
||||
1. Go to [polymarket.com/weather](https://polymarket.com/weather?via=dao) and pick 2–3 cities
|
||||
2. Pull forecasts from **NOAA** / **Open‑Meteo** for those exact stations
|
||||
3. Convert forecasts into bucket probabilities (the Monte Carlo snippet above is enough for v1)
|
||||
4. Ladder into the underpriced buckets instead of aiming for one exact number
|
||||
5. Log everything. After 50-100 markets, keep only what works net of fees
|
||||
6. Automate data pulls and alerts; only then think about full bots
|
||||
7. Keep tails small, but do not ignore them – that’s where Hans323‑style payoffs live
|
||||
|
||||
> That’s the path that turned weather from background noise into a serious on‑chain edge for traders like neobrother, Handsanitizer23, ColdMath, HondaCivic and BeefSlayer – and it’s still open to anyone willing to build the stack instead of guessing.
|
||||
|
||||
<video preload="auto" tabindex="-1" playsinline="" aria-label="嵌入式视频" poster="https://pbs.twimg.com/tweet_video_thumb/HFFV7m3WoAA5aGl.jpg" src="https://video.twimg.com/tweet_video/HFFV7m3WoAA5aGl.mp4" type="video/mp4" style="width: 100%; height: 100%; position: absolute; background-color: black; top: 0%; left: 0%; transform: rotate(0deg) scale(1.005);"></video>
|
||||
|
||||

|
||||
|
||||
GIF
|
||||
|
||||
## Want to start without building the stack yourself?
|
||||
|
||||
The traders in this article are live on Kreo - a copy-trading platform where you can mirror their weather positions in real time.
|
||||
|
||||
- Follow the top weather traders directly: [kreo.app/@trade](https://kreo.app/@trade)
|
||||
|
||||
You'll see their open positions, win rates, and track record. One click to copy.
|
||||
|
||||
> If you found this useful - follow me [@polydao](https://x.com/polydao) for daily alpha on Polymarket: market breakdowns, trader profiles, and the strategies that actually work.
|
||||
|
||||
I cover weather markets, political contracts, and the quant edges most people miss. Drop a like if this helped - it tells me to write more of this.
|
||||
@@ -0,0 +1,343 @@
|
||||
---
|
||||
title: "The .gitignore That Saves Your Career (Full File Included)"
|
||||
source: "https://x.com/zodchiii/status/2050505359584788850"
|
||||
author:
|
||||
- "[[@zodchiii]]"
|
||||
published: 2026-05-02
|
||||
created: 2026-05-02
|
||||
description: "Anthropic leaked 512,000 lines of their own source code because someone forgot to add one line to an ignore file. If it happens to them, it'..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
Anthropic leaked 512,000 lines of their own source code because someone forgot to add one line to an ignore file. If it happens to them, it's happening to you.
|
||||
|
||||
Within hours the code was mirrored on GitHub and got 50,000 stars in two hours, likely the fastest-growing repository in GitHub history.
|
||||
|
||||
Your .gitignore is probably a template you copied on day one and never touched.
|
||||
|
||||
Here's what actually needs to be in it 👇
|
||||
|
||||
Before we dive in, I share daily notes on AI & vibe coding in my Telegram channel: [https://t.me/zodchixquant](https://t.me/zodchixquant)🧠
|
||||
|
||||

|
||||
|
||||
## Why default .gitignore templates aren't enough
|
||||
|
||||
GitHub's default templates cover the basics: node\_modules, **pycache**, .DS\_Store. They were written before AI coding tools existed.
|
||||
|
||||
In 2026 your project has new files that didn't exist two years ago:
|
||||
|
||||
```text
|
||||
.claude/ → Claude Code settings with API tokens in shell commands
|
||||
.cursor/ → Cursor AI rules and configs
|
||||
.aider* → Aider chat history and configs
|
||||
.env → everyone knows this one, but...
|
||||
.env.local → ...most people forget this one
|
||||
.env.development → ...and this one
|
||||
.env.production → ...especially this one
|
||||
```
|
||||
|
||||
The **.claude/** directory is the newest threat. Claude Code stores your **settings.json** there, and if you've pre-approved bash commands with API tokens in them, those tokens are now sitting in a file that gets packaged into npm, PyPI, and RubyGems by default.
|
||||
|
||||
Lakera security researchers confirmed this in April 2026: build tools for Python, Ruby, and JavaScript all package files from your project directory.
|
||||
|
||||
If **.claude/** isn't in your ignore file, your approved shell commands with embedded secrets ship to the public registry.
|
||||
|
||||
## The files that actually leak
|
||||
|
||||
Based on real incidents from the past 12 months:
|
||||
|
||||
**Tier 1 - secrets that cost money immediately:**
|
||||
|
||||
```text
|
||||
.env, .env.local, .env.production, .env.development
|
||||
.claude/settings.json (contains pre-approved commands with tokens)
|
||||
*.pem, *.key (SSL certificates and private keys)
|
||||
credentials.json, service-account.json (cloud provider keys)
|
||||
.npmrc, .pypirc (package registry tokens)
|
||||
```
|
||||
|
||||
**Tier 2 - secrets that enable account takeover:**
|
||||
|
||||
```text
|
||||
.aws/credentials
|
||||
.ssh/id_rsa, .ssh/config
|
||||
.docker/config.json (registry auth)
|
||||
.kube/config (cluster access)
|
||||
.terraform/terraform.tfstate (contains passwords in plaintext)
|
||||
```
|
||||
|
||||
**Tier 3 - information that shouldn't be public:**
|
||||
|
||||
```text
|
||||
.vscode/settings.json (sometimes contains tokens)
|
||||
.idea/ (JetBrains configs with database passwords)
|
||||
*.sqlite, *.db (local databases with user data)
|
||||
coverage/ (can reveal internal file paths)
|
||||
.claude/memory/ (Claude's notes about your project)
|
||||
```
|
||||
|
||||
GitGuardian's 2026 report: 29 million secrets leaked on GitHub last year. 64% of credentials leaked in 2022 were still valid in 2026. Nobody revoked them.
|
||||
|
||||
## The .gitignore rules nobody adds
|
||||
|
||||
These are the lines missing from almost every project:
|
||||
|
||||
```text
|
||||
# AI tool configs (NEW in 2025-2026)
|
||||
.claude/
|
||||
.cursor/
|
||||
.aider*
|
||||
.continue/
|
||||
.cody/
|
||||
.codex/
|
||||
```
|
||||
|
||||
Before AI coding tools, you didn't need these. Now every project has at least one AI config directory with potential secrets. Most developers add the tool, use it for weeks, and never think to update .gitignore.
|
||||
|
||||
```text
|
||||
# Environment files (all variants)
|
||||
.env
|
||||
.env.*
|
||||
!.env.example
|
||||
```
|
||||
|
||||
The !.env.example exception is important. You want to commit the template (with dummy values) so new team members know which variables to set. You don't want to commit the actual values.
|
||||
|
||||
```text
|
||||
# Cloud credentials
|
||||
.aws/
|
||||
.azure/
|
||||
.gcloud/
|
||||
.terraform/terraform.tfstate
|
||||
.terraform/terraform.tfstate.backup
|
||||
```
|
||||
|
||||
Terraform state files deserve special attention. They store your infrastructure state in plaintext, including database passwords and API keys. I've seen production database credentials sitting in public GitHub repos inside .tfstate files.
|
||||
|
||||
## The trap: .gitignore doesn't fix files already committed
|
||||
|
||||
This is the mistake that kills people. You add **.env** to .gitignore after you've already committed it. The file is still in your git history. Anyone who clones your repo can run **git log --all -- .env** and see every version.
|
||||
|
||||
Adding to .gitignore only prevents future commits. To actually remove a file from history:
|
||||
|
||||
```bash
|
||||
# Remove from tracking but keep the local file
|
||||
git rm --cached .env
|
||||
git commit -m "chore: remove .env from tracking"
|
||||
|
||||
# To remove from entire git history (nuclear option)
|
||||
# Install BFG Repo-Cleaner first
|
||||
bfg --delete-files .env
|
||||
git reflog expire --expire=now --all
|
||||
git gc --prune=now --aggressive
|
||||
git push --force
|
||||
```
|
||||
|
||||
After cleaning history, rotate every credential that was ever in that file. If your Stripe key was in git history for 3 months, assume it's been scraped. GitGuardian found that bots scan public repos within minutes of a push.
|
||||
|
||||
## The Anthropic lesson: .npmignore matters too
|
||||
|
||||
.gitignore protects your git repository. But when you publish a package, npm/PyPI/RubyGems use different ignore files:
|
||||
|
||||
```text
|
||||
npm → .npmignore (or "files" field in package.json)
|
||||
PyPI → MANIFEST.in or pyproject.toml excludes
|
||||
Ruby → .gemspec files list
|
||||
```
|
||||
|
||||
Anthropic's leak happened because they had no **.npmignore** entry for source maps. Their .gitignore was probably fine. The npm package included everything.
|
||||
|
||||
If you publish packages, always run a dry run before publishing:
|
||||
|
||||
```text
|
||||
# npm - see what gets packaged
|
||||
npm pack --dry-run
|
||||
|
||||
# Python - check your sdist
|
||||
python -m build --sdist
|
||||
tar -tzf dist/*.tar.gz | grep -E '\.env|\.claude|secret'
|
||||
```
|
||||
|
||||
## The full .gitignore (copy-paste ready)
|
||||
|
||||
## Node.js / TypeScript
|
||||
|
||||
```text
|
||||
# Dependencies
|
||||
node_modules/
|
||||
.pnp.*
|
||||
|
||||
# Build
|
||||
dist/
|
||||
build/
|
||||
.next/
|
||||
out/
|
||||
|
||||
# Environment
|
||||
.env
|
||||
.env.*
|
||||
!.env.example
|
||||
|
||||
# AI tools
|
||||
.claude/
|
||||
.cursor/
|
||||
.aider*
|
||||
.continue/
|
||||
.cody/
|
||||
.codex/
|
||||
|
||||
# Secrets & credentials
|
||||
*.pem
|
||||
*.key
|
||||
*.p12
|
||||
*.pfx
|
||||
credentials.json
|
||||
service-account*.json
|
||||
.npmrc
|
||||
.aws/
|
||||
.ssh/
|
||||
.docker/config.json
|
||||
|
||||
# IDE
|
||||
.vscode/settings.json
|
||||
.idea/
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Logs & coverage
|
||||
*.log
|
||||
coverage/
|
||||
.nyc_output/
|
||||
|
||||
# Terraform
|
||||
.terraform/
|
||||
*.tfstate
|
||||
*.tfstate.backup
|
||||
```
|
||||
|
||||
## Python
|
||||
|
||||
```text
|
||||
Python
|
||||
# Virtual environments
|
||||
venv/
|
||||
.venv/
|
||||
env/
|
||||
|
||||
# Build
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*.egg-info/
|
||||
dist/
|
||||
build/
|
||||
|
||||
# Environment
|
||||
.env
|
||||
.env.*
|
||||
!.env.example
|
||||
|
||||
# AI tools
|
||||
.claude/
|
||||
.cursor/
|
||||
.aider*
|
||||
.continue/
|
||||
.cody/
|
||||
|
||||
# Secrets & credentials
|
||||
*.pem
|
||||
*.key
|
||||
credentials.json
|
||||
service-account*.json
|
||||
.pypirc
|
||||
.aws/
|
||||
.ssh/
|
||||
|
||||
# IDE
|
||||
.vscode/settings.json
|
||||
.idea/
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
|
||||
# Jupyter
|
||||
.ipynb_checkpoints/
|
||||
|
||||
# Logs & coverage
|
||||
*.log
|
||||
htmlcov/
|
||||
.coverage
|
||||
|
||||
# Terraform
|
||||
.terraform/
|
||||
*.tfstate
|
||||
*.tfstate.backup
|
||||
```
|
||||
|
||||
## GO
|
||||
|
||||
```text
|
||||
Go
|
||||
# Binary
|
||||
bin/
|
||||
*.exe
|
||||
|
||||
# Environment
|
||||
.env
|
||||
.env.*
|
||||
!.env.example
|
||||
|
||||
# AI tools
|
||||
.claude/
|
||||
.cursor/
|
||||
.aider*
|
||||
.continue/
|
||||
|
||||
# Secrets
|
||||
*.pem
|
||||
*.key
|
||||
credentials.json
|
||||
service-account*.json
|
||||
.aws/
|
||||
.ssh/
|
||||
|
||||
# IDE
|
||||
.vscode/settings.json
|
||||
.idea/
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
|
||||
# Vendor (optional)
|
||||
# vendor/
|
||||
|
||||
# Coverage
|
||||
coverage.out
|
||||
*.prof
|
||||
```
|
||||
|
||||
## The checklist
|
||||
|
||||
Before your next push:
|
||||
|
||||
```text
|
||||
1. Is .claude/ in your .gitignore?
|
||||
2. Are ALL .env variants covered (.env, .env.*, !.env.example)?
|
||||
3. Have you checked git history for previously committed secrets?
|
||||
4. If you publish packages: do you have .npmignore / MANIFEST.in?
|
||||
5. Have you run npm pack --dry-run to see what actually ships?
|
||||
6. Are cloud credential directories (.aws/, .ssh/) excluded?
|
||||
7. Is .terraform/terraform.tfstate excluded?
|
||||
```
|
||||
|
||||
Anthropic forgot one line and leaked 512,000 lines of source code. Your .gitignore is the cheapest security investment you'll ever make. Update it today.
|
||||
|
||||
I share daily notes on AI, finance, and vibe coding in my Telegram channel: [https://t.me/zodchixquant](https://t.me/zodchixquant)
|
||||
|
||||
Thanks for reading🙏🏼
|
||||
|
||||

|
||||
@@ -1,12 +1,203 @@
|
||||
---
|
||||
title: "The Anatomy of an Agent Harness"
|
||||
source: "https://x.com/Vtrivedy10/status/2031408954517971368"
|
||||
source: "https://x.com/akshay_pachaar/status/2041146899319971922"
|
||||
author:
|
||||
- "[[Unknown]]"
|
||||
published: 2026-03-11
|
||||
created: 2026-03-11
|
||||
description:
|
||||
- "[[@akshay_pachaar]]"
|
||||
published: 2026-04-06
|
||||
created: 2026-05-04
|
||||
description: "A deep dive into what Anthropic, OpenAI, Perplexity and LangChain are actually building. Covering the orchestration loop, tools, memory, con..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||
Harness
|
||||

|
||||
|
||||
A deep dive into what Anthropic, OpenAI, Perplexity and LangChain are actually building. Covering the orchestration loop, tools, memory, context management, and everything else that transforms a stateless LLM into a capable agent.
|
||||
|
||||
You've built a chatbot. Maybe you've wired up a ReAct loop with a few tools. It works for demos. Then you try to build something production-grade, and the wheels come off: the model forgets what it did three steps ago, tool calls fail silently, and context windows fill up with garbage.
|
||||
|
||||
The problem isn't your model. It's everything around your model.
|
||||
|
||||
LangChain proved this when they changed only the infrastructure wrapping their LLM (same model, same weights) and jumped from outside the top 30 to rank 5 on TerminalBench 2.0. A separate research project hit a 76.4% pass rate by having an LLM optimize the infrastructure itself, surpassing hand-designed systems.
|
||||
|
||||
That infrastructure has a name now: **the agent harness**.
|
||||
|
||||
# What Is the Agent Harness?
|
||||
|
||||
The term was formalized in early 2026, but the concept existed long before. The harness is the complete software infrastructure wrapping an LLM: orchestration loop, tools, memory, context management, state persistence, error handling, and guardrails. Anthropic's Claude Code documentation puts it simply: the SDK is "**the agent harness that powers Claude Code.**" OpenAI's Codex team uses the same framing, explicitly equating the terms "**agent**" and "**harness**" to refer to the **non-model infrastructure** that makes the LLM useful.
|
||||
|
||||
I really liked the canonical formula, from LangChain's Vivek Trivedy: **"If you're not the model, you're the harness."**
|
||||
|
||||
Here's the distinction that trips people up. The "agent" is the emergent behavior: the goal-directed, tool-using, self-correcting entity the user interacts with. The harness is the machinery producing that behavior. When someone says "I built an agent," they mean they built a harness and pointed it at a model.
|
||||
|
||||

|
||||
|
||||
Beren Millidge made this analogy precise in his 2023 essay "[Scaffolded LLMs as Natural Language Computers.](https://www.beren.io/2023-04-11-Scaffolded-LLMs-natural-language-computers/)" A raw LLM is a CPU with no RAM, no disk, and no I/O. The context window serves as RAM (fast but limited). External databases function as disk storage (large but slow). Tool integrations act as device drivers. The harness is the operating system. As Millidge wrote: **"We have reinvented the Von Neumann architecture"** because it's a natural abstraction for any computing system.
|
||||
|
||||
# Three Levels of Engineering
|
||||
|
||||
Three concentric levels of engineering surround the model:
|
||||
|
||||
- **Prompt engineering** crafts the instructions the model receives.
|
||||
- **Context engineering** manages what the model sees and when.
|
||||
- **Harness engineering** encompasses both, plus the entire application infrastructure: tool orchestration, state persistence, error recovery, verification loops, safety enforcement, and lifecycle management.
|
||||
|
||||
The harness is not a wrapper around a prompt. It is the complete system that makes autonomous agent behavior possible.
|
||||
|
||||
# The 12 Components of a Production Harness
|
||||
|
||||
Synthesizing across Anthropic, OpenAI, LangChain, and the broader practitioner community, a production agent harness has twelve distinct components. Let's walk through each one.
|
||||
|
||||

|
||||
|
||||
## 1\. The Orchestration Loop
|
||||
|
||||
This is the heartbeat. It implements the Thought-Action-Observation (TAO) cycle, also called the ReAct loop. The loop runs: assemble prompt, call LLM, parse output, execute any tool calls, feed results back, repeat until done.
|
||||
|
||||
Mechanically, it's often just a while loop. **The complexity lives in everything the loop manages**, not the loop itself. Anthropic describes their runtime as a "dumb loop" where all intelligence lives in the model. The harness just manages turns.
|
||||
|
||||
## 2\. Tools
|
||||
|
||||
Tools are the agent's hands. They're defined as schemas (name, description, parameter types) injected into the LLM's context so the model knows what's available. The tool layer handles registration, schema validation, argument extraction, sandboxed execution, result capture, and formatting results back into LLM-readable observations.
|
||||
|
||||
Claude Code provides tools across six categories: file operations, search, execution, web access, code intelligence, and subagent spawning. OpenAI's Agents SDK supports function tools (via [@function\_tool](https://x.com/@function_tool)), hosted tools (WebSearch, CodeInterpreter, FileSearch), and MCP server tools.
|
||||
|
||||
## 3\. Memory
|
||||
|
||||
Memory operates at multiple timescales. **Short-term memory** is conversation history within a single session. **Long-term memory** persists across sessions: Anthropic uses [CLAUDE.md](http://claude.md/) project files and auto-generated [MEMORY.md](http://memory.md/) files; LangGraph uses namespace-organized JSON Stores; OpenAI supports Sessions backed by SQLite or Redis.
|
||||
|
||||
Claude Code implements a three-tier hierarchy: a lightweight index (~150 characters per entry, always loaded), detailed topic files pulled in on demand, and raw transcripts accessed via search only. A critical design principle: **the agent treats its own memory as a "hint" and verifies against actual state before acting**.
|
||||
|
||||
## 4\. Context Management
|
||||
|
||||
This is where many agents fail silently. The core problem is context rot: **model performance degrades 30%+ when key content falls in mid-window positions** (Chroma research, corroborated by Stanford's "Lost in the Middle" finding). Even million-token windows suffer from instruction-following degradation as context grows.
|
||||
|
||||
**Production strategies include:**
|
||||
|
||||
- **Compaction**: summarizing conversation history when approaching limits (Claude Code preserves architectural decisions and unresolved bugs while discarding redundant tool outputs)
|
||||
- **Observation masking**: JetBrains' Junie hides old tool outputs while keeping tool calls visible
|
||||
- **Just-in-time retrieval**: maintaining lightweight identifiers and loading data dynamically (Claude Code uses grep, glob, head, tail rather than loading full files)
|
||||
- **Sub-agent delegation**: each subagent explores extensively but returns only 1,000 to 2,000 token condensed summaries
|
||||
|
||||
Anthropic's context engineering guide states the goal: find the **smallest possible set of high-signal tokens** that maximize likelihood of the desired outcome.
|
||||
|
||||
## 5\. Prompt Construction
|
||||
|
||||
This assembles what the model actually sees at each step. It's hierarchical: system prompt, tool definitions, memory files, conversation history, and the current user message.
|
||||
|
||||
OpenAI's Codex uses a strict priority stack: server-controlled system message (highest priority), tool definitions, developer instructions, user instructions (cascading [AGENTS.md](http://agents.md/) files, 32 KiB limit), then conversation history.
|
||||
|
||||
## 6\. Output Parsing
|
||||
|
||||
Modern harnesses rely on native tool calling, where the model returns structured tool\_calls objects rather than free-text that must be parsed. The harness checks: are there tool calls? Execute them and loop. No tool calls? That's the final answer.
|
||||
|
||||
For structured outputs, both OpenAI and LangChain support schema-constrained responses via Pydantic models. Legacy approaches like RetryWithErrorOutputParser (which feeds the original prompt, the failed completion, and the parsing error back to the model) remain available for edge cases.
|
||||
|
||||
## 7\. State Management
|
||||
|
||||
LangGraph models state as typed dictionaries flowing through graph nodes, with reducers merging updates. Checkpointing happens at super-step boundaries, enabling resume after interruptions and time-travel debugging. OpenAI offers four mutually exclusive strategies: application memory, SDK sessions, server-side Conversations API, or lightweight previous\_response\_id chaining. Claude Code takes a different approach: **git commits as checkpoints and progress files as structured scratchpads**.
|
||||
|
||||
## 8\. Error Handling
|
||||
|
||||
Here's why this matters: **a 10-step process with 99% per-step success still has only ~90.4% end-to-end success**. Errors compound fast.
|
||||
|
||||
LangGraph distinguishes four error types: transient (retry with backoff), LLM-recoverable (return error as ToolMessage so the model can adjust), user-fixable (interrupt for human input), and unexpected (bubble up for debugging). Anthropic catches failures within tool handlers and returns them as error results to keep the loop running. Stripe's production harness caps retry attempts at two.
|
||||
|
||||
## 9\. Guardrails and Safety
|
||||
|
||||
OpenAI's SDK implements three levels: input guardrails (run on first agent), output guardrails (run on final output), and tool guardrails (run on every tool invocation). A "tripwire" mechanism halts the agent immediately when triggered.
|
||||
|
||||
Anthropic separates permission enforcement from model reasoning architecturally. The model decides what to attempt; the tool system decides what's allowed. **Claude Code gates ~40 discrete tool capabilities independently**, with three stages: trust establishment at project load, permission check before each tool call, and explicit user confirmation for high-risk operations.
|
||||
|
||||
## 10\. Verification Loops
|
||||
|
||||
This is what separates toy demos from production agents. Anthropic recommends three approaches: rules-based feedback (tests, linters, type checkers), visual feedback (screenshots via Playwright for UI tasks), and LLM-as-judge (a separate subagent evaluates output).
|
||||
|
||||
Boris Cherny, creator of Claude Code, noted that **giving the model a way to verify its work improves quality by 2 to 3x**.
|
||||
|
||||
## 11\. Subagent Orchestration
|
||||
|
||||
Claude Code supports three execution models: Fork (byte-identical copy of parent context), Teammate (separate terminal pane with file-based mailbox communication), and Worktree (own git worktree, isolated branch per agent). OpenAI's SDK supports agents-as-tools (specialist handles bounded subtask) and handoffs (specialist takes full control). LangGraph implements subagents as nested state graphs.
|
||||
|
||||
# The Loop in Motion: A Step-by-Step Walkthrough
|
||||
|
||||
Now that you know the components, let's trace how they work together in a single cycle.
|
||||
|
||||

|
||||
|
||||
**Step 1 (Prompt Assembly)**: The harness constructs the full input: system prompt + tool schemas + memory files + conversation history + current user message. Important context is positioned at the beginning and end of the prompt (the "Lost in the Middle" finding).
|
||||
|
||||
**Step 2 (LLM Inference)**: The assembled prompt goes to the model API. The model generates output tokens: text, tool call requests, or both.
|
||||
|
||||
**Step 3 (Output Classification)**: If the model produced text with no tool calls, the loop ends. If it requested tool calls, proceed to execution. If a handoff was requested, update the current agent and restart.
|
||||
|
||||
**Step 4 (Tool Execution)**: For each tool call, the harness validates arguments, checks permissions, executes in a sandboxed environment, and captures results. Read-only operations can run concurrently; mutating operations run serially.
|
||||
|
||||
**Step 5 (Result Packaging)**: Tool results are formatted as LLM-readable messages. Errors are caught and returned as error results so the model can self-correct.
|
||||
|
||||
**Step 6 (Context Update)**: Results are appended to conversation history. If approaching the context window limit, the harness triggers compaction.
|
||||
|
||||
**Step 7 (Loop)**: Return to Step 1. Repeat until termination.
|
||||
|
||||
**Termination conditions** are layered: the model produces a response with no tool calls, maximum turn limit is exceeded, token budget is exhausted, a guardrail tripwire fires, the user interrupts, or a safety refusal is returned. A simple question might take 1 to 2 turns. A complex refactoring task can chain dozens of tool calls across many turns.
|
||||
|
||||
[For long-running tasks spanning multiple context windows, Anthropic developed a two-phase "Ralph Loop" pattern](https://www.anthropic.com/research/long-running-Claude): an **Initializer Agent** sets up the environment (init script, progress file, feature list, initial git commit), then a **Coding Agent** in every subsequent session reads git logs and progress files to orient itself, picks the highest-priority incomplete feature, works on it, commits, and writes summaries. The filesystem provides continuity across context windows.
|
||||
|
||||
# How Real Frameworks Implement the Pattern
|
||||
|
||||

|
||||
|
||||
**Anthropic's Claude Agent SDK** exposes the harness through a single query() function that creates the agentic loop and returns an async iterator streaming messages. The runtime is a "dumb loop." All intelligence lives in the model. Claude Code uses a Gather-Act-Verify cycle: gather context (search files, read code), take action (edit files, run commands), verify results (run tests, check output), repeat.
|
||||
|
||||
**OpenAI's Agents SDK** implements the harness through the Runner class with three modes: async, sync, and streamed. The SDK is "code-first": workflow logic is expressed in native Python rather than graph DSLs. The Codex harness extends this with a three-layer architecture: Codex Core (agent code + runtime), App Server (bidirectional JSON-RPC API), and client surfaces (CLI, VS Code, web app). All surfaces share the same harness, which is why "Codex models feel better on Codex surfaces than a generic chat window."
|
||||
|
||||
**LangGraph** models the harness as an explicit state graph. Two nodes (llm\_call and tool\_node) connected by a conditional edge: if tool calls present, route to tool\_node; if absent, route to END. LangGraph evolved from LangChain's AgentExecutor, which was deprecated in v0.2 because it was hard to extend and lacked multi-agent support. LangChain's **Deep Agents** explicitly use the term "agent harness": built-in tools, planning (write\_todos tool), file systems for context management, subagent spawning, and persistent memory.
|
||||
|
||||
**CrewAI** implements a role-based multi-agent architecture: Agent (the harness around the LLM, defined by role, goal, backstory, and tools), Task (the unit of work), and Crew (the collection of agents). CrewAI's Flows layer adds a "deterministic backbone with intelligence where it matters," managing routing and validation while Crews handle autonomous collaboration.
|
||||
|
||||
**AutoGen** (evolving into Microsoft Agent Framework) pioneered conversation-driven orchestration. Its three-layer architecture (Core, AgentChat, Extensions) supports five orchestration patterns: sequential, concurrent (fan-out/fan-in), group chat, handoff, and magentic (a manager agent maintains a dynamic task ledger coordinating specialists).
|
||||
|
||||
# The Scaffolding Metaphor
|
||||
|
||||
The scaffolding metaphor isn't decorative. It's precise. Construction scaffolding is temporary infrastructure that enables workers to build a structure they couldn't reach otherwise. It doesn't do the construction. But without it, workers can't reach the upper floors.
|
||||
|
||||

|
||||
|
||||
**The key insight: scaffolding is removed when the building is complete.** As models improve, harness complexity should decrease. Manus was rebuilt five times in six months, each rewrite removing complexity. Complex tool definitions became general shell execution. "Management agents" became simple structured handoffs.
|
||||
|
||||
This points to the **co-evolution principle**: models are now post-trained with specific harnesses in the loop. Claude Code's model learned to use the specific harness it was trained with. Changing tool implementations can degrade performance because of this tight coupling.
|
||||
|
||||
The "future-proofing test" for harness design: if performance scales up with more powerful models without adding harness complexity, the design is sound.
|
||||
|
||||

|
||||
|
||||
# Seven Decisions That Define Every Harness
|
||||
|
||||
**Every harness architect faces seven choices:**
|
||||
|
||||

|
||||
|
||||
1. **Single-agent vs. multi-agent.** Both Anthropic and OpenAI say: maximize a single agent first. Multi-agent systems add overhead (extra LLM calls for routing, context loss during handoffs). Split only when tool overload exceeds ~10 overlapping tools or clearly separate task domains exist.
|
||||
2. **ReAct vs. plan-and-execute.** ReAct interleaves reasoning and action at every step (flexible but higher per-step cost). Plan-and-execute separates planning from execution. LLMCompiler reports a **3.6x speedup** over sequential ReAct.
|
||||
3. **Context window management strategy.** Five production approaches: time-based clearing, conversation summarization, observation masking, structured note-taking, and sub-agent delegation. ACON research showed **26 to 54% token reduction while preserving 95%+ accuracy** by prioritizing reasoning traces over raw tool outputs.
|
||||
4. **Verification loop design.** Computational verification (tests, linters) provides deterministic ground truth. Inferential verification (LLM-as-judge) catches semantic issues but adds latency. Martin Fowler's Thoughtworks team frames this as **guides** (feedforward, steer before action) versus **sensors** (feedback, observe after action).
|
||||
5. **Permission and safety architecture.** Permissive (fast but risky, auto-approve most actions) versus restrictive (safe but slow, require approval for each action). The choice depends on deployment context.
|
||||
6. **Tool scoping strategy.** More tools often means worse performance. Vercel removed **80% of tools** from v0 and got better results. Claude Code achieves **95% context reduction** via lazy loading. The principle: expose the minimum tool set needed for the current step.
|
||||
7. **Harness thickness.** How much logic lives in the harness versus the model. Anthropic bets on thin harnesses and model improvement. Graph-based frameworks bet on explicit control. Anthropic regularly deletes planning steps from Claude Code's harness as new model versions internalize that capability.
|
||||
|
||||
# The Harness Is the Product
|
||||
|
||||
Two products using identical models can have wildly different performance based solely on harness design. The TerminalBench evidence is clear: changing only the harness moved agents by 20+ ranking positions.
|
||||
|
||||
The harness is not a solved problem or a commodity layer. It's where the hard engineering lives: managing context as a scarce resource, designing verification loops that catch failures before they compound, building memory systems that provide continuity without hallucination, and making architectural bets about how much scaffolding to build versus how much to leave to the model.
|
||||
|
||||
The field is moving toward thinner harnesses as models improve. But the harness itself isn't going away. Even the most capable model needs something to manage its context window, execute its tool calls, persist its state, and verify its work.
|
||||
|
||||
The next time your agent fails, don't blame the model. Look at the harness.
|
||||
|
||||
That's a wrap!
|
||||
|
||||
If you enjoyed reading this:
|
||||
|
||||
Find me →[@akshay\_pachaar](https://x.com/@akshay_pachaar) ✔️
|
||||
|
||||
Every day, I share tutorials and insights on AI, Machine Learning, and vibe coding best practices.
|
||||
@@ -0,0 +1,101 @@
|
||||
---
|
||||
title: "The Bitter Lesson of Agent Harnesses"
|
||||
source: "https://x.com/gregpr07/status/2047358189327520166"
|
||||
author:
|
||||
- "[[@gregpr07]]"
|
||||
published: 2026-04-24
|
||||
created: 2026-04-24
|
||||
description: "Don't wrap the LLM. Don't wrap its tools either.All you need is a SKILL.md and some Python helpers. The LLM has complete freedom. If somethi..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
Don't wrap the LLM. Don't wrap its tools either.
|
||||
|
||||
All you need is a SKILL.md and some Python helpers. The LLM has complete freedom. If something's missing, it writes it.
|
||||
|
||||
## The learning
|
||||
|
||||
A few months ago we wrote [The Bitter Lesson of Agent Frameworks](https://browser-use.com/posts/bitter-lesson-agent-frameworks). The argument: don't wrap the LLM in abstractions. Maximal action space, then restrict.
|
||||
|
||||
We were still wrapping its tools.
|
||||
|
||||
Every click(), type(), scroll() helper is an abstraction you decided the model needs. Every one of them is a constraint the RL'd model has to fight around.
|
||||
|
||||
## Why raw CDP
|
||||
|
||||
When we built the first version of Browser Use, we shipped thousands of lines of element extractors, DOM indexers, click wrappers.
|
||||
|
||||
LLMs know CDP. They were trained on millions of tokens of Page.navigate, DOM.querySelector, Runtime.evaluate.
|
||||
|
||||

|
||||
|
||||
CDP is the lowest level Chrome exposes. Give it directly to the model:
|
||||
|
||||
- **Cross-origin iframes.** Attach to the target directly, no frame abstraction to fight.
|
||||
- **Shadow DOM.** Walk shadowRoot.querySelectorAll like the model has seen ten thousand times.
|
||||
- **Anti-bot injection.** It's Chrome talking to itself.
|
||||
|
||||
## What we got wrong
|
||||
|
||||
A few months ago on this blog we wrote [Closer to the Metal: Leaving Playwright for CDP](https://browser-use.com/posts/playwright-to-cdp). The conclusion of that post: "Our agents shouldn't have to know the nuances of CDP Targets in order to Get Stuff Done."
|
||||
|
||||
Turns out we were wrong.
|
||||
|
||||
That post listed ten ways a Chrome tab can crash. We built watchdog services to catch each one - tab crashes, target detach, renderer OOM, zygote death, GPU process crash. Each got a handler. Each handler had to be kept in sync with Chrome's internals.
|
||||
|
||||
Give the LLM direct CDP access and the ability to edit its own harness, and it handles all of that itself. Pages dying, targets wrongly attached, Chrome stalling - the agent reads the error, reattaches to a fresh target, retries. It doesn't need a watchdog. It's read ten thousand threads about Chrome crashes. It already knows what to do.
|
||||
|
||||
The "complexities of CDP" we were trying to hide weren't something to hide. They were something to let the model see.
|
||||
|
||||
## Four files
|
||||
|
||||
That's the whole harness:
|
||||
|
||||
- [run.py](https://run.py/) (13 lines) - runs plain Python with helpers preloaded
|
||||
- [helpers.py](https://helpers.py/) (192 lines) - thin wrappers around CDP, and the agent edits them
|
||||
- [daemon.py](https://daemon.py/) (220 lines) - keeps the CDP websocket alive
|
||||
- SKILL.md - tells the agent how to use the above
|
||||
|
||||
~600 lines total.
|
||||
|
||||

|
||||
|
||||
The agent writes Python. The Python imports helpers. The helpers speak CDP. Chrome does what it's told. Everything above Chrome is rewriteable.
|
||||
|
||||
## The self-heal loop
|
||||
|
||||
Here's what happens when a tool is missing.
|
||||
|
||||

|
||||
|
||||
When a helper is missing, the agent does what any Claude Code user would do: greps [helpers.py](https://helpers.py/), adds the function, reruns.
|
||||
|
||||
We didn't tell it to do this. We gave it Claude Code's normal Read/Edit/Write plus CDP access. Coding agents already know how to fix a missing import.
|
||||
|
||||
The key: **the agent isn't writing new code from first principles. It's writing the one function that was missing, the same way it'd fix a missing import on any codebase.**
|
||||
|
||||
## Magical moments
|
||||
|
||||
**Upload.** We forgot to add upload\_file(). Mid-task, the agent hit a file input, grepped [helpers.py](https://helpers.py/), saw nothing, wrote the function using raw DOM.setFileInputFiles, and uploaded the file. We found out when we read the git diff.
|
||||
|
||||
**Chunked upload.** After writing upload\_file, the agent tried to upload a 12MB file. CDP websocket payloads cap around 10MB. It hit the limit, read the error, switched to a chunked upload pattern.
|
||||
|
||||
**Gusto to calendar.** Task: put every employee's birthday in our shared calendar. Required navigating Gusto's employee tab, extracting dates from the DOM, then creating Google Calendar events.
|
||||
|
||||
**Azure admin roles.** Azure's admin portal is a pile of blades inside iframes. Raw CDP, via coordinate-level Input.dispatchMouseEvent, passes through at the compositor level.
|
||||
|
||||
## Try it
|
||||
|
||||
Setup prompt for Claude Code or Codex:
|
||||
|
||||
```markdown
|
||||
Set up https://github.com/browser-use/browser-harness for me.
|
||||
```
|
||||
|
||||
First person to find a task it fails on (not captcha/2FA) gets a Mac Mini. Seriously. I've been trying to break it for a week and can't.
|
||||
|
||||
Repo: [github.com/browser-use/browser-harness](https://github.com/browser-use/browser-harness)
|
||||
|
||||
**The bitter lesson of agent harnesses: your helpers are abstractions too. Delete them. Let the agent write what it needs.**
|
||||
@@ -0,0 +1,355 @@
|
||||
---
|
||||
title: "The Definitive Guide to Harness Engineering"
|
||||
source: "https://x.com/Trae_ai/status/2047145274200768969"
|
||||
author:
|
||||
- "[[@Trae_ai]]"
|
||||
published: 2026-04-23
|
||||
created: 2026-04-24
|
||||
description: "Harness Engineering is simply a more evocative, intuitive way to systematically summarize and name these existing AI practices.1. What is Ha..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
> Harness Engineering is simply a more evocative, intuitive way to systematically summarize and name these existing AI practices.
|
||||
|
||||

|
||||
|
||||
# 1\. What is Harness Engineering?
|
||||
|
||||
2026 marks the rise of a new pillar in software engineering: **Harness Engineering**. Following in the footsteps of Prompt and Context Engineering, the name was introduced by Mitchell Hashimoto, Co-Founder of HashiCorp and gained widespread traction after a pivotal OpenAI report.
|
||||
|
||||
At its core lies the "**Horse and Reins**" metaphor. Think of an AI agent or any complex software system as a powerful but directionless "wild horse". **The "Harness" represents the reins used to constrain, guide, and correct its behavior, ensuring it stays on track with stability and reliability.**
|
||||
|
||||

|
||||
|
||||
To put it into a simple equation:
|
||||
|
||||
> **AI Agent = SOTA Model (Wild Horse) + Harness (Control System) = An Elite Performer**
|
||||
|
||||
An AI agent is a "wild horse" with limitless potential, and Harness Engineering is the complete system that domesticates it. You aren't changing the horse's DNA (the model itself), **you're designing the professional gear and training protocols required to make it work for you.**
|
||||
|
||||
> 💬 The Harness is essentially every piece of infrastructure other than the LLM that enables an agent to actually deliver results. It isn't about "better prompts" or "more capable models". **It's about optimizing the environment and mechanisms the model operates within**. It is an engineering philosophy and framework designed to transform raw AI intelligence into reliable, controllable, and scalable productivity.
|
||||
|
||||
Let's be clear: Harness Engineering isn't some shiny new toy to trigger your FOMO. It's more of a harnessing framework for AI engineering, designed to tackle one core problem.
|
||||
|
||||
The core problem it solves is simple: now that AI has joined your workflow, how do we actually manage this "super intern"?
|
||||
|
||||
# 2\. Why Do We Need Harness Engineering?
|
||||
|
||||
As AI evolves from simple "answering machines" to autonomous agents capable of planning and executing complex tasks, the role of the engineer is undergoing a fundamental paradigm shift.
|
||||
|
||||
Harness Engineering has emerged specifically to tackle the new challenges brought on by this evolution.
|
||||
|
||||
## 2.1 Building a more reliable Agent system
|
||||
|
||||
To move agents beyond the toy stage and into the realm of production-ready engineering, they must anchor on four core objectives: the **R.E.S.T** framework.
|
||||
|
||||
**2.1.1 Reliability**
|
||||
|
||||
**Definition**
|
||||
|
||||
The system's ability to provide stable, continuous service and complete designated tasks when faced with expected or unexpected inputs, environmental shifts, and internal faults.
|
||||
|
||||
**Key Requirements**
|
||||
|
||||
- **Fault Recovery**: The ability to automatically resume from checkpoints after a task is interrupted
|
||||
- **Operation Idempotency**: Ensuring critical write operations can be safely retried without corrupting the system state
|
||||
- **Behavioral Consistency**: Ensuring behavior remains predictable under the same set of inputs
|
||||
|
||||
**2.1.2 Efficiency**
|
||||
|
||||
**Definition**
|
||||
|
||||
The effective use of compute, storage, and network resources while meeting functional and reliability needs. This directly impacts service cost and scalability.
|
||||
|
||||
**Key Requirements**
|
||||
|
||||
- **Resource Control**: Precise budget management for token consumption, API calls, and compute time
|
||||
- **Low-Latency Response**: Providing meaningful feedback quickly in interactive scenarios
|
||||
- **High Throughput**: The ability to process more tasks per unit of time in batch scenarios
|
||||
|
||||
**2.1.3 Security**
|
||||
|
||||
**Definition**
|
||||
|
||||
Protecting the system and its data from unauthorized access, use, or destruction. For autonomous agents, security is a non-negotiable red line.
|
||||
|
||||
**Key Requirements**
|
||||
|
||||
- **Least Privilege**: Granting only the minimum permissions necessary to complete a specific sub-task
|
||||
- **Sandboxed Execution**: Executing all untrusted code or instructions within a strictly isolated sandbox environment
|
||||
- **I/O Filtering**: Preventing prompt injection, sensitive data leaks, and the generation of harmful content
|
||||
|
||||
**2.1.4 Traceability**
|
||||
|
||||
**Definition**
|
||||
|
||||
Providing sufficient data (logs, metrics, and traces) so that developers and operators can understand the internal state, decision-making process, and behavioral history of the agent.
|
||||
|
||||
**Key Requirements**
|
||||
|
||||
- **End-to-End Tracing**: Maintaining a clear, traceable call chain for every step from the initial request to the final result
|
||||
- **Explainable Decisions**: Ensuring every critical decision has a clear attribution record
|
||||
- **Auditable State**: Ensuring the complete state of the system at any point in its history can be queried and audited
|
||||
|
||||
## 2.2 The Engineering Imperative in the Agent-First Era
|
||||
|
||||
**2.2.1 Engineering complexity is hitting new heights**
|
||||
|
||||
As AI capabilities expand, so do our expectations for what we can build. We've moved far beyond "Vibe Coding" (quick demos of Snake or Tetris clones) and transitioned into the realm of **serious, production-grade engineering**.
|
||||
|
||||
**2.2.2 From "Executor" to "Architect"**
|
||||
|
||||
As AI takes over the heavy lifting of writing specific lines of code, the core value of a human engineer moves up the stack to **system design**. We are no longer laborers laying bricks line-by-line, we are architects drafting the blueprints, defining the rules, and signing off on the final output: a concept we call Spec Coding.
|
||||
|
||||

|
||||
|
||||
This practice is a powerful proof of concept: when AI becomes the primary engine of productivity, traditional engineering management models no longer work. Instructing an AI via prompts is a "soft constraint," and it simply isn't enough to guarantee quality, reliability, or maintainability.
|
||||
|
||||
We need a system of **"hard constraints"**, a robust engineering framework to anchor the agent performance. This is exactly where Harness Engineering comes in.
|
||||
|
||||
**The core philosophy of Harness Engineering is that when a model hits a wall, we implement an engineered mechanism to ensure that the same class of failure never happens again.**
|
||||
|
||||
It is a living system. As models continue to iterate, many foundational capabilities will eventually be internalized by the models themselves, allowing certain Harness practices to retire. Simultaneously, as new application scenarios emerge, they will inevitably birth new Harness innovations.
|
||||
|
||||
Let's then dive into what Harness Engineering actually looks like.
|
||||
|
||||
# 3\. Deconstructing Harness Engineering
|
||||
|
||||
Under the hood of current Transformer-based and autoregressive LLM architectures, raw output is inherently **stochastic and disordered**.
|
||||
|
||||
Harness Engineering is the practice of imposing deterministic constraints on that raw compute to enable complex engineering workflows.
|
||||
|
||||
To understand the "what," we have to look at how an agent actually functions. A production-ready agent operates on a continuous, four-stage loop: **Perception, Planning, Action, and Feedback/Reflection (PPAF)**.
|
||||
|
||||

|
||||
|
||||
We deconstruct the agent stack into four core dimensions, each mapped directly to the PPAF cycle. Think of these as the 'harness'—the necessary structure to guide, constrain, and unleash the model's true potential.
|
||||
|
||||

|
||||
|
||||
To map the capability boundaries and engineering hurdles of different agents, we use a two-dimensional matrix based on the **Cognitive Loop** and **Context Efficiency**.
|
||||
|
||||
**Horizontal Axis: AI Cognitive Loop**
|
||||
|
||||
- **React (Passive Response)**: Behavior is driven by single external triggers. The agent executes predefined, deterministic tasks but lacks autonomous planning or reflection.
|
||||
- **Proactive Plan & Reflect**: The agent pursues long-term goals, autonomously managing multi-step planning, execution, and dynamic adjustments based on outcomes.
|
||||
|
||||
**Vertical Axis: Context Efficiency**
|
||||
|
||||
- **Inefficient (Manual/Point-fed)**: Most context is manually provided by humans or pulled through limited, low-efficiency interfaces.
|
||||
- **Efficient (Sandboxed/Automated Injection)**: The agent operates in a highly integrated environment where context is automatically captured and injected via system-level interfaces like file systems, API gateways, or state engines.
|
||||
|
||||

|
||||
|
||||
This matrix reveals the core value of Harness Engineering: **the maturity of your harness directly determines an agent's ability to leap from the inefficient, passive lower quadrants into the high-efficiency, proactive upper tiers.**
|
||||
|
||||
# 4\. The Architecture of a Harness System
|
||||
|
||||
With the framework established, it's time to move from concept to action. Let's unpack how to build a resilient Harness system layer by layer.
|
||||
|
||||
## 4.1 High-Level Abstraction: The Harness as a Managed REPL Container
|
||||
|
||||
At the architectural level, a Harness is essentially a **REPL (Read-Eval-Print Loop) container** equipped with boundary controls, tool routing, and deterministic feedback.
|
||||
|
||||
Think of it as a deterministic shell wrapping the non-deterministic "brain" of the LLM. Its job is to manage the entire lifecycle from perception to action to reflection, effectively plugging LLM reasoning into the predictable world of software engineering.
|
||||
|
||||
> **💬** **The Core Logic of the REPL Harness**
|
||||
|
||||
> **Read**: The Harness uses a **Context Manager** to translate the external world (such as user input or API states) and internal memory into highly structured prompts that the LLM can actually digest. This is how we bring engineering rigor to the "perception" phase.
|
||||
|
||||
> **Eval**: When the LLM generates a plan (e.g., a Function Call), the **Call Interceptor** catches that intent and routes it to the appropriate tool executor. Every execution is strictly monitored for timeouts, resource quotas, and error handling.
|
||||
|
||||
> **Print**: The output of the tool (whether it's successful data or an exception) is captured by the **Feedback Assembler**. This is then repackaged as a structured "observation" and re-injected into the context, providing the LLM with the raw material for its next round of reflection and planning.
|
||||
|
||||
> **Loop**: This "**Read-Eval-Print**" cycle repeats continuously until the agent hits its goal or triggers a termination condition. This loop is the fundamental engine driving the PPAF process.
|
||||
|
||||
## 4.2 The Underlying Transformation Mechanism: Bridging Infinite State and Finite Tokens
|
||||
|
||||
An agent's emergent intelligence relies on its ability to digest massive amounts of state information. However, **the underlying Transformer architecture operates on a fundamentally finite, linear token sequence.**
|
||||
|
||||
Consequently, a central challenge of a Harness is establishing an efficient, reliable, bidirectional mapping between the "infinite" state of the external world and the "finite" token context of the LLM.
|
||||
|
||||
**4.2.1 Context Management: From "Infinite State" to "Finite Tokens"**
|
||||
|
||||
An agent's context is the ground truth for its perception, encompassing everything from task goals and interaction history to tool definitions and real-time state. The ability to distill this massive data stream into a finite token window is the ultimate bottleneck for planning quality.
|
||||
|
||||

|
||||
|
||||
> **💬** **Engineering Decisions: Reduction Rules and Injection Boundaries**
|
||||
|
||||
> At its core, context management is a set of **Reduction Rules**.
|
||||
|
||||
> The Harness must define explicit rules to determine which information to prioritize and which to prune when the token budget is tight. Furthermore, the **Injection Boundary** is vital. It dictates exactly where external data (such as RAG results) is inserted within the prompt to maximize performance and avoid the "Lost in the Middle" phenomenon.
|
||||
|
||||
**4.2.2 Function Calling: From "Text Prediction" to "Physical Execution"**
|
||||
|
||||
Function Calling (FC) serves as the bridge between LLM planning and real-world action. While it seems straightforward, it involves a rigorous, and often fragile lifecycle loop:
|
||||
|
||||
- **Schema Serialization**: The Harness serializes available tools and their parameters (JSON Schema) into a specific text format and injects it into the prompt. This is the only way an LLM understands its "capability boundaries".
|
||||
- **Trigger Generation**: Through pattern matching across its vast parameter space, the LLM generates text following a specific syntax (including the tool name and argument values) when it determines a tool is needed for the plan.
|
||||
- **Deterministic Deserialization**: The Harness intercepts this text and attempts to deserialize it into a structured request. This is the most brittle stage, as LLM output may violate syntax rules, such as malformed JSON or type mismatches.
|
||||
- **Observation Injection**: The Harness executes the call and wraps the result (success or failure) into an "observation" text block, which is re-injected into the prompt to close the loop.
|
||||
|
||||
**a) Failure Surfaces and Fallback Paths**
|
||||
|
||||
Given the non-deterministic nature of LLM output, every step of Function Calling is a potential point of failure. A resilient Harness must implement robust fallback paths:
|
||||
|
||||
**Deserialization Failure**
|
||||
|
||||
- **Retry**: Provide the LLM with the specific error (e.g., "Invalid JSON format") to trigger a re-generation.
|
||||
- **Fallback to Text**: Request natural language instructions for a traditional parser instead.
|
||||
|
||||
**Execution Failure**
|
||||
|
||||
- **Interactive Clarification**: Request missing parameters directly from the user.
|
||||
- **Reflection and Re-planning**: Inject detailed error logs into the context to guide the agent toward an alternative path in the next round.
|
||||
|
||||
**b) Core Architectural Decision: The State Separation Principle**
|
||||
|
||||
- You must treat the LLM strictly as a **stateless compute unit (a "CPU")**. All state requiring cross-turn consistency such as user sessions or task progress **must be offloaded to an external Context State Manager or persistence engine (Memory/Disk) controlled by the Harness**.
|
||||
- **The Anti-Pattern**: Attempting to force the LLM to maintain complex state via prompt engineering leads to chaotic, unpredictable, and untraceable system behavior.
|
||||
|
||||
**4.2.3 Core Constraints and Design Principles**
|
||||
|
||||
When building a Harness, we must confront three fundamental constraints and address them through six core design principles.
|
||||
|
||||
**The Three Core Constraints**
|
||||
|
||||

|
||||
|
||||
**The Six Design Principles**
|
||||
|
||||
1. **Design for Failure**: Treat exceptions and failures as the norm, not the outlier. Every component must support fault tolerance, retries, and graceful degradation.
|
||||
2. **Contract-First**: Define all interactions through explicit, machine-readable contracts (Schemas, APIs, Events). This is the foundation for modularity and system evolution.
|
||||
3. **Secure by Default**: Security isn't a bolt-on. It should be the starting point. We follow the principles of least privilege, zero trust, and defense-in-depth.
|
||||
4. **Separation of Concerns (Decision vs. Execution)**: Decouple "deciding what to do" (planning) from "how to do it" (execution) both logically and physically to increase system flexibility.
|
||||
5. **Everything is Measurable**: Every behavior, decision, and resource used must be quantifiable. Without measurement, there is no path to optimization.
|
||||
6. **Data-Driven Evolution**: Treat every agent run as a learning opportunity. Building a closed loop of data collection, labeling, and feedback is the only way to achieve long-term intelligent growth.
|
||||
|
||||
**4.2.4 Key Engineering Landmarks**
|
||||
|
||||
To drive the REPL loop and ground these design principles, a Harness requires several critical components or "Engineering Landmarks" deployed throughout the architecture.
|
||||
|
||||

|
||||
|
||||
**Harness Engineering** is just the collective name for how we orchestrate LLMs. Whether it's an SDK, an agent, or a custom plugin, the mission is always the same: **stopping the model from making the same mistake twice**.
|
||||
|
||||
These 'harnesses' aren't static. As models evolve, today's external guardrails will eventually be baked directly into the models themselves.
|
||||
|
||||
# 5\. Implementing Harness Engineering
|
||||
|
||||
Conceptual frameworks are a great starting point, but for the engineers building platforms and infrastructure, a Harness must be viewed as a **living, operational system**. To truly understand how it works, we need to examine it through four critical lenses: architectural layering, core mechanisms, operational governance, and data-driven evolution.
|
||||
|
||||
## 5.1 Architecture Overview: Control Plane and Data Plane
|
||||
|
||||
A production-grade Harness is typically decoupled into a **Control Plane** and a **Data Plane**:
|
||||
|
||||
- **Control Plane (The "What")**: Manages the high-level logic, including task scheduling, resource quotas, behavioral planning, and policy enforcement.
|
||||
- **Data Plane (The "How")**: Handles the heavy lifting, such as actual agent runtime instances, state and memory storage, and the sandboxed execution environment.
|
||||
|
||||
We further abstract this into four functional layers:
|
||||
|
||||

|
||||
|
||||
In practice, think of the Harness as "**intelligent glue.**" It sits between your model's API Gateway and your services, using engineering rigor to stitch disparate infrastructure into a cohesive system.
|
||||
|
||||
## 5.2 Core Mechanisms: The Loop, Memory, and Token Pipelines
|
||||
|
||||
**5.2.1 The Agent Core Loop**
|
||||
|
||||
We abstract agent behavior into a continuous **Observe → Think → Act** cycle:
|
||||
|
||||
- **Observe**: Perceiving the current state of the world, including user inputs, tool outputs, interaction history, and task progress.
|
||||
- **Think**: Using that perception to update goals, decompose tasks, and decide on the next move.
|
||||
- **Act**: Executing operations whether internal (updating memory) or external (calling a tool or replying), the results of which feed back into the next observation.
|
||||
|
||||
> **💬** **Engineering Note: It’s not a simple** **while (true)** **loop**
|
||||
|
||||
> In production, this loop must integrate with workflow engines or state machine frameworks. It needs to support pause/resume functionality, idempotent retries, and concurrent event handling to solve "context anxiety" in long-running tasks.
|
||||
|
||||
**5.2.2 Tiered Memory & the Token Pipeline**
|
||||
|
||||
To pack maximum signal into a finite context window, most agents rely on external memory.
|
||||
|
||||

|
||||
|
||||
On top of this, the Harness runs a **Token Transformation Pipeline** to distill multi-source information into a controlled prompt before every call:
|
||||
|
||||
1. **Collection**: Aggregating user requests, short-term memory, and long-term knowledge retrievals.
|
||||
2. **Ranking**: Scoring information based on recency and semantic relevance.
|
||||
3. **Compression**: Summarizing or structurally refining high-volume, low-density content.
|
||||
4. **Budgeting**: Allocating token limits to different information categories.
|
||||
5. **Assembly**: Piecing together the final prompt using structured templates (e.g., explicit \[user\_request\] or \[tool\_output\] blocks).
|
||||
|
||||
> **💬** **The Bottom Line: Offload attention management to engineering**
|
||||
|
||||
> Rather than hoping the model "figures out" what to focus on, use the Token Transformation Pipeline to actively build the context. Save that precious window for the information that actually matters.
|
||||
|
||||
**5.2.3 Planning Models and Execution Strategies**
|
||||
|
||||
At the Planner layer, we typically categorize patterns based on the complexity of the task:
|
||||
|
||||
> **💬** **The Recommendation**
|
||||
|
||||
> Default to Plan-and-Execute, and layer in re-planning or multi-agent orchestration only as needed.
|
||||
|
||||
> For most enterprise scenarios, a structured plan paired with "exception-triggered re-planning" is robust enough.
|
||||
|
||||

|
||||
|
||||
**5.2.4 Runtime and Governance: Sandboxing, Security, and Cost**
|
||||
|
||||
**Sandboxed Execution Frameworks**
|
||||
|
||||
To let agents "get things done" without wrecking your system, you must provide a secure, isolated runtime.
|
||||
|
||||
- **Level 1: Process-level Isolation**: Uses chroot, Linux namespaces, or seccomp-bpf. It’s fast but shares the kernel; best for trusted internal tools.
|
||||
- **Level 2: Container Isolation**: Docker or containerd. This is the mature, industry-standard choice for most tool execution.
|
||||
- **Level 3: MicroVMs**: Firecracker. Provides independent virtual kernels, making it ideal for multi-tenant environments or executing untrusted code.
|
||||
- **Level 4: Full VMs**: KVM/QEMU. Maximum security at the highest cost; reserved for the most sensitive tasks.
|
||||
|
||||
> **💬** **The Strategy**
|
||||
|
||||
> Default to Level 2 (Containers) paired with a hardened kernel and a read-only root filesystem. Introduce Level 3 (MicroVMs) as a bolstered sandbox for untrusted code or high-sensitivity data.
|
||||
|
||||
**Resource Management and Resilience**
|
||||
|
||||
Controlling costs and ensuring stability requires a few critical engineering guardrails:
|
||||
|
||||
- **Budgets and Quotas**: Set limits for tokens, API calls, and CPU time across platforms, tenants, or individual tasks.
|
||||
- **Timeout Control**: Enforce strict timeouts on all network requests and tool executions to prevent a hanging downstream service from dragging down the entire Agent.
|
||||
- **Retry Strategies**: Use retries with backoff for transient, recoverable errors, but fail fast on permanent ones.
|
||||
- **Circuit Breakers**: Temporarily trip the circuit if a dependency fails repeatedly to prevent cascading failures.
|
||||
- **Graceful Degradation**: If critical capabilities go offline, automatically downshift to a "weak but safe" mode (e.g., moving from "executable code" to "read-only suggestions").
|
||||
|
||||
**Security and Compliance: The Policy Gateway**
|
||||
|
||||
Beyond the sandbox, you need a **Policy Gateway** sitting between the Planner and the Execution layer to validate every action:
|
||||
|
||||
- **Permissions**: RBAC/ABAC checks to verify if an Agent is authorized to access a specific resource.
|
||||
- **Data Filtering**: PII and secret detection for both input parameters and return values.
|
||||
- **Injection Defense**: Identifying malicious prompt patterns or command stitching before they hit the execution layer.
|
||||
- **Audit Logging**: Recording "who did what, when, and the result" for post-mortems and compliance audits.
|
||||
|
||||
**Metrics and Evolution: Growing Through Data**
|
||||
|
||||
Finally, you need a robust evaluation suite to ensure your Agent system stays on the right track:
|
||||
|
||||
- **Task Effectiveness**: Success rate, instruction-following rate, and tool-use efficacy.
|
||||
- **Quality of Service (QoS)**: End-to-end latency, time-to-first-action, and overall error rates.
|
||||
- **Resource Efficiency**: Average token consumption and Average tool calls.
|
||||
- **Security and Compliance**: Policy denial rates and number of security incidents.
|
||||
|
||||
These metrics aren't just vanity metrics or dashboard filler; they are the feedback loop that drives your Harness's evolution. When success rates hit a ceiling, it’s a signal to revisit your planner or context strategy. If error rates or costs spike, you likely need to troubleshoot your sandboxing, resource quotas, or circuit breaker logic.
|
||||
|
||||
# 6\. Final Words
|
||||
|
||||
Harness Engineering isn't some "silver bullet" to be put on a pedestal. It's an engineering philosophy forged in and built for the real world.
|
||||
|
||||
While the industry fixates on the "disruption" and "replacement" of developers by generative AI, this methodology serves as a grounding reminder: t**he role of the engineer isn't disappearing. It's evolving. We are shifting from being the** **creators** **of code to becoming the** **guardians of the creation process**.
|
||||
|
||||
Architecting a reliable Harness is ultimately an exercise in balancing **chaos** and **order**. We don't expect AI to be perfect any more than we expect humans to be infallible. **True engineering wisdom lies in building systems that can learn from failure and navigate uncertainty with resilience.**
|
||||
|
||||
The ultimate goal of these "reins" was never to restrict, but to enable a safer, more complete release of potential. And perhaps, in the near future, models will begin to outgrow these foundational constraints entirely.
|
||||
@@ -0,0 +1,255 @@
|
||||
---
|
||||
title: "The Linear Algebra Needed For AI/ML (Complete Roadmap)"
|
||||
source: "https://x.com/TheVixhal/status/2047362720199274713"
|
||||
author:
|
||||
- "[[@TheVixhal]]"
|
||||
published: 2026-04-24
|
||||
created: 2026-04-24
|
||||
description: "You don’t need a math PhD to do AI/ML. You just need enough linear algebra to stop feeling lost when you open a paper or a PyTorch doc. This..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
You don’t need a math PhD to do AI/ML. You just need enough linear algebra to stop feeling lost when you open a paper or a PyTorch doc. This roadmap covers exactly what to learn, in the right order, and why it matters. Let’s get into it.
|
||||
|
||||
# Why Linear Algebra at All?
|
||||
|
||||
Before we start listing topics, let me explain why this subject matters so much in ML.
|
||||
|
||||
Everything in machine learning is numbers. Images are grids of numbers. Text becomes numbers after tokenization. Audio is a list of numbers sampled over time. Once you turn all your data into numbers, you need a way to:
|
||||
|
||||
1. Store these numbers efficiently
|
||||
2. Do fast operations on them
|
||||
3. Transform them from one form to another
|
||||
|
||||
Linear algebra is literally the language we use to do all three. Neural networks? They are just matrix multiplications with some non-linear functions sprinkled in. Principal Component Analysis? Eigenvectors. Recommendation systems? Matrix factorization. Word embeddings? Vectors in high dimensions.
|
||||
|
||||
You cannot escape it. But you can understand it. Let's go.
|
||||
|
||||
# Phase 1: The Absolute Basics
|
||||
|
||||
This is where everyone should start, even if you think you know this stuff. Trust me, come back and revise.
|
||||
|
||||
## 1\. Scalars, Vectors, Matrices, Tensors
|
||||
|
||||

|
||||
|
||||
Start here. Understand the hierarchy.
|
||||
|
||||
- A **scalar** is just one number. Like 5 or 3.14.
|
||||
- A **vector** is a list of numbers. Like \[2, 4, 7\].
|
||||
- A **matrix** is a 2D grid of numbers, basically rows and columns.
|
||||
- A **tensor** is the general version. It can be 3D, 4D, or more. Image batches in deep learning are usually 4D tensors (batch, channel, height, width).
|
||||
|
||||
Why this matters: every PyTorch or TensorFlow program you write will use these. If you do not know the shape of your data, you will spend hours debugging.
|
||||
|
||||
## 2\. Vector Operations
|
||||
|
||||
Learn how to:
|
||||
|
||||
- Add two vectors
|
||||
- Multiply a vector by a scalar
|
||||
- Find the length (also called the magnitude or norm) of a vector
|
||||
- Understand the geometric meaning, meaning vectors point somewhere in space
|
||||
|
||||
The norm concept will come back again and again. L1 norm, L2 norm, these are used in regularization and loss functions.
|
||||
|
||||
## 3\. Dot Product
|
||||
|
||||
This one is huge. The dot product tells you how similar two vectors are. It is the foundation of cosine similarity, which is used everywhere from search engines to recommender systems to attention in transformers.
|
||||
|
||||
Practice until you can compute a dot product in your sleep.
|
||||
|
||||
## 4\. Matrix Operations
|
||||
|
||||
- Matrix addition
|
||||
- Scalar multiplication on a matrix
|
||||
- Matrix multiplication (the big one)
|
||||
- Transpose of a matrix
|
||||
|
||||
Matrix multiplication is NOT element-wise multiplication. This confuses so many beginners. Spend extra time here. Understand why the dimensions need to match (the inner dimensions must agree, like (m x n) times (n x p) gives (m x p)).
|
||||
|
||||
# Phase 2: Building Blocks You Will Actually Use
|
||||
|
||||
Now we get into stuff that shows up in actual ML code.
|
||||
|
||||
## 5\. Special Matrices
|
||||
|
||||
Know these by name:
|
||||
|
||||
- **Identity matrix**: the matrix equivalent of the number 1
|
||||
- **Diagonal matrix**: only the diagonal has values, rest are zeros
|
||||
- **Symmetric matrix**: equal to its own transpose
|
||||
- **Orthogonal matrix**: its transpose is its inverse
|
||||
|
||||
You will see these pop up in covariance matrices, attention masks, and rotation operations.
|
||||
|
||||
## 6\. Matrix Inverse
|
||||
|
||||
Not every matrix has an inverse, and the ones that do not are called singular. In ML, we rarely compute inverses directly because they are slow and unstable. But understanding the concept helps you read equations in papers.
|
||||
|
||||
Know what the determinant is and why a zero determinant means no inverse.
|
||||
|
||||
## 7\. Linear Independence and Rank
|
||||
|
||||
If you have a bunch of vectors, are some of them basically repeats of the others? That is what linear independence asks. The rank of a matrix tells you how many truly independent directions it has.
|
||||
|
||||
This matters when you do PCA or when you hear people say "the data lies on a lower dimensional manifold". Rank is the idea hiding behind that fancy sentence.
|
||||
|
||||
## 8\. Span, Basis, and Subspaces
|
||||
|
||||
Think of a basis as the minimum set of vectors you need to describe everything in a space. Like how you only need North-South and East-West to describe any location on a map.
|
||||
|
||||
Understanding this helps when you get to embeddings. A word embedding of size 768 basically means each word gets placed in a 768-dimensional space using a chosen basis.
|
||||
|
||||
# Phase 3: The Important Stuff for ML
|
||||
|
||||
Okay now we are getting to the juicy parts that actually power ML algorithms.
|
||||
|
||||
## 9\. Eigenvalues and Eigenvectors
|
||||
|
||||
I know, scary name. But the idea is simple. When you apply a matrix to a vector, usually the vector gets stretched AND rotated. Eigenvectors are the special vectors that only get stretched, not rotated. The amount of stretching is the eigenvalue.
|
||||
|
||||
Why you care:
|
||||
|
||||
- PCA (dimensionality reduction) uses eigenvectors of the covariance matrix
|
||||
- PageRank (the original Google algorithm) is an eigenvector problem
|
||||
- Spectral clustering uses eigen-decomposition
|
||||
- Understanding stability of neural network training involves eigenvalues of the Hessian
|
||||
|
||||
Spend real time on this. Watch 3Blue1Brown's videos (they are free and genuinely the best resource on the internet for this).
|
||||
|
||||
## 10\. Singular Value Decomposition (SVD)
|
||||
|
||||
If I had to pick ONE concept that is the most important in applied linear algebra for ML, it would be SVD. It breaks any matrix (any shape, any size) into three simpler matrices.
|
||||
|
||||
Uses in ML:
|
||||
|
||||
- Low rank approximation (compressing matrices)
|
||||
- Recommender systems (Netflix prize algorithms used this)
|
||||
- Noise reduction in data
|
||||
- Understanding LoRA in fine-tuning large language models
|
||||
- Pseudoinverse computation
|
||||
|
||||
If eigen-decomposition is cool, SVD is cooler because it works on every matrix, not just square ones.
|
||||
|
||||
## 11\. Matrix Factorization
|
||||
|
||||
Related to SVD but broader. The idea is to break a big matrix into smaller matrices that when multiplied give back the original (approximately).
|
||||
|
||||
This is the entire basis of collaborative filtering. Also shows up in LoRA, where we approximate weight updates as the product of two smaller matrices to save memory during fine-tuning.
|
||||
|
||||
## 12\. Norms Revisited
|
||||
|
||||
Go deeper on norms now:
|
||||
|
||||
- L1 norm (sum of absolute values), used in Lasso regression for sparsity
|
||||
- L2 norm (the usual length), used in Ridge regression and weight decay
|
||||
- Frobenius norm for matrices
|
||||
- Infinity norm
|
||||
|
||||
Each has different properties that matter for optimization and regularization.
|
||||
|
||||
# Phase 4: The Calculus-Linear-Algebra Bridge
|
||||
|
||||
This is where ML actually happens. Pure linear algebra alone will not train a model, but combined with calculus it becomes gradient descent.
|
||||
|
||||
## 13\. Gradients and Jacobians
|
||||
|
||||
A gradient is the vector of partial derivatives. A Jacobian is the matrix of partial derivatives for vector valued functions. Neural network backpropagation is literally chained Jacobian-vector products.
|
||||
|
||||
You do not need to manually compute these (PyTorch does it for you via autograd), but you need to know what they represent.
|
||||
|
||||
## 14\. Hessian Matrix
|
||||
|
||||
The matrix of second derivatives. Its eigenvalues tell you about the curvature of your loss landscape. Second order optimization methods (like Newton's method) use it directly. For deep learning we usually approximate it because computing the full Hessian is too expensive.
|
||||
|
||||
## 15\. Chain Rule in Matrix Form
|
||||
|
||||
Backprop is the chain rule applied to matrices. Once you see this, neural networks stop being magic and start being just calculus on matrices.
|
||||
|
||||
# Phase 5: Advanced Topics (Only When Needed)
|
||||
|
||||
Do not stress about these until you actually run into them. But knowing they exist helps.
|
||||
|
||||
## 16\. Tensor Operations
|
||||
|
||||
- Broadcasting (how NumPy and PyTorch handle shape mismatches)
|
||||
- Einstein summation (einsum), once you learn this you will write cleaner code
|
||||
- Contractions and reshapes
|
||||
|
||||
Einsum is honestly a superpower. Learn it.
|
||||
|
||||
## 17\. Matrix Calculus Identities
|
||||
|
||||
There are some standard identities for differentiating common matrix expressions. Keep a cheat sheet. The Matrix Cookbook (a free PDF online) is the classic reference.
|
||||
|
||||
## 18\. Positive Definite Matrices
|
||||
|
||||
Matrices where x^T Ax > 0 for all non-zero x. Show up in:
|
||||
|
||||
- Covariance matrices (always positive semi-definite)
|
||||
- Gaussian processes
|
||||
- Convex optimization
|
||||
- Kernel methods
|
||||
|
||||
## 19\. Numerical Linear Algebra
|
||||
|
||||
How computers actually do these calculations matters once you scale up. Topics like:
|
||||
|
||||
- Condition number (how stable is your computation)
|
||||
- LU and QR decompositions
|
||||
- Iterative methods
|
||||
|
||||
Only dive here if you are doing heavy optimization work or writing your own linear algebra code.
|
||||
|
||||
# Phase 6: Where It All Shows Up in ML
|
||||
|
||||
Let me show you how each topic maps to actual ML tasks so you see the payoff.
|
||||
|
||||
**Linear Regression**: Matrix multiplication, matrix inverse (or pseudoinverse via SVD), norms for regularization.
|
||||
|
||||
**Logistic Regression and Neural Networks**: Matrix multiplications at every layer, gradients via Jacobians, norms for weight decay.
|
||||
|
||||
**PCA**: Eigenvectors of covariance matrix, or equivalently SVD of the data matrix.
|
||||
|
||||
**Transformers and Attention**: Tons of matrix multiplications, dot products for attention scores, softmax over those scores.
|
||||
|
||||
**Diffusion Models**: Linear transformations combined with noise, eigenvalues showing up in stability analysis.
|
||||
|
||||
**Recommender Systems**: Matrix factorization, SVD, low rank approximation.
|
||||
|
||||
**Graph Neural Networks**: Adjacency matrices, Laplacian matrices, eigendecomposition (spectral methods).
|
||||
|
||||
**LoRA Fine-Tuning**: Low rank decomposition, you literally learn two small matrices A and B such that their product approximates a weight update.
|
||||
|
||||
# How to Actually Learn This
|
||||
|
||||
Reading is not enough. You need to:
|
||||
|
||||
1. **Code it up**. Implement matrix multiplication from scratch in Python. Do SVD on a small image and reconstruct it with fewer components. Actually see dimensionality reduction happen in front of you.
|
||||
2. **Do problems by hand first, then scale up**. A 2x2 matrix calculation by hand teaches you more than a hundred **np.matmul** calls.
|
||||
3. **Visualize**. 3Blue1Brown's "Essence of Linear Algebra" series is mandatory viewing. I am not even joking, go watch it.
|
||||
4. **Use it in projects**. Build a simple recommender, do PCA on some dataset, train a tiny neural network from scratch. Theory without practice will fade in a week.
|
||||
5. **Read papers with math in them**. Start with easier ones. Force yourself to not skip the equations. Write them out, try to understand what each symbol means.
|
||||
|
||||
# Resources That Are Actually Good
|
||||
|
||||
- **3Blue1Brown's Essence of Linear Algebra** (YouTube, free): The visual intuition king.
|
||||
- **Gilbert Strang's MIT OCW lectures**: The legend himself. Takes time but gold standard.
|
||||
- **Mathematics for Machine Learning** by Deisenroth, Faisal, and Ong: Free PDF online, written specifically for ML.
|
||||
|
||||
Avoid books that are pure theory with no ML context unless you enjoy that. Time is finite.
|
||||
|
||||
# Final Advice
|
||||
|
||||
Do not try to learn all of this in one go. Seriously, do not. You will burn out and hate math forever.
|
||||
|
||||
Instead, learn Phase 1 and 2 thoroughly before touching any ML. Then start a simple ML project (linear regression from scratch). When you hit something you do not understand, come back and learn Phase 3 or 4. Repeat.
|
||||
|
||||
The goal is not to memorize theorems. The goal is to understand what is happening when you type **model.forward(x)**. Linear algebra gives you that x-ray vision.
|
||||
|
||||
Also, do not feel bad if it takes months. Some of this stuff took me years to really get. And I still Google things. Everyone does. You are not dumb for forgetting what a Jacobian is, you just have not used it in a while.
|
||||
|
||||
Keep going. Build stuff. Break stuff. Fix it. That is the only path.
|
||||
@@ -0,0 +1,123 @@
|
||||
---
|
||||
title: "The Math That Made $1M+ for quant Traders in 30 Days"
|
||||
source: "https://x.com/0xRicker/status/2044722741706678282"
|
||||
author:
|
||||
- "[[@0xRicker]]"
|
||||
published: 2026-04-16
|
||||
created: 2026-04-26
|
||||
description: "They don't use the same algorithm. They use the same thinking.Behind every profitable trader is not luck, intuition, or a mysterious black-..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
> They don't use the same algorithm. They use the same thinking. Behind every profitable trader is not luck, intuition, or a mysterious black-box AI. There is concrete mathematics.
|
||||
|
||||
## 1\. The Math Under the Hood
|
||||
|
||||
Most people look at a Polymarket account making [$400K](https://x.com/search?q=%24400K&src=cashtag_click) in a month and say: lucky bot. They're wrong.
|
||||
|
||||
There's a mathematical framework behind every single trade - one that has been in academic literature since the 1950s and is still almost completely absent from prediction markets. It's called **Markov Chains**. The core tool is the transition matrix ( P ), where each element pijp\_{ij}p\_{ij} represents the probability of moving from state ( i ) to state ( j ):
|
||||
|
||||

|
||||
|
||||
The core idea is deliberately simple: you don't need to predict where price is going. You need to measure which state the market is in right now - and what the probability of the next state is. If that probability is high enough, you enter. If it is not, you wait.
|
||||
|
||||
No technical analysis. No news reading. No gut feeling. Just a probability table, updated every minute from live data.
|
||||
|
||||

|
||||
|
||||
The machine builds a **transition matrix** - a grid of probabilities mapping every price state to the likelihood of the next one. The diagonal of that matrix is the key: how likely the market is to stay in its current state. Entry happens only when that diagonal value clears **0.87**.
|
||||
|
||||

|
||||
|
||||
Transition matrix P - each diagonal cell is the state persistence value. Bot enters only when p(j\*,j\*) ≥ 0.87
|
||||
|
||||
```python
|
||||
Core entry filter — two conditions, both must be true
|
||||
def should_enter(P, current_state, market_price, tau=0.87, eps=0.05):
|
||||
# Enter only when gap AND persistence both clear
|
||||
j_star = np.argmax(P[current_state]) # optimal next state
|
||||
p_hat = P[current_state][j_star] # model probability
|
||||
persist = P[j_star][j_star] # diagonal: state persistence
|
||||
gap = p_hat - market_price # arbitrage gap delta (2.2)
|
||||
|
||||
return gap >= eps and persist >= tau # eq.(2.2) AND eq.(2.3)
|
||||
```
|
||||
|
||||
> Two conditions. Both must be true. One function is the entire decision engine - and it runs **once per minute, across every open window, on every asset, 24 hours a day.**
|
||||
|
||||
## 2\. Three Accounts. One Month
|
||||
|
||||
Here are three bots that ran this framework on Polymarket in March–April 2026. Different assets, different entry logic, different position sizes. Same underlying principle.
|
||||
|
||||

|
||||
|
||||
Combined · 48,061 predictions · 30 days $1,331,821 Profit
|
||||
|
||||
These are not outlier results. They follow directly from the parameter specifications in the math. Let's look at the formal parameter table:
|
||||
|
||||

|
||||
|
||||

|
||||
|
||||
Equations (2.6)–(2.7): formal parameter specification for each bot - execution rates, entry windows, thresholds
|
||||
|
||||
> Bonereaper operates in the narrowest entry window (83–97¢), yielding the lowest variance. 0xB27BC932 accepts entries from 1–96¢, maximizing trade frequency at the cost of higher per-trade variance. **Both are profitable - just different implementations of eq. (2.7).**
|
||||
|
||||
## 3\. How Each Bot Reads the Market
|
||||
|
||||
Same principle. Three completely different implementations. Here is the math that separates them.
|
||||
|
||||
1. [Bonereaper](https://polymarket.com/profile/0xeebde7a0e019a63e6b476eb425505b7b3e6eba30?via=track) **- High-Confidence Spread Capture** Eq. (2.8): expected return = (1 − q) / q ≈ 10% at mean entry 91¢
|
||||
|
||||

|
||||
|
||||
Trades hourly BTC and ETH Up/Down windows at 83–97¢. The model agrees with the crowd direction but sees the market underpricing certainty. 1,500–2,900 shares per position. Collects 4–19% per resolution. Low variance. **BTC + ETH 1h windows Entry 83–97 ¢r̅ = 0.038%**
|
||||
|
||||
2\. [0xe1D6b514](https://polymarket.com/profile/0xe1d6b51521bd4365769199f392f9818661bd907c?via=track) **- Dual-Mode Expected Value** Eq. (2.9): blended EV from two concurrent strategies
|
||||
|
||||

|
||||
|
||||
Directional scalps at 64–83¢ (20–54% per trade) running alongside price level locks at 99.5–99.8¢. The $42,200 best trade at 64.7¢ entry follows eq. (2.10): r = 0.353/0.647 = 54.6%. **BTC + ETH Dual strategy Entry 64–99¢ Max +54.6%**
|
||||
|
||||
3\. [0xB27BC932](https://polymarket.com/profile/0xb27bc932bf8110d8f78e55da7d5f0497a18b5b82?via=track) **- Multi-Asset Variance Reduction** Eq. (2.11): 5 assets reduces volatility by 55% at same expected return
|
||||
|
||||

|
||||
|
||||
BTC, ETH, SOL, BNB, XRP across 5-min windows. Entry at 1.3¢ follows eq. (2.12): mark-to-market return = (0.655−0.013)/0.013 = 4876%, unrealized. Volume is the edge: 1 trade per 1.7 minutes. **5 assets 5-min windows σ reduced 55% 1 trade / 1.7 min**
|
||||
|
||||
> Lower entry = higher potential return per eq. (2.8). The tradeoff is variance. **All three found their own working balance - all three profitable.**
|
||||
|
||||

|
||||
|
||||
## 4\. The Real Edge
|
||||
|
||||
Here is the part nobody talks about. Polymarket's crypto markets are priced by humans. And humans have a fundamental limitation: they are not online at 3AM watching a 5-minute BTC window.
|
||||
|
||||
When human attention drops, the market still sets prices - but those prices are **lazy, stale, and exploitable**. The gap M(t) from eq. (2.13) is widest precisely when nobody is watching.
|
||||
|
||||

|
||||
|
||||
The second layer is **compounding**. Eq. (2.14)–(2.15) show that by the law of large numbers, sample mean log-returns converge to the true expected return - making the exponential growth formula exact for large N.
|
||||
|
||||

|
||||
|
||||
> Kelly criterion (eq. 2.17) explains why the bots don't blow up: f\* ≈ 0.71 is high enough to compound aggressively, low enough to avoid ruin. **It's not luck. It's optimal bet sizing.**
|
||||
|
||||
## 5\. The Closer
|
||||
|
||||
$1,331,821 in 30 days. Three bots. Three strategies. One mathematical principle.
|
||||
|
||||
- The market prices uncertainty. The model measures it. The gap between those two numbers is the edge - eq. (2.2). It exists in every window that humans are not watching.
|
||||
- 0.034% per trade sounds like nothing. Eq. (2.14)–(2.15) show it becomes ×240 at 16K trades. The math does not care about your conviction - only about N.
|
||||
- Kelly criterion (eq. 2.17) keeps the bots from blowing up. f\* ≈ 0.71 is the exact point where growth is maximized without risking ruin.
|
||||
- Theorem 2.1: as long as humans misprice short windows, the arbitrage gap persists and the edge is structurally self-sustaining. No prediction required.
|
||||
|
||||
> “The market rewards people who understand probability. Everyone else is just providing the liquidity.”
|
||||
|
||||
3 traders from article: 1. [https://polymarket.com/profile/0xeebde7a0e019a63e6b476eb425505b7b3e6eba30?via=track](https://polymarket.com/profile/0xeebde7a0e019a63e6b476eb425505b7b3e6eba30?via=track)
|
||||
|
||||
2\. [https://polymarket.com/profile/0xe1d6b51521bd4365769199f392f9818661bd907c?via=track](https://polymarket.com/profile/0xe1d6b51521bd4365769199f392f9818661bd907c?via=track)
|
||||
|
||||
3\. [https://polymarket.com/profile/0xb27bc932bf8110d8f78e55da7d5f0497a18b5b82?via=track](https://polymarket.com/profile/0xb27bc932bf8110d8f78e55da7d5f0497a18b5b82?via=track) Fastest way to copy-trade them even with $10 using: [http://kreo.app/@0xRicker](https://t.co/7qw0SmU8UR)
|
||||
+242
@@ -0,0 +1,242 @@
|
||||
---
|
||||
title: "The Math That Made $40,000,000 on Polymarket (Complete Trading Roadmap)"
|
||||
source: "https://x.com/adiix_official/status/2044121546189639953"
|
||||
author:
|
||||
- "[[@adiix_official]]"
|
||||
published: 2026-04-15
|
||||
created: 2026-04-26
|
||||
description: "While you were checking if YES + NO = $1.When you see a Polymarket market where YES is $0.62 and NO is $0.33, you think that adds up to $0...."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
**While you were checking if YES + NO = $1.**When you see a Polymarket market where YES is $0.62 and NO is $0.33, you think that adds up to $0.95, there's arbitrage. You're right. What you never realize is that while you're manually checking whether YES plus NO equals $1, quantitative systems are solving integer programs scanning 17,218 conditions across 2^63 possible outcomes in milliseconds.
|
||||
|
||||
By the time you place both orders, the spread is gone. The systems found the same violation across dozens of correlated markets, calculated optimal position sizes accounting for order book depth and fees, executed parallel trades and rotated capital into the next opportunity.
|
||||
|
||||
The difference isn't speed. It's mathematical infrastructure.
|
||||
|
||||
A research paper published in 2025 "Unravelling the Probabilistic Forest: Arbitrage in Prediction Markets" documented exactly what happened. From April 2024 to April 2025, quantitative traders extracted **$39,688,585** in guaranteed arbitrage profits from Polymarket. The top single trader made $2,009,631.76 from 4,049 trades. That's $496 guaranteed profit per trade, systematically, for a year.
|
||||
|
||||
**The key word is guaranteed.** This wasn't prediction. This wasn't luck. This was math identifying situations where one outcome pays $1 and you can buy it for less. No matter what happens, you profit. The only question is whether you can execute before the market corrects.
|
||||
|
||||

|
||||
|
||||
# Why simple math fails the marginal polytope problem
|
||||
|
||||
Here's what most people get wrong. They think arbitrage detection is about checking if numbers add up. It's not. It's about solving constraint satisfaction problems over exponentially large outcome spaces.
|
||||
|
||||
Single market, single condition: "Will Trump win Pennsylvania?" YES: $0.48, NO: $0.52. Looks perfect. No arbitrage. Now add: "Will Republicans win Pennsylvania by 5+ points?" YES: $0.32, NO: $0.68. Both sum to $1. Still looks fine.
|
||||
|
||||
But there's a logical dependency. **If Republicans win by 5+ points, Trump must win Pennsylvania.** These markets aren't independent. That creates arbitrage. And no simple addition check catches it.
|
||||
|
||||
## The scale of the problem
|
||||
|
||||
For any market with n conditions, there are 2^n possible price combinations. For the 2024 US election alone, there were 305 markets — creating 46,360 possible pairs to check. The NCAA 2010 tournament market had 63 games, meaning 2^63 = 9,223,372,036,854,775,808 possible outcomes.
|
||||
|
||||
Brute force is impossible. So quantitative systems don't enumerate. They constrain.
|
||||
|
||||

|
||||
|
||||
Real example from the Duke vs Cornell basketball market: Each team has 7 possible win-count outcomes. That's 14 conditions 2^14 = 16,384 combinations. But they can't both win 5+ games because they'd meet in the semifinals. Three linear constraints replace 16,384 brute force checks.
|
||||
|
||||

|
||||
|
||||
**What the research found:** Out of 17,218 conditions examined, 7,051 (41%) showed single-market arbitrage. The median mispricing was $0.60 meaning markets were regularly wrong by 40%. Not close to efficient. Massively exploitable.
|
||||
|
||||
# Bregman projection how to calculate the perfect trade
|
||||
|
||||
Finding arbitrage is one problem. Calculating the optimal trade is another. You can't just "fix" prices by averaging. You need to project the current market state onto the arbitrage-free manifold while preserving the information structure.
|
||||
|
||||
Standard distance metrics fail here. A price move from $0.50 to $0.60 has different information content than a move from $0.05 to $0.15, even though both are 10 cents. Market makers use logarithmic cost functions where prices represent probabilities. The math must respect this.
|
||||
|
||||
The formula for guaranteed profit
|
||||
|
||||
The maximum guaranteed profit from any arbitrage trade equals the Bregman divergence between the current market state and its projection onto the arbitrage-free set:
|
||||
|
||||

|
||||
|
||||
This is what the top arbitrageur was doing 4,049 times over a year. Each trade was solving this optimization problem faster and more accurately than every other participant. The $2 million wasn't luck. It was the consistent output of a mathematical system running at scale.
|
||||
|
||||
# Frank-Wolfe algorithm making the impossible tractable
|
||||
|
||||
Computing the Bregman projection directly is intractable. The arbitrage-free set M has exponentially many vertices you'd need to enumerate every valid outcome, which is impossible at scale.
|
||||
|
||||
The Frank-Wolfe algorithm solves this by reducing projection to a sequence of linear programs that build the solution iteratively. Instead of finding the entire set at once, it grows an active set one vertex at a time.
|
||||
|
||||
- **Start with a small set**of known valid outcomes
|
||||
- **Each iteration:**solve a convex optimization over the current set, then find one new vertex via integer programming
|
||||
- **Convergence gap**tells you when to stop typically 50–150 iterations
|
||||
- **Active set grows by one**per iteration after 100 iterations, tracking 100 vertices instead of 2^63
|
||||
|
||||

|
||||
|
||||
The research showed a crossover point: once enough outcomes settle, integer programs solve fast enough for real-time trading. After 45 games were settled in the NCAA tournament, the first successful 30-minute projection completed. For the remaining tournament, the Frank-Wolfe method outperformed the baseline by 38% on median security prices.
|
||||
|
||||
**Why does it get faster over time?** As outcomes settle, the feasible set shrinks. Fewer variables, tighter constraints, faster solves. Early in a tournament: 10–30 second solve times. Late in a tournament: under 5 seconds. The system accelerates as the event unfolds.
|
||||
|
||||
# Execution where most strategies fail
|
||||
|
||||
You've detected arbitrage. You've computed the optimal trade. Now you need to execute. This is where most people get destroyed.
|
||||
|
||||
Polymarket uses a Central Limit Order Book. Unlike decentralized exchanges where arbitrage can be atomic, CLOB execution is sequential. Your arbitrage plan: buy YES at $0.30, buy NO at $0.30, guaranteed $0.40 profit. Reality: YES fills at $0.30 ✓. Price updates. NO fills at $0.78 ✗. You just lost $0.08.
|
||||
|
||||
## The latency hierarchy
|
||||
|
||||

|
||||
|
||||
The 2-second window is not a bug. It's a structural feature. Polygon block time is 2 seconds. Everyone waits for the same blockchain. The edge comes from the 30 seconds before that the detection-to-submission window where fast systems submit all legs in one block and slow systems are still reading the market.
|
||||
|
||||
## Why copy-trading fast wallets fails
|
||||
|
||||
What you think happens
|
||||
|
||||
- You see their profitable trade on-chain
|
||||
- You copy the same position
|
||||
- You capture the same profit
|
||||
- You win alongside them
|
||||
|
||||
What actually happens
|
||||
|
||||
- Block N-1: system detects, submits in 30ms
|
||||
- Block N: all legs confirm, arbitrage captured
|
||||
- Block N+1: you see it and copy
|
||||
- You paid $0.344 for what they bought at $0.322
|
||||
- You're providing exit liquidity, not arbitraging
|
||||
|
||||
So the only way copy-trading works is if your execution fires in the same block as the original wallet. That's a hard technical requirement not a preference.
|
||||
|
||||
I tested a lot of bots. Most of them are too slow. By the time the Telegram signal fires, the position is already gone and you're buying into a moved market. I tried service after service looking for something that actually executes at block level.
|
||||
|
||||
## For copying trades I use Ares TG Bot
|
||||
|
||||
Join the TG Bot: [https://t.me/AresProTradingBot?start=r\_adiix](https://t.me/AresProTradingBot?start=r_adiix)
|
||||
|
||||
Executes at block level. Tracks the top 15+ wallets listed above. Automatic. Fastest I've found and I've tried most of them.
|
||||
|
||||
**This is not an advertisement, I really earned a five-digit amount using this tool**
|
||||
|
||||

|
||||
|
||||
# What was actually deployed the complete system
|
||||
|
||||
Theory is clean. Production is messy. Here's what a working arbitrage system actually looks like based on the research findings.
|
||||
|
||||
- **Data pipeline** Real-time
|
||||
|
||||
WebSocket connection to Polymarket CLOB API for live order book updates and trade feeds. Alchemy Polygon node for querying the OrderFilled contract events. The research analyzed 86 million transactions this requires infrastructure, not scripts.
|
||||
|
||||
- **Dependency detection** AI-powered
|
||||
|
||||
DeepSeek-R1-Distill-Qwen-32B with prompt engineering to classify market pairs. Input: two market descriptions. Output: JSON of valid outcome combinations. 81.45% accuracy on complex multi-condition election markets. Good enough for filtering; requires manual verification for execution.
|
||||
|
||||
- **Optimization engine** 3 layers
|
||||
|
||||
Layer 1: Fast linear programming relaxations for obvious mispricings (milliseconds). Layer 2: Frank-Wolfe algorithm with Gurobi IP solver for complex cases (1–30 seconds depending on market state). Layer 3: Execution validation against live order book before any order is submitted.
|
||||
|
||||
- **Position sizing** Kelly criterion
|
||||
|
||||
Modified Kelly criterion accounting for execution risk and order book depth. Position cap at 50% of available order book depth to avoid moving the market against yourself. Every position re-sized in real-time based on current portfolio value.
|
||||
|
||||
# The actual numbers broken down
|
||||
|
||||
The research broke down where the $39.7 million came from. Three distinct strategies, each exploiting a different type of market inefficiency.
|
||||
|
||||

|
||||
|
||||
The top 10 extractors took $8,127,849 20.5% of the total. The top single extractor made $2,009,632 from 4,049 trades. Average profit per trade: $496. Not lottery wins. Not lucky timing. Mathematical precision executed systematically over 365 days.
|
||||
|
||||

|
||||
|
||||
## What separates winners the honest breakdown
|
||||
|
||||
The research makes the gap explicit. Two groups of participants, same markets, same information, completely different outcomes.
|
||||
|
||||
Retail approach
|
||||
|
||||
- Check prices every 30 seconds manually
|
||||
- Look for obvious YES + NO ≠ $1
|
||||
- Submit orders sequentially via UI
|
||||
- No position sizing framework
|
||||
- No execution risk management
|
||||
- Providing exit liquidity to fast wallets
|
||||
|
||||
Quantitative approach
|
||||
|
||||
- Real-time WebSocket feeds <5ms
|
||||
- Integer programming for dependency detection
|
||||
- Bregman projection for optimal trades
|
||||
- Frank-Wolfe with Gurobi IP solver
|
||||
- Parallel order execution, same block
|
||||
- Kelly-based position sizing, live recalculation
|
||||
|
||||
One group extracted $40 million. The other group provided the liquidity that made it possible.
|
||||
|
||||
**The research paper is public.** The algorithms are known. arXiv:2508.03474. The theory foundation: arXiv:1606.02825v2. The math works. The infrastructure exists. The only question is whether you can build it before the next $40 million is extracted.
|
||||
|
||||
## 15 bots that made more money than most people earn in a lifetime
|
||||
|
||||
Theory is one thing. Here's what the math looks like when it actually runs. These are real, verified Polymarket profiles all publicly visible on-chain. Their PnL curves are not luck. They are the output of systematic strategies running the same loops, day after day, with mechanical consistency.
|
||||
|
||||
The total across these 15 wallets: **over $51 million in documented profit.**
|
||||
|
||||
- [kch123](https://polymarket.com/@kch123?r=ecosystem)—Latency arb · high frequency **$12,000,000**
|
||||
- [RN1](https://polymarket.com/@rn1?r=ecosystem)—Market making · multi-market **$7,400,000**
|
||||
- [Swisstony](https://polymarket.com/@swisstony?r=ecosystem)—Oracle arbitrage · Chainlink **$5,900,000**
|
||||
- [GamblingIsAllYouNeed](https://polymarket.com/@gamblingisallyouneed?r=ecosystem)—News-driven · AI probability **$4,600,000**
|
||||
- [DrPufferfish](https://polymarket.com/@drpufferfish?r=ecosystem)—Combinatorial arb · multi-market **$3,400,000**
|
||||
- [sovereign2013](https://polymarket.com/@sovereign2013?r=ecosystem)—Latency arb · BTC/ETH contracts **$3,400,000**
|
||||
- [0x2a2C53bD27](https://polymarket.com/@0x2a2c53bd278c04da9962fcf96490e17f3dfb9bc1-1772479215461?r=ecosystem)—Market rebalancing · systematic **$2,500,000**
|
||||
- [Countryside](https://polymarket.com/@countryside?r=ecosystem)—Election markets · base rate **$2,400,000**
|
||||
- [gatorr](https://polymarket.com/@gatorr?r=ecosystem)—Latency arb · parallel execution **$2,300,000**
|
||||
- [weflyhigh](https://polymarket.com/@weflyhigh?r=ecosystem)—Multi-strategy · diversified **$1,800,000**
|
||||
- [blindStaking](https://polymarket.com/@blindstaking?r=ecosystem)—Market making · liquidity provision **$1,500,000**
|
||||
- [CharlieKirkEvans](https://polymarket.com/@0x2a2c53bd278c04da9962fcf96490e17f3dfb9bc1-1772479215461?r=ecosystem)—Political markets · news arb **$1,200,000**
|
||||
- [JPMorgan101](https://polymarket.com/profile/0xb6d6e99d3bfe055874a04279f659f009fd57be17?r=ecosystem)—Institutional-style systematic **$1,100,000**
|
||||
- [cigarettes](https://polymarket.com/profile/0xd218e474776403a330142299f7796e8ba32eb5c9?r=ecosystem)—High-frequency · short contracts **$850,000**
|
||||
- [Sharky6999](https://polymarket.com/profile/0x751a2b86cab503496efd325c8344e10159349ea1?r=ecosystem)—Latency arb · crypto contracts **$813,000**
|
||||
|
||||
# How to start trading on Polymarket
|
||||
|
||||
Now that you understand how the math works here's how to actually get on the platform and what's in it for you right now.
|
||||
|
||||
## What is the Polymarket drop?
|
||||
|
||||
Polymarket has been running an active rewards program for new and existing traders. New users who register and place their first trades during active campaign periods receive platform rewards USDC distributed directly to your wallet based on trading volume and activity. The program is designed to bootstrap liquidity, which means **early participants get disproportionately large rewards** relative to the volume they bring.
|
||||
|
||||
This is not speculation. Polymarket's rewards structure is documented on the platform and has paid out to thousands of traders. The earlier you participate, the larger your share of the reward pool.
|
||||
|
||||
- Register
|
||||
|
||||
Go to the link below and connect your wallet MetaMask or Coinbase Wallet
|
||||
|
||||
[Polymarket AirDrop](https://polymarket.com/?r=ecosystem)
|
||||
|
||||
- Fund with USDC
|
||||
|
||||
Deposit via Polygon network only not ETH mainnet. Bridge USDC if needed.
|
||||
|
||||
- Place your first trade
|
||||
|
||||
Pick any active market and place a small position. $10–$50 is enough to start and qualify.
|
||||
|
||||
- Check your rewards
|
||||
|
||||
Open the Rewards tab. Your current drop allocation is shown in USDC and updates with volume.
|
||||
|
||||
- Scale volume
|
||||
|
||||
Higher trading volume = larger share of the reward pool. The earlier you start the more you get.
|
||||
|
||||
**Why register now:** Reward pools are time-limited and distributed proportionally to early participants. The math that extracted [$40M](https://x.com/search?q=%2440M&src=cashtag_click) from Polymarket required millions in capital and sophisticated infrastructure. Getting rewarded for simply trading on the platform during the drop period requires neither. This is the low-barrier version of being on the right side of the market.
|
||||
|
||||

|
||||
|
||||
The math works. The infrastructure exists. The only question is execution.
|
||||
|
||||
This took days to research and write. If it helped you understand what's actually happening on Polymarket share it. Someone in your feed is trading against systems like this right now and has no idea.
|
||||
|
||||
**Part 2 coming** building the system from scratch. Follow to get it when it drops.
|
||||
|
||||
[@adiix\_official](https://x.com/@adiix_official)
|
||||
@@ -0,0 +1,228 @@
|
||||
---
|
||||
title: "The Next Intelligence Breakthrough Won’t Look Like the Last"
|
||||
source: "https://x.com/agihouse_org/status/2048225702198288675"
|
||||
author:
|
||||
- "[[@agihouse_org]]"
|
||||
published: 2026-04-26
|
||||
created: 2026-04-26
|
||||
description: "On Feburary 18, AGI House hosted a dinner on frontier AI research.Around the table were researchers who helped build early RL systems at maj..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
On Feburary 18, AGI House hosted a dinner on **frontier AI research**.
|
||||
|
||||
Around the table were researchers who helped build early RL systems at major labs, architects of open-source model ecosystems, distributed systems pioneers, robotics builders, AI-for-science founders, professors, investors, and infrastructure operators. The conversation spanned robotics simulation, parallel intelligence, self-improving systems, Chinese hardware supply chains, coding agents, world models, and whether someone in the room might accidentally trigger a [$100B](https://x.com/search?q=%24100B&src=cashtag_click) public company collapse within two months.
|
||||
|
||||
Who is in the room:
|
||||
|
||||
Sebastian Thrun (Co-founder @ Waymo), Peter Welinder (VP @ OpenAI), Thomas Kipf (Research Scientist @ Google DeepMind), Joseph Spisak (Director @ Meta Superintelligence), Ankur Handa (Co-lead, Dex Team @ NVIDIA), Robert Nishihara (Co-founder @ AnyScale), Tim Shi (Co-founder @ Cresta), Nazneen Rajani (CEO @ Collinear), Robert Yang (CEO @ Fundamental Research Labs), Carina Hong (CEO @ Axiom Math), Volodymyr Kuleshov (Co-founder @ Inception Labs), Joyee Wang (Researcher @ Stanford AI Lab), Jesus Lares (MTS @ AGI House), Kexin Huang (CEO @ Phylo Bio), Di Jin (Co-founder @ Eigen AI), Patrick McGovern (Chair @ McGovern Foundation), Lavanya Shukla (Head of AI @ CoreWeave), David Cahn (Partner @ Sequoia Capital), Rocky Yu (Founder @ AGI House, Host)📷
|
||||
|
||||
Below is a synthesis of the themes that emerged.
|
||||
|
||||
**The Frontier Is Shifting: From Bigger Models to Better Systems**
|
||||
|
||||
The conversation quickly moved beyond “just scale it.”
|
||||
|
||||
Yes, scaling laws still hold directionally. Yes, frontier training runs cost hundreds of millions of dollars. But the deeper questions now are:
|
||||
|
||||
- How do we move from **sequential intelligence to parallel intelligence**?
|
||||
- How do we embed **time, memory, and continual learning** directly into architectures?
|
||||
- How do we scale **systems**, not just models?
|
||||
- How do we make AI operate robustly in the real world — not just benchmarks?
|
||||
|
||||
The tone wasn’t hype-driven. It was architectural.
|
||||
|
||||
**Simulation Is About to Have Its LLM Moment**
|
||||
|
||||
One of the strongest themes of the evening: we are dramatically underinvesting in simulation — especially for robotics.
|
||||
|
||||
Several participants argued:
|
||||
|
||||
- Physics engines are underutilized.
|
||||
- Teleoperation doesn’t scale.
|
||||
- We’re still overly dependent on real-world data collection.
|
||||
|
||||
**Prediction:** Within 2–3 years, robotics simulation will hit a breakthrough moment similar to what LLMs experienced with text generation.
|
||||
|
||||
World models and video generation systems are approaching visual indistinguishability (e.g., Sora-class systems), but they are not yet physically consistent enough for training robot controllers. Temporal coherence and contact dynamics remain bottlenecks.
|
||||
|
||||
That said:
|
||||
|
||||
- Within 1–2 years, training robot controllers primarily in simulation may become viable.
|
||||
- Robotics will achieve impressive pick-and-place capabilities within ~2 years.
|
||||
- The U.S. is underestimating China’s hardware and robotics supply chain advantage.
|
||||
|
||||
**Intelligence: Sequential Today, Parallel Tomorrow**
|
||||
|
||||
A provocative idea: today’s intelligence is fundamentally **sequential** — token by token, step by step.
|
||||
|
||||
But human cognition is massively parallel.
|
||||
|
||||
Diffusion-based language models generating ~1,000 tokens per second were cited as early signals of a shift away from strictly autoregressive thinking. The broader claim:
|
||||
|
||||
Intelligence will need to become parallel to break through current ceilings.
|
||||
|
||||
Related idea: **Transformer architectures may not be sufficient for AGI** without explicitly incorporating time and memory dynamics into their core design.
|
||||
|
||||
**The Efficiency Gap Is Still Massive**
|
||||
|
||||
One debate centered around computability and efficiency:
|
||||
|
||||
- The estimated lifetime electricity cost of a human brain is roughly ~$500 at retail energy prices.
|
||||
- Frontier AI systems require training runs costing hundreds of millions to approach similar levels of competence in narrow domains.
|
||||
|
||||
Implication: There are still **orders of magnitude of efficiency gains available**.
|
||||
|
||||
Algorithmic improvements may ultimately matter more than raw compute expansion.
|
||||
|
||||
**Coding Agents as a Path to AGI**
|
||||
|
||||
A recurring thesis: intellectual work already happens on computers.
|
||||
|
||||
If AGI emerges first anywhere, it may not be in robotics — it may be in **coding agents** capable of autonomously:
|
||||
|
||||
- Writing production software
|
||||
- Debugging large systems
|
||||
- Designing experiments
|
||||
- Improving their own infrastructure
|
||||
|
||||
Some argued that certain frontier systems are already better than any single engineer in constrained domains.
|
||||
|
||||
Others pushed back, pointing to brittleness, lack of generality, and robustness failures.
|
||||
|
||||
The table was split on whether “AGI” has already been achieved in narrow economic terms.
|
||||
|
||||
**Evaluation Is the Quiet Bottleneck**
|
||||
|
||||
Benchmarks are saturating. Public leaderboards are gamed. Real-world robustness remains unsolved.
|
||||
|
||||
Formal verification is gaining renewed attention in AI safety discussions. If models are writing critical infrastructure code, probabilistic correctness may not be enough.
|
||||
|
||||
A strong consensus emerged:
|
||||
|
||||
Evaluation may be the true bottleneck of 2026.
|
||||
|
||||
**Robotics & Physical AI: The Infrastructure Layer Matters**
|
||||
|
||||
Discussion shifted toward physical AI and supply chains:
|
||||
|
||||
- Chinese robotics hardware development is accelerating rapidly.
|
||||
- U.S. investors are underestimating the scale and velocity of progress.
|
||||
- Supply chain and manufacturing infrastructure may be the real constraint on robotics scaling.
|
||||
|
||||
Waymo adoption was cited as evidence that society will accept AI in life-critical contexts faster than expected — once reliability crosses a certain threshold.
|
||||
|
||||
**World Models & Video Generation**
|
||||
|
||||
Video generation systems are crossing visual indistinguishability thresholds.
|
||||
|
||||
But visual realism ≠ physical consistency.
|
||||
|
||||
Key challenges remaining:
|
||||
|
||||
- Temporal consistency over long rollouts
|
||||
- Contact dynamics modeling
|
||||
- Bridging visual world models with control policies
|
||||
- Using video models for training, not just evaluation
|
||||
|
||||
The optimistic view: 1–2 years to meaningful simulation-based robot controller training.
|
||||
|
||||
The cautious view: physics modeling remains underdeveloped relative to visual modeling.
|
||||
|
||||
**Systems Over Single Models**
|
||||
|
||||
There was broad agreement that AGI will likely emerge from **systems**, not a single monolithic model.
|
||||
|
||||
Important research directions raised:
|
||||
|
||||
- Continual learning
|
||||
- Context engineering
|
||||
- Long-horizon memory management
|
||||
- Active exploration in RL vs passive token sampling
|
||||
- Multi-modal integration beyond vision
|
||||
- Distributed systems for heterogeneous AI workloads
|
||||
|
||||
One especially sharp idea:
|
||||
|
||||
Context engineering may become a bigger compute workload than training.
|
||||
|
||||
Inference-time compute — reasoning loops, tool calls, search trees — may rival or exceed training-time compute.
|
||||
|
||||
**Economic Shockwaves**
|
||||
|
||||
The conversation turned speculative at times.
|
||||
|
||||
Questions raised:
|
||||
|
||||
- Will 50% of GDP be AI-generated by the end of 2027?
|
||||
- What does a post-AGI economy even look like?
|
||||
- What are the limits of human intelligence in comparison to synthetic systems?
|
||||
|
||||
One bold prediction:
|
||||
|
||||
Someone at this table will trigger a [$100B](https://x.com/search?q=%24100B&src=cashtag_click) public company loss within two months — via an AI-related incident that becomes major media news.
|
||||
|
||||
The point wasn’t recklessness. It was acknowledgment of the scale of leverage now in play.
|
||||
|
||||
**🔥** **Hot Takes from the Table**
|
||||
|
||||
Here’s a distilled list of sharper claims and predictions from the evening:
|
||||
|
||||
- We are underinvesting in simulation — robotics will have its LLM moment within 2–3 years.
|
||||
- Teleoperation doesn’t scale; physics engines are massively underutilized.
|
||||
- Transformer architectures alone cannot achieve AGI — time must be built into the architecture.
|
||||
- Intelligence today is sequential; the next leap requires parallelism.
|
||||
- Coding agents are the most likely path to AGI because intellectual work is already digital.
|
||||
- Some frontier models are already better than any single engineer in specific domains.
|
||||
- Context engineering may soon consume more compute than training.
|
||||
- Modeling raw sensory data may be “AGI complete” — and we’re underinvesting in it.
|
||||
- Formal verification will become central to AI safety.
|
||||
- China’s robotics supply chain advantage is underestimated in the U.S.
|
||||
- Efficiency gains available in AI are still orders of magnitude away from biological efficiency.
|
||||
- Experience may be inversely correlated with AI effectiveness — newer graduates sometimes adapt faster.
|
||||
- Scaling laws will continue — but will hit real-world interface limits.
|
||||
- Within 2 years, robotics pick-and-place will be impressively solved.
|
||||
- Within 1–2 years, simulation-trained robot controllers may become viable.
|
||||
- AI-for-math and AI-for-science applications are returning to prominence.
|
||||
- Someone will accidentally trigger a nine-figure market event through AI misuse or failure.
|
||||
|
||||
**What Felt Different**
|
||||
|
||||
Compared to similar conversations even a year ago, the tone has changed.
|
||||
|
||||
Less “AGI next quarter.”
|
||||
|
||||
More:
|
||||
|
||||
- Systems design
|
||||
- Infrastructure
|
||||
- Memory and time
|
||||
- Evaluation
|
||||
- Supply chains
|
||||
- Economic consequences
|
||||
|
||||
There was also an undercurrent of something else: inevitability.
|
||||
|
||||
Not hype. Not panic.
|
||||
|
||||
Just the sense that the slope is steepening.
|
||||
|
||||
**Why We Host These Dinners**
|
||||
|
||||
AGI House exists to create rooms where frontier builders can think together — candidly and off-stage.
|
||||
|
||||
No slides.
|
||||
|
||||
No recorded panels.
|
||||
|
||||
No performative optimism.
|
||||
|
||||
Just honest technical debate about what’s actually happening.
|
||||
|
||||
We’ll continue hosting these dinners regularly. If you’re working at the edge — in research, robotics, systems, infrastructure, safety, or applied AI — we’d love to have you at a future one.
|
||||
|
||||
Ref.: [https://blog.agihouse.org/posts/agi-dinner-series-frontier-ai-research](https://blog.agihouse.org/posts/agi-dinner-series-frontier-ai-research)
|
||||
|
||||
**Please drop a note at: info@agihouse.org if you’re interested in sponsoring the next dinner.**
|
||||
@@ -0,0 +1,106 @@
|
||||
---
|
||||
title: "These Are 23 Great Rules To Be A Productive Creative"
|
||||
source: "https://x.com/RyanHoliday/status/2048066241550487676"
|
||||
author:
|
||||
- "[[@RyanHoliday]]"
|
||||
published: 2026-04-25
|
||||
created: 2026-04-26
|
||||
description: "[1] Read. Read. Read.A book is made of books. “The greatest part of a writer’s time is spent in reading; a man will turn over half a library..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
**\[1\] Read. Read. Read.**
|
||||
|
||||
A book is made of books. “The greatest part of a writer’s time is spent in reading; a man will turn over half a library to make one book,” Samuel Johnson said. As I was putting together the bibliography for [Courage](https://store.dailystoic.com/pages/courage), I counted something like 300 books I was directly sourcing from.
|
||||
|
||||
**\[2\] Always be researching**
|
||||
|
||||
The bulk of the work is researching—collecting stories, anecdotes, and data to marshal your argument. The writing is stringing those pieces together. I’ve found stuff I’ve used in in-flight magazines, discovered snippets on social media, even heard things mentioned on TV. As Shelby Foote [put it in an interview](http://www.theparisreview.org/interviews/931/the-art-of-fiction-no-158-shelby-foote) with The Paris Review: “I can’t begin to tell you the things I discovered while I was looking for something else.”
|
||||
|
||||
**\[3\] Put good advice where you work**
|
||||
|
||||
Print and put a couple of [important quotes up on the wall](https://ryanholiday.net/print-out-good-advice-and-put-it-where-you-work-you-wont-be-able-to-run-away-from-it/) to help guide you (either generally, or for a specific project). When I was working on [Ego is the Enemy](https://www.thepaintedporch.com/products/ryan2?_pos=1&_sid=568f40a2f&_ss=r), I had this quote from Machiavelli on the wall to inspire its style and ethos: “I have not adorned this work with fine phrases, with swelling, pompous words, or with any of those blandishments or external ornaments with which many set forth and decorate their matter. For I have chosen either that nothing at all should bring it honor or that the variety of its material and the gravity of its subject matter alone should make it welcome.” I have another quote that I put up for this book from Martha Graham: “Never be afraid of the material. The material knows when you’re frightened and will not help.”
|
||||
|
||||
**\[4\] Make commitments**
|
||||
|
||||
I turn in a book proposal for my next book before my latest one comes out. When I have a commitment that I know I have to meet, Resistance doesn’t have the time or space to creep in. Right now I am on a book year path for the next four years. It keeps me honest and keeps me working. Meet deadline, or death.
|
||||
|
||||
**\[5\] Work with great people**
|
||||
|
||||
Success requires greater investment in the creative process. Pay for professional help. There’s that saying: if you think pros are expensive, try hiring an amateur.
|
||||
|
||||
**\[6\] Have something to say**
|
||||
|
||||
“To have something to say,” Schopenhauer said, “by itself is virtually a sufficient condition for good style.”
|
||||
|
||||
**\[7\] Have a model in mind**
|
||||
|
||||
Thucydides had Herodotus. Gibbon had Thucydides. Shelby Foote had Gibbon. Every playwright since Shakespeare has had Shakespeare. Everyone has a master to learn from. For me, it’s been Robert Greene
|
||||
|
||||
**\[8\] Know where you’re going**
|
||||
|
||||
You don’t “find the book as you write.” You have to do the hard work of solving the problem first. You have to figure out the best route, too. One of the best pieces of writing advice I ever got was to–before I started the process–articulate the idea in one sentence, one paragraph and one page. This crystallizes the idea for you and guides you—Nassim Taleb wrote in [Antifragile](https://www.thepaintedporch.com/products/selfhelp3?_pos=1&_sid=e9558a5cb&_ss=r) that every sentence in the book was a “derivation, an application or an interpretation of the short maxim” he opened with.
|
||||
|
||||
**\[9\] Focus on What You Control**
|
||||
|
||||
As Epictetus says, there’s some stuff that’s up to us, some stuff that’s not. The work is up to you. Everything else is not. If you’re in this for external rewards, god help you. [A Confederacy of Dunces](https://www.thepaintedporch.com/products/confederacy-of-dunces-anniversary?_pos=1&_sid=cdbc4ba8b&_ss=r) was rejected by publishers. After the author’s suicide, it won the Pulitzer. People don’t know shit. YOU know. So love it while you’re doing it. Success can only be extra.
|
||||
|
||||
**\[10\] Embrace draw-down periods**
|
||||
|
||||
You need what the strategist and theorist [John Boyd](https://www.thepaintedporch.com/products/war4?_pos=1&_sid=2cfb11897&_ss=r) called the “draw-down period.” Take a break right before you start. To think, to reflect, to let things settle. I started [Courage is Calling](https://store.dailystoic.com/pages/courage) on my birthday, but not before I took an extended period of just thinking.
|
||||
|
||||
**\[11\] Listen to the same song on repeat**
|
||||
|
||||
I’ve found that picking one song—usually something I am not proud to say I am listening to—and listening to it on repeat, over and over and over again is the best way to get into a rhythm and flow. It not only shuts out outside noise but also parts of my conscious mind I don’t need to hear from while I’m writing.
|
||||
|
||||
**\[12\] Make little progress each day**
|
||||
|
||||
One of the best rules I’ve heard as a writer is that the way to write a book is by producing “two crappy pages a day.” It’s by carving out a small win each and every day—getting words on the page—that [a book is created](https://medium.com/the-mission/here-with-2-years-of-exhausting-photographic-detail-is-how-to-write-a-book-fda1a6b40802). Hemingway once said that “the first draft of anything is shit,” and he’s right ([I actually have that on my wall as a reminder](https://prints.dailystoic.com/products/the-first-draft-of-anything-is-shit-print)).
|
||||
|
||||
**\[13\] Don’t let the tools distract you**
|
||||
|
||||
Great artists work. Mediocre artists talk a lot about tools. Software does not make you a better writer. If classics were created with quill and ink, you’ll probably be fine with a Word Document. Or a blank piece of paper. Don’t let technology distract you. Helen Simpson has “Faire et se taire” from Flaubert on a Post-it near her desk, which she translates as “Shut up and get on with it.”
|
||||
|
||||
**\[14\] Get some strenuous exercise every day**
|
||||
|
||||
I can’t tell you how many times I’ve thought of a great line or solved an intractable writing problem while running or swimming. Exercise is also an easy win every day. Writing can go poorly, but going on a run always goes well.
|
||||
|
||||
**\[15\] Write about the things you’re afraid to talk about.**
|
||||
|
||||
James Altucher has a great rule that I have stolen: write what you’re afraid to say. If your stuff isn’t scaring you, you’re not pushing yourself enough.
|
||||
|
||||
**\[16\] Journal every morning**
|
||||
|
||||
Each morning, [I journal in three small notebooks](https://ryanholiday.net/the-most-important-thing-you-can-do-each-morning/). The whole ritual takes 15 minutes and by the time I am finished, I am centered, I am calm and most importantly, I am primed to do my actual writing.
|
||||
|
||||
**\[17\] Don’t talk about the book (as much as you can help it)**
|
||||
|
||||
Don’t talk about projects until you’re finished. Save that carrot for the end. Talking and doing fight for the same resources.
|
||||
|
||||
**\[18\] Stop on the “wet edge”**
|
||||
|
||||
Hemingway advised fellow writer Thomas Wolfe “to break off work when you ‘are going good.’—Then you can rest easily and on the next day easily resume.” Brian Koppelman has referred to this as stopping on “wet edge.” It staves off the despair the next day.
|
||||
|
||||
**\[19\] Make something that does a job**
|
||||
|
||||
My editor Niki Papadopoulos once told me, “It’s not what a book is. It’s what a book does.” This is why musicians follow the “car test” (how does the song sound in a car driving down the highway). It’s just about whether you like it…but about what it does for the people buying it.
|
||||
|
||||
**\[20\] Cut out the jargon**
|
||||
|
||||
This was Ogilvy’s rule: “Never use jargon words like reconceptualize, demassification, attitudinally, judgmentally. They are hallmarks of a pretentious ass.” The other one I like is: “Never use two words where one will do.”
|
||||
|
||||
**\[21\] Talk it out**
|
||||
|
||||
When you get stuck, talk the ideas through with someone you trust. As Seth Godin observed, “no one ever gets talker’s block.”
|
||||
|
||||
**\[22\] It’s OK that it’s hard**
|
||||
|
||||
Thomas Mann described a writer as “someone to whom writing does not come easy,” he was putting it lightly. Walker Percy said “that writing is like suffering from a terrible disease for a certain period of time. Then when you finish you get well again.” That’s why there is the old saying: Painters like painting. Writers like having written.
|
||||
|
||||
**\[23\] Remember … it’s all material**
|
||||
|
||||
As [Vivian Gornick](https://geni.us/fAD1O) explains, “What happened to the writer is not what matters; what matters is the large sense that the writer is able to make of what happened.”
|
||||
|
||||
If all you do after reading this is start asking more often, “How can I use this to my advantage?”—your creative output will not only get better, your life will too.
|
||||
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: "Turn Your Hermes Agent Into an OpenRouter Expert"
|
||||
source: "https://x.com/OpenRouter/status/2047506176447783155"
|
||||
author:
|
||||
- "[[@OpenRouter]]"
|
||||
published: 2026-04-24
|
||||
created: 2026-04-24
|
||||
description: "If you use Hermes as your coding agent, connecting it to OpenRouter gives you a setup that improves over time rather than starting fresh eve..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
If you use [Hermes](https://hermes-agent.nousresearch.com/) as your coding agent, connecting it to OpenRouter gives you a setup that improves over time rather than starting fresh every session. This guide walks you through the setup and teaches Hermes to be an OpenRouter expert.
|
||||
|
||||
# Why Hermes + OpenRouter
|
||||
|
||||
Hermes is a provider-agnostic agent framework with built-in memory, tool use, and a self-improving skills system. It learns how you work and gets better the more you use it. OpenRouter gives you access to hundreds of models across major providers through a single API with unified billing, automatic failover, and intelligent routing.
|
||||
|
||||
Together you have a powerful coding agent that does not depend on any one provider and gets smarter the more you use it.
|
||||
|
||||
The skill we'll create to teach Hermes how to build with OpenRouter also covers the OpenRouter [Agent SDK](https://openrouter.ai/docs/sdks/typescript/call-model/overview) (\`[@openrouter/agent](https://x.com/@openrouter/agent)\`), the TypeScript toolkit for building agents on OpenRouter. Its \`callModel\` primitive handles multi-turn tool calling, stop conditions, streaming, state, and tool approval patterns, so you can focus on what your agent does instead of wiring the loop yourself.
|
||||
|
||||
Let's get them set up.
|
||||
|
||||
# Prerequisites
|
||||
|
||||
- An OpenRouter account and API key ([openrouter.ai](https://openrouter.ai/))
|
||||
- Python installed on your machine
|
||||
- A terminal you are comfortable working in
|
||||
|
||||
# Step 1: Install Hermes
|
||||
|
||||
Follow the [Hermes Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) to get it installed.
|
||||
|
||||
Then run \`hermes setup\` to configure your provider, API key, and model. Select OpenRouter as your provider and paste in your API key.
|
||||
|
||||
If you already have Hermes set up, run \`hermes model\` to switch to OpenRouter.
|
||||
|
||||
If the model you want is not in the predefined list, visit [openrouter.ai/models](https://openrouter.ai/models), click the model you want, and copy the exact model slug from the model page, not the display name. Add that slug as a custom model in Hermes.
|
||||
|
||||
# Step 2: Teach Hermes to be an OpenRouter expert
|
||||
|
||||
We're going to have Hermes build its own OpenRouter skill, leaning on referencing the docs. This way Hermes is always nudged toward looking at the current OpenRouter docs when building. The goal is to give it the principles it needs to build with OpenRouter directly within the new skill with references to docs links for specific implementation details.
|
||||
|
||||
Our docs index lives at [https://openrouter.ai/docs/llms.txt](https://openrouter.ai/docs/llms.txt). It is built for LLM consumption; a structured list of every docs page with descriptions. Hermes can read this once and create a skill that routes to the right docs for any OpenRouter task.
|
||||
|
||||
## The prompt
|
||||
|
||||
Paste [this prompt](https://gist.github.com/ping-Toven/2671af1cbcf1ffb1c03c311473ae683f) into Hermes:
|
||||
|
||||

|
||||
|
||||
The [prompt](https://gist.github.com/ping-Toven/2671af1cbcf1ffb1c03c311473ae683f) will have Hermes create a reusable openrouter-expert skill. Hermes will read the current OpenRouter docs index, check the supporting skill-creation guidance, and build a compact resolver skill that knows when to look up the right OpenRouter docs, when to fetch the models API, and how to choose between the OpenRouter API, SDKs, framework integrations, and the Agent SDK.
|
||||
|
||||
The skill is designed to keep Hermes from guessing about fast-changing details like model IDs, pricing, capabilities, SDK behavior, or docs URLs. Instead, it gives Hermes decision frameworks, routing tables, gotchas, and verification steps so future OpenRouter coding sessions start with the right current context. Hermes will read the docs index, check the supporting sources, and create the skill.
|
||||
|
||||
When it finishes, read the skill file at \`~/.hermes/profiles/<your-profile>/skills/<category>/openrouter-expert/SKILL.md\` and adjust anything that does not match your workflow. You can find the actual category with \`hermes skills list\` or by checking \`~/.hermes/profiles/<your-profile>/skills/\`. It does not need to be perfect, Hermes will refine it as you build.
|
||||
|
||||
## Smoke test the skill
|
||||
|
||||
Start a fresh Hermes session and try this:
|
||||
|
||||
> I want to build a small app that compares model latency and cost across providers. What should I use?
|
||||
|
||||
A good result should load the OpenRouter skill, check the docs index, avoid hardcoding model IDs, recommend a sensible SDK or API path, and point to relevant docs.
|
||||
|
||||
If Hermes gives a generic answer without checking docs, ask it to inspect the \`openrouter-expert\` skill it just created and strengthen the trigger description.
|
||||
|
||||
# What you get
|
||||
|
||||
After running the prompt you will have:
|
||||
|
||||
- Hermes connected to OpenRouter with your preferred model
|
||||
- A skill that routes OpenRouter questions to the right docs
|
||||
- Knowledge of the OpenRouter Agent SDK baked into the skill
|
||||
|
||||
Your Hermes agent is now an expert at building with OpenRouter. Time to go build!
|
||||
|
||||
For example, if you want to make something to help you keep up with what is happening in your state legislature, try this prompt and see what Hermes builds:
|
||||
|
||||
> Use OpenRouter to build a small agentic app that helps me track what is happening in my state legislature. It should fetch recent bills, summarize important changes, and let me ask follow-up questions.
|
||||
File diff suppressed because it is too large
Load Diff
+66
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: "Why High-Level Rust Wins Over Other High-Level Languages for Agentic Engineering"
|
||||
source: "https://hamy.xyz/blog/2026-04_why-rust-over-high-level-langs"
|
||||
author:
|
||||
published:
|
||||
created: 2026-04-24
|
||||
description:
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||
Essay - Published: 2026.04.22 | 5 min read (1,260 words)
|
||||
[artificial-intelligence](https://hamy.xyz/tags/artificial-intelligence) | [create](https://hamy.xyz/tags/create) | [rust](https://hamy.xyz/tags/rust)
|
||||
|
||||
DISCLOSURE: If you buy through affiliate links, I may earn a small commission. [(disclosures)](https://hamy.xyz/blog/disclosures)
|
||||
|
||||
For the past couple months I've been writing [High-Level Rust](https://hamy.xyz/blog/2026-01_high-level-rust) which gives ~80% of its benefits with ~20% of its pain.
|
||||
|
||||
One of the biggest pieces of feedback I've gotten is why not just use a high-level language that does this already? Think Go, C#, TypeScript, OCaml, etc.
|
||||
|
||||
Here's why I think, in the current model and language landscape, Rust is still the best choice.
|
||||
|
||||

|
||||
|
||||
## Why Rust
|
||||
|
||||
- **[Expressive types](https://hamy.xyz/blog/2026-01_missing-programming-language) + compiler hints** - [types scale](https://hamy.xyz/blog/2024-09_types-vs-no-types) logic to larger orgs and apps. I saw this transition first-hand at MasterCard, Facebook + Instagram, Rippling, and now Vanta. Expressive types allow you to precisely model the domain, making invalid states unrepresentable and removing whole classes of bugs. Rust's compiler goes further with ownership and lifetimes protecting against additional classes of bugs in data races and corruption - a category of protection no other mainstream high-level language offers. This puts Rust ahead of OO / simpler langs like Go, C# (until native unions drop), and Python.
|
||||
- **Mainstream long-term** - Rust is now a default choice at the infrastructure layer. It's used in the Linux kernel, Android, AWS core, and Cloudflare edge. Rust proved itself at the infra layer and is now moving up the stack with more webapps and games built in it (I'm building [CloudSeed Rust](https://hamy.xyz/blog/2026-02_launching-cloudseed-rust) to make webapps easier and macroquad has been super easy to work with for wasm targets). Rust has been the most admired language on Stack Overflow for 10 consecutive years with ~15% usage and ~20% YoY growth. The community continues to grow and these usages cement its longevity with support from large enterprises. This puts Rust ahead of the best FP langs that have expressive type + community support but not wide adoption - F#, OCaml, Haskell, Scala.
|
||||
- **AI proficiency** - can one and few shot large features. In [Why Rust Wins in the Age of AI](https://hamy.xyz/blog/2026-04_rust-age-of-ai), I cited benchmarks showing Rust winning not at speed or cost of AI generation but at real-world task completion - SWE-bench Multilingual showed Rust completing 58.14% of tasks, the best of 9 languages. Training data volume [explains ~40-50%](https://arxiv.org/abs/2305.06161) of cross-language AI performance variance and Rust's large, growing community means it has plenty. The large amount of training data combined with great types + compiler hints gives agents a tight feedback loop that leans into a pit of success. This puts Rust ahead of those same FP langs - F#, OCaml, Haskell, Scala - AI can write them but not very effectively, reliably, or idiomatically.
|
||||
- **Great performance** - [High-Level Rust](https://hamy.xyz/blog/2026-01_high-level-rust) with liberal cloning takes a 10-30% perf hit but is still competitive with optimized Go and C#. With hot path optimization - switching clones to references and mutations - it often pulls ahead significantly. This puts Rust ahead of even fast high level langs like Go, C#, and Java and far ahead of simpler langs like Python, Ruby, and TypeScript.
|
||||
|
||||
Rust has historically gotten a bad rap for being too low level with [steep learning curves](https://hamy.xyz/blog/2026-02_moving-csharp-to-rust) and ongoing hits to developer velocity. But with AI agents doing most of the coding, you can now choose basically any language and minimize onboarding and velocity issues.
|
||||
|
||||
So why not Rust?
|
||||
|
||||
## Common Objections
|
||||
|
||||
- **"Just use Go"** - Go is often perceived as the closest competitor with great perf, a big ecosystem, and lots of AI training data. But Go's type system can't make invalid states unrepresentable - it has no sum types or exhaustive matching and has no plans to add it. You get fast code that compiles but still lets entire categories of logic bugs through. Rust's expressive types [close that gap](https://hamy.xyz/blog/2026-01_missing-programming-language).
|
||||
- **"Just use TypeScript"** - Biggest ecosystem, most AI training data. But TS types are lies - they don't enforce at runtime (as evidenced by the prevalence of Zod), the ecosystem is in constant thrash, and the perf ceiling is low (not terrible, pretty good actually, but not great). TypeScript is a great language for high level apps but is less great for systems you want to be correct and function long-term - at least without constant maintenance.
|
||||
- **"Just use OCaml / F# / Gleam / Haskell / Roc / Lisette / Scala"** - These have great type systems, some arguably better than Rust's. But [AI is bad at them](https://hamy.xyz/blog/2025-11_why-im-moving-blog-fsharp-to-csharp) - FPEval (2026) found LLMs produce non-idiomatic imperative code even in functional langs. Training data volume [explains ~40-50%](https://arxiv.org/abs/2305.06161) of cross-language AI perf variance and these langs have a fraction of Rust's. Agents can help but they can't reliably finish full features autonomously in these languages, at least not yet. And it's unclear if this gap will shift - maybe with reasoning models to make up for the lack of data or maybe AI is bad at it and fewer people use it, leading to [the programming language death spiral](https://hamy.xyz/blog/2025-12_programming-language-death-spiral).
|
||||
- **"If AI removes language barriers, why not pick the easiest language?"** - AI removes the floor but Rust's compiler raises the ceiling. Agents + Rust = fast AND correct. Agents + Python = fast but fragile. You're trading some agent speed for a lot of agent reliability which I think is a good tradeoff - move fast with stable infrastructure. If agents are going to code it anyway, I think the question should be why not pick the most performant / reliable language?
|
||||
- **"Rust's web ecosystem is immature"** - Fair. Axum and actix are solid but young vs TS/JS's Express, dotnet's ASP.NET, or Go's stdlib. The ORM story is also weaker. This is a real trade-off but the ecosystem is growing fast and for most web apps the framework does only 20% of the work and your domain logic does 80% - that's where Rust's types shine. And as we've seen, AI is good at Rust so as long as the web ecosystem is good enough (it is) there's really no barriers to using it.
|
||||
- **"Good luck hiring Rust developers"** - Also fair, for now. But if AI agents are doing most of the coding, you need fewer deep Rust experts and more people who can direct agents and review output. Agents give matrix-like powers - I don't know this thing but I want to do it anyway. And you can, agents supercharge JIT learning and an agent trained on mainstream practices gets you average outputs at the outset. In many ways agents are raising the layer of abstraction to a point where the programming language is an implementation detail - you can focus on the system and its goals.
|
||||
- **"This could all change"** - Totally. Models could get way better at niche languages, removing Rust's training data advantage. Languages could evolve to add new compiler-level checks like ownership and lifetimes - or entirely new constraints we haven't thought of - with simpler syntax. We may even get AI-native languages that are just far more effective than human-native ones. Those could leapfrog Rust, in which case I'm happy to reconsider.
|
||||
|
||||
## Next
|
||||
|
||||
Rust gives you expressive types, compiler-enforced correctness, mainstream longevity, strong AI proficiency, and great performance. AI agents remove the historical learning curve barrier, making Rust's ceiling benefits accessible without the floor costs.
|
||||
|
||||
So, for now, I'm choosing Rust.
|
||||
|
||||
If you liked this post you might also like:
|
||||
|
||||
- [Why Rust Wins in the Age of AI](https://hamy.xyz/blog/2026-04_rust-age-of-ai)
|
||||
- [High-Level Rust: Getting 80% of the Benefits with 20% of the Pain](https://hamy.xyz/blog/2026-01_high-level-rust)
|
||||
- [The Missing Programming Language - Why There's No S-Tier Language (Yet)](https://hamy.xyz/blog/2026-01_missing-programming-language)
|
||||
|
||||
#### Outbound Links
|
||||
|
||||
- [High-Level Rust: Getting 80% of the Benefits with 20% of the Pain](https://hamy.xyz/blog/2026-01_high-level-rust)
|
||||
- [The Missing Programming Language - Why There's No S-Tier Language (Yet)](https://hamy.xyz/blog/2026-01_missing-programming-language)
|
||||
- [Types vs No Types - How Types Allow Code to Scale across Developers, Organizations, and Lines of Code](https://hamy.xyz/blog/2024-09_types-vs-no-types)
|
||||
- [CloudSeed Rust - A Fullstack Rust Boilerplate for Building Webapps in Minutes](https://hamy.xyz/blog/2026-02_launching-cloudseed-rust)
|
||||
- [Why Rust Wins in the Age of AI](https://hamy.xyz/blog/2026-04_rust-age-of-ai)
|
||||
- [Why I'm moving from C# to Rust for High-level Apps](https://hamy.xyz/blog/2026-02_moving-csharp-to-rust)
|
||||
- [Why I'm Moving my Blog from F# to C#](https://hamy.xyz/blog/2025-11_why-im-moving-blog-fsharp-to-csharp)
|
||||
- [The Programming Language Death Spiral - How Small Languages Die in the Age of AI](https://hamy.xyz/blog/2025-12_programming-language-death-spiral)
|
||||
@@ -0,0 +1,398 @@
|
||||
---
|
||||
title: "Why Less Motivation Leads To More Success"
|
||||
source: "https://x.com/RianSweetDoris/status/2047731767881224607"
|
||||
author:
|
||||
- "[[@RianSweetDoris]]"
|
||||
published: 2026-04-25
|
||||
created: 2026-04-26
|
||||
description: "If you think the more motivation you have, the better, be careful what you wish for. I've watched brilliant entrepreneurs destroy million-do..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
If you think the more motivation you have, the better, be careful what you wish for.
|
||||
|
||||
I've watched brilliant entrepreneurs destroy million-dollar companies because they couldn't handle their own drive. The most driven people I know didn't fail from laziness. They failed from too much drive. While amateurs chase motivation, top performers master something else entirely.
|
||||
|
||||
Over the next few minutes, you'll learn the counterintuitive science of how to harness extreme motivation without letting it destroy you.
|
||||
|
||||
# I. MY SPENDING SPREE
|
||||
|
||||
A few years ago, in my mid-twenties, I was riding high on momentum.
|
||||
|
||||
Alarm goes off at 5 AM, my eyes snapped open, mind already racing. I stumbled downstairs, poured my first cup of coffee, and cracked open my laptop, ideas bursting out of my brain that I had to write down.
|
||||
|
||||
By sunrise, I was two coffees deep, firing off messages to my team with a kind of frenzied certainty. New product launches, team expansions, partnerships. I felt like I was winning at blistering speed — sprinting from one thing to the next.
|
||||
|
||||
I could feel my system was in overdrive. I convinced myself I was unstoppable.
|
||||
|
||||

|
||||
|
||||
Then it started to become too much. Recklessness followed.
|
||||
|
||||
In a matter of weeks, I acquired a company on impulse. No real plan, just raw excitement and extreme conviction in myself.
|
||||
|
||||
I enrolled in a PhD program because it felt like the next power move.
|
||||
|
||||
Dropped six figures on a domain name that "made sense" in the moment.
|
||||
|
||||

|
||||
|
||||
I converted my spare room into a [$60K](https://x.com/search?q=%2460K&src=cashtag_click) podcast studio.
|
||||
|
||||
Hosted 400-person parties in a house that wasn't zoned for crowds.
|
||||
|
||||
I launched a year-long mastermind program.
|
||||
|
||||
Hired AI engineers after binge-reading a few articles on machine learning.
|
||||
|
||||
I even installed a [$40K](https://x.com/search?q=%2440K&src=cashtag_click) hyperbaric oxygen chamber in my home office because... well, why not?
|
||||
|
||||
The tipping point came when I convinced my team we should split the company into two separate operations. Bad move.
|
||||
|
||||
And then the cracks started showing.
|
||||
|
||||
People started quitting. Deadlines were missed. Results declined. Brilliant ideas started turning into expensive misfires everywhere I looked.
|
||||
|
||||
What felt like increasingly unstoppable momentum was actually the early signs of spiraling toward collapse.
|
||||
|
||||
Follow [@RianSweetDoris](https://x.com/@RianSweetDoris) for more content like this.
|
||||
|
||||
# II. THE PARADOX OF DRIVE
|
||||
|
||||
Here's the paradox: the force pushing you to new heights can send you crashing down. Hard. If mismanaged.
|
||||
|
||||
At a certain point, the dopamine from high-volume achievement becomes dangerous, like driving a turbo car before learning to steer.
|
||||
|
||||
Building momentum is tough. But once you're rolling, with flow state on tap and wins piling up, confidence soars and goals multiply. Usually, this is good.
|
||||
|
||||
But as Steven Kotler, my co-founder at Flow Research Collective, put it:
|
||||
|
||||
> "Flow makes you feel invincible, right up to the moment you're not."
|
||||
|
||||
The rush from the seemingly perfect decisions made in flow becomes your enemy. Like Icarus, you fly higher, blind to your melting wings.
|
||||
|
||||

|
||||
|
||||
I know. I lived it. And it's something that happens when you reach a certain extreme level of performance.
|
||||
|
||||
The question is: what is this force underpinning peak performance that determines if you'll succeed wildly or burn up badly? What drives the Icarus Effect?
|
||||
|
||||
# III. THE SYNDROME NOBODY TALKS ABOUT
|
||||
|
||||
There's a syndrome that plagues amateurs.
|
||||
|
||||
It's when motivation devolves into cynicism, self-confidence dies, and energy evaporates. It's called burnout.
|
||||
|
||||
**But there exists a less spoken of, yet equally formidable cousin of this syndrome.**
|
||||
|
||||
If burnout is the slow extinguishing of your flame, imagine now its opposite: not a dimming, but an inferno raging out of control.
|
||||
|
||||
Here, cynicism is replaced with a kind of optimism so intense it borders on delusion. Self-efficacy doesn't just grow but balloons into grandiosity. And rather than emotional exhaustion, you experience indefatigable, wild-horse-level, erratic energy.
|
||||
|
||||

|
||||
|
||||
**Rather than burning out, think of this as burning up.**
|
||||
|
||||

|
||||
|
||||
This syndrome is experienced not by amateurs but by those pushing the very limits of human potential. It's underpinned by a DSM-5 validated psychological condition. And paradoxically, this condition is one of the dark sides of flow.
|
||||
|
||||
**This condition is known as HYPOMANIA.**
|
||||
|
||||
Characterized by a racing mood, decreased need for sleep, an insatiable appetite for work and risk-taking, and a remarkable capacity for creative thought.
|
||||
|
||||
Unlike its more severe counterpart, mania, hypomania doesn't tip its bearers into the realms of delusion or incapacitation.
|
||||
|
||||
Instead, it endows them with a razor-sharp focus and an almost superhuman ability to execute. Ambition without brakes.
|
||||
|
||||

|
||||
|
||||
If you want to read more content like this, follow [@RianSweetDoris](https://x.com/@RianSweetDoris) on X.
|
||||
|
||||
## The History of Hypomania
|
||||
|
||||
Hypomania was first explored in the late 19th century.
|
||||
|
||||
Psychiatrists noticed a pattern: some patients exhibited elevated mood, energy, and productivity that fell between normalcy and full-blown mania.
|
||||
|
||||
These patients, while showing manic symptoms, remained functional and often excelled. The term "hypomania," meaning "less than mania," was coined to describe this condition.
|
||||
|
||||
The hypomania-achievement link was further explored in the 1970s when psychologist Arnold Ludwig found that hypomanic traits were overrepresented among eminent figures in politics, arts, and other fields.
|
||||
|
||||
The idea of hypomania as a success catalyst gained traction with John Gartner's 2005 book The Hypomanic Edge. Gartner argued that hypomania shaped America's entrepreneurial spirit. His theory went deeper than mindset — it suggested a genetic filter.
|
||||
|
||||

|
||||
|
||||
Who leaves everything behind to sail across an ocean toward complete uncertainty? According to Gartner: people with hypomanic traits.
|
||||
|
||||
The audacity required to make that leap **selected** for individuals with higher genetic predispositions to mania.
|
||||
|
||||
The proposed mechanism: the DRD4-7R gene variant — a "long" version of the dopamine D4 receptor gene associated with novelty-seeking, risk tolerance, and impulsivity. This variant shows significantly higher prevalence in populations with migration histories, particularly in the Americas. The hypothesis is that migration itself acted as a filter, concentrating these alleles in populations willing to take existential risks.
|
||||
|
||||
Over generations, this self-selected population passed down those traits, creating a culture neurochemically wired for innovation, bold action, and relentless forward motion.
|
||||
|
||||
## The Neuroscience of Hypomania
|
||||
|
||||
Neuroimaging studies have found that hypomania involves hyperactivity in the prefrontal cortex (the brain's decision-making hub), increased reactivity in the amygdala (which regulates emotion), and altered functioning in the hippocampus (which affects memory and learning).
|
||||
|
||||
On a neurotransmitter level, hypomania is marked by heightened dopamine activity (fueling motivation and reward-seeking behavior), increased norepinephrine levels (driving energy and alertness), and dysregulated serotonin (affecting mood stability). This biochemical cocktail is what gives hypomania its intoxicating blend of energy, confidence, and creativity.
|
||||
|
||||

|
||||
|
||||
But hypomania has its downsides. The hypomanic edge can tip into impulsivity, irritability, and reality distortion.
|
||||
|
||||
Grandiose visions can become reckless risks, causing you to fly too close to the sun and burn up. What fuels your rise can also burn you to the ground. Like it did when I was burning up, starting multiple businesses, a PhD, and making wild investments on hypomanic impulse.
|
||||
|
||||
Unaddressed burnout leaves you with no gas to drive. Unchecked hypomania will crash the car.
|
||||
|
||||
Amateurs need to learn how to accelerate. High-performers need to learn how to decelerate and sustain optimal speed.
|
||||
|
||||

|
||||
|
||||
# IV. HYPOMANIA IN THE WILD
|
||||
|
||||
Now, you might be thinking, "Hypomania doesn't apply to me."
|
||||
|
||||
But I'm sure you've seen it before. Let me show you what hypomania looks like in the wild. Because once you know the signs, you'll spot it everywhere — likely even in yourself.
|
||||
|
||||
## The Urgent Call
|
||||
|
||||
I was once at my parents' house in Dublin when my phone lit up.
|
||||
|
||||
James's message burned across the screen:
|
||||
|
||||
> **"IT'S URGENT. CALL ME."**
|
||||
|
||||
I pushed back from the table, muttered an apology, and stepped onto the back patio.
|
||||
|
||||
James picked up on the first ring. His words tumbled out at double speed. "I can see it. We're going to start a business that transforms the education space. You'll bring the IP, I'll bring the experience, and we'll hire an operator to handle the logistics. Done deal."
|
||||
|
||||
He'd already registered domain names and drafted partnership agreements.
|
||||
|
||||
You've probably seen it too. Maybe it was someone cornering you at a networking event, talking at you rather than to you. Their eyes wide, words spilling out faster than thoughts, more interested in hearing themselves speak than having a conversation.
|
||||
|
||||
Or like my other friend, who, in the grip of hypomania, became convinced that modern marketing was morally corrupt and tanked his businesses, causing his team to lose their jobs. Amidst this, he once said to me:
|
||||
|
||||
> "Socrates, Plato, and Jesus Christ would never market or sell like this. So why should I?"
|
||||
|
||||
He torched his seven-figure business based on a philosophical revelation that had struck him between his fourth and fifth espresso.
|
||||
|
||||
These are the red flags of hypomania. And if you're on the path to peak performance, you need to learn how to recognize them in yourself before they take over.
|
||||
|
||||
# V. THE FLOW-HYPOMANIA CONNECTION
|
||||
|
||||
As you gain momentum, start winning more, and stack achievements, you run the risk of experiencing hypomania. Your motivation will amplify. Your ability to move fast, execute, and create will feel unstoppable.
|
||||
|
||||
This isn't a rare glitch, but rather a default challenge on the path to high performance. If you don't learn how to navigate it, it's not a question of if it will sabotage you, but when.
|
||||
|
||||
**The same neurochemical processes fueling hypomania also fuel flow.**
|
||||
|
||||
Flow states are characterized by a balance of neurotransmitters such as dopamine, which enhances focus and motivation. However, an excess of dopamine, which can occur during prolonged periods of flow without proper regulation, may contribute to hypomanic behavior.
|
||||
|
||||
Research shows that dopamine excess distorts risk perception, inflates confidence beyond reason, and disrupts executive control in the prefrontal cortex. All hallmarks of hypomanic decision-making.
|
||||
|
||||
**This is flow's dark side. The price for euphoric productivity highs.**
|
||||
|
||||
As you ride the high of flow, reveling in unmatched focus and creativity, hypomania awaits if you're not careful.
|
||||
|
||||
So, as you push your performance to new heights, to sustain your progress without burning up, you need tools to recognize and manage it before it derails what you've built.
|
||||
|
||||
(Important note: this isn't a medical diagnosis. If you're experiencing extreme mood fluctuations or symptoms that disrupt your life, seek professional guidance.)
|
||||
|
||||
So how do we harness flow's power without tilting into hypomania and burning up?
|
||||
|
||||
# VI. STOP, DROP, AND ROLL
|
||||
|
||||
If you're in or on the brink of a hypomanic state, there's a simple solution. It's something you may have learned in elementary school:
|
||||
|
||||
Stop, drop, and roll.
|
||||
|
||||
Just like the fire safety technique we learn as children, this plan is designed to minimize damage when the flames of hypomania start to rage out of control.
|
||||
|
||||

|
||||
|
||||
## STEP 1: STOP
|
||||
|
||||
The first step is to stop.
|
||||
|
||||
When I was in a hypomanic state, I was like a rocket ship hurtling through space, fueled by pure ambition and drive, but with no real direction or control.
|
||||
|
||||
That's when my friend Liam called. He'd been watching from the sidelines, seeing what I couldn't see. "Rian," he said, his voice gentle but firm, "you need to take a week off. Now."
|
||||
|
||||
A week off felt impossible. Even irresponsible with all this momentum. But Liam insisted: "You're burning up. Without a break, you'll crash and burn."
|
||||
|
||||
So I did something unprecedented. I took an emergency week off. Texted everyone. Dropped work completely.
|
||||
|
||||
When my business partner reached out the next day, my body told me everything I needed to know. I felt physically ill, almost tweaking out after all that stimulation.
|
||||
|
||||
That week became my lifeline. My brother and I hiked through Malibu, letting nature's quiet soothe my frayed nerves. Daily saunas. Ice baths. No caffeine, no stimulants, nothing artificial revving up an already overcharged system.
|
||||
|
||||
What I was doing was counteracting the effects of hypomania by increasing interoception and embodiment, which some call being "grounded." As this happened, the cognitive activity quieted down, and awareness shifted throughout the rest of the nervous system, diffusing the excess hypomanic energy.
|
||||
|
||||
After seven days, the erratic energy and flighty thoughts faded, replaced by a clarity I hadn't felt in months.
|
||||
|
||||

|
||||
|
||||
Think of hypomanic energy like a high-performance sports car. The difference between an amateur and a professional? The amateur pushes the pedal to the floor until they spin out. The professional knows exactly how far they can push it, keeping control while maintaining maximum speed.
|
||||
|
||||
Stop, drop, and roll is your brake so you can maintain control.
|
||||
|
||||
For the free 30-day email sequence on how to access flow state without burning up, sign up at the link in my bio. [@RianSweetDoris](https://x.com/@RianSweetDoris)
|
||||
|
||||
## STEP 2: DROP
|
||||
|
||||
So here's how to drop:
|
||||
|
||||
Ditch the stimulants. Caffeine, energy drinks, anything that artificially revs you up needs to go. Your system is already in overdrive.
|
||||
|
||||
Dial down the stimulation. Step away from screens, notifications, and anything that ramps up your senses.
|
||||
|
||||
Hit pause on work. Yes, even if you're crushing it. When hypomania fuels success, it's tempting to run with it, but that's the path to burning up.
|
||||
|
||||
Activate your parasympathetic nervous system. This is your body's "rest and digest" mode. Sauna, cold plunge, and massage are all powerful tools to kickstart relaxation.
|
||||
|
||||
Move your body. Think of it as tiring out an overexcited puppy. Steady-state cardio and a mix of low and high-intensity workouts will help release that pent-up energy healthily. Fatigue your system so you can sleep more.
|
||||
|
||||
Get into nature. Expose yourself to nature to make yourself feel smaller and remind you of what matters. Even better is to do this with loved ones, like I did with my brother.
|
||||
|
||||
Spend time with loved ones. Hypomania can lead to delusions of invincibility.
|
||||
|
||||
But loved ones, the ones who see our flaws and our baseline, crack that facade. Your intimate other knows your baseline so intimately that you can only veer so far off it. Loved ones ground inflated egos.
|
||||
|
||||
Drop the long-term decisions. This includes hitting pause on strategic business decisions.
|
||||
|
||||
Hypomania can make every idea feel like a matter of life and death. This is dopamine flooding your salience network — the system that tags what matters — while norepinephrine keeps you locked in "act now" mode. Without sufficient prefrontal regulation to provide perspective, the brain loses its ability to distinguish genuine priorities from noise.
|
||||
|
||||
**In reality, most decisions can wait.**
|
||||
|
||||
Think of hypomania as a fire raging inside your mind. Just as you wouldn't make major life decisions while your house is burning down, you shouldn't make long-term plans when your brain is on fire with hypomanic energy.
|
||||
|
||||
## STEP 3: ROLL
|
||||
|
||||
That brings us to the last step — roll.
|
||||
|
||||
And that is to roll with the hypomania.
|
||||
|
||||
Hypomania, when harnessed and directed, can be a lethal competitive advantage. Some of the most impressive feats of human achievement have been fueled by a touch of hypomania.
|
||||
|
||||
Many of my best windows of peak performance have happened on the edge of a hypomanic state. But it's this state, plus sustained singular focus, that burns through all obstacles, instead of burning up or burning out.
|
||||
|
||||
The way to roll with and harness that hypomanic energy is to build what I call a **Reality Reinforcement Field.**
|
||||
|
||||
# VII. THE REALITY REINFORCEMENT FIELD
|
||||
|
||||
When you're in a hypomanic state, your conviction and enthusiasm can be so intense that it creates a reality distortion field. You might be convinced (and able to convince others) to make major, life-altering decisions. You become so persuasive that even your most trusted advisors can get swept up in your grandiose plans, reinforcing your distorted thinking without realizing it.
|
||||
|
||||
And this is dangerous. Because the very people you need who can pull you out of your reality distortion field become persuaded, in all your enthusiasm, into your reality.
|
||||
|
||||
Steve Jobs was famous for this. His reality distortion field could drive Apple to greatness, but it could also backfire.
|
||||
|
||||

|
||||
|
||||
Consider the Apple Lisa. He envisioned a revolutionary computer years ahead of its time — a sleek interface, advanced software. But the technology wasn't ready, and his relentless demands pushed the team to the breaking point. The Lisa's $10,000 price tag (closer to [$30K](https://x.com/search?q=%2430K&src=cashtag_click) today) made it a luxury few could afford, and the machine itself was slow and unreliable. Sales were terrible. This failure damaged relationships within Apple and led to Jobs being removed from the project.
|
||||
|
||||
While a reality distortion field bends reality to match your vision, a Reality Reinforcement Field helps you see reality more clearly. Instead of amplifying your grandiose visions, it grounds them in what's genuinely achievable.
|
||||
|
||||
A Reality Reinforcement Field is a system of checks that keeps your ambitions tethered to your actual capabilities. It works by catching and correcting the cognitive distortions — inflated confidence, distorted urgency, blind spots — that pull your self-perception away from reality.
|
||||
|
||||
It's the difference between being the captain who steers straight into the storm because they believe they can conquer it, and the captain who respects the weather enough to plot a course around it.
|
||||
|
||||

|
||||
|
||||
THREE STEPS TO BUILD YOUR REALITY REINFORCEMENT FIELD:
|
||||
|
||||
## Step 1: Feed One Fire, Starve the Rest
|
||||
|
||||
Don't let the hypomanic energy spill over into new projects or tangential ideas. Instead of burning up, use it to burn through obstacles, to power through resistance, to achieve things that might seem impossible in a more "normal" state of mind.
|
||||
|
||||
The key to pulling this off is to compress the hypomania into increasingly focused concentric circles instead of letting it spiral outward into chaos.
|
||||
|
||||
Your neurobiological impulse will push you toward dispersion — widening your focus, adding complexity, stacking projects that pull you further from your main thing. But the highest performers do the opposite.
|
||||
|
||||
They take all that energy and drive it deeper, not wider.
|
||||
|
||||

|
||||
|
||||
Think about it like this:
|
||||
|
||||
Instead of, "I'm going to launch three different offers," you say, "I'm going to refine my main offer until it dominates."
|
||||
|
||||
Instead of, "I'll split my time between two businesses," you say, "I will make this one business so valuable that expansion is inevitable."
|
||||
|
||||
Instead of, "I'm going to explore five different strategies," you say, "I will execute this one strategy relentlessly, squeezing every drop of value from it before moving on."
|
||||
|
||||
Each layer of focus becomes a tighter, more powerful iteration of the last, compounding energy instead of diffusing it.
|
||||
|
||||
When you channel that hypomanic fire into your main mission with increasingly narrower circles of execution, that's when you achieve the kind of explosive, sustained success that most people only dream of.
|
||||
|
||||
This is how you burn through rather than burn up.
|
||||
|
||||
## Step 2: Use Data to Puncture Delusions
|
||||
|
||||
For me, this involved pausing my PhD completely, letting go of side ventures I had started, and directing all my energy into getting my core professional pursuit in a thriving place.
|
||||
|
||||
My specific, number-bound goal was to hit 30% year-over-year growth for my business with only one hour of my time per week. If I'd made that my only priority, I would have hit it easily and could then, from a place of success, move on to the next thing.
|
||||
|
||||
So I started tracking my progress objectively, using hard data to keep me on track. By what percentage were my company's profits growing? Before taking on a new project, did I have a team member ready to fully own my current responsibilities?
|
||||
|
||||
The key is to dial up objectivity to an even higher degree than normal to counteract the power of the overly persuasive subjectivity that dominates in hypomania.
|
||||
|
||||
**Numbers puncture delusions.**
|
||||
|
||||
Whenever I felt myself getting carried away with grand visions, I'd look at the numbers. If they didn't support my fantasies, I knew it was time to reel myself back in.
|
||||
|
||||
The fundamental rule here is to set milestones and assess them objectively to earn the right to disperse your energy. Prove to yourself, through consistent results, that you're ready for the next challenge. Until then, stay focused on your main thing.
|
||||
|
||||
## Step 3: Write It Down, Move It Aside
|
||||
|
||||
When a new idea strikes, have an impulsivity outlet.
|
||||
|
||||
Write the idea down. Whether it's a business idea, project, book, whatever it is, scope it out. Do the prep work, map out the requirements, but don't start building yet. Scratch the dopamine itch, then throw it to the side. You can always pick it back up later.
|
||||
|
||||
You're allowing yourself to explore new ideas without getting derailed from your main mission. You're investing the lowest possible cost (in terms of time, attention, energy, and money) relative to the dopamine hit of the new idea.
|
||||
|
||||
And here's the beauty of it: often, once you've scoped out a new idea and let it simmer, you'll find that it loses its luster. By not acting on it immediately, you've saved yourself from a potentially costly distraction.
|
||||
|
||||
But if, when you hit your milestone, you're still excited about the idea, then you know it's worth pursuing.
|
||||
|
||||
## The Complete System
|
||||
|
||||
So that's how you stop, drop, and roll.
|
||||
|
||||
Looking back, I can see how much energy I wasted on dispersed efforts during that hypomanic period. If I had channeled that energy into my core pursuit, into the projects and relationships that truly mattered, I can only imagine where I'd be today.
|
||||
|
||||
But here's the catch: as you do this, you can't let that hypomanic fire rage unchecked. If you start heating up too much again, you need to have the self-awareness and tools to stop and drop, so you can cool down and not blow up your Reality Reinforcement Field.
|
||||
|
||||
# VIII. THE HIDDEN TRAP
|
||||
|
||||
A final cautionary note: when hypomania is not properly channeled through the above mechanisms, it tends to look more like fierce procrastination and frenzy than real progress.
|
||||
|
||||
You get an exciting insight. That triggers a hit of dopamine. But then something dangerous happens. You immediately get a second insight about why your first insight is brilliant. Another dopamine hit. Suddenly, you realize how this idea solves ten other problems. Even more dopamine. Each thought triggers a cascade of feel-good chemicals that make every next idea feel like genius.
|
||||
|
||||
This is why you can spend hours in hypomanic planning sessions, convinced you're making massive progress, when you're actually just getting drunk on your own thoughts.
|
||||
|
||||
This is the insidious nature of hypomania.
|
||||
|
||||
# IX. THE REAL MEASURE
|
||||
|
||||
As the philosopher Friedrich Nietzsche famously said, "There are no actors, only actions." This cuts to the heart of one of the most seductive traps of hypomania: the illusion of specialness.
|
||||
|
||||
Our worth, our impact, our "specialness" — these things aren't inherent qualities that we're born with, or that descend upon us in a moment of hypomanic inspiration. They're the result of our actions, the sum total of what we do in the world.
|
||||
|
||||
There are two key rules to keep in mind when exploring altered states of consciousness, including flow and hypomania.
|
||||
|
||||
As my co-founder, Steven Kotler, wrote in his book Stealing Fire: "It's not about you, and it's not about now."
|
||||
|
||||
Even in a flow state, you're still just a human. Don't let peak experiences inflate your ego, or think everything has to happen right this second.
|
||||
|
||||
Never trust the dopamine. Use it, but don't blindly believe it.
|
||||
|
||||
You can use the dopamine, you can ride the high, and you can achieve incredible things with it.
|
||||
|
||||
But in order not to get sabotaged by it, stop, drop, and roll when needed.
|
||||
|
||||
That's how you stay at your peak over the long term without the crash.
|
||||
|
||||
If this article resonated, subscribe to my free 30-day email sequence at the link in my bio — the full protocol for using flow as a competitive advantage without burning up. And follow [@RianSweetDoris](https://x.com/@RianSweetDoris) on X for more content like this.
|
||||
+255
@@ -0,0 +1,255 @@
|
||||
---
|
||||
title: "You Didn't Know GEO: AI Visibility Principles, Practices, and Trade-offs"
|
||||
source: "https://x.com/HiTw93/status/2050931710066565374"
|
||||
author:
|
||||
- "[[@HiTw93]]"
|
||||
published: 2026-05-03
|
||||
created: 2026-05-04
|
||||
description: "One Hour to Make AI Find Your ContentA few friends pinged me recently saying my open source tools were showing up when they asked AI questio..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
## One Hour to Make AI Find Your Content
|
||||
|
||||
|
||||
|
||||
A few friends pinged me recently saying my open source tools were showing up when they asked AI questions. I hadn’t done anything deliberate, so I figured: why not spend an hour structuring things properly? After doing it, I fired off a quick tweet, but the notes were messy. People seemed genuinely interested, so I decided to write it up as a proper article for reference.
|
||||
|
||||
I hate gaming rankings or generating junk content. This article won’t teach you shortcuts. It’s about helping AI better understand the content you already have.
|
||||
|
||||
I looked into why it happened and found that AI search runs on entirely different logic. Traditional SEO is about fighting into the top 10, but 83% of AI Overview citations come from pages outside the top 10. AI rewards clear structure and reliable sourcing, not PageRank. My projects aren’t big, but the READMEs and docs are well-written enough that AI picks them up where bigger sites have thin content. That’s probably why friends were seeing Pake and MiaoYan in their AI results.
|
||||
|
||||
AI search is growing fast: 527% year-over-year in the first half of 2025, ChatGPT hit 900 million weekly active users by February 2026, and referral traffic converts at roughly 5x the rate of traditional search. But it still accounts for less than 1% of total referral traffic. This is a brand visibility strategy, not a traffic strategy. Worth an hour of setup, not a week, because your product is your real competitive advantage, not this.
|
||||
|
||||

|
||||
|
||||
## Use robots.txt to Sort Out Crawler Types
|
||||
|
||||
Most people treat robots.txt as a switch: either block AI crawlers or allow them all. But AI crawlers come in several types, and they do different things.
|
||||
|
||||
**Training crawlers** (GPTBot, ClaudeBot, Meta-ExternalAgent, CCBot) take your content to train models. Blocking them keeps your content out of training data but doesn’t affect current AI search results.
|
||||
|
||||
**Search and retrieval crawlers** (OAI-SearchBot, Claude-SearchBot, PerplexityBot) fetch content in real time to answer user queries. Block these and you vanish from AI search.
|
||||
|
||||
**User-triggered fetchers** (ChatGPT-User, Claude-User, Perplexity-User, Google-Agent) only fire when someone pastes your URL into a chat window. Block them and users asking “summarize this page” get nothing.
|
||||
|
||||
**Opt-out tokens** (Google-Extended, Applebot-Extended) aren’t real crawlers. They’re signals you declare in robots.txt to opt out of AI training.
|
||||
|
||||
**Undeclared crawlers** (Bytespider, xAI’s Grok bot) don’t identify themselves and don’t necessarily follow the rules.
|
||||
|
||||

|
||||
|
||||
My approach: allow search/retrieval and user-triggered crawlers, block training and undeclared ones.
|
||||
|
||||
```text
|
||||
# Search & retrieval: allow
|
||||
User-agent: OAI-SearchBot
|
||||
Allow: /
|
||||
|
||||
User-agent: Claude-SearchBot
|
||||
Allow: /
|
||||
|
||||
User-agent: PerplexityBot
|
||||
Allow: /
|
||||
|
||||
# User-triggered: allow
|
||||
User-agent: ChatGPT-User
|
||||
Allow: /
|
||||
|
||||
User-agent: Claude-User
|
||||
Allow: /
|
||||
|
||||
# Training: block
|
||||
User-agent: GPTBot
|
||||
Disallow: /
|
||||
|
||||
User-agent: CCBot
|
||||
Disallow: /
|
||||
|
||||
# Opt-out tokens
|
||||
User-agent: Google-Extended
|
||||
Disallow: /
|
||||
|
||||
# Undeclared: block
|
||||
User-agent: Bytespider
|
||||
Disallow: /
|
||||
```
|
||||
|
||||
## Write Your llms.txt and Cross-Link Your Sites
|
||||
|
||||
llms.txt is a new standard, similar to robots.txt but designed for AI consumption. You place a Markdown file at your site root describing what your site does, its key pages, and who’s behind it. AI systems prioritize this file when they crawl your content.
|
||||
|
||||
BuiltWith tracks over 840,000 websites that have deployed llms.txt, including Anthropic, Cloudflare, Stripe, and Vercel. But in SE Ranking’s survey of 300,000 domains, adoption is only 10%. It’s still early, and being early is an advantage.
|
||||
|
||||
The format is simple:
|
||||
|
||||
```markdown
|
||||
# Your Project Name
|
||||
|
||||
> One-line description of what this is.
|
||||
|
||||
## Links
|
||||
|
||||
- [Documentation](https://yoursite.com/docs)
|
||||
- [GitHub](https://github.com/you/project)
|
||||
- [Blog](https://yoursite.com/blog)
|
||||
|
||||
## About
|
||||
|
||||
Short paragraph explaining the project, its purpose,
|
||||
key features, and what makes it different.
|
||||
```
|
||||
|
||||

|
||||
|
||||
After creating yours, submit it to [directory.llmstxt.cloud](https://directory.llmstxt.cloud/), [llmstxt.site](https://llmstxt.site/), and the llms-txt-hub repository on GitHub via PR.
|
||||
|
||||
I also did something interesting: I made each site’s llms.txt reference the others. I maintain [tw93.fun](https://tw93.fun/), [weekly.tw93.fun](https://weekly.tw93.fun/), and [yobi.tw93.fun](https://yobi.tw93.fun/). Each site’s llms.txt links to the rest, forming a mesh. An AI crawler entering through any one site can follow the links and discover everything else.
|
||||
|
||||

|
||||
|
||||
These changes take effect after crawlers revisit your site, usually within a few days. After that, try searching for your project name in ChatGPT. The citation sources and description accuracy should improve.
|
||||
|
||||

|
||||
|
||||
## Provide Full Content and Markdown Routes
|
||||
|
||||
llms.txt is the summary. llms-full.txt is the complete version, typically 30-60KB, containing project descriptions, FAQs, usage scenarios, competitive comparisons, and README excerpts. Mintlify’s CDN analysis shows llms-full.txt gets 3-4x more traffic than llms.txt. AI systems that find the summary want the full version.
|
||||
|
||||
**Markdown routes** go further. Evil Martians recommend providing a .md version of every page on your site. A 15,000-token HTML page becomes a 3,000-token Markdown document, 80% less noise.
|
||||
|
||||

|
||||
|
||||
The simplest way to tell AI you have a Markdown version is adding this to your page’s <head>:
|
||||
|
||||
```text
|
||||
<link rel="alternate" type="text/markdown" href="/page.md" />
|
||||
```
|
||||
|
||||
Claude Code and Cursor already send Accept: text/markdown headers when fetching docs. This is standard HTTP/1.1 content negotiation, around since 1997.
|
||||
|
||||
## Register Your Site with Search Platforms
|
||||
|
||||
The robots.txt and llms.txt work from the previous sections makes your content readable to AI, but AI has to find you first. ChatGPT’s search runs on Bing, Google AI Overview uses Google’s own index, and Perplexity also relies on search APIs. If your pages aren’t indexed by search engines, none of the structuring work above matters. So the first step is making sure Google and Bing have indexed your site.
|
||||
|
||||
The setup is straightforward: go to [Google Search Console](https://search.google.com/search-console), verify your domain via DNS or HTML file upload, then submit your sitemap URL (usually [yoursite.com/sitemap.xml](https://yoursite.com/sitemap.xml)). Check the “Pages” indexing report to see which pages are indexed and which have issues. If an important page isn’t indexed, use the URL Inspection tool to manually request indexing.
|
||||
|
||||
You might think Bing doesn’t matter, but Copilot, DuckDuckGo, and Yahoo all run on Bing’s index underneath. Register with Bing Webmaster Tools, submit your sitemap, and check the AI Performance panel to see how often AI cites your content. While you’re there, set up IndexNow so Bing gets notified immediately when you publish new content instead of waiting for a crawler to find it.
|
||||
|
||||
Setting up IndexNow means placing an API key file at your site root, then sending a POST request to [api.indexnow.org/indexnow](https://api.indexnow.org/indexnow) with the list of changed URLs whenever you publish. Bing picks them up within minutes. Many static site generators and CMS platforms have IndexNow plugins available.
|
||||
|
||||

|
||||
|
||||
Google Search Console doesn’t have an AI-specific panel yet, but submitting your sitemap and monitoring indexing status is still worth doing. Google’s AI Overviews pull from a wider range than traditional results, so even pages that don’t rank in the top 10 can appear in AI-generated answers.
|
||||
|
||||
Perplexity has more users than you’d expect. They run a publisher program at [pplx.ai/publisher-program](https://pplx.ai/publisher-program). Once approved, you get an 80/20 revenue share and access to citation analytics data.
|
||||
|
||||
## I Built a Dedicated Knowledge Site for AI
|
||||
|
||||
Instead of waiting for AI to scrape information from scattered sources, give it a single entry point with everything organized.
|
||||
|
||||
A knowledge site should provide three layers: an overview (llms.txt), a full version (llms-full.txt, 30-60KB), and standalone knowledge pages for each core project. Add structured JSON APIs so AI tools can fetch data programmatically. Pull data live from upstream sources like the GitHub API with caching that refreshes periodically, keeping maintenance cost near zero.
|
||||
|
||||
One thing that’s easy to miss: give AI a narrative structure, not just a list of projects. If you have multiple projects, write a description that connects them, how they relate, your technical direction, the overall picture. When AI answers “who is this person” or “what does this team do,” a coherent narrative works much better than a flat list.
|
||||
|
||||
My implementation is called Yobi (from the Japanese 呼び / よび, meaning “to call” or “to summon”). It serves an llms.txt overview, a 50KB llms-full.txt, per-project pages, and four JSON endpoints (/api/profile, /api/projects, /api/blog, /api/weekly) that pull live data from the GitHub API with ISR caching that refreshes hourly. Stack: Next.js + TypeScript on Vercel.
|
||||
|
||||

|
||||
|
||||
The JSON API returns structured project data with live GitHub stats:
|
||||
|
||||

|
||||
|
||||
## Give Each Project Its Own Page
|
||||
|
||||
Each project needs its own standalone page, not a row in a list, but a self-contained Markdown document with a citable summary, core features, competitive comparisons, use cases, and install commands. Ahrefs found that cited pages have titles with higher semantic similarity to user queries, and natural-language URL slugs (like /projects/pake) get cited more than opaque IDs (like /page?id=47).
|
||||
|
||||

|
||||
|
||||
URL structure matters. /projects/pake tells the model what the page is about before it reads a single line. /page?id=47 tells it nothing.
|
||||
|
||||
## Sync Structured Data to Your Main Domain
|
||||
|
||||
Subdomains carry less authority than root domains. AI crawlers that discover [example.com](https://example.com/) won’t automatically find [docs.example.com](https://docs.example.com/) or [api.example.com](https://api.example.com/). If your llms.txt, project pages, and API data are spread across subdomains, AI may only see part of the picture.
|
||||
|
||||
The fix is to mirror key structured data onto your main domain so that [example.com/llms.txt](https://example.com/llms.txt), [example.com/projects/xxx.md](https://example.com/projects/xxx.md), and [example.com/api/projects.json](https://example.com/api/projects.json) all live under one roof. AI crawlers discover your main site through search indexing and find everything without leaving. Implementation options include scheduled CI sync, build-time fetching, or reverse proxying. I use a GitHub Action that syncs subdomain data to the blog repo nightly.
|
||||
|
||||

|
||||
|
||||
When launching a new site, use a checklist to avoid gaps. Core items: robots.txt (categorized crawler permissions), llms.txt (site summary with cross-references), sitemap (submitted to search engines), Bing Webmaster Tools (enable IndexNow), Google Search Console (monitor indexing). Each site’s llms.txt should reference the others, forming a discovery mesh.
|
||||
|
||||
The easiest trap when doing this work is getting carried away with every GEO technique you come across and trying to add them all, creating a mess and losing sight of what matters.
|
||||
|
||||
## These Didn’t Work
|
||||
|
||||
**<meta name="ai-content-url"> and <meta name="llms">**: no spec, no adoption by any major AI system.
|
||||
|
||||
**/.well-known/ai.txt**: multiple competing proposals, no real adoption. Wait for a winner.
|
||||
|
||||
**HTML comments with AI hints**: parsers strip comments before AI sees the content.
|
||||
|
||||
**User-Agent sniffing to serve Markdown**: returning different content to bots versus humans is cloaking. Google will penalize you.
|
||||
|
||||
**Unofficial AI meta tags**: unless a major AI provider explicitly documents support, it’s just noise.
|
||||
|
||||
## JSON-LD Isn’t as Useful as You’d Think
|
||||
|
||||
I initially thought JSON-LD would be powerful for AI visibility. Deeper research showed a more complicated picture. SearchVIU ran an experiment where they put data only in JSON-LD without showing it on the page. All five AI systems they tested failed to find it. Mark Williams-Cook’s follow-up experiment showed that LLMs treat <script type="application/ld+json"> as plain text, reading whatever words are inside without understanding the structured semantics.
|
||||
|
||||
The one confirmed exception is Bing/Copilot, which uses JSON-LD to enrich its search index. Keep existing JSON-LD (it helps Bing/Copilot and traditional rich results), but don’t add it expecting ChatGPT or Claude to cite you more.
|
||||
|
||||
## What the Research Data Says
|
||||
|
||||
The GEO paper from Princeton and IIT Delhi, published at KDD 2024, found that adding **authoritative citations** improves AI visibility by 115%, **relevant statistics** by 33%, and **direct quotations** from credible sources by 43%.
|
||||
|
||||

|
||||
|
||||
My friend [@yaojingang](https://github.com/yaojingang) has been doing serious research on GEO. His [geo-citation-lab](https://github.com/yaojingang/geo-citation-lab) ran 602 prompts across three platforms and scraped tens of thousands of pages for feature analysis. His [full report](https://github.com/yaojingang/geo-citation-lab/blob/main/04-repet/final_report.md) is worth reading. Here are the patterns most useful for content creators.
|
||||
|
||||
**Specificity.** Pages with real data, clear definitions, and side-by-side comparisons see over 50% higher impact than vague, general pages. Step-by-step structure also helps noticeably. Pure FAQ format actually hurts. Those GEO tools that tell you “add FAQ to boost your score” are giving advice the data contradicts, which also validates my decision to drop FAQ sections from my own pages.
|
||||
|
||||
**Content depth.** AI doesn’t favor short summaries. It favors long content it can slice into reusable segments. High-impact pages average nearly 2,000 words with 10+ headings. Low-impact pages average just 170 words, over a 10x gap. The sweet spot is 1,000 to 3,000 words.
|
||||
|
||||
**Relevance.** All mechanical SEO metrics (heading hierarchy, meta descriptions, keyword density) predict less than one single variable: whether your page content actually answers the question the user asked.
|
||||
|
||||
**Platform differences.** ChatGPT cites fewer sources but uses each deeply; its per-citation impact is over 5x that of Google. Perplexity casts a wider net, citing more than twice as many sources. To get cited by ChatGPT, go deep on individual pages. To get cited by Perplexity, go wide.
|
||||
|
||||
**Content type.** Official websites, news, and industry verticals account for roughly 80% of citation sources. But encyclopedia-style and explainer pages have 3x the impact of news pages. English content accounts for over 83% of global citation samples, so projects targeting an international audience need English versions.
|
||||
|
||||
## Retrieved Doesn’t Mean Cited
|
||||
|
||||
Of all the pages ChatGPT retrieves during a session, only 15% end up in the final answer. The other 85% are never cited. Getting into the retrieval pool is just the first hurdle. The model still has to decide which pages are worth citing.
|
||||
|
||||
Ahrefs found that cited pages have titles with noticeably higher semantic similarity to user queries, and pages with descriptive natural-language URL slugs get cited more than those with opaque IDs. This is why llms.txt and Markdown routes help: they give the model a clean, unambiguous signal about what your page covers.
|
||||
|
||||
Brands get cited 6.5x more often through third-party sources than through their own domains. Someone praising your project on Reddit or Hacker News carries more weight than your own marketing copy. That’s exactly why having a well-structured llms.txt matters: it gives the model a citable anchor to point to, even when the conversation that triggered the query happened somewhere else.
|
||||
|
||||
There are AI SEO audit tools that score your site and tell you to add FAQ sections, trust pages, or more text. Don’t let scores drive your decisions. The test is simple: does every paragraph you add contain information that isn’t already on the page? If not, don’t add it. I once added a FAQ to Yobi that just restated what the About section already said, purely to push the score up. That’s padding. I removed it.
|
||||
|
||||
Everything here is about helping AI understand what you have accurately, giving it a clean working environment. That lasts longer than any shortcut.
|
||||
|
||||
The basic configuration takes about an hour. The knowledge endpoint and per-project pages take longer, but once the data structure is in place, maintenance is easy. The daily sync runs on its own.
|
||||
|
||||
Give it a few days for crawlers to pick up the changes, then try searching for your name or project in ChatGPT, Perplexity, or Claude. The citations should be more accurate.
|
||||
|
||||

|
||||
|
||||
AI citation attribution is still unreliable. CJR and Tow Center tested 200 AI-generated citations and found 153 with partial or complete errors. Do the structural work because it makes your content easier to access accurately, but don’t treat an AI citation as proof that users saw your exact words. The mechanism is still improving
|
||||
|
||||
If you have your own products, blog, or website, give it a try. You can also hand this article to Claude Code and let it handle most of the setup.
|
||||
|
||||
## Further Reading
|
||||
|
||||
1. [GEO: Generative Engine Optimization - Princeton & IIT Delhi, KDD 2024](https://arxiv.org/abs/2311.09735)
|
||||
2. [Overseas GEO Research - geo-citation-lab](https://github.com/yaojingang/geo-citation-lab)
|
||||
3. [llms.txt standard specification](https://llmstxt.org/)
|
||||
4. [Why ChatGPT Cites One Page Over Another - Ahrefs](https://ahrefs.com/blog/why-chatgpt-cites-pages/)
|
||||
5. [GEO Benchmark Study 2026 - ConvertMate](https://www.convertmate.io/research/geo-benchmark-2026)
|
||||
6. [Optimizing Content for AI Discovery - Evil Martians](https://evilmartians.com/chronicles/optimizing-content-for-ai-discovery)
|
||||
7. [How LLMs Actually Use Schema Markup - SearchVIU](https://searchviu.com/en/how-llms-actually-use-schema-markup/)
|
||||
8. [AI Search Has a Citation Problem - CJR / Tow Center](https://www.cjr.org/tow_center/we-compared-eight-ai-search-engines-theyre-all-bad-at-citing-news.php)
|
||||
9. [LLMs.txt: Why Brands Rely On It and Why It Doesn’t Work - SE Ranking](https://seranking.com/blog/llms-txt/)
|
||||
10. [How Often Do LLMs Visit llms.txt? - Mintlify](https://www.mintlify.com/blog/how-often-do-llms-visit-llms-txt)
|
||||
11. [IndexNow Protocol Documentation](https://www.indexnow.org/documentation)
|
||||
@@ -0,0 +1,331 @@
|
||||
---
|
||||
title: "Your Prompts Are Fine. Your Context Is Broken"
|
||||
source: "https://x.com/kiruwaaaaaa/status/2047960386066890756"
|
||||
author:
|
||||
- "[[@kiruwaaaaaa]]"
|
||||
published: 2026-04-25
|
||||
created: 2026-04-26
|
||||
description: "Everyone got obsessed with prompt engineering. The perfect wording. The magic phrase. The \"act as an expert\" trick. And for a while, it work..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
Everyone got obsessed with prompt engineering. The perfect wording. The magic phrase. The "act as an expert" trick. And for a while, it worked.
|
||||
|
||||
Then agents arrived - and everything changed.
|
||||
|
||||
Now your AI is not answering one question anymore. It is running a full workflow: searching the web, reading files, calling APIs, editing code, retrying errors - all in one session. And at some point, usually around turn 20, it starts forgetting things. Making mistakes it already fixed. Ignoring instructions it followed perfectly an hour ago.
|
||||
|
||||
That is not a prompting problem. That is a context problem.
|
||||
|
||||
Welcome to 2026, where the real skill is not writing better prompts - it is Context Engineering.
|
||||
|
||||

|
||||
|
||||
## The Evolution Nobody Talks About
|
||||
|
||||
The industry went through three phases quietly, and most people missed the transition:
|
||||
|
||||
2023 - Prompt Engineering. Craft the right words, get the right output. Static, one-turn, artisanal. One person, one question, one answer. This is where 90% of AI content online is still stuck.
|
||||
|
||||
2024-2025 - Context Engineering. Design the entire information ecosystem. What the agent knows, when it knows it, how it stores and retrieves it. This is the phase that separates people who build toys from people who build products.
|
||||
|
||||
2026 - Intent Engineering. Align the full intent of a task - outcomes, trade-offs, constraints - so the agent makes decisions autonomously, not just executes commands.
|
||||
|
||||
Most vibecoders are still in phase one. They write longer prompts when things break. They add "please" and "be careful." They wonder why the agent keeps making the same mistake on step 15 of a 20-step task.
|
||||
|
||||
The answer is almost never the prompt. It is almost always the context.
|
||||
|
||||

|
||||
|
||||
## What Context Engineering Actually Is
|
||||
|
||||
Context engineering is the practice of deliberately designing, structuring and optimizing all information that enters an AI agent's context window at runtime - system prompts, conversation history, retrieved documents, tool definitions, memory, and structured state.
|
||||
|
||||
Andrej Karpathy, one of the founding researchers behind modern AI, put it best:
|
||||
|
||||
"Context engineering is the delicate art and science of filling the context window with just the right information for the next step."
|
||||
|
||||
The analogy that makes this click: an LLM is like a CPU, and its context window is like RAM. The CPU can only process what is in RAM right now. Everything else - no matter how important - does not exist for the model at this moment. Context engineering is the operating system that decides what gets loaded into RAM, when, and how.
|
||||
|
||||
Prompt engineering asks: "How should I phrase this?"
|
||||
|
||||
Context engineering asks: "What does the model need to know right now to do this correctly?"
|
||||
|
||||
The difference sounds subtle. It is not. One is a conversation skill. The other is a system design skill - and in 2026, it is the #1 job of anyone building serious AI applications.
|
||||
|
||||

|
||||
|
||||
## The Four Ways Context Kills Your Agent
|
||||
|
||||
When things go wrong in an agentic workflow, the failure mode almost always fits into one of these four categories:
|
||||
|
||||
Context Poisoning - a hallucination makes it into the context and gets treated as fact for the rest of the session. The agent built a lie into its foundation and now everything downstream is wrong.
|
||||
|
||||
Context Distraction - the volume of context overwhelms the model. There is so much information that the model loses the thread of what actually matters. It answers adjacent questions instead of the real one.
|
||||
|
||||
Context Confusion - superfluous or redundant context influences the response. The agent has two conflicting versions of the same instruction and picks the wrong one.
|
||||
|
||||
Context Clash - different parts of the context actively disagree with each other. Instructions from the system prompt conflict with instructions in a tool result. The model has to choose, and it might choose wrong.
|
||||
|
||||
These are not model bugs. They are architectural failures. Better prompting does not fix them - better context management does.
|
||||
|
||||

|
||||
|
||||
## Context Rot: The Silent Killer of Long Sessions
|
||||
|
||||
The specific failure that destroys most agent workflows has a name: context rot.
|
||||
|
||||
Context rot is the performance degradation that happens as an LLM processes an increasingly long context window over a session. The model technically has all the information - but it stops using it correctly.
|
||||
|
||||
The mechanism behind this is the "lost-in-the-middle" problem, documented by Stanford researchers. Attention weight distributes across the entire context window. Models consistently perform best when critical information sits at the very beginning or the very end of the context. When key instructions get buried in the middle - under tool outputs, error logs, search results, and intermediate reasoning - the model's attention drifts away from them.
|
||||
|
||||
The result: your agent ignores rules it followed perfectly 30 messages ago. It re-introduces bugs it already fixed. It forgets what the goal was. It contradicts itself.
|
||||
|
||||
The numbers are brutal: 79% of multi-agent failures come from context management issues, not model capability. Your agent is not getting dumber. It is drowning in its own history.
|
||||
|
||||
Context gets worse as context windows get bigger. It sounds counterintuitive - surely more context is better? But Opus 4.5 with a 200K context window and Gemini 3 Pro with a 1M window both exhibit the same attention degradation. A 900K-token Gemini session performs dramatically worse on instructions buried at position 400K than instructions at position 0.
|
||||
|
||||
More capacity does not solve the problem - it just delays it and makes it harder to debug.
|
||||
|
||||

|
||||
|
||||
## The 4 Strategies That Actually Fix It
|
||||
|
||||
LangChain's engineering team, after studying dozens of production agents, distilled context engineering into four core strategies: Write, Select, Compress, Isolate. Here is how each one works in practice.
|
||||
|
||||
## Strategy 1 - Write: Save Context Outside the Window
|
||||
|
||||
The first strategy is to stop trying to keep everything in the active context window. Instead, write important information to external storage - files, databases, state objects - and load it back only when needed.
|
||||
|
||||
The most practical implementation for vibecoders: a WORKING.md file.
|
||||
|
||||
```text
|
||||
## Current Task
|
||||
|
||||
Build payment API endpoint
|
||||
|
||||
## Status
|
||||
|
||||
Schema done - controller 50% complete
|
||||
|
||||
## Constraints
|
||||
|
||||
No external libraries - must use existing auth system
|
||||
|
||||
## Next Step
|
||||
Write error handling logic
|
||||
```
|
||||
|
||||
The agent reads this at the start of each session, updates it as it works, and uses it as the ground truth instead of trying to remember what happened 60 messages ago. This single habit eliminates most context rot for most projects.
|
||||
|
||||
For longer sessions, add a MEMORY.md for persistent facts that survive across sessions - API keys structure, project decisions, architecture choices. The agent loads this once at the beginning and never has to re-establish context from scratch.
|
||||
|
||||
This is exactly how Anthropic's multi-agent researcher works internally: it begins by saving its plan to memory before doing any work, because if the 200K context window gets truncated, the plan must survive.
|
||||
|
||||

|
||||
|
||||
## Strategy 2 - Select: Pull Only What Is Needed, When It Is Needed
|
||||
|
||||
Stop dumping everything into context upfront. Instead, design your agent to fetch information at the moment it becomes relevant.
|
||||
|
||||
This is the principle behind Retrieval-Augmented Generation (RAG): instead of loading an entire knowledge base into context, the agent embeds a query, searches a vector database, and pulls only the top 3-5 most relevant chunks - at runtime, for that specific step.
|
||||
|
||||
RAG solves the core problem of static knowledge. Your AI's training data has a cutoff. Your codebase changes daily. Your documents get updated. RAG lets the agent reach into live data sources and pull exactly what the current step needs, without polluting the context with everything else.
|
||||
|
||||
The same principle applies to tools. Agents with 50+ available tools perform significantly worse than agents with 5-10 relevant tools per task - because the tool descriptions themselves consume tokens and create confusion about which one to use. Some teams apply RAG to tool selection itself: embed the task description, match it against tool descriptions semantically, and only load the top tools into context. Studies have shown this improves tool selection accuracy by 3x.
|
||||
|
||||
For vibecoders without a vector database: use Claude Code's Explore sub-agent. Instead of loading your entire codebase into context, the Explore agent reads the codebase in read-only mode, builds a summary, and returns only the relevant parts. Your main context stays clean.
|
||||
|
||||

|
||||
|
||||
## Strategy 3 - Compress: Shrink What Is Already There
|
||||
|
||||
When context cannot be avoided, compress it.
|
||||
|
||||
Claude Code does this automatically at 95% capacity with /compact. The agent summarizes the entire session trajectory into a compressed handoff note and starts fresh with that clean summary as the foundation. Think of it like a developer writing a clean end-of-day status update instead of handing a colleague 6 hours of raw chat logs.
|
||||
|
||||
But compression should not wait for 95% capacity. Build compression into your workflow from the start:
|
||||
|
||||
\- After long tool calls, summarize the result before adding it to context
|
||||
|
||||
\- At the end of each major phase, write a phase summary before moving to the next
|
||||
|
||||
\- When switching tasks, compact the previous task's context first
|
||||
|
||||
\- Use structured formats (JSON/XML/YAML) instead of prose - they are denser and more reliably parsed
|
||||
|
||||
The 60% rule: when Claude Code hits 60% context capacity, compact proactively. Waiting until 95% means the model is already degraded for the last 35% of the session.
|
||||
|
||||

|
||||
|
||||
## Strategy 4 - Isolate: Split Context Across Agents
|
||||
|
||||
The most powerful context engineering technique is also the most underused: isolating context by distributing work across specialized sub-agents with separate context windows.
|
||||
|
||||
The main orchestrator manages goals, decisions, and coordination. Each sub-agent handles a specific subtask in its own isolated bubble. When a sub-agent finishes, only the clean result comes back to the orchestrator - its entire working memory, intermediate steps, failed attempts, and debugging logs are discarded.
|
||||
|
||||
Anthropic's research found that many parallel sub-agents with isolated contexts consistently outperform single-agent architectures on complex tasks - because each sub-agent's full context window is allocated to a narrow, focused problem instead of being shared across everything.
|
||||
|
||||
The tradeoff is token cost. Multi-agent architectures use up to 15x more tokens than single-turn chat. But for production workflows where reliability matters - and where a failed run costs hours of work, not cents - the isolation is worth it.
|
||||
|
||||
In Claude Code 2.0, spawning a sub-agent takes three lines of config. The Task Tool schema handles the rest:
|
||||
|
||||
```text
|
||||
{
|
||||
"description": "Audit payment module",
|
||||
"prompt": "Review src/payments/ for security issues. Return findings only.",
|
||||
"subagenttype": "security-reviewer",
|
||||
"model": "haiku",
|
||||
"runInBackground": true
|
||||
}
|
||||
```
|
||||
|
||||
The sub-agent runs, does its work, returns a clean report, and dies. Your main context never touched the raw audit process.
|
||||
|
||||

|
||||
|
||||
## The Memory Stack Every Serious Builder Needs
|
||||
|
||||
Production AI agents in 2026 use a three-tier memory architecture. You do not need a full vector database to implement this - you can build 80% of it with markdown files.
|
||||
|
||||
> Tier 1 - Hot Memory (Session State)
|
||||
|
||||
The last 5-10 interactions. Managed automatically by the agent. For Claude Code, this is the active conversation. No action needed.
|
||||
|
||||
> Tier 2 - Warm Memory (Working Files)
|
||||
|
||||
Your WORKING.md and daily notes. What are you building today? What did you finish? What is next? What decisions have been made? This is where most context rot gets prevented. Write to it constantly. Read it at session start.
|
||||
|
||||
> Tier 3 - Cold Memory (Semantic Storage)
|
||||
|
||||
Facts, documents, and knowledge that need to survive across weeks and projects. For simple setups: a structured MEMORY.md. For serious production: a vector database (ChromaDB, Qdrant, Pinecone) with embedding-based retrieval. The agent queries this store with semantic search and pulls only what is relevant to the current task.
|
||||
|
||||
The transition from Tier 2 to Tier 3 is where vibecoding becomes a real engineering practice. When your project is complex enough that a single MEMORY.md file is getting unwieldy - that is the signal to move to vector storage.
|
||||
|
||||

|
||||
|
||||
## RAG is Part of Context Engineering - Not the Same Thing
|
||||
|
||||
This confusion is everywhere, so it is worth being explicit.
|
||||
|
||||
RAG (Retrieval-Augmented Generation) is a retrieval technique. It answers one question: "What is relevant to this query?" It uses vector search to fetch matching chunks from a knowledge base and injects them into the prompt.
|
||||
|
||||
Context engineering is the discipline that contains RAG - and much more. It answers a different question: "What is relevant, trustworthy, timely, and auditable enough to put in front of this model right now?"
|
||||
|
||||
Dimension | RAG | Context Engineering
|
||||
|
||||
What it is | Retrieval technique | Full discipline governing all context input
|
||||
|
||||
Scope | Fetches relevant knowledge chunks | Manages instructions, memory, tools, state, history
|
||||
|
||||
Key question | "What is relevant?" | "What is relevant, trusted, and properly timed?"
|
||||
|
||||
Handles memory | No | Yes
|
||||
|
||||
Handles tool outputs | No | Yes
|
||||
|
||||
Handles multi-agent | No | Yes
|
||||
|
||||
When it is enough | Simple Q&A on static corpus | Always needed in agentic systems
|
||||
|
||||
RAG is a powerful tool inside the context engineering toolkit. But thinking RAG solves your context problems is like thinking a good database solves your software architecture problems. It is necessary. It is not sufficient.
|
||||
|
||||

|
||||
|
||||
## MCP: The Infrastructure Layer That Changes Everything
|
||||
|
||||
Model Context Protocol (MCP) is the open standard Anthropic released that makes context engineering scalable at the infrastructure level. Think of MCP as USB-C for AI - a universal connector that lets your agent pull live, structured data from any external system at runtime.
|
||||
|
||||
Before connecting an AI agent to GitHub required custom integration code. Connecting it to Notion required different custom code. Connecting it to Slack required more custom code. Every integration was bespoke, fragile, and maintained separately.
|
||||
|
||||
MCP provides one universal protocol. Implement it once in your agent, and it unlocks an entire ecosystem of integrations - GitHub, Notion, Slack, Google Drive, databases, APIs - all through the same interface. The agent requests what it needs, the MCP server provides it, and the information flows into context exactly when required.
|
||||
|
||||
The key insight for context engineering: MCP enables just-in-time data access at the infrastructure level. Instead of pre-loading everything an agent might need (which causes context bloat and rot), MCP lets the agent pull precisely what it needs at each step. Anthropic's research shows this approach resolves roughly 80% of routine data queries while keeping context lean and accurate.
|
||||
|
||||
> **For vibecoders, the practical implications are significant:**
|
||||
|
||||
\- Connect Claude Code to your GitHub repository and it reads the diff directly instead of you copy-pasting it
|
||||
|
||||
\- Connect it to Notion and your project docs flow into context automatically
|
||||
|
||||
\- Connect it to a Telegram bot and your agent operates live without you running it manually
|
||||
|
||||
MCP is also the foundation of code execution as a context engineering tool. Instead of passing raw data into the context window, the agent writes code that processes the data in a sandboxed environment and passes back only the result. This is how you handle token-heavy objects - images, large files, raw API responses - without poisoning your context with them.
|
||||
|
||||

|
||||
|
||||
## Context Engineering in Practice: A Vibecoder's Workflow
|
||||
|
||||
Here is what a properly context-engineered session looks like for someone building a crypto Telegram bot with Claude Code.
|
||||
|
||||
> Before the session starts:
|
||||
|
||||
\- WORKING.md is updated with current task, status, and next step
|
||||
|
||||
\- MEMORY.md holds project architecture decisions, API endpoints, and key constraints
|
||||
|
||||
\- MCP servers are connected: GitHub (for code), Telegram API (for testing)
|
||||
|
||||
> Opening message to the agent:
|
||||
|
||||
"Load WORKING.md and MEMORY.md. Continue from where we left off. Current task: add price alert functionality."
|
||||
|
||||
Two sentences. The agent has full context in 20 tokens.
|
||||
|
||||
> **During the session:**
|
||||
|
||||
\- Agent reads files via MCP instead of you pasting code
|
||||
|
||||
\- Agent writes progress notes to WORKING.md after each step
|
||||
|
||||
\- At 60% context: /compact - agent summarizes and continues
|
||||
|
||||
\- Sub-agent handles the notification logic in isolation, returns clean code
|
||||
|
||||
> **After the session:**
|
||||
|
||||
\- Agent writes a phase summary to MEMORY.md
|
||||
|
||||
\- WORKING.md is updated with completion status and next steps
|
||||
|
||||
Total context used: dramatically less than a chaotic unstructured session. Reliability: dramatically higher. The bot works on turn 50 the same way it worked on turn 5.
|
||||
|
||||

|
||||
|
||||
## The Bigger Picture: Why This Matters Beyond Individual Projects
|
||||
|
||||
Context engineering is not just a productivity trick. It is the difference between AI that works once and AI that works reliably at scale.
|
||||
|
||||
Vibe coding failures are accelerating in 2026. Amazon's March 2026 outage - caused by an AI-assisted deployment - shut down [Amazon.com](https://amazon.com/) for 6 hours and cost an estimated 6.3 million lost orders. A December 2025 study found 69 vulnerabilities across 15 apps built by major AI coding tools, with 45% of all AI-generated code containing at least one security flaw. Every single tested app lacked CSRF protection.
|
||||
|
||||
Almost none of these failures were model capability failures. They were context failures. Agents that did not have the right information at the right time made catastrophically wrong decisions. Agents that were not told about security constraints did not apply them. Agents whose context had drifted forgot that a table was in production.
|
||||
|
||||
Context engineering solves this by making the agent's information environment explicit, auditable, and controlled. When you design what your agent knows - and what it does not know - you can reason about what it will do. Prompting is a black box. Context engineering is architecture.
|
||||
|
||||
The vibecoders shipping reliable products in 2026 are not the ones with the best prompts. They are the ones who treat context as a first-class engineering concern.
|
||||
|
||||

|
||||
|
||||
## The Stack to Start With Today
|
||||
|
||||
You do not need a vector database. You do not need a custom MCP server. You do not need to understand embedding dimensions. Start here:
|
||||
|
||||
1\. Create WORKING.md in your project folder. Write your current task, status, constraints, and next step. Update it every session. This alone eliminates 80% of context rot for most projects.
|
||||
|
||||
2\. Create MEMORY.md for facts that survive sessions. Architecture decisions, key API structures, project goals. Load it at the start of every session with two lines.
|
||||
|
||||
3\. Use /compact proactively at 60% context, not 95%. Your session's second half will be dramatically more reliable.
|
||||
|
||||
4\. Use structured prompts with XML or markdown blocks instead of prose. <current\_task>, <constraints>, <progress>, <next\_step>. The model's attention finds tagged information far more reliably than narrative paragraphs.
|
||||
|
||||
5\. Delegate with sub-agents when a task is genuinely separable. Let the sub-agent do its work, return its result, and die. Keep your main context clea
|
||||
|
||||
That is it. Five habits. No infrastructure required. Start with WORKING.md today, and you will immediately feel the difference.
|
||||
|
||||

|
||||
|
||||
Prompt engineering got you started. Context engineering is what gets you to production.
|
||||
|
||||
The models are already good enough. The bottleneck is what you put in front of them.
|
||||
@@ -0,0 +1,123 @@
|
||||
---
|
||||
title: "Your harness, your memory"
|
||||
source: "https://x.com/hwchase17/status/2042978500567609738"
|
||||
author:
|
||||
- "[[@hwchase17]]"
|
||||
published: 2026-04-04
|
||||
created: 2026-04-26
|
||||
description: "Agent harnesses are becoming the dominant way to build agents, and they are not going anywhere. These harnesses are intimately tied to agent..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
Agent harnesses are becoming the dominant way to build agents, and they are not going anywhere. These harnesses are intimately tied to agent memory. If you used a closed harness - especially if it’s behind a proprietary API - you are choosing to yield control of your agent’s memory to a third party. Memory is incredibly important to creating good and sticky agentic experiences. This creates incredible lock in. Memory - and therefor harnesses - should be open, so that you own your own memory
|
||||
|
||||
## Agent Harnesses are how you build agents, and they’re not going anywhere
|
||||
|
||||
The “best” way to build agentic systems has changed dramatically over the past three years. When ChatGPT came out, all you could do were simple RAG chains ([LangChain](https://github.com/langchain-ai/langchain)). Then the models got a little better, and could create more complex flows ([LangGraph](https://github.com/langchain-ai/langgraph)). Then they got a lot better, and that gave rise to a new type of scaffolding - [agent harnesses](https://blog.langchain.com/the-anatomy-of-an-agent-harness/).
|
||||
|
||||
Examples of agent harnesses include [Claude Code](https://code.claude.com/docs/en/overview), [Deep Agents](https://github.com/langchain-ai/deepagents), [Pi](https://github.com/badlogic/pi-mono) (powers [OpenClaw](https://docs.openclaw.ai/)), [OpenCode](https://opencode.ai/), [Codex](https://openai.com/codex/), [Letta Code](https://www.letta.com/blog/letta-code), and many more.
|
||||
|
||||

|
||||
|
||||
💡**Agent harnesses are not going away.**
|
||||
|
||||
There is sometimes sentiment that models will absorb more and more of the scaffolding. This is not true. What has happened (and will continue to happen) is that a lot of the scaffolding needed in 2023 is no longer needed. But this has been replaced by other types of scaffolding. An agent, by definition, is an LLM interacting with tools and other sources of data. There will always be a system around the LLM to facilitate that type of interaction. Need evidence? When Claude Code’s source code was leaked, there was [512k lines of code](https://www.reddit.com/r/technology/comments/1scyuod/anthropic_leaked_512k_lines_of_claude_codebut/). That code is the harness. Even the makers of the best model in the world are investing heavily in harnesses.
|
||||
|
||||
When things like web search are built into OpenAI and Anthropic’s APIs - they are not “part of the model”. Rather, they are part of a lightweight harness that sits behind their APIs and orchestrates the model with those web search APIs (via nothing other than tool calling).
|
||||
|
||||
## Harnesses are tied to memory
|
||||
|
||||
Sarah Wooders wrote a [great blog](https://x.com/sarahwooders/status/2040121230473457921) on why “memory isn’t a plugin (it’s the harness)”, and I couldn’t agree with it more.
|
||||
|
||||
> 4月4日
|
||||
|
||||
There is sometimes sentiment that memory is a standalone service, separate from any particular harness. At this point in time, that is not true.
|
||||
|
||||
A large responsibility of the harness is to interact with context. As Sarah puts it:
|
||||
|
||||
> Asking to plug memory into an agent harness is like asking to plug driving into a car. Managing context, and therefore memory, is a core capability and responsibility of the agent harness.
|
||||
|
||||
Memory is just a form of context. Short term memory (messages in the conversation, large tool call results) are handled by the harness. Long term memory (cross session memory) needs to be updated and read by the harness. Sarah lists out many other ways the harness is tied to memory:
|
||||
|
||||
> How is the [AGENTS.md](http://agents.md/) or [CLAUDE.md](http://claude.md/) file loaded into context? How is skill metadata shown to the agents? (in the system prompt? in system messages?) Can the agent modify its own system instructions? What survives compaction, and what's lost? Are interactions stored and made queryable? How is memory metadata presented to the agent? How is the current working directory represented? How much filesystem information is exposed?
|
||||
|
||||
Right now, memory as a concept is in it’s infancy. It’s so early for memory. Transparently, we see that long term memory is often not part of the MVP. First you need to get an agent working generally, then you can worry about personalization. This means that we (as an industry) are still figuring out memory. This means there are not well known or common abstractions for memory. If memory does become more known, and as we discover best practices, it is possible that separate memory systems start to make sense. But not at this point in time. Right now, as Sarah said, “ultimately, how the harness manages context and state in general is the foundation for agent memory.”
|
||||
|
||||
## if you don't own your harness, you don't own your memory
|
||||
|
||||
The harness is intimately tied to memory.
|
||||
|
||||

|
||||
|
||||
💡**If you use a closed harness, especially if its behind an API, you don’t own your memory.**
|
||||
|
||||
This manifests itself in several ways.
|
||||
|
||||
Mildly bad: If you use a stateful API (like OpenAI’s Responses API, or Anthropic’s server side compaction), you are storing state on their server. If you want to swap models and resume previous threads - that is no longer doable.
|
||||
|
||||

|
||||
|
||||
Bad: If you use a closed harness (like Claude Agent SDK, which uses Claude Code under the hood, which is not open source), this harness interacts with memory in a way that is unknown to you. Maybe it creates some artifacts client side - but what is the shape of those, and how should a harness use those? That is unknown, and therefor non-transferrable from one harness to another.
|
||||
|
||||

|
||||
|
||||
💡**But worst is something else - when the whole harness, including long term memory is behind an API.**
|
||||
|
||||
In this situation, you have zero ownership or visibility into memory, including long term memory. You do not know the harness (which means you don’t know how to use the memory). But even worse - you don’t even own the memory! Maybe some parts are exposed via API, maybe no parts are - you have no control over that.
|
||||
|
||||

|
||||
|
||||
When people say that the “models will absorb more and more of the harness” - this is what they really mean. They mean that these memory related parts will go behind the APIs that model providers offer.
|
||||
|
||||
💡**This is incredibly alarming - it means that memory will become locked into a single platform, a single model.**
|
||||
|
||||
Model providers are incredibly incentivized to do this. And they are starting to. Anthropic launched [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview). This puts literally everything behind an API, locked into their platform.
|
||||
|
||||
Even if the whole harness isn’t behind the API, model providers are incentivized to move more and more behind APIs - and are already doing so. For example: even though Codex is an open source, it generates an encrypted compaction summary (that is not usable outside of the OpenAI ecosystem).
|
||||
|
||||
Why are they doing this? Because memory is important, and it creates lock in that they don’t get from just the model.
|
||||
|
||||
## Memory is important, and it creates lock in
|
||||
|
||||
Although memory is early, it is clear to everyone that it is important. It is what allows agents to get better as users interact with them, and allows you build up a data flywheel. It is what allows your agent to be personalized to each of your users, and build up an agentic experience that molds to their desires and usage patterns.
|
||||
|
||||
💡**Without memory, your agents are easily replicable by anyone who has access to the same tools.**
|
||||
|
||||
With memory, you build up a proprietary dataset - a dataset of user interactions and preferences. This proprietary dataset allows you to provide a differentiated and increasingly intelligent experience.
|
||||
|
||||
It’s been relatively easy to switch model providers to date. They have similar, if not identical, APIs. Sure, you have to change prompts a little bit, but that’s not that hard.
|
||||
|
||||
But this is all because they are stateless.
|
||||
|
||||
As soon as there is any state associated, its much harder to switch. Because this memory matters. And if you switch, you lose access to it.
|
||||
|
||||
Let me tell a story. I have an email assistant internally. It’s built on top of a template in [Fleet](https://www.langchain.com/langsmith/fleet), our no-code platform for building Enterprise ready OpenClaws. This platform has memory built in, so as I interacted with my email assistant over the past few months it built up memory. A few weeks ago, my agent got deleted by accident. I was pissed! I tried to create an agent from the same template - but the experience was so much worse. I had to reteach it all my preferences, my tone, everything.
|
||||
|
||||
The plus side of my email agent deleted - it made me realize how powerful and sticky memory could be.
|
||||
|
||||
## Open Memory, Open Harnesses
|
||||
|
||||
Memory needs to be opened, owned by whomever is developing the agentic experience. It allows you to build up a proprietary dataset that you actually control.
|
||||
|
||||
Memory (and therefor harnesses) should be separate from model providers. You should want optionality to try out whatever models are best for your use case. Model providers are incentivized to create lock in via memory.
|
||||
|
||||
This is why we are building [Deep Agents](https://docs.langchain.com/oss/python/deepagents/overview). Deep Agents:
|
||||
|
||||
- Is open source
|
||||
- Is model agnostic
|
||||
- Uses open standards like [agents.md](http://agents.md/) and [skills](https://agentskills.io/home)
|
||||
- Has plugins to [Mongo](https://www.mongodb.com/docs/atlas/ai-integrations/langgraph/), Postgres, Redis and others for storing memories
|
||||
- Is deployable: (1) via [LangSmith Deployment](https://docs.langchain.com/langsmith/deployment) (self hostable, can be deployed on any cloud, can bring your own database to serve as a memory store); (2) behind any standard web hosting framework
|
||||
|
||||
**In order to own your memory, you need to be using an Open Harness**
|
||||
|
||||
**Try out** [Deep Agents](https://docs.langchain.com/oss/python/deepagents/overview) **today.**
|
||||
|
||||
Thank you to a few people for review and thoughts:
|
||||
|
||||
- [Sydney Runkle](https://x.com/sydneyrunkle), who is doing a lot of great Deep Agents and memory work
|
||||
- [Viv Trivedy](https://x.com/Vtrivedy10), who is a leading voice on agent harnesses
|
||||
- [Nuno Campos](https://x.com/nfcampos), who has some great writing on context engineering for finance agents
|
||||
- [Sarah Wooders](https://x.com/sarahwooders), who is CTO of Letta, a company that has consistently been at the forefront of stateful agents
|
||||
@@ -0,0 +1,146 @@
|
||||
---
|
||||
title: "为 Agent 设计产品"
|
||||
source: "https://x.com/dotey/status/2048135262606393777"
|
||||
author:
|
||||
- "[[@dotey]]"
|
||||
published: 2026-04-23
|
||||
created: 2026-04-26
|
||||
description: "原文:Designing for Agents作者:Teddy RikerTeddy Riker@teddy_riker·4月23日 文章Designing for AgentsIf you spend time in the same corner of X as I do,..."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||

|
||||
|
||||
原文:[Designing for Agents](https://x.com/teddy_riker/status/2047312986696454584) 作者:Teddy Riker
|
||||
|
||||
> 4月23日
|
||||
|
||||
如果你和我一样,经常混在 X 上同一个信息圈里刷动态,那么你大概也见过这种说法:用户界面已经死了。
|
||||
|
||||
你会一边刷到“我如何用 Obsidian 搭建第二大脑”,一边刷到“Anthropic 彻底杀死了某某行业”这类帖子。然后很快,你就会看到有人说:一个产品如果不能被 AI 智能体(AI Agent)通过 MCP、API、CLI,或者介于它们之间的方式使用,那它就活不下去。
|
||||
|
||||
这个趋势在 Ramp 已经很明显。过去三个月里,随着越来越多客户开始通过 Claude、ChatGPT 和其他 AI 智能体进入我们的产品,我们 MCP 上的每周活跃用户增长了 10 倍。**(MCP,Model Context Protocol,模型上下文协议,可以理解为一种让 AI 智能体调用外部工具和数据的标准方式。)**
|
||||
|
||||
上周,Salesforce 成了最早主动拥抱这个判断的传统软件巨头之一。
|
||||
|
||||
来自 [https://venturebeat.com/ai/salesforce-launches-headless-360-to-turn-its-entire-platform-into-infrastructure-for-ai-agents](https://venturebeat.com/ai/salesforce-launches-headless-360-to-turn-its-entire-platform-into-infrastructure-for-ai-agents):
|
||||
|
||||
> [https://www.salesforce.com/](https://www.salesforce.com/) 周三宣布了这家公司 27 年历史上最激进的一次架构转型,推出了“[https://www.salesforce.com/news/stories/salesforce-headless-360-announcement/”——这是一项覆盖整个平台的大计划:把平台里的每一项能力都暴露成](https://www.salesforce.com/news/stories/salesforce-headless-360-announcement/%E2%80%9D%E2%80%94%E2%80%94%E8%BF%99%E6%98%AF%E4%B8%80%E9%A1%B9%E8%A6%86%E7%9B%96%E6%95%B4%E4%B8%AA%E5%B9%B3%E5%8F%B0%E7%9A%84%E5%A4%A7%E8%AE%A1%E5%88%92%EF%BC%9A%E6%8A%8A%E5%B9%B3%E5%8F%B0%E9%87%8C%E7%9A%84%E6%AF%8F%E4%B8%80%E9%A1%B9%E8%83%BD%E5%8A%9B%E9%83%BD%E6%9A%B4%E9%9C%B2%E6%88%90) API、MCP 工具或 CLI 命令,让 AI 智能体可以在完全不打开浏览器的情况下操作整个系统。
|
||||
|
||||
> 这项发布是在 Salesforce 于旧金山举办的年度 [https://www.salesforce.com/tdx/](https://www.salesforce.com/tdx/) 大会上宣布的,并且立刻向开发者开放了 100 多个新工具和技能。它也正面回应了一个悬在企业软件头顶的生死问题:当 AI 智能体已经能够推理、规划和执行时,一家公司还需要一个带图形界面的 CRM 吗?
|
||||
|
||||
> Salesforce 的回答是:不需要——而这正是重点。
|
||||
|
||||
Salesforce 这一步很聪明,而且我很难想象这会是一个容易做出的决定。你问大多数销售,他们大概率会告诉你,他们并不喜欢用 Salesforce。但 Salesforce 之所以无处不在,很大一部分原因正是它的用户体验(UX)足够熟悉。销售负责人通常并不想让整个团队重新适应一套新技术;在很多时候,一致性比功能强大更重要。
|
||||
|
||||
Benioff 和他的团队正在承认:这条护城河正在被侵蚀。他们也开始主动拥抱一个现实——未来大量使用行为会通过 Claude、ChatGPT 以及其他用户根本看不见的后台流程来完成。
|
||||
|
||||
我并不认为用户界面(UI)正在死亡。人类仍然想要点击按钮、查看配置、确认任务已经完成。但二八法则已经反过来了:未来人与软件之间 80% 的交互,都会通过 AI 智能体完成。这不仅会改变你需要构建什么,也会改变你构建它的方式。
|
||||
|
||||
## 新的交互模式
|
||||
|
||||
过去二十年里,人们和软件交互的主要方式是:
|
||||
|
||||
用户 → 界面 → 数据库
|
||||
|
||||
你打开一个产品,点来点去,把事情做完。界面就是你体验软件的方式。对大多数人来说,界面本身就是产品。
|
||||
|
||||
但随着 AI 智能体接手越来越多工作,一个新的中间层出现了:
|
||||
|
||||
用户 → 用户的 AI 智能体(比如 Claude)→ 数据库
|
||||
|
||||
AI 智能体代表用户行动。它读取、写入、浏览产品,这样用户就不用亲自操作。突然之间,界面消失了。智能体开始直接和底层系统对话。
|
||||
|
||||

|
||||
|
||||
不过,这个模式也在迅速变化。软件公司正在——而且也应该——设计自己的 AI 智能体和能力。所以新的模式更像这样:
|
||||
|
||||
用户 → 用户的 AI 智能体 → 软件自己的 AI 智能体 → 数据库
|
||||
|
||||
在这个模型里,软件自己的 AI 智能体会替用户的智能体处理复杂性:执行业务逻辑、落实规则、补充后者没有的上下文。两个大语言模型(LLM)一起协作,朝着同一个结果推进。
|
||||
|
||||
## 教会 AI 智能体如何成功
|
||||
|
||||
我现在大部分头脑风暴、写作和构思,都是和大语言模型一起完成的。当一篇草稿准备好分享时,我会通过 Notion 的 MCP 服务器把它推到 Notion 里。我曾经是 Google Docs 的忠实用户很多年,但 Notion 的 MCP 改变了我的习惯。
|
||||
|
||||
作为 Notion MCP 的用户,我很欣赏的一点是:每次我让 AI 智能体写点什么,它几乎都能一次到位。表格、项目符号、斜体、列表,你能想到的格式,它都不会出错。
|
||||
|
||||
这不是偶然,而是设计出来的。
|
||||
|
||||
Notion 的 notion-create-pages 工具描述一开始就写着:“如需完整 Markdown 规范,必须先获取 MCP 资源 notion://docs/enhanced-markdown-spec。不要猜测或幻觉 Markdown 语法。”当我让智能体写入一个页面时,它做的第一件事就是获取这份规范。先读规范,再动笔。所有 Notion 特有的假设,都会被明确指出,而不是依赖通用模型的默认理解。
|
||||
|
||||
在旧世界里,这类规范会放在 API 文档里。接入 Notion 的开发者会读文档、理解规则,然后写一个转换层。现在,Notion 会在 AI 智能体真正需要的时候,直接把规范交到它手里。
|
||||
|
||||
如果你用过 Slack MCP,可能就体验过相反的情况。你的 AI 智能体会默认使用标准 Markdown,却没有遵守 Slack 自己那套特定格式。结果是,你花在修改格式上的时间,可能比自己手写消息还多:
|
||||
|
||||

|
||||
|
||||
当然,Slack 的格式指南在网上能找到,你也可以把它保存下来,再教你的智能体怎么用。但这很烦,而且本来就不该是用户需要操心的事。
|
||||
|
||||
你应该思考:调用你家智能体的人,需要知道什么才能成功?然后主动把这些信息交给它。不要让它自己摸索。
|
||||
|
||||

|
||||
|
||||
## 建立反馈循环
|
||||
|
||||
当我们刚在 Ramp 发布 MCP 时,最大的问题是可观测性(observability)。我们能看到工具调用量,但看不到触发这些调用的聊天上下文。仅仅知道调用量,并不能告诉我们什么有效、什么坏了、用户到底想完成什么。
|
||||
|
||||
后来我们用几种方式解决了这个问题:
|
||||
|
||||
1. **每次工具调用都要求填写“理由”。** 每一次 MCP 或 CLI 工具调用,都要求 AI 智能体带上一个 rationale 参数,解释它为什么要发起这个请求。我们看不到聊天内容,但这个理由可以重建意图。理由里的模式,会告诉我们用户到底想做什么。
|
||||
2. **提供一个反馈工具。** 我们发布了一个独立工具。当 AI 智能体遇到阻碍,或者发现某种模式行不通时,它可以调用这个工具。它会提交自己原本想做什么、尝试了什么、卡在了哪里。
|
||||
3. **给特定工具加入上下文种子。** 我们会给单个工具加入专门设计的参数,用来捕捉之后会有用的上下文:这些信息智能体能拿到,但如果不主动收集,我们之后只能靠猜。
|
||||
|
||||
想象一下,你正在做一个客户支持平台,并提供工具让客户抓取工单。过了一段时间,你开始在理由日志里反复看到类似表达:“正在生成事故报告”“正在起草事故摘要”“正在收集停机复盘相关工单”。
|
||||
|
||||
这就是一个新产品功能的信号!你可以做一个 build-incident-report 工具,用来识别相关工单、评估严重程度、拉取受影响的客户群体,并用一种强约束的格式起草摘要。
|
||||
|
||||
这个工具上线后,你可能又会开始收到反馈:“报告拉进了三天前的工单,但那些不属于这次事故”,或者“它总是把免费套餐用户的工单也放进复盘里,但这些用户不应该出现在事故复盘中”。突然之间,你的 AI 智能体开始告诉你的 AI 智能体:接下来到底该构建什么。
|
||||
|
||||
AI 智能体当然会幻觉。但在反馈这件事上,它们往往比你真正发给产品的多数人类用户更具体,也更一致。
|
||||
|
||||
如果报告拉进了无关工单,你就增加一个日期范围参数。如果不该包含免费套餐客户,你就增加一个客户分组筛选器。每一个反馈循环,都会变成产品改进的新入口。
|
||||
|
||||

|
||||
|
||||
## 留意上下文缺口
|
||||
|
||||
在任何 AI 智能体交互中,你的系统掌握一些调用方智能体不知道的上下文;而调用方智能体也掌握一些你的系统不知道的上下文。设计这些交互时,你应该清楚地判断:哪一方在哪些信息上更有优势。
|
||||
|
||||
比如 Diego 去出了一趟差。他的 AI 首席幕僚收到一条来自费用管理系统智能体的 Slack 提醒:他最近这趟出差还有未完成的报销。现在,两个 AI 智能体都指向同一个目标:正确提交这些报销。
|
||||
|
||||
这两个智能体各自带着不同的上下文。
|
||||
|
||||
Diego 的 AI 首席幕僚知道:
|
||||
|
||||
- Diego 的日历:知道哪些会议发生了、在什么时候、和谁一起
|
||||
- Diego 的邮箱:有酒店和航班确认邮件附件
|
||||
- Diego 的 Slack:能把 Kokkari 那顿晚餐关联到一个他邀请 Acme 团队的对话线程
|
||||
- Diego 的收据:来自邮件附件和照片图库
|
||||
|
||||
费用管理系统知道:
|
||||
|
||||
- 原始交易数据,比如商户、交易时间
|
||||
- 公司关于报销提交的政策
|
||||
- 公司的总账科目(GL accounts)**(GL 通常指 General Ledger,也就是财务记账里的总账分类)**
|
||||
- 公司过往的费用归类习惯
|
||||
|
||||
传统 API 会把问题丢回给用户:“这里有一笔交易需要填写 GL code。请调用这个接口获取 150 个 GL code 选项,然后自己选一个。”
|
||||
|
||||
设计得好的 AI 智能体交互会反过来处理这件事——它不会直接索要 GL code,而是索要上下文:这是一顿客户餐、团队餐,还是个人旅行支出?AI 首席幕僚可以从日历条目或 Slack 对话里找到答案。然后费用管理系统根据自己原本缺失的那部分上下文,自动套用正确的科目。
|
||||
|
||||
Diego 和他的智能体都不需要知道 GL code 到底是什么。财务团队也能得到准确的分类。双方各自贡献自己知道的信息,最终交付一个对 Diego——也对他的会计——都更好的结果。
|
||||
|
||||

|
||||
|
||||
当你设计这种智能体到智能体的交互时,一定要留意上下文缺口。承认你的智能体在哪些地方不擅长,是完全可以的——因为你们其实是在服务同一个用户。
|
||||
|
||||
过去,界面夹在 Diego 和他的费用系统之间。现在,界面夹在他的智能体和你的智能体之间。
|
||||
|
||||
这个变化重新定义了产品团队的工作。过去,你是在为一个想快速完成任务、避免犯错、看得见自己工作的真人设计产品。现在,你仍然是在服务同一个人,只不过中间多了一个代理者。它的直觉、上下文和局限,都和人类不同。
|
||||
|
||||
教会 AI 智能体如何成功、建立反馈循环、留意上下文缺口,这三件事背后其实都在问同一个问题:调用你家智能体的一方,到底需要什么才能把工作做好?你有没有把这些东西交给它?
|
||||
|
||||
大多数公司会发布一个 MCP,勾上“我们也支持 AI 智能体了”这个框,然后继续往前走。它们的使用量可能会增长几个季度,然后停滞。随着时间推移,客户会流向那些真正打磨细节的产品,也会绕开那些只是敷衍了事的产品。
|
||||
|
||||
像当初为人类用户设计产品一样,认真为 AI 智能体设计产品。因为你很快就会发现,最后签支票的,可能正是它。
|
||||
Reference in New Issue
Block a user