<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Ahmad Shawar</title>
    <description>The latest articles on DEV Community by Ahmad Shawar (@ahmad_shawar_de8d35d546cf).</description>
    <link>https://dev.to/ahmad_shawar_de8d35d546cf</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4209564%2F53e87819-0ac9-43b4-ac5d-9f2d1d1462cc.jpg</url>
      <title>DEV Community: Ahmad Shawar</title>
      <link>https://dev.to/ahmad_shawar_de8d35d546cf</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/ahmad_shawar_de8d35d546cf"/>
    <language>en</language>
    <item>
      <title>Giving an AI agent a wallet without giving it your keys</title>
      <dc:creator>Ahmad Shawar</dc:creator>
      <pubDate>Sun, 01 Nov 2026 20:41:25 +0000</pubDate>
      <link>https://dev.to/ahmad_shawar_de8d35d546cf/giving-an-ai-agent-a-wallet-without-giving-it-your-keys-407k</link>
      <guid>https://dev.to/ahmad_shawar_de8d35d546cf/giving-an-ai-agent-a-wallet-without-giving-it-your-keys-407k</guid>
      <description>&lt;p&gt;Agents are starting to pay for things. An agent buying API credits, renting a GPU for an hour or paying for a dataset is no longer a thought experiment, and x402 (HTTP &lt;code&gt;402 Payment Required&lt;/code&gt; with on-chain payment) makes it a normal web request.&lt;/p&gt;

&lt;p&gt;That leaves the question of how the agent holds money.&lt;/p&gt;

&lt;h2&gt;
  
  
  The two bad options
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Give the agent a private key.&lt;/strong&gt; It works until a prompt injection, a bug or a leaked environment file. Then the wallet is empty, and there is nothing between the key and the funds.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Approve every payment by hand.&lt;/strong&gt; Safe, and it removes the reason to use an agent.&lt;/p&gt;

&lt;p&gt;What people actually want is what they already do with a company card: a limit per purchase, a monthly budget, a list of places it works, and a phone call for anything unusual.&lt;/p&gt;

&lt;h2&gt;
  
  
  Put the limits where the agent can't reach them
&lt;/h2&gt;

&lt;p&gt;The limits have to live somewhere the agent, and the machine it runs on, can't change. A smart contract is a good fit: the rules are checked by every node, and changing them needs the owner's key.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://github.com/ahmad-codex/purser" rel="noopener noreferrer"&gt;Purser&lt;/a&gt; is an ERC-4337 smart account built for this. The owner grants each agent a session key with a policy:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;an allow-list of contracts and functions it may call&lt;/li&gt;
&lt;li&gt;a cap per payment and a budget per period, per token&lt;/li&gt;
&lt;li&gt;a validity window&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Inside the policy, the agent pays on its own. Over the limit, the payment becomes an approval request, and it runs only if the owner co-signs. One transaction revokes a key or freezes the whole account.&lt;/p&gt;

&lt;p&gt;If the agent's key leaks, the damage is bounded: the rest of the current budget, at allowed places, until you revoke it.&lt;/p&gt;

&lt;h2&gt;
  
  
  The part that was harder than it looks
&lt;/h2&gt;

&lt;p&gt;ERC-4337 splits an operation into validation and execution, and validation is not allowed to read the clock (ERC-7562), because bundlers have to be able to simulate it reliably. A daily budget is all about the clock.&lt;/p&gt;

&lt;p&gt;So the checks are split:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Validation:&lt;/strong&gt; signature, validity window, allow-list and per-payment cap. A disallowed call fails here, before it costs anything.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Execution:&lt;/strong&gt; the rolling budget, in &lt;code&gt;executeUserOp&lt;/code&gt;, where reading the block time is fine.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Two smaller rules that matter: an owner approval raises the amount but never the scope, so an approved payment still has to be to an allowed place; and a revoke earlier in a bundle still stops a later operation in the same bundle.&lt;/p&gt;

&lt;h2&gt;
  
  
  Testing money code
&lt;/h2&gt;

&lt;p&gt;Unit tests aren't enough for this. Purser has 41 unit tests through a real EntryPoint, fuzz tests that compare random payment and time sequences against a simple model of the budget, and invariant tests that throw thousands of random calls at the account and check three properties after each one: no spending over budget without approval, no funds moved by a revoked key, no policy change without the owner. Slither runs in CI.&lt;/p&gt;

