DEV Community: Sergei Strebulaev

The Project I Inherited Had No Memory Either

Sergei Strebulaev — Wed, 09 Sep 2026 14:57:35 +0000

My teammate joined the project on a Tuesday. By Wednesday she asked
the question every new hire eventually asks: "Why is auth handled in
three different places?"

I didn't have a good answer — just a fuzzy memory of a decision made
months earlier, in a call nobody wrote down. That's the same problem
I wrote about last time — an AI agent with no memory of what we'd
already decided. Turns out it's not just an AI problem; a team
forgets too. Most real projects aren't a clean slate. Here's what
fixing that actually looks like on one that already has history.

Retrofitting memory onto an existing project

bootstrap has two modes. Fresh-project mode creates
docs/{facts,decisions,guardrails,skills}/ from nothing. Gap-fill mode
is for a project that already has some of that, inconsistent and
incomplete:

/kms:bootstrap

That's Claude Code. Codex reads the same skill set through its own
plugin manifest. Kilo Code CLI reads it too once kilo.jsonc points
at the published skills manifest.

It found our existing docs/decisions/ folder and extended it instead
of replacing it. Then it scanned git history and existing docs for
decision language — a DECISION: marker, a "because we need to" — and
came back with draft stubs (id, title, a first-pass motivation,
status: draft) for decisions I'd genuinely forgotten were decisions
at all — not the full rationale, that's still ours to write, but a
real starting point instead of a blank page. The auth-in-three-places
thing was one of them.

It also flagged two guardrail files missing the field recording which
decision they came from — not silently, and not by guessing: each got
logged as undeclared debt with a proposed likely source, turning an
archaeology project into a five-minute confirmation.

A role-tailored ramp-up, not a wiki page

Once the knowledge base had real content, I pointed my teammate at:

/kms:onboard

