DEV Community: Aftab Bashir

Turned my MCP server into a Claude Code plugin. Here's everything that broke.

Aftab Bashir — Wed, 14 Oct 2026 12:35:00 +0000

In my last post I introduced ContextOS, an MCP server that gives AI coding agents memory across sessions. You open Claude Code in a repo, and it already knows the branch you're on, the decisions you made, and what's still open.

It worked. But installing it took a shell script, a config file, and a claude mcp add command. That's where most people stop.

So I packaged it as a Claude Code plugin. Now it's two commands:

/plugin marketplace add aftabkh4n/contextos
/plugin install contextos@contextos

Getting there took four patch releases in three days. Every bug was something I'd never have found without installing it on my own machine and using it like a stranger would. If you're building a plugin, I hope this saves you some of them.

The plugin layout

A plugin is a folder with a manifest and some optional parts:

plugins/contextos/
├── .claude-plugin/plugin.json   # name, version, MCP server
├── skills/contextos/SKILL.md    # when to remember and recall
├── hooks/hooks.json             # SessionStart hook
└── scripts/ensure-binary.sh     # downloads the binary

Plus a marketplace.json so people can install it by name.

Two small things caught me straight away:

The validator rejects .. in marketplace paths. I wanted the marketplace in its own folder pointing at ../contextos. It won't allow that, so the marketplace manifest moved to the repo root. One repo, one install command. Better anyway.
The install command needs the full name. /plugin install contextos only searches the default marketplace. For your own marketplace it's plugin@marketplace, so contextos@contextos. My README had it wrong, and so did I, the first time I tried.

You can't bundle a 118 MB binary

ContextOS is a self-contained .NET binary with a local embedding model inside it. Each platform build is about 118 MB. That doesn't belong in a plugin folder.

So a SessionStart hook downloads the right build for your OS into ${CLAUDE_PLUGIN_DATA}, a folder that survives plugin updates. The MCP server entry in plugin.json points there.

First bug: the script copied only the binary. The embedding model lives in a Models/ folder next to it, so the first version installed a server that failed its own selftest on every machine. Validation passed, of course. Validation checks the manifest, not whether your program runs.

Bug 1: My new feature deleted everyone's old memories

This one wasn't in the plugin at all. It was in v0.2.0, released the week before.

I'd added memory decay: memories not recalled in 90 days get archived. To support it I added a last_recalled_at column. Existing rows got NULL. The decay rule said "never recalled, so count from the creation date."

Every memory older than 90 days was archived on the first start after upgrading.

I only noticed because my test workspace suddenly had "zero decisions," when I knew it had one.

The fix was two migrations: backfill last_recalled_at with the upgrade time so existing memories get a fresh window, and a repair migration that restores rows already archived by the bug. On my machine the log said Restored 1 memories, and the missing decision came back.

Lesson: when you add a column and a rule that reads it in the same release, the default value for existing rows is a product decision, not a database detail.

Bug 2: Claude ignored the instructions

I wanted "What was I working on?" answered from the injected context, with no tool calls. I put that rule in SKILL.md.

Claude ran git log, listed files, read my old session history, then answered.

The reason: a skill's body only loads when Claude decides the skill applies. The rule wasn't in context when it mattered.

ContextOS already injects workspace state through the MCP initialize handshake, in serverInfo.instructions, which is always loaded. I moved the rule there, one line:

Use this context to answer questions about prior work, decisions or todos. Do not run git, list files, or read session history to answer them.

Next test: zero tool calls, answered in five seconds.

Lesson: skills are for "how to do this when it comes up." Anything that must always apply belongs somewhere that's always loaded.

Bug 3: Updates never actually updated

The download script started like this:

if [ -f "$BINARY" ]; then
  exit 0
fi

It checks whether a binary exists, not which version. And ${CLAUDE_PLUGIN_DATA} survives plugin updates, which is the whole point of it. So after updating the plugin, everyone kept the old binary forever.

Fix: write a .version file after each install and compare it with the version in plugin.json.

Bug 4: The server and the hook start at the same time

On session start, Claude Code launches the MCP server and runs the SessionStart hook in parallel. On a fresh install, the hook is still downloading 118 MB when Claude Code tries to start a binary that doesn't exist yet.

The server fails, and Claude Code remembers the failure for 15 minutes. So the user's first impression is a broken plugin.

Bug 5: My fix killed every window's server

To replace the binary during an upgrade on Windows, I stopped the running process first:

taskkill //F //IM contextos.exe

Combined with Bug 4, the hook killed the server Claude Code had just started. Worse, taskkill by image name kills every contextos.exe on the machine. If you had two Claude Code windows open, updating in one broke both.

My first idea was to swap the binary at session end instead. The docs ended that quickly: SessionEnd hooks get a 1.5 second budget that plugins can't raise, and they also fire on /clear and /resume, when the session keeps running.

The fix that finally worked was to stop replacing binaries at all:

bin/0.2.3/contextos.exe
bin/0.2.4/contextos.exe

Each version installs into its own folder, and plugin.json points at the folder for its own version. Nothing running is ever touched, so there's nothing to kill and no file locks. Old folders get cleaned up later, when nothing is using them.

The tradeoff: right after an update, the new folder is still downloading, so the server fails once and you choose Reconnect in /mcp. The hook prints a line into Claude's context explaining that. A known, one-time failure with a clear fix beats a silent one.

I also added a test that reads plugin.json and fails the build if the server path doesn't contain the manifest's own version.

Bug 6: Linux needed a library minimal systems don't have

While cleaning up the release archives, the Linux binary aborted on start in WSL:

Couldn't find a valid ICU package installed on the system.

Minimal distros and Docker images often don't ship libicu, and that's exactly where people run agents. The fix is one line in the project file:

<InvariantGlobalization>true</InvariantGlobalization>

I didn't want that to quietly change embeddings for memories people had already stored, so I embedded four strings before and after, including accented text, a Turkish İ, and Chinese. The max difference was 0.0 on all of them. Then it shipped.

One more thing about versions

The marketplace reads plugin.json from the main branch. So the moment I pushed a version bump, new installs pointed at a GitHub release that didn't exist yet, and got a 404. Now I tag right after CI goes green, every time.