&lt;p&gt;It's still early and not audited, which is why everything below runs on a local chain.&lt;/p&gt;

&lt;h2&gt;
  
  
  Agents use it through MCP
&lt;/h2&gt;

&lt;p&gt;An MCP server exposes six tools: &lt;code&gt;wallet_status&lt;/code&gt;, &lt;code&gt;send_eth&lt;/code&gt;, &lt;code&gt;send_token&lt;/code&gt;, &lt;code&gt;call_contract&lt;/code&gt;, &lt;code&gt;get_request&lt;/code&gt; and &lt;code&gt;list_requests&lt;/code&gt;. Each payment returns one of three outcomes, written for the model: done with the budget left, waiting for the owner with a request id, or refused with a reason it can act on.&lt;/p&gt;

&lt;h2&gt;
  
  
  Try it
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker run &lt;span class="nt"&gt;--rm&lt;/span&gt; &lt;span class="nt"&gt;-it&lt;/span&gt; &lt;span class="nt"&gt;-p&lt;/span&gt; 127.0.0.1:8787:8787 ghcr.io/ahmad-codex/purser:demo
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Open &lt;a href="http://localhost:8787" rel="noopener noreferrer"&gt;http://localhost:8787&lt;/a&gt;. The container starts a local chain, deploys everything, and plays the agent story while the console updates. Then connect your own agent:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;claude mcp add &lt;span class="nt"&gt;--transport&lt;/span&gt; http purser http://localhost:8787/mcp
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;and ask it to pay the merchant 0.3 ETH.&lt;/p&gt;

&lt;p&gt;The &lt;a href="https://github.com/ahmad-codex/purser/blob/main/ROADMAP.md" rel="noopener noreferrer"&gt;roadmap&lt;/a&gt; starts with paying x402 endpoints within the budget, a gas budget per key and EIP-7702 support. It's MIT licensed, and there are good first issues open. If you let agents spend money today, I'd like to hear how you limit it.&lt;/p&gt;

</description>
      <category>agents</category>
      <category>ai</category>
      <category>security</category>
      <category>web3</category>
    </item>
    <item>
      <title>Your embeddings are 32x bigger than they need to be. Maybe.</title>
      <dc:creator>Ahmad Shawar</dc:creator>
      <pubDate>Sat, 31 Oct 2026 11:54:38 +0000</pubDate>
      <link>https://dev.to/ahmad_shawar_de8d35d546cf/your-embeddings-are-32x-bigger-than-they-need-to-be-maybe-309h</link>
      <guid>https://dev.to/ahmad_shawar_de8d35d546cf/your-embeddings-are-32x-bigger-than-they-need-to-be-maybe-309h</guid>
      <description>&lt;p&gt;Every OpenAI embedding you store in Postgres is 6 KB. A hundred million documents is 600 GB of vectors before you build a single index, and an HNSW index wants to live in RAM. That is how a RAG prototype turns into a database bill nobody planned for.&lt;/p&gt;

&lt;p&gt;The fix sounds simple: store fewer bits per number. pgvector already has &lt;code&gt;halfvec&lt;/code&gt; (16 bits) and &lt;code&gt;binary_quantize&lt;/code&gt; (1 bit). VectorChord ships RaBitQ. TurboQuant from Google Research is the new name everyone mentions. Each one promises a smaller index with "minimal recall loss".&lt;/p&gt;

&lt;p&gt;I spent most of this year building TurboQuant and RaBitQ into Postgres as a Rust extension. The most useful thing I learned is this: &lt;strong&gt;whether compression is safe depends on your embedding model, not on the codec.&lt;/strong&gt; Here is what that looks like in numbers, the mistake that cost me months, and how to check your own data in three minutes.&lt;/p&gt;

&lt;h2&gt;
  
  
  The same trick, three very different results
&lt;/h2&gt;

&lt;p&gt;I took pgvector's recommended setup for binary quantization (search 1-bit codes, then rerank the best 100 with the full vectors) and ran it on three public datasets. Recall@10 means: of the 10 results exact search would return, how many did we get back.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Dataset&lt;/th&gt;
&lt;th&gt;Recall@10, binary + rerank&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;OpenAI ada-002 embeddings (DBpedia)&lt;/td&gt;
&lt;td&gt;0.992&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GloVe word vectors&lt;/td&gt;
&lt;td&gt;0.348&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SIFT image descriptors&lt;/td&gt;
&lt;td&gt;0.055&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;On OpenAI embeddings it is almost free: a 32x smaller search for 1% of the results. On SIFT it returns the wrong answer 95% of the time. SIFT values are all positive, so one sign bit per number says almost nothing.&lt;/p&gt;

