Provides a vendor-agnostic governance and traceability layer for AI coding agents to record decisions, track tasks, and share memory.
Also known as fagugon283/rational, rational
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.7
- Last commit
- Nov 10, 2026
- License
- MIT
What is rational-agnostic MCP?
rational-agnostic provides a vendor-agnostic governance and traceability layer for AI coding agents to record decisions, track tasks, and share memory.
Summary generated from the project's README
About rational-agnostic MCP server
rational-agnostic provides a file-based governance and traceability layer designed for AI coding agents. It functions as a shared, durable record that sits above various agent frameworks like Claude Code, Cursor, Copilot, and Gemini CLI. By using this system, developers can ensure that different AI tools maintain a consistent understanding of project decisions, task states, and shared memory across different sessions.
The server operates locally using a file-based approach where all knowledge is persisted in English markdown files. It includes a zero-config wiring process that automatically updates configuration files for major agents. Users can interact with it via a CLI or through MCP-capable agents using 22 specific tools such as record_decision, tag_code, and get_context. The system supports semantic search using a built-in lexical embedder, with an optional local transformer model for higher quality retrieval without requiring external API keys.
What you can do with it
- 1Documenting architectural decisionsAn agent can record the reasoning behind a specific technical choice to create a permanent ADR-style record.
- 2Linking code to rationaleDevelopers can use tags to connect specific functions to the decisions that justified their implementation.
- 3Optimizing context for agentsAn AI client can retrieve a minimal set of relevant information that fits within a specific token limit.
Written from the project's README. Every use case is checked against a quote from it.
How to install rational-agnostic MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall rational-agnostic MCP in Claude Code
$ claude mcp add rational -- npx -y rational-agnosticInstall rational-agnostic MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"rational": {
"command": "npx",
"args": [
"-y",
"rational-agnostic"
]
}
}
}Install rational-agnostic MCP in VS Code
.vscode/mcp.json
{
"servers": {
"rational": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"rational-agnostic"
]
}
}
}Install rational-agnostic MCP in VS Code CLI
$ code --add-mcp '{"name":"rational","type":"stdio","command":"npx","args":["-y","rational-agnostic"]}'Install rational-agnostic MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"rational": {
"command": "npx",
"args": [
"-y",
"rational-agnostic"
]
}
}
}Install rational-agnostic MCP in Codex
$ codex mcp add rational -- npx -y rational-agnosticInstall rational-agnostic MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.rational] command = "npx" args = ["-y", "rational-agnostic"]
Install rational-agnostic MCP in Gemini CLI
$ gemini mcp add -s user rational npx -- -y rational-agnosticInstall rational-agnostic MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"rational": {
"command": "npx",
"args": [
"-y",
"rational-agnostic"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablefagugon283/rational is public and reachablegithub.com/fagugon283/rational ↗Pass
- Package names this repository as its sourcerational-agnostic names fagugon283/rational as sourcenpmjs.com/package/rational-agnostic ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/fagugon283/rational ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from rational-agnosticPass
- No critical advisory in the package or its dependencies114 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubrational-agnostic
A vendor-agnostic, file-based governance & traceability layer for AI coding agents.
rational-agnostic sits above any agent framework (Claude Code, Codex, Cursor,
Copilot, Jules, …). It is the shared, durable record that agents of any vendor
read from and write to:
- 🧠 Decisions — every non-trivial choice is recorded as an ADR-style file explaining why (in English).
- 🔗 Traceability — every generated function carries a
// @why: D-xxxxtag; you can take a function, hash it, and find the decision behind it. - 🤝 Shared memory — a cross-vendor meeting point so agents don't lose context between sessions or between each other.
- ✅ Task state — one file per task + a status board, so everyone knows what's
doing,blockedordone. - 📚 Learnings — the system distills recurring patterns from past decisions and code, and keeps improving.
- 🎯 Token-aware context —
get_contextreturns a minimal relevant bundle within a token budget, instead of dumping history.
Everything is persisted in English, even when the user works in another language, so the knowledge base stays portable, searchable and diffable.
Design principle:
AGENTS.mddescribes how the system is structured and used — never what your project is about. Project rationale lives in the decision records.
Install
npm install -g rational-agnostic # or: npx rational-agnostic <command>
Quickstart
Every project starts with init, which scaffolds AGENTS.md, the
.rational-agnostic/ store, and wires every major AI agent (see
Zero-config agent wiring):
cd your-repo
rational-agnostic init # creates AGENTS.md + .rational-agnostic/
Already have a codebase? Run adopt (brownfield)
If the repo already had code before rational-agnostic, don't start from a blank slate — have it inventory what exists and lay out an onboarding plan. This is the recommended path for any non-empty project:
rational-agnostic init # 1. scaffold (adopt needs this first)
rational-agnostic adopt # 2. read-only inventory + plan:
# languages, manifests, entry points,
# largest/most-central files, tag coverage
rational-agnostic adopt --write # 3. persist an "as-built" baseline decision,
# open an adoption task, post a brief to
# shared memory — then point your agent here
Nothing breaks on day one: existing untagged code is allowed (verify only
flags @why tags that point to a missing decision, never legacy code). From
there you work the plan incrementally — largest/most central modules first —
recording a decision and tagging the code for each design choice you can infer.
Never invent rationale: if you can't tell why something exists, ask (append a
question to shared memory) instead of fabricating a decision.
MCP-capable agents have the same two steps as the
adopt_reportandstart_adoptiontools.
Record a decision and tag the code
Record a decision and tag the code it justifies:
rational-agnostic decision add \
--title "Use JWT for auth" \
--summary "Chose JWT over sessions for stateless scaling" \
--context "API must scale horizontally without sticky sessions" \
--decision "Short-lived JWT access tokens + refresh tokens" \
--why "Stateless tokens avoid shared session storage" \
--author agent:anthropic:claude-code --tags auth,security
# -> Created D-ea3ec7 — tag code with: // @why: D-ea3ec7
// @why: D-ea3ec7
function issueToken(user) { /* ... */ }
Find why a function exists — by location or by hash:
rational-agnostic why src/auth.js issueToken
printf '%s' "$(cat the-body)" | rational-agnostic hash # -> sha256
rational-agnostic why --hash <sha256>
Gate your commits with traceability:
rational-agnostic init --hook # installs a pre-commit `verify` gate
rational-agnostic verify # exit 1 on orphan tags / bad task status
Zero-config agent wiring
init doesn't just scaffold the data store — it wires every major AI agent for
you, so whoever runs npx rational-agnostic init gets a ready-to-use setup with
no manual MCP configuration. It generates (and safely merges into, never
clobbers) the file each client actually reads:
| Agent | MCP config written | Instructions file |
|---|---|---|
| Claude Code | .mcp.json (auto-discovered) |
CLAUDE.md → AGENTS.md |
| Cursor | .cursor/mcp.json |
AGENTS.md |
| Codex | .codex/config.toml |
AGENTS.md |
| Gemini CLI | .gemini/settings.json |
GEMINI.md → AGENTS.md |
| Copilot | .vscode/mcp.json |
.github/copilot-instructions.md → AGENTS.md |
Open any of those agents in the repo and the MCP server + protocol are already in
place (restart the client once to load MCP; approve/trust it if prompted). Opt out
with rational-agnostic init --no-mcp.
The CLI needs none of this — every operation is also a command, so any agent
can use rational-agnostic with zero setup by running npx rational-agnostic …
straight from AGENTS.md. MCP is just a more token-efficient interface on top.
Connect an AI agent (MCP) manually
If a client wasn't auto-wired, add this stdio server to its config:
{
"mcpServers": {
"rational-agnostic": { "command": "npx", "args": ["-y", "rational-agnostic", "mcp"] }
}
}
The agent then sees 22 tools — get_context, search, record_decision,
tag_code, create_task, set_task_status, read_memory, append_memory,
record_learning, distill, verify, and more. Agents are told how to use them
by the generated AGENTS.md.
What gets stored
AGENTS.md generic manifest: how to use the package + where things live
.rational-agnostic/
config.json locale, canonical "en", embeddings provider, verify rules
decisions/ D-*.md one decision per file (Context / Decision / Why / Consequences)
tasks/ T-*.md one task per file
board.json status index
memory/ shared.md cross-agent shared memory
agents/*.md per-agent scratch
knowledge/ learnings.md accumulated learnings
conventions.md emergent conventions
index/ registry.json code anchor -> decision map (+ SHA for drift)
embeddings/ rebuildable semantic index (gitignored)
Semantic retrieval & tokens
Search and get_context use embeddings. Out of the box they run on a
deterministic lexical embedder with zero extra dependencies — nothing to
download, no network, no native binaries. For higher-quality semantic search you
can opt into a local, offline transformer model (Xenova/all-MiniLM-L6-v2,
no API key) by installing it yourself:
npm install @huggingface/transformers # optional; enables the local model
It is not a dependency on purpose: it pulls sharp/onnxruntime (~135 MB,
and the source of the libvips/libheif/librsvg advisories if you add it). When
absent, the lexical fallback keeps search working everywhere; when present, the
code detects and uses it automatically. The vector index is a rebuildable cache —
the markdown files are always the source of truth:
rational-agnostic search "how are auth tokens issued"
rational-agnostic context --task T-0001 --budget 1500
rational-agnostic reindex
Library
import { init, decisions, getContext, verify } from "rational-agnostic";
Documentation
A detailed, self-contained explainer (what was built, why, and how it works) is
in docs/how-it-works.html
— clone the repo and open it in a browser. Available in English (primary),
Spanish, Chinese and Japanese via the in-page language switcher.
Security & footprint
The default install is deliberately lean and npm audit reports 0
vulnerabilities — no native binaries, no install scripts, no network access at
install time:
- Heavy ML stack is opt-in.
@huggingface/transformers(and itssharp/onnxruntimesubtree, ~135 MB, which carried the libvips/libheif/librsvg advisories) is not declared as a dependency at all. The embedder loads it via a guarded, indirect dynamicimportonly if you install it yourself, so the default footprint stays ~27 MB and clean. - Small, trusted runtime deps.
commander(CLI, zero-dep),gray-matter(YAML frontmatter),proper-lockfile(safe cross-process writes),zod≥ 4.6.7 (schema validation, past the GHSA-mrhx-c7xc-m3w5 DoS) and the official@modelcontextprotocol/sdk. - Deliberately not reinvented. YAML frontmatter, cross-process locking and CLI parsing stay on their small, trusted libraries: a hand-rolled replacement would trade a negligible supply-chain reduction for real correctness risk (your decision records are hand-editable and must round-trip exactly).
Run npm audit any time to check the current state. Report a vulnerability via
the repo's issues.
License
MIT © Paco Aguilera
rational-agnostic MCP questions
How do I add rational-agnostic MCP to Claude Code?
Run claude mcp add rational -- npx -y rational-agnostic in your terminal. Add --scope user to make it available in every project.
How do I add rational-agnostic MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Can I use this with an existing codebase?
Yes, you can use the 'adopt' command to perform a read-only inventory of your existing languages, manifests, and entry points to create an onboarding plan.
Does it require an API key for semantic search?
No, it uses a deterministic lexical embedder with zero extra dependencies and no network access by default. You can optionally install a local transformer model for higher quality without an API key.