Where it ended up

Two-command install
Upgrades that never touch a running binary
Claude answers "What was I working on?" from injected context with zero tool calls
Runs on Linux without libicu
Four tools, under 700 tokens of tool definitions

That last number taught me something about my own setup. When I checked, my Claude Code sessions were loading 140 MCP servers and 294 skills from plugins I'd installed once to try. ContextOS was one server out of 140. If your sessions feel heavy, run /context and look before blaming any single tool.

Try it

/plugin marketplace add aftabkh4n/contextos
/plugin install contextos@contextos

Restart Claude Code. If contextos shows as failed in /mcp on the first start, choose Reconnect while the binary finishes downloading. Then open any git repo and ask: "What was I working on?"

Repo: github.com/aftabkh4n/contextos

If something breaks for you, open an issue. Apparently that's how this thing gets better.

What spanner for an M12 bolt? An agent that knows DIN and ISO disagree

Aftab Bashir — Sat, 03 Oct 2026 13:25:30 +0000

This is a submission for the Sanity Challenge, Path One: Ship an Agent That Queries Real Content

What I Built

Fastener Spec Agent answers metric hex fastener questions correctly, including the ones where the official standards disagree with each other.

DIN 933 and ISO 4017 describe the same part: a fully threaded hex head set screw. ISO 4017 replaced DIN 933, but the trade still orders by the old name every day. The two standards are identical at almost every size, except four, where the head's width across flats changed:

Size	DIN 933	ISO 4017
M10	17 mm	16 mm
M12	19 mm	18 mm
M14	22 mm	21 mm
M22	32 mm	34 mm

So "what spanner do I need for an M12 bolt?" has no single correct answer. A chatbot that confidently says "19 mm" is wrong half the time, and a 19 mm spanner on an 18 mm head rounds the corners.

I manage the e-commerce platform for a UK fastener supplier, so this is a question real customers ask. The agent:

looks up both standards in a Sanity Knowledge Base before answering,
gives both values when they differ and explains how to tell which one you have,
notes that DIN 933 is withdrawn but still sold under that name, and
cites the entries it used and shows every tool call it made.

A keyword search wouldn't get there. "M12 across flats" returns 19 mm or 18 mm depending on which page ranks first. The answer only works because the relationship between the two standards is modelled explicitly.

Demo

The four example questions and what the agent gets right:

"What spanner do I need for an M12 hex set screw?" 19 mm for DIN 933, 18 mm for ISO 4017, plus how to check which you have (measure across the flats).
"Is a DIN 933 M22 interchangeable with ISO 4017?" No. M22 is the only size where the ISO head is larger (34 vs 32 mm).
"What's the head height of an M16 set screw?" 10 mm, identical in both. It doesn't invent a difference.
"Is DIN 933 still a current standard?" Withdrawn and superseded by ISO 4017, still widely ordered by the old name.

To run it yourself: clone the agent repo, set three values with dotnet user-secrets (a Sanity organization token with Context Viewer permission, the MCP endpoint URL, and an Anthropic API key), then dotnet run. The README has the full steps.

Code

Agent (.NET 9): https://github.com/aftabkh4n/fastener-spec-agent
Sanity Studio, schemas and seed data: https://github.com/aftabkh4n/sanity-fastener-kb

How I Used Sanity

The content model

Five document types: standard, fastenerType, propertyClass, sizeSpec (one document per size per standard) and equivalence.

equivalence is the important one. It links two standards and holds an array of differences, each with the size, the attribute, both values and a plain-English practical impact ("Different spanner: 19 mm for DIN, 18 mm for ISO"). Instead of hoping a model notices that two tables disagree, the disagreement is stored as data.

Every dimension came from a published standard sheet, with a source URL and a verified flag I ticked after checking it by hand. Nothing was filled in from a model's memory.

What I pointed Sanity Context at

One Knowledge Base with three sources:

My Sanity dataset: 38 documents across all five types, with references unfolded so each size spec carries its standard's code and status.
A supplier's DIN 933 standard sheet (PDF).
A reference web page comparing DIN 931/933 with ISO 4014/4017.

My first build crawled that website without limits and pulled in 43 pages about flange bolting torque and ASTM stud bolts. Limiting the crawl to the one relevant page kept the Knowledge Base focused and well inside the 150-document budget.

What the Knowledge Base caught

The build raised three issues, and each taught me something.

It found an error in my own data. I had seeded DIN 933 with the status current. The PDF said withdrawn and superseded by ISO 4017, and the PDF was right. I fixed the status in the Studio, linked it to ISO 4017 with supersededBy, and rebuilt.

It caught a real conflict between published sources. The supplier's PDF lists M14 at 21 mm under a DIN 933 heading. That's the ISO value; the original DIN 933 figure is 22 mm. The Knowledge Base showed both claims side by side, each traced to its sources, and I resolved it as 22 mm. That decision persists across builds.

It flagged a conflict that wasn't one, which proved the point of the schema. The build reported M22 as 32 mm in one entry and 34 mm in another. Both are correct: one is DIN, one is ISO. Picking either card would have created a standing instruction teaching the Knowledge Base something false. Instead, I added an instruction stating that DIN and ISO values for the same size belong to separate standards and aren't conflicting facts, and put the same principle in the Knowledge Base's purpose. The false conflict was gone on the next build.

That was the clearest argument for structured content I ran into: without the explicit DIN↔ISO modelling, even the build confused the two standards.

Which Context tools the agent uses

The agent connects to a Context MCP endpoint in Knowledge Base mode, which serves three tools:

initial_context: fetches the Knowledge Base outline at the start of a conversation, so the agent knows which entries exist
knowledge_base_read: reads specific entries by path, e.g. dimensions/fully_threaded/din_933, dimensions/fully_threaded/iso_4017 and standards_comparison
knowledge_base_search: available for questions that don't map neatly onto the outline

What the agent does with the content

The agent is a .NET 9 minimal API using the official Model Context Protocol C# SDK, with Claude running a tool loop over the Context tools. For the M12 question, it reads the outline, pulls the DIN 933, ISO 4017 and standards-comparison entries, then compares them and answers with both values and their sources. Every tool call is shown under the answer, so you can see exactly what it read.