&lt;p&gt;Your embeddings are not DBpedia. A vendor benchmark on someone else's vectors tells you very little about yours, and nothing in your monitoring will flag that 20% of your search results quietly got worse. You find out when users stop trusting the answers.&lt;/p&gt;

&lt;h2&gt;
  
  
  What each option costs, on real embeddings
&lt;/h2&gt;

&lt;p&gt;On 100,000 OpenAI ada-002 embeddings, exhaustive search over the codes (so this is the compression alone, before any index), averaged over three random seeds:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Option&lt;/th&gt;
&lt;th&gt;Bytes per vector&lt;/th&gt;
&lt;th&gt;Smaller by&lt;/th&gt;
&lt;th&gt;Recall@10&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;float32&lt;/td&gt;
&lt;td&gt;6,144&lt;/td&gt;
&lt;td&gt;1x&lt;/td&gt;
&lt;td&gt;1.000&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;halfvec&lt;/td&gt;
&lt;td&gt;3,072&lt;/td&gt;
&lt;td&gt;2x&lt;/td&gt;
&lt;td&gt;0.999&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;RaBitQ 4-bit&lt;/td&gt;
&lt;td&gt;776&lt;/td&gt;
&lt;td&gt;8x&lt;/td&gt;
&lt;td&gt;0.972&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TurboQuant 4-bit&lt;/td&gt;
&lt;td&gt;772&lt;/td&gt;
&lt;td&gt;8x&lt;/td&gt;
&lt;td&gt;0.953&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;RaBitQ 1-bit&lt;/td&gt;
&lt;td&gt;200&lt;/td&gt;
&lt;td&gt;31x&lt;/td&gt;
&lt;td&gt;0.834&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;binary_quantize&lt;/td&gt;
&lt;td&gt;192&lt;/td&gt;
&lt;td&gt;32x&lt;/td&gt;
&lt;td&gt;0.707&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;RaBitQ 1-bit, rerank top 100&lt;/td&gt;
&lt;td&gt;200 searched&lt;/td&gt;
&lt;td&gt;31x&lt;/td&gt;
&lt;td&gt;0.999&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TurboQuant 3-bit, rerank with 8-bit&lt;/td&gt;
&lt;td&gt;580 searched&lt;/td&gt;
&lt;td&gt;11x&lt;/td&gt;
&lt;td&gt;0.996&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Three practical takeaways:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;halfvec is free.&lt;/strong&gt; If your index fits in memory at half size, stop here.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;At one bit, the codec matters.&lt;/strong&gt; RaBitQ keeps 13 more points of recall than a plain sign bit for 8 extra bytes per row, because it centres the data and corrects its own estimate.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Search small, rerank precise.&lt;/strong&gt; The 100 best candidates from tiny codes almost always contain the true top 10. Reranking them gets you back to 0.99+ while the part you search stays 10 to 30 times smaller.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  In Postgres, today
&lt;/h2&gt;

&lt;p&gt;You don't need to write an extension any more. Same 100,000 embeddings, real indexes in Postgres 18, each at the first setting that reaches 0.95 recall:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Index&lt;/th&gt;
&lt;th&gt;Size&lt;/th&gt;
&lt;th&gt;Recall@10&lt;/th&gt;
&lt;th&gt;p50 latency&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;pgvector HNSW, float32&lt;/td&gt;
&lt;td&gt;781 MiB&lt;/td&gt;
&lt;td&gt;0.959&lt;/td&gt;
&lt;td&gt;2.34 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;pgvector HNSW, halfvec&lt;/td&gt;
&lt;td&gt;391 MiB&lt;/td&gt;
&lt;td&gt;0.957&lt;/td&gt;
&lt;td&gt;2.31 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;pgvector HNSW, binary + rerank&lt;/td&gt;
&lt;td&gt;48 MiB&lt;/td&gt;
&lt;td&gt;0.963&lt;/td&gt;
&lt;td&gt;2.83 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;VectorChord, default&lt;/td&gt;
&lt;td&gt;812 MiB&lt;/td&gt;
&lt;td&gt;0.981&lt;/td&gt;
&lt;td&gt;2.58 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;VectorChord, &lt;code&gt;rerank_in_table&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;31 MiB&lt;/td&gt;
&lt;td&gt;0.957&lt;/td&gt;
&lt;td&gt;1.69 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Two things I would not have guessed:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;VectorChord's default index is bigger than plain HNSW.&lt;/strong&gt; It keeps a second copy of every vector inside the index for reranking. One option, &lt;code&gt;rerank_in_table = true&lt;/code&gt;, stores only the compressed codes: 25x smaller, and the fastest index in this test. VectorChord warns that this mode gets slow when the table has to come from disk; here the table fit in memory, so test it at your real size.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;An HNSW graph costs more than the codes in it.&lt;/strong&gt; The binary index uses about 500 bytes per row for 192 bytes of codes. The rest is neighbour lists. It is still 16x smaller than float32.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  The mistake that cost me months
&lt;/h2&gt;

