# My AI Keeps Forgetting What We Already Decided

> Source: <https://dev.to/sergemso/my-ai-keeps-forgetting-what-we-already-decided-4okd>
> Published: 2026-09-03 22:41:57+00:00

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.

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.

`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/` |

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?"*

Say you're picking an auth provider. Quickstart interviews you — what

you're choosing, why, what would make this wrong — then writes the

result to `docs/decisions/0001-auth-provider-choice.md`

:

```
---
id: 0001-auth-provider-choice
title: Use Auth0 for user authentication
status: accepted
date: 2026-09-03
tags: [auth, infra]
track: product
---

## Decision

Auth0 for all user-facing auth. Rejected rolling our own — team of
two, no time to own session security. Rejected Firebase Auth — we're
not on the rest of the Firebase stack and didn't want the lock-in.

## 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.

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.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).

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.

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

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](https://github.com/vivantel/kms/blob/main/CONTRIBUTING.md)

for how to propose new skills or improve existing ones.