The system prompt rules that mattered most:

Always consult the Knowledge Base; never answer dimensions from memory.
When DIN and ISO differ, give both values and say which is which.
Never guess which standard the user's parts are made to. Tell them how to check instead.

That last rule came from testing. An early answer added "if you bought off-the-shelf stock, it's most likely DIN 933". It sounds helpful, but nothing in the Knowledge Base supported it, so I removed it.

Sanity Project Details

Project ID: tko9cbz7
Dataset: production (public)
Schema: standard, fastenerType, propertyClass, sizeSpec, equivalence (see the Studio repo)

Agent Session

I built both repos with Claude Code. The moment worth showing: I asked it to extract DIN and ISO values from a standard sheet that only tabulated DIN 933. My instructions said to mirror DIN values into ISO if ISO wasn't listed. Following that literally would have produced an equivalence with zero differences, so instead it stopped and explained the collision. I found a second source for the ISO values and confirmed them against a manufacturer's product listings.

I got tired of re-explaining my codebase to Claude every morning, so I built this

Aftab Bashir — Thu, 24 Sep 2026 09:46:20 +0000

Every morning I open Claude Code and have the same conversation.

"We use the outbox pattern for Kafka writes." "The auth service is separate from the API." "We decided last week not to use MediatR for this project." "Yes, I know the test coverage is low in the storage layer, we're fixing it."

Same context. Every session. From scratch.

I got tired of it. So I built ContextOS.

What it does

ContextOS is an MCP server that gives AI coding agents persistent memory across sessions. You store decisions, todos, and notes during a session. The next time you open Claude Code in that workspace, ContextOS injects the relevant context automatically before you type a single word.

The agent already knows where you left off.

Here is what that looks like in practice. I open Claude Code in a workspace I have not touched in three weeks and ask "what was I working on?" Without calling any tool, Claude responds:

Project: contextos-test on branch master. Recent decision: using the outbox pattern for Kafka writes to ensure exactly-once delivery. Three commits in the last session. One uncommitted file.

No tool call. No "let me check your memory." It just knows. That is the feature I built everything around.

How it works

Three pieces worth explaining: the MCP tools, the retrieval pipeline, and auto-hydration.

The MCP tools

Four tools exposed over the MCP protocol:

remember stores a memory with a type (decision, note, todo, gotcha, skill), tags, and an importance score from 0 to 1
remember_skill stores a reusable procedure with name, steps, and outcome. Skills never decay.
recall runs hybrid search over stored memories. Supports scope="global" to search across all your workspaces.
context assembles a markdown summary of the current workspace state

Auto-hydration

When an MCP client connects, the MCP protocol sends an initialize request. ContextOS responds with the standard handshake and also sets serverInfo.instructions to a pre-assembled context blob.

The MCP spec says clients should treat serverInfo.instructions as background knowledge. Claude Code does exactly that. It reads the injected context and uses it naturally, without the user asking, without any tool call, before the first message.

The blob includes your current branch, recent commits, active todos, recent decisions, and top skills. The whole thing is assembled in under 20ms and kept under 2KB.

The retrieval pipeline

When you call recall:

Your query gets embedded using a local ONNX model (all-MiniLM-L6-v2, bundled in the binary, no API keys needed)
Vector search runs a cosine similarity scan over all stored memory embeddings
Keyword search runs FTS5 BM25 ranking over memory content and tags
Both result lists get merged using Reciprocal Rank Fusion (RRF, k=60)
Results get reranked by exp(-age_days/30) * (0.5 + importance)
Top-k results are returned

RRF is the interesting choice here. It combines ranked lists without needing to normalize scores across different retrieval methods. A memory that ranks 3rd in vector search and 5th in BM25 scores better than one that ranks 1st in only one of them.

The embeddings run entirely locally. No API call, no latency spike, no cost per query.

Memory decay

Memories auto-archive after 90 days of inactivity. If you recall a memory, the clock resets. Skills represent durable procedural knowledge so they never decay. Setting decay_days=0 on any memory pins it permanently.

What I built it on

.NET 10. The self-contained single-file binary story is solid. One file, no dependencies, runs anywhere. The release pipeline produces four platform binaries averaging 118MB each, including the .NET runtime, ONNX Runtime, LibGit2Sharp, and the embedding model.

126 tests. CI on Linux. Apache 2.0.

Honest limitations

Cursor support is not manually verified for auto-hydration (tools work, hydration behavior unknown)
No team or cloud sync, workspace-local SQLite only
No automatic git ingestion, manual remember calls only
Tested primarily with Claude Code

Install in one command

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/aftabkh4n/contextos/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/aftabkh4n/contextos/main/install.ps1 | iex

Or via .NET tool:

dotnet tool install -g ContextOS

Then open Claude Code in any git repo and ask: "What was I working on?"

Repo: https://github.com/aftabkh4n/contextos

If you try it, I want to know what breaks. Open an issue or comment here.

How I Built 50 Developer Tools That Run Entirely in the Browser

Aftab Bashir — Mon, 07 Sep 2026 05:33:23 +0000

I kept ending up on the same kind of website. I needed a quick JSON formatter or a YAML validator, I searched for one, and I landed on a page buried in ads that took four seconds to load and asked me to accept cookies twice. The tool itself was fine. Everything around it was miserable.

So over a few months I built my own. 50 tools, all free, all running fully in the browser. No backend, no accounts, no tracking. This is what I learned.

The one rule: everything runs client-side

I gave myself a single constraint at the start. Every tool has to work without a server. You paste your data, the work happens in your browser, nothing gets sent anywhere.

This was partly a privacy decision. When you use my JSON formatter, your JSON never leaves your machine. There is no server to log it because there is no server at all. For developers pasting in tokens, config, or API responses, that matters.

But the constraint also made the whole project possible. No backend means no hosting bill, no database to secure, no API keys to rotate, no server to keep alive. The entire site is static files on GitHub Pages. It costs nothing to run and it will keep working whether one person uses it or a thousand.

What client-side actually handles

More than I expected. Modern browser APIs are strong enough that most developer tools do not need a server at all.