&lt;p&gt;TurboQuant comes in two flavours. One spends all its bits on the codes. The other spends one bit on a correction that makes inner products mathematically unbiased. Unbiased sounded strictly better, so that is what I shipped in my extension.&lt;/p&gt;

&lt;p&gt;It isn't, for search. Same total bits per number, 100,000 GloVe vectors:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Bits&lt;/th&gt;
&lt;th&gt;With the correction bit&lt;/th&gt;
&lt;th&gt;All bits on the codes&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;td&gt;0.806&lt;/td&gt;
&lt;td&gt;0.925&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;0.667&lt;/td&gt;
&lt;td&gt;0.867&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;0.478&lt;/td&gt;
&lt;td&gt;0.753&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Up to 28 points of recall lost. Search only needs the right order of results for one query, and the uncorrected codes shrink every score by the same factor, which never changes the order. The correction removes that harmless shrink and adds noise, and noise is exactly what reorders neighbours.&lt;/p&gt;

&lt;p&gt;A second detail was worth up to 11 more points: after decoding, rescale each vector back to unit length. The decoded lengths wobble by about 1% from row to row, and that wobble leaks straight into the ranking.&lt;/p&gt;

&lt;p&gt;Both bugs looked like "compression is just lossy". Neither was. When your compressed recall is far below the paper, suspect the estimator before you blame the bits.&lt;/p&gt;

&lt;h2&gt;
  
  
  Which one should you use?
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Under a few million vectors:&lt;/strong&gt; keep float32 or halfvec. Memory is cheap at that size.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Memory is the bill, recall must stay high:&lt;/strong&gt; a 1-bit index with a rerank from the table. pgvector's binary + rerank or VectorChord with &lt;code&gt;rerank_in_table&lt;/code&gt;, whichever wins on your data.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Constant inserts, data that drifts:&lt;/strong&gt; TurboQuant. Nothing to train, a vector is compressed the moment it arrives.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Very large, slow-changing collections:&lt;/strong&gt; RaBitQ with IVF (VectorChord), with an error bound that tells you how many candidates to rerank.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Changing embedding models:&lt;/strong&gt; measure again. Your old compression may not survive the new model.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Check your own data in three minutes
&lt;/h2&gt;

&lt;p&gt;I turned all of this into &lt;a href="https://github.com/ahmad-codex/shrinkvec" rel="noopener noreferrer"&gt;shrinkvec&lt;/a&gt;, an open-source tool. Point it at a table and it samples your vectors, computes the exact answers, measures every option above, builds the real indexes in a scratch schema and prints the SQL for the smallest one that keeps your recall:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;pip &lt;span class="nb"&gt;install&lt;/span&gt; &lt;span class="s1"&gt;'shrinkvec[pg]'&lt;/span&gt;
shrinkvec run &lt;span class="nt"&gt;--dsn&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$DATABASE_URL&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; &lt;span class="nt"&gt;--table&lt;/span&gt; documents &lt;span class="nt"&gt;--column&lt;/span&gt; embedding &lt;span class="nt"&gt;--target&lt;/span&gt; 0.95
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Or try it with nothing installed, on real OpenAI embeddings with Postgres, pgvector and VectorChord inside one container:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker run &lt;span class="nt"&gt;--rm&lt;/span&gt; &lt;span class="nt"&gt;-p&lt;/span&gt; 8080:8080 ghcr.io/ahmad-codex/shrinkvec:demo
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Put &lt;code&gt;--min-recall 0.95&lt;/code&gt; in CI and a model or codec change that hurts search fails the build instead of reaching users.&lt;/p&gt;

