DEV Community

Cover image for My AI coding agents kept forgetting why they did things — so I built them a shared memory
fagugon283
fagugon283

Posted on Edited on

My AI coding agents kept forgetting why they did things — so I built them a shared memory

#ai #opensource #productivity #mcp

If you code with AI agents — Claude Code, Cursor, Codex, Copilot — you've probably hit these two walls:

  1. Every session starts from zero. The agent has no idea what happened yesterday, what you already decided, or what it was in the middle of.
  2. The why evaporates. Three months later you stare at a function and have no clue why it's built that way. The reasoning lived in a chat that's gone.

We solved "where does the code live" with git decades ago. We never solved "where does the reasoning live" — and now that agents generate the code, that gap hurts more than ever.

So I built rational-agnostic: a small, vendor-neutral layer that lives inside your repo as plain markdown files. No SaaS, no account, no database.

What it actually does

  • Decisions. Every non-trivial choice is recorded ADR-style (context / decision / why / consequences). One file per decision, git-diffable.
  • Traceability. Functions get a // @why: D-ab12cd tag. You can take any function, hash its body, and jump straight to the decision behind it — and detect drift when the body later changes.
  • Shared memory + task state. Agents of any vendor read and write the same context, so Cursor picks up where Claude Code left off instead of starting cold.
  • Token-aware retrieval. get_context hands the agent only the relevant slice within a token budget, instead of dumping the whole history.

Everything is persisted in English and in markdown, so it stays portable, searchable, reviewable in PRs, and diffable in git.

Zero-config for every agent

Each AI client reads a different file for MCP config and project instructions. So init writes (and safely merges into) the right file for each one:

Agent MCP config Instructions
Claude Code .mcp.json CLAUDE.md
Cursor .cursor/mcp.json AGENTS.md
Codex .codex/config.toml AGENTS.md
Gemini CLI .gemini/settings.json GEMINI.md
Copilot .vscode/mcp.json .github/copilot-instructions.md 
npx rational-agnostic init
Enter fullscreen mode Exit fullscreen mode

Open any of those agents in the repo and the MCP server + protocol are already wired. The CLI works with zero MCP setup too — every operation is also a command.

Already have a codebase?

Don't start from a blank slate. adopt inventories the project (languages, manifests, entry points, largest files) and lays out an onboarding plan:

rational-agnostic init
rational-agnostic adopt          # read-only inventory + plan
rational-agnostic adopt --write  # baseline decision + adoption task
Enter fullscreen mode Exit fullscreen mode

Legacy untagged code is fine — verify only flags @why tags pointing to a missing decision, never existing code. And a core rule: never invent rationale. If the agent can't tell why something exists, it asks instead of fabricating.

Boring on purpose (the good kind)

  • MIT, zero native dependencies, npm audit clean.
  • The optional local-embedding model is opt-in; by default it uses a dependency-free lexical embedder, so there's nothing to download and no native build at install time.
  • The vector index is just a rebuildable cache — the markdown files are always the source of truth.

Try it 

npm i -g rational-agnostic
cd your-repo && rational-agnostic init
Enter fullscreen mode Exit fullscreen mode

👉 npm: https://www.npmjs.com/package/rational-agnostic

I'd genuinely love feedback — especially on whether the @why → decision traceability is useful in your workflow or overkill. What do you do today to keep your AI agents from forgetting context?

Top comments (0)