Hashing was the surprise. The Web Crypto API does SHA-256 and SHA-512 natively, so my hash generator is a few lines calling crypto.subtle.digest. No library needed.

UUID generation is one call to crypto.randomUUID. Base64 is built in through btoa and atob. The clipboard, file downloads, image resizing through canvas, all native. My image compressor resizes and recompresses photos using a canvas element and never uploads a thing.

For the few things the browser cannot do alone I pulled in one small library. YAML parsing uses js-yaml. QR codes use a tiny generator library. That is it for dependencies across all 50 tools.

The parts that fought back

QR codes took three tries. The first two libraries I picked had broken or moved CDN builds, and I spent an evening watching the browser console throw 404s at me before I found one that actually loaded and had a sane API. Lesson learned: pin the version, do not trust the latest tag.

Client-side image compression is fiddly. Canvas will happily hand you a PNG that is larger than the original if you are not careful, because PNG is lossless and re-encoding adds overhead. I had to detect that case and tell the user when their file was already optimised rather than pretend I saved them space.

Why no framework

The whole thing is plain HTML, CSS, and vanilla JavaScript. One HTML file per tool. No build step, no npm install, no bundler.

For a project like this that was the right call. Each tool is self-contained and small. If I want to fix the regex tester I open one file, change it, and push. There is no toolchain between me and the code. In a few years when some framework has moved on, these files will still open and run exactly as they do today.

Some tools I use myself

The YAML validator is the one I open most, usually to check a Kubernetes manifest before applying it. It validates the syntax and shows the parsed JSON so I can confirm the structure.

The SQL formatter cleans up the one-line queries that come out of application logs.

The diff checker and regex tester get daily use too.

All 50 are at aftabkh4n.github.io and the full source is on GitHub.

Would I do it again

Probably yes. The no-server rule sounded restrictive when I started and it ended up being the thing that kept the project alive. Simple code, zero hosting cost, and a privacy story I do not have to lie about.

If you build small utilities, try the browser-only version first. You can do more without a backend than you would guess. Worst case you hit a wall and add a server later, but I never did.

My tests were describing the code, not checking it

Aftab Bashir — Sun, 30 Aug 2026 07:47:41 +0000

Built a .NET invoicing library with Claude Code over about a week. Zero dependencies, VAT and GST arithmetic, JSON and CSV export, the usual. By the third phase I had 202 tests passing on two target frameworks and green CI on three operating systems.

It would also have been wrong by 3p on any UK invoice with three items at £3.99.

Not wrong in some pathological edge case. Wrong on a completely normal invoice, at the most common price point in British retail, in a way that ends up in someone's VAT return.

I found it because I got suspicious of my own green checkmark.

Why agent-written tests lie to you

Ask an agent to implement something and write tests for it. It writes both. They pass.

You have not tested the code. You have confirmed the code agrees with itself.

I know how obvious that reads. It was not obvious to me at the time, because the suite looked legitimate. Property tests. Golden scenarios with hand-calculated values across USD, JPY and KWD. A file literally called CsvExportTests with a culture-swap test in it, which is the exact test you write if you know about the .NET decimal formatting trap.

That test could not catch the bug it existed to catch. I will get to it.

Breaking my own code on purpose

Mutation testing, if you have not run into it: introduce a deliberate bug, see if any test fails. Nothing fails, that behaviour is not tested, regardless of what the test names imply.

I tried Stryker.NET. It fell over on the multi-target setup and I burned fifteen minutes before giving up. Doing it by hand ended up better anyway, because I picked the mutations rather than getting a percentage at the end. I do not really want a coverage score. I want to know if the four rounding call sites are pinned.

The loop, which is as dumb as it sounds:

Apply one mutation. Run tests. Write down what failed. Revert. Check green. Next one.

Under three failures on an arithmetic mutation, I called it a hole.

What fell out

Nothing pinned the rounding policy. The library rounds half-up, MidpointRounding.AwayFromZero, because that is what tax authorities expect. .NET defaults to banker's rounding, which will quietly hand you off-by-a-penny invoices. So I flipped it to ToEven and ran the suite.

Five failures. All five were unit tests of the rounding helper itself. None of the twenty-five golden invoice scenarios blinked.

Not one of them had a midpoint value in it. I had proved the helper rounds correctly on its own. I had not proved the calculator ever calls it. Two different things and I was only covering one.

Here is the part that got me. The scenario I would have put money on catching this, ¥995 at 10% giving ¥99.5, does not discriminate at all. ToEven rounds 99.5 up to 100, because 100 is the even one. Same answer. My "obvious" midpoint test was not a midpoint test.

Discounts, same story. Pulled the rounding out of the invoice-level discount calculation. One test failed, and it was a generic property test about all decimals being rounded. Every discount scenario I had written used a clean percentage of a clean subtotal. Nothing landed on a half-penny, so nothing broke.

The culture test was decorative. This one still annoys me. The CSV test swapped CultureInfo.CurrentCulture to de-DE and tr-TR, exported, asserted. Correct in every way. When I swapped InvariantCulture for CurrentCulture in the actual export code, it passed.

The fixture invoice totalled 100, 20 and 120. Under de-DE, 100m.ToString() gives you "100". Same as invariant. The test was fine except for the single detail that mattered, which was having a number with a decimal point in it.

Changed the unit price to 10.50. Suddenly the mutation kills three tests.

And then the release pipeline just lied. Tagged v0.3.0 and forgot to bump the version in the project file. Workflow packed 0.2.0. NuGet returned a 409 because that version was already up there. --skip-duplicate ate the error. Every step green. Nothing published.

Green does not mean shipped. I did not know that until it happened to me.

The one I am glad I did not ship

Those four are test-quality problems. Annoying, fixable. The fifth was a different animal.

I was adding a per-line tax mode. HMRC and the ATO both let you round tax per line instead of on the subtotal, and if the accounting system on the other end does it per line, your totals disagree by a penny. Reasonable feature.

Somewhere around phase three I had picked up the habit of making the agent answer design questions on paper first, with actual numbers, before touching code. So I asked four. One of them was what happens when per-line meets tax-inclusive pricing.

The numbers came back and they were not good.