&lt;p&gt;Every number in this post comes from it. The TurboQuant and RaBitQ implementations are checked against the error figures their papers publish and against the reference libraries (turbovec and the official rabitqlib) on the same vectors. The method and every raw result are in the repository, and one script regenerates all of them.&lt;/p&gt;

&lt;p&gt;Compression doesn't replace a good index. It decides what fits in memory, and that is usually what decides the bill. Measure it on your data before you ship it.&lt;/p&gt;




&lt;p&gt;&lt;strong&gt;References:&lt;/strong&gt; &lt;a href="https://arxiv.org/abs/2504.19874" rel="noopener noreferrer"&gt;TurboQuant&lt;/a&gt; (Zandieh et al., ICLR 2026) · &lt;a href="https://arxiv.org/abs/2405.12497" rel="noopener noreferrer"&gt;RaBitQ&lt;/a&gt; (Gao and Long, SIGMOD 2024) · &lt;a href="https://arxiv.org/abs/2409.09913" rel="noopener noreferrer"&gt;Extended RaBitQ&lt;/a&gt; (Gao et al., SIGMOD 2025) · &lt;a href="https://github.com/pgvector/pgvector" rel="noopener noreferrer"&gt;pgvector&lt;/a&gt; · &lt;a href="https://github.com/tensorchord/VectorChord" rel="noopener noreferrer"&gt;VectorChord&lt;/a&gt; · &lt;a href="https://github.com/RyanCodrai/turbovec" rel="noopener noreferrer"&gt;turbovec&lt;/a&gt; · &lt;a href="https://github.com/ahmad-codex/shrinkvec" rel="noopener noreferrer"&gt;shrinkvec&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Ahmad Shawar builds LLM and vector search systems in .NET, TypeScript and Rust. &lt;a href="https://github.com/ahmad-codex" rel="noopener noreferrer"&gt;GitHub&lt;/a&gt; · &lt;a href="https://www.linkedin.com/in/ahmad-shawar-0b653752" rel="noopener noreferrer"&gt;LinkedIn&lt;/a&gt;&lt;/em&gt;&lt;/p&gt;

</description>
    </item>
    <item>
      <title>Why markdown plans break when you run multiple AI agents</title>
      <dc:creator>Ahmad Shawar</dc:creator>
      <pubDate>Tue, 27 Oct 2026 21:55:01 +0000</pubDate>
      <link>https://dev.to/ahmad_shawar_de8d35d546cf/why-markdown-plans-break-when-you-run-multiple-ai-agents-h11</link>
      <guid>https://dev.to/ahmad_shawar_de8d35d546cf/why-markdown-plans-break-when-you-run-multiple-ai-agents-h11</guid>
      <description>&lt;p&gt;Most of us coordinate AI coding agents the same way: a markdown file in the repo with a checklist. The agent reads it, picks an item, does the work, ticks the box and commits. For one agent in one session, it works well.&lt;/p&gt;

&lt;p&gt;Then you start a second session. And a third.&lt;/p&gt;

&lt;h2&gt;
  
  
  What goes wrong
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Two agents pick the same item.&lt;/strong&gt; Nothing in a markdown file stops two readers from choosing the same line at the same moment. You find out when both open a PR for the same fix.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;An agent dies mid-task.&lt;/strong&gt; The session times out, the laptop sleeps, the context runs out. The item stays marked "in progress" and no other agent will touch it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Edits race each other.&lt;/strong&gt; Two agents update the plan at once, and one change is lost or turns into a merge conflict an agent then "resolves" badly.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;History lives in git diffs.&lt;/strong&gt; Who claimed what, when, and why it was rejected is buried in commit history, if it was recorded at all.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Nobody can see it.&lt;/strong&gt; You can't tell at a glance which agent is on what, or what has been stuck for an hour.&lt;/p&gt;

&lt;p&gt;None of these are agent problems. They're the classic problems of shared mutable state, and a file is the wrong place for it.&lt;/p&gt;

&lt;h2&gt;
  
  
  What a fix needs
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Atomic claims.&lt;/strong&gt; Two claimers can never get the same item.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Expiry.&lt;/strong&gt; A claim that isn't refreshed goes back to the pool.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Legal transitions only&lt;/strong&gt;, with an error that tells the model what is allowed instead.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Review as a step&lt;/strong&gt;, not an afterthought: approve, send back, or escalate.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;An append-only history&lt;/strong&gt; of every change.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Visibility&lt;/strong&gt;: a live view for people, and updates where the team already looks, without making agents wait on GitHub or Slack.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  How workstream-mcp does it
&lt;/h2&gt;

