Most answers to « give my AI agent long-term memory » hand you an opaque vector store: embeddings in a database you can’t read, can’t diff, and can’t easily redact. I wanted the opposite — memory I can open in an editor, review in a pull request, and git blame line by line. That itch is what pushed OKF4net from a single library into a small toolkit over the last few months. It just reached v0.5, and this post is about what’s new — starting with the part I’m most excited about.
If you haven’t seen it before: OKF4net (docs & project site) is an independent, zero-dependency .NET implementation of Google’s Open Knowledge Format (OKF). OKF represents knowledge as a directory of markdown files with YAML frontmatter — cross-linked like a wiki, versioned in git. No database, no proprietary format: if you can cat a file you can read it, if you can git clone a repo you can ship it.
The headline: agent memory as plain markdown
OKF4net.Agents turns a bundle into tools and context for the Microsoft Agent Framework. OkfBundleTools exposes read, browse, graph, search, write, append-log, validate and more as function tools an agent can call directly. Layer OkfContextProvider onto the same instance and the agent automatically gets relevant bundle context injected into each turn — and, when you opt in, its exchanges captured back into the bundle as long-term memory:
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OKF4net.Agents;
var tools = new OkfBundleTools("./my_bundle");
// Memory capture is opt-in (Disabled by default) — turn it on explicitly.
var provider = new OkfContextProvider(
tools,
new OkfContextProviderOptions { MemoryCapture = MemoryCaptureMode.Enabled });
AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
{
ChatOptions = new ChatOptions { Tools = tools.GetTools() },
AIContextProviders = [provider],
});
var response = await agent.RunAsync("What do we know about orders?");
Here’s what makes it different. Capture is deterministic — no extra LLM call: after each turn, the last user message and the agent’s final response are appended to a single memory concept for the day (memory/<yyyy-MM-dd>), with a matching log.md change-history entry. Those writes go through the exact same validated, lock-protected, path-safe write path any other caller uses, and the captured text is blockquote-neutralized so a payload smuggled into a message can’t fake document structure.
The payoff is that memory is just files in your bundle. You can:
git blame a remembered fact to see exactly when and in which exchange it entered the memory,
diff memory across commits and redact a line with a normal edit,
point a second agent at the same directory with no export step,
and review the whole thing in a PR like any other change.
I’ll be honest about where v1 stands: this captured memory is bundle-global, unscoped, and opt-in — it carries no session/user/tenant key, so it’s meant for a shared, non-sensitive knowledge base, which is exactly why it ships disabled by default. If you need per-caller isolation, that lives one layer up in the catalog (below). I’d rather ship an honest, inspectable v1 than a magic box.
The rest of what’s new (v0.2 → v0.5)
The memory story is the headline, but the project grew in every direction since the first release. OKF4net now ships as five NuGet packages plus a couple of standalone tools:
A local MCP server, OKF4net.Mcp. The okf-mcpdotnet tool exposes a bundle to Claude Desktop or Claude Code over the Model Context Protocol — now with bundle auto-discovery, so it finds your knowledge base instead of making you wire a path. Recipes for other MCP-capable editors (VS Code, Cursor, Rider…) are on the issue tracker as good-first contributions.
A multi-bundle catalog, OKF4net.Catalog. A catalog.json manifest, a source resolver, and full-text search across many bundles — with read-only knowledge sources and writable memory tiers (session / user / tenant) for exactly the per-caller scoping the agent provider’s v1 memory doesn’t do.
Machine-readable CLI output. The Native AOT okf CLI (validate/info/index/graph/parse/fmt) gained a --json flag on validate and info, so a CI step can parse structured diagnostics instead of scraping text.
A producer that turns a repo into a bundle.producers/OkfProducer generates a validated OKF bundle straight from an existing repository (npm/NuGet/README detection so far). It’s an early walking skeleton, but it closes the loop: you don’t have to hand-author a bundle to try the ecosystem.
Through all of it, the core constraint held: OKF4net and its CLI have zero third-party runtime dependencies — base class library only, hand-written YAML-subset parser and link scanner included. That’s what lets the CLI ship as a single self-contained Native AOT binary with no runtime to install, and it keeps the barrier to contributing low: there’s no framework to learn before you can read the code. Much of OKF4net is built with AI assistance (Claude Code), with the OKF spec and an extensive test suite — including byte-exact golden CLI captures — as the ground truth every change has to satisfy.
Come contribute
OKF4net is open source under LGPL-3.0-or-later and deliberately welcoming to first contributions — no prior OKF knowledge needed. The good first issue label names the files to touch and the test that should go green, ROADMAP.md shows where it’s headed, and Discussions is the place to ask before you write any code. If you’d rather start by reading, the project site and docs are the friendlier way in. Your first PR is three commands away: dotnet build, dotnet test, dotnet format.
If « agents that remember things in files you can read » sounds useful, I’d love the help — and the feedback.
Parts 1 and 2 covered the model and the full import/configuration procedure. This last part is about timing and running it in production: the day-before / day-of / stabilization timeline, scheduled archiving, backups, GDPR re-activation, and rollback.
The single most under-estimated fact of this whole migration:
The migration starts the day before, not on go-live day. The 05:00 go-live is only the tracking switch. All the heavy lifting — import, configuration, first archive — happens the evening before.
When
What
Duration
Day-1, afternoon
Import + configuration + Tag Manager + rehearsal
≈ 4 h (incl. ≈1h45 import)
Day-1, evening
First full archive
several hours on a large history
Day, before 05:00
Tracking cutover
≈ 30 min
Phase A — Day before (Day-1)
This phase runs everything from Part 2, in order, ending with the first full archive. The steps that specifically belong to the day-before rehearsal:
A1–A2. Sanity gates. Containers are up (podman ps), and the image version is ≥ the dump’s version_core. If the image is older, stop here — core:update will refuse and nothing downstream matters.
A3–A8. Import and wire up. Detect the real dump format, derive the prefix, create the DB/user, verify the DB is empty, import (in tmux), verify the import and restore durability, write config.ini.php. (All detailed in Part 2.)
A9. core:update → expect « Everything is already up to date ».
A10. Tag Manager → activate, regenerate containers, confirm a 200.
A11. Inventory then disable scheduled reports — save the list first, because you’ll need it to re-enable exactly the same ones later:
$DB_EXEC="podman exec -i mariadb"
$DB_EXEC mariadb -u root -p"<ROOT_PWD>" matomo -e \
"SELECT idreport, idsite, login, description, period FROM report WHERE deleted = 0;" \
| tee /var/backups/matomo/active-reports.txt
$DB_EXEC mariadb -u root -p"<ROOT_PWD>" matomo -e \
"UPDATE report SET deleted = 1 WHERE deleted = 0;"
deleted is a reversible flag, not a real delete. Keep active-reports.txt — it’s the only record of which reports to bring back.
A12. Disable the GDPR purge during migration — to rule out any deletion concurrent with cutover:
$DB_EXEC mariadb -u root -p"<ROOT_PWD>" matomo -e \
"UPDATE \`option\` SET option_value='0' WHERE option_name='delete_logs_enable';"
$APP_EXEC ./console core:clear-caches
A13–A14. Configure geolocation (UI) and generate security files.
A15. Persistence test — do not skip this. This is the check that catches the silent volume trap before it costs you. Restart the app container and confirm everything survived:
If the config disappears or the container falls back to 404, the volumes are not persistent → stop and fix with your infra team before any cutover. This is the trap that breaks everything silently on the first container recreation.
A16. First full archive — the evening of Day-1. Run it manually, in tmux:
tmux new -s archive
time $APP_EXEC ./console core:archive --url=https://analytics.example.com
Expect it to end with Done archiving!. An exit code 1 alongside Done archiving! is normal here — it comes from a failed report send (no SMTP yet), not from an archiving failure. This must run the evening before; started on go-live morning it won’t finish in time and reports would be slow and incomplete when users log in.
A17. Functional rehearsal — walk the go/no-go checklist below.
The go / no-go checklist
Before cutover, confirm:
[ ] Image on the pinned build; core:version ≥ dump’s version_core.
[ ] core:update ran without error.
[ ] Superuser login works (Cloud credentials); 2FA works.
[ ] Historical data visible (a past period renders).
[ ] Site main_url values updated (no leftover Cloud URLs).
[ ] Geolocation active for new traffic.
[ ] Scheduled reports disabled, and the idreport list saved.
[ ] Single collation — the collation query returns exactly one row.
[ ] 🚨 Tag Manager active and containers served (curl → 200, not 404).
[ ] config.ini.php, plugins, GeoIP and js/container_*.js on persistent volumes — verified by restarting the container.
[ ] A test hit shows up in real time.
[ ] Archive timer active + first run OK.
[ ] Monitoring in place (timer failure, disk space).
Some items are deliberately not satisfied at cutover and that’s fine — track them, don’t tick them: SMTP not configured, scheduled reports disabled, premium plugins absent, GDPR purge disabled, restorable backup tested. They’re decisions, not failures. Never tick them « to look clean » — a successful core:test-email during rehearsal would mean SMTP is live, which means reports can go out, exactly what you’re avoiding.
Phase B — Go-live day, before 05:00 (~30 min window)
B1. Confirm the day-before archive finished.
B2. Re-check the Tag Manager container serves a 200 (rerun A10 if it’s 404).
B3. Switch the tracking — the irreversible move on the sites. First, separate your two populations, because they switch differently:
# Sites WITH a Tag Manager container -> switch the container URL
$DB_EXEC mariadb -u root -p"<ROOT_PWD>" matomo -e \
"SELECT s.idsite, s.name, c.idcontainer FROM \`site\` s
JOIN tagmanager_container c ON c.idsite = s.idsite AND c.status='active'
ORDER BY s.idsite;"
# Sites WITHOUT a container -> switch the classic tracking code
$DB_EXEC mariadb -u root -p"<ROOT_PWD>" matomo -e \
"SELECT idsite, name FROM \`site\`
WHERE idsite NOT IN (SELECT idsite FROM tagmanager_container WHERE status='active');"
Then, on the sites:
Update the classic tracking code (matomo.js / matomo.php URL) to analytics.example.com — the sites without a container first, and anywhere the snippet is hard-coded.
Update the Tag Manager container URL on the sites that use one.
Or switch DNS if you keep the same hostname — then no URL changes are needed.
« All sites are reporting » is not a sufficient check — it doesn’t prove the Tag-Manager-published sites are covered. Check the two populations separately in B4.
B4. Verify real-time collection, per population:
$DB_EXEC mariadb -u root -p"<ROOT_PWD>" matomo -e \
"SELECT s.idsite, s.name,
CASE WHEN c.idsite IS NULL THEN 'direct code' ELSE 'Tag Manager' END AS mode,
COUNT(v.idvisit) AS visits_30min
FROM \`site\` s
LEFT JOIN (SELECT DISTINCT idsite FROM tagmanager_container WHERE status='active') c
ON c.idsite = s.idsite
LEFT JOIN log_visit v ON v.idsite = s.idsite
AND v.visit_last_action_time > NOW() - INTERVAL 30 MINUTE
GROUP BY s.idsite, s.name, mode ORDER BY visits_30min ASC;"
If all Tag Manager sites are at 0 while direct-code sites report, the container isn’t served or the URL wasn’t switched → revisit B2/B3. A single site at 0 isn’t necessarily a failure — low-traffic sites at 5 AM legitimately show zero; compare to each site’s usual volume, not to zero.
B5. Verify real IPs — the reverse-proxy trap. Don’t rely on counting distinct IPs. Test against a known IP:
# 1) From the test machine, note its public IP:
curl -s https://ifconfig.me ; echo
# 2) Generate a visit from that machine on a tracked site.# 3) Confirm Matomo recorded THAT IP, not the proxy's:
$DB_EXEC mariadb -u root -p"<ROOT_PWD>" matomo -e \
"SELECT INET6_NTOA(location_ip) AS ip, COUNT(*) AS visits FROM log_visit \
WHERE visit_last_action_time > NOW() - INTERVAL 15 MINUTE \
GROUP BY location_ip ORDER BY visits DESC;"
The IP from step 1 must appear. If every visit carries the proxy IP (or an internal 10.x / 172.16-31.x / 192.168.x), the forwarded-for headers aren’t being applied → fix proxy_client_headers and core:clear-caches. Fix immediately — visits collected meanwhile are falsified and unrecoverable. The header name must match what your proxy actually sends (X-Forwarded-For usually, sometimes X-Real-IP).
Phase C — Right after cutover (H+0 to H+2)
C1. Watch real-time for ~1h; confirm all sites report.
C2. Enable scheduled archiving — on a container host, prefer a systemd timer over cron; it shares the container’s mode (rootful/rootless) and logging.
core:archive does more than archive. At the end of each run it triggers the scheduled tasks: emailing reports and the GDPR log purge. Without this timer, neither the reports nor the purge ever run. To trigger them in isolation: ./console scheduled-tasks:run.
C3. Inform users: new URL, unchanged credentials (passwords and 2FA migrated), email reports temporarily suspended, and any premium features currently unavailable.
Phase D — Stabilization (Day+1 to Day+7)
Order is imposed — do not invert it. Reports have been disabled since A11. Wire SMTP first (D1) so you can test it empty and safe, then re-enable reports (D2) knowingly. The reverse order — reports active before a working SMTP — blasts emails on the next archive run.
D1. SMTP — configure the relay, then validate empty:
$APP_EXEC ./console core:test-email
Expect the test email to arrive. Reports are still disabled, so no mass send is possible yet. If it fails, fix the relay before D2.
D2. Re-enable scheduled reports — only the ones saved in active-reports.txt, and only after D1 passes:
$DB_EXEC mariadb -u root -p"<ROOT_PWD>" matomo -e \
"UPDATE report SET deleted = 0 WHERE idreport IN ( /* ids from active-reports.txt */ );"
Never run a global UPDATE report SET deleted = 0 — it would resurrect reports that were intentionally deleted while on Cloud.
D3. Re-enable the GDPR purge:
$DB_EXEC mariadb -u root -p"<ROOT_PWD>" matomo -e \
"UPDATE \`option\` SET option_value='1' WHERE option_name='delete_logs_enable';"
$APP_EXEC ./console core:clear-caches
Leaving it off makes the database grow indefinitely and steps outside your declared retention — it’s a compliance control, not an optimization.
D4. Backups — set up database + application volume, and test a restore. The application volume matters: it holds config.ini.php, plugins and the GeoIP database — restoring only the database won’t bring the service back. A reference logical dump:
Rotate on a separate target. A backup that has never been restored is not a backup.
D5. Confirm durability is restored (SELECT @@innodb_flush_log_at_trx_commit; → 1).
D6. Cancel the Cloud subscription — point of no return. Only after: a conclusive observation period, a backup successfully restored at least once, and any needed export of the data gap (below).
The data gap — a decision to make explicitly
The dump is a snapshot at time T. Between the dump and the cutover, Cloud keeps collecting. A common, defensible decision is to accept the gap: don’t replay a final dump at go-live; the visits between the dump’s last data and the tracking switch stay only in Cloud and aren’t recovered on-premise.
Consequences to keep in mind:
✅ The cutover window stays short — no ~2h import to fit in, just switching tracking code / DNS.
✅ The pinned image stays valid (it matches the already-imported dump) — no version re-qualification.
⚠️ The gap grows over time — its size is the interval between the dump’s last data and the cutover date. The later the go-live, the longer the missing period. That’s the one argument for cutting over sooner rather than later.
💡 Cloud remains readable until cancellation — if the missing period ever needs analysis, export or consult it from Cloud before cancelling (D6 is the point of no return).
Rollback
As long as Cloud is not cancelled, rolling back is quick:
Restore the old tracking code and Cloud container URLs on the sites.
Confirm collection resumes on Cloud.
The on-premise instance can stay in place for analysis.
No on-premise data is lost — the imported database stays intact. Keep both the original dump and an on-premise backup before any destructive operation.
Part 2 — the full procedure: prepare MariaDB, inspect and import, wire up config.ini.php, core:update, and post-migration configuration.
Part 3 — timing and operations: the day-before / day-of / stabilization runbook, archiving, backups, GDPR, and rollback.
The recurring lesson across all three: the import is the easy part. What breaks a Matomo Cloud→self-hosted migration is everything the dump doesn’t carry — and the fact that most of it fails silently, well after the migration looks done.
An incident write-up, told from the inside: how the Miasma worm (a Mini Shai-Hulud variant) locked me out of my GitHub account, what I found pulling the thread, and the tools I had to write myself to clean up the mess. If you’d rather jump straight to the technical part, the TL;DR and the analysis sections (§3 onward) are further down.
How it all started
It was a Saturday. I was on the floor playing with my kids when my phone buzzed: an email from GitHub telling me that my password had just been changed. Not by me.
Reflex: I try to log in. Password rejected. Okay. I kick off the email recovery flow… and nothing arrives. For a good reason I’d only understand later: the attacker had also changed my recovery email address. At that exact moment, I’m locked out of everything and all my projects live on that account.
I open a ticket with GitHub support. The day after : no response. On reddit, I read that recovery normally takes about 5 days. Five days without my account is like an eternity for IT people !
First lesson learned the hard way: thankfully, Git is decentralized. My local clones held the latest version of everything, so I could re-upload them to a new account while I waited for the old one to come back. Back up, contain but without making things worse.
That left the real question: where did the breach come from?
I dig out an old laptop I barely ever use, open one of my repos (a personal project, a friend of mine asked me the code for his own personal project, thanks to him I found the culprit) … and there it is : a commit I never made, tagged [skip ci]. A folder .gemini and .cursor for AI CLI I’m not using. So I open the files it brought in. One of them is a .js, and the moment I open it I get it: this is encrypted execution code, code that is actively trying to hide itself. A few minutes later, Windows Defender lights up and points straight at that file: virus detected .
The penny drops. I’d just understood why I was locked out: somewhere, a GitHub PAT must have been sitting in an uncommitted file (a .env, or something like it), and the worm had scooped it up. With that token, it owned my account : password, recovery email, the lot. The Github security log was clear : just before Github suspended my account, a lots of PAT were emitted and strange activities were send. Hopefully, Github suspended my account just before it strikes all my repos.
After that, I did what any dev does at hour zero of a lockout: I searched. How does this worm work? How bad is it, really, for my repos and my machine? I found a few references that confirmed what I was already reverse-engineering but no automated tooling to clean up a machine or a fleet of repos. So I got to it: writing my own scripts to sanitize the machine and the repositories, working from the sound assumption that every secret and the machine itself stay compromised no matter what. You back up, you contain, and above all you don’t make it worse.
What follows is the full autopsy of what I found pulling that thread: how the attack gets in and runs, the payload deobfuscated layer by layer, the indicators of compromise, and the eradication procedure aka the one « I wish I’d found ready-made that Saturday ».
Note : no client repositories were impacted (GH migration is planned in 3 months – lucky me) and no code source extraction before the automatic lockout by Github (no entry in the security and activity log – confirmed later by github).
TL;DR or « If you have sometime to spend, here’s how it works and do those best practise starting now »
Entry vector: a forged commit (spoofing the owner’s GitHub email, unsigned, [skip ci]) from a malicious npm dependance (identification in progress) adds a .github/setup.js dropper (~4.6 MB, multi-layer encrypted) plus auto-executed launchers in .claude/, .gemini/, .cursor/, .vscode/ and package.json.
Execution: simply opening the repo in an AI agent / VS Code triggers a hook that runs node .github/setup.js, which decrypts and runs an infostealer via the Bun runtime (to evade Node.js monitoring).
Impact: theft of GitHub/npm tokens, cloud credentials (AWS/GCP/Azure), SSH/private keys, passwords, then self-propagation to the account’s other repos via the GitHub API, plus abuse of GitHub Actions (secrets, self-hosted runners).
Eradication: disarm hooks → delete files → purge git history + force-push → clean Bun artifacts → rotate ALL secrets → scan machine + every repo.
1. Context — Miasma / Shai-Hulud
First thing I wanted to know once the panic wore off: who am I dealing with? A name on a file tells you next to nothing; but understanding a malware’s family tells you what it’s after, how it spreads, and therefore how far it could have gotten on my side.
Miasma is a variant of the Shai-Hulud lineage (« Mini Shai-Hulud »), a family of supply-chain worms that spread across npm and GitHub in mid-2026. This wave’s twist — and the thing that made me uneasy, given that I live in Claude Code and Cursor all day: it targets AI coding-agent configurations, abusing the fact that these tools auto-execute hooks/tasks defined inside the repository. In other words, the trap doesn’t spring when you run a build, it springs when you open the folder.
First seen: ~June 3-4, 2026 (UTC).
Documented scope: dozens of public repos (incl. popular projects and ~73 Microsoft repos disabled by GitHub within ~105 s), 57 npm packages / 286+ versions on the « registry arm ».
Exfiltration (« dead-drop ») accounts: windy629, liuende501, HerGomUli — repos described « Miasma – The Spreading Blight » / « Hades – The End for the Damned ».
2. Infection chain — how it gets in and runs
Back to that commit I never made, the one that jumped out at me on my old laptop. Taking it apart, I reconstructed the whole mechanism: a commit dressed up to slip by unnoticed, dropping a payload and a handful of triggers waiting for one thing — for me to open the repo. Here, piece by piece, is what I found (and read on this topic).
2.1 The forged commit (entry)
The worm pushes a disguised commit. In the analyzed case / mine:
Email differs from the usual git identity (here ~109 real commits use [email protected]). The worm uses the GitHub profile email.
[skip ci] to dodge CI/scrutiny.
Timestamp copied from the real merge to blend in.
Unsigned (real GitHub merges are signed).
Other waves: author github-actions <[email protected]> (message chore: update dependencies [skip ci]), or a real contributor via a stolen PAT (backdated commit). → The reliable detection is NOT the email/message but « a commit that adds .github/setup.js« .
2.2 The 6 auto-execution vectors
The commit injects the dropper and launchers that run without user action:
purge-history.sh : git-history purge (git filter-repo → git filter-branch) of the worm’s standalone files: automatic backup bundle, ref cleanup + GC, force-push left manual, .setup-js.yar (YARA) rules for the dropper and launchers.
Expand-MiasmaPayload.ps1 : static deobfuscator of the dropper, READ-ONLY (never executes the payload): unpacks the packerp,a,c,k,e,d wave → decodes the char codes wave => detects/reverses the Caesar shift => decrypts each AES-128-GCM blob (_b bootstrapper, _p infostealer) => extracts URLs / IPs / « dead-drop » accounts. Writes each layer to <Path>.deob/; -SelfTest validates the engine.
CI integration : reusable composite action .github/actions/miasma-guard (« refuse to build if .github/setup.js present »): fails the build if the dropper or a launcher that runs it is present. Wave-agnostic, scoped to launcher config files (no false positives on docs). full-scan option to additionally run Scan-Miasma.ps1 -Mode Local.
scan-miasma.sh : bash port of the local scan (Linux/macOS): cross-platform subset (injected configs, payload, Bun artifacts, compromised npm deps, signatures, git history, runners, cron/systemd persistence).
Invoke-MiasmaRotation.ps1 : post-eradication secret-rotation checklist, READ-ONLY (revokes nothing): detects which credentials are reachable from the machine and prints prioritized revoke commands.
Quick « before opening an untrusted repo » check:
test -f .github/setup.js && echo "DROPPER PRESENT — DO NOT OPEN"
grep -rn "node .github/setup.js" .claude .gemini .cursor .vscode package.json Gemfile 2>/dev/null
7. Eradication — step by step
Principle: disarm first (cut execution), clean next, treat the machine and all secrets
as compromised.
Do not re-open the repo in an AI agent / VS Code until cleaned. Do not run npm test.
Do not git checkout/restoresetup.js (re-arms it).
Disarm the hooks: empty .claude/settings.json / .gemini/settings.json (=> {}), remove .cursor/rules/setup.mdc, .vscode/tasks.json, drop the injected test script.
Delete the payload: .github/setup.js (commit the removal of all 6 vectors).
Purge git history (the file is otherwise recoverable by SHA):
Rotate ALL secrets reachable from the machine (the stealer ran): GitHub PAT first, npm/NuGet tokens, AWS/GCP/Azure credentials, SSH/GPG keys, browser passwords, Vault/K8s tokens.
Audit the GitHub account: Security log (find the forged-commit push => culprit token/IP), revoke PATs / OAuth apps / GitHub Apps / deploy keys, purge Actions secrets (repo + org), remove any unknown SSH/GPG keys.
Scan ALL repos (local and remote — the worm spreads) with the scripts, and clean every infected repo the same way.
Full antivirus scan of the machine (note the detection name).
8. Hardening / lessons
Sign your commits (and enable branch protection « require signed commits »): makes the unsigned forged commit immediately visible/blockable.