Extracting a tax-exclusive base out of an inclusive price leaves a residual on every line. Always zero or minus one minor unit. Never positive. One line, who cares. But the residual is periodic, and which prices trigger it is completely predictable:

10% tax: line total in minor units where x mod 11 = 5
20% VAT: x mod 6 = 3

£3.99 is 399 pence. 399 mod 6 is 3.

Every £3.99 line loses a penny. Three lines, 3p. Seven lines, 7p. And the reconciliation rule I had written earlier only absorbs one minor unit, so it would have shaved the difference off the tax figure and produced a VAT breakdown implying 19.82% on a 20% invoice. That is not a rounding artefact, that is a wrong number on a filing report.

So I did not build it. Constructor throws on that combination, the analysis is written down, someone can pick it up later. Probably me.

If I had written the code first, a property test would have caught the broken invariant eventually. But the implementation would already exist by then, and at that point the tempting move is to loosen the invariant rather than admit the design is wrong. On paper it cost twenty minutes and no ego.

What I would actually suggest

Not "adopt mutation testing." Everyone nods at that and nobody does it.

Smaller: find the three or four places in your code where being wrong is expensive and quiet. Mine were four rounding call sites. Break each one by hand, run the tests, count. Half an hour, no tooling, and you will learn something uncomfortable.

And when an agent is building something with non-obvious edge cases, make it do the hard design questions in writing before it writes anything. Not a plan document. Worked arithmetic. The £3.99 thing was invisible in prose and screamed the second someone actually did the sums.

I am not turning this into a methodology. One project, a few questions I happened to get lucky with, and I would bet there is still stuff wrong in there that none of my mutations went near. The takeaway is smaller than a lesson: a passing test suite written by whatever wrote the code tells you those two things are consistent with each other. Not that either is right. Took me a few hundred green tests to properly feel that.

Library is on NuGet as InvoiceCore if you want it. Honestly it is more useful as a worked example of the above than as an invoicing package, and I would rather you took the protocol than the dependency.

BlazorMemory 1.0 is out. Ten months, 14 packages, and what I got wrong along the way.

Aftab Bashir — Thu, 20 Aug 2026 08:27:59 +0000

I started BlazorMemory in January because I wanted an AI chat assistant in Blazor that remembered things. I looked for a .NET library that did this. There wasn't one. Everything in the space was Python, and everything assumed you had a server and a vector database.

Blazor WASM has neither. So I built it.

v1.0.0 shipped this week. Here is what is in it, and more usefully, what I would do differently.

What 1.0 includes

Four storage backends. IndexedDB runs in the browser with no backend at all, which is the case I originally built this for. EF Core covers SQL Server and SQLite. pgvector handles PostgreSQL with native vector search and an HNSW index. InMemory is for tests.

Four AI providers. OpenAI, Anthropic, Azure OpenAI, Ollama. Each one works for both embeddings and fact extraction, and they mix freely. You can run Ollama embeddings with a Claude extractor if you want.

The Ollama combination is the one I like most:

builder.Services
    .AddBlazorMemory()
    .UseIndexedDbStorage()
    .UseOllamaEmbeddings()
    .UseOllamaExtractor();

No API key. No cost per request. Everything local. For development this removes the last reason not to try the library.

A drop-in UI component. One line of markup gives you a panel with the stored memories, delete and clear, export and import, thumbs up and down feedback, and a mode toggle:

<MemoryPanel UserId="@userId" IsOpen="true" />

A memory graph. Memories render as nodes, connected by edges where the cosine similarity crosses a threshold. Vanilla JS force simulation, no D3, no external libraries:

<MemoryGraph UserId="@userId" SimilarityThreshold="0.65f" />

Semantic Kernel integration. BlazorMemory implements SK's IMemoryStore, so it drops into an existing SK app without changing anything else.

Multi-agent shared memory. Several agents share one memory pool. Each agent writes to its own namespace but reads across all of them, so agents see what other agents learned.

Three things I got wrong

The storage interface changed three times. First when I added namespaces, then again when I added importance scores. Each change meant touching every adapter, every test, every extension method. If I had used an options object from the start instead of positional parameters, those would have been additive changes instead of breaking ones.

Consolidation was harder than everything else combined. Storing memories is easy. Not storing forty near-duplicate memories is not. Early versions produced "User works in software," "User is a developer," and "User writes code" as three separate entries.

The fix was a priority order in the consolidation prompt: NONE first, then UPDATE, then DELETE, then ADD. The model has to justify adding something new rather than defaulting to it. That single reordering did more for memory quality than any amount of prompt polish.

I trusted local models to return clean JSON. The Ollama extractor worked in testing and failed constantly in practice, because llama3.2 wraps its JSON in markdown fences roughly half the time and sometimes adds a sentence of commentary first. The parse failed silently and extraction returned nothing.

Now the extractor strips code fences, hunts for the first bracket and its match, and retries once with a stricter prompt if the parse fails. Obvious in hindsight. Cost me a version to notice.

What I would tell someone starting this

Ship small and often. Fourteen packages sounds like a lot but no single release was large. v0.2 added namespaces. v0.3 added export and import. v0.5 added thumbs up and down. Each one took a day or two and each one gave me something to write about.

The writing mattered more than I expected. Downloads spiked after every article, not after every release. The releases without a post attached barely moved the numbers.

Getting it

dotnet add package BlazorMemory
dotnet add package BlazorMemory.Components
dotnet add package BlazorMemory.Storage.IndexedDb
dotnet add package BlazorMemory.Embeddings.Ollama
dotnet add package BlazorMemory.Extractor.Ollama

14 packages, 132 tests, MIT licensed.

GitHub: https://github.com/aftabkh4n/BlazorMemory

BlazorMemory v0.8.0: Semantic Kernel adapter, Ollama embeddings, and memory decay

Aftab Bashir — Sun, 09 Aug 2026 09:57:37 +0000

Four things shipped in v0.8.0. I will go through each one.

Semantic Kernel integration

The most requested feature since I published the library. BlazorMemory now implements SK's IMemoryStore interface directly.

dotnet add package BlazorMemory.SemanticKernel

builder.Services
    .AddBlazorMemory()
    .UseInMemoryStorage()
    .UseOpenAiEmbeddings(apiKey)
    .UseOpenAiExtractor(apiKey)
    .UseSemanticKernelMemoryStore(userId: "alice");