&lt;p&gt;I built &lt;a href="https://github.com/ahmad-codex/workstream-mcp" rel="noopener noreferrer"&gt;workstream-mcp&lt;/a&gt; to cover that list. It's an MCP server, so agents use it through ordinary tool calls.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Claims&lt;/strong&gt; run in one Postgres transaction with &lt;code&gt;SELECT ... FOR UPDATE SKIP LOCKED&lt;/code&gt;. Concurrent claimers skip rows that are already locked instead of waiting on them, so 32 agents claiming at once each get a different task, and none of them block. A test suite runs exactly that. Each claim has a TTL. If an agent stops refreshing it, the task returns to the pool. A plan can also cap how long a claim lives and refuse refreshes when the holder hasn't recorded any progress, so an agent stuck in a loop that keeps its heartbeat going still lets go.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Dependencies decide what can run in parallel.&lt;/strong&gt; When the orchestrator breaks work into tasks, it declares which ones depend on which, typically because they touch the same module. &lt;code&gt;claim_next_task&lt;/code&gt; skips a task until its dependencies are done, so two agents never work the same code at once, and tasks that don't overlap run side by side.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The state machine is data.&lt;/strong&gt; Each plan type stores its statuses, transitions, allowed roles and retry caps in a JSON graph. If an agent tries an illegal move, the tool returns &lt;code&gt;illegal_transition&lt;/code&gt; along with &lt;code&gt;allowed_next&lt;/code&gt;. In practice the model reads that and corrects itself.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Reviews are part of the flow.&lt;/strong&gt; A developer agent submits an attempt; a reviewer approves it or sends it back to the pool for another pass. After the retry cap, the task goes to a human.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Every change writes an event.&lt;/strong&gt; Database triggers block updates and deletes on the event log, so the history can't be rewritten after the fact.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;GitHub and Slack go through an outbox.&lt;/strong&gt; The change and its notification commit in the same transaction, and a background worker delivers it with retries. A GitHub outage never fails an agent's tool call.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The dashboard&lt;/strong&gt; shows each plan as a board: who holds each task, how long their claim has left, what is waiting on what, and what is stuck. It reads through the same tools the agents call.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F1puqh9p4nxo99cai33ck.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F1puqh9p4nxo99cai33ck.png" alt="Dashboard" width="800" height="450"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Try it
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker run &lt;span class="nt"&gt;--rm&lt;/span&gt; &lt;span class="nt"&gt;-p&lt;/span&gt; 127.0.0.1:8080:8080 &lt;span class="nt"&gt;-e&lt;/span&gt; &lt;span class="nv"&gt;WORKSTREAM_ADMIN_TOKEN&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;local-admin &lt;span class="se"&gt;\&lt;/span&gt;
  ghcr.io/ahmad-codex/workstream-mcp:demo
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Open &lt;a href="http://localhost:8080/demo-insecure-token/ui/" rel="noopener noreferrer"&gt;http://localhost:8080/demo-insecure-token/ui/&lt;/a&gt;. From a clone of the repo, &lt;code&gt;WORKSTREAM_ADMIN_TOKEN=local-admin node scripts/simulate-agents.mjs&lt;/code&gt; runs two developer agents and a reviewer against a ten-task plan, so you can watch claims move across the board.&lt;/p&gt;

&lt;p&gt;To connect your own agent: &lt;code&gt;claude mcp add --transport http workstream-demo http://localhost:8080/demo-insecure-token/mcp&lt;/code&gt;, then ask it to claim the next task.&lt;/p&gt;

&lt;p&gt;For a real setup, clone the repo, open Claude Code in it and paste the setup prompt from the README.&lt;/p&gt;

&lt;p&gt;It's MIT licensed. The &lt;a href="https://github.com/ahmad-codex/workstream-mcp/blob/master/ROADMAP.md" rel="noopener noreferrer"&gt;roadmap&lt;/a&gt; is public, with good first issues for webhooks, connectors and SDKs. Several of these details came straight from the first Reddit thread: the outbox transaction and the refresh limits both shipped within a day of someone pointing at them. I'd especially like to hear how you coordinate multiple agents today, and what breaks.&lt;/p&gt;

</description>
      <category>agents</category>
      <category>ai</category>
      <category>automation</category>
      <category>softwaredevelopment</category>
    </item>
  </channel>
</rss>