First question back: which role was she ramping up as. Not guessed —
a backend-leaning plan and a frontend one pull from almost entirely
different decisions and guardrails. What came back was 5 days, each
with a goal, specific artifacts to read (real paths, not "the
decisions folder"), and a skill to run:

Day	Focus
1	Highest-level facts, most consequential decisions
2	Role-specific decisions and guardrails — what not to violate, and why
3	Role-specific facts, current state
4	First real task; `query` for anything unclear
5	Practice a decision with `clarify`; `capture` afterward

It also told her the truth: our facts directory was still thin, so the
plan opened with a plain warning that it was built on an incomplete
base. A wiki page doesn't flag its own staleness. This did.

Planning the refactor I'd been avoiding

The auth question turned into a real refactor — the kind I'd normally
put off because nobody could tell me what it'd break:

/kms:refactor-plan

Phase 1 searched the knowledge base and found two relevant artifacts:
the (now-recorded) decision that split auth in the first place, and a
session-handling guardrail I'd forgotten existed. Phase 2 mapped call
sites and config by reading the code directly — no dependency on any
other skill running first. Phase 3 came back with ordered phases, each
carrying concrete steps, a verification checkpoint, and a rollback
strategy specific to that phase, not "revert everything."

One planned step would've quietly violated the session-handling
guardrail. It wasn't dropped and it wasn't silently worked around — it
was flagged, cited by path, with an explicit ask to confirm before it
stayed in the plan.

What this doesn't do

onboard won't write the facts and decisions that don't exist yet —
that's bootstrap's job, run first. refactor-plan won't tell you a
refactor is worth doing, only what it'll cost and what could break;
if the knowledge base has nothing relevant to what you're touching, it
says so plainly instead of inventing a concern to sound thorough.
Neither replaces the actual conversation with your teammate.

And if kms isn't for you later, uninstall finds everything it added
— seeded guardrails, generated files like the doc manifest, the marker
block in your agent instructions — and asks about each one
individually: detach
(keep the content, stop tracking it as kms's) or remove. Same
confirm-first discipline as every other kms skill, including this one.
Nothing about adopting kms locks you in, and this piece exists partly
to prove that's not just a claim in the README.

Try it

If this is useful, a star helps other developers find it:

⭐ Star vivantel/kms on GitHub

/plugin marketplace add vivantel/kms
/plugin install kms

If your project already has some history — an incomplete
decisions/ folder, a wiki nobody trusts — run /kms:bootstrap on it
before assuming you have to start clean. That's the case it's built
for.

Contributions welcome — see
CONTRIBUTING.md
for how to propose new skills or improve existing ones.

Two Kinds of Memory

Sergei Strebulaev — Mon, 07 Sep 2026 19:16:59 +0000

I asked my AI agent where the retry logic lived. Four seconds later:
three files, one shared helper, a comment linking to a Slack thread
that doesn't exist anymore. Found it cleanly.

Then I asked why the retry count was capped at three instead of five.
Silence, then a guess. It could find the code. It had no idea why the
code said what it said.

Two failures wearing the same complaint — "the AI doesn't know this
project." One's a search problem. The other's a memory problem. I'd
already fixed the memory one; that's what this whole series has been
about. The search problem needed a genuinely different tool.

What kms doesn't do

kms retrieves what's been captured as decisions, facts, and guardrails — curated, citable, checkable. query answers "why does this work this way" with a real citation because the answer was captured on purpose.

But kms also has skills that discover knowledge implicitly: bootstrap extracts intents from git history and facts from existing docs; capture flags contradictions and drift after every work session; roadmap interviews a plan and captures every implicit presupposition as a durable record. None of those require someone to have written it down beforehand — they find what's already there in history, code, and conversation.

What kms doesn't have is semantic search across the raw codebase. Most of a codebase isn't a captured decision, though. It's just code — functions, old comments, a README paragraph, a PR nobody formalized because it never rose to that level. kms has nothing to say about any of it unless a skill captured it. Not broken. Never the job.

What virage does instead

virage is a separate vivantel tool for exactly that gap — a
git-aware pipeline that turns a codebase and its docs into a
searchable vector index.

virage init
virage index
virage query "how does authentication work?"

init writes virage.config.json via an interactive wizard. index
chunks the repo — AST-aware, so a function stays one semantic unit
instead of getting sliced at an arbitrary line count — and embeds it.
query searches by meaning, not keyword: ask about authentication and
it finds the relevant code even if that word never appears in it —
something grep structurally can't do.

Every stage is swappable: an OpenAI-compatible embedder or a fully
local ONNX model, an embedded file-based vector store for a solo repo
or Postgres/Qdrant for a team, an optional reranker on top. Same CLI
regardless of what's behind it.

Why not one tool that claims to do both

"AI memory" tools promising a single system for this exist — Mem0,
Letta, Cognee, and similar. They solve a third, different problem: raw
recall of accumulated facts or conversation history, closer to
virage's mechanism than kms's, but aimed at remembering what happened,
not retrieving a curated decision a human stood behind. None separate
"a fact" from "a commitment the team made" the way kms does, and none
are built for a git repo's own structure the way virage is.

Same auth mess, two different tools

An earlier piece in this project's kms series described a real mess:
auth split across three places, nobody could say why.

virage index finds all three in seconds — every file touching auth,
ranked by relevance, whether or not "auth" shows up in a variable
name. Search problem, solved.

It can't tell you why it's split three ways. That answer, if it
exists, lives in a decision someone wrote down — the kind
bootstrap's gap-fill mode goes looking for, or query retrieves
with a citation once it's captured. virage has no opinion on that
question. Never asked one.

Neither tool is weaker — they answer different questions, where is
this and why is it this way. Conflating them is how a team ends up
re-grepping the same code every time, or re-deciding the same question
every time.

Using both without confusing what each is for

virage query for "where"/"what" questions. kms query for "why"
questions. They're two separate tools today, not one integrated
system — running virage doesn't feed kms's decisions, and vice
versa. Worth saying plainly rather than implying a seamlessness that
isn't there. What they share is a practice, not a product: don't let
either kind of memory live only in someone's head.

Try it

If this is useful, a star helps other developers find both:

⭐ Star vivantel/kms ·
⭐ Star vivantel/virage

/plugin marketplace add vivantel/kms
/plugin install kms

That's Claude Code. Codex reads the same skill set through its own
plugin manifest. Kilo Code CLI reads it too, once kilo.jsonc points
at the published skills manifest.

npm install -g @vivantel/virage
virage init

Claude Code again first, via virage's own agent plugin. GitHub Copilot
reads the same index through its own agent plugin. Codex reads it
through its own agent plugin. Antigravity reads it through its own
integration.

If you already run kms, virage index on the same repo takes about a
minute and costs nothing to try. If you run neither yet, start with
whichever question you actually have: something you can't find, or
something you can't explain.

Contributions welcome on both —
kms,
virage.

Building a Terraform Provider for Paddle Billing: Why Real-Sandbox Testing Matters

Sergei Strebulaev — Sat, 05 Sep 2026 06:08:59 +0000

We manage our whole infrastructure as code, and wanted our Paddle Billing catalog — products, prices, discounts, webhook config — to work the same way instead of being the one thing still managed by hand through a dashboard. Existing tooling didn't cover enough of what we actually needed, lifecycle actions for subscriptions and refunds especially, so we built our own.

terraform-provider-paddle manages Paddle Billing's catalog — products, prices, discounts, discount groups, notification settings — plus six lifecycle actions (refunds/credits, subscription cancel/pause/resume/charge, notification replay), lookup data sources for subscriptions/transactions/customers/events, and a couple of newer Terraform capabilities: an ephemeral resource for a webhook secret that never touches state, and resource identity + list-block support for bulk-discovering existing infrastructure via terraform query.

This post isn't a feature tour, though — it's about one specific decision that shaped how the whole thing got built: every resource and data source is verified end-to-end against Paddle's real sandbox API before each release, not just tested against mocks. Here's a real bug from that process that explains why.

The problem with mocking someone else's API

Every API client eventually encodes assumptions about the wire format — what fields exist, what shape they're nested in, what a status value actually means. When those assumptions are right, mocks are great: fast, free, deterministic, no network flakiness. When they're wrong, a hand-written mock just encodes the same wrong assumption and "confirms" it forever. A test suite built entirely on mocks can be green for months while quietly testing the wrong thing.

Here's a concrete example. A transaction's line items don't carry a flat price_id field — Paddle nests a full price object under each line item, and the ID you actually want is price.id. A mock built around the flat-field assumption would have exercised the same code path, returned a plausible-looking response, and passed — while the real code silently compared against an empty string every time it ran against the real API.

The fix wasn't just correcting that one field. Paddle publishes a proper machine-readable OpenAPI spec for their whole API, auto-generated from their own backend whenever it changes — so this provider now vendors a copy of it and runs a forward-only contract check on every test run: for every field a client struct actually reads or writes, does that field still exist in Paddle's real API, at the same nested path, with a structurally compatible shape? It's deliberately one-directional — the provider intentionally leaves plenty of Paddle's API surface unmodeled, so checking "does the provider cover everything Paddle has" would just flag every deliberate scope decision as false-positive drift. Checking "does what the provider does model still match the spec" is the direction that actually matches the bug history.

Newer Terraform features, and why they showed up here

Ephemeral resources. A webhook signing secret is real, sensitive data that's genuinely needed at apply time — but there's no reason it should sit in a state file forever. Sensitive: true on a schema attribute only redacts CLI/log output; it does nothing to state itself, which still stores the real value in plaintext. This provider added an ephemeral resource specifically so that secret can be fetched fresh on every apply and never written to state at all, while keeping the old (now-deprecated, still fully working) attribute in place for anyone already depending on it.

Resource identity + list resources. terraform query (Terraform 1.14+) turns out to hard-depend on resource identity being implemented on the target resource first — a list result's identity is required, and it's built from that schema. Once that's wired up for a resource, bulk-discovering everything of that type already sitting in a Paddle account — and generating import config for it — becomes a first-class Terraform workflow instead of something you'd have to script by hand against the raw API.

Try it

Terraform Registry: registry.terraform.io/providers/vivantel/paddle
Repo: github.com/vivantel/terraform-provider-paddle

Feedback and issues welcome — especially anywhere the schema doesn't match real Paddle behavior. That's exactly the kind of thing this whole approach is built to catch, and it's more reliable with more real accounts exercising it.

My AI Keeps Forgetting What We Already Decided

Sergei Strebulaev — Thu, 03 Sep 2026 22:41:57 +0000

Every week I re-explain the same architecture choices to my AI coding
agent. New session, zero memory — like we never talked. That's not a
prompting problem, it's a memory problem, and I fixed it with a
git-based knowledge system that lives right next to the code. Here's
the actual walkthrough, the schema it writes, and where it falls
short — not just the pitch.

The problem in one sentence

I plan a feature with Claude Code on Tuesday. Wednesday, fresh
session: "Where did we leave off?" No idea. I re-explain everything.
By Thursday I've explained it a third time to a different agent. Each
one asks good questions, gets a good answer, and forgets it the moment
the session ends. The plan was never the problem — nothing durable
ever got written down, so there was nothing for the next session to
read.

What I built: kms

kms is a Claude Code plugin that captures decisions, facts, and
guardrails as plain markdown files, version-controlled right alongside
your code. Any agent that reads the repo reads the knowledge base
first, before it asks you anything.

Install:

/plugin marketplace add vivantel/kms
/plugin install kms

Four artifact types, each with one job:

Type	Answers	Lives in
Fact	What's true right now	`docs/facts/`
Decision	What you're committing to, and why	`docs/decisions/`
Guardrail	What must (or must not) happen, derived from a decision	`docs/guardrails/`
Skill	How to act on all of the above	`docs/skills/`

Walkthrough: capturing your first decision

One command:

/kms:quickstart

If docs/{facts,decisions,guardrails,skills}/ doesn't exist yet,
quickstart sets it up first. Then it asks one direct question:
"What decision or plan is currently live for you right now?"

Mine was the multi-platform content strategy I'd re-explained three
times that week — which platforms, what cadence, what CTA on each.
Quickstart interviews you — what's changing, why, what stays fixed —
then writes the result to
docs/decisions/0002-content-multi-platform-strategy.md:

---
id: 0002-content-multi-platform-strategy
title: Multi-platform content strategy for kms outreach
status: accepted
date: 2026-08-31
tags: [kms, content, outreach, platforms, multi-channel]
track: product
scope: All public articles produced in kms_content
---

## Decision

kms public articles expand beyond Medium to Dev.to and Hashnode.
Medium stays canonical; the others get manually adapted copies. Weekly
cadence. Platform-specific primary CTAs — Medium leads with install,
Dev.to with GitHub stars, Hashnode with newsletter signup — rather
than one CTA everywhere.

## Rationale

...

Nothing gets summarized or paraphrased away — that's your call,
captured once, in your own words. The session closes by naming what to
run next, not leaving you to guess: query to pull this decision back
up later with a citation, capture after the next session that
touches it.

From that point on, Claude Code
reads that file the next time it opens the repo and knows exactly
what was decided. Codex reads the same skill set through its own
plugin manifest. Kilo Code CLI reads it too, once kilo.jsonc points
at the published skills manifest.

Beyond decisions

Facts and guardrails link back to why they exist, not just what they
say. Say you decide Medium posts close with an install CTA, Dev.to
posts close with a GitHub-stars ask. That's a decision. The guardrail
that enforces it on every article cites that decision by id. A skill
that tells you how to adapt a draft per platform references the
guardrail. Change the decision later, and capture/lint catch the
guardrail and skill silently drifting out of sync with it — instead
of you finding out three articles later.

Commands worth knowing once you've got a knowledge base going:

query — retrieve a past decision with a citation, instead of re-explaining it.
capture — log what a work session changed, after the fact; flags contradictions it finds along the way.
lint — validate the whole knowledge base on demand: dangling references, missing fields, stale derived artifacts.
brainstorm — generate fresh approaches with no anchor to past decisions, for exploring before anything's locked in.
onboard — a role-tailored, 5-day ramp-up plan for a new teammate, built from the existing knowledge base.
conform — check whether a pending change respects the guardrails before it lands.

What this doesn't solve

It's not magic memory — you still write the interview answers
yourself; quickstart just makes sure they get written down instead of
staying in your head. It doesn't replace tests, code review, or
actual documentation for end users. And it only helps if the habit
sticks — a knowledge base nobody updates after month one is just a
docs/ folder with extra steps. The parts that make that less likely
are capture (so updating it is a five-minute pass after a session,
not a separate chore) and lint (so drift gets caught instead of
silently rotting).

Why this beats a context file you paste in

I've tried system prompts, paste-in context files, separate
note-taking apps I'd open in another window. They all fail the same
way: they live outside the repo, so they don't survive a fresh
session, and they rely on you remembering to open them, paste them in,
and keep them updated. This is different because it's part of the
repository — every decision is version-controlled, every fact is
verified, and a guardrail is derived from a real commitment instead of
vibes. When the project changes, the knowledge base changes with it,
in the same commit history as the code.

Try it

If this is useful to you, a star helps other developers find it:

⭐ Star vivantel/kms on GitHub

Then install the plugin and run /kms:quickstart on one real decision
that's been living in your head. You'll never explain it twice.

Contributions welcome — see
CONTRIBUTING.md
for how to propose new skills or improve existing ones.