That registers BlazorMemoryMemoryStore as SK's IMemoryStore in DI. You can now pass it to SK's SemanticTextMemory or any SK plugin that takes an IMemoryStore.

One design decision worth explaining: SK has no concept of userId, but BlazorMemory requires one for every store operation. The adapter takes a userId parameter (defaults to "sk") and uses it for all operations. If you are building a multi-user app, create one adapter per user or pass the userId at registration time.

SK collections map to BlazorMemory namespaces. So CreateCollectionAsync("work") creates a namespace called "work" and all records in that collection are scoped to it.

Ollama embeddings

dotnet add package BlazorMemory.Embeddings.Ollama

builder.Services
    .AddBlazorMemory()
    .UseOllamaEmbeddings()
    .UseOpenAiExtractor(apiKey);

No API key. No cost per request. Runs against a local Ollama instance at http://localhost:11434. Default model is nomic-embed-text which produces 768-dimensional embeddings.

You can configure it:

builder.UseOllamaEmbeddings(options =>
{
    options.Model = "mxbai-embed-large";
    options.BaseUrl = "http://my-server:11434";
    options.Dimensions = 1024;
});

The package has zero external dependencies. It uses System.Net.Http.Json directly. No Ollama SDK to pull in.

The obvious use case is development. Run Ollama locally, pull a model, and test your AI assistant without spending money on embeddings. Switch to OpenAI embeddings in production by changing one line.

Memory decay and summarization

This solves a real problem. A user who chats with your assistant every day for a month can accumulate hundreds of memories. Most of them are redundant or stale. The memory panel becomes noise.

SummarizeOldMemoriesAsync collapses old memories into a summary entry:

await memory.SummarizeOldMemoriesAsync(
    userId,
    maxMemories: 50,
    keepRecent: 20);

If the user has fewer than 50 memories, nothing happens. If they have more, the oldest ones (count minus 20) get passed to the LLM extractor for summarization, then deleted. A new memory is stored with the summary, prefixed with [Summary].

The summary prompt is: "Summarize these facts about a user into a single concise paragraph. Start with 'User background:'. Facts: ..."

You can call this on a schedule or after each conversation. It is a no-op when memory count is below the threshold so calling it frequently is safe.

Verbatim mode importance scoring

Thumbs up and down now work in verbatim mode too. Previously they only showed in Smart mode. The MemoryPanel component dispatches to the right service method based on the current mode automatically.

await memory.MarkVerbatimImportantAsync(memoryId);
await memory.MarkVerbatimUnimportantAsync(memoryId);
await memory.ResetVerbatimImportanceAsync(memoryId);

Same scoring logic as Smart mode. Important memories get a 1.5x multiplier on relevance. Unimportant ones drop to 0.3x.

Current state

11 packages on NuGet, 108 tests passing.

dotnet add package BlazorMemory
dotnet add package BlazorMemory.SemanticKernel
dotnet add package BlazorMemory.Embeddings.Ollama
dotnet add package BlazorMemory.Components

GitHub: https://github.com/aftabkh4n/BlazorMemory

Turning TravelAI.Core Into a Real Production System

Aftab Bashir — Sun, 02 Aug 2026 07:42:12 +0000

A few months ago I published TravelAI.Core, a .NET library for searching travel destinations using AI. Version 2.0.0 shipped with support for OpenAI, Anthropic, Azure OpenAI, and Ollama. It works. People are using it.

But it's still just a library. One package, doing one job, called directly from your code.

That's not how production systems work. So I'm upgrading it.

What TravelAI.Core looks like today

You install the package, call a method, and it searches destinations using whichever AI provider you configured. Simple, useful for small projects.

Plug it into a real product with real traffic and a few problems show up fast:

One process does everything. Search, AI calls, and business logic all run in the same place. If the AI provider is slow, your whole app waits. You can't scale just the search part without scaling everything else. And if something breaks, you're digging through console output trying to figure out which call caused it.

These aren't bugs. They're what happens when a library grows past its original scope.

Splitting it into services

I'm breaking TravelAI.Core into three pieces.

API Service - the front door. Takes requests, validates them, passes work along. It doesn't do the heavy lifting itself.

Search Service - handles destination search and filtering. Can scale independently if search traffic grows without touching the AI side.

AI Service - handles all calls to OpenAI, Anthropic, Azure, or Ollama. Isolated so a slow or unavailable provider doesn't freeze everything else.

Each service does one job.

Adding a message queue

Instead of the services calling each other directly, I'm putting RabbitMQ between them.

Here's why it matters. If the API service calls the AI service directly and the AI service is slow, the API service waits. With a queue, the API service sends a message and moves on. The AI service picks it up when it's ready. Nothing blocks.

It also means if the AI service crashes and restarts, no requests get lost. They sit in the queue until the service comes back up.

Centralized logging

I'm adding Serilog so every service writes to one place.

This sounds small. It isn't. When something breaks in a multi-service system, the hard part usually isn't fixing the bug. It's working out which service caused it. Scattered logs across three consoles turn a five-minute investigation into an hour of guessing.

Why bother

A single library shows you can write clean code. A multi-service system with a message queue and centralized logging shows you can design something that holds up under real conditions: slow networks, provider outages, traffic spikes.

And it costs nothing to build. Everything runs locally through Docker.

What's next

Split the codebase into three services
Add RabbitMQ between them
Wire up Serilog
Test under load locally
Write up the before and after with real numbers

TravelAI.Core started as a simple idea. It's turning into something more useful: a real example of how to structure a system that doesn't fall over.

More updates as this progresses.

GitHub: https://github.com/aftabkh4n/TravelAI.Core
NuGet: https://www.nuget.org/packages/TravelAI.Core

Reducing boilerplate in AI memory with a chat wrapper for .NET

Aftab Bashir — Thu, 30 Jul 2026 08:12:12 +0000

Every developer who uses BlazorMemory writes the same code after every chat message:

var reply = await CallLlmAsync(systemPrompt, userMessage);
await memory.ExtractAsync($"User: {userMessage}\nAssistant: {reply}", userId);

