Mnema ⚡

Your project's coding standards — in every AI tool, without re-explaining them.

Mnema reads your repo, captures your stack, architecture, and conventions into one portable Project Brain, and renders it into each AI tool's native format — CLAUDE.md, .cursorrules, and more. Switch from Cursor to Claude Code, or onboard a teammate, with zero re-explaining.

npx mnemakit init

Installs as the mnemakit package. Examples below use the global mnema command — run npm i -g mnemakit once, or prefix each command with npx mnemakit.

The problem

Every new AI coding session — and every different AI tool — behaves like a new engineer who's never seen your codebase.

It doesn't know you default to Server Components. It doesn't know your team uses Prisma and never raw SQL. It doesn't know tests go through Vitest, not Jest. It suggests patterns you've already standardized away from.

So you re-explain your conventions. Every session. And again the moment you switch tools — because the context is trapped in whichever assistant you told last.

The fix: capture once, render everywhere

Mnema keeps one agent-neutral Project Brain in your repo (.mnema/) and renders it into each tool's native format on demand.

1. Capture — mnema init and mnema scan read your repo and git history to build a profile of your stack, architecture, and conventions.
2. Render — mnema render projects that one Brain into CLAUDE.md, .cursorrules, and more.
3. Switch freely — move between Cursor, Claude Code, Windsurf… each reads the same standards natively. A new teammate is caught up the moment they clone.

The Brain is the source of truth; the agent files are generated views of it. Edit the Brain, re-run render, and every tool updates. No LLM, no API key, no network — the core loop is fully local.

Quick start

cd your-project

mnema init      # detect your stack, create the Project Brain
mnema scan      # surface conventions & decisions from git history
mnema render    # write CLAUDE.md + .cursorrules from the Brain

That's the whole loop: one Brain in .mnema/, rendered out to whatever tools you use.

What it does

mnema render — your standards, in every tool

The core of Mnema: turn one Project Brain into agent-native files.

mnema render            # render every declared target (CLAUDE.md, .cursorrules)
mnema render claude     # just CLAUDE.md
mnema render cursor     # just .cursorrules
mnema render --stdout   # preview without writing anything

• Non-destructive. Mnema writes inside <!-- MNEMA:START -->…<!-- MNEMA:END --> markers. Re-running updates only that block — anything you've hand-written above or below it survives. An existing file with no markers is appended to, never clobbered (use --force to fully overwrite).
• Reads your edits. Render works from the on-disk Brain, so hand-edits to brain.md and rules.md flow straight into every generated file.

Targets today: Claude Code (CLAUDE.md) and Cursor (.cursorrules). Windsurf, Codex, and Gemini CLI are declared in skills.md; their generators are landing incrementally.

mnema init

Scans your repository (package.json, requirements.txt, Cargo.toml, Dockerfile, and more), detects your stack, and generates the Brain:

.mnema/
├── project.json     — machine-readable stack profile
├── brain.md         — human-readable project summary
├── rules.md         — AI behavior rules for your stack
├── skills.md        — portable cross-agent context file
└── decisions/       — architectural decision records (ADRs)

Example detection for a Next.js project:

Detected stack:
  Language        TypeScript
  Framework       Next.js
  Database        PostgreSQL
  ORM             Prisma
  Testing         Vitest
  Deployment      Vercel

Auto-generated rules.md — the part that makes an AI tool actually follow your conventions:

- Default all components to Server Components
- Use Prisma for all database operations — do not introduce another ORM
- Use Vitest for all tests — do not introduce Jest
- No `useEffect` + `fetch` for data loading — use Server Components instead
- TypeScript strict mode — no `any` types

No LLM is involved in any of this — it's derived directly from your stack, so it's always accurate.

mnema scan — conventions, and rationale where it exists

mnema scan reads your git history to surface the decisions and conventions already baked into your codebase — your most-changed areas, your top contributors, and the commits that look like real architectural decisions. Fully local, no key.

Optionally, mnema scan --enrich (your own LLM key) infers the reasoning behind those decisions. This part is deliberately honest about its limits:

• It reads commit messages and, with a GitHub token, the linked PR/issue text — and records a "why" only when it can ground it in that text.
• Where your team wrote the rationale down, you get it. Where they didn't, Mnema leaves the decision unenriched rather than inventing a reason.
• Confidence is capped by the strength of the source: a guess inferred from a one-line commit subject is marked low-confidence and kept out of your agent files by default.

So the decisions section is trustworthy: what's there is real, and it's quiet when the source material is. (Much of the "why" behind code lives in issue trackers and people's heads, not git — see the roadmap.)

mnema scan                                   # free, fully local
GROQ_API_KEY=gsk_... mnema scan --enrich     # add reasoning (free Groq tier by default)
GH_TOKEN=ghp_... GROQ_API_KEY=gsk_... mnema scan --enrich   # also read linked PR text

mnema learn

Record an architectural decision by hand, in ADR format:

Decision: Use PostgreSQL
Reason: Complex relational queries needed for reporting
Alternatives considered: MongoDB, PlanetScale
Why alternatives were rejected: MongoDB lacks JOIN support; PlanetScale has no free tier

Saves to .mnema/decisions/001-use-postgresql.md. Now when an agent suggests MongoDB, your Brain already explains why it was rejected — and so does every file render writes.

mnema explain

A full project summary, for onboarding humans and agents alike — stack, rules, and any recorded decisions, in one view.

Commit it

.mnema/ belongs in your repo, not in .gitignore. It's your team's shared Project Brain — every developer, every agent, every new session starts with the same standards.

git add .mnema/
git commit -m "feat: add project brain"

Commit the rendered files (CLAUDE.md, .cursorrules) too, so everyone's tools pick up the same conventions. Re-run mnema render whenever the Brain changes.

Cloud sync (beta)

Everything above works fully offline. To sync a Brain across machines or share it with teammates, there's an optional cloud layer (beta): mnema connect, mnema sync, mnema pull. The local commands are the stable core.

Detected stacks

Languages: TypeScript, JavaScript, Python, Rust Frameworks: Next.js, Remix, SvelteKit, Astro, Nuxt, Express, Fastify, Hono, FastAPI, Django, Flask, Actix-web, Axum Databases: PostgreSQL, MySQL, SQLite, MongoDB, Supabase ORMs: Prisma, Drizzle, SQLAlchemy, Diesel, SQLx, Mongoose Testing: Vitest, Jest, Pytest, Playwright, Mocha Styling: Tailwind CSS, Styled Components, Emotion Auth: NextAuth, Clerk, Lucia, Passport Deployment: Vercel, Netlify, Fly.io, Railway, Render, Heroku Package managers: pnpm, bun, yarn, npm CI/CD: GitHub Actions, GitLab CI

Missing your stack? Open a PR — the scanner is easy to extend.

Roadmap

• More render targets — Windsurf, Codex, Gemini CLI (and Cursor's newer .cursor/rules/*.mdc format)
• Pull decision rationale from issue trackers (Linear, Jira, GitHub Issues) — where the real "why" often lives
• mnema diff — show what changed in the Brain since last render
• Web dashboard for browsing team Brains
• GitHub Action to keep the Brain rendered and in sync automatically

Contributing

The scanner lives in src/utils/scanner.js. Adding a new framework is ~5 lines:

if (deps['your-framework']) profile.framework = 'your-framework';

Adding a new render target is one entry in src/utils/agent-renderers.js. Open a PR — we review fast.

License

MIT