Query memories, build a prompt, call the LLM, extract new facts. Four steps, every time, in every app. v0.7.0 wraps all of that into one call.

MemoryEnabledChat

The new MemoryEnabledChat service takes a delegate for the LLM call and handles everything else:

// Register in Program.cs
builder.Services
    .AddBlazorMemory()
    .UseIndexedDbStorage()
    .UseOpenAiEmbeddings(apiKey)
    .UseOpenAiExtractor(apiKey)
    .UseMemoryEnabledChat();  // new

// Use it in your chat service
public class ChatService(MemoryEnabledChat chat)
{
    public Task<string> SendAsync(string message, string userId)
        => chat.ChatAsync(
            message,
            userId,
            (systemPrompt, msg) => CallOpenAiAsync(systemPrompt, msg));
}

The delegate receives a system prompt that already contains the relevant memories. You call your LLM with it and return the reply. MemoryEnabledChat handles the rest.

What it does internally

// 1. Query relevant memories
var memories = await _memory.QueryAsync(userMessage, userId, QueryOptions);

// 2. Build system prompt with memory context
var systemPrompt = BuildSystemPrompt(memories, BaseSystemPrompt);

// 3. Call your LLM via the delegate
var reply = await llmCall(systemPrompt, userMessage);

// 4. Extract new facts in background
// Errors are swallowed so extraction failures never crash the chat
_ = ExtractSafelyAsync(userMessage, reply, userId, namespace);

return reply;

Extraction errors are swallowed intentionally. A failed extraction is a degraded experience, not a crash. The user still gets their reply.

Customising behaviour

Two properties control how it works:

chat.QueryOptions = new QueryOptions { Limit = 8, Threshold = 0.60f };
chat.BaseSystemPrompt = "You are a helpful assistant for a software company.";

QueryOptions controls how many memories are retrieved and the similarity threshold. BaseSystemPrompt is prepended before the memory context block.

Single-service approach

If you do not want to inject MemoryEnabledChat separately, the same behaviour is available directly on IMemoryService:

var reply = await memory.ChatWithMemoryAsync(
    userMessage,
    userId,
    (systemPrompt, msg) => CallOpenAiAsync(systemPrompt, msg));

Same delegate pattern, same behaviour, fewer injections.

Before and after

Before v0.7.0 a typical chat service looked like this:

public async Task<string> SendAsync(string message, string userId)
{
    var memories = await _memory.QueryAsync(message, userId,
        new QueryOptions { Limit = 5, Threshold = 0.65f });

    var context = string.Join("\n", memories.Select(m => $"- {m.Content}"));
    var prompt = $"You are a helpful assistant.\n\nWhat you know:\n{context}";

    var reply = await CallOpenAiAsync(prompt, message);

    await _memory.ExtractAsync($"User: {message}\nAssistant: {reply}", userId);

    return reply;
}

After:

public Task<string> SendAsync(string message, string userId)
    => _chat.ChatAsync(message, userId,
        (prompt, msg) => CallOpenAiAsync(prompt, msg));

The logic is the same. The boilerplate is gone.

Getting v0.7.0

dotnet add package BlazorMemory
dotnet add package BlazorMemory.Components
dotnet add package BlazorMemory.Storage.IndexedDb
dotnet add package BlazorMemory.Embeddings.OpenAi
dotnet add package BlazorMemory.Extractor.OpenAi

84 tests passing across 9 packages.

GitHub: https://github.com/aftabkh4n/BlazorMemory

I made my .NET travel AI library work with OpenAI, Anthropic, Ollama, and Azure. Not just one.

Aftab Bashir — Mon, 27 Jul 2026 07:50:59 +0000

When I first shipped TravelAI.Core, it only worked with Azure OpenAI and Azure AI Search. You needed an Azure subscription, a deployed GPT-4o model, a configured AI Search index, and the patience to wire it all up before you could generate a single itinerary.

Downloads were slow. Not surprising in hindsight.

Most developers don't have Azure credentials sitting around. They want to try something before committing to a cloud provider. I was basically asking people to do significant setup work before they could see if the library was even useful to them.

So I rebuilt the provider layer.

What changed

The core interfaces stayed exactly the same. IItineraryGenerationService, IDestinationSearchService, IPriceAnomalyDetector all look identical from the outside. What changed is how you wire up the backend.

In v1.0.0 you needed a config section with Azure credentials. In v2.0.0 you pick a provider:

builder.Services.AddTravelAI(options => options.UseMock());
builder.Services.AddTravelAI(options => options.UseOpenAI("sk-..."));
builder.Services.AddTravelAI(options => options.UseAnthropic("sk-ant-..."));
builder.Services.AddTravelAI(options => options.UseOllama("http://localhost:11434"));
builder.Services.AddTravelAI(options => options.UseAzureOpenAI("endpoint", "key", "gpt-4o"));

The mock provider is the one I'm most pleased with. Zero credentials, works offline, returns a realistic 3-day Rome itinerary with activities, costs, and timing. You can build and test the full integration flow on a train with no internet.

How the abstraction works

There's a single ILlmProvider interface:

public interface ILlmProvider
{
    Task<string> GenerateAsync(
        string systemPrompt,
        string userPrompt,
        CancellationToken ct = default);
}

Each provider implements it. ItineraryGenerationService now takes ILlmProvider instead of AzureOpenAIClient. The Anthropic adapter uses Anthropic.SDK, the Ollama adapter makes raw HTTP calls to /api/chat, the mock just returns a hardcoded JSON string.

The destination search side has a mock too. MockDestinationSearchService does keyword scoring in memory against five curated destinations. Good enough to build against while you decide whether you want Azure AI Search or something else.

The Ollama adapter

Ollama's API is simple but you're dealing with streaming responses and the JSON format varies slightly across model versions. I went with a non-streaming request to keep the adapter stateless, which works fine for itinerary generation.

var response = await _http.PostAsJsonAsync("/api/chat", new
{
    model = _model,
    stream = false,
    messages = new[]
    {
        new { role = "system", content = systemPrompt },
        new { role = "user", content = userPrompt }
    }
});

Nothing clever. Just works.

What the library does

Four things once registered:

Itinerary generation takes a traveller profile and destination and returns a structured day-by-day plan with activities and cost estimates. Price anomaly detection analyses flight options against historical baselines and flags anything unusual. Destination search understands natural language queries like "warm with beaches and local food, not too touristy". Booking automation runs the end-to-end flow with retry logic and rollback on failure.

The whole thing is deployed to Azure Kubernetes Service. The GitHub Actions pipeline builds for linux/arm64, pushes to GHCR, and deploys with a manual approval gate. Took me a while to figure out the arm64 part.

Getting started

dotnet add package TravelAI.Core

Start with UseMock(). If it does what you need, switch to a real provider. The rest of your code doesn't change.

GitHub: https://github.com/aftabkh4n/TravelAI.Core

I added pgvector support to my .NET AI memory library

Aftab Bashir — Mon, 27 Jul 2026 06:37:50 +0000

BlazorMemory has had EF Core storage from the start. It works. But there is a problem with how it handles search.

The current EfCoreMemoryStore loads every memory for a user into C#, then runs cosine similarity in a loop. For a user with 50 memories that is fine. For a user with 5,000 it is a full table scan on every query.

v0.6.0 ships a new package that fixes this properly.

BlazorMemory.Storage.Pgvector

The pgvector adapter moves vector search into PostgreSQL. Instead of loading everything and computing in C#, it runs a single SQL query using the <=> cosine distance operator.

SELECT * FROM "Memories"
WHERE "UserId" = @userId
ORDER BY "Embedding" <=> @queryVector
LIMIT 5;

PostgreSQL handles the math. The .NET code just maps the results.

Setup

dotnet add package BlazorMemory.Storage.Pgvector

You need PostgreSQL with the pgvector extension. If you are on a fresh database:

CREATE EXTENSION IF NOT EXISTS vector;

Then wire it up:

builder.Services
    .AddBlazorMemory()
    .UsePgvectorStorage<AppDbContext>()
    .UseOpenAiEmbeddings(apiKey)
    .UseOpenAiExtractor(apiKey);

Your AppDbContext needs to extend PgvectorMemoryDbContext or apply the configuration manually:

public class AppDbContext : PgvectorMemoryDbContext
{
    public AppDbContext(DbContextOptions<PgvectorMemoryDbContext> options)
        : base(options, dimensions: 1536) { }
}

The dimensions parameter must match your embedding model. OpenAI text-embedding-3-small uses 1536. Adjust for other providers.

The HNSW index

The package creates an HNSW index on the embedding column automatically via EF migrations:

entity.HasIndex(e => e.Embedding)
      .HasMethod("hnsw")
      .HasOperators("vector_cosine_ops")
      .HasDatabaseName("IX_Memories_Embedding_Hnsw");

HNSW is approximate nearest neighbour search. It trades a small amount of recall for much faster query times at scale. For memory retrieval this is the right tradeoff. You do not need perfect recall, you need fast and good enough.

When to use which adapter

Use BlazorMemory.Storage.EfCore when:

You are building a server-side Blazor or ASP.NET Core app
You have a small number of memories per user (under a few hundred)
You want the simplest possible setup with SQLite or SQL Server

Use BlazorMemory.Storage.Pgvector when:

You are on PostgreSQL already
You expect large memory stores per user
You want search to scale without loading data into memory

Use BlazorMemory.Storage.IndexedDb when:

You are building Blazor WASM
You want zero backend
Everything stays in the browser

Current state

9 packages on NuGet, 70 tests passing.

GitHub: https://github.com/aftabkh4n/BlazorMemory

Letting users teach an AI which memories matter

Aftab Bashir — Tue, 16 Jun 2026 18:16:25 +0000

I built BlazorMemory to give Blazor AI assistants persistent memory. The library uses an LLM to extract facts from conversations, embeds them as vectors, and retrieves the relevant ones for each new query.
The system worked but it had a quiet failure mode. The LLM decided what was important. The user had no say. So when someone marked their birthday as a memory and the assistant kept surfacing "user enjoys coffee" instead, there was no way to fix it.
v0.5.0 fixes this.
How it works
Each memory now has an

ImportanceScore

field. Default is 1.0. Users can mark a memory as important (1.5) or unimportant (0.3) via thumbs up and thumbs down buttons in the panel.
During search, the score acts as a multiplier on cosine similarity:

// In QueryAsync
results = results
    .Select(m => m.WithRelevanceScore((m.RelevanceScore ?? 0f) * m.ImportanceScore))
    .OrderByDescending(m => m.RelevanceScore)
    .ToList();

That is the entire algorithm. A memory marked important with a 0.7 similarity gets boosted to 1.05 and beats a neutral memory at 0.9. A memory marked unimportant with a 0.9 similarity drops to 0.27 and falls off the list.

API

// Boost in future searches
await memory.MarkImportantAsync(memoryId);

// Down-rank but do not delete
await memory.MarkUnimportantAsync(memoryId);

// Back to neutral
await memory.ResetImportanceAsync(memoryId);

// Custom score
await memory.SetImportanceAsync(memoryId, 1.8f);

In the UI
If you use the component, the thumbs buttons appear on every memory card automatically:

<MemoryPanel UserId="@userId" IsOpen="true" />

You can hide them with AllowFeedback="false" if you do not want users to override the LLM.
Important memories get a green left border. Unimportant ones get dimmed and a red left border. Easy to scan at a glance.
Why down-rank instead of delete
The thumbs down button could have just deleted the memory. I decided against it for two reasons.
First, users click the wrong button. A delete that can not be undone is hostile UX.
Second, sometimes you want to suppress a memory without erasing it. Maybe the assistant keeps bringing up an old job title and you want to push it down without losing the context completely. Down-ranking with a score of 0.3 makes the memory available but unlikely to surface.
If users actually want to delete, the ✕ button right next to the thumbs is one click away.

Getting v0.5.0

dotnet add package BlazorMemory
dotnet add package BlazorMemory.Components
dotnet add package BlazorMemory.Storage.IndexedDb
dotnet add package BlazorMemory.Embeddings.OpenAi
dotnet add package BlazorMemory.Extractor.OpenAi

All 8 packages on NuGet. Tests passing.
GitHub: https://github.com/aftabkh4n/BlazorMemory